cockatiel

All Cockatiel fault handling policies (fallbacks, circuit breakers, bulkheads, timeouts, retries) implement the IPolicy interface.

Key features:

• execute<T>(fn, signal): The primary method to run a function through the policy's behavior. It returns a Promise<T>. You can optionally pass an AbortSignal.
• onSuccess: An event that fires when a request successfully completes. In a retry policy, this fires once even if multiple retries occurred.
• onFailure: An event that fires when a request fails due to a handled reason. Cockatiel does not treat all thrown errors as failures; you must define which errors the policy should handle.

Note: The context object passed to the function in execute contains metadata (like AbortSignal or retry attempt numbers) depending on the policies applied.

To use Cockatiel in your JavaScript or TypeScript project, install it using npm:

npm install --save cockatiel

In Cockatiel, backoff strategies determine the delay between retry attempts. The IBackoff<T> interface defines a strategy that provides a duration (in milliseconds) for the current attempt. It extends IBackoffFactory<T>, which provides a next(context: T) method to calculate the next backoff interval based on the current retry context.

Common implementations include ConstantBackoff, ExponentialBackoff, and IterableBackoff.

// Example of what an IBackoff implementation looks like conceptually
export interface IBackoff<T> extends IBackoffFactory<T> {
  readonly duration: number;
}

The CircuitBreakerPolicy operates in one of four states:

• CircuitState.Closed: Normal operation. Actions are executed. If the breaker determines a failure threshold is met, the state changes to Open.
• CircuitState.Open: The circuit is broken. All calls to execute() immediately throw a BrokenCircuitError. The circuit stays in this state for the duration specified by halfOpenAfter.
• CircuitState.HalfOpen: The circuit is testing the waters. A limited number of calls (halfOpenSampling.calls) are permitted. If they succeed (within the threshold), the circuit returns to Closed. If they fail, it returns to Open.
• CircuitState.Isolated: The circuit is manually held open via the isolate() method. All calls throw an IsolatedCircuitError.

The noop policy does nothing and simply returns the result of the function passed to execute. This is useful for providing a default policy that can be swapped out for a real policy (like retry) based on environment settings (e.g., production vs. test).

import { noop, handleAll, retry } from 'cockatiel';

const policy = isProduction ? retry(handleAll, { attempts: 3 }) : noop;

export async function handleRequest() {
  return policy.execute(() => getInfoFromDatabase());
}

By default, the timers used for backoff keep the Node.js event loop active. If you want the process to be able to exit even if a retry delay is pending, call .dangerouslyUnref() on the retry builder before calling .execute().

const response1 = await retry(handleAll, { maxAttempts: 3 })
  .dangerouslyUnref()
  .execute(() => getJson('https://example.com'));

The Event.once(event, callback) utility waits for an event to fire exactly once, then automatically unregisters the listener.

This method returns an IDisposable, which allows you to manually unregister the listener if the event hasn't fired yet.

import { Event } from 'cockatiel';

async function waitForFallback(policy) {
  Event.once(policy.onFallback, () => {
    console.log('a fallback happened!');
  });
}

Cockatiel policies provide events for monitoring lifecycle changes (e.g., onFailure, onFallback, onRetry, onSuccess, onGiveUp). You can subscribe to these events by passing a callback function.

Each subscription returns an IDisposable instance. To stop listening and prevent memory leaks, call .dispose() on that instance. It is safe to call .dispose() multiple times.

const listener = policy.onFailure(error => {
  console.log(error);
});

// Later, to unsubscribe:
listener.dispose();

The Event.toPromise(event[, signal]) utility returns a promise that resolves once a specific event fires.

If you provide an AbortSignal, the promise will reject with a TaskCancelledError if the signal is aborted before the event occurs.

import { Event } from 'cockatiel';

async function waitForFallback(policy) {
  await Event.toPromise(policy.onFallback);
  console.log('a fallback happened!');
}