Cockatiel

Cockatiel is a dependency-free resilience and transient-fault-handling library for JavaScript and TypeScript, inspired by .NET’s Polly. It lets you express reliability policies — Retry with configurable backoff, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback — as composable objects you wrap around any async operation.

Policies are built with a fluent API and can be combined with wrap() so a single call site retries through a circuit breaker, times out, and falls back, all with first-class cancellation support. It ships full TypeScript types, has no runtime dependencies, and is widely used to make calls to databases, HTTP services, and other flaky dependencies robust against transient failures.

What You Get

• Retry policies with configurable backoff strategies including exponential backoff with jitter
• Circuit breakers (consecutive-failure and sampling) that stop calls to a failing dependency and recover via a half-open state
• Timeout and bulkhead-isolation policies for bounding latency and concurrency
• Fallback policies that substitute a safe value when an operation fails
• Composition via wrap() plus first-class cancellation and TypeScript types, with zero runtime dependencies

Common Use Cases

• Making database or HTTP calls resilient to transient failures with retries and backoff
• Protecting a downstream service from overload using a circuit breaker and bulkhead isolation
• Bounding operation latency with timeouts and degrading gracefully via fallbacks

Under The Hood

Architecture Each resilience strategy is its own class — RetryPolicy, CircuitBreakerPolicy, TimeoutPolicy, BulkheadPolicy, FallbackPolicy — exposing a common execute() contract, re-exported from src/index.ts. Backoff strategies live under src/backoff and breaker strategies (ConsecutiveBreaker, SamplingBreaker) under src/breaker, so retry and circuit-breaker behavior is pluggable. A shared Event/EventEmitter in src/common powers policy lifecycle hooks, and wrap() composes policies by chaining their execute calls. Cancellation flows through the executed function via a cancellation token.

Tech Stack Written in TypeScript (99.9% of the codebase) targeting Node.js with zero runtime dependencies. Built with tsc against a tsconfig.json, tested with Mocha (configured via mocha.opts), and distributed with bundled type definitions.

Code Quality The source keeps a test file alongside nearly every policy (RetryPolicy.test.ts, CircuitBreakerPolicy.test.ts, BulkheadPolicy.test.ts, and so on), indicating strong unit coverage. Errors are modeled explicitly under src/errors, and the consistent per-policy class structure keeps concerns cleanly separated.

API Design The fluent factory functions (retry, circuitBreaker, timeout, fallback) paired with handleAll/handleType predicates read naturally, and wrap() makes layering strategies a one-liner. Mirroring .NET Polly gives the API a proven mental model, though the breadth of policies and backoff/breaker options means there is a moderate learning curve before you know which combination to reach for.