@stimulcross/rate-limiter 0.0.1

package/src/index.ts

@@ -0,0 +1,11 @@
+export type { Clock } from './core/clock.js';
+export type { StateStorage } from './core/state-storage.js';
+export type { RateLimiter } from './core/rate-limiter.js';
+export type { LimitBehavior } from './types/limit-behavior.js';
+export type { KeyResolver, RateLimiterOptions } from './interfaces/rate-limiter-options.js';
+export type { RateLimiterQueueOptions } from './interfaces/rate-limiter-queue-options.js';
+export type { RateLimiterRunOptions } from './interfaces/rate-limiter-run-options.js';
+export { type RateLimitErrorPlainObject, RateLimitError } from './errors/rate-limit.error.js';
+export { RateLimiterDestroyedError } from './errors/rate-limiter-destroyed.error.js';
+export { type InvalidCostErrorPlainObject, InvalidCostError } from './errors/invalid-cost.error.js';
+export { RateLimitErrorCode } from './enums/rate-limit-error-code.js';

package/src/interfaces/rate-limiter-options.ts

@@ -0,0 +1,84 @@
+import { type LoggerOptions } from '@stimulcross/logger';
+import { type RateLimiterQueueOptions } from './rate-limiter-queue-options.js';
+import { type Clock } from '../core/clock.js';
+import { type StateStorage } from '../core/state-storage.js';
+import { type LimitBehavior } from '../types/limit-behavior.js';
+
+/**
+ * A function that generates a unique ID for the task.
+ */
+export type IdGenerator = () => string;
+
+/**
+ * A function that resolves a global key for the given key.
+ */
+export type KeyResolver = (key?: string) => string;
+
+/**
+ * Rate limiter options.
+ *
+ * @template TState The type of the rate limiter state.
+ */
+export interface RateLimiterOptions<TState = unknown> {
+	/**
+	 * A custom clock implementation.
+	 */
+	clock?: Clock;
+
+	/**
+	 * An optional key that can be either a string or a key resolver function.
+	 *
+	 * If a string is provided, it will be used as a global prefix for all keys.
+	 *
+	 * If a function is provided, it will be called with the provided key and should return a unique global key.
+	 *
+	 * Useful for distributed stores.
+	 *
+	 * @default limiter
+	 */
+	key?: string | KeyResolver;
+
+	/**
+	 * A custom ID factory function.
+	 *
+	 * It is used to generate unique IDs for each task for logging and debugging purposes.
+	 */
+	idGenerator?: IdGenerator;
+
+	/**
+	 * State storage implementation for persisting rate limiter state.
+	 *
+	 * By default, an in-memory state store is used, which is unique to each process.
+	 * This is suitable for single-instance applications or when rate limiting doesn't need
+	 * to be shared across multiple processes.
+	 *
+	 * For distributed applications, you can implement a custom state store using Redis, Memcached,
+	 * or other distributed storage systems. However, be aware that this introduces network latency
+	 * due to multiple round-trips (typically 3-4 requests with lock acquire/release).
+	 *
+	 * For distributed rate limiting, consider using, for example, Redis with Lua scripts.
+	 * This allows atomic operations and minimizes latency.
+	 */
+	store?: StateStorage<TState>;
+
+	/**
+	 * Defines the behavior when the limit is reached.
+	 *
+	 * Available options:
+	 * - `reject` - rejects the task with `LIMIT_EXCEEDED` error code
+	 * - `enqueue` - enqueues the task
+	 *
+	 * @default 'reject'
+	 */
+	limitBehavior?: LimitBehavior;
+
+	/**
+	 * Logger options.
+	 */
+	loggerOptions?: Omit<LoggerOptions, 'context'>;
+
+	/**
+	 * Queue settings.
+	 */
+	queue?: RateLimiterQueueOptions;
+}

package/src/interfaces/rate-limiter-queue-options.ts

