@stimulcross/rate-limiter 0.0.1

package/src/runtime/in-memory-state-store.ts

@@ -0,0 +1,135 @@
+import { Deque } from '@stimulcross/ds-deque';
+import { type Clock } from '../core/clock.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 { promiseWithResolvers } from '../utils/promise-with-resolvers.js';
+
+interface StateEntry<V> {
+	value: V;
+	expiresAt?: number;
+}
+
+interface Waiter {
+	resolve: () => void;
+	reject: (err: Error) => void;
+}
+
+const CLEANUP_INTERVAL_MS = 60_000;
+
+/** @internal */
+export class InMemoryStateStore<V> implements StateStorage<V> {
+	private readonly _state = new Map<string, StateEntry<V>>();
+	private readonly _activeLocks = new Set<string>();
+	private readonly _waitingResolvers = new Map<string, Deque<Waiter>>();
+
+	private readonly _cleanupTimer: ReturnType<typeof setTimeout>;
+
+	constructor(private readonly _clock: Clock) {
+		this._cleanupTimer = setInterval(() => {
+			const now = this._clock.now();
+
+			for (const [key, entry] of this._state.entries()) {
+				if (entry.expiresAt && entry.expiresAt <= now) {
+					this._state.delete(key);
+				}
+			}
+		}, CLEANUP_INTERVAL_MS);
+
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+		if (this._cleanupTimer.unref) {
+			this._cleanupTimer.unref();
+		}
+	}
+
+	public async get(key: string): Promise<V | null> {
+		const entry = this._state.get(key);
+
+		if (entry?.expiresAt && entry.expiresAt <= this._clock.now()) {
+			this._state.delete(key);
+			return null;
+		}
+
+		return entry?.value ?? null;
+	}
+
+	public async set(key: string, value: V, ttlMs?: number): Promise<void> {
+		const entry: StateEntry<V> = { value };
+
+		if (typeof ttlMs === 'number') {
+			if (ttlMs <= 0) {
+				this._state.delete(key);
+				return;
+			}
+
+			entry.expiresAt = this._clock.now() + ttlMs;
+		}
+
+		this._state.set(key, entry);
+	}
+
+	public async delete(key: string): Promise<void> {
+		this._state.delete(key);
+	}
+
+	public async clear(): Promise<void> {
+		this._state.clear();
+
+		const error = new RateLimitError(
+			RateLimitErrorCode.Destroyed,
+			undefined,
+			'Store was cleared or destroyed while waiting for lock',
+		);
+
+		for (const queue of this._waitingResolvers.values()) {
+			while (queue.size > 0) {
+				const waiter = queue.shift();
+
+				if (waiter) {
+					waiter.reject(error);
+				}
+			}
+		}
+
+		this._waitingResolvers.clear();
+		this._activeLocks.clear();
+	}
+
+	public async destroy(): Promise<void> {
+		clearInterval(this._cleanupTimer);
+		await this.clear();
+	}
+
+	public async acquireLock(key: string): Promise<void> {
+		if (this._activeLocks.has(key)) {
+			const { promise, resolve, reject } = promiseWithResolvers();
+
+			const queue = this._waitingResolvers.get(key) ?? new Deque();
+			queue.push({ resolve, reject });
+			this._waitingResolvers.set(key, queue);
+
+			await promise;
+		} else {
+			this._activeLocks.add(key);
+		}
+	}
+
+	public async releaseLock(key: string): Promise<void> {
+		const queue = this._waitingResolvers.get(key);
+
+		if (queue && queue.size > 0) {
+			const nextWaiter = queue.shift();
+
+			if (nextWaiter) {
+				nextWaiter.resolve();
+			}
+
+			if (queue.size === 0) {
+				this._waitingResolvers.delete(key);
+			}
+		} else {
+			this._activeLocks.delete(key);
+			this._waitingResolvers.delete(key);
+		}
+	}
+}

package/src/runtime/rate-limiter.executor.ts

