@hardlydifficult/throttle 1.0.0

package/README.md

@@ -0,0 +1,42 @@
+# @hardlydifficult/throttle
+
+Rate limiting utilities with optional state persistence.
+
+## Installation
+
+```bash
+npm install @hardlydifficult/throttle
+```
+
+## Throttle
+
+Delay-based rate limiting with human-readable durations.
+
+```typescript
+import { Throttle } from '@hardlydifficult/throttle';
+
+const throttle = new Throttle({
+  minimumDelay: { value: 1.5, unit: 'minutes' },
+  onSleep: (ms) => console.log(`Sleeping ${ms}ms`),
+});
+
+await throttle.wait(); // resolves immediately
+await throttle.wait(); // sleeps 90s before resolving
+```
+
+## WeightedThrottle
+
+Per-operation weight support with optional state persistence across restarts.
+
+```typescript
+import { WeightedThrottle } from '@hardlydifficult/throttle';
+
+const throttle = new WeightedThrottle({
+  unitsPerSecond: 10,
+  persistKey: 'api-throttle', // optional: survives restarts
+  onSleep: (ms, info) => console.log(`Sleeping ${ms}ms (weight: ${info.weight})`),
+});
+
+await throttle.wait(5);  // consumes 5 units
+await throttle.wait(10); // consumes 10 units, sleeps if needed
+```

package/dist/Throttle.d.ts

@@ -0,0 +1,13 @@
+import { type TimeSpan } from "@hardlydifficult/date-time";
+export interface ThrottleOptions {
+    minimumDelay: TimeSpan;
+    onSleep?: (ms: number) => void;
+}
+export declare class Throttle {
+    private lastTimestamp;
+    private readonly minimumDelayMs;
+    private readonly onSleep?;
+    constructor(options: ThrottleOptions);
+    wait(): Promise<void>;
+}
+//# sourceMappingURL=Throttle.d.ts.map

package/dist/Throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Throttle.d.ts","sourceRoot":"","sources":["../src/Throttle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAkB,MAAM,4BAA4B,CAAC;AAO3E,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,QAAQ,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAuB;gBAEpC,OAAO,EAAE,eAAe;IAQ9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAY5B"}

package/dist/Throttle.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Throttle = void 0;
+const date_time_1 = require("@hardlydifficult/date-time");
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+class Throttle {
+    lastTimestamp = 0;
+    minimumDelayMs;
+    onSleep;
+    constructor(options) {
+        this.minimumDelayMs = (0, date_time_1.toMilliseconds)(options.minimumDelay);
+        if (this.minimumDelayMs <= 0) {
+            throw new Error("Throttle minimumDelay must be a positive duration");
+        }
+        this.onSleep = options.onSleep;
+    }
+    async wait() {
+        const now = Date.now();
+        const target = Math.max(now, this.lastTimestamp + this.minimumDelayMs);
+        const delay = target - now;
+        this.lastTimestamp = target;
+        if (delay > 0) {
+            this.onSleep?.(delay);
+            await sleep(delay);
+        }
+    }
+}
+exports.Throttle = Throttle;
+//# sourceMappingURL=Throttle.js.map

package/dist/Throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Throttle.js","sourceRoot":"","sources":["../src/Throttle.ts"],"names":[],"mappings":";;;AAAA,0DAA2E;AAE3E,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAC1C,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACtB,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1B,CAAC,CAAC,CAAC;AAOL,MAAa,QAAQ;IACX,aAAa,GAAG,CAAC,CAAC;IACT,cAAc,CAAS;IACvB,OAAO,CAAwB;IAEhD,YAAY,OAAwB;QAClC,IAAI,CAAC,cAAc,GAAG,IAAA,0BAAc,EAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC3D,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;QACvE,MAAM,KAAK,GAAG,MAAM,GAAG,GAAG,CAAC;QAE3B,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;QAE5B,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;YACtB,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AAzBD,4BAyBC"}

package/dist/WeightedThrottle.d.ts

@@ -0,0 +1,20 @@
+export interface WeightedThrottleSleepInfo {
+    weight: number;
+    limitPerSecond: number;
+    scheduledStart: number;
+}
+export interface WeightedThrottleOptions {
+    unitsPerSecond: number;
+    persistKey?: string;
+    stateDirectory?: string;
+    onSleep?: (delayMs: number, info: WeightedThrottleSleepInfo) => void;
+}
+export declare class WeightedThrottle {
+    private nextAvailableAt;
+    private readonly unitsPerSecond;
+    private readonly stateTracker?;
+    private readonly onSleep?;
+    constructor(options: WeightedThrottleOptions);
+    wait(weight: number): Promise<void>;
+}
+//# sourceMappingURL=WeightedThrottle.d.ts.map