@@ -0,0 +1,45 @@
+import { type SelectionPolicy } from '@stimulcross/ds-policy-priority-queue';
+
+/**
+ * Queue options for rate limiter.
+ *
+ * These options are applied to limiters that support delayed execution.
+ */
+export interface RateLimiterQueueOptions {
+	/**
+	 * Defines the maximum number of tasks that can be executed concurrently.
+	 *
+	 * @default Infinity
+	 */
+	concurrency?: number;
+
+	/**
+	 * Maximum time to wait in the queue (in milliseconds).
+	 *
+	 * If a task is not started within this time, it will be rejected with `EXPIRED` error code.
+	 *
+	 * @default Infinity
+	 */
+	maxWaitMs?: number;
+
+	/**
+	 * Maximum queue size.
+	 *
+	 * When overflowed, new tasks will be rejected immediately.
+	 *
+	 * @default Infinity
+	 */
+	capacity?: number;
+
+	/**
+	 * Selection policy for the priority queue.
+	 *
+	 * Defaults to Weighted round-robin (WRR) with the following weights:
+	 * - `Priority.Lowest` - 1
+	 * - `Priority.Low` - 2
+	 * - `Priority.Normal` - 4
+	 * - `Priority.High` - 8
+	 * - `Priority.Highest` - 16
+	 */
+	selectionPolicy?: SelectionPolicy;
+}

package/src/interfaces/rate-limiter-run-options.ts

@@ -0,0 +1,58 @@
+import { type Priority } from '@stimulcross/ds-policy-priority-queue';
+import { type LimitBehavior } from '../types/limit-behavior.js';
+
+/**
+ * Options for running a single task.
+ */
+export interface RateLimiterRunOptions {
+	/**
+	 * A unique identifier for the task for logging and debugging.
+	 *
+	 * If not provided, the library will generate a unique ID.
+	 */
+	id?: string;
+
+	/**
+	 * A storage key for the task.
+	 */
+	key?: string;
+
+	/**
+	 * The cost to consume the limit.
+	 *
+	 * @default 1
+	 */
+	cost?: number;
+
+	/**
+	 * Defines the behavior when the limit is reached for the current task. Overrides the global limit behavior
+	 * set in {@link RateLimiterOptions.limitBehavior}.
+	 *
+	 * - `reject` - rejects the task with `LIMIT_EXCEEDED` error code
+	 * - `enqueue` - enqueues the task if possible
+	 *
+	 * Defaults to global {@link RateLimiterOptions.limitBehavior}
+	 */
+	limitBehavior?: LimitBehavior;
+
+	/**
+	 * Task priority.
+	 *
+	 * @default Priority.Normal (3)
+	 */
+	priority?: Priority;
+
+	/**
+	 * An abort signal to abort the task execution.
+	 */
+	signal?: AbortSignal;
+
+	/**
+	 * Maximum wait time in milliseconds for the task in the queue.
+	 *
+	 * This does not affect execution time.
+	 *
+	 * @default Infinity
+	 */
+	maxWaitMs?: number;
+}

package/src/limiters/abstract-rate-limiter.ts

