@fsilva3/rate-limiter-redis 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filipe Silva
+
+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,115 @@
+# Rate Limiter Redis
+
+Rate Limiter Redis is a JavaScript library that provides different algorithms to rate limit your requests using Redis as shared state between the distributed services.
+
+This library is useful for controlling the rate of requests from your application to a third-party service or API.
+
+## Reference
+
+- [Redis Blog](https://redis.io/glossary/rate-limiting/)
+- [Token Bucket](https://en.wikipedia.org/wiki/Token_bucket)
+
+## Benefits
+
+- **Cost-Effective**: Instead calling HTTP APIs and handling execptions might throw from the Third-party API, you can block the request before it reaches the API, or retry the request later.
+
+- **Distributed**: Rate Limiter Redis is designed to work in a distributed environment, where multiple instances of your application can share the same rate limit.
+
+## Installation
+
+To install the library, use npm:
+
+```bash
+npm i --save rate-limiter-redis
+```
+
+## Usage
+
+Here is a few examples of how to use Rate Limiter Redis:
+
+1. Token Bucket Instance
+```javascript
+import { TokenBucket, TokenBucketSettings } from ('@fsilva3/rate-limiter-redis')
+const second = 1000
+
+// 60 tokens (requests) per minute
+const tbSettings: TokenBucketSettings = {
+    capacity: 60,
+    interval: (60*second)
+}
+
+// Create a new token bucket instance
+const bucket = await TokenBucket.create(tbSettings); 
+```
+
+2. Take Method
+```javascript
+// Takes the first token created in the bucket, if exists! Otherwise the token.value will return null
+const token = await bucket.take();
+
+const { 
+    value, // value is a hash string if a token is available, null otherwise
+    timestamp, // timestamp when the token was created
+    remaning // remaining is the number of tokens
+} = token;
+
+if (!value) {
+    // re-queue the message, throw exception or return error
+}
+
+... 
+// Call the Third-party API
+```
+
+3. Delay Method
+```javascript
+// Usually from HTTP frameworks to cancel requests
+const controler = new AbortController()
+
+// In case the bucket is empty, it will block the operation until receive a new token!
+// This method accepts abort signal, which means you can cancel the operation at any time
+const token = await bucket.delay(controler.signal);
+
+const { 
+    value,
+    timestamp,
+    remaning
+} = token;
+
+...
+// Call the Third-party API
+```
+
+## Configuration
+
+The `Redis` connection is made by using environment variables; make sure to have these keys available in your `.env` or any other environment setup:
+```bash
+# .env
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_USER=default
+REDIS_PASSWORD=mysecretpassword
+```
+
+<br>
+
+The `TokenBucket` constructor accepts the following options:
+
+- `capacity`: The maximum number of tokens in the bucket.
+- `interval`: The milliseconds interval at which tokens are added to the bucket
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Acknowledgements
+
+This library is inspired by the token bucket algorithm and uses Redis for storage.
+
+## Contact
+
+For any questions or issues, please open an issue on GitHub.

package/dist/bucket.d.ts

@@ -0,0 +1,13 @@
+import { RedisClientType } from 'redis';
+export default class Bucket {
+    private host;
+    private port;
+    protected client: RedisClientType;
+    private maxConnectionRetries;
+    private retryConnectionCount;
+    constructor();
+    protected connect(): Promise<void>;
+    protected quit(): Promise<void>;
+    private onConnect;
+    private onError;
+}

package/dist/bucket.js

@@ -0,0 +1,74 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const redis_1 = __importDefault(require("redis"));
+const exception_1 = require("./exception");
+const utils_1 = require("./utils");
+class Bucket {
+    constructor() {
+        this.host = '';
+        this.port = 6379;
+        this.maxConnectionRetries = 5;
+        this.retryConnectionCount = 0;
+        const { REDIS_HOST, REDIS_USER, REDIS_PASSWORD, REDIS_PORT, } = process.env;
+        if (!REDIS_HOST) {
+            throw new exception_1.RateLimiterException('REDIS_HOST environment is required');
+        }
+        if (!REDIS_USER) {
+            throw new exception_1.RateLimiterException('REDIS_USER environment is required');
+        }
+        if (!REDIS_PASSWORD) {
+            throw new exception_1.RateLimiterException('REDIS_PASSWORD environment is required');
+        }
+        this.host = REDIS_HOST;
+        if (REDIS_PORT && parseInt(REDIS_PORT) !== 6379) {
+            this.port = parseInt(REDIS_PORT);
+        }
+        const redisURL = `redis://${REDIS_USER}:${REDIS_PASSWORD}@${this.host}:${this.port}`;
+        this.client = redis_1.default.createClient({ url: redisURL, socket: { connectTimeout: 5000 } });
+        this.client.on('error', this.onError);
+        this.client.on('connect', this.onConnect);
+    }
+    connect() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.retryConnectionCount >= this.maxConnectionRetries) {
+                throw new Error('The max Redis connection retry reached out');
+            }
+            if (this.client.isOpen) {
+                yield (0, utils_1.sleep)(200);
+                this.retryConnectionCount += 1;
+                return this.connect();
+            }
+            if (this.client.isReady) {
+                return;
+            }
+            yield this.client.connect();
+        });
+    }
+    quit() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.client.isOpen) {
+                return;
+            }
+            yield this.client.disconnect();
+        });
+    }
+    onConnect() {
+        console.log('Connected to Redis');
+    }
+    onError(err) {
+        throw new exception_1.RateLimiterException(err.message);
+    }
+}
+exports.default = Bucket;

