@stimulcross/rate-limiter 0.0.1

package/src/limiters/leaky-bucket/leaky-bucket.options.ts

@@ -0,0 +1,23 @@
+import { type LeakyBucketState } from './leaky-bucket.state.js';
+import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
+
+/**
+ * Options for the Leaky Bucket rate limiter.
+ */
+export interface LeakyBucketOptions extends RateLimiterOptions<LeakyBucketState> {
+	/**
+	 * The maximum number of requests that can be queued in the bucket.
+	 *
+	 * In the Leaky Bucket algorithm, this represents the maximum depth of the bucket
+	 * that holds incoming requests before they leak out at a constant rate.
+	 */
+	capacity: number;
+
+	/**
+	 * The rate at which requests are processed from the bucket (requests per second).
+	 *
+	 * This defines the constant rate at which requests "leak" out of the bucket
+	 * and are allowed to proceed.
+	 */
+	leakRate: number;
+}

package/src/limiters/leaky-bucket/leaky-bucket.policy.ts

@@ -0,0 +1,134 @@
+import { type LeakyBucketState } from './leaky-bucket.state.js';
+import { type LeakyBucketStatus } from './leaky-bucket.status.js';
+import { type RateLimitPolicy, type RateLimitPolicyResult } from '../../core/rate-limit-policy.js';
+import { validateCost } from '../../utils/validate-cost.js';
+
+/** @internal */
+export class LeakyBucketPolicy implements RateLimitPolicy<LeakyBucketState, LeakyBucketStatus> {
+	constructor(
+		private readonly _capacity: number,
+		private readonly _leakRate: number,
+		private readonly _maxOverflow: number = Number.POSITIVE_INFINITY,
+	) {
+		if (!Number.isFinite(_capacity) || !Number.isSafeInteger(_capacity) || _capacity <= 0) {
+			throw new Error(`Invalid capacity: ${_capacity}. Must be a positive integer.`);
+		}
+
+		if (!Number.isFinite(_leakRate) || _leakRate <= 0) {
+			throw new Error(`Invalid leakRate: ${_leakRate}. Must be a positive number.`);
+		}
+
+		if (_maxOverflow < 0 || (!Number.isSafeInteger(_maxOverflow) && _maxOverflow !== Number.POSITIVE_INFINITY)) {
+			throw new Error(`Invalid maxOverflow: ${_maxOverflow}. Must be a non-negative integer or Infinity.`);
+		}
+	}
+
+	public get capacity(): number {
+		return this._capacity;
+	}
+
+	public get leakRate(): number {
+		return this._leakRate;
+	}
+
+	public getInitialState(): LeakyBucketState {
+		return { level: 0, lastUpdate: 0 };
+	}
+
+	public getStatus(state: LeakyBucketState, now: number): LeakyBucketStatus {
+		const { level } = this._syncState(state, now);
+
+		const volumeToClearForOne = Math.max(0, level + 1 - this._capacity);
+		const nextAvailableAt =
+			volumeToClearForOne === 0 ? now : now + Math.ceil((volumeToClearForOne / this._leakRate) * 1000);
+
+		const resetAt = level === 0 ? now : now + Math.ceil((level / this._leakRate) * 1000);
+
+		return {
+			capacity: this._capacity,
+			leakRate: this._leakRate,
+			level,
+			remaining: Math.max(0, this._capacity - level),
+			nextAvailableAt,
+			resetAt,
+		};
+	}
+
+	public evaluate(
+		state: LeakyBucketState,
+		now: number,
+		cost: number,
+		shouldReserve?: boolean,
+	): RateLimitPolicyResult<LeakyBucketState> {
+		validateCost(cost, this._capacity);
+
+		const { level, lastUpdate } = this._syncState(state, now);
+		const nextLevel = level + cost;
+
+		if (nextLevel <= this._capacity) {
+			return {
+				decision: { kind: 'allow' },
+				nextState: { level: nextLevel, lastUpdate },
+			};
+		}
+
+		const overflow = nextLevel - this._capacity;
+
+		if (shouldReserve) {
+			if (overflow > this._maxOverflow) {
+				const volumeToLeak = nextLevel - (this._capacity + this._maxOverflow);
+				const waitMs = Math.ceil((volumeToLeak / this._leakRate) * 1000);
+				const retryAt = now + waitMs;
+
+				return this._deny(level, lastUpdate, retryAt);
+			}
+
+			const waitMs = Math.ceil((overflow / this._leakRate) * 1000);
+			const runAt = now + waitMs;
+
+			return {
+				decision: { kind: 'delay', runAt },
+				nextState: { level: nextLevel, lastUpdate },
+			};
+		}
+
+		const waitMs = Math.ceil((overflow / this._leakRate) * 1000);
+		const retryAt = now + waitMs;
+
+		return this._deny(level, lastUpdate, retryAt);
+	}
+
+	public revert(state: LeakyBucketState, cost: number, now: number): LeakyBucketState {
+		const { level, lastUpdate } = this._syncState(state, now);
+
+		return {
+			level: Math.max(0, level - cost),
+			lastUpdate,
+		};
+	}
+
+	private _deny(level: number, lastUpdate: number, retryAt: number): RateLimitPolicyResult<LeakyBucketState> {
+		return {
+			decision: { kind: 'deny', retryAt },
+			nextState: { level, lastUpdate },
+		};
+	}
+
+	private _syncState(state: LeakyBucketState, now: number): LeakyBucketState {
+		if (state.lastUpdate === 0) {
+			return { level: 0, lastUpdate: now };
+		}
+
+		if (now <= state.lastUpdate) {
+			return state;
+		}
+
+		const elapsedMs = now - state.lastUpdate;
+		const leaked = (elapsedMs / 1000) * this._leakRate;
+
+		return {
+			level: Math.max(0, state.level - leaked),
+			lastUpdate: now,
+		};
+	}
+}

