nextlimiter 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Production-ready rate limiting for Node.js — sliding window, token bucket, SaaS plans, smart limiting, and built-in analytics.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -67,4 +67,4 @@
     "url": "https://github.com/abhishekck31/nextlimiter/issues"
   },
   "homepage": "https://github.com/abhishekck31/nextlimiter#readme"
-}
+}

package/src/index.js

@@ -3,6 +3,7 @@
 const { Limiter }     = require('./core/limiter');
 const { PRESETS, DEFAULT_PLANS } = require('./core/config');
 const { MemoryStore } = require('./store/memoryStore');
+const { RedisStore }  = require('./store/redisStore');
 
 /**
  * Create a fully configured rate limiter instance.
@@ -99,6 +100,7 @@ module.exports = {
 
   // Storage
   MemoryStore,
+  RedisStore,
 
   // Constants
   PRESETS,

package/src/store/redisStore.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * RedisStore — Redis-backed storage backend for NextLimiter.
+ *
+ * Requires ioredis to be installed separately:
+ *   npm install ioredis
+ *
+ * Uses a Lua script for atomic increment so it is safe across multiple servers
+ * behind a load balancer — no race conditions, no split-brain issues.
+ *
+ * Implements the NextLimiter Store interface:
+ *   get(key)                  → Promise<value | undefined>
+ *   set(key, value, ttlMs)    → Promise<void>
+ *   increment(key, ttlMs)     → Promise<number>  (atomic via Lua)
+ *   delete(key)               → Promise<void>
+ *   keys()                    → []               (SCAN not required by the interface)
+ */
+
+/**
+ * Lua script for atomic rate-limit increment.
+ *
+ * KEYS[1]  — the rate limit key
+ * ARGV[1]  — the max limit (not used for blocking in this script; handled in JS)
+ * ARGV[2]  — TTL in milliseconds (applied only on first request in window)
+ *
+ * Logic:
+ *   1. GET current value (default 0 if nil)
+ *   2. INCR the key
+ *   3. If new value == 1 (first request), set PEXPIRE to establish the window TTL
+ *   4. Return the new count
+ *
+ * Atomicity guarantee: all steps execute as a single Redis transaction — no
+ * other command can interleave between the GET, INCR, and PEXPIRE.
+ */
+const INCR_SCRIPT = `
+local current = tonumber(redis.call('GET', KEYS[1])) or 0
+local new = redis.call('INCR', KEYS[1])
+if new == 1 then
+  redis.call('PEXPIRE', KEYS[1], tonumber(ARGV[1]))
+end
+return new
+`;
+
+class RedisStore {
+  /**
+   * @param {import('ioredis').Redis} client — a connected ioredis client instance
+   */
+  constructor(client) {
+    if (!client || typeof client.eval !== 'function') {
+      throw new Error(
+        '[NextLimiter] RedisStore requires an ioredis client instance. ' +
+        'Install it with: npm install ioredis'
+      );
+    }
+    this._client = client;
+  }
+
+  // ── Store interface ─────────────────────────────────────────────────────────
+
+  /**
+   * Get a stored value by key.
+   * @param {string} key
+   * @returns {Promise<any>}
+   */
+  async get(key) {
+    const raw = await this._client.get(key);
+    if (raw === null || raw === undefined) return undefined;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+
+  /**
+   * Set a value with a TTL.
+   * @param {string} key
+   * @param {any} value
+   * @param {number} ttlMs - Time to live in milliseconds
+   */
+  async set(key, value, ttlMs) {
+    await this._client.set(key, JSON.stringify(value), 'PX', ttlMs);
+  }
+
+  /**
+   * Atomically increment the request counter for a key using a Lua script.
+   * Sets the window TTL on first request. Returns the new count.
+   *
+   * @param {string} key
+   * @param {number} ttlMs - Window TTL in milliseconds (set on first request only)
+   * @returns {Promise<number>} new count after increment
+   */
+  async increment(key, ttlMs) {
+    const result = await this._client.eval(
+      INCR_SCRIPT,
+      1,       // number of KEYS
+      key,     // KEYS[1]
+      ttlMs    // ARGV[1] — TTL in ms
+    );
+    return Number(result);
+  }
+
+  /**
+   * Delete a key.
+   * @param {string} key
+   */
+  async delete(key) {
+    await this._client.del(key);
+  }
+
+  /**
+   * Return tracked keys. Redis SCAN is optional per the Store interface,
+   * so we return an empty array here. Use Redis SCAN / HSCAN externally
+   * if you need to inspect active keys in production.
+   * @returns {string[]}
+   */
+  keys() {
+    return [];
+  }
+
+  /** No-op — Redis keys expire automatically via PEXPIRE. */
+  clear() {}
+}
+
+module.exports = { RedisStore };
+
+// ── Usage example ─────────────────────────────────────────────────────────────
+//
+// const Redis = require('ioredis');
+// const { createLimiter, RedisStore } = require('nextlimiter');
+//
+// const redis = new Redis();   // connects to 127.0.0.1:6379 by default
+//
+// const limiter = createLimiter({
+//   store:    new RedisStore(redis),
+//   max:      100,
+//   windowMs: 60_000,
+//   strategy: 'sliding-window',
+//   keyBy:    'ip',
+//   logging:  true,
+// });
+//
+// app.use('/api', limiter.middleware());
+//
+// // Programmatic check (WebSockets, background jobs, etc.)
+// const result = await limiter.check(`user:${userId}`);
+// if (!result.allowed) throw new Error(`Rate limited. Retry in ${result.retryAfter}s`);
+//
+// ─────────────────────────────────────────────────────────────────────────────

package/types/index.d.ts

@@ -240,6 +240,37 @@ export declare class MemoryStore implements Store {
   readonly size: number;
 }
 
+/**
+ * RedisStore — Redis-backed storage backend for NextLimiter.
+ *
+ * Requires ioredis to be installed separately:
+ *   npm install ioredis
+ *
+ * Uses an atomic Lua script for increment — race-condition safe across
+ * multiple Node.js processes behind a load balancer.
+ *
+ * @example
+ * import Redis from 'ioredis';
+ * import { createLimiter, RedisStore } from 'nextlimiter';
+ *
+ * const redis = new Redis();
+ * const limiter = createLimiter({ store: new RedisStore(redis), max: 100 });
+ * app.use('/api', limiter.middleware());
+ */
+export declare class RedisStore implements Store {
+  /**
+   * @param client - A connected ioredis client instance
+   */
+  constructor(client: any);
+  get(key: string): Promise<any>;
+  set(key: string, value: any, ttlMs: number): Promise<void>;
+  /** Atomically increments the counter using a Lua script. */
+  increment(key: string, ttlMs: number): Promise<number>;
+  delete(key: string): Promise<void>;
+  keys(): string[];
+  clear(): void;
+}
+
 // ── Constants ────────────────────────────────────────────────────────────────
 
 export declare const PRESETS: Record<BuiltInPreset, LimiterOptions>;