API

Entry points

Import path	Exports
`@julr/tenace`	`Tenace`, the strategies, the errors, `ok`, `err`, `match`, `backoff`, the instrumentation helpers, and the types.
`@julr/tenace/testing`	`TestClock`
`@julr/tenace/adapters/rate-limiter-flexible`	`rateLimiterFlexible`
`@julr/tenace/adapters/verrou`	`verrou`
`@julr/tenace/adapters/bentocache`	`bentocache`
`@julr/tenace-otel`	`openTelemetry`, `errorType`

Tenace

Method	Returns	Description
`Tenace.policy<E>(options?)`	`Policy`	A reusable policy. `E` declares errors the functions may return, for the callbacks.
`Tenace.call(fn, options?)`	`Policy`	A policy bound to `fn`. Throws a `TypeError` when `fn` is not a function.
`Tenace.all(tasks, options?)`	`Batch`	Runs `tasks` through a policy. See Batches.
`Tenace.map(items, fn, options?)`	`Batch`	Runs `fn(item, context, index)` for each item through a policy.
`Tenace.instrument(...instrumentations)`	`() => void`	Sets the default instrumentation. Returns a function that removes this setting.
`Tenace.chaos(options)`	`() => void`	Injects faults around every function call. Returns a function that removes this setting.

The functions returned by Tenace.instrument() and Tenace.chaos() can be called in any order: the active setting is the latest one not removed yet.

PolicyOptions

Option	Type	Default	Description
`name`	`string`	`'tenace'`	Operation name reported to instrumentation.
`instrumentation`	`Instrumentation \| false`	none	Added to the default for this policy. `false` turns the default off.

The default set with Tenace.instrument() wraps the instrumentation option. See Instrumentation.

Policy

Every method that adds a strategy returns a new policy. See Composition.

Method	Strategy page
`with(strategyOrPolicy)`	Composition
`withTimeout(duration, options?)`	Timeout
`withRetry(options)`	Retry
`withCircuitBreaker(breakerOrOptions?)`	Circuit breaker
`withBulkhead(bulkheadOrOptions)`	Bulkhead
`withRateLimit(rateLimitOrOptions)`	Rate limit
`withLock(lockOrOptions?)`	Lock
`withDedupe(dedupeOrOptions?)`	Dedupe
`withCache(cacheOrOptions)`	Cache
`withStaleFallback(staleOrOptions?)`	Stale fallback
`withChaos(chaosOrOptions?)`	Chaos
`withFallback(handler)`	Fallback
`withFallbackOn(tags, handler)`	Fallback
`withFallbackWhen(when, handler)`	Fallback
`mapError(mapper)`	Fallback

Member	Description
`execute(fn, options?)`	Runs `fn`. Resolves with its value or rejects. A bound policy takes only `options`.
`settle(fn, options?)`	Runs `fn`. Resolves with a `Result`. A bound policy takes only `options`.
`isError(error)`	Whether `execute()` of this policy rejected with `error`, a known error. Narrows its type, `OtherError` included.
`describe()`	The strategy names, from the outermost to the innermost.
`strategies`	The strategy instances, from the innermost to the outermost.

See execute() and settle().

ExecuteOptions

Option	Type	Default	Description
`signal`	`AbortSignal`		Aborting it stops the execution. The promise rejects with `signal.reason`, without running `fn` when already aborted.
`clock`	`Clock`	`systemClock`	Clock of the time-based strategies of this execution. See Testing.
`name`	`string`	the policy name	Operation name reported to instrumentation.
`key`	`string`		Key of the execution. See Keys.
`idempotent`	`boolean`	`true`	`false` when running the function twice is not safe. See Idempotency.
`attributes`	`Attributes`	`{}`	Extra attributes reported to instrumentation. Keep them low cardinality.

Context

The function receives a Context:

Field	Type	Description
`signal`	`AbortSignal`	Aborts when the caller aborts, a timeout fires, or a batch sibling fails.
`attempt`	`number`	The 1-based attempt number.

Results

Export	Description
`ok(value?)`	Builds `{ ok: true, value }`.
`err(error)`	Builds `{ ok: false, error }`.
`isResult(value)`	Whether `value` is a Result created by any copy of Tenace.
`match(result, handlers)`	Calls the `ok` handler or the handler named after the error `_tag`. See Typed errors.
`registerResult(name, adapter)`, `unregisterResult(name)`	Register a foreign Result type. See Use your own Result type.

Types

Type	Description
`Result<T, E>`	`Ok<T> \| Err<E>`.
`ErrorOf<P>`	The errors of policy `P`, as its callbacks see them, without `OtherError`.
`CurrentError<P>`	The errors the callbacks added at the end of `P` see, `OtherError` included.
`KnownError<E>`	`E` without `UnexpectedError`, `OtherError` included: the errors `execute()` rejects with as they are.
`OtherError`	Stands for the errors a reusable policy did not declare.
`ValueOf<R>`, `ErrorOfResult<R>`	The value and error types of a Result type.
`TagOf<E>`, `ByTag<E, K>`	The tags of an error union, and its members with tag `K`.
`Duration`	A number of milliseconds, or a string: `'250ms'`, `'1.5s'`, `'2m'`, `'1h'`, `'1d'`.

Durations

Every duration option accepts a number of milliseconds or a string with one unit: ms, s, m, h, or d. The number of a string is a non-negative decimal, and '+1s', '5.s', and '1e3ms' are accepted too. toMs(duration) converts a duration to milliseconds. It throws a RangeError for a negative, NaN, or malformed duration. Infinity is accepted and means never.

Clock

interface Clock {
  now(): number
  setTimeout(callback: () => void, ms: number): TimerHandle
  clearTimeout(handle: TimerHandle): void
}

setTimeout() must accept delays longer than the timer limit of the platform, and never fire a timer of Infinity. systemClock uses Date.now() and the global timers, and chains timers for delays longer than about 24.8 days. TestClock from @julr/tenace/testing moves only when you tell it to.