package/dist/exception.d.ts

@@ -0,0 +1,3 @@
+export declare class RateLimiterException extends Error {
+    constructor(msg: string);
+}

package/dist/exception.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiterException = void 0;
+class RateLimiterException extends Error {
+    constructor(msg) {
+        super(msg);
+        Object.setPrototypeOf(this, RateLimiterException.prototype);
+    }
+}
+exports.RateLimiterException = RateLimiterException;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { RateLimiterException } from './exception';
+export { TokenBucketSettings, Token } from './types';
+export { sleep } from './utils';
+import TokenBucket from './token-bucket';
+export { TokenBucket };

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenBucket = exports.sleep = exports.RateLimiterException = void 0;
+var exception_1 = require("./exception");
+Object.defineProperty(exports, "RateLimiterException", { enumerable: true, get: function () { return exception_1.RateLimiterException; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return utils_1.sleep; } });
+const token_bucket_1 = __importDefault(require("./token-bucket"));
+exports.TokenBucket = token_bucket_1.default;

package/dist/token-bucket.d.ts

@@ -0,0 +1,67 @@
+import { Token, TokenBucketSettings } from './types';
+import Bucket from './bucket';
+export default class TokenBucket extends Bucket {
+    private static readonly BUCKET_NAME;
+    private readonly maxDelayRetryCount;
+    private capacity;
+    private interval;
+    private delayRetryCount;
+    private timer;
+    private startTime;
+    constructor(settings: TokenBucketSettings);
+    private generateToken;
+    private getNextExecutionInMilliseconds;
+    private abortHandler;
+    /**
+     * Static method to create a new TokenBucket instance to ensure the bucket is refilled
+     * @param {TokenBucketSettings} settings - The constructor settings for the Bucket
+     * @return {Promise<TokenBucket>} TokenBucket instance
+     * @throws {RateLimiterException}
+     */
+    static create(settings: TokenBucketSettings): Promise<TokenBucket>;
+    /**
+     * If there is tokens available, it takes the token right away, null otherwise
+     * @return {Promise<Token | null>} returns a token or null token
+     *
+     * @example
+     *  const controller = new AbortController()
+     *  const token = await bucket.delay(controller.signal)
+     *  if (!token) {
+     *      // re-queue the message
+     *  }
+     */
+    take(context?: AbortSignal): Promise<Token | null>;
+    /**
+     * Block the operation until receive a new token based on the delay time
+     * @param {AbortSignal?} context - The context in case wants to abort the request
+     * @return {Promise<Token>} The token object
+     *
+     * @example
+     *  const controller = new AbortController()
+     *  const myFreshToken = await bucket.delay(controller.signal)
+     *  ...
+     *  // call the API
+     */
+    delay(context?: AbortSignal): Promise<Token>;
+    /**
+     * Refill the token-bucket with new tokens, in case the bucket is not at the full capacity
+     * @return {Promise<void>}
+     * @throws {RateLimiterException}
+     */
+    refill(): Promise<void>;
+    /**
+     * Close the TokenBucket instance, clear the time and disconnect from Redis
+     * @return {Promise<void>}
+     */
+    close(): Promise<void>;
+    /**
+     * Get the current total of tokens in the bucket
+     * @return {Promise<number>}
+     */
+    getTotalTokens(): Promise<number>;
+    /**
+     * Remove all tokens from the bucket
+     * @return {Promise<void>}
+     */
+    clearTokens(): Promise<void>;
+}

