token-bucket.ts 0.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) [2026], [Beeno Tung (Tung Cheung Leong)]
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,157 @@
+# token-bucket.ts
+
+A simple, lightweight token bucket rate limiter for TypeScript/JavaScript.
+
+[![npm Package Version](https://img.shields.io/npm/v/token-bucket.ts)](https://www.npmjs.com/package/token-bucket.ts)
+[![Minified Package Size](https://img.shields.io/bundlephobia/min/token-bucket.ts)](https://bundlephobia.com/package/token-bucket.ts)
+[![Minified and Gzipped Package Size](https://img.shields.io/bundlephobia/minzip/token-bucket.ts)](https://bundlephobia.com/package/token-bucket.ts)
+
+## Features
+
+- Zero dependencies
+- Continuous refill (lazy evaluation, no timers)
+- Per-key buckets (rate limit by IP, user ID, etc.)
+- Optional cooldown (minimum time between consumes)
+- TypeScript with full type definitions
+- Works in Node.js and browsers
+
+## Installation
+
+```bash
+npm install token-bucket.ts
+```
+
+You can also install with [pnpm](https://pnpm.io/), [yarn](https://yarnpkg.com/), or [slnpm](https://github.com/beenotung/slnpm)
+
+## Usage
+
+```typescript
+import { TokenBucket } from 'token-bucket.ts'
+
+// Create a bucket: 5 tokens capacity, refill 1 token per second
+let bucket = new TokenBucket({
+  capacity: 5, // max number of token for each key
+  initial: 3, // can be different from capacity
+  interval: 1000, // ms, refill interval for each token
+  cooldown: 1000, // ms, minimum time between successful consumes,
+})
+
+// Consume a token
+let { wait_time } = bucket.consume('user:123')
+if (wait_time > 0) {
+  // Rate limited - wait_time ms until a token is available
+  throw new Error(`Rate limited. Try again in ${Math.ceil(wait_time / 1000)}s`)
+}
+
+// Check without consuming
+let result = bucket.check('user:123')
+
+// Consume multiple tokens
+bucket.consume('user:123', 3)
+
+// Reset a specific key, you don't need to reset it manually, but you can
+bucket.reset('user:123')
+
+// Reset all keys
+bucket.reset_all()
+
+// Get number of tracked buckets
+console.log(bucket.size)
+
+// Remove fully-recovered buckets to free memory
+bucket.prune()
+```
+
+## API
+
+### `new TokenBucket(options)`
+
+| Option     | Type   | Default  | Description                                   |
+| ---------- | ------ | -------- | --------------------------------------------- |
+| `capacity` | number | required | Maximum tokens in bucket                      |
+| `interval` | number | required | Refill interval in milliseconds               |
+| `refill`   | number | 1        | Tokens to add per interval                    |
+| `initial`  | number | capacity | Starting tokens for new buckets               |
+| `cooldown` | number | 0        | Minimum time (ms) between successful consumes |
+
+### Methods
+
+| Method                  | Description                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `check(key, amount?)`   | Check if tokens available (doesn't consume). `amount` defaults to 1, can be 0 to check only cooldown |
+| `consume(key, amount?)` | Consume tokens if available. `amount` defaults to 1, must be > 0                                     |
+| `reset(key)`            | Reset a specific key's bucket                                                                        |
+| `reset_all()`           | Reset all buckets                                                                                    |
+| `prune()`               | Remove fully-recovered buckets. Returns number removed. Only works when `initial >= capacity`        |
+| `size`                  | Get number of tracked buckets                                                                        |
+
+### Return Value
+
+```typescript
+{
+  wait_time: number
+} // 0 = allowed, >0 = wait this many ms
+```
+
+### Validation
+
+Both `check` and `consume` throw errors for invalid amounts:
+
+- `amount must be a number` - NaN provided
+- `amount must be >= 0` (check) or `amount must be > 0` (consume)
+- `amount must be <= capacity` - Cannot request more than bucket capacity
+
+## Examples
+
+### API Rate Limiting
+
+```typescript
+let apiLimit = new TokenBucket({ capacity: 60, interval: 1000 })
+
+function handleRequest(ip: string) {
+  let { wait_time } = apiLimit.consume(ip)
+  if (wait_time > 0) {
+    return { status: 429, message: 'Too many requests' }
+  }
+  // Process request...
+}
+```
+
+### SMS Verification with Cooldown
+
+```typescript
+let smsLimit = new TokenBucket({
+  capacity: 5, // Allow burst of 5
+  interval: 60000, // Refill 1 per minute
+  cooldown: 60000, // Minimum 60s between sends
+})
+
+function sendSMS(phone: string) {
+  let { wait_time } = smsLimit.consume(phone)
+  if (wait_time > 0) {
+    throw new Error(`Please wait ${Math.ceil(wait_time / 1000)} seconds`)
+  }
+  // Send SMS...
+}
+```
+
+### Gradual Trust (Lower Initial Tokens)
+
+```typescript
+let newUserLimit = new TokenBucket({
+  capacity: 10,
+  interval: 1000,
+  initial: 3, // New users start with fewer tokens
+})
+```
+
+## License
+
+This project is licensed with [BSD-2-Clause](./LICENSE)
+
+This is free, libre, and open-source software. It comes down to four essential freedoms [[ref]](https://seirdy.one/2021/01/27/whatsapp-and-the-domestication-of-users.html#fnref:2):
+
+- The freedom to run the program as you wish, for any purpose
+- The freedom to study how the program works, and change it so it does your computing as you wish
+- The freedom to redistribute copies so you can help others
+- The freedom to distribute copies of your modified versions to others

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export type TokenBucketOptions = {
+    capacity: number;
+    interval: number;
+    refill?: number;
+    initial?: number;
+    cooldown?: number;
+};
+export type TokenBucketResult = {
+    /**
+     * - in milliseconds
+     * - if zero, means no wait is needed
+     */
+    wait_time: number;
+};
+export declare class TokenBucket {
+    capacity: number;
+    interval: number;
+    refill: number;
+    initial: number;
+    cooldown: number;
+    private buckets;
+    constructor(options: TokenBucketOptions);
+    private get_bucket;
+    private refill_bucket;
+    private calc_token_wait_time;
+    private calc_cooldown_wait_time;
+    check(key: string, amount?: number): TokenBucketResult;
+    consume(key: string, amount?: number): TokenBucketResult;
+    reset(key: string): void;
+    reset_all(): void;
+    get size(): number;
+    /**
+     * Remove stale buckets that have fully recovered.
+     * Only prunes if initial >= capacity to avoid losing accumulated tokens.
+     * A bucket is pruned when it has full capacity and cooldown has passed.
+     * @returns number of buckets removed
+     */
+    prune(): number;
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenBucket = void 0;
+class TokenBucket {
+    capacity;
+    interval; // in milliseconds
+    refill;
+    initial;
+    cooldown; // in milliseconds
+    buckets = new Map();
+    constructor(options) {
+        this.capacity = options.capacity;
+        this.interval = options.interval;
+        this.refill = options.refill ?? 1;
+        this.initial = options.initial ?? this.capacity;
+        this.cooldown = options.cooldown ?? 0;
+    }
+    get_bucket(key) {
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = {
+                tokens: this.initial,
+                last_refill: Date.now(),
+                last_consume: -Infinity,
+            };
+            this.buckets.set(key, bucket);
+        }
+        return bucket;
+    }
+    refill_bucket(bucket) {
+        let now = Date.now();
+        let elapsed = now - bucket.last_refill;
+        let refill_amount = (elapsed / this.interval) * this.refill;
+        bucket.tokens = Math.min(this.capacity, bucket.tokens + refill_amount);
+        bucket.last_refill = now;
+    }
+    calc_token_wait_time(tokens, amount) {
+        if (tokens >= amount)
+            return 0;
+        let needed = amount - tokens;
+        return (needed / this.refill) * this.interval;
+    }
+    calc_cooldown_wait_time(bucket) {
+        if (this.cooldown === 0)
+            return 0;
+        let now = Date.now();
+        let elapsed = now - bucket.last_consume;
+        if (elapsed >= this.cooldown)
+            return 0;
+        return this.cooldown - elapsed;
+    }
+    check(key, amount = 1) {
+        if (Number.isNaN(amount)) {
+            throw new Error('amount must be a number');
+        }
+        if (amount < 0) {
+            throw new Error('amount must be >= 0');
+        }
+        if (amount > this.capacity) {
+            throw new Error('amount must be <= capacity');
+        }
+        let bucket = this.get_bucket(key);
+        this.refill_bucket(bucket);
+        let cooldown_wait = this.calc_cooldown_wait_time(bucket);
+        let token_wait = this.calc_token_wait_time(bucket.tokens, amount);
+        return {
+            wait_time: Math.max(cooldown_wait, token_wait),
+        };
+    }
+    consume(key, amount = 1) {
+        if (Number.isNaN(amount)) {
+            throw new Error('amount must be a number');
+        }
+        if (amount <= 0) {
+            throw new Error('amount must be > 0');
+        }
+        if (amount > this.capacity) {
+            throw new Error('amount must be <= capacity');
+        }
+        let bucket = this.get_bucket(key);
+        this.refill_bucket(bucket);
+        let cooldown_wait = this.calc_cooldown_wait_time(bucket);
+        let token_wait = this.calc_token_wait_time(bucket.tokens, amount);
+        let wait_time = Math.max(cooldown_wait, token_wait);
+        if (wait_time === 0) {
+            bucket.tokens -= amount;
+            bucket.last_consume = Date.now();
+        }
+        return { wait_time };
+    }
+    reset(key) {
+        this.buckets.delete(key);
+    }
+    reset_all() {
+        this.buckets.clear();
+    }
+    get size() {
+        return this.buckets.size;
+    }
+    /**
+     * Remove stale buckets that have fully recovered.
+     * Only prunes if initial >= capacity to avoid losing accumulated tokens.
+     * A bucket is pruned when it has full capacity and cooldown has passed.
+     * @returns number of buckets removed
+     */
+    prune() {
+        let capacity = this.capacity;
+        if (this.initial < capacity) {
+            console.warn("TokenBucket.prune(): initial < capacity, won't prune to avoid losing accumulated tokens");
+            return 0; // Don't prune - would lose accumulated tokens
+        }
+        let removed = 0;
+        for (let [key, bucket] of this.buckets) {
+            this.refill_bucket(bucket);
+            let cooldown_wait = this.calc_cooldown_wait_time(bucket);
+            if (bucket.tokens < capacity || cooldown_wait > 0) {
+                continue;
+            }
+            this.buckets.delete(key);
+            removed++;
+        }
+        return removed;
+    }
+}
+exports.TokenBucket = TokenBucket;

package/package.json

@@ -1,26 +1,51 @@
 {
   "name": "token-bucket.ts",
-  "version": "0.0.0",
+  "version": "1.0.1",
   "type": "commonjs",
-  "description": "",
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "description": "A simple, lightweight token bucket rate limiter for TypeScript/JavaScript.",
+  "keywords": [
+    "token-bucket",
+    "rate-limit",
+    "rate-limiter",
+    "throttle",
+    "throttling",
+    "api-limit",
+    "cooldown",
+    "typescript"
+  ],
+  "author": "Beeno Tung <aabbcc1241@yahoo.com.hk> (https://beeno-tung.surge.sh)",
+  "license": "BSD-2-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beenotung/token-bucket.ts.git"
+  },
+  "homepage": "https://github.com/beenotung/token-bucket.ts#readme",
+  "bugs": {
+    "url": "https://github.com/beenotung/token-bucket.ts/issues"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
   "scripts": {
-    "test": "tsc --noEmit",
+    "test": "npm run mocha && tsc --noEmit",
     "clean": "rimraf dist",
     "build": "rimraf dist && tsc -p . && rimraf dist/tsconfig.tsbuildinfo dist/*.test.d.ts dist/*.test.js dist/*.spec.d.ts dist/*.spec.js",
     "tsc": "tsc -p .",
-    "dev": "tsc -p . --watch"
+    "dev": "tsc -p . --watch",
+    "mocha": "ts-mocha \"src/**/*.{test,spec}.ts\""
   },
   "devDependencies": {
+    "@types/chai": "^4.3.20",
+    "@types/mocha": "^10.0.10",
     "@types/node": "^24.10.9",
+    "@types/sinon": "^21.0.0",
+    "chai": "^4.5.0",
+    "mocha": "^11.7.5",
     "rimraf": "^6.1.2",
+    "sinon": "^21.0.1",
+    "ts-mocha": "^11.1.0",
     "ts-node": "^10.9.2",
     "ts-node-dev": "^2.0.0",
     "typescript": "^5.9.3"