@stimulcross/rate-limiter 0.0.1

package/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = tab
+tab_width = 4
+max_line_length = 120
+
+[*.json]
+indent_style = tab
+indent_size = 4
+
+[package.json]
+indent_style = space
+indent_size = 2
+
+[*.yml]
+indent_style = space
+indent_size = 2

package/.github/workflows/node.yml

@@ -0,0 +1,87 @@
+name: Node.js CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        run: pnpm run format:check
+
+      - name: Check types
+        run: pnpm run check-types
+
+      - name: Lint
+        run: pnpm run lint
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [ 20, 22, 24 ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm run test

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint -e $1

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.megaignore

@@ -0,0 +1,8 @@
++sync:.megaignore
+-d:node_modules
+-d:lib
+-f:yarn.lock
+-f:yalc.lock
+-f:package-lock.json
+-f:pnpm-lock.yaml
+

package/.prettierignore

@@ -0,0 +1,3 @@
+docs
+packages/*/lib
+lerna.json

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stimul Cross
+
+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,7 @@
+# Rate Limiters
+
+A collection of rate limiters designed primarily for **outbound request throttling**.
+
+They are suited for client-side usage to respect third-party limits or protect internal resources.
+
+While it is technically possible to use these limiters for server-side traffic backed by a distributed store like Redis, it is **not recommended**. The algorithms evaluate state within the application process, so distributed usage requires multiple network operations per request introducing significant round-trip latency.

package/commitlint.config.js

@@ -0,0 +1,8 @@
+export default {
+	extends: ['@stimulcross/commitlint-config'],
+	rules: {
+		'body-max-line-length': [2, 'always', 500],
+		'footer-max-line-length': [2, 'always', 500],
+	}
+
+};

package/eslint.config.js

@@ -0,0 +1,65 @@
+import { resolveFlatConfig } from '@leancodepl/resolve-eslint-flat-config';
+import typescript from '@stimulcross/eslint-config-typescript';
+import typescriptStyle from '@stimulcross/eslint-config-typescript/style';
+import { defineConfig, globalIgnores } from 'eslint/config';
+import globals from 'globals';
+
+export const globs = {
+	js: ['**/*.js', '**/*.cjs', '**/*.mjs'],
+	ts: ['**/*.ts', '**/*.cts', '**/*.mts'],
+	jsSpec: ['**/*.spec.js', '**/*.spec.cjs', '**/*.spec.mjs'],
+	tsSpec: ['**/*.spec.ts', '**/*.spec.cts', '**/*.spec.mts'],
+	lib: '**/dist',
+	nodeModules: '**/node_modules',
+	coverage: '**/coverage',
+	dts: '**/*.d.ts',
+};
+
+/** @type {import("eslint").Linter.Config[]} */
+export const config = resolveFlatConfig(
+	defineConfig(
+		globalIgnores([globs.lib, globs.nodeModules, globs.dts, globs.coverage]),
+		{
+			files: [...globs.js, ...globs.ts, ...globs.jsSpec, ...globs.tsSpec],
+			languageOptions: {
+				globals: {
+					...globals.node,
+					...globals.es2022,
+				},
+			},
+		},
+		{
+			files: [...globs.js, ...globs.ts, ...globs.tsSpec],
+			extends: [typescript, typescriptStyle],
+		},
+		{
+			files: [...globs.ts, ...globs.tsSpec],
+			rules: {
+				'id-length': 'off',
+				'no-await-in-loop': 'off',
+				'unicorn/no-new-array': 'off',
+				'unicorn/no-thenable': 'off',
+				'unicorn/no-useless-undefined': 'error',
+				'@typescript-eslint/no-explicit-any': 'off',
+				'@typescript-eslint/no-non-null-assertion': 'off',
+				'@typescript-eslint/no-unnecessary-condition': ['warn', { allowConstantLoopConditions: true }],
+			},
+		},
+		{
+			files: [...globs.jsSpec, ...globs.tsSpec],
+			rules: {
+				'id-length': 'off',
+				'max-nested-callbacks': 'off',
+				'unicorn/consistent-function-scoping': 'off',
+				'unicorn/no-array-push-push': 'off',
+				'@typescript-eslint/naming-convention': 'off',
+				'@typescript-eslint/no-empty-function': 'off',
+				'@typescript-eslint/no-unsafe-member-access': 'off',
+				'@typescript-eslint/no-unsafe-return': 'off',
+				'@typescript-eslint/unbound-method': 'off',
+			},
+		},
+	),
+);
+
+export default config;