@@ -0,0 +1,286 @@
+import { BinaryHeap } from '@stimulcross/ds-binary-heap';
+import { PolicyPriorityQueue, type Priority, type SelectionPolicy } from '@stimulcross/ds-policy-priority-queue';
+import { type Logger, LogLevel } from '@stimulcross/logger';
+import { ExecutionTickets } from './execution-tickets.js';
+import { Semaphore } from './semaphore.js';
+import { Task } from './task.js';
+import { type Clock } from '../core/clock.js';
+import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../errors/rate-limit.error.js';
+
+/** @internal */
+export interface RateLimiterExecutionOptions {
+	id: string;
+	key: string;
+	expiresAt?: number;
+	priority?: number;
+	signal?: AbortSignal;
+}
+
+/** @internal */
+export interface RateLimiterExecutorQueueOptions {
+	concurrency?: number;
+	capacity?: number;
+	selectionPolicy?: SelectionPolicy;
+	signal?: AbortSignal;
+}
+
+/** @internal */
+export class RateLimiterExecutor {
+	private readonly _clock: Clock;
+	private readonly _tickets = new ExecutionTickets();
+	private readonly _semaphore: Semaphore;
+	private readonly _queue: PolicyPriorityQueue<Task>;
+	private readonly _expiryHeap = new BinaryHeap<Task>((a: Task, b: Task): number => a.expiresAt! - b.expiresAt!);
+
+	private _drainTimer: ReturnType<typeof setTimeout> | null = null;
+	private _expiryTimer: ReturnType<typeof setTimeout> | null = null;
+	private _nextExpiryScheduledAt: number | null = null;
+
+	constructor(
+		private readonly _logger: Logger,
+		clock: Clock,
+		{ concurrency, capacity, selectionPolicy }: RateLimiterExecutorQueueOptions = {},
+	) {
+		this._clock = clock;
+		this._semaphore = new Semaphore(concurrency ?? null);
+		this._queue = new PolicyPriorityQueue<Task>({
+			capacity,
+			selectionPolicy: selectionPolicy as SelectionPolicy<Task> | undefined,
+		});
+	}
+
+	public get isQueueFull(): boolean {
+		return this._queue.isFull;
+	}
+
+	public get queueSize(): number {
+		return this._queue.size;
+	}
+
+	public get queueCapacity(): number {
+		return this._queue.capacity;
+	}
+
+	public async execute<T>(fn: () => T | Promise<T>, runAt: number, options: RateLimiterExecutionOptions): Promise<T> {
+		const task = new Task<T>(fn, options);
+
+		task.isCancellable &&
+			task.onAbort(() => {
+				this._shouldPrintDebug &&
+					this._logger.debug(
+						`[DROP CANCELLED] [id: ${options.id}, key: ${options.key}] - ${this._getStateDebugString(task.priority)}`,
+					);
+
+				this._tickets.dropLast();
+
+				const priorityQueue = this._queue.getQueue(task.priority);
+				priorityQueue.remove(task);
+
+				this._drain();
+			});
+
+		this._tickets.add(runAt);
+		this._queue.enqueue(task, task.priority);
+
+		if (task.expiresAt !== undefined) {
+			this._expiryHeap.push(task);
+		}
+
+		this._shouldPrintDebug &&
+			this._logger.debug(
+				`↓ [ENQ] [id: ${options.id}, key: ${options.key}] - ${this._getStateDebugString(task.priority)}`,
+			);
+
+		this._drain();
+
+		return await task;
+	}
+
+	public clear(): void {
+		this._clearDrainTimer();
+		this._clearExpiryTimer();
+		this._tickets.clear();
+		this._expiryHeap.clear();
+
+		const pendingTasks = this._drainRemainingTasks();
+
+		if (pendingTasks.length === 0) {
+			return;
+		}
+
+		for (const task of pendingTasks) {
+			this._shouldPrintDebug &&
+				this._logger.debug(
+					`[DROP CLEAR] [id: ${task.id}, key: ${task.key}] - Destroy due to clear() - ${this._getStateDebugString(task.priority)}`,
+				);
+
+			task.destroy();
+			task.reject(new RateLimitError(RateLimitErrorCode.Destroyed));
+		}
+	}
+
+	private get _shouldPrintDebug(): boolean {
+		return this._logger.minLevel >= LogLevel.DEBUG;
+	}
+
+	private _drain(): void {
+		const now = this._clock.now();
+		const expiredTasks = this._extractExpiredTasks(now);
+
+		for (const task of expiredTasks) {
+			this._shouldPrintDebug &&
+				this._logger.debug(
+					`[DROP EXPIRED] [id: ${task.id}, key: ${task.key}] - ${this._getStateDebugString(task.priority)}`,
+				);
+
+			this._tickets.dropLast();
+			task.destroy();
+			task.reject(new RateLimitError(RateLimitErrorCode.Expired));
+		}
+
+		this._recalibrateExpiryTimer(now);
+
+		while (!this._queue.isEmpty) {
+			const nextTicketAt = this._tickets.peek();
+
+			if (nextTicketAt !== undefined && nextTicketAt > now) {
+				this._scheduleDrainTimer(nextTicketAt - now);
+				return;
+			}
+
+			const isAcquired = this._semaphore.acquire();
+
+			if (!isAcquired) {
+				return;
+			}
+
+			const task = this._queue.dequeue();
+
+			if (!task) {
+				this._semaphore.release();
+				return;
+			}
+
+			task.destroy();
+			this._tickets.consume();
+
+			this._shouldPrintDebug &&
+				this._logger.debug(
+					`↑ [DEQ] [id: ${task.id}, key: ${task.key}] - ${this._getStateDebugString(task.priority)}`,
+				);
+
+			void task.run().finally(() => {
+				this._semaphore.release();
+				queueMicrotask(() => this._drain());
+			});
+		}
+	}
+
+	private _getNextExpiryTimestamp(): number | null {
+		while (!this._expiryHeap.isEmpty) {
+			const task = this._expiryHeap.peek()!;
+
+			if (!task.isActive) {
+				this._expiryHeap.pop();
+				continue;
+			}
+
+			return task.expiresAt!;
+		}
+
+		return null;
+	}
+
+	private _extractExpiredTasks(now: number): Task[] {
+		const result: Task[] = [];
+
+		while (!this._expiryHeap.isEmpty) {
+			const task = this._expiryHeap.peek()!;
+
+			if (!task.isActive) {
+				this._expiryHeap.pop();
+				continue;
+			}
+
+			if (task.expiresAt! > now) {
+				break;
+			}
+
+			this._expiryHeap.pop();
+
+			const priorityQueue = this._queue.getQueue(task.priority);
+			priorityQueue.remove(task);
+			result.push(task);
+		}
+
+		return result;
+	}
+
+	private _drainRemainingTasks(): Task[] {
+		const remaining: Task[] = [];
+
+		for (const queue of this._queue.queues()) {
+			while (!queue.isEmpty) {
+				const task = queue.dequeue()!;
+				remaining.push(task);
+			}
+		}
+
+		return remaining;
+	}
+
+	private _scheduleDrainTimer(delayMs: number): void {
+		if (this._drainTimer) {
+			return;
+		}
+
+		this._drainTimer = setTimeout(() => {
+			this._clearDrainTimer();
+			this._drain();
+		}, delayMs);
+	}
+
+	private _recalibrateExpiryTimer(now: number): void {
+		const nextExpiry = this._getNextExpiryTimestamp();
+
+		if (nextExpiry === null) {
+			this._clearExpiryTimer();
+			this._nextExpiryScheduledAt = null;
+
+			return;
+		}
+
+		if (this._nextExpiryScheduledAt === nextExpiry) {
+			return;
+		}
+
+		this._clearExpiryTimer();
+
+		const delay = Math.max(0, nextExpiry - now);
+
+		this._nextExpiryScheduledAt = nextExpiry;
+		this._expiryTimer = setTimeout(() => {
+			this._clearExpiryTimer();
+			this._drain();
+		}, delay);
+	}
+
+	private _clearDrainTimer(): void {
+		if (this._drainTimer) {
+			clearTimeout(this._drainTimer);
+			this._drainTimer = null;
+		}
+	}
+
+	private _clearExpiryTimer(): void {
+		if (this._expiryTimer) {
+			clearTimeout(this._expiryTimer);
+			this._expiryTimer = null;
+		}
+	}
+
+	private _getStateDebugString(priority: Priority): string {
+		return `prt: ${priority} | q: ${this._queue.size}/${this._queue.capacity}`;
+	}
+}

