ts-rate-limiter/dist/types.d.ts

High-performance, flexible rate limiting for TypeScript and Bun

export declare interface RateLimiterConfig {
  verbose: boolean
  storage?: 'memory' | 'redis'
  algorithm?: 'fixed-window' | 'sliding-window' | 'token-bucket'
  windowMs?: number
  maxRequests?: number
  redisKeyPrefix?: string
  standardHeaders?: boolean
  legacyHeaders?: boolean
  draftMode?: boolean
  memoryStorage?: {
    enableAutoCleanup?: boolean
    cleanupIntervalMs?: number
  }
  redis?: {
    url?: string
    enableSlidingWindow?: boolean
  }
}
/**
 * Interface for storage providers that persist rate limit data.
 * Implement this interface to create custom storage backends.
 * @example
 * ```ts
 * class CustomStorage implements StorageProvider {
 *   async increment(key: string, windowMs: number) {
 *     // Implementation
 *     return { count: 1, resetTime: Date.now() + windowMs };
 *   }
 *
 *   async reset(key: string) {
 *     // Implementation
 *   }
 * }
 * ```
 */
export declare interface StorageProvider {
  increment: (key: string, windowMs: number) => Promise<{
    count: number
    resetTime: number
  }>
  reset: (key: string) => Promise<void>
  getCount?: (key: string) => Promise<number>
  getSlidingWindowCount?: (key: string, windowMs: number) => Promise<number>
  batchIncrement?: (keys: string[], windowMs: number) => Promise<Map<string, { count: number, resetTime: number }>>
  cleanExpired?: () => void
  dispose?: () => void
}
/**
 * Configuration options for creating a rate limiter instance.
 * These options control the behavior of the rate limiter.
 * @example
 * ```ts
 * const options: RateLimiterOptions = {
 *   windowMs: 60000,
 *   maxRequests: 100,
 *   algorithm: 'sliding-window',
 *   standardHeaders: true,
 *   legacyHeaders: false
 * };
 *
 * const rateLimiter = new RateLimiter(options);
 * ```
 */
export declare interface RateLimiterOptions {
  windowMs: number
  maxRequests: number
  storage?: StorageProvider
  keyGenerator?: (request: Request) => string | Promise<string>
  skipFailedRequests?: boolean
  algorithm?: RateLimitAlgorithm
  standardHeaders?: boolean
  legacyHeaders?: boolean
  skip?: (request: Request) => boolean | Promise<boolean>
  handler?: (request: Request, result: RateLimitResult) => Response | Promise<Response>
  draftMode?: boolean
}
/**
 * Result of a rate limit check, containing limit status and metrics.
 * Used to determine if a request is allowed and to generate headers.
 * @example
 * ```ts
 * // Example result for an allowed request
 * {
 *   allowed: true,
 *   current: 43,
 *   limit: 100,
 *   remaining: 30000,  // 30 seconds until reset
 *   resetTime: 1623967458000
 * }
 *
 * // Example result for a blocked request
 * {
 *   allowed: false,
 *   current: 101,
 *   limit: 100,
 *   remaining: 15000,  // 15 seconds until reset
 *   resetTime: 1623967443000
 * }
 * ```
 */
export declare interface RateLimitResult {
  allowed: boolean
  current: number
  limit: number
  remaining: number
  resetTime: number
}
/**
 * Configuration options for the token bucket algorithm.
 * Models rate limits as tokens that refill at a constant rate.
 * @example
 * ```ts
 * const tokenBucket: TokenBucketOptions = {
 *   capacity: 100,  // Bucket size
 *   refillRate: 0.5 // 0.5 tokens per ms = 30 tokens per second
 * };
 * ```
 */
export declare interface TokenBucketOptions {
  capacity: number
  refillRate: number
}
/**
 * Configuration options for Redis-based storage.
 * Used when creating a RedisStorage instance.
 * @example
 * ```ts
 * const redisOptions: RedisStorageOptions = {
 *   client: redisClient,
 *   keyPrefix: 'api:rate-limit:',
 *   enableSlidingWindow: true
 * };
 *
 * const storage = new RedisStorage(redisOptions);
 * ```
 */
export declare interface RedisStorageOptions {
  client: any
  keyPrefix?: string
  enableSlidingWindow?: boolean
}
/**
 * Configuration options for memory-based storage.
 * Used when creating a MemoryStorage instance.
 * @example
 * ```ts
 * const memOptions: MemoryStorageOptions = {
 *   enableAutoCleanup: true,
 *   cleanupIntervalMs: 30000 // 30 seconds
 * };
 *
 * const storage = new MemoryStorage(memOptions);
 * ```
 */
export declare interface MemoryStorageOptions {
  enableAutoCleanup?: boolean
  cleanupIntervalMs?: number
}
/**
 * Supported algorithms for rate limiting calculations.
 * Each algorithm has different characteristics for accuracy and resource usage.
 * @example
 * ```ts
 * const algorithm: RateLimitAlgorithm = 'sliding-window';
 * ```
 */
export type RateLimitAlgorithm = 'fixed-window' |
  /** Tracks requests over a continuously moving time window for more accurate limiting */
  'sliding-window' |
  /** Models rate limits as tokens that refill at a constant rate, smoothing traffic */
  'token-bucket';