@stimulcross/rate-limiter 0.0.1 → 0.0.3

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

@@ -1,286 +0,0 @@
-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

@@ -1,31 +0,0 @@
-/** @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

@@ -1,141 +0,0 @@
-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/utils/generate-random-string.ts

@@ -1,16 +0,0 @@
-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

@@ -1,23 +0,0 @@
-/** @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

@@ -1,4 +0,0 @@
-/** @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

@@ -1,22 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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);
-	}
-}