@stimulcross/rate-limiter 0.0.1

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

@@ -0,0 +1,159 @@
+import { type FixedWindowState } from './fixed-window.state.js';
+import { type FixedWindowStatus } from './fixed-window.status.js';
+import { type RateLimitPolicy, type RateLimitPolicyResult } from '../../core/rate-limit-policy.js';
+import { validateCost } from '../../utils/validate-cost.js';
+
+/** @internal */
+export class FixedWindowPolicy implements RateLimitPolicy<FixedWindowState, FixedWindowStatus> {
+	constructor(
+		private readonly _limit: number,
+		private readonly _windowMs: number,
+		private readonly _maxReserved: number = Number.POSITIVE_INFINITY,
+	) {
+		if (!Number.isSafeInteger(_limit) || _limit <= 0) {
+			throw new Error(`Invalid limit: ${_limit}. Must be a positive integer.`);
+		}
+
+		if (!Number.isSafeInteger(_windowMs) || _windowMs <= 0) {
+			throw new Error(`Invalid windowMs: ${_windowMs}. Must be a positive integer.`);
+		}
+
+		if (_maxReserved < 0 || (_maxReserved !== Number.POSITIVE_INFINITY && !Number.isSafeInteger(_maxReserved))) {
+			throw new Error(`Invalid maxReserved: ${_maxReserved}. Must be a positive integer or Infinity.`);
+		}
+	}
+
+	public get limit(): number {
+		return this._limit;
+	}
+
+	public get windowMs(): number {
+		return this._windowMs;
+	}
+
+	public getInitialState(): FixedWindowState {
+		return { windowStart: 0, used: 0, reserved: 0 };
+	}
+
+	public getStatus(state: FixedWindowState, now: number): FixedWindowStatus {
+		const { windowStart, used, reserved } = this._syncState(state, now);
+		const windowEnd = windowStart + this._windowMs;
+
+		let nextAvailableAt: number;
+
+		if (used < this._limit) {
+			nextAvailableAt = windowStart;
+		} else {
+			const blockedWindows = Math.floor((used + reserved) / this._limit);
+			nextAvailableAt = windowStart + blockedWindows * this._windowMs;
+		}
+
+		const windowsToClear = Math.ceil((used + reserved) / this._limit);
+		const resetAt = windowStart + Math.max(1, windowsToClear) * this._windowMs;
+
+		return {
+			windowStart,
+			windowEnd,
+			limit: this._limit,
+			used,
+			reserved,
+			remaining: Math.max(0, this._limit - used),
+			nextAvailableAt,
+			resetAt,
+		};
+	}
+
+	public evaluate(
+		state: FixedWindowState,
+		now: number,
+		cost: number,
+		shouldReserve?: boolean,
+	): RateLimitPolicyResult<FixedWindowState> {
+		validateCost(cost, this._limit);
+
+		const { windowStart, used, reserved } = this._syncState(state, now);
+		const currentTotal = used + cost;
+
+		if (reserved === 0 && currentTotal <= this._limit) {
+			return {
+				decision: { kind: 'allow' },
+				nextState: { windowStart, used: currentTotal, reserved: 0 },
+			};
+		}
+
+		if (shouldReserve) {
+			if (reserved + cost > this._maxReserved) {
+				const deficit = reserved + cost - this._maxReserved;
+				const windowsToWait = Math.ceil(deficit / this._limit);
+				const retryAt = windowStart + Math.max(1, windowsToWait) * this._windowMs;
+
+				return this._deny(windowStart, used, reserved, retryAt);
+			}
+
+			const totalItems = used + reserved + cost;
+			const windowIndex = Math.floor((totalItems - 1) / this._limit);
+			const runAt = windowStart + windowIndex * this._windowMs;
+
+			return {
+				decision: { kind: 'delay', runAt },
+				nextState: {
+					windowStart,
+					used,
+					reserved: reserved + cost,
+				},
+			};
+		}
+
+		const windowsToWait = Math.ceil((used + reserved + cost - this._limit) / this._limit);
+		const retryAt = windowStart + Math.max(1, windowsToWait) * this._windowMs;
+
+		return this._deny(windowStart, used, reserved, retryAt);
+	}
+
+	public revert(state: FixedWindowState, cost: number, now: number): FixedWindowState {
+		let { used, reserved, windowStart } = this._syncState(state, now);
+
+		if (reserved >= cost) {
+			reserved -= cost;
+		} else {
+			const remainder = cost - reserved;
+			reserved = 0;
+			used = Math.max(0, used - remainder);
+		}
+
+		return { windowStart, used, reserved };
+	}
+
+	private _deny(
+		start: number,
+		used: number,
+		reserved: number,
+		retryAt: number,
+	): RateLimitPolicyResult<FixedWindowState> {
+		return {
+			decision: { kind: 'deny', retryAt },
+			nextState: { windowStart: start, used, reserved },
+		};
+	}
+
+	private _syncState(state: FixedWindowState, now: number): FixedWindowState {
+		const currentWindowStart = Math.max(Math.floor(now / this._windowMs) * this._windowMs, state.windowStart);
+
+		if (currentWindowStart <= state.windowStart) {
+			return state;
+		}
+
+		let { reserved } = state;
+		const windowsPassed = Math.floor((currentWindowStart - state.windowStart) / this._windowMs);
+		const burnableWindows = windowsPassed - 1;
+
+		if (burnableWindows > 0 && reserved > 0) {
+			reserved = Math.max(0, reserved - burnableWindows * this._limit);
+		}
+
+		const used = Math.min(reserved, this._limit);
+		reserved = Math.max(0, reserved - used);
+
+		return { windowStart: currentWindowStart, used, reserved };
+	}
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Fixed Window rate limiter state.
+ *
+ * When using a distributed state store, make sure it properly serializes and deserializes the state.
+ */
+export interface FixedWindowState {
+	windowStart: number;
+	used: number;
+	reserved: number;
+}

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

@@ -0,0 +1,46 @@
+import { type RateLimiterStatus } from '../../core/rate-limiter-status.js';
+
+/**
+ * The status of the Fixed Window Limiter.
+ */
+export interface FixedWindowStatus extends RateLimiterStatus {
+	/**
+	 * The start of the current window.
+	 */
+	readonly windowStart: number;
+
+	/**
+	 * The end of the current window.
+	 */
+	readonly windowEnd: number;
+
+	/**
+	 * The maximum number of tokens can be used in the window.
+	 */
+	readonly limit: number;
+
+	/**
+	 * The number of tokens that have been used in the current window.
+	 */
+	readonly used: number;
+
+	/**
+	 * The number of tokens that are reserved for future windows.
+	 */
+	readonly reserved: number;
+
+	/**
+	 * The number of tokens that can be used in the current window.
+	 */
+	readonly remaining: number;
+
+	/**
+	 * The timestamp (in milliseconds) when the next token will be available for use.
+	 */
+	readonly nextAvailableAt: number;
+
+	/**
+	 * The timestamp (in milliseconds) when the limit will be reset (all tokens will be available for use again).
+	 */
+	readonly resetAt: number;
+}

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

@@ -0,0 +1,4 @@
+export type { FixedWindowState } from './fixed-window.state.js';
+export type { FixedWindowStatus } from './fixed-window.status.js';
+export type { FixedWindowLimitOptions, FixedWindowOptions } from './fixed-window.options.js';
+export { FixedWindowLimiter } from './fixed-window.limiter.js';

package/src/limiters/generic-cell/generic-cell.limiter.ts

@@ -0,0 +1,108 @@
+import { LogLevel } from '@stimulcross/logger';
+import { GenericCellPolicy } from './generic-cell.policy.js';
+import { AbstractRateLimiter, type ExecutionContext } from '../abstract-rate-limiter.js';
+import { type GenericCellOptions } from './generic-cell.options.js';
+import { type GenericCellState } from './generic-cell.state.js';
+import { type GenericCellStatus } from './generic-cell.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';
+
+/**
+ * Generic Cell (GCRA) 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:
+ * - **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 GenericCellLimiter extends AbstractRateLimiter<GenericCellState, GenericCellStatus> {
+	private readonly _defaultLimitBehaviour: LimitBehavior;
+	private readonly _defaultMaxWaitMs: number | undefined;
+
+	protected override readonly _policy: GenericCellPolicy;
+
+	constructor(options: GenericCellOptions) {
+		super(options);
+
+		this._defaultLimitBehaviour = options.limitBehavior ?? 'reject';
+
+		if (options.queue?.maxWaitMs) {
+			this._defaultMaxWaitMs = options.queue.maxWaitMs;
+		}
+
+		this._policy = new GenericCellPolicy(options.intervalMs, options.burst);
+	}
+
+	protected override async _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T> {
+		const now = this._clock.now();
+		const baseTtlMs: number = Math.ceil(this._policy.burst * this._policy.intervalMs);
+
+		let runAt: number;
+		let storeTtlMs: number;
+
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const state = (await this._store.get(ctx.key)) ?? this._policy.getInitialState();
+			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(baseTtlMs, runAt - now + baseTtlMs);
+
+			await this._store.set(ctx.key, nextState, storeTtlMs);
+
+			this._printSuccessDebug(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<T>(fn, runAt, storeTtlMs, ctx, expiresAt);
+	}
+
+	protected override _getDebugStateString(state: GenericCellState): string {
+		return String(state.tat);
+	}
+
+	private _printSuccessDebug(
+		decision: Decision,
+		nextState: GenericCellState,
+		now: number,
+		ctx: ExecutionContext,
+	): void {
+		if (this._logger.minLevel < LogLevel.DEBUG) {
+			return;
+		}
+
+		if (decision.kind === 'delay') {
+			this._logger.debug(
+				`[DELAY] [id: ${ctx.id}, key: ${ctx.key}] +${decision.runAt - now}ms - tat: ${nextState.tat}`,
+			);
+		} else {
+			this._logger.debug(`[ALLOW] [id: ${ctx.id}, key: ${ctx.key}] - tat: ${nextState.tat}`);
+		}
+	}
+}

package/src/limiters/generic-cell/generic-cell.options.ts

@@ -0,0 +1,23 @@
+import { type GenericCellState } from './generic-cell.state.js';
+import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
+
+/**
+ * Options for the Generic Cell Rate Algorithm (GCRA) limiter.
+ */
+export interface GenericCellOptions extends RateLimiterOptions<GenericCellState> {
+	/**
+	 * The minimum interval between requests (in milliseconds).
+	 *
+	 * This defines the emission interval.
+	 * For example, if you want to allow 10 requests per second, set this to 100ms (1000ms / 10).
+	 */
+	intervalMs: number;
+
+	/**
+	 * The maximum burst size.
+	 *
+	 * This defines how many requests can be made immediately in quick succession before rate limiting kicks in.
+	 * The burst capacity allows temporary spikes in traffic.
+	 */
+	burst: number;
+}

package/src/limiters/generic-cell/generic-cell.policy.ts

@@ -0,0 +1,115 @@
+import { type GenericCellState } from './generic-cell.state.js';
+import { type GenericCellStatus } from './generic-cell.status.js';
+import { type RateLimitPolicy, type RateLimitPolicyResult } from '../../core/rate-limit-policy.js';
+import { validateCost } from '../../utils/validate-cost.js';
+
+/** @internal */
+export class GenericCellPolicy implements RateLimitPolicy<GenericCellState, GenericCellStatus> {
+	constructor(
+		private readonly _intervalMs: number,
+		private readonly _burst: number,
+		private readonly _maxDelayMs: number = Number.POSITIVE_INFINITY,
+	) {
+		if (!Number.isFinite(_intervalMs) || !Number.isSafeInteger(_intervalMs) || _intervalMs <= 0) {
+			throw new Error(`Invalid intervalMs: ${_intervalMs}. Must be a positive integer.`);
+		}
+
+		if (!Number.isFinite(_burst) || !Number.isSafeInteger(_burst) || _burst <= 0) {
+			throw new Error(`Invalid burst: ${_burst}. Must be a positive integer.`);
+		}
+
+		if (_maxDelayMs < 0 || (!Number.isSafeInteger(_maxDelayMs) && _maxDelayMs !== Number.POSITIVE_INFINITY)) {
+			throw new Error(`Invalid maxDelayMs: ${_maxDelayMs}. Must be a non-negative integer or Infinity.`);
+		}
+	}
+
+	public get burst(): number {
+		return this._burst;
+	}
+
+	public get intervalMs(): number {
+		return this._intervalMs;
+	}
+
+	public getInitialState(): GenericCellState {
+		return { tat: 0 };
+	}
+
+	public getStatus(state: GenericCellState, now: number): GenericCellStatus {
+		const tat = Math.max(state.tat, now);
+		const burstOffset = this._burst * this._intervalMs;
+
+		const availableTimeDebt = burstOffset + now - tat;
+		const remaining = Math.max(0, Math.floor(availableTimeDebt / this._intervalMs));
+
+		const nextAvailableAt = Math.max(now, tat + this._intervalMs - burstOffset);
+
+		const resetAt = tat;
+
+		return {
+			intervalMs: this._intervalMs,
+			burst: this._burst,
+			tat,
+			remaining,
+			nextAvailableAt,
+			resetAt,
+		};
+	}
+
+	public evaluate(
+		state: GenericCellState,
+		now: number,
+		cost: number,
+		shouldReserve?: boolean,
+	): RateLimitPolicyResult<GenericCellState> {
+		const absoluteMax = shouldReserve ? this._burst + Math.floor(this._maxDelayMs / this._intervalMs) : this._burst;
+
+		validateCost(cost, absoluteMax);
+
+		const tat = Math.max(state.tat, now);
+		const costInterval = cost * this._intervalMs;
+		const burstOffset = this._burst * this._intervalMs;
+
+		const newTat = tat + costInterval;
+
+		const minNow = newTat - burstOffset;
+
+		if (now >= minNow) {
+			return {
+				decision: { kind: 'allow' },
+				nextState: { tat: newTat },
+			};
+		}
+
+		if (shouldReserve) {
+			const waitMs = minNow - now;
+
+			if (waitMs > this._maxDelayMs) {
+				const retryAt = minNow - this._maxDelayMs;
+				return this._deny(state.tat, retryAt);
+			}
+
+			const runAt = minNow;
+			return {
+				decision: { kind: 'delay', runAt },
+				nextState: { tat: newTat },
+			};
+		}
+
+		return this._deny(state.tat, minNow);
+	}
+
+	public revert(state: GenericCellState, cost: number): GenericCellState {
+		const costInterval = cost * this._intervalMs;
+		return {
+			tat: Math.max(0, state.tat - costInterval),
+		};
+	}
+
+	private _deny(tat: number, retryAt: number): RateLimitPolicyResult<GenericCellState> {
+		return {
+			decision: { kind: 'deny', retryAt },
+			nextState: { tat },
+		};
+	}
+}

package/src/limiters/generic-cell/generic-cell.state.ts

@@ -0,0 +1,8 @@
+/**
+ * Generic Cell rate limiter state.
+ *
+ * When using a distributed state store, make sure it properly serializes and deserializes the state.
+ */
+export interface GenericCellState {
+	tat: number;
+}

package/src/limiters/generic-cell/generic-cell.status.ts

@@ -0,0 +1,54 @@
+import { type RateLimiterStatus } from '../../core/rate-limiter-status.js';
+
+/**
+ * The status of the Generic Cell rate limiter.
+ */
+export interface GenericCellStatus extends RateLimiterStatus {
+	/**
+	 * The minimum interval between tokens (in milliseconds).
+	 *
+	 * It represents the emission interval - the time period between
+	 * successive token emissions at the steady-state rate.
+	 */
+	readonly intervalMs: number;
+
+	/**
+	 * The maximum burst size (maximum number of tokens that can be accumulated).
+	 *
+	 * It represents the burst capacity - the maximum number of requests
+	 * that can be made instantaneously when the bucket is full.
+	 */
+	readonly burst: number;
+
+	/**
+	 * Theoretical Arrival Time (TAT) - the virtual time when the bucket will be empty.
+	 *
+	 * TAT represents the earliest time at which a future request could be allowed.
+	 *
+	 * Value is in milliseconds.
+	 */
+	readonly tat: number;
+
+	/**
+	 * The number of tokens that can be used immediately.
+	 *
+	 * Calculated as the time allowance available between now and TAT, divided by
+	 * the emission interval.
+	 */
+	readonly remaining: number;
+
+	/**
+	 * The timestamp (in milliseconds) when the next token will be available for use.
+	 *
+	 * This is the earliest time when a request can be accepted if no tokens are currently available.
+	 */
+	readonly nextAvailableAt: number;
+
+	/**
+	 * The timestamp when all tokens will be available for use again.
+	 *
+	 * It is when the TAT returns to the current time, meaning the bucket has fully recovered to its
+	 * maximum burst capacity.
+	 */
+	readonly resetAt: number;
+}

package/src/limiters/generic-cell/index.ts

@@ -0,0 +1,4 @@
+export type { GenericCellState } from './generic-cell.state.js';
+export type { GenericCellStatus } from './generic-cell.status.js';
+export type { GenericCellOptions } from './generic-cell.options.js';
+export { GenericCellLimiter } from './generic-cell.limiter.js';

package/src/limiters/http-response-based/http-limit-info.extractor.ts

@@ -0,0 +1,20 @@
+import { type HttpLimitInfo } from './http-limit.info.js';
+
+/**
+ * A function that extracts limit information from response headers.
+ *
+ * @param res The response object, for example, native `Response` object from the `fetch` API.
+ * @param err The error object, if any.
+ * @param now The current timestamp in milliseconds gotten from the internal clock.
+ *            If you need the current timestamp, prefer this value over `Date.now()`.
+ *
+ * @returns {@link HttpLimitInfo} or `null` if not possible to extract or no limit info.
+ *
+ * @template TResponse The type of the response object.
+ * @template TError The type of the error object.
+ */
+export type HttpLimitInfoExtractor<TResponse, TError extends Error = Error> = (
+	res: TResponse | null,
+	err: TError | null,
+	now: number,
+) => HttpLimitInfo | null;

package/src/limiters/http-response-based/http-limit.info.ts

@@ -0,0 +1,41 @@
+/**
+ * Rate limit information extracted from the HTTP response headers.
+ */
+export interface HttpLimitInfo {
+	/**
+	 * The maximum number of requests allowed within the time window.
+	 *
+	 * It usually corresponds to `RateLimit-Limit` or `X-RateLimit-Limit` headers.
+	 */
+	limit: number;
+
+	/**
+	 * The number of requests remaining in the current time window.
+	 *
+	 * It usually corresponds to `RateLimit-Remaining` or `X-RateLimit-Remaining` headers.
+	 */
+	remaining: number;
+
+	/**
+	 * The timestamp (in milliseconds) when the current time window resets.
+	 *
+	 * It usually corresponds to `RateLimit-Reset`, `X-RateLimit-Reset`, or `Retry-After` headers.
+	 *
+	 * **WARNING:** these headers can be either delta (usually in seconds) or UNIX epoche
+	 * timestamp (usually in seconds) depending on the target API specs.
+	 *
+	 *The library expects a UNIX epoche timestamp in milliseconds. Refer to the API docs to
+	 * determine the header format and properly convert it to UNIX epoche timestamp in milliseconds.
+	 *
+	 * For example,
+	 *   - delta in seconds: `Date.now() + delta * 1000`
+	 *   - UNIX timestamp in seconds: `timestamp * 1000`
+	 *
+	 */
+	resetAt?: number | null;
+
+	/**
+	 * HTTP status code of the response.
+	 */
+	statusCode: number;
+}

package/src/limiters/http-response-based/http-response-based-limiter.options.ts

@@ -0,0 +1,18 @@
+import { type HttpLimitInfoExtractor } from './http-limit-info.extractor.js';
+import { type HttpResponseBasedLimiterState } from './http-response-based-limiter.state.js';
+import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
+
+/**
+ * Options for the HTTP Response Based rate limiter.
+ */
+export interface HttpResponseBasedLimiterOptions<TResponse> extends RateLimiterOptions<HttpResponseBasedLimiterState> {
+	/**
+	 * Function that extracts limit information from the HTTP response.
+	 */
+	limitInfoExtractor: HttpLimitInfoExtractor<TResponse>;
+
+	/**
+	 * The fallback reset delay in milliseconds.
+	 */
+	fallbackResetDelayMs?: number;
+}

package/src/limiters/http-response-based/http-response-based-limiter.state.ts

@@ -0,0 +1,13 @@
+/**
+ * The state of the HTTP Response Based rate limiter.
+ *
+ * When using a distributed state store, make sure it properly serializes and deserializes the state.
+ */
+export interface HttpResponseBasedLimiterState {
+	isProbing: boolean;
+	isUnlimited: boolean;
+	lastKnownLimit: number | null;
+	lastKnownRemaining: number | null;
+	lastKnownResetAt: number | null;
+	lastSyncedAt: number | null;
+}