@stimulcross/rate-limiter 0.0.1 → 0.0.2

package/commitlint.config.js

@@ -1,8 +0,0 @@
-export default {
-	extends: ['@stimulcross/commitlint-config'],
-	rules: {
-		'body-max-line-length': [2, 'always', 500],
-		'footer-max-line-length': [2, 'always', 500],
-	}
-
-};

package/eslint.config.js

@@ -1,65 +0,0 @@
-import { resolveFlatConfig } from '@leancodepl/resolve-eslint-flat-config';
-import typescript from '@stimulcross/eslint-config-typescript';
-import typescriptStyle from '@stimulcross/eslint-config-typescript/style';
-import { defineConfig, globalIgnores } from 'eslint/config';
-import globals from 'globals';
-
-export const globs = {
-	js: ['**/*.js', '**/*.cjs', '**/*.mjs'],
-	ts: ['**/*.ts', '**/*.cts', '**/*.mts'],
-	jsSpec: ['**/*.spec.js', '**/*.spec.cjs', '**/*.spec.mjs'],
-	tsSpec: ['**/*.spec.ts', '**/*.spec.cts', '**/*.spec.mts'],
-	lib: '**/dist',
-	nodeModules: '**/node_modules',
-	coverage: '**/coverage',
-	dts: '**/*.d.ts',
-};
-
-/** @type {import("eslint").Linter.Config[]} */
-export const config = resolveFlatConfig(
-	defineConfig(
-		globalIgnores([globs.lib, globs.nodeModules, globs.dts, globs.coverage]),
-		{
-			files: [...globs.js, ...globs.ts, ...globs.jsSpec, ...globs.tsSpec],
-			languageOptions: {
-				globals: {
-					...globals.node,
-					...globals.es2022,
-				},
-			},
-		},
-		{
-			files: [...globs.js, ...globs.ts, ...globs.tsSpec],
-			extends: [typescript, typescriptStyle],
-		},
-		{
-			files: [...globs.ts, ...globs.tsSpec],
-			rules: {
-				'id-length': 'off',
-				'no-await-in-loop': 'off',
-				'unicorn/no-new-array': 'off',
-				'unicorn/no-thenable': 'off',
-				'unicorn/no-useless-undefined': 'error',
-				'@typescript-eslint/no-explicit-any': 'off',
-				'@typescript-eslint/no-non-null-assertion': 'off',
-				'@typescript-eslint/no-unnecessary-condition': ['warn', { allowConstantLoopConditions: true }],
-			},
-		},
-		{
-			files: [...globs.jsSpec, ...globs.tsSpec],
-			rules: {
-				'id-length': 'off',
-				'max-nested-callbacks': 'off',
-				'unicorn/consistent-function-scoping': 'off',
-				'unicorn/no-array-push-push': 'off',
-				'@typescript-eslint/naming-convention': 'off',
-				'@typescript-eslint/no-empty-function': 'off',
-				'@typescript-eslint/no-unsafe-member-access': 'off',
-				'@typescript-eslint/no-unsafe-return': 'off',
-				'@typescript-eslint/unbound-method': 'off',
-			},
-		},
-	),
-);
-
-export default config;

package/lint-staged.config.js

@@ -1,4 +0,0 @@
-export default {
-	'*.{js,mjs,ts,json,md}': 'prettier --write ',
-	'src/*.{js,ts}': 'eslint src',
-};

package/prettier.config.cjs

@@ -1 +0,0 @@
-module.exports = require('@stimulcross/prettier-config');

package/src/core/cancellable.ts

@@ -1,4 +0,0 @@
-/** @internal */
-export interface Cancellable {
-	cancel(): void;
-}

package/src/core/clock.ts

@@ -1,9 +0,0 @@
-/**
- * Clock interface.
- */
-export interface Clock {
-	/**
-	 * Returns the current timestamp in milliseconds.
-	 */
-	now(): number;
-}

package/src/core/decision.ts

@@ -1,27 +0,0 @@
-/** @internal */
-export type DecisionKind = 'allow' | 'deny' | 'delay';
-
-/** @internal */
-export interface DecisionBase {
-	kind: DecisionKind;
-}
-
-/** @internal */
-export interface DecisionAllow extends DecisionBase {
-	kind: Extract<DecisionKind, 'allow'>;
-}
-
-/** @internal */
-export interface DecisionDeny extends DecisionBase {
-	kind: Extract<DecisionKind, 'deny'>;
-	retryAt: number;
-}
-
-/** @internal */
-export interface DecisionDelay extends DecisionBase {
-	kind: Extract<DecisionKind, 'delay'>;
-	runAt: number;
-}
-
-/** @internal */
-export type Decision = DecisionAllow | DecisionDeny | DecisionDelay;

