@lucid-softworks/token-bucket 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucid Softworks
+
+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,13 @@
+# `@lucid-softworks/token-bucket`
+
+A continuously refilling token bucket with burst capacity, injected time, wait
+estimation, and resetting.
+
+```ts
+import { TokenBucket } from "@lucid-softworks/token-bucket";
+
+const bucket = new TokenBucket({ capacity: 10, refillRate: 0.01 });
+if (bucket.take()) await performRequest();
+```
+
+`refillRate` is tokens per millisecond.

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export interface TokenBucketOptions {
+    readonly capacity: number;
+    readonly refillRate: number;
+    readonly initialTokens?: number;
+    readonly now?: () => number;
+}
+/** A continuously refilling token bucket for burst-aware rate limiting. */
+export declare class TokenBucket {
+    readonly options: TokenBucketOptions;
+    private tokens;
+    private lastRefill;
+    private readonly now;
+    constructor(options: TokenBucketOptions);
+    get available(): number;
+    take(count?: number): boolean;
+    timeUntilAvailable(count?: number): number;
+    reset(tokens?: number): void;
+    private refill;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,2EAA2E;AAC3E,qBAAa,WAAW;IAKV,QAAQ,CAAC,OAAO,EAAE,kBAAkB;IAJhD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,YAAqB,OAAO,EAAE,kBAAkB,EAkB/C;IAED,IAAI,SAAS,IAAI,MAAM,CAGtB;IAED,IAAI,CAAC,KAAK,GAAE,MAAU,GAAG,OAAO,CAQ/B;IAED,kBAAkB,CAAC,KAAK,GAAE,MAAU,GAAG,MAAM,CAe5C;IAED,KAAK,CAAC,MAAM,GAAE,MAA8B,GAAG,IAAI,CAUlD;IAED,OAAO,CAAC,MAAM;CASf"}

package/dist/index.js

@@ -0,0 +1,68 @@
+/** A continuously refilling token bucket for burst-aware rate limiting. */
+export class TokenBucket {
+    options;
+    tokens;
+    lastRefill;
+    now;
+    constructor(options) {
+        this.options = options;
+        if (!Number.isFinite(options.capacity) || options.capacity <= 0) {
+            throw new RangeError("capacity must be positive and finite");
+        }
+        if (!Number.isFinite(options.refillRate) || options.refillRate < 0) {
+            throw new RangeError("refillRate must be finite and non-negative");
+        }
+        const initial = options.initialTokens ?? options.capacity;
+        if (!Number.isFinite(initial) ||
+            initial < 0 ||
+            initial > options.capacity) {
+            throw new RangeError("initialTokens must be between zero and capacity");
+        }
+        this.tokens = initial;
+        this.now = options.now ?? Date.now;
+        this.lastRefill = this.now();
+    }
+    get available() {
+        this.refill();
+        return this.tokens;
+    }
+    take(count = 1) {
+        if (!Number.isFinite(count) || count <= 0) {
+            throw new RangeError("count must be positive and finite");
+        }
+        this.refill();
+        if (this.tokens < count)
+            return false;
+        this.tokens -= count;
+        return true;
+    }
+    timeUntilAvailable(count = 1) {
+        if (!Number.isFinite(count) ||
+            count <= 0 ||
+            count > this.options.capacity) {
+            throw new RangeError("count must be positive and no greater than capacity");
+        }
+        this.refill();
+        if (this.tokens >= count)
+            return 0;
+        return this.options.refillRate === 0
+            ? Number.POSITIVE_INFINITY
+            : (count - this.tokens) / this.options.refillRate;
+    }
+    reset(tokens = this.options.capacity) {
+        if (!Number.isFinite(tokens) ||
+            tokens < 0 ||
+            tokens > this.options.capacity) {
+            throw new RangeError("tokens must be between zero and capacity");
+        }
+        this.tokens = tokens;
+        this.lastRefill = this.now();
+    }
+    refill() {
+        const now = this.now();
+        const elapsed = Math.max(0, now - this.lastRefill);
+        this.tokens = Math.min(this.options.capacity, this.tokens + elapsed * this.options.refillRate);
+        this.lastRefill = now;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,2EAA2E;AAC3E,MAAM,OAAO,WAAW;IAKD,OAAO;IAJpB,MAAM,CAAS;IACf,UAAU,CAAS;IACV,GAAG,CAAe;IAEnC,YAAqB,OAA2B;uBAA3B,OAAO;QAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;YAChE,MAAM,IAAI,UAAU,CAAC,sCAAsC,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,UAAU,CAAC,4CAA4C,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,QAAQ,CAAC;QAC1D,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;YACzB,OAAO,GAAG,CAAC;YACX,OAAO,GAAG,OAAO,CAAC,QAAQ,EAC1B,CAAC;YACD,MAAM,IAAI,UAAU,CAAC,iDAAiD,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;QACtB,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,CAAC;IAED,IAAI,SAAS;QACX,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,CAAC,KAAK,GAAW,CAAC;QACpB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,UAAU,CAAC,mCAAmC,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB,CAAC,KAAK,GAAW,CAAC;QAClC,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YACvB,KAAK,IAAI,CAAC;YACV,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAC7B,CAAC;YACD,MAAM,IAAI,UAAU,CAClB,qDAAqD,CACtD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;YAAE,OAAO,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,CAAC;YAClC,CAAC,CAAC,MAAM,CAAC,iBAAiB;YAC1B,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,MAAM,GAAW,IAAI,CAAC,OAAO,CAAC,QAAQ;QAC1C,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YACxB,MAAM,GAAG,CAAC;YACV,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAC9B,CAAC;YACD,MAAM,IAAI,UAAU,CAAC,0CAA0C,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,CAAC;IAEO,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CACpB,IAAI,CAAC,OAAO,CAAC,QAAQ,EACrB,IAAI,CAAC,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAChD,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@lucid-softworks/token-bucket",
+  "version": "0.0.0",
+  "description": "A continuously refilling token bucket for burst-aware limiting.",
+  "keywords": [
+    "bucket",
+    "javascript",
+    "token",
+    "typescript",
+    "utility"
+  ],
+  "homepage": "https://github.com/lucid-softworks/token-bucket#readme",
+  "bugs": {
+    "url": "https://github.com/lucid-softworks/token-bucket/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucid-softworks/token-bucket.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "bench": "vitest bench --run",
+    "bench:smoke": "VITEST_BENCHMARK_SMOKE=1 vitest bench --run",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "oxfmt --check . && oxlint . && tsc -p tsconfig.json && tsc -p tsconfig.build.json && vitest run --coverage && publint && VITEST_BENCHMARK_SMOKE=1 vitest bench --run",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "pack:check": "publint",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@lucid-softworks/oxfmt-config": "^0.1.1",
+    "@lucid-softworks/oxlint-config": "^0.1.0",
+    "@lucid-softworks/tsconfig": "^0.1.0",
+    "@lucid-softworks/vitest-config": "^0.1.1",
+    "@types/node": "26.1.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "oxfmt": "0.60.0",
+    "oxlint": "1.75.0",
+    "publint": "0.3.22",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.16.0"
+}