@joint-ops/hitlimit-types

TypeScript type definitions for hitlimit rate limiting libraries

This package contains shared TypeScript interfaces and types used by @joint-ops/hitlimit and @joint-ops/hitlimit-bun.

Installation

This package is automatically installed as a dependency of hitlimit and hitlimit-bun. You don't need to install it directly.

# Install hitlimit (includes types automatically)
npm install @joint-ops/hitlimit

# Or for Bun
bun add @joint-ops/hitlimit-bun

Usage

Types are re-exported from the main packages:

import type {
  HitLimitConfig,
  RateLimitResult,
  Store,
  TierConfig
} from '@joint-ops/hitlimit'

// Or from hitlimit-bun
import type { HitLimitConfig, Store } from '@joint-ops/hitlimit-bun'

Available Types

Core Types

// Main configuration
interface HitLimitConfig {
  limit?: number
  window?: string | number
  key?: (req: Request) => string | Promise<string>
  tiers?: Record<string, TierConfig>
  tier?: (req: Request) => string | Promise<string>
  response?: RateLimitResponse | ((info: RateLimitInfo) => RateLimitResponse)
  headers?: HeadersConfig
  store?: Store
  skip?: (req: Request) => boolean | Promise<boolean>
  onStoreError?: (error: Error, req: Request) => 'allow' | 'deny'
}

// Store interface for custom backends
interface Store {
  increment(key: string, window: number): Promise<RateLimitResult>
  decrement?(key: string): Promise<void>
  reset?(key: string): Promise<void>
  close?(): Promise<void>
}

// Rate limit result
interface RateLimitResult {
  allowed: boolean
  limit: number
  remaining: number
  resetAt: number
}

// Tier configuration
interface TierConfig {
  limit: number
  window?: string | number
}

Logger Types

interface Logger {
  debug(message: string, meta?: Record<string, unknown>): void
  info(message: string, meta?: Record<string, unknown>): void
  warn(message: string, meta?: Record<string, unknown>): void
  error(message: string, meta?: Record<string, unknown>): void
}

Related Packages

• @joint-ops/hitlimit - Rate limiting for Node.js (Express, NestJS)
• @joint-ops/hitlimit-bun - Rate limiting for Bun (Bun.serve, Elysia)

License

MIT

Keywords

rate limit types, typescript rate limit, rate limiter types, hitlimit, api types, middleware types, typescript definitions