redis-lua-rate-limiter 1.0.0 → 1.0.1

package/README.md

@@ -1,24 +1,100 @@
-# redis-lua-rate-limiter
 
-Distributed, atomic, token-bucket rate limiter for Node.js powered by Redis Lua scripts.
+### Redis-lua-rate-limiter
 
-## Why?
+**Distributed, atomic, token-bucket rate limiter for Node.js powered by Redis Lua scripts.**
 
-Most Express rate limiters break in distributed systems.
-This one keeps the logic inside Redis using Lua for atomic safety.
+> Works correctly across multiple Node.js instances with zero race conditions by keeping the rate-limiting logic inside Redis.
 
-## Install
+---
+
+##  The Problem With Typical Express Rate Limiters
+
+Most middleware like `express-rate-limit`:
+
+* Store counters in memory
+* Break when you scale to multiple servers
+* Leak requests under concurrency
+* Suffer from race conditions
+
+This library solves that by:
+
+> Running the entire rate limiting algorithm **inside Redis** using **Lua**, executed atomically.
+
+---
+
+##  What is the Token Bucket Algorithm?
+
+Token Bucket is an industry standard algorithm used by:
+
+* API Gateways
+* CDNs
+* Reverse Proxies
+* Cloud providers
+
+### How it works
+
+Each user / API key / IP has a **bucket**:
+
+* Bucket has **capacity** (max tokens)
+* Tokens **refill over time**
+* Each request **consumes 1 token**
+* If bucket is empty → request denied
+
+This allows:
+
+* Short bursts of traffic
+* Strict control of long-term rate
+* Smooth throttling instead of hard blocks
+
+Example:
+
+| Setting     | Value             |
+| ----------- | ----------------- |
+| Capacity    | 10                |
+| Refill Rate | 5 tokens / second |
+
+User can send 10 requests instantly, then 5 per second after.
+
+---
+
+##  Why Redis + Lua?
+
+Without Lua:
+
+```
+GET tokens
+CHECK tokens
+SET tokens
+```
+
+This causes race conditions under concurrency.
+
+With Lua:
+
+```
+All logic runs atomically inside Redis.
+```
+
+No race. No burst leak. Fully distributed.
+
+---
+
+##  Install
 
 ```bash
 npm i redis-lua-rate-limiter
 ```
 
-## Usage
+---
+
+##  Basic Usage (IP based)
 
 ```ts
 import express from "express";
 import { createRateLimiter } from "redis-lua-rate-limiter";
 
+const app = express();
+
 const limiter = await createRateLimiter({
   redisUrl: "redis://localhost:6379",
   default: { capacity: 10, refillRate: 5 },
@@ -26,53 +102,165 @@ const limiter = await createRateLimiter({
 });
 
 app.use(limiter.middleware());
+
+app.get("/", (_, res) => res.send("OK"));
+
+app.listen(3000);
+```
+
+---
+
+## 🔑 API Key Based Rate Limiting
+
+```ts
+const limiter = await createRateLimiter({
+  redisUrl: "redis://localhost:6379",
+  default: { capacity: 20, refillRate: 10 },
+
+  keyGenerator: (req) => {
+    const apiKey = req.headers["x-api-key"];
+    if (typeof apiKey === "string") return `rate:${apiKey}`;
+    return `rate:${req.ip}`;
+  },
+});
+```
+
+---
+
+## 🛣️ Per Route Limits
+
+```ts
+const limiter = await createRateLimiter({
+  redisUrl: "redis://localhost:6379",
+
+  default: { capacity: 10, refillRate: 5 },
+
+  routes: {
+    "/login": { capacity: 3, refillRate: 1 },
+    "/heavy": { capacity: 2, refillRate: 0.5 },
+  },
+});
 ```
 
-## Features
+---
 
-- Token bucket algorithm
-- Redis Lua atomic execution
-- Per API key / IP limiting
-- Per route limits
-- Rate limit headers
-- Works across multiple Node servers
+## 📡 Rate Limit Headers
 