package/src/limiters/leaky-bucket/leaky-bucket.state.ts

@@ -0,0 +1,9 @@
+/**
+ * Leaky Bucket rate limiter state.
+ *
+ * When using a distributed state store, make sure it properly serializes and deserializes the state.
+ */
+export interface LeakyBucketState {
+	level: number;
+	lastUpdate: number;
+}

package/src/limiters/leaky-bucket/leaky-bucket.status.ts

@@ -0,0 +1,36 @@
+import { type RateLimiterStatus } from '../../core/rate-limiter-status.js';
+
+/**
+ * The status of the Leaky Bucket rate limiter.
+ */
+export interface LeakyBucketStatus extends RateLimiterStatus {
+	/**
+	 * The maximum capacity of the bucket (maximum number of requests that can be queued).
+	 */
+	capacity: number;
+
+	/**
+	 * The rate at which requests leak from the bucket (requests per second).
+	 */
+	leakRate: number;
+
+	/**
+	 * The current number of requests in the bucket waiting to be processed.
+	 */
+	level: number;
+
+	/**
+	 * The number of requests that can still be added to the bucket before reaching capacity.
+	 */
+	remaining: number;
+
+	/**
+	 * Timestamp (in milliseconds) when the next request slot will become available.
+	 */
+	nextAvailableAt: number;
+
+	/**
+	 * Timestamp (in milliseconds) when all queued requests will have leaked (bucket becomes empty).
+	 */
+	resetAt: number;
+}

package/src/limiters/sliding-window-counter/index.ts

@@ -0,0 +1,7 @@
+export type { SlidingWindowCounterState } from './sliding-window-counter.state.js';
+export type { SlidingWindowCounterStatus } from './sliding-window-counter.status.js';
+export type { SlidingWindowCounterOptions } from './sliding-window-counter.options.js';
+export {
+	type SlidingWindowCounterLimiterRunOptions,
+	SlidingWindowCounterLimiter,
+} from './sliding-window-counter.limiter.js';

package/src/limiters/sliding-window-counter/sliding-window-counter.limiter.ts