@@ -0,0 +1,206 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+import { createLogger, type Logger, LogLevel } from '@stimulcross/logger';
+import { type Clock } from '../core/clock.js';
+import { type RateLimitPolicy } from '../core/rate-limit-policy.js';
+import { type RateLimiterStatus } from '../core/rate-limiter-status.js';
+import { type RateLimiter } from '../core/rate-limiter.js';
+import { type StateStorage } from '../core/state-storage.js';
+import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../errors/rate-limit.error.js';
+import { RateLimiterDestroyedError } from '../errors/rate-limiter-destroyed.error.js';
+import { type IdGenerator, type KeyResolver, type RateLimiterOptions } from '../interfaces/rate-limiter-options.js';
+import { type RateLimiterRunOptions } from '../interfaces/rate-limiter-run-options.js';
+import { defaultClock } from '../runtime/default-clock.js';
+import { InMemoryStateStore } from '../runtime/in-memory-state-store.js';
+import { RateLimiterExecutor } from '../runtime/rate-limiter.executor.js';
+import { type LimitBehavior } from '../types/limit-behavior.js';
+import { generateRandomString } from '../utils/generate-random-string.js';
+
+const DEFAULT_KEY_PREFIX = 'limiter';
+
+/** @internal */
+export interface ExecutionContext {
+	readonly id: string;
+	readonly key: string;
+	readonly cost: number;
+	readonly limitBehavior?: LimitBehavior;
+	readonly priority?: Priority;
+	readonly signal?: AbortSignal;
+	readonly maxWaitMs?: number;
+}
+
+/** @internal */
+export abstract class AbstractRateLimiter<
+	TState extends object,
+	TStatus extends RateLimiterStatus | RateLimiterStatus[],
+	TResult = unknown,
+> implements RateLimiter<TStatus> {
+	protected readonly _logger: Logger;
+	protected readonly _clock: Clock;
+	protected readonly _store: StateStorage<TState>;
+	protected readonly _executor: RateLimiterExecutor;
+	protected readonly _getStoreKey: KeyResolver;
+	protected readonly _generateId: IdGenerator;
+
+	private _isDestroyed = false;
+
+	protected abstract readonly _policy: RateLimitPolicy<TState, TStatus>;
+
+	protected constructor(options?: RateLimiterOptions<TState>) {
+		this._logger = createLogger(new.target.name, { minLevel: 'WARNING', ...options?.loggerOptions });
+		this._clock = options?.clock ?? defaultClock;
+		this._store = options?.store ?? new InMemoryStateStore<TState>(this._clock);
+		this._executor = new RateLimiterExecutor(this._logger, this._clock, options?.queue);
+
+		this._getStoreKey =
+			options?.key && typeof options.key === 'function'
+				? options.key
+				: (key?: string): string => (key ? `${DEFAULT_KEY_PREFIX}:${key}` : DEFAULT_KEY_PREFIX);
+
+		this._generateId = options?.idGenerator ?? generateRandomString;
+	}
+
+	public async run<T = TResult>(fn: () => T | Promise<T>, options: RateLimiterRunOptions = {}): Promise<T> {
+		const ctx: ExecutionContext = {
+			id: options.id ?? this._generateId(),
+			key: this._getStoreKey(options.key),
+			cost: options.cost ?? 1,
+			limitBehavior: options.limitBehavior,
+			priority: options.priority,
+			signal: options.signal,
+			maxWaitMs: options.maxWaitMs,
+		};
+
+		await this._ensureCanExecute(ctx);
+
+		return await this._runInternal<T>(fn, ctx);
+	}
+
+	public async getStatus(key?: string): Promise<TStatus> {
+		const now = this._clock.now();
+		const state = await this._store.get(this._getStoreKey(key));
+
+		return this._policy.getStatus(state ?? this._policy.getInitialState(now), now);
+	}
+
+	public async clear(key?: string): Promise<void> {
+		this._executor.clear();
+		const storeKey = this._getStoreKey(key);
+
+		this._shouldPrintDebug && this._logger.debug(`[CLR] [key: ${storeKey}]`);
+
+		await this._store.acquireLock?.(storeKey);
+
+		try {
+			await this._store.delete(storeKey);
+		} finally {
+			await this._store.releaseLock?.(storeKey);
+		}
+	}
+
+	public async destroy(): Promise<void> {
+		if (this._isDestroyed) {
+			return;
+		}
+
+		this._shouldPrintDebug && this._logger.debug('[KILL] Destroying limiter');
+
+		this._isDestroyed = true;
+
+		this._executor.clear();
+		await this._store.destroy?.();
+	}
+
+	protected get _shouldPrintDebug(): boolean {
+		return this._logger.minLevel >= LogLevel.DEBUG;
+	}
+
+	protected abstract _runInternal<T = TResult>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T>;
+
+	protected async _execute<T = TResult>(
+		fn: () => T | Promise<T>,
+		runAt: number,
+		storeTtlMs: number,
+		ctx: ExecutionContext,
+		expiresAt?: number,
+	): Promise<T> {
+		await this._ensureCanExecute(ctx);
+
+		try {
+			return await this._executor.execute<T>(fn, runAt, {
+				id: ctx.id,
+				key: ctx.key,
+				priority: ctx.priority,
+				signal: ctx.signal,
+				expiresAt,
+			});
+		} catch (e) {
+			if (this._shouldRevert(e)) {
+				await this._store.acquireLock?.(ctx.key);
+
+				try {
+					const currentState = await this._store.get(ctx.key);
+
+					if (currentState) {
+						const revertedState = this._policy.revert(currentState, ctx.cost, this._clock.now());
+						await this._store.set(ctx.key, revertedState, storeTtlMs);
+
+						this._shouldPrintDebug &&
+							this._logger.debug(
+								`[RVRT] [id: ${ctx.id}, key: ${ctx.key}, cost: ${ctx.cost}] - ${this._getDebugStateString(revertedState)}`,
+							);
+					}
+				} catch (e_) {
+					this._logger.error(`[ERR] [id: ${ctx.id}, key: ${ctx.key}, cost: ${ctx.cost}] - Revert failed`, e_);
+				} finally {
+					await this._store.releaseLock?.(ctx.key);
+				}
+			}
+
+			throw e;
+		}
+	}
+
+	protected abstract _getDebugStateString(state: TState): string;
+
+	protected _shouldRevert(e: unknown): boolean {
+		return e instanceof RateLimitError && e.code !== RateLimitErrorCode.LimitExceeded;
+	}
+
+	private async _ensureCanExecute(ctx: ExecutionContext): Promise<void> {
+		if (this._executor.isQueueFull) {
+			this._shouldPrintDebug &&
+				this._logger.debug(
+					`[DROP OVERFLOW] [id: ${ctx.id}, key: ${ctx.key}] - prt: ${ctx.priority ?? Priority.Normal} | q: ${this._executor.queueSize}/${this._executor.queueCapacity}`,
+				);
+
+			let retryAt: number | undefined;
+			const state = await this._store.get(this._getStoreKey());
+
+			if (state) {
+				const status = this._policy.getStatus(state, this._clock.now());
+				retryAt = Array.isArray(status)
+					? Math.min(...status.map(s => s.nextAvailableAt))
+					: status.nextAvailableAt;
+			}
+
+			throw new RateLimitError(RateLimitErrorCode.QueueOverflow, retryAt);
+		}
+
+		if (ctx.signal?.aborted) {
+			this._logger.debug(
+				`[DROP CANCELLED] [id: ${ctx.id}, key: ${ctx.key}] - prt: ${ctx.priority} | q: ${this._executor.queueSize}/${this._executor.queueCapacity}`,
+			);
+
+			throw new RateLimitError(RateLimitErrorCode.Cancelled);
+		}
+
+		if (this._isDestroyed) {
+			this._logger.debug(
+				`[DROP DESTROYED] [id: ${ctx.id}, key: ${ctx.key}] - prt: ${ctx.priority ?? Priority.Normal} | q: ${this._executor.queueSize}/${this._executor.queueCapacity}}`,
+			);
+
+			throw new RateLimiterDestroyedError();
+		}
+	}
+}

