@stimulcross/rate-limiter 0.0.1 → 0.0.3

package/lib/limiters/sliding-window-log/sliding-window-log.status.d.ts

@@ -0,0 +1,39 @@
+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;
+}
+//# sourceMappingURL=sliding-window-log.status.d.ts.map

package/lib/limiters/sliding-window-log/sliding-window-log.status.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sliding-window-log.status.js.map

package/{src/limiters/token-bucket/index.ts → lib/limiters/token-bucket/index.d.ts}

@@ -2,3 +2,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';
+//# sourceMappingURL=index.d.ts.map

package/lib/limiters/token-bucket/index.js

@@ -0,0 +1,2 @@
+export { TokenBucketLimiter } from './token-bucket.limiter.js';
+//# sourceMappingURL=index.js.map

package/lib/limiters/token-bucket/token-bucket.limiter.d.ts

@@ -0,0 +1,30 @@
+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 { 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 declare class TokenBucketLimiter extends AbstractRateLimiter<TokenBucketState, TokenBucketStatus> {
+    private readonly _defaultLimitBehaviour;
+    private readonly _maxWaitMs;
+    protected readonly _policy: TokenBucketPolicy;
+    constructor(options: TokenBucketOptions);
+    protected _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T>;
+    protected _getDebugStateString(state: TokenBucketState): string;
+    private _printSuccessDebug;
+}
+//# sourceMappingURL=token-bucket.limiter.d.ts.map

package/lib/limiters/token-bucket/token-bucket.limiter.js

@@ -0,0 +1,75 @@
+import { LogLevel } from '@stimulcross/logger';
+import { TokenBucketPolicy } from './token-bucket.policy.js';
+import { RateLimitErrorCode } from '../../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../../errors/rate-limit.error.js';
+import { AbstractRateLimiter } 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 {
+    _defaultLimitBehaviour;
+    _maxWaitMs;
+    _policy;
+    constructor(options) {
+        super(options);
+        this._defaultLimitBehaviour = options.limitBehavior ?? 'reject';
+        if (options.queue?.maxWaitMs) {
+            this._maxWaitMs = options.queue.maxWaitMs;
+        }
+        this._policy = new TokenBucketPolicy(options.capacity, options.refillRate);
+    }
+    async _runInternal(fn, ctx) {
+        const now = this._clock.now();
+        const baseTtlMs = Math.ceil(this._policy.capacity / (this._policy.refillRate / 1000));
+        let runAt;
+        let storeTtlMs;
+        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);
+    }
+    _getDebugStateString(state) {
+        return `tkn: ${state.tokens.toFixed(2)}/${this._policy.capacity}, deb: ${state.debt.toFixed(2)}`;
+    }
+    _printSuccessDebug(decision, nextState, now, ctx) {
+        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}`);
+        }
+    }
+}
+//# sourceMappingURL=token-bucket.limiter.js.map

package/{src/limiters/token-bucket/token-bucket.options.ts → lib/limiters/token-bucket/token-bucket.options.d.ts}

@@ -1,17 +1,16 @@
 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;
+    /**
+     * 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;
 }
+//# sourceMappingURL=token-bucket.options.d.ts.map

package/lib/limiters/token-bucket/token-bucket.options.js

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

package/lib/limiters/token-bucket/token-bucket.policy.d.ts

@@ -0,0 +1,19 @@
+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';
+/** @internal */
+export declare class TokenBucketPolicy implements RateLimitPolicy<TokenBucketState, TokenBucketStatus> {
+    private readonly _capacity;
+    private readonly _refillRate;
+    private readonly _maxDebt;
+    constructor(_capacity: number, _refillRate: number, _maxDebt?: number);
+    get capacity(): number;
+    get refillRate(): number;
+    getInitialState(): TokenBucketState;
+    getStatus(state: TokenBucketState, now: number): TokenBucketStatus;
+    evaluate(state: TokenBucketState, now: number, cost: number, shouldReserve?: boolean): RateLimitPolicyResult<TokenBucketState>;
+    revert(state: TokenBucketState, cost: number, now: number): TokenBucketState;
+    private _deny;
+    private _syncState;
+}
+//# sourceMappingURL=token-bucket.policy.d.ts.map

package/lib/limiters/token-bucket/token-bucket.policy.js

@@ -0,0 +1,116 @@
+import { validateCost } from '../../utils/validate-cost.js';
+/** @internal */
+export class TokenBucketPolicy {
+    _capacity;
+    _refillRate;
+    _maxDebt;
+    constructor(_capacity, _refillRate, _maxDebt = Number.POSITIVE_INFINITY) {
+        this._capacity = _capacity;
+        this._refillRate = _refillRate;
+        this._maxDebt = _maxDebt;
+        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.`);
+        }
+    }
+    get capacity() {
+        return this._capacity;
+    }
+    get refillRate() {
+        return this._refillRate;
+    }
+    getInitialState() {
+        return { tokens: this._capacity, debt: 0, lastRefill: 0 };
+    }
+    getStatus(state, now) {
+        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,
+        };
+    }
+    evaluate(state, now, cost, shouldReserve) {
+        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);
+    }
+    revert(state, cost, now) {
+        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 };
+    }
+    _deny(tokens, debt, lastRefill, retryAt) {
+        return {
+            decision: { kind: 'deny', retryAt },
+            nextState: { tokens, debt, lastRefill },
+        };
+    }
+    _syncState(state, now) {
+        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 };
+    }
+}
+//# sourceMappingURL=token-bucket.policy.js.map