package/src/core/rate-limit-policy.ts

@@ -1,15 +0,0 @@
-import { type Decision } from './decision.js';
-
-/** @internal */
-export interface RateLimitPolicyResult<S> {
-	decision: Decision;
-	nextState: S;
-}
-
-/** @internal */
-export interface RateLimitPolicy<TState extends object = object, TStatus extends object = object> {
-	getInitialState(now: number): TState;
-	getStatus(state: TState, now: number): TStatus;
-	evaluate(state: TState, now: number, cost: number, shouldReserve?: boolean): RateLimitPolicyResult<TState>;
-	revert(state: TState, cost: number, now: number): TState;
-}

package/src/core/rate-limiter-status.ts

@@ -1,14 +0,0 @@
-/**
- * The status of the rate limiter.
- */
-export interface RateLimiterStatus {
-	/**
-	 * The timestamp (in milliseconds) when a rate limiter will allow a single request.
-	 */
-	readonly nextAvailableAt: number;
-
-	/**
-	 * The timestamp (in milliseconds) when the rate limiter will reset.
-	 */
-	readonly resetAt: number;
-}

package/src/core/rate-limiter.ts

@@ -1,37 +0,0 @@
-import { type RateLimiterRunOptions } from '../interfaces/rate-limiter-run-options.js';
-
-/**
- * Rate limiter interface.
- *
- * @template TStatus The type of the rate limiter status returned by {@link getStatus} method.
- */
-export interface RateLimiter<TStatus extends object = object> {
-	/**
-	 * Runs the given task.
-	 *
-	 * @param task The task to run.
-	 * @param options Options for running the task.
-	 */
-	run<T>(task: () => T | Promise<T>, options?: RateLimiterRunOptions): Promise<T>;
-
-	/**
-	 * Clears the rate limiter state.
-	 *
-	 * @param key The optional key to clear the state for.
-	 */
-	clear(key?: string): Promise<void>;
-
-	/**
-	 * Gets the rate limiter's status.
-	 *
-	 * @param key The optional key to get the status for.
-	 */
-	getStatus?(key?: string): Promise<TStatus>;
-
-	/**
-	 * Destroys the rate limiter.
-	 *
-	 * The limiter cannot be used after it has been destroyed. It should be used only for graceful shutdown.
-	 */
-	destroy?(): Promise<void>;
-}

package/src/core/state-storage.ts

@@ -1,51 +0,0 @@
-/**
- * State storage interface.
- */
-export interface StateStorage<TState> {
-	/**
-	 * Gets the state for the given key.
-	 *
-	 * @param key The key to get the state for.
-	 */
-	get(key: string): Promise<TState | null>;
-
-	/**
-	 * Sets the state for the given key.
-	 *
-	 * @param key The key to set the state for.
-	 * @param value The state to set.
-	 * @param ttlMs Optional TTL in milliseconds.
-	 */
-	set(key: string, value: TState, ttlMs?: number): Promise<void>;
-
-	/**
-	 * Deletes the state for the given key.
-	 *
-	 * @param key The key to delete the state for.
-	 */
-	delete(key: string): Promise<void>;
-
-	/**
-	 * Clears all stored states.
-	 */
-	clear(): Promise<void>;
-
-	/**
-	 * Destroys the storage.
-	 */
-	destroy?(): Promise<void>;
-
-	/**
-	 * Acquires a lock for the given key.
-	 *
-	 * @param key The key to acquire the lock for.
-	 */
-	acquireLock?(key: string): Promise<void>;
-
-	/**
-	 * Releases the lock for the given key.
-	 *
-	 * @param key The key to release the lock for.
-	 */
-	releaseLock?(key: string): Promise<void>;
-}

package/src/enums/rate-limit-error-code.ts

@@ -1,29 +0,0 @@
-/**
- * Rate limiter error codes.
- */
-export enum RateLimitErrorCode {
-	/**
-	 * Indicates that the limit has been reached.
-	 */
-	LimitExceeded = 'LIMIT_EXCEEDED',
-
-	/**
-	 * Indicates that the execution queue is full.
-	 */
-	QueueOverflow = 'QUEUE_OVERFLOW',
-
-	/**
-	 * Indicates that the task has expired.
-	 */
-	Expired = 'EXPIRED',
-
-	/**
-	 * Indicates that a task was cleared before it was executed.
-	 */
-	Destroyed = 'DESTROYED',
-
-	/**
-	 * Indicates that a task was canceled via abort controller before it was executed.
-	 */
-	Cancelled = 'CANCELLED',
-}

