Resilience policies
with typed errors.

What it does

Five jobs, one chain.

Failure

Stack strategies in the order they run.

Each call wraps the steps added before it. The timeout bounds one attempt, the retry repeats it, the breaker stops calling a dead service, and the fallback answers.

Read more →

const policy = Tenace.policy({ name: 'users.get' })
  .withTimeout('1s')
  .withRetry({ retries: 3, retryOn: ['TimeoutError'] })
  .withCircuitBreaker({ trip: { consecutive: 5 }, openFor: '30s' })
  .withFallbackOn(['TimeoutError', 'CircuitOpenError'], () => null)

const user = await policy.execute(({ signal }) => fetchUser(id, { signal }))
// user: User | null

Concurrency

Control how many calls run, and how often.

Bulkheads cap parallel work, rate limits cap throughput per key, Tenace.map runs batches with a limit.

Read more →

// 10 reports at once, 100 more waiting
const reports = Tenace.policy()
  .withBulkhead({ concurrency: 10, queue: 100 })

// 10 searches per second and per user
const search = Tenace.policy()
  .withRateLimit({ limit: 10, per: '1s' })
await search.execute(() => searchUsers(query), {
  key: `user:${userId}`,
})

// 1,000 ids, at most 5 requests in flight
const users = await Tenace.map(ids, fetchUser, {
  policy,
  concurrency: 5,
}).execute()

Typed errors

The compiler knows every error.

match() needs one handler per error, so a new strategy fails the build until you handle it.

Read more →

const policy = Tenace.policy()
  .withTimeout('1s')
  .withCircuitBreaker()

type Failure = ErrorOf<typeof policy>
// UnexpectedError | TimeoutError | CircuitOpenError

const result = await policy.settle(() => fetchUser(id))

const message = match(result, {
  ok: user => `Hello ${user.name}`,
  TimeoutError: () => 'The user service is slow',
  CircuitOpenError: () => 'The user service is down',
  UnexpectedError: () => 'Something went wrong',
})

Chaos

Break it before production does.

Inject latency, throws, or typed errors into a share of calls, in one policy or all of them.

Read more →

// 1 call in 5 takes 2s longer: the timeout fires
const policy = Tenace.policy()
  .withChaos({ rate: 0.2, latency: '2s' })
  .withTimeout('1s')
  .withFallbackOn(['TimeoutError'], () => cachedUser)

// in tests: every policy throws until restore()
const restore = Tenace.chaos({
  throws: () => new Error('users API down'),
})

Testing

Test retries without waiting.

TestClock moves time only when the test says so. Three timeouts and two delays run instantly.

Read more →

import { TestClock } from '@julr/tenace/testing'

const clock = new TestClock()
const policy = Tenace.policy()
  .withTimeout('1s')
  .withRetry({ retries: 2, delay: '100ms' })

const hang = () => new Promise<never>(() => {})
const done = policy.settle(hang, { clock })

await clock.runAll() // 3 timeouts, 2 delays, 0ms
const result = await done // a TimeoutError

The toolbox

Everything a call to a flaky dependency needs.

Failure

• withTimeoutGive up after a deadline.
• withRetryTry again, with backoff and jitter.
• withCircuitBreakerStop calling what keeps failing.
• withFallbackAnswer something anyway.
• withStaleFallbackServe the last good value.

Concurrency

• withBulkheadCap the calls running at once.
• withRateLimitLimit the call rate per key.
• withLockOne holder per key, local or distributed.
• withDedupeShare one in-flight call.
• withCacheServe successes from a cache.
• Tenace.mapBatches with bounded concurrency.

Types

• execute()Resolve or reject, like any call.
• settle()Resolve with a Result instead.
• match()One handler per error, checked.
• ErrorOf<P>The error channel of a policy.

Test & observe

• withChaosInject latency and faults.
• Tenace.chaosChaos around every policy.
• TestClockMove time only when you say.
• OpenTelemetrySpans and metrics per call.
• listener()Every event, to your logger.

