@stimulcross/rate-limiter 0.0.1 → 0.0.3

package/README.md

@@ -5,3 +5,23 @@ A collection of rate limiters designed primarily for **outbound request throttli
 They are suited for client-side usage to respect third-party limits or protect internal resources.
 
 While it is technically possible to use these limiters for server-side traffic backed by a distributed store like Redis, it is **not recommended**. The algorithms evaluate state within the application process, so distributed usage requires multiple network operations per request introducing significant round-trip latency.
+
+## Installation
+
+**npm**
+
+```
+npm add @stimulcross/rate-limiter
+```
+
+**pnpm**
+
+```
+pnpm add @stimulcross/rate-limiter
+```
+
+**yarn**
+
+```
+yarn add @stimulcross/rate-limiter
+```

package/lib/core/cancellable.d.ts

@@ -0,0 +1,5 @@
+/** @internal */
+export interface Cancellable {
+    cancel(): void;
+}
+//# sourceMappingURL=cancellable.d.ts.map

package/lib/core/cancellable.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cancellable.js.map

package/lib/core/clock.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Clock interface.
+ */
+export interface Clock {
+    /**
+     * Returns the current timestamp in milliseconds.
+     */
+    now(): number;
+}
+//# sourceMappingURL=clock.d.ts.map

package/lib/core/clock.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=clock.js.map

package/{src/core/decision.ts → lib/core/decision.d.ts}

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

package/lib/core/decision.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decision.js.map

package/lib/core/rate-limit-policy.d.ts

@@ -0,0 +1,14 @@
+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;
+}
+//# sourceMappingURL=rate-limit-policy.d.ts.map

package/lib/core/rate-limit-policy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rate-limit-policy.js.map

package/lib/core/rate-limiter-status.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=rate-limiter-status.d.ts.map

package/lib/core/rate-limiter-status.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rate-limiter-status.js.map

package/lib/core/rate-limiter.d.ts

@@ -0,0 +1,34 @@
+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>;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/lib/core/rate-limiter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rate-limiter.js.map

package/lib/core/state-storage.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=state-storage.d.ts.map

package/lib/core/state-storage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=state-storage.js.map

package/lib/enums/rate-limit-error-code.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Rate limiter error codes.
+ */
+export declare 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"
+}
+//# sourceMappingURL=rate-limit-error-code.d.ts.map

package/lib/enums/rate-limit-error-code.js

@@ -0,0 +1,27 @@
+/**
+ * Rate limiter error codes.
+ */
+export var RateLimitErrorCode;
+(function (RateLimitErrorCode) {
+    /**
+     * Indicates that the limit has been reached.
+     */
+    RateLimitErrorCode["LimitExceeded"] = "LIMIT_EXCEEDED";
+    /**
+     * Indicates that the execution queue is full.
+     */
+    RateLimitErrorCode["QueueOverflow"] = "QUEUE_OVERFLOW";
+    /**
+     * Indicates that the task has expired.
+     */
+    RateLimitErrorCode["Expired"] = "EXPIRED";
+    /**
+     * Indicates that a task was cleared before it was executed.
+     */
+    RateLimitErrorCode["Destroyed"] = "DESTROYED";
+    /**
+     * Indicates that a task was canceled via abort controller before it was executed.
+     */
+    RateLimitErrorCode["Cancelled"] = "CANCELLED";
+})(RateLimitErrorCode || (RateLimitErrorCode = {}));
+//# sourceMappingURL=rate-limit-error-code.js.map

package/lib/errors/custom.error.d.ts

@@ -0,0 +1,6 @@
+/** @internal */
+export declare abstract class CustomError extends Error {
+    protected constructor(message: string);
+    get name(): string;
+}
+//# sourceMappingURL=custom.error.d.ts.map

package/lib/errors/custom.error.js

@@ -0,0 +1,13 @@
+/** @internal */
+export class CustomError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        Error.captureStackTrace?.(this, new.target.constructor);
+    }
+    get name() {
+        return this.constructor.name;
+    }
+}
+//# sourceMappingURL=custom.error.js.map