package/src/runtime/semaphore.ts

@@ -0,0 +1,31 @@
+/** @internal */
+export class Semaphore {
+	private _permits: number;
+
+	constructor(private readonly _maxPermits: number | null) {
+		if (_maxPermits !== null && (!Number.isSafeInteger(_maxPermits) || _maxPermits <= 0)) {
+			throw new Error('Maximum permits must be a non-negative integer or null');
+		}
+
+		this._permits = _maxPermits ?? 0;
+	}
+
+	public acquire(): boolean {
+		if (this._maxPermits === null) {
+			return true;
+		}
+
+		if (this._permits > 0) {
+			this._permits--;
+			return true;
+		}
+
+		return false;
+	}
+
+	public release(): void {
+		if (this._maxPermits !== null && this._permits < this._maxPermits) {
+			this._permits++;
+		}
+	}
+}

package/src/runtime/task.ts

@@ -0,0 +1,141 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../errors/rate-limit.error.js';
+import { promiseWithResolvers } from '../utils/promise-with-resolvers.js';
+
+/** @internal */
+export interface TaskOptions {
+	id: string;
+	key: string;
+	priority?: Priority;
+	expiresAt?: number;
+	signal?: AbortSignal;
+}
+
+/** @internal */
+export class Task<T = any> implements PromiseLike<T> {
+	private readonly _task: () => T | Promise<T>;
+	private readonly _promise: Promise<T>;
+	private readonly _resolve: (v: T) => void;
+	private readonly _reject: (reason?: any) => void;
+
+	private readonly _id: string;
+	private readonly _key: string;
+	private readonly _priority: Priority;
+	private readonly _expiresAt?: number;
+
+	private _signal?: AbortSignal;
+	private _abortListener?: () => void;
+	private _abortHandler?: () => void;
+
+	private _isActive = true;
+	private _isAborted = false;
+
+	constructor(task: () => T | Promise<T>, { id, key, priority = Priority.Normal, expiresAt, signal }: TaskOptions) {
+		const { promise, resolve, reject } = promiseWithResolvers<T>();
+
+		this._task = task;
+		this._promise = promise;
+		this._resolve = resolve;
+		this._reject = reject;
+		this._id = id;
+		this._key = key;
+		this._priority = priority;
+		this._expiresAt = expiresAt;
+
+		if (signal) {
+			this._signal = signal;
+
+			this._abortListener = (): void => {
+				this._isActive = false;
+				this._isAborted = true;
+
+				this._abortHandler?.();
+				this._reject(new RateLimitError(RateLimitErrorCode.Cancelled, undefined, 'Aborted by client'));
+				this.destroy();
+			};
+
+			this._signal.addEventListener('abort', this._abortListener, { once: true });
+		}
+	}
+
+	public get id(): string {
+		return this._id;
+	}
+
+	public get key(): string {
+		return this._key;
+	}
+
+	public get priority(): Priority {
+		return this._priority;
+	}
+
+	public get expiresAt(): number | undefined {
+		return this._expiresAt;
+	}
+
+	public get isActive(): boolean {
+		return this._isActive;
+	}
+
+	public get isCancellable(): boolean {
+		return Boolean(this._signal);
+	}
+
+	public get isAborted(): boolean {
+		return this._isAborted;
+	}
+
+	public async run(): Promise<void> {
+		this._isActive = false;
+
+		try {
+			const result = await this._task();
+			this._resolve(result);
+		} catch (e) {
+			this._reject(e);
+		}
+	}
+
+	public reject(reason: unknown): void {
+		this._isActive = false;
+		this._reject(reason);
+	}
+
+	public destroy(): void {
+		this._isActive = false;
+
+		if (this._signal && this._abortListener) {
+			this._signal.removeEventListener('abort', this._abortListener);
+
+			this._signal = undefined;
+			this._abortListener = undefined;
+		}
+
+		if (this._abortHandler) {
+			this._abortHandler = undefined;
+		}
+	}
+
+	public onAbort(handler: () => void): void {
+		this._abortHandler = handler;
+	}
+
+	public then<TResult1 = T, TResult2 = never>(
+		onfulfilled?: ((value: T) => PromiseLike<TResult1> | TResult1) | null,
+		onrejected?: ((reason: any) => PromiseLike<TResult2> | TResult2) | null,
+	): PromiseLike<TResult1 | TResult2> {
+		return this._promise.then(onfulfilled, onrejected);
+	}
+
+	public catch<TResult = never>(
+		onrejected?: ((reason: any) => PromiseLike<TResult> | TResult) | null,
+	): PromiseLike<T | TResult> {
+		return this._promise.catch(onrejected);
+	}
+
+	public finally(onfinally?: (() => void) | null): PromiseLike<T> {
+		return this._promise.finally(onfinally);
+	}
+}