package/lint-staged.config.js

@@ -0,0 +1,4 @@
+export default {
+	'*.{js,mjs,ts,json,md}': 'prettier --write ',
+	'src/*.{js,ts}': 'eslint src',
+};

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@stimulcross/rate-limiter",
+  "version": "0.0.1",
+  "description": "A collection of client-side rate limiters for Node.js and browsers.",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./fixed-window": {
+      "types": "./lib/limiters/fixed-window/index.d.ts",
+      "default": "./lib/limiters/fixed-window/index.js"
+    },
+    "./sliding-window-counter": {
+      "types": "./lib/limiters/sliding-window-counter/index.d.ts",
+      "default": "./lib/limiters/sliding-window-counter/index.js"
+    },
+    "./sliding-window-log": {
+      "types": "./lib/limiters/sliding-window-log/index.d.ts",
+      "default": "./lib/limiters/sliding-window-log/index.js"
+    },
+    "./token-bucket": {
+      "types": "./lib/limiters/token-bucket/index.d.ts",
+      "default": "./lib/limiters/token-bucket/index.js"
+    },
+    "./leaky-bucket": {
+      "types": "./lib/limiters/leaky-bucket/index.d.ts",
+      "default": "./lib/limiters/leaky-bucket/index.js"
+    },
+    "./generic-cell": {
+      "types": "./lib/limiters/generic-cell/index.d.ts",
+      "default": "./lib/limiters/generic-cell/index.js"
+    },
+    "./http-response-based": {
+      "types": "./lib/limiters/http-response-based/index.d.ts",
+      "default": "./lib/limiters/http-response-based/index.js"
+    }
+  },
+  "dependencies": {
+    "@stimulcross/ds-binary-heap": "^0.1.0",
+    "@stimulcross/ds-deque": "^0.1.0",
+    "@stimulcross/ds-policy-priority-queue": "^0.2.2",
+    "@stimulcross/logger": "^8.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.4",
+    "@leancodepl/resolve-eslint-flat-config": "^9.7.4",
+    "@stimulcross/commitlint-config": "^2.0.0",
+    "@stimulcross/eslint-config-node": "^2.0.0",
+    "@stimulcross/eslint-config-typescript": "^2.0.0",
+    "@stimulcross/prettier-config": "^2.0.0",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "clean": "del-cli lib *.tsbuildinfo",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "format:check": "prettier --config \"prettier.config.cjs\" --check src tests",
+    "format:fix": "prettier --config \"prettier.config.cjs\" --write src tests",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "preversion": "pnpm run format:check && pnpm run lint && pnpm run test && pnpm run rebuild",
+    "postversion": "pnpm i",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "test:watch": "vitest watch",
+    "test:verbose": "vitest --run --reporter verbose --logHeapUsage",
+    "test:watch:cov": "vitest watch --coverage"
+  }
+}

package/prettier.config.cjs

@@ -0,0 +1 @@
+module.exports = require('@stimulcross/prettier-config');

package/src/core/cancellable.ts

@@ -0,0 +1,4 @@
+/** @internal */
+export interface Cancellable {
+	cancel(): void;
+}

package/src/core/clock.ts

@@ -0,0 +1,9 @@
+/**
+ * Clock interface.
+ */
+export interface Clock {
+	/**
+	 * Returns the current timestamp in milliseconds.
+	 */
+	now(): number;
+}

package/src/core/decision.ts

@@ -0,0 +1,27 @@
+/** @internal */
+export type DecisionKind = 'allow' | 'deny' | 'delay';
+
+/** @internal */
+export interface DecisionBase {
+	kind: DecisionKind;
+}
+
+/** @internal */
+export interface DecisionAllow extends DecisionBase {
+	kind: Extract<DecisionKind, 'allow'>;
+}
+
+/** @internal */
+export interface DecisionDeny extends DecisionBase {
+	kind: Extract<DecisionKind, 'deny'>;
+	retryAt: number;
+}
+
+/** @internal */
+export interface DecisionDelay extends DecisionBase {
+	kind: Extract<DecisionKind, 'delay'>;
+	runAt: number;
+}
+
+/** @internal */
+export type Decision = DecisionAllow | DecisionDeny | DecisionDelay;

package/src/core/rate-limit-policy.ts

