@eric8810/catcher-http

Resilient HTTP client for Node.js — retry, circuit breaker, priority queue, interceptors, SSE streaming. Part of the catcher toolkit.

Built on axios (optional peer dep) + cockatiel (circuit breaker) + p-retry + p-queue.

💡 For maximum performance, consider @eric8810/catcher-napi-http — Rust native via napi-rs, with typed TypeScript wrappers and the same config schema. Recommended for production Node.js workloads.

Install

npm install @eric8810/catcher-http
# axios is an optional peer dependency
npm install axios

Quick Start

import { createHttpClient } from '@eric8810/catcher-http'

const client = createHttpClient({
  baseURL: 'https://api.example.com',
  keepAlive: true,
  retry: { attempts: 3, backoff: 'exponential', minTimeout: 500 },
  concurrency: 10,
  circuitBreaker: { failureThreshold: 5, resetTimeout: 30_000 },
})

// Basic requests
const user = await client.get('/users/1')
const created = await client.post('/messages', { text: 'hello' })

// Per-request overrides
await client.get('/analytics', { retry: false, timeout: 5000 })

// Dynamic interceptors
client.interceptors.request.use(config => {
  config.headers['Authorization'] = `Bearer ${token}`
  return config
})

SSE Streaming

One-shot stream (e.g. OpenAI)

import { createSSEStream } from '@eric8810/catcher-http'

const stream = createSSEStream({
  url: 'https://api.openai.com/v1/chat/completions',
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: { model: 'gpt-4', messages: [{ role: 'user', content: 'Hello' }], stream: true },
})

for await (const line of stream) {
  if (!line.startsWith('data:')) continue
  const payload = line.startsWith('data: ') ? line.slice(6) : line.slice(5)
  if (payload === '[DONE]') break
  process.stdout.write(JSON.parse(payload).choices[0]?.delta?.content ?? '')
}

Long-lived push with auto-reconnect

import { createSSEClient } from '@eric8810/catcher-http'

const sse = createSSEClient({
  url: 'https://api.example.com/events',
  reconnect: { initialDelay: 1000, maxDelay: 30_000 },
})

for await (const line of sse) {
  if (line.startsWith('data: ')) console.log(line.slice(6))
}

API

createHttpClient(config)

Resilience layers (inside → out): axios → retry → circuit breaker → concurrency queue

interface HttpClientConfig {
  baseURL?: string
  timeout?: number
  keepAlive?: boolean
  retry?: RetryOptions | false
  concurrency?: number
  circuitBreaker?: { failureThreshold: number; resetTimeout: number }
  interceptors?: { request?: Function[]; response?: [Function?, Function?] }
  auth?: { username: string; password: string }
  bearerToken?: string | (() => Promise<string>)
  // ... more options
}

Client Methods

| Method | Priority | |--------|----------| | client.get(url, config?) | 3 (low) | | client.put(url, body?, config?) | 2 | | client.patch(url, body?, config?) | 2 | | client.post(url, body?, config?) | 1 (high) | | client.delete(url, config?) | 3 | | client.circuitBreakerState() | 'closed' \| 'open' \| 'half-open' | | client.queueDepth() | Current queue size | | client.on(event, listener) | Subscribe to events | | client.updateConfig(updates) | Hot-update retry/timeout at runtime |

Additional Exports

| Export | Description | |--------|-------------| | createRetryWrapper(fn, retryOpts) | Wrap any async function with retry | | createInterceptorManager() | Standalone interceptor chain | | createSharedAgent(opts) | TCP keep-alive + DNS cache agent | | clearDnsCache() | Clear the shared DNS cache | | createPriorityQueue(opts) | Priority-based concurrency queue | | createSSEStream(opts) | One-shot SSE async iterable | | createSSEClient(opts) | Long-lived SSE with auto-reconnect |

License

MIT