@@ -0,0 +1,76 @@
+import { type SlidingWindowCounterOptions } from './sliding-window-counter.options.js';
+import { SlidingWindowCounterPolicy } from './sliding-window-counter.policy.js';
+import { type SlidingWindowCounterState } from './sliding-window-counter.state.js';
+import { type SlidingWindowCounterStatus } from './sliding-window-counter.status.js';
+import { RateLimitErrorCode } from '../../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../../errors/rate-limit.error.js';
+import { type RateLimiterRunOptions } from '../../interfaces/rate-limiter-run-options.js';
+import { AbstractRateLimiter, type ExecutionContext } from '../abstract-rate-limiter.js';
+
+/**
+ * The options for running a task in the Sliding Window Counter rate limiter.
+ */
+export type SlidingWindowCounterLimiterRunOptions = Omit<
+	RateLimiterRunOptions,
+	'limitBehavior' | 'priority' | 'maxWaitMs'
+>;
+
+/**
+ * Sliding Window Counter 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.
+ *
+ * Note: Unlike queue-based limiters, this implementation operates in strict immediate mode.
+ * It does not support request queueing, delays, priorities, or task cancellation.
+ */
+export class SlidingWindowCounterLimiter extends AbstractRateLimiter<
+	SlidingWindowCounterState,
+	SlidingWindowCounterStatus
+> {
+	protected override readonly _policy: SlidingWindowCounterPolicy;
+
+	private readonly _storeTtl: number;
+
+	constructor(options: SlidingWindowCounterOptions) {
+		super(options);
+
+		this._policy = new SlidingWindowCounterPolicy(options.limit, options.windowMs);
+		this._storeTtl = options.windowMs * 2;
+	}
+
+	protected override async _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T> {
+		const now = this._clock.now();
+
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const state = (await this._store.get(ctx.key)) ?? this._policy.getInitialState();
+
+			const { decision, nextState } = this._policy.evaluate(state, now, ctx.cost);
+
+			if (decision.kind === 'deny') {
+				this._shouldPrintDebug &&
+					this._logger.debug(`[DENY] [id: ${ctx.id}, key: ${ctx.key}] - Retry: +${decision.retryAt - now}ms`);
+
+				throw new RateLimitError(RateLimitErrorCode.LimitExceeded, decision.retryAt);
+			}
+
+			await this._store.set(ctx.key, nextState, this._storeTtl);
+
+			this._shouldPrintDebug &&
+				this._logger.debug(
+					`[ALLOW] [id: ${ctx.id}, key: ${ctx.key}] - ${this._getDebugStateString(nextState)}`,
+				);
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+
+		return await this._execute(fn, now, this._storeTtl, ctx);
+	}
+
+	protected override _getDebugStateString(state: SlidingWindowCounterState): string {
+		return `lim: ${this._policy.limit}; c/p: ${state.currentCount}/${state.previousCount}`;
+	}
+}

package/src/limiters/sliding-window-counter/sliding-window-counter.options.ts

@@ -0,0 +1,20 @@
+import { type SlidingWindowCounterState } from './sliding-window-counter.state.js';
+import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
+
+/**
+ * Options for the Sliding Window Counter rate limiter.
+ */
+export interface SlidingWindowCounterOptions extends Omit<
+	RateLimiterOptions<SlidingWindowCounterState>,
+	'queue' | 'limitBehavior'
+> {
+	/**
+	 * Maximum number of requests allowed within the time window.
+	 */
+	limit: number;
+
+	/**
+	 * Duration of the time window in milliseconds.
+	 */
+	windowMs: number;
+}

package/src/limiters/sliding-window-counter/sliding-window-counter.policy.ts

