rate-limiter-flexible 11.0.1 → 11.1.0

package/README.md

@@ -136,7 +136,7 @@ Copy/paste examples on Wiki:
 * [DynamoDb](https://github.com/animir/node-rate-limiter-flexible/wiki/DynamoDB)
 * [Etcd](https://github.com/animir/node-rate-limiter-flexible/wiki/Etcd) Atomic and non-atomic counters.
 * [Memcached](https://github.com/animir/node-rate-limiter-flexible/wiki/Memcache)
-* [Memory](https://github.com/animir/node-rate-limiter-flexible/wiki/Memory)
+* [Memory](https://github.com/animir/node-rate-limiter-flexible/wiki/Memory) Supports dump() and restore() for graceful restarts and green/blue deployment
 * [Mongo](https://github.com/animir/node-rate-limiter-flexible/wiki/Mongo) (with [sharding support](https://github.com/animir/node-rate-limiter-flexible/wiki/Mongo#mongodb-sharding-options))
 * [MySQL](https://github.com/animir/node-rate-limiter-flexible/wiki/MySQL) (support Sequelize and Knex)
 * [Postgres](https://github.com/animir/node-rate-limiter-flexible/wiki/PostgreSQL) (support Sequelize, TypeORM and Knex)

package/lib/RateLimiterDrizzle.js

@@ -9,23 +9,76 @@ class RateLimiterDrizzleError extends Error {
   }
 }
 
-async function getDrizzleOperators() {
+async function loadDrizzleOperators() {
   if (drizzleOperators) return drizzleOperators;
 
-  try {
-    // Use dynamic import to prevent static analysis tools from detecting the import
-    function getPackageName() {
-      return ['drizzle', 'orm'].join('-');
+  const requiredOperators = ['and', 'or', 'gt', 'lt', 'eq', 'isNull', 'sql'];
+
+  // Use dynamic import to prevent static analysis tools from detecting the import
+  function getPackageName() {
+    return ['drizzle', 'orm'].join('-');
+  }
+
+  const collectModuleLayers = (mod) => {
+    const layers = [];
+    const seen = new Set();
+    let current = mod;
+
+    while (current && (typeof current === 'object' || typeof current === 'function') && !seen.has(current)) {
+      layers.push(current);
+      seen.add(current);
+      current = current.default;
+    }
+
+    return layers;
+  };
+
+  const importModule = async (specifier, { optional = false } = {}) => {
+    try {
+      return await import(/* @vite-ignore */ specifier);
+    } catch (error) {
+      if (optional) {
+        return null;
+      }
+      throw new RateLimiterDrizzleError(
+        error.message || 'Failed to import drizzle-orm package.'
+      );
+    }
+  };
+
+  const mainModule = await importModule(`${getPackageName()}`);
+  const sqlModule = await importModule(`${getPackageName()}/sql`, { optional: true });
+
+  const mainCandidates = collectModuleLayers(mainModule);
+  const sqlCandidates = sqlModule ? collectModuleLayers(sqlModule) : [];
+  const resolvedOperators = {};
+  const missingOperators = [];
+
+  for (const operatorName of requiredOperators) {
+    const candidates = operatorName === 'sql'
+      ? [...sqlCandidates, ...mainCandidates]
+      : mainCandidates;
+
+    const operator = candidates
+      .map((candidate) => candidate?.[operatorName])
+      .find((value) => typeof value === 'function');
+
+    if (!operator) {
+      missingOperators.push(operatorName);
+      continue;
     }
-    const drizzleOrm = await import(`${getPackageName()}`);
-    const { and, or, gt, lt, eq, isNull, sql } = drizzleOrm.default || drizzleOrm;
-    drizzleOperators = { and, or, gt, lt, eq, isNull, sql };
-    return drizzleOperators;
-  } catch (error) {
+
+    resolvedOperators[operatorName] = operator;
+  }
+
+  if (missingOperators.length > 0) {
     throw new RateLimiterDrizzleError(
-      'drizzle-orm is not installed. Please install drizzle-orm to use RateLimiterDrizzle.'
+      `Failed to load drizzle-orm operators: missing ${missingOperators.join(', ')}`
     );
   }
+
+  drizzleOperators = resolvedOperators;
+  return drizzleOperators;
 }
 
 const RateLimiterStoreAbstract = require('./RateLimiterStoreAbstract');
@@ -71,7 +124,7 @@ class RateLimiterDrizzle extends RateLimiterStoreAbstract {
       return Promise.reject(new RateLimiterDrizzleError('Drizzle client is not established'))
     }
 
-    const { eq, sql } = await getDrizzleOperators();
+    const { eq, sql } = await loadDrizzleOperators();
     const now = new Date();
     const newExpire = msDuration > 0 ? new Date(now.getTime() + msDuration) : null;
 
@@ -117,7 +170,7 @@ class RateLimiterDrizzle extends RateLimiterStoreAbstract {
       return Promise.reject(new RateLimiterDrizzleError('Drizzle client is not established'))
     }
 
-    const { and, or, gt, eq, isNull } = await getDrizzleOperators();
+    const { and, or, gt, eq, isNull } = await loadDrizzleOperators();
 
     const [response] = await this.drizzleClient
       .select()
@@ -139,7 +192,7 @@ class RateLimiterDrizzle extends RateLimiterStoreAbstract {
       return Promise.reject(new RateLimiterDrizzleError('Drizzle client is not established'))
     }
 
-    const { eq } = await getDrizzleOperators();
+    const { eq } = await loadDrizzleOperators();
 
     const [result] = await this.drizzleClient
       .delete(this.schema)
@@ -156,7 +209,7 @@ class RateLimiterDrizzle extends RateLimiterStoreAbstract {
 
     this._clearExpiredTimeoutId = setTimeout(async () => {
       try {
-        const { lt } = await getDrizzleOperators();
+        const { lt } = await loadDrizzleOperators();
         await this.drizzleClient
           .delete(this.schema)
           .where(lt(this.schema.expire, new Date(Date.now() - EXPIRED_THRESHOLD_MS)));

package/lib/RateLimiterMemory.js

@@ -102,6 +102,96 @@ class RateLimiterMemory extends RateLimiterAbstract {
   delete(key) {
     return Promise.resolve(this._memoryStorage.delete(this.getKey(key)));
   }
+
+  dump() {
+    const storage = [];
+    for (const [key, record] of this._memoryStorage._storage) {
+      storage.push({
+        key: this.parseKey(key),
+        value: record.value,
+        expiresAt: record.expiresAt,
+      });
+    }
+
+    return {
+      version: 1,
+      dumpedAt: Date.now(),
+      storage,
+    };
+  }
+
+  /**
+   * Restores rate-limiter state from a previously dumped snapshot.
+   *
+   * Each entry is classified into one of three buckets:
+   *  - **invalid**  – the item is not an object or has a malformed schema (bad key, value or expiry type).
+   *  - **expired**  – the item has logically expired based on current timestamp.
+   *  - **restored** – the item was valid and successfully loaded into storage.
+   *
+   * @param {Object}  data            - Snapshot produced by {@link dump}.
+   * @param {boolean} [detailResponse=false] - When `true`, each bucket also
+   *   carries a `keys` array listing every affected key.
+   * @returns {{ invalid, expired, restored } | undefined} Summary counts (and
+   *   optionally keys).  Returns `undefined` when `data` fails schema checks.
+   */
+  restore(data, detailResponse = false) {
+    if (!data || typeof data !== 'object' || data.version !== 1) {
+      return undefined;
+    }
+
+    const response = detailResponse
+      ? {
+        invalid: { count: 0, keys: [] },
+        expired: { count: 0, keys: [] },
+        restored: { count: 0, keys: [] },
+      }
+      : { invalid: 0, expired: 0, restored: 0 };
+
+    /**
+     * Increments the named bucket and, in detail mode, appends the key.
+     * @param {'invalid'|'expired'|'restored'} bucket
+     * @param {string|number} key
+     */
+    const record = (bucket, key) => {
+      if (detailResponse) {
+        response[bucket].count += 1;
+        response[bucket].keys.push(key);
+      } else {
+        response[bucket] += 1;
+      }
+    };
+
+    if (!Array.isArray(data.storage)) {
+      return response;
+    }
+
+    for (const item of data.storage) {
+      if (!item || typeof item !== 'object') {
+        //in array if we don't get object we push N/A
+        record('invalid', 'N/A');
+        continue;
+      }
+
+      const isValidKey = typeof item.key === 'string' || typeof item.key === 'number';
+      const isValidValue = Number.isFinite(item.value);
+      const isValidExpiry = item.expiresAt === null || Number.isFinite(item.expiresAt);
+
+      if (!isValidKey || !isValidValue || !isValidExpiry) {
+        record('invalid', item.key);
+        continue;
+      }
+
+      if (item.expiresAt !== null && item.expiresAt <= Date.now()) {
+        record('expired', item.key);
+        continue;
+      }
+
+      this._memoryStorage._restoreRecord(this.getKey(item.key), item.value, item.expiresAt);
+      record('restored', item.key);
+    }
+
+    return response;
+  }
 }
 
 module.exports = RateLimiterMemory;

package/lib/component/MemoryStorage/MemoryStorage.js

@@ -86,4 +86,45 @@ module.exports = class MemoryStorage {
     }
     return false;
   }
+
+  /**
+   * @internal
+   * @param key
+   * @param value
+   * @param expiresAt
+   */
+  _restoreRecord(key, value, expiresAt) {
+    const now = Date.now();
+    const hasExpiresAt = expiresAt !== null;
+
+    if (hasExpiresAt && !Number.isFinite(expiresAt)) {
+      return;
+    }
+
+    if (hasExpiresAt && expiresAt <= now) {
+      return;
+    }
+
+    const durationMs = hasExpiresAt ? expiresAt - now : 0;
+
+    const existingRecord = this._storage.get(key);
+    if (existingRecord && existingRecord.timeoutId) {
+      clearTimeout(existingRecord.timeoutId);
+    }
+
+    const record = new Record(
+      value,
+      expiresAt
+    );
+    this._storage.set(key, record);
+
+    if (durationMs > 0) {
+      record.timeoutId = setTimeout(() => {
+        this._storage.delete(key);
+      }, durationMs);
+      if (record.timeoutId.unref) {
+        record.timeoutId.unref();
+      }
+    }
+  }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rate-limiter-flexible",
-  "version": "11.0.1",
+  "version": "11.1.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": {
@@ -11,7 +11,8 @@
     "test:valkey-cluster": "VALKEY_CLUSTER_PORT=7001 mocha test/RateLimiterValkeyGlide.test.js --  -g 'RateLimiterValkeyGlide with cluster client'",
     "prisma:postgres": "prisma generate --schema=./test/RateLimiterPrisma/Postgres/schema.prisma && prisma db push --schema=./test/RateLimiterPrisma/Postgres/schema.prisma",
     "drizzle:postgres": "cd ./test/RateLimiterDrizzle/Postgres && drizzle-kit push",
-    "test": "npm run prisma:postgres && npm run drizzle:postgres && nyc --reporter=html --reporter=text mocha \"test/**/*.test.js\"",
+    "test:drizzle:postgres:v1": "npm i --no-save --no-package-lock drizzle-orm@^1.0.0-beta.23 && mocha test/RateLimiterDrizzle/Postgres/RateLimiterDrizzlePostgres.test.js && ( [ \"$GITHUB_ACTIONS\" = \"true\" ] || npm i )",
+    "test": "npm run prisma:postgres && npm run drizzle:postgres && nyc --reporter=html --reporter=text mocha \"test/**/*.test.js\" && npm run test:drizzle:postgres:v1",
     "debug-test": "mocha --inspect-brk lib/**/**.test.js",
     "coveralls": "cat ./coverage/lcov.info | coveralls",
     "eslint": "eslint --quiet lib/**/**.js test/**/**.js",

package/types.d.ts

@@ -318,7 +318,7 @@ interface IRateLimiterRedisOptions extends IRateLimiterStoreOptions {
 }
 
 interface IRateLimiterValkeyOptions extends IRateLimiterStoreOptions {
-  customIncrTtlLuaScript?: string;
+    customIncrTtlLuaScript?: string;
 }
 
 interface ICallbackReady {
@@ -334,8 +334,43 @@ interface IRLWrapperBlackAndWhiteOptions {
     runActionAnyway?: boolean;
 }
 
+export interface IRateLimiterMemoryRecord {
+    key: string | number;
+    value: number;
+    expiresAt: number | null;
+}
+
+export interface IRateLimiterMemoryExport {
+    version: number;
+    dumpedAt: number;
+    storage: IRateLimiterMemoryRecord[];
+}
+
+/** Common structure for restore results. */
+export interface IRateLimiterRestoreResult<T> {
+    invalid: T;
+    expired: T;
+    restored: T;
+}
+
+/** Returned by {@link RateLimiterMemory.restore} when `detailResponse` is `false` (default). */
+export type IRateLimiterRestoreResponse = IRateLimiterRestoreResult<number>;
+
+export interface IRateLimiterRestoreBucketDetail {
+    count: number;
+    keys: Array<string | number>;
+}
+
+/** Returned by {@link RateLimiterMemory.restore} when `detailResponse` is `true`. */
+export type IRateLimiterRestoreDetailResponse = IRateLimiterRestoreResult<IRateLimiterRestoreBucketDetail>;
+
 export class RateLimiterMemory extends RateLimiterAbstract {
     constructor(opts: IRateLimiterOptions);
+
+    dump(): IRateLimiterMemoryExport;
+    restore(data: Omit<IRateLimiterMemoryExport, 'dumpedAt'>, detailResponse: true): IRateLimiterRestoreDetailResponse | undefined;
+    restore(data: Omit<IRateLimiterMemoryExport, 'dumpedAt'>, detailResponse?: false): IRateLimiterRestoreResponse | undefined;
+    restore(data: Omit<IRateLimiterMemoryExport, 'dumpedAt'>, detailResponse?: boolean): IRateLimiterRestoreResponse | IRateLimiterRestoreDetailResponse | undefined;
 }
 
 export class RateLimiterCluster extends RateLimiterAbstract {
@@ -359,7 +394,7 @@ export class RateLimiterRedisNonAtomic extends RateLimiterStoreAbstract {
 }
 
 export class RateLimiterValkey extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterValkeyOptions);
+    constructor(opts: IRateLimiterValkeyOptions);
 }
 
 export interface IRateLimiterMongoFunctionOptions {
@@ -424,19 +459,19 @@ export class RateLimiterPostgres extends RateLimiterStoreAbstract {
 }
 
 export class RateLimiterSQLite extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
 }
 
 export class RateLimiterPrisma extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptions, cb?: ICallbackReady);
 }
 
 export class RateLimiterDrizzle extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
 }
 
 export class RateLimiterDrizzleNonAtomic extends RateLimiterStoreAbstract {
-  constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
+    constructor(opts: IRateLimiterStoreNoAutoExpiryOptionsAndSchema, cb?: ICallbackReady);
 }
 
 export class RateLimiterMemcache extends RateLimiterStoreAbstract { }