BreakerHandle

A BreakerHandle is returned by client.breaker(slug). It delegates all operations to the parent client.

const stripe = client.breaker('stripe-api')

Properties

slug

readonly slug: string

The breaker slug this handle is bound to.

Methods

protect()

protect<T>(
  fn: (signal: AbortSignal) => Promise<T> | T,
  options?: TProtectOptions<T>,
): Promise<T>

Executes fn with circuit breaker protection. Checks breaker state, records metrics, and supports timeouts and fallbacks.

Parameters

TProtectOptions

type TProtectOptions<T> = {
  timeout?: number
  fallback?: () => Promise<T> | T
  signal?: AbortSignal
}

Behavior

• Breaker closed/half-open: fn executes. Metrics are recorded.
• Breaker open + fallback: Fallback executes. No metrics recorded.
• Breaker open + no fallback: fn executes with a warning logged (fail-open). Metrics are recorded.
• State unknown: fn executes (fail-open). Metrics are recorded.

Throws

• TimeoutError if fn exceeds timeout.
• AbortOperationError if signal is aborted.
• Any error thrown by fn is rethrown.

const charge = await stripe.protect(
  async (signal) => {
    return await paymentApi.charge({ amount: 1000 }, { signal })
  },
  {
    timeout: 5000,
    fallback: () => ({ status: 'queued' }),
  },
)

isOpen()

isOpen(): Promise<boolean>

Returns true if the breaker is open. Returns false if closed, half-open, unknown, or on any error. Never throws. Has a 500ms budget.

if (await stripe.isOpen()) {
  return cachedResponse
}

isClosed()

isClosed(): Promise<boolean>

Returns true if the breaker is closed. Returns true on any error (fail-open). Never throws. Has a 500ms budget.

if (await stripe.isClosed()) {
  // Safe to proceed
}

status()

status(signal?: AbortSignal): Promise<TBreaker | null>

Returns the full breaker object or null if not found or unreachable. Never throws. Has a 500ms budget.

const breaker = await stripe.status()
if (breaker) {
  console.log(breaker.state)
  console.log(breaker.updatedAt)
  console.log(breaker.retryAfter)
}