@stimulcross/rate-limiter 0.0.1 → 0.0.2

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

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

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

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

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

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

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

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

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

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

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

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

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