@stimulcross/rate-limiter 0.0.1

package/src/limiters/sliding-window-log/sliding-window-log.policy.ts

@@ -0,0 +1,166 @@
+import { Deque } from '@stimulcross/ds-deque';
+import { type SlidingWindowLogEntry, type SlidingWindowLogState } from './sliding-window-log.state.js';
+import { type SlidingWindowLogStatus } from './sliding-window-log.status.js';
+import { type RateLimitPolicy, type RateLimitPolicyResult } from '../../core/rate-limit-policy.js';
+import { validateCost } from '../../utils/validate-cost.js';
+
+/** @internal */
+export class SlidingWindowLogPolicy implements RateLimitPolicy<SlidingWindowLogState, SlidingWindowLogStatus> {
+	constructor(
+		private readonly _limit: number,
+		private readonly _windowMs: number,
+	) {
+		if (!Number.isFinite(_limit) || !Number.isInteger(_limit) || _limit <= 0) {
+			throw new Error(`Invalid limit: ${_limit}. Must be a positive integer.`);
+		}
+
+		if (!Number.isFinite(_windowMs) || !Number.isInteger(_windowMs) || _windowMs <= 0) {
+			throw new Error(`Invalid windowMs: ${_windowMs}. Must be a positive integer.`);
+		}
+	}
+
+	public get limit(): number {
+		return this._limit;
+	}
+
+	public get windowMs(): number {
+		return this._windowMs;
+	}
+
+	public getInitialState(): SlidingWindowLogState {
+		return {
+			logs: new Deque<SlidingWindowLogEntry>(),
+			totalUsed: 0,
+		};
+	}
+
+	public getStatus(state: SlidingWindowLogState, now: number): SlidingWindowLogStatus {
+		const syncedState = this._syncState(state, now);
+		const { logs, totalUsed } = syncedState;
+
+		const remaining = Math.max(0, this._limit - totalUsed);
+
+		const nextAvailableAt = this._calculateAvailableAt(logs, totalUsed, 1, now);
+
+		const tail = logs.peekTail();
+		const resetAt = tail ? tail.ts + this._windowMs : now;
+
+		return {
+			limit: this._limit,
+			windowMs: this._windowMs,
+			totalUsed,
+			remaining,
+			nextAvailableAt,
+			resetAt,
+		};
+	}
+
+	public evaluate(
+		state: SlidingWindowLogState,
+		now: number,
+		cost: number,
+	): RateLimitPolicyResult<SlidingWindowLogState> {
+		validateCost(cost, this._limit);
+
+		const syncedState = this._syncState(state, now);
+		const { logs, totalUsed } = syncedState;
+
+		if (totalUsed + cost <= this._limit) {
+			const tail = logs.peekTail();
+
+			if (tail?.ts === now) {
+				tail.count += cost;
+			} else {
+				logs.push({ ts: now, count: cost });
+			}
+
+			return {
+				decision: { kind: 'allow' },
+				nextState: { logs, totalUsed: totalUsed + cost },
+			};
+		}
+
+		const retryAt = this._calculateAvailableAt(logs, totalUsed, cost, now);
+
+		return {
+			decision: { kind: 'deny', retryAt },
+			nextState: syncedState,
+		};
+	}
+
+	public revert(state: SlidingWindowLogState, cost: number, now: number): SlidingWindowLogState {
+		if (cost <= 0 || state.totalUsed === 0) {
+			return state;
+		}
+
+		const syncedState = this._syncState(state, now);
+		const { logs } = syncedState;
+		let { totalUsed } = syncedState;
+
+		let remainingToRemove = cost;
+
+		while (remainingToRemove > 0 && !logs.isEmpty) {
+			const tail = logs.peekTail()!;
+
+			if (tail.count <= remainingToRemove) {
+				remainingToRemove -= tail.count;
+				totalUsed -= tail.count;
+				logs.pop();
+			} else {
+				tail.count -= remainingToRemove;
+				totalUsed -= remainingToRemove;
+				remainingToRemove = 0;
+			}
+		}
+
+		return { logs, totalUsed: Math.max(0, totalUsed) };
+	}
+
+	private _syncState(state: SlidingWindowLogState, now: number): SlidingWindowLogState {
+		const { logs } = state;
+		let { totalUsed } = state;
+		const windowStart = now - this._windowMs;
+
+		while (!logs.isEmpty) {
+			const head = logs.peekHead();
+
+			if (head!.ts > windowStart) {
+				break;
+			}
+
+			const removed = logs.shift();
+
+			if (removed) {
+				totalUsed -= removed.count;
+			}
+		}
+
+		return { logs, totalUsed: Math.max(0, totalUsed) };
+	}
+
+	private _calculateAvailableAt(
+		logs: Deque<SlidingWindowLogEntry>,
+		totalUsed: number,
+		cost: number,
+		now: number,
+	): number {
+		if (totalUsed + cost <= this._limit) {
+			return now;
+		}
+
+		const targetToFree = totalUsed + cost - this._limit;
+		let freed = 0;
+		let availableAt = now;
+
+		for (const entry of logs) {
+			freed += entry.count;
+
+			if (freed >= targetToFree) {
+				availableAt = entry.ts + this._windowMs;
+				break;
+			}
+		}
+
+		return Math.max(now, availableAt);
+	}
+}