package/dist/token-bucket.js

@@ -0,0 +1,193 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const exception_1 = require("./exception");
+const bucket_1 = __importDefault(require("./bucket"));
+const utils_1 = require("./utils");
+/*
+* TokenBucket algorithm implemented using Redis as storage
+* @class TokenBucket
+* @extends Bucket
+* @since 0.0.1
+*/
+class TokenBucket extends bucket_1.default {
+    constructor(settings) {
+        super();
+        this.maxDelayRetryCount = 5;
+        this.capacity = 0;
+        this.interval = 0;
+        this.delayRetryCount = 0;
+        this.timer = null;
+        this.startTime = 0;
+        this.capacity = settings.capacity;
+        this.interval = settings.interval;
+        this.startTime = Date.now();
+        this.timer = setInterval(this.refill.bind(this), this.interval);
+    }
+    generateToken() {
+        return Math.random().toString(36).substring(2);
+    }
+    getNextExecutionInMilliseconds() {
+        const elapsedTime = Date.now() - this.startTime;
+        const nextExecution = this.interval - Math.ceil(elapsedTime % this.interval);
+        return nextExecution;
+    }
+    abortHandler() {
+        if (this.aborted) {
+            throw new Error('Operation aborted');
+        }
+    }
+    /**
+     * Static method to create a new TokenBucket instance to ensure the bucket is refilled
+     * @param {TokenBucketSettings} settings - The constructor settings for the Bucket
+     * @return {Promise<TokenBucket>} TokenBucket instance
+     * @throws {RateLimiterException}
+     */
+    static create(settings) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const bucket = new TokenBucket(settings);
+                yield bucket.connect();
+                yield bucket.refill();
+                return bucket;
+            }
+            catch (error) {
+                throw new exception_1.RateLimiterException(`Error creating TokenBucket instance | ${error}`);
+            }
+        });
+    }
+    /**
+     * If there is tokens available, it takes the token right away, null otherwise
+     * @return {Promise<Token | null>} returns a token or null token
+     *
+     * @example
+     *  const controller = new AbortController()
+     *  const token = await bucket.delay(controller.signal)
+     *  if (!token) {
+     *      // re-queue the message
+     *  }
+     */
+    take(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                if (context === null || context === void 0 ? void 0 : context.aborted) {
+                    throw new Error('Operation aborted');
+                }
+                context === null || context === void 0 ? void 0 : context.addEventListener('abort', this.abortHandler);
+                const response = yield this.client.RPOP(TokenBucket.BUCKET_NAME);
+                if (!response) {
+                    return null;
+                }
+                const token = JSON.parse(response);
+                token.remaining = yield this.getTotalTokens();
+                context === null || context === void 0 ? void 0 : context.removeEventListener('abort', this.abortHandler);
+                return token;
+            }
+            catch (error) {
+                throw new exception_1.RateLimiterException(`Error taking token from bucket | ${error}`);
+            }
+        });
+    }
+    /**
+     * Block the operation until receive a new token based on the delay time
+     * @param {AbortSignal?} context - The context in case wants to abort the request
+     * @return {Promise<Token>} The token object
+     *
+     * @example
+     *  const controller = new AbortController()
+     *  const myFreshToken = await bucket.delay(controller.signal)
+     *  ...
+     *  // call the API
+     */
+    delay(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.delayRetryCount >= this.maxDelayRetryCount) {
+                throw new exception_1.RateLimiterException('Max delay retries reached out');
+            }
+            const token = yield this.take(context);
+            if (token === null || token === void 0 ? void 0 : token.value) {
+                this.delayRetryCount = 0;
+                return token;
+            }
+            const delayInMilliseconds = this.getNextExecutionInMilliseconds();
+            yield (0, utils_1.sleep)(delayInMilliseconds + 10, context);
+            this.delayRetryCount += 1;
+            return this.delay(context);
+        });
+    }
+    /**
+     * Refill the token-bucket with new tokens, in case the bucket is not at the full capacity
+     * @return {Promise<void>}
+     * @throws {RateLimiterException}
+     */
+    refill() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                if (!this.client.isReady) {
+                    throw new exception_1.RateLimiterException('Redis client is not ready');
+                }
+                const countTokens = yield this.client.LLEN(TokenBucket.BUCKET_NAME);
+                if (countTokens >= this.capacity) {
+                    return;
+                }
+                const tokens = Array.from({
+                    length: this.capacity - countTokens
+                }, () => {
+                    return JSON.stringify({
+                        value: this.generateToken(),
+                        timestamp: Date.now()
+                    });
+                });
+                yield this.client.LPUSH(TokenBucket.BUCKET_NAME, tokens);
+            }
+            catch (error) {
+                throw new exception_1.RateLimiterException(`Error filling token bucket | ${error}`);
+            }
+        });
+    }
+    /**
+     * Close the TokenBucket instance, clear the time and disconnect from Redis
+     * @return {Promise<void>}
+     */
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.timer) {
+                clearInterval(this.timer);
+                this.timer = null;
+            }
+            yield this.quit();
+            console.log('Closed Token Bucket instance!');
+        });
+    }
+    /**
+     * Get the current total of tokens in the bucket
+     * @return {Promise<number>}
+     */
+    getTotalTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.client.LLEN(TokenBucket.BUCKET_NAME);
+        });
+    }
+    /**
+     * Remove all tokens from the bucket
+     * @return {Promise<void>}
+     */
+    clearTokens() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.client.LTRIM(TokenBucket.BUCKET_NAME, 1, 0);
+        });
+    }
+}
+TokenBucket.BUCKET_NAME = 'rate-limiter-tokens';
+exports.default = TokenBucket;

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export type TokenBucketSettings = {
+    capacity: number;
+    interval: number;
+};
+export type Token = {
+    value: string;
+    timestamp: number;
+    remaining?: number;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+declare function sleep(milliseconds: number, context?: AbortSignal): Promise<void>;
+export { sleep };

package/dist/utils.js

@@ -0,0 +1,32 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = sleep;
+const abortHandler = (reject, timeoutId) => {
+    clearTimeout(timeoutId);
+    reject(new Error('Operation aborted'));
+};
+function sleep(milliseconds, context) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise((resolve, reject) => {
+            if (context === null || context === void 0 ? void 0 : context.aborted) {
+                return reject(new Error('Operation aborted'));
+            }
+            const timeoutId = setTimeout(() => {
+                resolve();
+            }, milliseconds);
+            const fn = () => abortHandler(reject, timeoutId);
+            context === null || context === void 0 ? void 0 : context.addEventListener('abort', fn);
+        }).finally(() => {
+            context === null || context === void 0 ? void 0 : context.removeEventListener('abort', () => abortHandler);
+        });
+    });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@fsilva3/rate-limiter-redis",
+  "version": "0.0.2",
+  "license": "MIT",
+  "description": "A javascript library to rate limiter requests using different algorithms using Redis as shared state where you can sync the tokens between multiple services instances",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "coverage": "vitest run --coverage",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "redis": "^4.7.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@types/node": "^22.13.4",
+    "@vitest/coverage-v8": "^3.0.6",
+    "eslint": "^9.20.1",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.0",
+    "vitest": "^3.0.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsilva3/rate-limiter-redis.git"
+  },
+  "keywords": [
+    "token-bucket",
+    "rate limiter",
+    "redis"
+  ],
+  "bugs": {
+    "url": "https://github.com/fsilva3/rate-limiter-redis/issues"
+  },
+  "homepage": "https://github.com/fsilva3/rate-limiter-redis#readme",
+  "author": "Filipe Silva"
+}