redis-traffic-limiter 1.0.0 → 1.1.0

package/README.md

@@ -1,11 +1,40 @@
-# Redis Rate Limiter
+# Redis Traffic Limiter
 
 A lightweight Redis-based rate limiter for Node.js using Redis.
 
 Currently supported algorithms:
 
-- ✅ Fixed Window
-- ✅ Sliding Window
+* ✅ Fixed Window
+* ✅ Sliding Window
+* ✅ Token Bucket
+
+---
+
+## What's New in v1.1.0
+
+### Added
+
+* ✅ Token Bucket rate limiting algorithm.
+
+### Improved
+
+* Introduced a shared `BaseLimiter` for cleaner architecture.
+* Added constructor validation with clear error messages for invalid configuration.
+* Standardized the response object across all algorithms.
+
+All limiters now return the same response format:
+
+```js
+{
+    allowed: true,
+    limit: 100,
+    remaining: 99,
+    retryAfter: null,
+    resetTime: null
+}
+```
+
+> **Note:** `retryAfter` and `resetTime` are currently `null` and will be fully implemented in future releases.
 
 ---
 
@@ -13,8 +42,8 @@ Currently supported algorithms:
 
 Before using this package, make sure you have:
 
-- Node.js
-- Redis Server
+* Node.js
+* Redis Server
 
 ---
 
@@ -51,7 +80,7 @@ docker run -d \
 Install the package along with the official Redis client.
 
 ```bash
- npm install redis-traffic-limiter redis
+npm install redis-traffic-limiter redis
 ```
 
 ---
@@ -76,8 +105,9 @@ Pass the connected Redis client while creating the limiter.
 
 Example programs are available in the `examples/` directory.
 
-- `examples/fixed.js`
-- `examples/sliding.js`
+* `examples/fixed.js`
+* `examples/sliding.js`
+* `examples/tokenBucket.js`
 
 Run them using:
 