package/src/limiters/sliding-window-log/sliding-window-log.state.ts

@@ -0,0 +1,19 @@
+import { type Deque } from '@stimulcross/ds-deque';
+
+/**
+ * A log entry in the sliding window log rate limiter.
+ */
+export interface SlidingWindowLogEntry {
+	ts: number;
+	count: number;
+}
+
+/**
+ * The state of the sliding window log rate limiter.
+ *
+ * When using a distributed state store, make sure it properly serializes and deserializes the state.
+ */
+export interface SlidingWindowLogState {
+	logs: Deque<SlidingWindowLogEntry>;
+	totalUsed: number;
+}

package/src/limiters/sliding-window-log/sliding-window-log.status.ts

@@ -0,0 +1,44 @@
+import { type RateLimiterStatus } from '../../core/rate-limiter-status.js';
+
+/**
+ * The status of the Sliding Window Log rate limiter.
+ */
+export interface SlidingWindowLogStatus extends RateLimiterStatus {
+	/**
+	 * Maximum number of requests allowed within the time window.
+	 */
+	limit: number;
+
+	/**
+	 * The sliding time window duration in milliseconds.
+	 */
+	windowMs: number;
+
+	/**
+	 * Total number of requests consumed within the current sliding window.
+	 *
+	 * This count includes all requests that fall within the window period.
+	 */
+	totalUsed: number;
+
+	/**
+	 * Number of remaining requests available before hitting the limit.
+	 */
+	remaining: number;
+
+	/**
+	 * The timestamp (in milliseconds) when the next request slot will become available.
+	 *
+	 * This is based on when the oldest request in the window will expire.
+	 */
+	nextAvailableAt: number;
+
+	/**
+	 * The timestamp (in milliseconds) when the current window will fully reset.
+	 *
+	 * Represents when the last (most recent) request in the log will expire.
+	 *
+	 * After this time, all requests will have aged out of the sliding window.
+	 */
+	resetAt: number;
+}

package/src/limiters/token-bucket/index.ts

@@ -0,0 +1,4 @@
+export type { TokenBucketState } from './token-bucket.state.js';
+export type { TokenBucketStatus } from './token-bucket.status.js';
+export type { TokenBucketOptions } from './token-bucket.options.js';
+export { TokenBucketLimiter } from './token-bucket.limiter.js';

package/src/limiters/token-bucket/token-bucket.limiter.ts

@@ -0,0 +1,110 @@
+import { LogLevel } from '@stimulcross/logger';
+import { type TokenBucketOptions } from './token-bucket.options.js';
+import { TokenBucketPolicy } from './token-bucket.policy.js';
+import { type TokenBucketState } from './token-bucket.state.js';
+import { type TokenBucketStatus } from './token-bucket.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';
+
+/**
+ * Token Bucket 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 TokenBucketLimiter extends AbstractRateLimiter<TokenBucketState, TokenBucketStatus> {
+	private readonly _defaultLimitBehaviour: LimitBehavior;
+	private readonly _maxWaitMs: number | undefined;
+
+	protected override readonly _policy: TokenBucketPolicy;
+
+	constructor(options: TokenBucketOptions) {
+		super(options);
+
+		this._defaultLimitBehaviour = options.limitBehavior ?? 'reject';
+
+		if (options.queue?.maxWaitMs) {
+			this._maxWaitMs = options.queue.maxWaitMs;
+		}
+
+		this._policy = new TokenBucketPolicy(options.capacity, options.refillRate);
+	}
+
+	protected override async _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T> {
+		const now = this._clock.now();
+		const baseTtlMs = Math.ceil(this._policy.capacity / (this._policy.refillRate / 1000));
+
+		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, baseTtlMs + (runAt - now));
+
+			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._maxWaitMs;
+		const expiresAt = finalMaxWaitMs ? now + finalMaxWaitMs : undefined;
+
+		return await this._execute(fn, runAt, storeTtlMs, ctx, expiresAt);
+	}
+
+	protected override _getDebugStateString(state: TokenBucketState): string {
+		return `tkn: ${state.tokens.toFixed(2)}/${this._policy.capacity}, deb: ${state.debt.toFixed(2)}`;
+	}
+
+	private _printSuccessDebug(
+		decision: Decision,
+		nextState: TokenBucketState,
+		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/token-bucket/token-bucket.options.ts

@@ -0,0 +1,17 @@
+import { type TokenBucketState } from './token-bucket.state.js';
+import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
+
+/**
+ * Options for the Token Bucket rate limiter.
+ */
+export interface TokenBucketOptions extends RateLimiterOptions<TokenBucketState> {
+	/**
+	 * The maximum number of tokens that can be stored in the bucket.
+	 */
+	capacity: number;
+
+	/**
+	 * The rate, in seconds, at which tokens are refilled.
+	 */
+	refillRate: number;
+}