@@ -0,0 +1,15 @@
+import { type Decision } from './decision.js';
+
+/** @internal */
+export interface RateLimitPolicyResult<S> {
+	decision: Decision;
+	nextState: S;
+}
+
+/** @internal */
+export interface RateLimitPolicy<TState extends object = object, TStatus extends object = object> {
+	getInitialState(now: number): TState;
+	getStatus(state: TState, now: number): TStatus;
+	evaluate(state: TState, now: number, cost: number, shouldReserve?: boolean): RateLimitPolicyResult<TState>;
+	revert(state: TState, cost: number, now: number): TState;
+}

package/src/core/rate-limiter-status.ts

@@ -0,0 +1,14 @@
+/**
+ * The status of the rate limiter.
+ */
+export interface RateLimiterStatus {
+	/**
+	 * The timestamp (in milliseconds) when a rate limiter will allow a single request.
+	 */
+	readonly nextAvailableAt: number;
+
+	/**
+	 * The timestamp (in milliseconds) when the rate limiter will reset.
+	 */
+	readonly resetAt: number;
+}

package/src/core/rate-limiter.ts

@@ -0,0 +1,37 @@
+import { type RateLimiterRunOptions } from '../interfaces/rate-limiter-run-options.js';
+
+/**
+ * Rate limiter interface.
+ *
+ * @template TStatus The type of the rate limiter status returned by {@link getStatus} method.
+ */
+export interface RateLimiter<TStatus extends object = object> {
+	/**
+	 * Runs the given task.
+	 *
+	 * @param task The task to run.
+	 * @param options Options for running the task.
+	 */
+	run<T>(task: () => T | Promise<T>, options?: RateLimiterRunOptions): Promise<T>;
+
+	/**
+	 * Clears the rate limiter state.
+	 *
+	 * @param key The optional key to clear the state for.
+	 */
+	clear(key?: string): Promise<void>;
+
+	/**
+	 * Gets the rate limiter's status.
+	 *
+	 * @param key The optional key to get the status for.
+	 */
+	getStatus?(key?: string): Promise<TStatus>;
+
+	/**
+	 * Destroys the rate limiter.
+	 *
+	 * The limiter cannot be used after it has been destroyed. It should be used only for graceful shutdown.
+	 */
+	destroy?(): Promise<void>;
+}

package/src/core/state-storage.ts

@@ -0,0 +1,51 @@
+/**
+ * State storage interface.
+ */
+export interface StateStorage<TState> {
+	/**
+	 * Gets the state for the given key.
+	 *
+	 * @param key The key to get the state for.
+	 */
+	get(key: string): Promise<TState | null>;
+
+	/**
+	 * Sets the state for the given key.
+	 *
+	 * @param key The key to set the state for.
+	 * @param value The state to set.
+	 * @param ttlMs Optional TTL in milliseconds.
+	 */
+	set(key: string, value: TState, ttlMs?: number): Promise<void>;
+
+	/**
+	 * Deletes the state for the given key.
+	 *
+	 * @param key The key to delete the state for.
+	 */
+	delete(key: string): Promise<void>;
+
+	/**
+	 * Clears all stored states.
+	 */
+	clear(): Promise<void>;
+
+	/**
+	 * Destroys the storage.
+	 */
+	destroy?(): Promise<void>;
+
+	/**
+	 * Acquires a lock for the given key.
+	 *
+	 * @param key The key to acquire the lock for.
+	 */
+	acquireLock?(key: string): Promise<void>;
+
+	/**
+	 * Releases the lock for the given key.
+	 *
+	 * @param key The key to release the lock for.
+	 */
+	releaseLock?(key: string): Promise<void>;
+}

package/src/enums/rate-limit-error-code.ts

@@ -0,0 +1,29 @@
+/**
+ * Rate limiter error codes.
+ */
+export enum RateLimitErrorCode {
+	/**
+	 * Indicates that the limit has been reached.
+	 */
+	LimitExceeded = 'LIMIT_EXCEEDED',
+
+	/**
+	 * Indicates that the execution queue is full.
+	 */
+	QueueOverflow = 'QUEUE_OVERFLOW',
+
+	/**
+	 * Indicates that the task has expired.
+	 */
+	Expired = 'EXPIRED',
+
+	/**
+	 * Indicates that a task was cleared before it was executed.
+	 */
+	Destroyed = 'DESTROYED',
+
+	/**
+	 * Indicates that a task was canceled via abort controller before it was executed.
+	 */
+	Cancelled = 'CANCELLED',
+}

