TypeScript Types

interface HitLimitOptions<TRequest = any> {
  /** Maximum requests per window */
  limit?: number

  /** Time window (e.g., '1m', '1h', 60000) */
  window?: string | number

  /** Key extraction function */
  key?: (req: TRequest) => string | Promise<string>

  /** Tiered rate limits by tier name */
  tiers?: Record<string, { limit: number; window?: string | number }>

  /** Resolve tier name per request */
  tier?: (req: TRequest) => string | Promise<string>

  /** Custom error response body */
  response?: object | ((info: HitLimitInfo) => object)

  /** Rate limit response headers config */
  headers?: HeadersConfig

  /** Storage backend */
  store?: HitLimitStore

  /** Handler called when the store throws */
  onStoreError?: (err: unknown, req: TRequest) => void

  /** Skip rate limiting for certain requests */
  skip?: (req: TRequest) => boolean | Promise<boolean>

  /** Logger for internal events */
  logger?: { warn(msg: string): void }

  /** Ban configuration */
  ban?: { threshold: number; duration: string | number }

  /** Group identifier for shared rate limits */
  group?: string | ((req: TRequest) => string)
}

interface HeadersConfig {
  /** RateLimit-* headers (IETF draft) */
  standard?: boolean

  /** X-RateLimit-* legacy headers */
  legacy?: boolean

  /** Retry-After header on 429 responses */
  retryAfter?: boolean
}

interface HitLimitInfo {
  limit: number
  remaining: number
  resetIn: number    // seconds until window resets
  resetAt: number    // unix timestamp (ms)
  key: string
  tier?: string
  banned?: boolean
  banExpiresAt?: number
  violations?: number
  group?: string
}

interface HitLimitStore {
  hit(key: string, windowMs: number, limit: number): Promise<StoreResult> | StoreResult
  reset(key: string): Promise<void> | void
  shutdown?(): Promise<void> | void
}

interface StoreResult {
  count: number
  resetAt: number
}

interface SqliteStoreOptions {
  /** Path to SQLite database file (default: ':memory:') */
  path?: string
}

interface RedisStoreOptions {
  /** Redis connection URL */
  url?: string

  /** Key prefix (default: 'hitlimit:') */
  keyPrefix?: string
}

interface Request {
  rateLimit?: {
    limit: number
    remaining: number
    resetAt: number
  }
}

import type { HitLimitOptions, HitLimitStore } from '@joint-ops/hitlimit'

const options: HitLimitOptions = {
  limit: 100,
  window: '1m',
  headers: { standard: true }
}

const customStore: HitLimitStore = {
  hit(key, windowMs) { /* ... */ },
  reset(key) { /* ... */ }
}