@@ -0,0 +1,167 @@
+import { type SlidingWindowCounterState } from './sliding-window-counter.state.js';
+import { type SlidingWindowCounterStatus } from './sliding-window-counter.status.js';
+import { type RateLimitPolicy, type RateLimitPolicyResult } from '../../core/rate-limit-policy.js';
+import { validateCost } from '../../utils/validate-cost.js';
+
+/** @internal */
+export class SlidingWindowCounterPolicy implements RateLimitPolicy<
+	SlidingWindowCounterState,
+	SlidingWindowCounterStatus
+> {
+	constructor(
+		private readonly _limit: number,
+		private readonly _windowMs: number,
+	) {
+		if (!Number.isFinite(_limit) || !Number.isInteger(_limit) || _limit < 0) {
+			throw new Error(`Invalid limit: ${_limit}. Must be a positive integer.`);
+		}
+
+		if (!Number.isFinite(_windowMs) || !Number.isInteger(_windowMs) || _windowMs <= 0) {
+			throw new Error(`Invalid windowMs: ${_windowMs}. Must be a positive integer.`);
+		}
+	}
+
+	public get limit(): number {
+		return this._limit;
+	}
+
+	public get windowMs(): number {
+		return this._windowMs;
+	}
+
+	public getInitialState(): SlidingWindowCounterState {
+		return {
+			windowStart: 0,
+			currentCount: 0,
+			previousCount: 0,
+		};
+	}
+
+	public getStatus(state: SlidingWindowCounterState, now: number): SlidingWindowCounterStatus {
+		const syncedState = this._syncState(state, now);
+		const { windowStart, previousCount, currentCount } = syncedState;
+
+		const timeIntoCurrentWindow = now - windowStart;
+		const weight = (this._windowMs - timeIntoCurrentWindow) / this._windowMs;
+		const estimatedCount = Math.floor(previousCount * weight + currentCount);
+
+		const remaining = Math.max(0, this._limit - estimatedCount);
+
+		const nextAvailableAt = this._calculateAvailableAt(windowStart, previousCount, currentCount, 1, now);
+
+		let resetAt: number;
+
+		if (currentCount > 0) {
+			resetAt = windowStart + 2 * this._windowMs;
+		} else if (previousCount > 0) {
+			resetAt = windowStart + this._windowMs;
+		} else {
+			resetAt = now;
+		}
+
+		return {
+			limit: this._limit,
+			windowMs: this._windowMs,
+			windowStart,
+			currentCount,
+			previousCount,
+			estimatedCount,
+			remaining,
+			nextAvailableAt,
+			resetAt,
+		};
+	}
+
+	public evaluate(
+		state: SlidingWindowCounterState,
+		now: number,
+		cost: number,
+	): RateLimitPolicyResult<SlidingWindowCounterState> {
+		validateCost(cost, this._limit);
+
+		const syncedState = this._syncState(state, now);
+		const { windowStart, previousCount, currentCount } = syncedState;
+
+		const timeIntoCurrentWindow = now - windowStart;
+		const weight = (this._windowMs - timeIntoCurrentWindow) / this._windowMs;
+		const estimatedCount = Math.floor(previousCount * weight + currentCount);
+
+		if (estimatedCount + cost <= this._limit) {
+			return {
+				decision: { kind: 'allow' },
+				nextState: {
+					windowStart,
+					previousCount,
+					currentCount: currentCount + cost,
+				},
+			};
+		}
+
+		const availableAt = this._calculateAvailableAt(windowStart, previousCount, currentCount, cost, now);
+
+		return {
+			decision: { kind: 'deny', retryAt: availableAt },
+			nextState: syncedState,
+		};
+	}
+
+	public revert(state: SlidingWindowCounterState, cost: number, now: number): SlidingWindowCounterState {
+		if (cost <= 0) {
+			return state;
+		}
+
+		const syncedState = this._syncState(state, now);
+
+		return {
+			...syncedState,
+			currentCount: Math.max(0, syncedState.currentCount - cost),
+		};
+	}
+
+	private _syncState(state: SlidingWindowCounterState, now: number): SlidingWindowCounterState {
+		const currentWindowStart = Math.floor(now / this._windowMs) * this._windowMs;
+
+		if (currentWindowStart <= state.windowStart) {
+			return state;
+		}
+
+		const windowsPassed = Math.floor((currentWindowStart - state.windowStart) / this._windowMs);
+
+		if (windowsPassed > 1) {
+			return { windowStart: currentWindowStart, previousCount: 0, currentCount: 0 };
+		}
+
+		return {
+			windowStart: currentWindowStart,
+			previousCount: state.currentCount,
+			currentCount: 0,
+		};
+	}
+
+	private _calculateAvailableAt(windowStart: number, prev: number, curr: number, cost: number, now: number): number {
+		if (curr + cost <= this._limit) {
+			if (prev === 0) {
+				return now;
+			}
+
+			const numerator = this._windowMs * (prev + curr + cost - this._limit - 1);
+			const t = Math.max(0, Math.floor(numerator / prev) + 1);
+			const absoluteTime = windowStart + t;
+
+			return Math.max(now, absoluteTime);
+		}
+
+		const newPrev = curr;
+		const newWindowStart = windowStart + this._windowMs;
+
+		if (newPrev === 0) {
+			return Math.max(now, newWindowStart);
+		}
+
+		const numerator = this._windowMs * (newPrev + cost - this._limit - 1);
+		const t = Math.max(0, Math.floor(numerator / newPrev) + 1);
+		const absoluteTime = newWindowStart + t;
+
+		return Math.max(now, absoluteTime);
+	}
+}

package/src/limiters/sliding-window-counter/sliding-window-counter.state.ts

@@ -0,0 +1,10 @@
+/**
+ * Sliding Window Counter rate limiter state.
+ *
+ * When using a distributed state store, make sure it properly serializes and deserializes the state.
+ */
+export interface SlidingWindowCounterState {
+	windowStart: number;
+	currentCount: number;
+	previousCount: number;
+}

package/src/limiters/sliding-window-counter/sliding-window-counter.status.ts

@@ -0,0 +1,53 @@
+import { type RateLimiterStatus } from '../../core/rate-limiter-status.js';
+
+/**
+ * The status of the Sliding Window Counter rate limiter.
+ */
+export interface SlidingWindowCounterStatus extends RateLimiterStatus {
+	/**
+	 * Maximum number of requests allowed within the time window.
+	 */
+	limit: number;
+
+	/**
+	 * Duration of the time window in milliseconds.
+	 */
+	windowMs: number;
+
+	/**
+	 * Timestamp (in milliseconds) when the current window started.
+	 */
+	windowStart: number;
+
+	/**
+	 * Number of requests made in the current window.
+	 */
+	currentCount: number;
+
+	/**
+	 * Number of requests made in the previous window.
+	 */
+	previousCount: number;
+
+	/**
+	 * Estimated request count based on the sliding window algorithm.
+	 *
+	 * Calculated by combining current and previous window counts proportionally.
+	 */
+	estimatedCount: number;
+
+	/**
+	 * Number of requests remaining before hitting the limit.
+	 */
+	remaining: number;
+
+	/**
+	 * Timestamp (in milliseconds) when the next request slot becomes available.
+	 */
+	nextAvailableAt: number;
+
+	/**
+	 * Timestamp (in milliseconds) when the current window resets.
+	 */
+	resetAt: number;
+}