package/src/limiters/composite.policy.ts

@@ -0,0 +1,102 @@
+import { type DecisionKind } from '../core/decision.js';
+import { type RateLimitPolicy, type RateLimitPolicyResult } from '../core/rate-limit-policy.js';
+import { validateCost } from '../utils/validate-cost.js';
+
+type CompositeState<T> = T[];
+type CompositeInfo<T> = T[];
+
+/** @internal */
+export class CompositePolicy<
+	S extends object = object,
+	I extends object = object,
+	P extends RateLimitPolicy<S, I> = RateLimitPolicy<S, I>,
+> implements RateLimitPolicy<CompositeState<S>, CompositeInfo<I>> {
+	constructor(private readonly _policies: P[]) {}
+
+	public get policies(): P[] {
+		return this._policies;
+	}
+
+	public getInitialState(now: number): CompositeState<S> {
+		return this._policies.map(policy => policy.getInitialState(now));
+	}
+
+	public getStatus(states: CompositeState<S>, now: number): CompositeInfo<I> {
+		const result: CompositeInfo<I> = [];
+
+		for (let i = 0; i < this._policies.length; i++) {
+			const policy = this._policies[i];
+			const state = states[i];
+			const info = policy.getStatus(state, now);
+
+			result.push(info);
+		}
+
+		return result;
+	}
+
+	public evaluate(
+		states: CompositeState<S>,
+		now: number,
+		cost?: number,
+		shouldReserve?: boolean,
+	): RateLimitPolicyResult<CompositeState<S>> {
+		if (cost === undefined) {
+			cost = 1;
+		} else {
+			validateCost(cost);
+		}
+
+		const results: Array<RateLimitPolicyResult<S>> = [];
+
+		let compositeDecision: DecisionKind = 'allow';
+		let maxRetryAt = 0;
+		let maxRunAt = 0;
+
+		for (let i = 0; i < this._policies.length; i++) {
+			const policy = this._policies[i];
+			const state = states[i];
+
+			const result = policy.evaluate(state, now, cost, shouldReserve);
+			results.push(result);
+
+			if (result.decision.kind === 'deny') {
+				compositeDecision = 'deny';
+				maxRetryAt = Math.max(maxRetryAt, result.decision.retryAt);
+			} else if (result.decision.kind === 'delay') {
+				if (compositeDecision !== 'deny') {
+					compositeDecision = 'delay';
+				}
+
+				maxRunAt = Math.max(maxRunAt, result.decision.runAt);
+			}
+		}
+
+		if (compositeDecision === 'deny') {
+			const nextState = results.map((res, i) =>
+				res.decision.kind === 'deny' ? res.nextState : this._policies[i].revert(res.nextState, cost, now),
+			);
+
+			return {
+				decision: { kind: 'deny', retryAt: maxRetryAt },
+				nextState,
+			};
+		}
+
+		if (compositeDecision === 'delay') {
+			return {
+				decision: { kind: 'delay', runAt: maxRunAt },
+				nextState: results.map(res => res.nextState),
+			};
+		}
+
+		return {
+			decision: { kind: 'allow' },
+			nextState: results.map(res => res.nextState),
+		};
+	}
+
+	public revert(states: S[], cost: number, now: number): S[] {
+		return states.map((state, i) => this._policies[i].revert(state, cost, now));
+	}
+}