package/src/types/limit-behavior.ts

@@ -0,0 +1,8 @@
+/**
+ * Defines the behavior when the limit is reached.
+ *
+ * Available options:
+ * - `reject` - rejects the task with `LIMIT_EXCEEDED` error code
+ * - `enqueue` - enqueues the task
+ */
+export type LimitBehavior = 'enqueue' | 'reject';

package/src/utils/generate-random-string.ts

@@ -0,0 +1,16 @@
+const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/** @internal */
+export function generateRandomString(length: number = 7): string {
+	if (!Number.isSafeInteger(length) || length < 0) {
+		throw new RangeError(`Invalid length: ${length}. Length must be a positive integer.`);
+	}
+
+	const result = new Array(length);
+
+	for (let i = 0; i < length; i++) {
+		result.push(characters.charAt(Math.floor(Math.random() * characters.length)));
+	}
+
+	return result.join('');
+}

package/src/utils/promise-with-resolvers.ts

@@ -0,0 +1,23 @@
+/** @internal */
+export interface PromiseWithResolvers<T = void> {
+	promise: Promise<T>;
+	resolve: (value: T | PromiseLike<T>) => void;
+	reject: (reason?: unknown) => void;
+}
+
+/** @internal */
+export function promiseWithResolvers<T = void>(): PromiseWithResolvers<T> {
+	// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+	if (Promise.withResolvers) {
+		return Promise.withResolvers<T>();
+	}
+
+	let resolve!: (value: T | PromiseLike<T>) => void;
+	let reject!: (reason: unknown) => void;
+	const promise = new Promise<T>((_resolve, _reject) => {
+		resolve = _resolve;
+		reject = _reject;
+	});
+
+	return { promise, resolve, reject };
+}