package/src/limiters/sliding-window-log/index.ts

@@ -0,0 +1,4 @@
+export type { SlidingWindowLogEntry, SlidingWindowLogState } from './sliding-window-log.state.js';
+export type { SlidingWindowLogStatus } from './sliding-window-log.status.js';
+export type { SlidingWindowLogOptions } from './sliding-window-log.options.js';
+export { type SlidingWindowLogLimiterRunOptions, SlidingWindowLogLimiter } from './sliding-window-log.limiter.js';

package/src/limiters/sliding-window-log/sliding-window-log.limiter.ts

@@ -0,0 +1,65 @@
+import { type SlidingWindowLogOptions } from './sliding-window-log.options.js';
+import { SlidingWindowLogPolicy } from './sliding-window-log.policy.js';
+import { type SlidingWindowLogState } from './sliding-window-log.state.js';
+import { type SlidingWindowLogStatus } from './sliding-window-log.status.js';
+import { RateLimitErrorCode } from '../../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../../errors/rate-limit.error.js';
+import { type RateLimiterRunOptions } from '../../interfaces/rate-limiter-run-options.js';
+import { AbstractRateLimiter, type ExecutionContext } from '../abstract-rate-limiter.js';
+
+/**
+ * The options for running a task in the Sliding Window Log rate limiter.
+ */
+export type SlidingWindowLogLimiterRunOptions = Omit<RateLimiterRunOptions, 'limitBehavior' | 'priority'>;
+
+/**
+ * Sliding Window Log 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.
+ *
+ * Note: Unlike queue-based limiters, this implementation operates in strict immediate mode.
+ * It does not support request queueing, delays, priorities, or task cancellation.
+ */
+export class SlidingWindowLogLimiter extends AbstractRateLimiter<SlidingWindowLogState, SlidingWindowLogStatus> {
+	protected override readonly _policy: SlidingWindowLogPolicy;
+
+	constructor(options: SlidingWindowLogOptions) {
+		super(options);
+
+		this._policy = new SlidingWindowLogPolicy(options.limit, options.windowMs);
+	}
+
+	protected override async _runInternal<T>(fn: () => T | Promise<T>, ctx: ExecutionContext): Promise<T> {
+		const now = this._clock.now();
+		const storeTtlMs = this._policy.windowMs;
+
+		await this._store.acquireLock?.(ctx.key);
+
+		try {
+			const state = (await this._store.get(ctx.key)) ?? this._policy.getInitialState();
+
+			const { decision, nextState } = this._policy.evaluate(state, now, ctx.cost);
+
+			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);
+			}
+
+			await this._store.set(ctx.key, nextState, storeTtlMs);
+
+			this._logger.debug(
+				`[ALLOW] [id: ${ctx.id}, key: ${ctx.key}] - used/lim: ${nextState.totalUsed}/${this._policy.limit} logs: ${nextState.logs.size}`,
+			);
+		} finally {
+			await this._store.releaseLock?.(ctx.key);
+		}
+
+		return await this._execute<T>(fn, now, storeTtlMs, ctx);
+	}
+
+	protected override _getDebugStateString(state: SlidingWindowLogState): string {
+		return `used/lim: ${state.totalUsed}/${this._policy.limit} logs: ${state.logs.size}`;
+	}
+}

package/src/limiters/sliding-window-log/sliding-window-log.options.ts

@@ -0,0 +1,20 @@
+import { type SlidingWindowLogState } from './sliding-window-log.state.js';
+import { type RateLimiterOptions } from '../../interfaces/rate-limiter-options.js';
+
+/**
+ * Options for the Sliding Window Log rate limiter.
+ */
+export interface SlidingWindowLogOptions extends Omit<
+	RateLimiterOptions<SlidingWindowLogState>,
+	'queue' | 'limitBehavior'
+> {
+	/**
+	 * Maximum number of requests allowed within the time window.
+	 */
+	limit: number;
+
+	/**
+	 * Duration of the time window in milliseconds.
+	 */
+	windowMs: number;
+}