A rolling time window

Downloads in past


1.0.02 years ago4 years agoMinified + gzip package size for @shuhei/rolling-window in KB


Actions Status Codecov npm version
Implements "Reset reservoir periodically by chunks" strategy to use hdr-histogram-js for monitoring. Inspired by vladimir-bukhtoyarov/rolling-metrics. No additional dependencies.
See rolling-metrics' documentation for the background.


With hdr-histogram-js@2:
npm install -S hdr-histogram-js @shuhei/rolling-window

With hdr-histogram-js@1:
npm install -S hdr-histogram-js@1 @shuhei/rolling-window@^0.2.1


const { RollingWindowHistogram } = require("@shuhei/rolling-window");

// This configuration creates 7 internal histograms (6 + 1) and rotates them
// one by one in each 10 seconds. `getSnapshot()` returns a histogram of the
// last 60 to 70 seconds. These additional 0 to 10 seconds make sure that the
// rolling window can provide a fresh histogram without losing any records at
// any given time.
const rollingWindowHistogram = new RollingWindowHistogram({
  timeWindow: 1000 * 60,
  numChunks: 6,

// Record a value

// Get a snapshot
const snapshot = rollingWindowHistogram.getSnapshot();
const p99 = snapshot.getValueAtPercentile(99);


new RollingWindowHistogram(options)

  • options
- timeWindow: number The length of a time window in milliseconds. Default: 60000 - numChunks: number The number of chunks in the time window. Default: 6 - buildHistogram: () => Histogram A factory function to create a histogram. This will be called multiple times to prepare necessary histograms in the rolling window. Use this to provide custom options to histograms. Default: build from hdr-histogram-js
Creates a rolling window histogram with numChunks + 1 histograms in it and starts rotating chunks with an interval of timeWindow / numChunks.


Stop the rotation timer. When you stop using a rolling window histogram, make sure to call this method to avoid memory leak.


  • value: number A numerical value to record. It must not be negative.


  • snapshot: Histogram A histogram to accumulate histograms. It is reset before accumulating histograms. If this is not provided, a Histogram is created and kept for reuse.
  • Returns: Histogram