package/{src/limiters/token-bucket/token-bucket.state.ts → lib/limiters/token-bucket/token-bucket.state.d.ts}

@@ -4,7 +4,8 @@
  * When using a distributed state store, make sure it properly serializes and deserializes the state.
  */
 export interface TokenBucketState {
-	tokens: number;
-	debt: number;
-	lastRefill: number;
+    tokens: number;
+    debt: number;
+    lastRefill: number;
 }
+//# sourceMappingURL=token-bucket.state.d.ts.map

package/lib/limiters/token-bucket/token-bucket.state.js

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

package/lib/limiters/token-bucket/token-bucket.status.d.ts

@@ -0,0 +1,31 @@
+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;
+}
+//# sourceMappingURL=token-bucket.status.d.ts.map

package/lib/limiters/token-bucket/token-bucket.status.js

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

package/lib/runtime/default-clock.d.ts

@@ -0,0 +1,4 @@
+import { type Clock } from '../core/clock.js';
+/** @internal */
+export declare const defaultClock: Clock;
+//# sourceMappingURL=default-clock.d.ts.map

package/lib/runtime/default-clock.js

@@ -0,0 +1,7 @@
+/** @internal */
+export const defaultClock = {
+    now() {
+        return Date.now();
+    },
+};
+//# sourceMappingURL=default-clock.js.map

package/lib/runtime/execution-tickets.d.ts

@@ -0,0 +1,12 @@
+/** @internal */
+export declare class ExecutionTickets {
+    private readonly _tickets;
+    get size(): number;
+    get isEmpty(): boolean;
+    add(tick: number): void;
+    peek(): number | undefined;
+    consume(): number | undefined;
+    dropLast(): number | undefined;
+    clear(): void;
+}
+//# sourceMappingURL=execution-tickets.d.ts.map

package/lib/runtime/execution-tickets.js

@@ -0,0 +1,27 @@
+import { Deque } from '@stimulcross/ds-deque';
+/** @internal */
+export class ExecutionTickets {
+    _tickets = new Deque();
+    get size() {
+        return this._tickets.size;
+    }
+    get isEmpty() {
+        return this._tickets.size === 0;
+    }
+    add(tick) {
+        this._tickets.push(tick);
+    }
+    peek() {
+        return this._tickets.peekHead();
+    }
+    consume() {
+        return this._tickets.shift();
+    }
+    dropLast() {
+        return this._tickets.pop();
+    }
+    clear() {
+        this._tickets.clear();
+    }
+}
+//# sourceMappingURL=execution-tickets.js.map