package/src/errors/custom.error.ts

@@ -1,14 +0,0 @@
-/** @internal */
-export abstract class CustomError extends Error {
-	protected constructor(message: string) {
-		super(message);
-
-		Object.setPrototypeOf(this, new.target.prototype);
-		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-		Error.captureStackTrace?.(this, new.target.constructor);
-	}
-
-	public get name(): string {
-		return this.constructor.name;
-	}
-}

package/src/errors/invalid-cost.error.ts

@@ -1,33 +0,0 @@
-import { CustomError } from './custom.error.js';
-
-export interface InvalidCostErrorPlainObject extends Error {
-	cost: number;
-}
-
-/**
- * Error thrown when the cost is invalid.
- *
- * The cost must be a positive integer or zero.
- */
-export class InvalidCostError extends CustomError {
-	constructor(
-		message: string,
-		private readonly _cost: number,
-	) {
-		super(message);
-	}
-
-	public get cost(): number {
-		return this._cost;
-	}
-
-	// eslint-disable-next-line @typescript-eslint/naming-convention
-	public toJSON(): InvalidCostErrorPlainObject {
-		return {
-			name: this.name,
-			message: this.message,
-			cost: this._cost,
-			stack: this.stack,
-		};
-	}
-}

package/src/errors/rate-limit.error.ts

@@ -1,91 +0,0 @@
-import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
-
-export interface RateLimitErrorPlainObject extends Error {
-	code: RateLimitErrorCode;
-	retryAt: number | null;
-}
-
-/**
- * An error thrown when a rate limit is exceeded.
- *
- * This error has a {@link code} property that indicates the type of error.
- *
- * The `code` can be:
- * - `LIMIT_EXCEEDED` - When the rate limit is exceeded.
- * - `QUEUE_OVERFLOW` - When the queue is full (if the limiter has a queue and the capacity has been exceeded).
- * - `EXPIRED` - When the task has expired (waited too long in the queue). This is related to the `maxWaitMs` option.
- *			   **NOTE:** This is never thrown if the task is executing too long. Such scenarios should be handled by the
- *			   task itself.
- * - `DESTROYED` - When the task is destroyed due to the rate limiter's `clear()` or `destroy()` methods.
- * - `CANCELLED` - When the task is cancelled using an abort signal.
- */
-export class RateLimitError extends Error {
-	private readonly _code: RateLimitErrorCode;
-	private readonly _retryAt: number | null;
-
-	/** @internal */
-	constructor(code: RateLimitErrorCode, retryAt?: number, message?: string) {
-		if (!message) {
-			switch (code) {
-				case RateLimitErrorCode.LimitExceeded: {
-					message = `Rate limit exceeded.${retryAt ? ` Retry at ${new Date(retryAt).toISOString()}.` : ''}`;
-					break;
-				}
-
-				case RateLimitErrorCode.QueueOverflow: {
-					message = 'Queue overflow.';
-					break;
-				}
-
-				case RateLimitErrorCode.Expired: {
-					message = 'Task expired.';
-					break;
-				}
-
-				case RateLimitErrorCode.Destroyed: {
-					message = 'Task destroyed.';
-					break;
-				}
-
-				case RateLimitErrorCode.Cancelled: {
-					message = 'Task cancelled.';
-					break;
-				}
-
-				// No default
-			}
-		}
-
-		super(message);
-
-		this._code = code;
-		this._retryAt = retryAt ?? null;
-	}
-
-	/**
-	 * The error code.
-	 */
-	public get code(): RateLimitErrorCode {
-		return this._code;
-	}
-
-	/**
-	 * The timestamp (in milliseconds) when the task can be retried.
-	 *
-	 * Can be `null` if the retry time is not known.
-	 */
-	public get retryAt(): number | null {
-		return this._retryAt ?? null;
-	}
-
-	// eslint-disable-next-line @typescript-eslint/naming-convention
-	public toJSON(): RateLimitErrorPlainObject {
-		return {
-			name: this.name,
-			message: this.message,
-			code: this._code,
-			retryAt: this._retryAt,
-			stack: this.stack,
-		};
-	}
-}

package/src/index.ts

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

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

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

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