package/dist/WeightedThrottle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WeightedThrottle.d.ts","sourceRoot":"","sources":["../src/WeightedThrottle.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACtE;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAuB;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAGf;gBAEE,OAAO,EAAE,uBAAuB;IAsBtC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAuB1C"}

package/dist/WeightedThrottle.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeightedThrottle = void 0;
+const state_tracker_1 = require("@hardlydifficult/state-tracker");
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+class WeightedThrottle {
+    nextAvailableAt;
+    unitsPerSecond;
+    stateTracker;
+    onSleep;
+    constructor(options) {
+        this.unitsPerSecond = options.unitsPerSecond;
+        this.onSleep = options.onSleep;
+        if (!Number.isFinite(this.unitsPerSecond) || this.unitsPerSecond <= 0) {
+            throw new Error("WeightedThrottle requires a positive unitsPerSecond value");
+        }
+        if (options.persistKey !== undefined) {
+            this.stateTracker = new state_tracker_1.StateTracker({
+                key: options.persistKey,
+                default: Date.now(),
+                stateDirectory: options.stateDirectory,
+            });
+            this.nextAvailableAt = this.stateTracker.load();
+        }
+        else {
+            this.nextAvailableAt = 0;
+        }
+    }
+    async wait(weight) {
+        if (!Number.isFinite(weight) || weight <= 0) {
+            return;
+        }
+        const now = Date.now();
+        const startAt = Math.max(now, this.nextAvailableAt);
+        const processingWindowMs = (weight / this.unitsPerSecond) * 1000;
+        const delayMs = startAt - now;
+        const newNextAvailableAt = startAt + processingWindowMs;
+        this.stateTracker?.save(newNextAvailableAt);
+        this.nextAvailableAt = newNextAvailableAt;
+        if (delayMs > 0) {
+            this.onSleep?.(delayMs, {
+                weight,
+                limitPerSecond: this.unitsPerSecond,
+                scheduledStart: startAt,
+            });
+            await sleep(delayMs);
+        }
+    }
+}
+exports.WeightedThrottle = WeightedThrottle;
+//# sourceMappingURL=WeightedThrottle.js.map

package/dist/WeightedThrottle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WeightedThrottle.js","sourceRoot":"","sources":["../src/WeightedThrottle.ts"],"names":[],"mappings":";;;AAAA,kEAA8D;AAE9D,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAC1C,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACtB,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1B,CAAC,CAAC,CAAC;AAeL,MAAa,gBAAgB;IACnB,eAAe,CAAS;IACf,cAAc,CAAS;IACvB,YAAY,CAAwB;IACpC,OAAO,CAGd;IAEV,YAAY,OAAgC;QAC1C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAE/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,KAAK,CACb,2DAA2D,CAC5D,CAAC;QACJ,CAAC;QAED,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACrC,IAAI,CAAC,YAAY,GAAG,IAAI,4BAAY,CAAC;gBACnC,GAAG,EAAE,OAAO,CAAC,UAAU;gBACvB,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;gBACnB,cAAc,EAAE,OAAO,CAAC,cAAc;aACvC,CAAC,CAAC;YACH,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;QAClD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;YAC5C,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QACpD,MAAM,kBAAkB,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;QACjE,MAAM,OAAO,GAAG,OAAO,GAAG,GAAG,CAAC;QAC9B,MAAM,kBAAkB,GAAG,OAAO,GAAG,kBAAkB,CAAC;QAExD,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC5C,IAAI,CAAC,eAAe,GAAG,kBAAkB,CAAC;QAE1C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE;gBACtB,MAAM;gBACN,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,cAAc,EAAE,OAAO;aACxB,CAAC,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;CACF;AAtDD,4CAsDC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Throttle, type ThrottleOptions } from "./Throttle";
+export { WeightedThrottle, type WeightedThrottleOptions, type WeightedThrottleSleepInfo, } from "./WeightedThrottle";
+//# 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,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeightedThrottle = exports.Throttle = void 0;
+var Throttle_1 = require("./Throttle");
+Object.defineProperty(exports, "Throttle", { enumerable: true, get: function () { return Throttle_1.Throttle; } });
+var WeightedThrottle_1 = require("./WeightedThrottle");
+Object.defineProperty(exports, "WeightedThrottle", { enumerable: true, get: function () { return WeightedThrottle_1.WeightedThrottle; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uCAA4D;AAAnD,oGAAA,QAAQ,OAAA;AACjB,uDAI4B;AAH1B,oHAAA,gBAAgB,OAAA"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hardlydifficult/throttle",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@hardlydifficult/state-tracker": "1.0.0",
+    "@hardlydifficult/date-time": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.31",
+    "typescript": "5.8.3",
+    "vitest": "1.6.1"
+  },
+  "peerDependencies": {
+    "@hardlydifficult/state-tracker": "1.0.0",
+    "@hardlydifficult/date-time": "1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}