rate-limiter-flexible 10.0.0 → 11.0.0

package/CONTEXT.md

@@ -30,7 +30,7 @@ const { RateLimiterMemory } = require("rate-limiter-flexible");
 ## Core Concepts
 
 - **Atomic increments** — all operations use atomic increments to prevent race conditions.
-- **Fixed window** algorithm — much faster than rolling window. See [comparative benchmarks](https://github.com/animir/node-rate-limiter-flexible/wiki/Comparative-benchmarks).
+- **Enhanced fixed window** algorithm — starts counting from the moment a request is received, diversifying rate limit reset times across clients. Much faster than rolling window. See [comparative benchmarks](https://github.com/animir/node-rate-limiter-flexible/wiki/Comparative-benchmarks).
 - **Zero production dependencies.**
 - **Deno compatible** — see [example gist](https://gist.github.com/animir/d06ca92931677f330d3f2d4c6c3108e4).
 - **Browser compatible** — `RateLimiterMemory` works in the browser.
@@ -45,8 +45,8 @@ Options can be changed at runtime: `rateLimiter.points = 50`, `rateLimiter.durat
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `points` | `4` | Max points consumable over `duration`. |
-| `duration` | `1` | Seconds before points reset (from first consume). `0` = never expire. |
+| `points` | **Required** | Max points consumable over `duration`. Must be a number. |
+| `duration` | **Required** | Seconds before points reset (from first consume). Must be >= 0. `0` = never expire. |
 | `keyPrefix` | `'rlflx'` | Unique prefix per limiter to avoid key collisions. For some stores, used as table/collection name. |
 | `blockDuration` | `0` | If >0, block key for this many seconds once points exhausted. |
 | `storeClient` | — | Required for store limiters. Accepts `@valkey/valkey-glide`, `iovalkey`, `redis`, `ioredis`, `memcached`, `mongodb`, `pg`, `mysql2`, `mysql`, Sequelize, TypeORM, Knex, or any related pool/connection. |
@@ -156,9 +156,9 @@ const headers = {
 | Limiter | Description |
 |---------|-------------|
 | `BurstyRateLimiter` | Combines two limiters: primary + burst allowance. |
-| `RateLimiterUnion` | Consume from multiple limiters simultaneously. Only `consume` method. |
+| `RateLimiterUnion` | Consume from multiple limiters simultaneously. Only `consume` method. Accepts any `RateLimiterAbstract` or `RateLimiterCompatibleAbstract` instance. |
 | `RateLimiterQueue` | Queue actions and execute at controlled rate (FIFO). |
-| `RLWrapperBlackAndWhite` | Wrap any limiter with black/white IP lists. |
+| `RLWrapperBlackAndWhite` | Wrap any limiter with black/white IP lists. Can be used as `insuranceLimiter`, in `RLWrapperTimeouts`, or `RateLimiterUnion`. |
 | `RLWrapperTimeouts` | Wrap any limiter with custom timeout behavior. |
 
 ## Common Patterns
@@ -469,3 +469,11 @@ Any new limiter with storage must extend `RateLimiterStoreAbstract` and implemen
 - `_upsert` — atomic or non-atomic increment. Must support `forceExpire` mode. If non-atomic, suffix class with `NonAtomic` (e.g. `RateLimiterRedisNonAtomic`).
 - `_get` — return raw data by key or `null`.
 - `_delete` — delete key data, return `true`/`false`.
+
+## Creating Custom Wrappers
+
+For wrapper classes that don't need full `RateLimiterAbstract` functionality (like `points`, `duration`, etc.), extend `RateLimiterCompatibleAbstract` instead. This lightweight abstract class requires implementing:
+- `consume`, `penalty`, `reward`, `get`, `set`, `block`, `delete` methods
+- `blockDuration` and `execEvenly` getters/setters (if not used, empty no-op implementations can be provided)
+
+Classes extending `RateLimiterCompatibleAbstract` can be used anywhere `RateLimiterAbstract` is accepted: as `insuranceLimiter`, in `RLWrapperTimeouts`, `RateLimiterUnion`, etc. See `RLWrapperBlackAndWhite` for an example implementation.

package/README.md

@@ -32,8 +32,7 @@ Memory limiter also works in the browser.
 
 **Deno compatible** See [this example](https://gist.github.com/animir/d06ca92931677f330d3f2d4c6c3108e4) 
 
-It uses a **fixed window**, as it is much faster than a rolling window. 
-[See comparative benchmarks with other libraries here](https://github.com/animir/node-rate-limiter-flexible/wiki/Comparative-benchmarks)
+The enhanced fixed window algorithm starts counting from the moment a request is received, diversifying rate limit reset times across clients.
 
 ## Installation
 
@@ -227,4 +226,6 @@ It has to implement 4 methods:
 
 All other methods depend on the store. See `RateLimiterRedis` or `RateLimiterPostgres` for examples.
 
+For wrapper classes that don't need full `RateLimiterAbstract` functionality, extend `RateLimiterCompatibleAbstract` instead. It requires implementing `consume`, `penalty`, `reward`, `get`, `set`, `block`, `delete` methods and `blockDuration`/`execEvenly` getters/setters. If the wrapper doesn't use `blockDuration` or `execEvenly`, empty no-op implementations can be provided. See `RLWrapperBlackAndWhite` for an example.
+
 Note: all changes should be covered by tests.

package/index.js

@@ -12,6 +12,7 @@ const RateLimiterUnion = require('./lib/RateLimiterUnion');
 const RateLimiterQueue = require('./lib/RateLimiterQueue');
 const BurstyRateLimiter = require('./lib/BurstyRateLimiter');
 const RateLimiterRes = require('./lib/RateLimiterRes');
+const RateLimiterCompatibleAbstract = require('./lib/RateLimiterCompatibleAbstract');
 const RateLimiterDynamo = require('./lib/RateLimiterDynamo');
 const RateLimiterPrisma = require('./lib/RateLimiterPrisma');
 const RateLimiterDrizzle = require('./lib/RateLimiterDrizzle');
@@ -41,6 +42,7 @@ module.exports = {
   RateLimiterQueue,
   BurstyRateLimiter,
   RateLimiterRes,
+  RateLimiterCompatibleAbstract,
   RateLimiterDynamo,
   RateLimiterPrisma,
   RateLimiterValkey,

package/lib/RLWrapperBlackAndWhite.js

@@ -1,7 +1,9 @@
 const RateLimiterRes = require('./RateLimiterRes');
+const RateLimiterCompatibleAbstract = require('./RateLimiterCompatibleAbstract');
 
-module.exports = class RLWrapperBlackAndWhite {
+module.exports = class RLWrapperBlackAndWhite extends RateLimiterCompatibleAbstract {
   constructor(opts = {}) {
+    super();
     this.limiter = opts.limiter;
     this.blackList = opts.blackList;
     this.whiteList = opts.whiteList;
@@ -22,6 +24,26 @@ module.exports = class RLWrapperBlackAndWhite {
     this._limiter = value;
   }
 
+  get keyPrefix() {
+    return this.limiter.keyPrefix;
+  }
+
+  get blockDuration() {
+    return this.limiter.blockDuration;
+  }
+
+  set blockDuration(value) {
+    this.limiter.blockDuration = value;
+  }
+
+  get execEvenly() {
+    return this.limiter.execEvenly;
+  }
+
+  set execEvenly(value) {
+    this.limiter.execEvenly = value;
+  }
+
   get runActionAnyway() {
     return this._runActionAnyway;
   }
@@ -102,94 +124,52 @@ module.exports = class RLWrapperBlackAndWhite {
     return Promise.resolve(this.getWhiteRes());
   }
 
-  consume(key, pointsToConsume = 1) {
+  _execAction(action, key, args, rejectOnBlack = false) {
     let res;
     if (this.isWhiteListedSomewhere(key)) {
       res = this.resolveWhite();
     } else if (this.isBlackListedSomewhere(key)) {
-      res = this.rejectBlack();
+      res = rejectOnBlack ? this.rejectBlack() : this.resolveBlack();
     }
 
     if (typeof res === 'undefined') {
-      return this.limiter.consume(key, pointsToConsume);
+      return this.limiter[action](key, ...args);
     }
 
     if (this.runActionAnyway) {
-      this.limiter.consume(key, pointsToConsume).catch(() => {});
+      this.limiter[action](key, ...args).catch(() => {});
     }
     return res;
   }
 
-  block(key, secDuration) {
-    let res;
-    if (this.isWhiteListedSomewhere(key)) {
-      res = this.resolveWhite();
-    } else if (this.isBlackListedSomewhere(key)) {
-      res = this.resolveBlack();
-    }
-
-    if (typeof res === 'undefined') {
-      return this.limiter.block(key, secDuration);
-    }
-
-    if (this.runActionAnyway) {
-      this.limiter.block(key, secDuration).catch(() => {});
-    }
-    return res;
+  consume(key, pointsToConsume = 1, options = {}) {
+    return this._execAction('consume', key, [pointsToConsume, options], true);
   }
 
-  penalty(key, points) {
-    let res;
-    if (this.isWhiteListedSomewhere(key)) {
-      res = this.resolveWhite();
-    } else if (this.isBlackListedSomewhere(key)) {
-      res = this.resolveBlack();
-    }
-
-    if (typeof res === 'undefined') {
-      return this.limiter.penalty(key, points);
-    }
-
-    if (this.runActionAnyway) {
-      this.limiter.penalty(key, points).catch(() => {});
-    }
-    return res;
+  block(key, secDuration, options = {}) {
+    return this._execAction('block', key, [secDuration, options]);
   }
 
-  reward(key, points) {
-    let res;
-    if (this.isWhiteListedSomewhere(key)) {
-      res = this.resolveWhite();
-    } else if (this.isBlackListedSomewhere(key)) {
-      res = this.resolveBlack();
-    }
+  penalty(key, points = 1, options = {}) {
+    return this._execAction('penalty', key, [points, options]);
+  }
 
-    if (typeof res === 'undefined') {
-      return this.limiter.reward(key, points);
-    }
+  reward(key, points = 1, options = {}) {
+    return this._execAction('reward', key, [points, options]);
+  }
 
+  get(key, options = {}) {
     if (this.runActionAnyway) {
-      this.limiter.reward(key, points).catch(() => {});
+      return this.limiter.get(key, options);
     }
-    return res;
+    return this._execAction('get', key, [options]);
   }
 
-  get(key) {
-    let res;
-    if (this.isWhiteListedSomewhere(key)) {
-      res = this.resolveWhite();
-    } else if (this.isBlackListedSomewhere(key)) {
-      res = this.resolveBlack();
-    }
-
-    if (typeof res === 'undefined' || this.runActionAnyway) {
-      return this.limiter.get(key);
-    }
-
-    return res;
+  set(key, points, secDuration, options = {}) {
+    return this._execAction('set', key, [points, secDuration, options]);
   }
 
-  delete(key) {
-    return this.limiter.delete(key);
+  delete(key, options = {}) {
+    return this.limiter.delete(key, options);
   }
 };

package/lib/RLWrapperTimeouts.js

@@ -1,9 +1,13 @@
-const RateLimiterAbstract = require('./RateLimiterAbstract');
 const RateLimiterInsuredAbstract = require('./RateLimiterInsuredAbstract');
+const isRateLimiterCompatible = require('./helper/isRateLimiterCompatible');
 
 module.exports = class RLWrapperTimeouts extends RateLimiterInsuredAbstract {
   constructor(opts= {}) {
-    super(opts);
+    super({
+      ...opts,
+      points: 0,
+      duration: 0,
+    });
     this.limiter = opts.limiter;
     this.timeoutMs = opts.timeoutMs || 0;
   }
@@ -13,8 +17,8 @@ module.exports = class RLWrapperTimeouts extends RateLimiterInsuredAbstract {
   }
 
   set limiter(limiter) {
-    if (!(limiter instanceof RateLimiterAbstract)) {
-      throw new TypeError('limiter must be an instance of RateLimiterAbstract');
+    if (!isRateLimiterCompatible(limiter)) {
+      throw new TypeError('limiter must be an instance of RateLimiterAbstract or RateLimiterCompatibleAbstract');
     }
     this._limiter = limiter;
     if (!this.insuranceLimiter && limiter instanceof RateLimiterInsuredAbstract) {

package/lib/RateLimiterAbstract.js

@@ -100,7 +100,7 @@ module.exports = class RateLimiterAbstract {
   }
 
   parseKey(rlKey) {
-    return rlKey.substring(this.keyPrefix.length);
+    return this.keyPrefix.length > 0 ? rlKey.substring(this.keyPrefix.length + 1) : rlKey;
   }
 
   consume() {

package/lib/RateLimiterCompatibleAbstract.js

@@ -0,0 +1,49 @@
+module.exports = class RateLimiterCompatibleAbstract {
+  get keyPrefix() {
+    throw new Error("You have to implement the getter 'keyPrefix'!");
+  }
+
+  get blockDuration() {
+    throw new Error("You have to implement the getter 'blockDuration'!");
+  }
+
+  set blockDuration(value) {
+    throw new Error("You have to implement the setter 'blockDuration'!");
+  }
+
+  get execEvenly() {
+    throw new Error("You have to implement the getter 'execEvenly'!");
+  }
+
+  set execEvenly(value) {
+    throw new Error("You have to implement the setter 'execEvenly'!");
+  }
+
+  consume() {
+    throw new Error("You have to implement the method 'consume'!");
+  }
+
+  penalty() {
+    throw new Error("You have to implement the method 'penalty'!");
+  }
+
+  reward() {
+    throw new Error("You have to implement the method 'reward'!");
+  }
+
+  get() {
+    throw new Error("You have to implement the method 'get'!");
+  }
+
+  set() {
+    throw new Error("You have to implement the method 'set'!");
+  }
+
+  block() {
+    throw new Error("You have to implement the method 'block'!");
+  }
+
+  delete() {
+    throw new Error("You have to implement the method 'delete'!");
+  }
+};

package/lib/RateLimiterInsuredAbstract.js

@@ -1,5 +1,6 @@
 const RateLimiterAbstract = require('./RateLimiterAbstract');
 const RateLimiterRes = require('./RateLimiterRes');
+const isRateLimiterCompatible = require('./helper/isRateLimiterCompatible');
 
 module.exports = class RateLimiterInsuredAbstract extends RateLimiterAbstract {
   constructor(opts = {}) {
@@ -12,8 +13,8 @@ module.exports = class RateLimiterInsuredAbstract extends RateLimiterAbstract {
   }
 
   set insuranceLimiter(value) {
-    if (typeof value !== 'undefined' && !(value instanceof RateLimiterAbstract)) {
-      throw new Error('insuranceLimiter must be instance of RateLimiterAbstract');
+    if (typeof value !== 'undefined' && !isRateLimiterCompatible(value)) {
+      throw new Error('insuranceLimiter must be instance of RateLimiterAbstract or RateLimiterCompatibleAbstract');
     }
     this._insuranceLimiter = value;
     if (this._insuranceLimiter) {
@@ -25,7 +26,7 @@ module.exports = class RateLimiterInsuredAbstract extends RateLimiterAbstract {
   _handleError(err, funcName, resolve, reject, params) {
     if (err instanceof RateLimiterRes) {
       reject(err);
-    } else if (!(this.insuranceLimiter instanceof RateLimiterAbstract)) {
+    } else if (!isRateLimiterCompatible(this.insuranceLimiter)) {
       reject(err);
     } else {
       this.insuranceLimiter[funcName](...params)

package/lib/RateLimiterStoreAbstract.js

@@ -1,4 +1,3 @@
-const RateLimiterAbstract = require('./RateLimiterAbstract');
 const BlockedKeys = require('./component/BlockedKeys');
 const RateLimiterRes = require('./RateLimiterRes');
 const RateLimiterInsuredAbstract = require('./RateLimiterInsuredAbstract');
@@ -152,7 +151,7 @@ module.exports = class RateLimiterStoreAbstract extends RateLimiterInsuredAbstra
    */
   set(key, points, secDuration, options = {}) {
     const msDuration = (secDuration >= 0 ? secDuration : this.duration) * 1000;
-    return this._block(this.getKey(key), points, msDuration, options);
+    return this._set(this.getKey(key), points, msDuration, options);
   }
 
   /**
@@ -300,6 +299,26 @@ module.exports = class RateLimiterStoreAbstract extends RateLimiterInsuredAbstra
     });
   }
 
+  /**
+   * @param rlKey
+   * @param points
+   * @param msDuration
+   * @param {Object} options
+   *
+   * @return Promise<any>
+   */
+  _set(rlKey, points, msDuration, options = {}) {
+    return new Promise((resolve, reject) => {
+      this._upsert(rlKey, points, msDuration, true, options)
+        .then(() => {
+          resolve(new RateLimiterRes(0, msDuration > 0 ? msDuration : -1, points));
+        })
+        .catch((err) => {
+          this._handleError(err, 'set', resolve, reject, [this.parseKey(rlKey), points, msDuration / 1000, options]);
+        });
+    });
+  }
+
   /**
    * Have to be implemented in every limiter
    * Resolve with raw result from Store OR null if rlKey is not set

package/lib/RateLimiterUnion.js

@@ -1,4 +1,4 @@
-const RateLimiterAbstract = require('./RateLimiterAbstract');
+const isRateLimiterCompatible = require('./helper/isRateLimiterCompatible');
 
 module.exports = class RateLimiterUnion {
   constructor(...limiters) {
@@ -6,8 +6,8 @@ module.exports = class RateLimiterUnion {
       throw new Error('RateLimiterUnion: at least one limiter have to be passed');
     }
     limiters.forEach((limiter) => {
-      if (!(limiter instanceof RateLimiterAbstract)) {
-        throw new Error('RateLimiterUnion: all limiters have to be instance of RateLimiterAbstract');
+      if (!isRateLimiterCompatible(limiter)) {
+        throw new Error('RateLimiterUnion: all limiters have to be instance of RateLimiterAbstract or RateLimiterCompatibleAbstract');
       }
     });
 

package/lib/helper/isRateLimiterCompatible.js

@@ -0,0 +1,6 @@
+const RateLimiterAbstract = require('../RateLimiterAbstract');
+const RateLimiterCompatibleAbstract = require('../RateLimiterCompatibleAbstract');
+
+module.exports = function isRateLimiterCompatible(obj) {
+  return obj instanceof RateLimiterAbstract || obj instanceof RateLimiterCompatibleAbstract;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rate-limiter-flexible",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "description": "Node.js atomic and non-atomic counters, rate limiting tools, protection from DoS and brute-force attacks at scale",
   "main": "index.js",
   "scripts": {

package/types.d.ts

@@ -27,6 +27,55 @@ export class RateLimiterRes {
     };
 }
 
+export class RateLimiterCompatibleAbstract {
+    readonly keyPrefix: string;
+    blockDuration: number;
+    execEvenly: boolean;
+
+    consume(
+        key: string | number,
+        pointsToConsume?: number,
+        options?: { [key: string]: any }
+    ): Promise<RateLimiterRes>;
+
+    penalty(
+        key: string | number,
+        points?: number,
+        options?: { [key: string]: any }
+    ): Promise<RateLimiterRes>;
+
+    reward(
+        key: string | number,
+        points?: number,
+        options?: { [key: string]: any }
+    ): Promise<RateLimiterRes>;
+
+    get(
+        key: string | number,
+        options?: { [key: string]: any }
+    ): Promise<RateLimiterRes | null>;
+
+    set(
+        key: string | number,
+        points: number,
+        secDuration: number,
+        options?: { [key: string]: any }
+    ): Promise<RateLimiterRes>;
+
+    block(
+        key: string | number,
+        secDuration: number,
+        options?: { [key: string]: any }
+    ): Promise<RateLimiterRes>;
+
+    delete(
+        key: string | number,
+        options?: { [key: string]: any }
+    ): Promise<boolean>;
+}
+
+export type RateLimiterLike = RateLimiterAbstract | RateLimiterCompatibleAbstract;
+
 export class RateLimiterAbstract {
     constructor(opts: IRateLimiterOptions);
 
@@ -224,7 +273,7 @@ interface IRateLimiterOptions {
     execEvenly?: boolean;
     execEvenlyMinDelayMs?: number;
     blockDuration?: number;
-    insuranceLimiter?: RateLimiterAbstract;
+    insuranceLimiter?: RateLimiterLike;
 }
 
 interface IRateLimiterClusterOptions extends IRateLimiterOptions {
@@ -236,7 +285,7 @@ interface IRateLimiterStoreOptions extends IRateLimiterOptions {
     storeType?: string;
     inMemoryBlockOnConsumed?: number;
     inMemoryBlockDuration?: number;
-    insuranceLimiter?: RateLimiterAbstract;
+    insuranceLimiter?: RateLimiterLike;
     dbName?: string;
     tableName?: string;
     tableCreated?: boolean;
@@ -277,7 +326,7 @@ interface ICallbackReady {
 }
 
 interface IRLWrapperBlackAndWhiteOptions {
-    limiter: RateLimiterAbstract;
+    limiter: RateLimiterLike;
     blackList?: string[] | number[];
     whiteList?: string[] | number[];
     isBlackListed?(key: any): boolean;
@@ -393,17 +442,24 @@ export class RateLimiterDrizzleNonAtomic extends RateLimiterStoreAbstract {
 export class RateLimiterMemcache extends RateLimiterStoreAbstract { }
 
 export class RateLimiterUnion {
-    constructor(...limiters: RateLimiterAbstract[]);
+    constructor(...limiters: RateLimiterLike[]);
 
     consume(key: string | number, points?: number): Promise<Record<string, RateLimiterRes>>;
 }
 
-export class RLWrapperBlackAndWhite extends RateLimiterAbstract {
+export class RLWrapperBlackAndWhite extends RateLimiterCompatibleAbstract {
     constructor(opts: IRLWrapperBlackAndWhiteOptions);
+
+    limiter: RateLimiterLike;
+    blackList: string[] | number[];
+    whiteList: string[] | number[];
+    isBlackListed: (key: any) => boolean;
+    isWhiteListed: (key: any) => boolean;
+    runActionAnyway: boolean;
 }
 
-interface IRLWrapperTimeoutsOptions extends IRateLimiterOptions {
-    limiter: RateLimiterAbstract;
+interface IRLWrapperTimeoutsOptions extends Omit<IRateLimiterOptions, 'points' | 'duration'> {
+    limiter: RateLimiterLike;
     timeoutMs?: number;
 }
 
@@ -417,7 +473,7 @@ interface IRateLimiterQueueOpts {
 
 export class RateLimiterQueue {
     constructor(
-        limiterFlexible: RateLimiterAbstract | BurstyRateLimiter,
+        limiterFlexible: RateLimiterLike | BurstyRateLimiter,
         opts?: IRateLimiterQueueOpts
     );
 
@@ -428,8 +484,8 @@ export class RateLimiterQueue {
 
 export class BurstyRateLimiter {
     constructor(
-        rateLimiter: RateLimiterAbstract,
-        burstLimiter: RateLimiterAbstract
+        rateLimiter: RateLimiterLike,
+        burstLimiter: RateLimiterLike
     );
 
     consume(