Resilience

@adonis-agora/resilience is an AdonisJS-native fault-tolerance toolkit — composable timeout, retry, circuit breaker and failover policies, with a pluggable, distributed circuit-breaker store. Think cockatiel for AdonisJS, wired into the ecosystem's conventions (diagnostics, context, Telescope) through soft, optional integrations.

Compose policies, outer to inner

Each policy is a small object with an execute(op) method. wrap() composes them — the first argument is the outermost layer, the last is closest to your operation:

import { wrap, timeout, retry, exponential, circuitBreaker, InMemoryResilienceStore } from '@adonis-agora/resilience'

const store = new InMemoryResilienceStore()

const policy = wrap(
  timeout(2_000),
  retry({ attempts: 3, backoff: exponential(100) }),
  circuitBreaker({ key: 'payments', store, threshold: 5, cooldownMs: 30_000 }),
)

await policy.execute(() => chargeCard(order)) // timeout → retry → breaker → chargeCard

The policies are framework-agnostic — you can use them standalone anywhere in your codebase. The AdonisJS surface (a provider, a config/resilience.ts, and a container-resolved ResilienceService) is a convenience layer on top.

Three ways to use it

Wired into the ecosystem

State transitions (circuit opened/closed/half-open, short-circuited, failover) emit over @adonis-agora/diagnostics on the agora:resilience:* channel — so Telescope or any subscriber can observe them. An optional EventEmitter mirror lets you react in-app, and @adonis-agora/context makes breaker keys tenant-aware automatically. Every integration is soft-detected through a global slot, so there is no hard dependency between packages. See Integrations.

Install

node ace add @adonis-agora/resilience

@adonisjs/core is a peer dependency; @adonis-agora/diagnostics and @adonis-agora/context are optional, soft-detected ones. Head to Getting Started.