package/src/limiters/token-bucket/token-bucket.policy.ts

@@ -0,0 +1,155 @@
+import { type TokenBucketState } from './token-bucket.state.js';
+import { type TokenBucketStatus } from './token-bucket.status.js';
+import { type RateLimitPolicy, type RateLimitPolicyResult } from '../../core/rate-limit-policy.js';
+import { validateCost } from '../../utils/validate-cost.js';
+
+/** @internal */
+export class TokenBucketPolicy implements RateLimitPolicy<TokenBucketState, TokenBucketStatus> {
+	constructor(
+		private readonly _capacity: number,
+		private readonly _refillRate: number,
+		private readonly _maxDebt: number = Number.POSITIVE_INFINITY,
+	) {
+		if (!Number.isSafeInteger(_capacity) || _capacity <= 0) {
+			throw new Error(`Invalid capacity: ${_capacity}. Must be a positive integer.`);
+		}
+
+		if (!Number.isFinite(_refillRate) || _refillRate <= 0) {
+			throw new Error(`Invalid refillRate: ${_refillRate}. Must be a positive number.`);
+		}
+
+		if (_maxDebt < 0 || (!Number.isSafeInteger(_maxDebt) && _maxDebt !== Number.POSITIVE_INFINITY)) {
+			throw new Error(`Invalid maxDebt: ${_maxDebt}. Must be a non-negative integer or Infinity.`);
+		}
+	}
+
+	public get capacity(): number {
+		return this._capacity;
+	}
+
+	public get refillRate(): number {
+		return this._refillRate;
+	}
+
+	public getInitialState(): TokenBucketState {
+		return { tokens: this._capacity, debt: 0, lastRefill: 0 };
+	}
+
+	public getStatus(state: TokenBucketState, now: number): TokenBucketStatus {
+		const { tokens, debt } = this._syncState(state, now);
+
+		const deficitToOne = Math.max(0, debt + 1 - tokens);
+		const nextAvailableAt = deficitToOne === 0 ? now : now + Math.ceil((deficitToOne / this._refillRate) * 1000);
+
+		const deficitToCapacity = debt + (this._capacity - tokens);
+		const resetAt = deficitToCapacity === 0 ? now : now + Math.ceil((deficitToCapacity / this._refillRate) * 1000);
+
+		return {
+			capacity: this._capacity,
+			refillRate: this._refillRate,
+			tokens,
+			debt,
+			nextAvailableAt,
+			resetAt,
+		};
+	}
+
+	public evaluate(
+		state: TokenBucketState,
+		now: number,
+		cost: number,
+		shouldReserve?: boolean,
+	): RateLimitPolicyResult<TokenBucketState> {
+		validateCost(cost, this._capacity);
+
+		const { tokens, debt, lastRefill } = this._syncState(state, now);
+
+		if (tokens >= cost) {
+			return {
+				decision: { kind: 'allow' },
+				nextState: { tokens: tokens - cost, debt, lastRefill },
+			};
+		}
+
+		const deficit = cost - tokens;
+
+		if (shouldReserve) {
+			const newDebt = debt + deficit;
+
+			if (newDebt > this._maxDebt) {
+				const targetDebt = this._maxDebt - deficit;
+				const debtToClear = Math.max(0, debt - targetDebt);
+				const waitMs = Math.ceil((debtToClear / this._refillRate) * 1000);
+				const retryAt = now + waitMs;
+
+				return this._deny(tokens, debt, lastRefill, retryAt);
+			}
+
+			const waitMs = Math.ceil((newDebt / this._refillRate) * 1000);
+			const runAt = now + waitMs;
+
+			return {
+				decision: { kind: 'delay', runAt },
+				nextState: { tokens: 0, debt: newDebt, lastRefill },
+			};
+		}
+
+		const totalNeeded = debt + deficit;
+		const waitMs = Math.ceil((totalNeeded / this._refillRate) * 1000);
+		const retryAt = now + waitMs;
+
+		return this._deny(tokens, debt, lastRefill, retryAt);
+	}
+
+	public revert(state: TokenBucketState, cost: number, now: number): TokenBucketState {
+		let { tokens, debt, lastRefill } = this._syncState(state, now);
+
+		if (debt >= cost) {
+			debt -= cost;
+		} else {
+			const remainder = cost - debt;
+			debt = 0;
+			tokens = Math.min(this._capacity, tokens + remainder);
+		}
+
+		return { tokens, debt, lastRefill };
+	}
+
+	private _deny(
+		tokens: number,
+		debt: number,
+		lastRefill: number,
+		retryAt: number,
+	): RateLimitPolicyResult<TokenBucketState> {
+		return {
+			decision: { kind: 'deny', retryAt },
+			nextState: { tokens, debt, lastRefill },
+		};
+	}
+
+	private _syncState(state: TokenBucketState, now: number): TokenBucketState {
+		if (state.lastRefill === 0) {
+			return { tokens: this._capacity, debt: 0, lastRefill: now };
+		}
+
+		if (now <= state.lastRefill) {
+			return state;
+		}
+
+		let { tokens, debt } = state;
+
+		const elapsedMs = now - state.lastRefill;
+		const generatedTokens = (elapsedMs / 1000) * this._refillRate;
+
+		if (debt > 0) {
+			const payOff = Math.min(debt, generatedTokens);
+			debt -= payOff;
+			const remainingTokens = generatedTokens - payOff;
+			tokens = Math.min(this._capacity, tokens + remainingTokens);
+		} else {
+			tokens = Math.min(this._capacity, tokens + generatedTokens);
+		}
+
+		return { tokens, debt, lastRefill: now };
+	}
+}