In code

Small API, read in one sitting.

FailureConcurrencyTyped errorsChaosTestingObservability

Stack strategies in the order they run.

Each call wraps the steps added before it. The timeout bounds one attempt, the retry repeats it, the breaker stops the bleeding, the fallback answers.

Read more →

const policy = Tenace.policy({ name: 'users.get' })
  .withTimeout('1s')
  .withRetry({ retries: 3, retryOn: ['TimeoutError'] })
  .withCircuitBreaker({ trip: { consecutive: 5 }, openFor: '30s' })
  .withFallbackOn(['TimeoutError', 'CircuitOpenError'], () => null)

const user = await policy.execute(({ signal }) => fetchUser(id, { signal }))
// user: User | null

Control how many calls run, and how often.

Bulkheads cap parallel work, rate limits cap throughput per key, and Tenace.map runs whole batches through a policy with a concurrency limit.

Read more →

// 10 reports at once, 100 more waiting
const reports = Tenace.policy()
  .withBulkhead({ concurrency: 10, queue: 100 })

// 10 searches per second and per user
const search = Tenace.policy()
  .withRateLimit({ limit: 10, per: '1s' })
await search.execute(() => searchUsers(query), {
  key: `user:${userId}`,
})

// 1,000 ids, at most 5 requests in flight
const users = await Tenace.map(ids, fetchUser, {
  policy,
  concurrency: 5,
}).execute()

The compiler knows every error.

Strategies add their errors to the type of the policy and fallbacks remove them. match() needs one handler per error, so a new strategy fails the build until you handle it.

Read more →

const policy = Tenace.policy()
  .withTimeout('1s')
  .withCircuitBreaker()

type Failure = ErrorOf<typeof policy>
// UnexpectedError | TimeoutError | CircuitOpenError

const result = await policy.settle(() => fetchUser(id))

const message = match(result, {
  ok: user => `Hello ${user.name}`,
  TimeoutError: () => 'The user service is slow',
  CircuitOpenError: () => 'The user service is down',
  UnexpectedError: () => 'Something went wrong',
})

Break it before production does.

withChaos() injects latency, throws, or typed errors into a share of calls. Tenace.chaos() does it around every policy at once, without touching the code under test.

Read more →

// 1 call in 5 takes 2s longer: the timeout fires
const policy = Tenace.policy()
  .withChaos({ rate: 0.2, latency: '2s' })
  .withTimeout('1s')
  .withFallbackOn(['TimeoutError'], () => cachedUser)

// in tests: every policy throws until restore()
const restore = Tenace.chaos({
  throws: () => new Error('users API down'),
})

Test retries without waiting for them.

Timeouts, retry delays, and open circuits read the time from a clock. TestClock moves it only when the test says so.

Read more →

import { TestClock } from '@julr/tenace/testing'

const clock = new TestClock()
const policy = Tenace.policy()
  .withTimeout('1s')
  .withRetry({ retries: 2, delay: '100ms' })

const hang = () => new Promise<never>(() => {})
const done = policy.settle(hang, { clock })

await clock.runAll() // 3 timeouts, 2 delays, 0ms
const result = await done // a TimeoutError

See every attempt in production.

One instrumentation interface sees every execution, attempt, and event. OpenTelemetry, diagnostics_channel, and your logger plug into it.

Read more →

import { openTelemetry } from '@julr/tenace-otel'

// a span per execution, an event per retry or timeout
Tenace.instrument(openTelemetry())

// or your own logger
Tenace.instrument(
  listener((event, info) => logger.info({ name: info.name, event })),
)

Get started

Start with one policy.

Add a timeout and a retry to one call. Grow from there.

Get startedGitHub$pnpm add @julr/tenacecopy

Tenace

Built by Julien Ripouteau. MIT licensed.

Sponsor