package/src/limiters/fixed-window/fixed-window.limiter.ts

@@ -0,0 +1,121 @@
+import { LogLevel } from '@stimulcross/logger';
+import { type FixedWindowOptions } from './fixed-window.options.js';
+import { FixedWindowPolicy } from './fixed-window.policy.js';
+import { type FixedWindowState } from './fixed-window.state.js';
+import { type FixedWindowStatus } from './fixed-window.status.js';
+import { type Decision } from '../../core/decision.js';
+import { RateLimitErrorCode } from '../../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../../errors/rate-limit.error.js';
+import { type LimitBehavior } from '../../types/limit-behavior.js';
+import { AbstractRateLimiter, type ExecutionContext } from '../abstract-rate-limiter.js';
+import { CompositePolicy } from '../composite.policy.js';
+
+/**
+ * Fixed Window rate limiter.
+ *
+ * Designed primarily for client-side use to respect third-party limits or protect resources.
+ * While this can be used as a server-side limiter with custom distributed storage
+ * (e.g., Redis), it is best-effort and not recommended due to high network round-trip latency.
+ *
+ * Key features:
+ * - **Composite limits** - supports multiple windows simultaneously (e.g., 10 per second AND 1000 per hour)
+ * - **Queueing & overflow** - optionally enqueues excess requests up to a maximum allowed overflow capacity
+ * - **Concurrency** - limits how many requests can be executed simultaneously
+ * - **Priority** - supports task priorities (with fairness and custom policy) to execute critical requests first
+ * - **Cancellation** - supports `AbortSignal` to safely remove pending requests from the queue
+ * - **Expiration** - automatically drops queued requests that wait longer than the allowed `maxWaitMs`
+ * - **Auto-rollback** - reverts spent quota if an enqueued task is canceled or expired
+ */
+export class FixedWindowLimiter extends AbstractRateLimiter<FixedWindowState[], FixedWindowStatus[]> {
+	private readonly _defaultLimitBehaviour: LimitBehavior;
+	private readonly _defaultMaxWaitMs: number | undefined;
+	private readonly _maxWindowSizeMs: number;
+
+	protected override readonly _policy: CompositePolicy<FixedWindowState, FixedWindowStatus, FixedWindowPolicy>;
+
+	constructor(options: FixedWindowOptions) {
+		super(options);
+
+		this._defaultLimitBehaviour = options.limitBehavior ?? 'reject';
+
+		if (options.queue?.maxWaitMs) {
+			this._defaultMaxWaitMs = options.queue.maxWaitMs;
+		}
+
+		this._policy = new CompositePolicy(
+			Array.isArray(options.limitOptions)
+				? options.limitOptions.map(({ limit, windowMs }) => new FixedWindowPolicy(limit, windowMs))
+				: [new FixedWindowPolicy(options.limitOptions.limit, options.limitOptions.windowMs)],
+		);
+
+		this._maxWindowSizeMs = Math.max(...this._policy.policies.map(policy => policy.windowMs));
+	}
+
+	protected override async _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T> {
+		const now = this._clock.now();
+
+		let runAt: number;
+		let storeTtlMs: number;
+
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const state = (await this._store.get(ctx.key)) ?? this._policy.getInitialState(this._clock.now());
+			const finalLimitBehavior = ctx.limitBehavior ?? this._defaultLimitBehaviour;
+
+			const { decision, nextState } = this._policy.evaluate(
+				state,
+				now,
+				ctx.cost,
+				finalLimitBehavior === 'enqueue',
+			);
+
+			if (decision.kind === 'deny') {
+				this._logger.debug(`[DENY] [id: ${ctx.id}, key: ${ctx.key}] - Retry: +${decision.retryAt - now}ms`);
+				throw new RateLimitError(RateLimitErrorCode.LimitExceeded, decision.retryAt);
+			}
+
+			runAt = decision.kind === 'delay' ? decision.runAt : now;
+			storeTtlMs = Math.max(this._maxWindowSizeMs, runAt - now + this._maxWindowSizeMs);
+
+			await this._store.set(ctx.key, nextState, storeTtlMs);
+
+			this._printDebug(decision, nextState, now, ctx);
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+
+		const finalMaxWaitMs = ctx.maxWaitMs ?? this._defaultMaxWaitMs;
+		const expiresAt = finalMaxWaitMs ? now + finalMaxWaitMs : undefined;
+
+		return await this._execute(fn, runAt, storeTtlMs, ctx, expiresAt);
+	}
+
+	protected override _getDebugStateString(state: FixedWindowState[]): string {
+		const result: string[] = [];
+
+		for (const [i, { used, reserved }] of state.entries()) {
+			const { windowMs, limit } = this._policy.policies[i];
+
+			result.push(`w/l: ${windowMs}/${limit}; u/r: ${used}/${reserved}`);
+		}
+
+		return result.join(', ');
+	}
+
+	private _printDebug(decision: Decision, nextState: FixedWindowState[], now: number, ctx: ExecutionContext): void {
+		if (this._logger.minLevel < LogLevel.DEBUG) {
+			return;
+		}
+
+		const debugStateString = this._getDebugStateString(nextState);
+
+		if (decision.kind === 'delay') {
+			this._logger.debug(
+				`[DELAY] [id: ${ctx.id}, key: ${ctx.key}] +${decision.runAt - now}ms - ${debugStateString}`,
+			);
+		} else {
+			this._logger.debug(`[ALLOW] [id: ${ctx.id}, key: ${ctx.key}] - ${debugStateString}`);
+		}
+	}
+}

package/src/limiters/fixed-window/fixed-window.options.ts

@@ -0,0 +1,29 @@
+import { type FixedWindowState } from './fixed-window.state.js';
+import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
+
+/**
+ * Fixed Window limit options.
+ */
+export interface FixedWindowLimitOptions {
+	/**
+	 * Maximum number of requests allowed within the time window.
+	 */
+	limit: number;
+
+	/**
+	 * Duration of the time window in milliseconds.
+	 */
+	windowMs: number;
+}
+
+/**
+ * Options for the Fixed Window rate limiter.
+ */
+export interface FixedWindowOptions extends RateLimiterOptions<FixedWindowState[]> {
+	/**
+	 * Options time window.
+	 *
+	 * Can be a single object or an array of objects for composite time windows.
+	 */
+	limitOptions: FixedWindowLimitOptions | FixedWindowLimitOptions[];
+}