package/src/limiters/token-bucket/token-bucket.state.ts

@@ -0,0 +1,10 @@
+/**
+ * Token Bucket rate limiter state.
+ *
+ * When using a distributed state store, make sure it properly serializes and deserializes the state.
+ */
+export interface TokenBucketState {
+	tokens: number;
+	debt: number;
+	lastRefill: number;
+}

package/src/limiters/token-bucket/token-bucket.status.ts

@@ -0,0 +1,36 @@
+import { type RateLimiterStatus } from '../../core/rate-limiter-status.js';
+
+/**
+ * The status of the Token Bucket rate limiter.
+ */
+export interface TokenBucketStatus extends RateLimiterStatus {
+	/**
+	 * The maximum number of tokens that can be stored in the bucket.
+	 */
+	capacity: number;
+
+	/**
+	 * The rate, in seconds, at which tokens are refilled.
+	 */
+	refillRate: number;
+
+	/**
+	 * The number of tokens available in the bucket.
+	 */
+	tokens: number;
+
+	/**
+	 * The number of tokens that have been reserved.
+	 */
+	debt: number;
+
+	/**
+	 * The timestamp (in milliseconds) at which next token will be available for use.
+	 */
+	nextAvailableAt: number;
+
+	/**
+	 * The timestamp (in milliseconds) at which the bucket will be reset.
+	 */
+	resetAt: number;
+}

package/src/runtime/default-clock.ts

@@ -0,0 +1,8 @@
+import { type Clock } from '../core/clock.js';
+
+/** @internal */
+export const defaultClock: Clock = {
+	now(): number {
+		return Date.now();
+	},
+};

package/src/runtime/execution-tickets.ts

@@ -0,0 +1,34 @@
+import { Deque } from '@stimulcross/ds-deque';
+
+/** @internal */
+export class ExecutionTickets {
+	private readonly _tickets = new Deque<number>();
+
+	public get size(): number {
+		return this._tickets.size;
+	}
+
+	public get isEmpty(): boolean {
+		return this._tickets.size === 0;
+	}
+
+	public add(tick: number): void {
+		this._tickets.push(tick);
+	}
+
+	public peek(): number | undefined {
+		return this._tickets.peekHead();
+	}
+
+	public consume(): number | undefined {
+		return this._tickets.shift();
+	}
+
+	public dropLast(): number | undefined {
+		return this._tickets.pop();
+	}
+
+	public clear(): void {
+		this._tickets.clear();
+	}
+}