package/lib/runtime/in-memory-state-store.d.ts

@@ -0,0 +1,19 @@
+import { type Clock } from '../core/clock.js';
+import { type StateStorage } from '../core/state-storage.js';
+/** @internal */
+export declare class InMemoryStateStore<V> implements StateStorage<V> {
+    private readonly _clock;
+    private readonly _state;
+    private readonly _activeLocks;
+    private readonly _waitingResolvers;
+    private readonly _cleanupTimer;
+    constructor(_clock: Clock);
+    get(key: string): Promise<V | null>;
+    set(key: string, value: V, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    destroy(): Promise<void>;
+    acquireLock(key: string): Promise<void>;
+    releaseLock(key: string): Promise<void>;
+}
+//# sourceMappingURL=in-memory-state-store.d.ts.map

package/lib/runtime/in-memory-state-store.js

@@ -0,0 +1,97 @@
+import { Deque } from '@stimulcross/ds-deque';
+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';
+const CLEANUP_INTERVAL_MS = 60_000;
+/** @internal */
+export class InMemoryStateStore {
+    _clock;
+    _state = new Map();
+    _activeLocks = new Set();
+    _waitingResolvers = new Map();
+    _cleanupTimer;
+    constructor(_clock) {
+        this._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();
+        }
+    }
+    async get(key) {
+        const entry = this._state.get(key);
+        if (entry?.expiresAt && entry.expiresAt <= this._clock.now()) {
+            this._state.delete(key);
+            return null;
+        }
+        return entry?.value ?? null;
+    }
+    async set(key, value, ttlMs) {
+        const entry = { value };
+        if (typeof ttlMs === 'number') {
+            if (ttlMs <= 0) {
+                this._state.delete(key);
+                return;
+            }
+            entry.expiresAt = this._clock.now() + ttlMs;
+        }
+        this._state.set(key, entry);
+    }
+    async delete(key) {
+        this._state.delete(key);
+    }
+    async clear() {
+        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();
+    }
+    async destroy() {
+        clearInterval(this._cleanupTimer);
+        await this.clear();
+    }
+    async acquireLock(key) {
+        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);
+        }
+    }
+    async releaseLock(key) {
+        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);
+        }
+    }
+}
+//# sourceMappingURL=in-memory-state-store.js.map

package/lib/runtime/rate-limiter.executor.d.ts

@@ -0,0 +1,47 @@
+import { type SelectionPolicy } from '@stimulcross/ds-policy-priority-queue';
+import { type Logger } from '@stimulcross/logger';
+import { type Clock } from '../core/clock.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 declare class RateLimiterExecutor {
+    private readonly _logger;
+    private readonly _clock;
+    private readonly _tickets;
+    private readonly _semaphore;
+    private readonly _queue;
+    private readonly _expiryHeap;
+    private _drainTimer;
+    private _expiryTimer;
+    private _nextExpiryScheduledAt;
+    constructor(_logger: Logger, clock: Clock, { concurrency, capacity, selectionPolicy }?: RateLimiterExecutorQueueOptions);
+    get isQueueFull(): boolean;
+    get queueSize(): number;
+    get queueCapacity(): number;
+    execute<T>(fn: () => T | Promise<T>, runAt: number, options: RateLimiterExecutionOptions): Promise<T>;
+    clear(): void;
+    private get _shouldPrintDebug();
+    private _drain;
+    private _getNextExpiryTimestamp;
+    private _extractExpiredTasks;
+    private _drainRemainingTasks;
+    private _scheduleDrainTimer;
+    private _recalibrateExpiryTimer;
+    private _clearDrainTimer;
+    private _clearExpiryTimer;
+    private _getStateDebugString;
+}
+//# sourceMappingURL=rate-limiter.executor.d.ts.map