@devhuset-oss/ratelimit/dist/index.d.mts

A flexible rate limiting library with support for fixed and sliding windows using Valkey

import Redis, { RedisOptions } from 'iovalkey';

declare class Valkey extends Redis {
    slidingWindowRateLimit: (keys: string[], limit: string, now: string, window: string, increment: string) => Promise<[number, number]>;
    constructor(port: number, host: string, options: RedisOptions);
    constructor(path: string, options: RedisOptions);
    constructor(port: number, options: RedisOptions);
    constructor(port: number, host: string);
    constructor(options: RedisOptions);
    constructor(port: number);
    constructor(path: string);
    constructor();
}

/**
 * Thrown when rate limiter configuration is invalid
 * @example
 * ```ts
 * throw new ConfigurationError('Limit must be greater than 0')
 * ```
 */
declare class ConfigurationError extends Error {
    constructor(message: string);
}
/**
 * Thrown when Valkey operations fail. Includes the original Valkey error if available
 * @example
 * ```ts
 * throw new ValkeyError('Failed to check rate limit', originalError)
 * ```
 */
declare class ValkeyError extends Error {
    originalError?: Error | undefined;
    constructor(message: string, originalError?: Error | undefined);
}

/**
 * Response from a rate limit check
 */
interface RatelimitResponse {
    /** Whether the request should be allowed */
    success: boolean;
    /** Maximum number of requests allowed in the window */
    limit: number;
    /** Number of remaining requests in current window */
    remaining: number;
    /** Time in milliseconds until the next request will be allowed. 0 if under limit */
    retry_after: number;
    /** Time in milliseconds when the current window expires completely */
    reset: number;
}
/**
 * Base configuration options for both fixed and sliding window rate limiters
 */
interface RatelimitOptionsWithoutType {
    /** Maximum number of requests allowed within the window */
    limit: number;
    /** Time window in seconds */
    window: number;
    /** Optional prefix for Valkey keys to prevent collisions */
    prefix?: string;
}
/**
 * Complete rate limiter configuration including window type
 */
interface RatelimitOptions extends RatelimitOptionsWithoutType {
    /** Type of rate limiting window to use */
    type: 'fixed' | 'sliding';
}

/**
 * Valkey-based rate limiter supporting both fixed and sliding window algorithms.
 * Fixed window divides time into discrete chunks while sliding window
 * provides smoother rate limiting using weighted scoring.
 */
declare class Ratelimit {
    private readonly options;
    private readonly time_provider;
    private readonly valkey;
    constructor(valkey: Valkey, options: RatelimitOptions, time_provider?: () => number);
    static fixedWindow(params: RatelimitOptionsWithoutType): RatelimitOptions;
    static slidingWindow(params: RatelimitOptionsWithoutType): RatelimitOptions;
    limit(identifier: string): Promise<RatelimitResponse>;
    private validateOptions;
    private getKey;
    private fixedWindowLimit;
    private slidingWindowLimit;
}

export { ConfigurationError, Ratelimit, type RatelimitOptions, type RatelimitOptionsWithoutType, type RatelimitResponse, Valkey, ValkeyError };