package/src/utils/sanitize-error.ts

@@ -0,0 +1,4 @@
+/** @internal */
+export function sanitizeError(error: unknown): Error {
+	return error instanceof Error ? error : new Error('Non-error thrown. Check "cause" property', { cause: error });
+}

package/src/utils/sanitize-priority.ts

@@ -0,0 +1,22 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+
+/** @internal */
+export function sanitizePriority(priority: number): Priority {
+	if (!Number.isFinite(priority)) {
+		return Priority.Normal;
+	}
+
+	if (priority < Priority.Lowest) {
+		return Priority.Lowest;
+	}
+
+	if (priority > Priority.Highest) {
+		return Priority.Highest;
+	}
+
+	if (!Number.isInteger(priority)) {
+		priority = Math.round(priority);
+	}
+
+	return priority;
+}

package/src/utils/validate-cost.ts

@@ -0,0 +1,16 @@
+import { InvalidCostError } from '../errors/invalid-cost.error.js';
+
+/** @internal */
+export function validateCost(cost: number, max?: number, min?: number): void {
+	if (!Number.isSafeInteger(cost) || cost < 0) {
+		throw new InvalidCostError(`Invalid cost: ${cost}. Cost must be a positive integer.`, cost);
+	}
+
+	if (max !== undefined && cost > max) {
+		throw new InvalidCostError(`Invalid cost: ${cost}. Cost must be greater than or equal to ${max}.`, cost);
+	}
+
+	if (min !== undefined && cost < min) {
+		throw new InvalidCostError(`Invalid cost: ${cost}. Cost must be greater than or equal to ${min}.`, cost);
+	}
+}