distributed-limiter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohit Pandey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# distributed-limiter
+
+  
+
+A high-performance distributed rate limiter based on the Token Bucket algorithm, designed for Node.js applications using Redis as the backing store.
+
+  
+
+## Features
+
+  
+
+- Token Bucket rate limiting
+
+- Redis-backed distributed state
+
+- Atomic operations using Lua scripts
+
+- TypeScript support
+
+- Lightweight and framework-agnostic
+
+- Suitable for APIs, services, and microservices
+
+  
+
+## Installation
+
+  
+
+```bash
+
+npm  install  distributed-limiter
+
+```
+
+  
+
+## Quick Start
+
+  
+
+```ts
+
+import { TokenBucketLimiter } from  "distributed-limiter";
+
+  
+
+const limiter =  new  TokenBucketLimiter({
+
+redis,
+capacity,
+refillRate
+
+});
+
+  
+
+const result =  await limiter.isAllowed({
+
+key:  "user:123",
+
+tokenRequest:  1,
+
+});
+
+  
+
+if (result.allowed) {
+
+console.log("Request allowed");
+
+} else {
+
+console.log("Rate limit exceeded");
+
+}
+
+```
+
+  
+
+## API
+
+  
+
+### `new TokenBucketLimiter(options)`
+
+  
+
+Creates a new limiter instance.
+
+  
+
+```ts
+
+const limiter =  new  TokenBucketLimiter({
+
+redis,
+limiterCapacity,
+refillRate
+
+});
+
+```
+
+  
+
+### `limiter.isAllowed(request)`
+
+  
+
+Checks whether a request can consume the requested number of tokens.
+
+  
+
+```ts
+
+const result =  await limiter.isAllowed({
+
+key: string,
+
+tokenRequest: number,
+
+});
+
+```
+
+  
+
+#### Request Parameters
+
+`key` - Unique identifier (user, IP, API key, etc.)
+
+`capacity` - Maximum bucket size
+
+`refillRate` - Tokens added per second
+
+`tokenRequest` - Tokens required for the request
+
+  **Note:** `capacity` and `refillRate` can be configured once during limiter initialization and reused automatically for all requests. In applications, only `key` and `tokenRequest` need to be supplied per request.
+
+#### Response
+
+  
+
+```ts
+
+{
+
+allowed: boolean;
+
+}
+
+```
+
+  
+
+## Architecture
+
+  ![Diagram](assets/Rate%20Limiter%20Architecture.png)
+
+```text
+
+Client Request
+
+│
+
+▼
+
+BucketLimiter
+
+│
+
+▼
+
+Redis Lua Script
+
+│
+
+▼
+
+Token Bucket State
+
+```
+
+  
+
+The limiter stores bucket state in Redis and performs all token calculations atomically through Lua scripts to ensure correctness across multiple application instances.
+
+  
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,98 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Limiter: () => Limiter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/TokenBucket.ts
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
+var import_meta = {};
+var tokenBucketLua = import_fs.default.readFileSync(import_path.default.join(import_meta.dirname, "../db/scripts/tokenBucket.lua"), "utf-8");
+async function TokenBucket(redis, { key, capacity, refillRate, tokenRequest }) {
+  const currentTime = Date.now();
+  const sha = await redis.script("LOAD", tokenBucketLua);
+  try {
+    const result = await redis.evalsha(
+      sha,
+      1,
+      key,
+      capacity,
+      refillRate,
+      tokenRequest,
+      currentTime
+    );
+    return result === 1;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("NOSCRIPT")) {
+      const result = await redis.eval(
+        tokenBucketLua,
+        1,
+        key,
+        capacity,
+        refillRate,
+        tokenRequest,
+        currentTime
+      );
+      return result === 1;
+    }
+    throw Error;
+  }
+}
+
+// src/core/LimiterEngine.ts
+var Limiter = class {
+  constructor(redis, capacity, refillRate) {
+    this.redis = redis;
+    this.capacity = capacity;
+    this.refillRate = refillRate;
+  }
+  redis;
+  capacity;
+  refillRate;
+  async isAllowed({ key, tokenRequest }) {
+    const args = {
+      key,
+      capacity: this.capacity,
+      refillRate: this.refillRate,
+      tokenRequest
+    };
+    const redisResponse = await TokenBucket(this.redis, args);
+    ;
+    return redisResponse;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Limiter
+});

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { Redis } from 'ioredis';
+
+type BucketOptions = {
+    key: string;
+    capacity: number;
+    refillRate: number;
+    tokenRequest: number;
+};
+type RateLimiterOptions = {
+    key: string;
+    tokenRequest: number;
+};
+
+declare class Limiter {
+    private redis;
+    private capacity;
+    private refillRate;
+    constructor(redis: Redis, capacity: number, refillRate: number);
+    isAllowed({ key, tokenRequest }: RateLimiterOptions): Promise<Boolean>;
+}
+
+export { type BucketOptions, Limiter, type RateLimiterOptions };

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/db/scripts/tokenBucket.ts
+var bucketLua = `local key = KEYS[1];
+
+local capacity = tonumber(ARGV[1]) or 0;
+local refillRate = tonumber(ARGV[2]);
+local tokenRequest = tonumber(ARGV[3]);
+local currentTime = tonumber(ARGV[4]);
+
+--get bucket from redis
+local bucket = redis.call(
+    "HMGET",
+    key,
+    "tokens",
+    "lastRefill"
+)
+--declare token and lastRefill from bucket
+local tokens = tonumber(bucket[1]);
+local lastRefill = tonumber(bucket[2]);
+
+--if no token refillRate, initialize token with capacity and lastRefill with currentTime.
+if tokens == nil then
+    tokens = capacity
+    lastRefill = currentTime
+end
+
+--calculate refill and elapsed time
+local elapsedTime = (currentTime - lastRefill) / 1000
+local refill = elapsedTime * refillRate
+
+--prepare tokens and avoid bucket overflow
+tokens = math.min(capacity, tokens + refill)
+
+--if requestedTokens exceeds available tokens, return 0
+if tokens < tokenRequest then
+    return 0
+end
+--consume tokens
+tokens = tokens - tokenRequest
+--HMSET the new bucket in redis
+redis.call(
+    "HMSET",
+    key,
+    "tokens",
+    tokens,
+    "lastRefill",
+    currentTime
+)
+--set redis expire
+redis.call(
+    "EXPIRE",
+    key,
+    3600
+)
+return 1`;
+
+// src/core/TokenBucket.ts
+var tokenBucketLua = bucketLua;
+async function TokenBucket(redis, { key, capacity, refillRate, tokenRequest }) {
+  const currentTime = Date.now();
+  const sha = await redis.script("LOAD", tokenBucketLua);
+  try {
+    const result = await redis.evalsha(
+      sha,
+      1,
+      key,
+      capacity,
+      refillRate,
+      tokenRequest,
+      currentTime
+    );
+    return result === 1;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("NOSCRIPT")) {
+      const result = await redis.eval(
+        tokenBucketLua,
+        1,
+        key,
+        capacity,
+        refillRate,
+        tokenRequest,
+        currentTime
+      );
+      return result === 1;
+    }
+    throw Error;
+  }
+}
+
+// src/core/LimiterEngine.ts
+var Limiter = class {
+  constructor(redis, capacity, refillRate) {
+    this.redis = redis;
+    this.capacity = capacity;
+    this.refillRate = refillRate;
+  }
+  redis;
+  capacity;
+  refillRate;
+  async isAllowed({ key, tokenRequest }) {
+    const args = {
+      key,
+      capacity: this.capacity,
+      refillRate: this.refillRate,
+      tokenRequest
+    };
+    const redisResponse = await TokenBucket(this.redis, args);
+    ;
+    return redisResponse;
+  }
+};
+export {
+  Limiter
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "distributed-limiter",
+  "version": "1.0.0",
+  "description": "Distributed token bucket rate limiter using Redis and Lua",
+  "homepage": "https://github.com/Toxic209/distributed-rate-limiter#readme",
+  "bugs": {
+    "url": "https://github.com/Toxic209/distributed-rate-limiter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Toxic209/distributed-rate-limiter.git"
+  },
+  "license": "MIT",
+  "author": "rohit pandey",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "dev": "nodemon --watch src --ext ts --exec tsx src/index.ts",
+    "build": "tsup src/index.ts --format esm --dts"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "ioredis": "^5.10.1",
+    "nodemon": "^3.1.14",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+
+  "files": [
+    "dist",
+    "db"
+  ],
+
+  "keywords": [
+    "rate-limiter",
+    "redis",
+    "token-bucket",
+    "distributed-systems"
+  ]
+}