sliding-window-limiter 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# sliding-window-limiter
+
+A JavaScript implementation of the Sliding Window rate limiting algorithm.
+
+## Features
+
+- Sliding window rate limiting with configurable window size, unit, and slice width
+- Pluggable persistence store (in-memory by default)
+- Written in modern JavaScript, using [lodash](https://lodash.com/) and [luxon](https://moment.github.io/luxon/)
+- Thoroughly tested with Jest
+
+## Installation
+
+```sh
+npm install sliding-window-limiter
+```
+
+## Usage
+
+```js
+const { RateLimiter } = require('sliding-window-limiter');
+
+const limiter = new RateLimiter({
+  name: 'api-rate-limit',
+  max: 100,                 // max requests per window
+  window: {
+    unit: 'minute',         // time unit for window
+    size: 10,               // number of slices in window
+    width: 1,               // width of each slice
+  },
+  store: customStore,       // optional: provide your own store
+});
+
+// To check and update the rate limit:
+const allowed = await limiter.update(1, new Date());
+if (!allowed) {
+  // Rate limit exceeded
+}
+```
+
+## API
+
+### `RateLimiter`
+
+#### Constructor
+
+```js
+new RateLimiter(config)
+```
+
+- `config.name` (string): Unique name for the limiter
+- `config.max` (number): Maximum allowed value in the window
+- `config.window` (object): Window configuration
+  - `unit` (string): Time unit (`second`, `minute`, `hour`, etc.)
+  - `size` (number): Number of slices in the window
+  - `width` (number): Width of each slice
+- `config.store` (object): Store for persistence (must implement `get` and `set`)
+
+#### Methods
+
+- `static async RateLimiter.load(config)`: Loads a limiter and its state from the store
+- `async update(value, timestamp)`: Attempts to add `value` at `timestamp`. Returns `true` if allowed, `false` if limit exceeded.
+- `set(state)`: Sets the internal window state
+- `valueOf()`: Returns the current sum of the window
+
+### `Window`
+
+- Internal class for managing the sliding window logic
+
+## Testing
+
+Run all tests with:
+
+```sh
+npm test
+```
+
+## License
+
+ISC
+
+## Author
+
+Dima Michaelov
+```

package/index.js

@@ -0,0 +1,5 @@
+const {RateLimiter} = require("./lib/rate_limiter");
+
+module.exports = {
+  RateLimiter,
+};

package/lib/null_store.js

@@ -0,0 +1,9 @@
+class Store {
+  get(key) { return null; }
+  set(key, value) { }
+};
+
+module.exports = {
+  Store,
+  NullStore: new Store(),
+};

package/lib/rate_limiter.js

@@ -0,0 +1,78 @@
+const {isNumber} = require('lodash/fp');
+const {Window} = require('./window');
+const {NullStore} = require('./null_store');
+
+// window with twenty three-second buckets
+const DefaultConfig = () => ({
+  name: 'request-rate-per-minute-max10',
+  max: 10,
+  window: {
+    unit: 'second',         // unit of time ('second', 'minute', 'hour', 'day', 'week', 'month', 'year')
+    size: 20,               // number of time slices
+    width: 3,               // width of slice 
+  },
+  store: NullStore,         // store to handle persistence
+});
+
+class RateLimiter {
+  constructor(config = DefaultConfig()) {
+    ({name: this.name, max: this.max, store: this.store, window: this.windowConfig} = config);
+    if (!this.name)
+      throw new TypeError('name must be specified and be unique');
+    if (!isNumber(this.max) || this.max <= 0)
+      throw new TypeError('max must be a positive number');
+    if (!this.store)
+      throw new TypeError('store must be specified');
+    if (!this.windowConfig)
+      throw new TypeError('window configuration must be specified');
+  }
+
+  static async load(config) {
+    if (!config.name)
+      throw new TypeError('name must be specified and be unique');
+    if (!config.store)
+      throw new TypeError('store must be specified');
+
+    try {
+      const state = await config.store.get(config.name);
+      return new RateLimiter(config).set(state);
+    }
+    catch (err) {
+      throw new Error(`Failed to load rate-limit window ${config.name}`, {cause: err});
+    }
+  }
+
+  // should update the buckets according to configuration
+  // returns true if update successful
+  async update(value, timestamp) {
+    if (!isNumber(value) || value <= 0)
+      throw new TypeError('value must be a positive number');
+    
+    try {
+      this.window = this.window || Window.fromConfig(this.windowConfig);
+      if (this.max < this.valueOf() + value)
+        return false;
+      
+      this.window.update(value, timestamp);
+      await this.store.set(this.name, this.window.toObject());
+      return true;
+    }
+    catch (err) {
+      throw new Error(`Failed to update rate-limit window ${this.name}`, {cause: err});
+    }
+  }
+
+  set(state) {
+    if (this.window) return;
+    this.window = state ? new Window(state) : Window.fromConfig(this.windowConfig);
+    return this;
+  }
+
+  valueOf() {
+    return this.window?.valueOf();
+  }
+};
+
+module.exports = {
+  RateLimiter,
+};

package/lib/window.js

@@ -0,0 +1,101 @@
+const {isNumber, isString, min, rangeStep, slice, sum} = require('lodash/fp');
+const {DateTime} = require('luxon');
+
+// window with twenty three-second timeSlices
+const DefaultWindow = () => ({
+  timeSlices: [],
+  updated: DateTime.now(),
+  unit: 'second',
+  width: 3,
+});
+
+const zeroes = rangeStep(0, 0);
+const mod = (a, b) => ((a % b) + b) % b;
+const validUnit = unit => ['second', 'minute', 'hour', 'day', 'week', 'month', 'year'].includes(unit);
+
+class Window {
+  constructor(data = DefaultWindow()) {
+    ({timeSlices: this.timeSlices, updated: this.updated, unit: this.unit, width: this.width} = data);
+    if (!this.unit || !validUnit(this.unit))
+      throw new TypeError("unit must be one of 'second', 'minute', 'hour', 'day', 'week', 'month', 'year'")
+    if (isString(this.updated))
+      this.updated = DateTime.fromISO(this.updated);
+    if (!this.updated.isValid) throw new TypeError('updated must be luxon DateTime');
+  }
+
+  static fromConfig(config) {
+    if (!isNumber(config.size) || config.size <= 0)
+      throw new TypeError('config.size must be a positive number');
+    return new Window({
+      timeSlices: zeroes(config.size),
+      updated: DateTime.now(),
+      unit: config.unit,
+      width: config.width,
+    });
+  }
+
+  update(value, timestamp = DateTime.now()) {
+    if (!isNumber(value))
+      throw new TypeError('value must be a number');
+    if (value < 0)
+      throw new TypeError('value must be a positive number');
+    
+    let _timestamp = timestamp;
+    if (timestamp instanceof Date)
+      _timestamp = DateTime.fromJSDate(timestamp);
+    if (isString(timestamp))
+      _timestamp = DateTime.fromISO(timestamp);
+    if (!_timestamp.isValid)
+      throw new TypeError('timestamp must be valid DateTime, Date or ISO string');
+
+    this.recalculate(_timestamp);
+    this.timeSlices[0] += value;
+    this.updated = _timestamp;
+  }
+
+  slicesBetween(now, start) {
+    let count = now.diff(start, this.unit).get(this.unit);
+    if (this.width) {
+      count = count < this.width ? 0 : Math.floor(count / this.width);
+    }
+    return count;
+  }
+
+  start() {
+    let time = this.updated;
+    if (this.width) {
+      const val = time.get(this.unit);
+      time = time.set({[this.unit]: val - (mod(val, this.width))});
+    }
+    return time.startOf(this.unit);
+  }
+
+  recalculate(timestamp) {
+    const slicesCount = this.slicesBetween(timestamp, this.start());
+    if (slicesCount > 0) {
+      const invalidSlices = min([slicesCount, this.timeSlices.length]);
+      this.timeSlices = [
+        ...zeroes(invalidSlices),
+        ...slice(0, -invalidSlices)(this.timeSlices),
+      ];
+    }
+  }
+
+  valueOf() {
+    return sum(this.timeSlices);
+  }
+
+  toObject() {
+    return {
+      timeSlices: this.timeSlices,
+      updated: this.updated.toISO(),
+      unit: this.unit,
+      width: this.width,
+    };
+  }
+}
+
+module.exports = {
+  DefaultWindow,
+  Window,
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "sliding-window-limiter",
+  "version": "1.0.0",
+  "description": "Implementation of the Sliding Window rate limiting algorithm",
+  "keywords": [
+    "sliding-window",
+    "rolling-buckets",
+    "rate-limiting"
+  ],
+  "homepage": "https://github.com/Dimch/sliding-window-limiter#readme",
+  "bugs": {
+    "url": "https://github.com/Dimch/sliding-window-limiter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dimch/sliding-window-limiter.git"
+  },
+  "license": "ISC",
+  "author": "Dima Michaelov",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0",
+    "luxon": "^3.7.2"
+  }
+}

package/test/rate_limiter.spec.js

@@ -0,0 +1,151 @@
+const {DateTime} = require('luxon');
+const {cloneDeep} = require('lodash/fp');
+const {RateLimiter} = require('../lib/rate_limiter');
+const {Window} = require('../lib/window');
+const {NullStore} = require('../lib/null_store');
+
+const MockStoreFactory = () => {
+  let internalValue = {
+    timeSlices: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    updated: '2025-01-01T00:00:00',
+    unit: 'second',
+    width: 3,
+  }
+  return ({
+    get: jest.fn(name => name !== 'ip-req-per-minute-max10-u00001' ? null : cloneDeep(internalValue)),
+    set: jest.fn((name, value) => (internalValue = cloneDeep(value))),
+  });
+};
+
+const MockStore = MockStoreFactory();
+
+const ErrorStore = ({
+  get: jest.fn().mockRejectedValue(new Error('network error')),
+  set: jest.fn().mockRejectedValue(new Error('network error')),
+});
+
+const DefaultOptions = () => ({
+  name: 'ip-req-per-minute-max10-u00001',
+  max: 10,
+  window: {
+    unit: 'second',
+    size: 20,
+    width: 3,
+  },
+  store: MockStore,
+});
+
+describe('RateLimiter', () => {
+
+  describe('#constructor', () => {
+    test('should correctly initialize RateLimiter', () => {
+      const lim = new RateLimiter(DefaultOptions());
+      expect(lim.windowConfig).toStrictEqual({unit: 'second', size: 20, width: 3});
+      expect(lim.max).toBe(10);
+      expect(lim.name).toBe('ip-req-per-minute-max10-u00001');
+      expect(lim.store).toBe(MockStore);
+      expect(lim.window).toBeFalsy();
+    });
+
+    test('should throw error if one of properties is invalid', () => {
+      let fn = () => new RateLimiter({});
+      expect(fn).toThrow('name must be specified and be unique');
+      fn = () => new RateLimiter({name: 'ip-hour-0001', max: 0});
+      expect(fn).toThrow('max must be a positive number');
+      fn = () => new RateLimiter({name: 'ip-hour-0001', max: 20});
+      expect(fn).toThrow('store must be specified');
+      fn = () => new RateLimiter({name: 'ip-hour-0001', max: 20, store: NullStore});
+      expect(fn).toThrow('window configuration must be specified');
+    });
+  });
+
+  describe('#load', () => {
+    test('should correctly initialize RateLimiter and load Window state', async () => {
+      const lim = await RateLimiter.load(DefaultOptions());
+      expect(lim.name).toBe('ip-req-per-minute-max10-u00001');
+      expect(lim.max).toBe(10);
+      expect(lim.store).toBe(MockStore);
+      expect(MockStore.get).toHaveBeenCalledTimes(1);
+      expect(MockStore.get.mock.calls[0][0]).toBe(DefaultOptions().name);
+      expect(lim.window).toStrictEqual(new Window({
+        timeSlices: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+        updated: '2025-01-01T00:00:00.000+02:00',
+        unit: 'second',
+        width: 3,
+      }));
+    });
+
+    test('should throw error if one of properties is invalid', async () => {
+      let fn = () => RateLimiter.load({});
+      await expect(fn()).rejects.toThrow('name must be specified and be unique');
+      fn = () => RateLimiter.load({name: 'ip-hour-0001'});
+      await expect(fn()).rejects.toThrow('store must be specified');
+    });
+
+    test('should throw an error if failed to load state', async () => {
+      const fn = () => RateLimiter.load({...DefaultOptions(), store: ErrorStore});
+      await expect(fn()).rejects.toThrow('Failed to load rate-limit window ip-req-per-minute-max10-u00001');
+    });
+  });
+
+  describe('#set', () => {
+    test('should not reset existing window state', async () => {
+      const lim = await RateLimiter.load(DefaultOptions());
+      expect(lim.valueOf()).toBe(0);
+      lim.set({
+        timeSlices: [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+        updated: '2025-01-01T00:00:00',
+        unit: 'second',
+        width: 3,
+      });
+      expect(lim.valueOf()).toBe(0);
+    });
+    
+    test('should set provided set', () => {
+      const lim = new RateLimiter(DefaultOptions());
+      expect(lim.valueOf()).toBe(undefined);
+      lim.set({
+        timeSlices: [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+        updated: '2025-01-01T00:00:00',
+        unit: 'second',
+        width: 3,
+      });
+      expect(lim.valueOf()).toBe(1);
+    });
+    
+    test('should set default set if state is empty', async () => {
+      const lim = await RateLimiter.load({...DefaultOptions(), store: NullStore});
+      expect(lim.valueOf()).toBe(0);
+      expect(lim.window.timeSlices).toStrictEqual([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
+      expect(lim.window.unit).toBe(lim.windowConfig.unit);
+      expect(lim.window.width).toBe(lim.windowConfig.width);
+    });
+  });
+
+  describe('#update', () => {
+    test('should should throw error if one of arguments is invalid', async () => {
+      const lim = new RateLimiter(DefaultOptions());
+      const fn = () => lim.update(0);
+      await expect(fn()).rejects.toThrow('value must be a positive number');
+    });
+    
+    test('should return false if getting over max threshold', async () => {
+      const lim = new RateLimiter(DefaultOptions());
+      const fn = () => lim.update(40, '2025-01-01T00:00:30Z');
+      await expect(fn()).resolves.toBe(false);
+    });
+    
+    test('should return true if window state is updated', async () => {
+      const lim = new RateLimiter(DefaultOptions());
+      const fn = () => lim.update(10, '2025-01-01T00:00:30Z');
+      await expect(fn()).resolves.toBe(true);
+      expect(lim.valueOf()).toBe(10);
+    });
+    
+    test('should throw an error if failed to update store', async () => {
+      const lim = new RateLimiter({...DefaultOptions(), store: ErrorStore});
+      const fn = () => lim.update(1, '2025-01-01T00:00:00Z');
+      await expect(fn()).rejects.toThrow('Failed to update rate-limit window ip-req-per-minute-max10-u00001');
+    });
+  });
+});

package/test/window.spec.js

@@ -0,0 +1,79 @@
+const {DateTime} = require('luxon');
+const {isString} = require('lodash/fp');
+const {Window} = require('../lib/window');
+
+describe('Window', () => {
+
+  describe('#constructor', () => {
+    test('should initialize Window', () => {
+      const win = new Window({timeSlices: [0, 0, 0, 0, 0], unit: 'minute', width: 2, updated: '2025-01-01T00:00:00Z'});
+      expect(win.timeSlices).toHaveLength(5);
+      expect(win.timeSlices).toStrictEqual([0, 0, 0, 0, 0]);
+      expect(win.unit).toBe('minute');
+      expect(win.width).toBe(2);
+      expect(win.updated.toUTC().toISO()).toBe('2025-01-01T00:00:00.000Z');
+    });
+
+    test('should throw error if updated is invalid', () => {
+      const fn = () => new Window({timeSlices: [0, 0, 0, 0, 0], unit: 'minute', width: 2, updated: 'abc'});
+      expect(fn).toThrow(TypeError);
+    });
+  });
+
+  describe('#fromConfig', () => {
+    test('should initialize Window', () => {
+      const win = Window.fromConfig({unit: 'minute', width: 2, size: 5});
+      expect(win.timeSlices).toHaveLength(5);
+      expect(win.timeSlices).toStrictEqual([0, 0, 0, 0, 0]);
+      expect(win.unit).toBe('minute');
+      expect(win.width).toBe(2);
+      expect(DateTime.isDateTime(win.updated)).toBe(true);
+    });
+  });
+
+  describe('#slicesBetween', () => {
+    const win = Window.fromConfig({unit: 'minute', width: 2, size: 5});
+    test('should return number of slices between timestamps', () => {
+      const date0 = '2014-01-01T00:00:00Z';
+      const date1 = '2014-01-01T00:01:00Z';
+      const date2 = '2014-01-01T00:05:00Z';
+      expect(win.slicesBetween(DateTime.fromISO(date0), DateTime.fromISO(date0))).toBe(0);
+      expect(win.slicesBetween(DateTime.fromISO(date1), DateTime.fromISO(date0))).toBe(0);
+      expect(win.slicesBetween(DateTime.fromISO(date2), DateTime.fromISO(date0))).toBe(2);
+    });
+  });
+
+  describe('#valueOf', () => {
+    const win = new Window({timeSlices: [0, 0, 0, 0, 0], unit: 'minute', width: 2, updated: '2025-01-01T00:00:00Z'});
+    test('should return sum of values', () => {
+      expect(win.valueOf()).toBe(0);
+      win.update(1, '2025-01-01T00:01:00Z');
+      expect(win.valueOf()).toBe(1);
+    });
+  });
+
+  describe('#toObject', () => {
+    const win = new Window({timeSlices: [0, 0, 0, 0, 0], unit: 'minute', width: 2, updated: '2025-01-01T00:00:00Z'});
+    test('should return sum of values', () => {
+      const obj = win.toObject();
+      expect(obj.timeSlices).toEqual([0, 0, 0, 0, 0]);
+      expect(obj.unit).toEqual('minute');
+      expect(obj.width).toEqual(2);
+      expect(isString(obj.updated)).toBe(true);
+      win.update(1, '2025-01-01T00:01:00Z');
+      expect(win.toObject().timeSlices).toEqual([1, 0, 0, 0, 0]);
+    });
+  });
+
+  describe('#update()', () => {
+    test('should throw error if invalid parameter', () => {
+      const win = new Window({timeSlices: [0, 0, 0, 0, 0], unit: 'minute', width: 2, updated: '2025-01-01T00:00:00Z'});
+      let fn = () => win.update('a');
+      expect(fn).toThrow('value must be a number');
+      fn = () => win.update(-1);
+      expect(fn).toThrow('value must be a positive number');
+      fn = () => win.update(1, '2025-01-02 00:00:00');
+      expect(fn).toThrow('timestamp must be valid DateTime, Date or ISO string');
+    });
+  });
+});