{"_id":"@aksparadise/valkey-token-bucket","name":"@aksparadise/valkey-token-bucket","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aksparadise/valkey-token-bucket","version":"1.0.0","description":"Production-ready, highly-scalable, and distributed Rate Limiter using Token Bucket algorithm in Valkey/Redis. Prevents race-conditions atomically via Lua scripting. Highly optimized with zero runtime dependencies. Created by AksParadise.","type":"module","main":"./dist/cjs/index.cjs","module":"./dist/esm/index.mjs","types":"./dist/index.d.ts","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/esm/index.mjs","require":"./dist/cjs/index.cjs"},"./limiter":{"types":"./dist/limiter.d.ts","import":"./dist/esm/limiter.mjs","require":"./dist/cjs/limiter.cjs"},"./middleware":{"types":"./dist/middleware.d.ts","import":"./dist/esm/middleware.mjs","require":"./dist/cjs/middleware.cjs"}},"typesVersions":{"*":{"limiter":["dist/limiter.d.ts"],"middleware":["dist/middleware.d.ts"],"*":["dist/index.d.ts"]}},"scripts":{"build":"npm run build:esm && npm run build:cjs && npm run build:types","build:esm":"node build-esm.js","build:cjs":"node build-cjs.js","build:types":"node build-types.js","prepublishOnly":"npm run build","test":"vitest","test:run":"vitest run","lint":"eslint src/"},"author":{"name":"AksParadise"},"license":"MIT","dependencies":{},"devDependencies":{"@eslint/js":"^9.0.0","esbuild":"^0.21.0","eslint":"^9.0.0","vitest":"^1.5.0"},"peerDependencies":{"ioredis":">=5.0.0","redis":">=4.0.0"},"peerDependenciesMeta":{"ioredis":{"optional":true},"redis":{"optional":true}},"_id":"@aksparadise/valkey-token-bucket@1.0.0","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-7UPHeMc8s6dhYScQWr46vwLd8ZC41Q1VMpiClqfL+NXp48aweZ0chnSsns7l0/RHh7j/ILFIZvT9Vzvd/FOCRQ==","shasum":"b8b51847d28b9d94d561a7b3a44e8fdba493a9ce","tarball":"https://registry.npmjs.org/@aksparadise/valkey-token-bucket/-/valkey-token-bucket-1.0.0.tgz","fileCount":19,"unpackedSize":31063,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD0UJTaAUK6O1J8ymDw+jGs4VQLIAVDtDAYeBhTPUKpdAIhAN6nwfODZESB9Ninu0JULm7TYbjMOoBDG8TusFMSafb9"}]},"_npmUser":{"name":"akstyleakstyle","email":"akstyleakstyle1@gmail.com"},"directories":{},"maintainers":[{"name":"akstyleakstyle","email":"akstyleakstyle1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/valkey-token-bucket_1.0.0_1786087832583_0.10938800345024768"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-07T07:30:32.394Z","1.0.0":"2026-08-07T07:30:32.734Z","modified":"2026-08-07T07:30:33.231Z"},"maintainers":[{"name":"akstyleakstyle","email":"akstyleakstyle1@gmail.com"}],"description":"Production-ready, highly-scalable, and distributed Rate Limiter using Token Bucket algorithm in Valkey/Redis. Prevents race-conditions atomically via Lua scripting. Highly optimized with zero runtime dependencies. Created by AksParadise.","author":{"name":"AksParadise"},"license":"MIT","readme":"# @aksparadise/valkey-token-bucket ⏱️\n\n[![NPM Version](https://img.shields.io/npm/v/@aksparadise/valkey-token-bucket.svg)](https://www.npmjs.com/package/@aksparadise/valkey-token-bucket)\n[![License](https://img.shields.io/npm/l/@aksparadise/valkey-token-bucket.svg)](https://github.com/aksparadise/valkey-token-bucket/blob/main/LICENSE)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/@aksparadise/valkey-token-bucket)\n\nA production-ready, highly-scalable, and distributed **Token Bucket Rate Limiter** for **Valkey** and **Redis** in Node.js. \n\nAtomically eliminates distributed race-conditions using high-speed server-side **Lua scripts**. Zero runtime dependencies for absolute security and safety. Built by **AksParadise**.\n\n---\n\n## ✨ Features\n\n* **🏎️ Zero-Latency Atomic Evaluation**: Recalculates limits inside a single-threaded Lua script on Valkey, preventing concurrency race-conditions (TOCTOU) completely.\n* **🛡️ Zero-Vulnerability Architecture**: Has **0 direct runtime dependencies**, fully protecting your project from nested package CVE chains.\n* **📦 Dual CJS + ESM Packaging**: Supports modern ES6 `import` syntax as well as legacy CommonJS `require()` natively.\n* **🔌 Native Driver Support**: Out-of-the-box auto-detection for both `ioredis` and `redis` (node-redis v4+).\n* **💡 Advanced Express Middleware Wrapper**: Built-in, RFC-compliant rate limiter supporting standard headers and custom user dynamic keys (e.g. rate limit by Session Account IDs, API keys, or custom headers).\n* **📐 TypeScript Definitions Included**: Fully typed out-of-the-box (`d.ts` definitions).\n\n---\n\n## 📋 Prerequisites\n\nTo use this library, ensure your project setup has:\n1. **Node.js** version `16.0.0` or newer.\n2. **Valkey** version `7.2.0+` OR **Redis** version `2.6.0+` (since `EVAL` execution was introduced).\n3. Either of the following driver clients installed in your project:\n   * **`redis`** (node-redis version `^4.0.0`)\n   * **`ioredis`** (version `^5.0.0`)\n\n---\n\n## 🚀 Installation\n\n```bash\nnpm install @aksparadise/valkey-token-bucket\n```\n\n---\n\n## 💻 Usage\n\n### 1. Simple Express Middleware Integration (By Client IP)\nBy default, the middleware tracks client IP addresses and enforces rate limiting:\n\n```javascript\nimport express from \"express\";\nimport { createClient } from \"redis\";\nimport { expressRateLimiter } from \"@aksparadise/valkey-token-bucket\";\n\nconst app = express();\nconst redisClient = createClient();\nawait redisClient.connect();\n\nconst limiter = expressRateLimiter({\n    redisClient: redisClient,\n    capacity: 100,             // Max tokens\n    windowMs: 60000,           // Duration to fully refill (1 minute)\n    keyPrefix: \"limit:api:\"\n});\n\n// Apply to routes\napp.use(\"/api/v3\", limiter);\n```\n\n---\n\n### 2. Advanced Express Middleware Integration (By Custom Session User)\nYou can provide a `keyGenerator` callback to rate-limit by custom session properties (like logged-in user account IDs or custom auth API keys) rather than client IP addresses:\n\n```javascript\nimport express from \"express\";\nimport { expressRateLimiter } from \"@aksparadise/valkey-token-bucket\";\n\nconst app = express();\n\nconst folderSyncLimiter = expressRateLimiter({\n    redisClient: myRedisClient,\n    capacity: 10,\n    windowMs: 60000,\n    keyPrefix: \"ratelimit:sync:\",\n    \n    // Custom key resolver:\n    keyGenerator: (req) => req.session?.accountId // Defaults to client IP if undefined\n});\n\napp.get(\"/folders\", folderSyncLimiter, (req, res) => {\n    res.json({ success: true, folders: [] });\n});\n```\n\n---\n\n### 3. Programmatic Usage (Any Framework)\nYou can use the core class directly inside any web framework, microservice, gRPC, or WebSocket server:\n\n```javascript\nimport { TokenBucketLimiter } from \"@aksparadise/valkey-token-bucket\";\n\nconst limiter = new TokenBucketLimiter({\n    redisClient: myRedisClient,\n    capacity: 250,\n    windowMs: 60000, // 250 requests per minute\n    keyPrefix: \"api-limit:\"\n});\n\nasync function handleRequest(userId) {\n    const result = await limiter.consume(userId, 1);\n\n    if (result.allowed) {\n        console.log(`Allowed! Tokens left: ${result.remaining}`);\n        // Proceed with request...\n    } else {\n        console.log(`Rate limited! Retry after ${result.retryAfterSeconds} seconds.`);\n        // Return 429 Too Many Requests...\n    }\n}\n```\n\n---\n\n## 📈 Standard HTTP Response Headers\n\nThe built-in Express middleware automatically attaches standard RFC-compliant headers:\n\n| Header Name | Description |\n| :--- | :--- |\n| `X-RateLimit-Limit` | The maximum capacity of the rate limit bucket. |\n| `X-RateLimit-Remaining` | Remaining tokens left in the bucket. |\n| `Retry-After` | Time (in seconds) the client must wait before making another request (returned only on `429`). |\n\n---\n\n## 🛡️ Security & Fail-Open Philosophy\n\nIn enterprise production architectures, a database lag or caching server crash should **never** lock legitimate users out of your core services. \n\nOur package operates under a strict **Fail-Open Policy**: if your Valkey or Redis server goes offline or suffers connection timeouts, the library catches the incident, prints a structured warning log console, and **silently allows the user request to proceed** (calls `next()`), keeping your user experience 100% seamless during infrastructure updates.\n\n---\n\n## 📄 License\n\nMIT © [AksParadise](https://github.com/aksparadise)\n","readmeFilename":"README.md","_rev":"1-5a7352e3b126a65ba848d4dbd2d8fd94"}