package/lib/errors/invalid-cost.error.d.ts

@@ -0,0 +1,16 @@
+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 declare class InvalidCostError extends CustomError {
+    private readonly _cost;
+    constructor(message: string, _cost: number);
+    get cost(): number;
+    toJSON(): InvalidCostErrorPlainObject;
+}
+//# sourceMappingURL=invalid-cost.error.d.ts.map

package/lib/errors/invalid-cost.error.js

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

package/lib/errors/rate-limit.error.d.ts

@@ -0,0 +1,37 @@
+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 declare class RateLimitError extends Error {
+    private readonly _code;
+    private readonly _retryAt;
+    /** @internal */
+    constructor(code: RateLimitErrorCode, retryAt?: number, message?: string);
+    /**
+     * The error code.
+     */
+    get code(): RateLimitErrorCode;
+    /**
+     * The timestamp (in milliseconds) when the task can be retried.
+     *
+     * Can be `null` if the retry time is not known.
+     */
+    get retryAt(): number | null;
+    toJSON(): RateLimitErrorPlainObject;
+}
+//# sourceMappingURL=rate-limit.error.d.ts.map

package/lib/errors/rate-limit.error.js

@@ -0,0 +1,75 @@
+import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
+/**
+ * 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 {
+    _code;
+    _retryAt;
+    /** @internal */
+    constructor(code, retryAt, message) {
+        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.
+     */
+    get code() {
+        return this._code;
+    }
+    /**
+     * The timestamp (in milliseconds) when the task can be retried.
+     *
+     * Can be `null` if the retry time is not known.
+     */
+    get retryAt() {
+        return this._retryAt ?? null;
+    }
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this._code,
+            retryAt: this._retryAt,
+            stack: this.stack,
+        };
+    }
+}
+//# sourceMappingURL=rate-limit.error.js.map

package/lib/errors/rate-limiter-destroyed.error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * An error thrown when running a task on a destroyed rate limiter.
+ */
+export declare class RateLimiterDestroyedError extends Error {
+    constructor();
+}
+//# sourceMappingURL=rate-limiter-destroyed.error.d.ts.map

package/lib/errors/rate-limiter-destroyed.error.js

@@ -0,0 +1,9 @@
+/**
+ * An error thrown when running a task on a destroyed rate limiter.
+ */
+export class RateLimiterDestroyedError extends Error {
+    constructor() {
+        super('Rate limiter has been destroyed and cannot be used.');
+    }
+}
+//# sourceMappingURL=rate-limiter-destroyed.error.js.map

package/{src/index.ts → lib/index.d.ts}

@@ -9,3 +9,4 @@ export { type RateLimitErrorPlainObject, RateLimitError } from './errors/rate-li
 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';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,5 @@
+export { RateLimitError } from './errors/rate-limit.error.js';
+export { RateLimiterDestroyedError } from './errors/rate-limiter-destroyed.error.js';
+export { InvalidCostError } from './errors/invalid-cost.error.js';
+export { RateLimitErrorCode } from './enums/rate-limit-error-code.js';
+//# sourceMappingURL=index.js.map

package/lib/interfaces/rate-limiter-options.d.ts

@@ -0,0 +1,76 @@
+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;
+}
+//# sourceMappingURL=rate-limiter-options.d.ts.map

package/lib/interfaces/rate-limiter-options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rate-limiter-options.js.map

package/lib/interfaces/rate-limiter-queue-options.d.ts

@@ -0,0 +1,42 @@
+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;
+}
+//# sourceMappingURL=rate-limiter-queue-options.d.ts.map

package/lib/interfaces/rate-limiter-queue-options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rate-limiter-queue-options.js.map

package/lib/interfaces/rate-limiter-run-options.d.ts

@@ -0,0 +1,52 @@
+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;
+}
+//# sourceMappingURL=rate-limiter-run-options.d.ts.map