-## Benchmark
+When `headers: true`:
 
 ```
-$ npx autocannon -c 1000 -d 15 http://localhost:3000
-Running 15s test @ http://localhost:3000
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 4
 ```
 
-Tested with 1000 connections using autocannon
+Similar to real API gateways.
 
+---
+
+##  Options Reference
+
+```ts
+createRateLimiter({
+  redisUrl: string,              // required
+
+  default: {
+    capacity: number,
+    refillRate: number
+  },
+
+  routes?: Record<string, {
+    capacity: number,
+    refillRate: number
+  }>,
+
+  keyGenerator?: (req: Request) => string,
+
+  headers?: boolean
+})
 ```
-┌─────────┬────────┬────────┬────────┬────────┬───────────┬──────────┬────────┐
-│ Stat    │ 2.5%   │ 50%    │ 97.5%  │ 99%    │ Avg       │ Stdev
-    │ Max    │
-├─────────┼────────┼────────┼────────┼────────┼───────────┼──────────┼────────┤
-│ Latency │ 203 ms │ 214 ms │ 253 ms │ 481 ms │ 220.74 ms │ 41.38 ms │ 759 ms │
-└─────────┴────────┴────────┴────────┴────────┴───────────┴──────────┴────────┘
-┌───────────┬────────┬────────┬─────────┬─────────┬─────────┬────────┬────────┐
-│ Stat      │ 1%     │ 2.5%   │ 50%     │ 97.5%   │ Avg     │ Stdev  │ Min    │
-├───────────┼────────┼────────┼─────────┼─────────┼─────────┼────────┼────────┤
-│ Req/Sec   │ 2,739  │ 2,739  │ 4,595   │ 5,003   │ 4,516.4 │ 558.22 │ 2,739  │
-├───────────┼────────┼────────┼─────────┼─────────┼─────────┼────────┼────────┤
-│ Bytes/Sec │ 898 kB │ 898 kB │ 1.51 MB │ 1.64 MB │ 1.48 MB │ 183 kB │ 897 kB │
-└───────────┴────────┴────────┴─────────┴─────────┴─────────┴────────┴────────┘
+
+---
+
+## 🧪 Benchmark (autocannon)
+
+Tested under heavy concurrency:
+
+```bash
+npx autocannon -c 1000 -d 15 http://localhost:3000
 ```
-Req/Bytes counts sampled once per second.
-# of samples: 15
+
+Result:
+
 ```
 160 2xx responses, 67579 non 2xx responses
-69k requests in 15.22s, 22.2 MB read
-
+69k requests in 15s
+~4500 req/sec
 ```
 
-Shows strict enforcement without race conditions.
+This shows:
+
+* Strict enforcement
+* No race condition
+* No burst leak
+* Fully atomic behavior
+
+---
+
+##  Docker (for Redis)
+
+```yaml
+version: "3.9"
+services:
+  redis:
+    image: redis:7
+    ports:
+      - "6379:6379"
+```
 
-## Docker
+Run:
 
 ```bash
 docker compose up
 ```
+
+---
+
+##  Architecture
+
+```
+Client → Express → Redis Lua → Allow / Deny
+```
+
+All Node instances share the same Redis logic.
+
+---
+
+##  Features
+
+* Token bucket algorithm
+* Redis Lua atomic execution
+* Works across multiple servers
+* Per IP / API key / user limiting
+* Per route limits
+* Rate limit headers
+* TypeScript support
+* Production ready
+
+---
+
+##  When should you use this?
+
+* Horizontally scaled Node.js apps
+* Microservices
+* API servers
+* Authentication endpoints
+* Public APIs
+
+---
+
+## 📜 License
+
+MIT
+
+---
+

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "redis-lua-rate-limiter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Distributed token-bucket rate limiter using Redis Lua scripts for Node.js/Express",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "lua"],
-
+  "files": [
+    "dist",
+    "lua"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "ts-node-dev example/express-app.ts"
@@ -21,7 +23,6 @@
   "author": "shubhankar kumar singh",
   "license": "MIT",
   "dependencies": {
-    
     "ioredis": "^5.9.2"
   },
   "peerDependencies": {