package/src/errors/custom.error.ts

@@ -0,0 +1,14 @@
+/** @internal */
+export abstract class CustomError extends Error {
+	protected constructor(message: string) {
+		super(message);
+
+		Object.setPrototypeOf(this, new.target.prototype);
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+		Error.captureStackTrace?.(this, new.target.constructor);
+	}
+
+	public get name(): string {
+		return this.constructor.name;
+	}
+}

package/src/errors/invalid-cost.error.ts

@@ -0,0 +1,33 @@
+import { CustomError } from './custom.error.js';
+
+export interface InvalidCostErrorPlainObject extends Error {
+	cost: number;
+}
+
+/**
+ * Error thrown when the cost is invalid.
+ *
+ * The cost must be a positive integer or zero.
+ */
+export class InvalidCostError extends CustomError {
+	constructor(
+		message: string,
+		private readonly _cost: number,
+	) {
+		super(message);
+	}
+
+	public get cost(): number {
+		return this._cost;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	public toJSON(): InvalidCostErrorPlainObject {
+		return {
+			name: this.name,
+			message: this.message,
+			cost: this._cost,
+			stack: this.stack,
+		};
+	}
+}

package/src/errors/rate-limit.error.ts

@@ -0,0 +1,91 @@
+import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
+
+export interface RateLimitErrorPlainObject extends Error {
+	code: RateLimitErrorCode;
+	retryAt: number | null;
+}
+
+/**
+ * An error thrown when a rate limit is exceeded.
+ *
+ * This error has a {@link code} property that indicates the type of error.
+ *
+ * The `code` can be:
+ * - `LIMIT_EXCEEDED` - When the rate limit is exceeded.
+ * - `QUEUE_OVERFLOW` - When the queue is full (if the limiter has a queue and the capacity has been exceeded).
+ * - `EXPIRED` - When the task has expired (waited too long in the queue). This is related to the `maxWaitMs` option.
+ *			   **NOTE:** This is never thrown if the task is executing too long. Such scenarios should be handled by the
+ *			   task itself.
+ * - `DESTROYED` - When the task is destroyed due to the rate limiter's `clear()` or `destroy()` methods.
+ * - `CANCELLED` - When the task is cancelled using an abort signal.
+ */
+export class RateLimitError extends Error {
+	private readonly _code: RateLimitErrorCode;
+	private readonly _retryAt: number | null;
+
+	/** @internal */
+	constructor(code: RateLimitErrorCode, retryAt?: number, message?: string) {
+		if (!message) {
+			switch (code) {
+				case RateLimitErrorCode.LimitExceeded: {
+					message = `Rate limit exceeded.${retryAt ? ` Retry at ${new Date(retryAt).toISOString()}.` : ''}`;
+					break;
+				}
+
+				case RateLimitErrorCode.QueueOverflow: {
+					message = 'Queue overflow.';
+					break;
+				}
+
+				case RateLimitErrorCode.Expired: {
+					message = 'Task expired.';
+					break;
+				}
+
+				case RateLimitErrorCode.Destroyed: {
+					message = 'Task destroyed.';
+					break;
+				}
+
+				case RateLimitErrorCode.Cancelled: {
+					message = 'Task cancelled.';
+					break;
+				}
+
+				// No default
+			}
+		}
+
+		super(message);
+
+		this._code = code;
+		this._retryAt = retryAt ?? null;
+	}
+
+	/**
+	 * The error code.
+	 */
+	public get code(): RateLimitErrorCode {
+		return this._code;
+	}
+
+	/**
+	 * The timestamp (in milliseconds) when the task can be retried.
+	 *
+	 * Can be `null` if the retry time is not known.
+	 */
+	public get retryAt(): number | null {
+		return this._retryAt ?? null;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	public toJSON(): RateLimitErrorPlainObject {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this._code,
+			retryAt: this._retryAt,
+			stack: this.stack,
+		};
+	}
+}

package/src/errors/rate-limiter-destroyed.error.ts

@@ -0,0 +1,8 @@
+/**
+ * An error thrown when running a task on a destroyed rate limiter.
+ */
+export class RateLimiterDestroyedError extends Error {
+	constructor() {
+		super('Rate limiter has been destroyed and cannot be used.');
+	}
+}