@@ -91,25 +121,92 @@ or
 node examples/sliding.js
 ```
 
+or
+
+```bash
+node examples/tokenBucket.js
+```
+
 ---
 
 ## Supported Algorithms
 
-- Fixed Window
-- Sliding Window
+### Fixed Window
+
+```js
+import { FixedWindow } from "redis-traffic-limiter";
+
+const limiter = new FixedWindow({
+    redis,
+    window: 60000,
+    max: 100
+});
+```
+
+---
+
+### Sliding Window
+
+```js
+import { SlidingWindow } from "redis-traffic-limiter";
+
+const limiter = new SlidingWindow({
+    redis,
+    window: 60000,
+    max: 100
+});
+```
+
+---
+
+### Token Bucket
+
+```js
+import { TokenBucket } from "redis-traffic-limiter";
+
+const limiter = new TokenBucket({
+    redis,
+    capacity: 100,
+    refillRate: 10,
+    interval: 60
+});
+```
+
+Where:
+
+* `capacity` – Maximum number of tokens the bucket can hold.
+* `refillRate` – Number of tokens added every interval.
+* `interval` – Refill interval in seconds.
+
+---
+
+## Response Format
+
+Every limiter returns a standardized response object.
+
+```js
+{
+    allowed: true,
+    limit: 100,
+    remaining: 99,
+    retryAfter: null,
+    resetTime: null
+}
+```
 
 ---
 
 ## Notes
 
-- The package expects a **connected node-redis client**.
-- Redis connections are managed by your application.
-- `window` is specified in **milliseconds**.
-- Currently supports the official **node-redis** client only.
-- Support for additional Redis clients (e.g. ioredis) is planned for future releases.
+* The package expects a **connected node-redis client**.
+* Redis connections are managed by your application.
+* `window` is specified in **milliseconds**.
+* `interval` for the Token Bucket algorithm is specified in **seconds**.
+* Currently supports the official **node-redis** client only.
+* Support for additional Redis clients (e.g. ioredis), Express middleware, Lua scripts for atomic operations, and additional features are planned for future releases.
 
 ---
 
 ## License
 
-MIT
+MIT

package/example/TokenBucket.js

@@ -0,0 +1,22 @@
+import { createClient } from "redis";
+import { TokenBucket } from "../src";
+
+// Create a Redis client.
+const redis = createClient({
+    url: "redis://localhost:6379"
+});
+
+// Connect to Redis.
+await redis.connect();
+
+const limiter = new TokenBucket({
+    redis,
+    capacity: 10,
+    refillRate: 5,
+    interval: 60
+});
+
+for (let i = 1; i <= 12; i++) {
+    const result = await limiter.consume("user:1");
+    console.log(i, result);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redis-traffic-limiter",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A lightweight Redis-based rate limiter for Node.js supporting Fixed Window and Sliding Window algorithms.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,2 +1,3 @@
 export { default as FixedWindow } from "./limiter/FixedWindow.js";
-export { default as SlidingWindow } from "./limiter/SlidingWindow.js";
+export { default as SlidingWindow } from "./limiter/SlidingWindow.js";
+export { default as TokenBucket } from "./limiter/TokenBucket.js";

package/src/limiter/BaseLimiter.js

@@ -0,0 +1,44 @@
+class BaseLimiter {
+    constructor({ redis }) {
+        this.validateRedis(redis);
+        this.redis = redis;
+    }
+
+    validateRedis(redis) {
+        if (!redis) {
+            throw new Error("A connected Redis client is required.");
+        }
+
+        if (
+            typeof redis.get !== "function" ||
+            typeof redis.set !== "function"
+        ) {
+            throw new Error("Invalid Redis client provided.");
+        }
+    }
+
+    validatePositiveInteger(value, name) {
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new Error(`${name} must be a positive integer.`);
+        }
+    }
+
+
+    createResponse({
+        allowed,
+        limit,
+        remaining,
+        retryAfter = null,
+        resetTime = null
+    }) {
+        return {
+            allowed,
+            limit,
+            remaining,
+            retryAfter,
+            resetTime
+        };
+    }
+}
+
+export default BaseLimiter;

package/src/limiter/FixedWindow.js

@@ -1,7 +1,13 @@
-class FixedWindow {
+import BaseLimiter from "./BaseLimiter.js";
+
+class FixedWindow extends BaseLimiter {
 
     constructor({ redis, window, max }) {
-        this.redis = redis;
+        super({ redis });
+
+        this.validatePositiveInteger(window, "window");
+        this.validatePositiveInteger(max, "max");
+
         this.window = window;
         this.max = max;
     }
@@ -15,16 +21,18 @@ class FixedWindow {
         }
 
         if (count <= this.max) {
-            return {
+            return this.createResponse({
                 allowed: true,
+                limit: this.max,
                 remaining: this.max - count
-            };
+            });
         }
 
-        return {
+        return this.createResponse({
             allowed: false,
+            limit: this.max,
             remaining: 0
-        };
+        });
     }
 
 }

package/src/limiter/SlidingWindow.js

@@ -1,8 +1,14 @@
-class SlidingWindow {
+import BaseLimiter from "./BaseLimiter.js";
+
+class SlidingWindow extends BaseLimiter {
 
     constructor({ redis, window, max }) {
-        this.redis = redis;
-        this.window = window; 
+        super({ redis });
+
+        this.validatePositiveInteger(window, "window");
+        this.validatePositiveInteger(max, "max");
+
+        this.window = window;
         this.max = max;
     }
 
@@ -10,42 +16,37 @@ class SlidingWindow {
 
         const now = Date.now();
 
-        
         await this.redis.zRemRangeByScore(
             key,
             0,
             now - this.window
         );
 
-        
         const count = await this.redis.zCard(key);
 
-        
         if (count >= this.max) {
-
-            return {
+            return this.createResponse({
                 allowed: false,
+                limit: this.max,
                 remaining: 0
-            };
-
+            });
         }
 
-       
         await this.redis.zAdd(key, {
             score: now,
             value: `${now}-${Math.random()}`
         });
 
-        
         await this.redis.expire(
             key,
             Math.ceil(this.window / 1000)
         );
 
-        return {
+        return this.createResponse({
             allowed: true,
+            limit: this.max,
             remaining: this.max - count - 1
-        };
+        });
 
     }
 

package/src/limiter/TokenBucket.js

@@ -0,0 +1,80 @@
+import BaseLimiter from "./BaseLimiter.js";
+
+class TokenBucket extends BaseLimiter {
+
+    constructor({ redis, capacity, refillRate, interval }) {
+        super({ redis });
+
+        this.validatePositiveInteger(capacity, "capacity");
+        this.validatePositiveInteger(refillRate, "refillRate");
+        this.validatePositiveInteger(interval, "interval");
+
+        this.capacity = capacity;
+        this.refillRate = refillRate;
+        this.interval = interval;
+    }
+
+    async consume(key) {
+
+        const tokenKey = `${key}:tokens`;
+        const timeKey = `${key}:lastRefill`;
+
+        const now = Date.now();
+
+        const storedTokens = await this.redis.get(tokenKey);
+        const storedLastRefill = await this.redis.get(timeKey);
+
+        let tokens;
+        let lastRefill;
+
+        // First request
+        if (storedTokens === null || storedLastRefill === null) {
+            tokens = this.capacity;
+            lastRefill = now;
+        } else {
+            tokens = Number(storedTokens);
+            lastRefill = Number(storedLastRefill);
+        }
+
+        // Calculate elapsed time
+        const elapsed = (now - lastRefill) / 1000;
+
+        // Number of complete intervals passed
+        const intervalsPassed = Math.floor(elapsed / this.interval);
+
+        // Refill tokens
+        if (intervalsPassed > 0) {
+            tokens = Math.min(
+                this.capacity,
+                tokens + intervalsPassed * this.refillRate
+            );
+
+            lastRefill += intervalsPassed * this.interval * 1000;
+        }
+
+        if (tokens <= 0) {
+
+            await this.redis.set(tokenKey, tokens);
+            await this.redis.set(timeKey, lastRefill);
+
+            return this.createResponse({
+                allowed: false,
+                limit: this.capacity,
+                remaining: 0
+            });
+        }
+
+        tokens--;
+
+        await this.redis.set(tokenKey, tokens);
+        await this.redis.set(timeKey, lastRefill);
+
+        return this.createResponse({
+            allowed: true,
+            limit: this.capacity,
+            remaining: tokens
+        });
+    }
+}
+
+export default TokenBucket;