@git-stunts/alfred 0.2.0 → 0.3.0

package/README.md

@@ -1,20 +1,43 @@
 # @git-stunts/alfred
 
-> *"Why do we fall, Bruce?"*
+```text
+      .o.       oooo   .o88o.                          .o8
+     .888.      `888   888 `"                         "888
+    .8"888.      888  o888oo  oooo d8b  .ooooo.   .oooo888
+   .8' `888.     888   888    `888""8P d88' `88b d88' `888
+  .88ooo8888.    888   888     888     888ooo888 888   888
+ .8'     `888.   888   888     888     888    .o 888   888
+o88o     o8888o o888o o888o   d888b    `Y8bod8P' `Y8bod88P"
+```
+
+[![JSR](https://jsr.io/badges/@git-stunts/alfred)](https://jsr.io/@git-stunts/alfred)
+[![NPM Version](https://img.shields.io/npm/v/@git-stunts/alfred)](https://www.npmjs.com/package/@git-stunts/alfred)
+[![CI](https://github.com/git-stunts/alfred/actions/workflows/ci.yml/badge.svg)](https://github.com/git-stunts/alfred/actions/workflows/ci.yml)
+
+> _"Why do we fall, Bruce?"_
 >
-> *"So we can `retry({ backoff: 'exponential', jitter: 'decorrelated' })`."*
+> _"So we can `retry({ backoff: 'exponential', jitter: 'decorrelated' })`."_
 
-Resilience patterns for async operations. *Tuff 'nuff for most stuff!*
+Resilience patterns for async operations. _Tuff 'nuff for most stuff!_
 
 ## Installation
 
+### NPM
+
 ```bash
 npm install @git-stunts/alfred
 ```
 
+### JSR (Deno, Bun, Node)
+
+```bash
+npx jsr add @git-stunts/alfred
+```
+
 ## Multi-Runtime Support
 
 Alfred is designed to be platform-agnostic and is tested against:
+
 - **Node.js** (>= 20.0.0)
 - **Bun** (>= 1.0.0)
 - **Deno** (>= 1.35.0)
@@ -27,10 +50,11 @@ It uses standard Web APIs (AbortController, AbortSignal) and provides runtime-aw
 import { retry, circuitBreaker, timeout, compose } from '@git-stunts/alfred';
 
 // Simple retry with exponential backoff
-const data = await retry(
-  () => fetch('https://api.example.com/data'),
-  { retries: 3, backoff: 'exponential', delay: 100 }
-);
+const data = await retry(() => fetch('https://api.example.com/data'), {
+  retries: 3,
+  backoff: 'exponential',
+  delay: 100,
+});
 
 // Circuit breaker - fail fast when service is down
 const breaker = circuitBreaker({ threshold: 5, duration: 60000 });
@@ -64,13 +88,13 @@ await retry(() => mightFail(), {
   retries: 5,
   backoff: 'exponential',
   delay: 100,
-  maxDelay: 10000
+  maxDelay: 10000,
 });
 
 // Only retry specific errors
 await retry(() => mightFail(), {
   retries: 3,
-  shouldRetry: (err) => err.code === 'ECONNREFUSED'
+  shouldRetry: (err) => err.code === 'ECONNREFUSED',
 });
 
 // With jitter to prevent thundering herd
@@ -78,21 +102,21 @@ await retry(() => mightFail(), {
   retries: 3,
   backoff: 'exponential',
   delay: 100,
-  jitter: 'full' // or 'equal' or 'decorrelated'
+  jitter: 'full', // or 'equal' or 'decorrelated'
 });
 ```
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `retries` | `number` | `3` | Maximum retry attempts |
-| `delay` | `number` | `1000` | Base delay in milliseconds |
-| `maxDelay` | `number` | `30000` | Maximum delay cap |
-| `backoff` | `'constant' \| 'linear' \| 'exponential'` | `'constant'` | Backoff strategy |
-| `jitter` | `'none' \| 'full' \| 'equal' \| 'decorrelated'` | `'none'` | Jitter strategy |
-| `shouldRetry` | `(error) => boolean` | `() => true` | Predicate to filter retryable errors |
-| `onRetry` | `(error, attempt, delay) => void` | - | Callback on each retry |
+| Option        | Type                                            | Default      | Description                          |
+| ------------- | ----------------------------------------------- | ------------ | ------------------------------------ |
+| `retries`     | `number`                                        | `3`          | Maximum retry attempts               |
+| `delay`       | `number`                                        | `1000`       | Base delay in milliseconds           |
+| `maxDelay`    | `number`                                        | `30000`      | Maximum delay cap                    |
+| `backoff`     | `'constant' \| 'linear' \| 'exponential'`       | `'constant'` | Backoff strategy                     |
+| `jitter`      | `'none' \| 'full' \| 'equal' \| 'decorrelated'` | `'none'`     | Jitter strategy                      |
+| `shouldRetry` | `(error) => boolean`                            | `() => true` | Predicate to filter retryable errors |
+| `onRetry`     | `(error, attempt, delay) => void`               | -            | Callback on each retry               |
 
 ### `circuitBreaker(options)`
 
@@ -102,11 +126,11 @@ Fails fast when a service is degraded, preventing cascade failures.
 import { circuitBreaker } from '@git-stunts/alfred';
 
 const breaker = circuitBreaker({
-  threshold: 5,      // Open after 5 failures
-  duration: 60000,   // Stay open for 60 seconds
+  threshold: 5, // Open after 5 failures
+  duration: 60000, // Stay open for 60 seconds
   onOpen: () => console.log('Circuit opened!'),
   onClose: () => console.log('Circuit closed!'),
-  onHalfOpen: () => console.log('Testing recovery...')
+  onHalfOpen: () => console.log('Testing recovery...'),
 });
 
 // Circuit has three states:
@@ -125,15 +149,15 @@ try {
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `threshold` | `number` | required | Failures before opening |
-| `duration` | `number` | required | How long to stay open (ms) |
-| `successThreshold` | `number` | `1` | Successes to close from half-open |
-| `shouldTrip` | `(error) => boolean` | `() => true` | Which errors count as failures |
-| `onOpen` | `() => void` | - | Called when circuit opens |
-| `onClose` | `() => void` | - | Called when circuit closes |
-| `onHalfOpen` | `() => void` | - | Called when entering half-open |
+| Option             | Type                 | Default      | Description                       |
+| ------------------ | -------------------- | ------------ | --------------------------------- |
+| `threshold`        | `number`             | required     | Failures before opening           |
+| `duration`         | `number`             | required     | How long to stay open (ms)        |
+| `successThreshold` | `number`             | `1`          | Successes to close from half-open |
+| `shouldTrip`       | `(error) => boolean` | `() => true` | Which errors count as failures    |
+| `onOpen`           | `() => void`         | -            | Called when circuit opens         |
+| `onClose`          | `() => void`         | -            | Called when circuit closes        |
+| `onHalfOpen`       | `() => void`         | -            | Called when entering half-open    |
 
 ### `bulkhead(options)`
 
@@ -143,8 +167,8 @@ Limits the number of concurrent executions to prevent resource exhaustion.
 import { bulkhead } from '@git-stunts/alfred';
 
 const limiter = bulkhead({
-  limit: 10,       // Max 10 concurrent executions
-  queueLimit: 20   // Max 20 pending requests in queue
+  limit: 10, // Max 10 concurrent executions
+  queueLimit: 20, // Max 20 pending requests in queue
 });
 
 // Returns an object with:
@@ -163,10 +187,10 @@ console.log(`Current load: ${limiter.stats.active} active tasks`);
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `limit` | `number` | required | Maximum concurrent executions |
-| `queueLimit` | `number` | `0` | Maximum pending requests in queue |
+| Option       | Type     | Default  | Description                       |
+| ------------ | -------- | -------- | --------------------------------- |
+| `limit`      | `number` | required | Maximum concurrent executions     |
+| `queueLimit` | `number` | `0`      | Maximum pending requests in queue |
 
 ### `timeout(ms, options)`
 
@@ -180,7 +204,7 @@ const result = await timeout(5000, () => slowOperation());
 
 // With callback
 const result = await timeout(5000, () => slowOperation(), {
-  onTimeout: (elapsed) => console.log(`Timed out after ${elapsed}ms`)
+  onTimeout: (elapsed) => console.log(`Timed out after ${elapsed}ms`),
 });
 ```
 
@@ -211,10 +235,10 @@ Combines multiple policies. Policies execute from left to right (outermost to in
 import { compose, retry, circuitBreaker, timeout } from '@git-stunts/alfred';
 
 const resilient = compose(
-  timeout(30000),                                    // Total timeout
-  retry({ retries: 3, backoff: 'exponential' }),     // Retry failures
+  timeout(30000), // Total timeout
+  retry({ retries: 3, backoff: 'exponential' }), // Retry failures
   circuitBreaker({ threshold: 5, duration: 60000 }), // Fail fast if broken
-  bulkhead({ limit: 5, queueLimit: 10 })             // Limit concurrency
+  bulkhead({ limit: 5, queueLimit: 10 }) // Limit concurrency
 );
 
 // Execution order:
@@ -229,23 +253,15 @@ await resilient.execute(() => riskyOperation());
 Alfred provides a composable telemetry system to monitor policy behavior.
 
 ```javascript
-import {
-  Policy,
-  ConsoleSink,
-  InMemorySink,
-  MultiSink
-} from '@git-stunts/alfred';
+import { Policy, ConsoleSink, InMemorySink, MultiSink } from '@git-stunts/alfred';
 
 // 1. Create a sink (or multiple)
-const sink = new MultiSink([
-  new ConsoleSink(),
-  new InMemorySink()
-]);
+const sink = new MultiSink([new ConsoleSink(), new InMemorySink()]);
 
 // 2. Attach to policies
 const policy = Policy.retry({
   retries: 3,
-  telemetry: sink
+  telemetry: sink,
 });
 
 // All policies emit events:
@@ -277,7 +293,7 @@ test('retries with exponential backoff', async () => {
     retries: 3,
     backoff: 'exponential',
     delay: 1000,
-    clock
+    clock,
   });
 
   // First attempt fails immediately
@@ -299,11 +315,7 @@ test('retries with exponential backoff', async () => {
 ## Error Types
 
 ```javascript
-import {
-  RetryExhaustedError,
-  CircuitOpenError,
-  TimeoutError
-} from '@git-stunts/alfred';
+import { RetryExhaustedError, CircuitOpenError, TimeoutError } from '@git-stunts/alfred';
 
 try {
   await resilientOperation();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@git-stunts/alfred",
-  "version": "0.2.0",
-"description": "Why do we fall, Bruce? Resilience patterns for async operations.",
+  "version": "0.3.0",
+  "description": "Why do we fall, Bruce? Production-grade resilience patterns for async operations.",
   "type": "module",
   "main": "src/index.js",
   "types": "./src/index.d.ts",

package/src/compose.js

@@ -33,7 +33,7 @@
 export function compose(...policies) {
   if (policies.length === 0) {
     return {
-      execute: (fn) => fn()
+      execute: (fn) => fn(),
     };
   }
 
@@ -55,7 +55,7 @@ export function compose(...policies) {
       }
 
       return chain();
-    }
+    },
   };
 }
 
@@ -86,7 +86,7 @@ export function fallback(primary, secondary) {
       } catch {
         return await secondary.execute(fn);
       }
-    }
+    },
   };
 }
 
@@ -148,6 +148,6 @@ export function race(policyA, policyB) {
         policyA.execute(fn).then(handleSuccess, (e) => handleFailure(e, true));
         policyB.execute(fn).then(handleSuccess, (e) => handleFailure(e, false));
       });
-    }
+    },
   };
 }

package/src/index.d.ts

@@ -1,125 +1,360 @@
+/**
+ * @module @git-stunts/alfred
+ * @description Production-grade resilience patterns for async operations.
+ * Includes Retry, Circuit Breaker, Timeout, and Bulkhead policies.
+ *
+ * @example
+ * ```ts
+ * import { compose, retry, circuitBreaker, timeout } from "@git-stunts/alfred";
+ *
+ * const policy = compose(
+ *   retry({ retries: 3 }),
+ *   circuitBreaker({ threshold: 5, duration: 60000 }),
+ *   timeout(5000)
+ * );
+ *
+ * await policy.execute(() => fetch("https://api.example.com"));
+ * ```
+ */
+
+/**
+ * A value that can be either static or resolved dynamically via a function.
+ */
+export type Resolvable<T> = T | (() => T);
+
+/**
+ * Options for the Retry policy.
+ */
 export interface RetryOptions {
-  retries?: number;
-  delay?: number;
-  maxDelay?: number;
-  backoff?: 'constant' | 'linear' | 'exponential';
-  jitter?: 'none' | 'full' | 'equal' | 'decorrelated';
+  /** Maximum number of retry attempts. Default: 3 */
+  retries?: Resolvable<number>;
+  /** Base delay in milliseconds. Default: 1000 */
+  delay?: Resolvable<number>;
+  /** Maximum delay cap in milliseconds. Default: 30000 */
+  maxDelay?: Resolvable<number>;
+  /** Backoff strategy. Default: 'constant' */
+  backoff?: Resolvable<'constant' | 'linear' | 'exponential'>;
+  /** Jitter strategy to prevent thundering herd. Default: 'none' */
+  jitter?: Resolvable<'none' | 'full' | 'equal' | 'decorrelated'>;
+  /** Predicate to determine if an error is retryable. Default: always true */
   shouldRetry?: (error: Error) => boolean;
+  /** Callback invoked before each retry. */
   onRetry?: (error: Error, attempt: number, delay: number) => void;
+  /** Telemetry sink for observability. */
   telemetry?: TelemetrySink;
+  /** Clock implementation for testing. */
   clock?: any;
 }
 
+/**
+ * Options for the Circuit Breaker policy.
+ */
 export interface CircuitBreakerOptions {
-  threshold: number;
-  duration: number;
-  successThreshold?: number;
+  /** Number of failures before opening the circuit. */
+  threshold: Resolvable<number>;
+  /** Milliseconds to stay open before transitioning to half-open. */
+  duration: Resolvable<number>;
+  /** Consecutive successes required to close the circuit from half-open. Default: 1 */
+  successThreshold?: Resolvable<number>;
+  /** Predicate to determine if an error counts as a failure. Default: always true */
   shouldTrip?: (error: Error) => boolean;
+  /** Callback when circuit opens. */
   onOpen?: () => void;
+  /** Callback when circuit closes. */
   onClose?: () => void;
+  /** Callback when circuit transitions to half-open. */
   onHalfOpen?: () => void;
+  /** Telemetry sink for observability. */
   telemetry?: TelemetrySink;
+  /** Clock implementation for testing. */
   clock?: any;
 }
 
+/**
+ * Options for the Timeout policy.
+ */
 export interface TimeoutOptions {
+  /** Callback invoked when timeout occurs. */
   onTimeout?: (elapsed: number) => void;
+  /** Telemetry sink for observability. */
   telemetry?: TelemetrySink;
 }
 
+/**
+ * Options for the Bulkhead policy.
+ */
 export interface BulkheadOptions {
-  limit: number;
-  queueLimit?: number;
+  /** Maximum concurrent executions. */
+  limit: Resolvable<number>;
+  /** Maximum pending requests in queue. Default: 0 */
+  queueLimit?: Resolvable<number>;
+  /** Telemetry sink for observability. */
+  telemetry?: TelemetrySink;
+  /** Clock implementation for testing. */
+  clock?: any;
+}
+
+/**
+ * Options for the Hedge policy.
+ */
+export interface HedgeOptions {
+  /** Milliseconds to wait before spawning a hedge. */
+  delay: Resolvable<number>;
+  /** Maximum number of hedged attempts to spawn. Default: 1 */
+  maxHedges?: Resolvable<number>;
+  /** Telemetry sink for observability. */
   telemetry?: TelemetrySink;
+  /** Clock implementation for testing. */
   clock?: any;
 }
 
+/**
+ * A structured event emitted by the telemetry system.
+ */
 export interface TelemetryEvent {
+  /** The type of event (e.g., 'retry.failure', 'circuit.open'). */
   type: string;
+  /** Unix timestamp of the event. */
   timestamp: number;
+  /** Metric increments (counters) to be aggregated by MetricsSink. */
+  metrics?: Record<string, number>;
+  /** Additional metadata (error, duration, attempts, etc.). */
   [key: string]: any;
 }
 
+/**
+ * Interface for receiving telemetry events.
+ */
 export interface TelemetrySink {
+  /**
+   * Records a telemetry event.
+   * @param event The structured event.
+   */
   emit(event: TelemetryEvent): void;
 }
 
+/**
+ * Stores telemetry events in an in-memory array. Useful for testing.
+ */
 export class InMemorySink implements TelemetrySink {
   events: TelemetryEvent[];
   emit(event: TelemetryEvent): void;
   clear(): void;
 }
 
+/**
+ * Logs telemetry events to the console (stdout).
+ */
 export class ConsoleSink implements TelemetrySink {
   emit(event: TelemetryEvent): void;
 }
 
+/**
+ * Discards all telemetry events.
+ */
 export class NoopSink implements TelemetrySink {
   emit(event: TelemetryEvent): void;
 }
 
+/**
+ * Broadcasts telemetry events to multiple other sinks.
+ */
 export class MultiSink implements TelemetrySink {
   constructor(sinks: TelemetrySink[]);
   emit(event: TelemetryEvent): void;
 }
 
+/**
+ * Sink that aggregates metrics in memory.
+ */
+export class MetricsSink implements TelemetrySink {
+  emit(event: TelemetryEvent): void;
+  /** Returns a snapshot of the current metrics. */
+  get stats(): {
+    retries: number;
+    failures: number;
+    successes: number;
+    circuitBreaks: number;
+    circuitRejections: number;
+    bulkheadRejections: number;
+    timeouts: number;
+    hedges: number;
+    latency: {
+      count: number;
+      sum: number;
+      min: number;
+      max: number;
+      avg: number;
+    };
+    [key: string]: number | { count: number; sum: number; min: number; max: number; avg: number };
+  };
+  /** Resets all metrics to zero. */
+  clear(): void;
+}
+
+/**
+ * Error thrown when all retry attempts are exhausted.
+ */
 export class RetryExhaustedError extends Error {
   attempts: number;
   cause: Error;
   constructor(attempts: number, cause: Error);
 }
 
+/**
+ * Error thrown when the circuit breaker is open (OPEN state).
+ */
 export class CircuitOpenError extends Error {
   openedAt: Date;
   failureCount: number;
   constructor(openedAt: Date, failureCount: number);
 }
 
+/**
+ * Error thrown when an operation exceeds its time limit.
+ */
 export class TimeoutError extends Error {
   timeout: number;
   elapsed: number;
   constructor(timeout: number, elapsed: number);
 }
 
+/**
+ * Error thrown when the bulkhead limit and queue are both full.
+ */
 export class BulkheadRejectedError extends Error {
   limit: number;
   queueLimit: number;
   constructor(limit: number, queueLimit: number);
 }
 
+/**
+ * Executes an async function with configurable retry logic.
+ *
+ * @param fn The async operation to execute.
+ * @param options Retry configuration options.
+ * @returns The result of the operation.
+ * @throws {RetryExhaustedError} If all retries fail.
+ */
 export function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 
+/**
+ * Represents a Circuit Breaker instance.
+ */
 export interface CircuitBreaker {
+  /**
+   * Executes a function with circuit breaker protection.
+   */
   execute<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Current state of the circuit.
+   */
   readonly state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
 }
 
+/**
+ * Creates a Circuit Breaker policy.
+ *
+ * @param options Configuration options.
+ */
 export function circuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
 
-export function timeout<T>(ms: number, fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>), options?: TimeoutOptions): Promise<T>;
+/**
+ * Executes a function with a time limit.
+ *
+ * @param ms Timeout duration in milliseconds.
+ * @param fn The function to execute. Accepts an AbortSignal if defined.
+ * @param options Configuration options.
+ */
+export function timeout<T>(
+  ms: Resolvable<number>,
+  fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>),
+  options?: TimeoutOptions
+): Promise<T>;
 
+/**
+ * Represents a Bulkhead instance.
+ */
 export interface Bulkhead {
+  /**
+   * Executes a function with concurrency limiting.
+   */
   execute<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Current load statistics.
+   */
   readonly stats: { active: number; pending: number; available: number };
 }
 
+/**
+ * Creates a Bulkhead policy for concurrency limiting.
+ *
+ * @param options Configuration options.
+ */
 export function bulkhead(options: BulkheadOptions): Bulkhead;
 
+/**
+ * Represents a Hedge policy instance.
+ */
+export interface Hedge {
+  execute<T>(fn: (signal?: AbortSignal) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Creates a Hedge policy for speculative execution.
+ * @param options Configuration options.
+ */
+export function hedge(options: HedgeOptions): Hedge;
+
+/**
+ * Composes multiple policies into a single executable policy.
+ * Policies execute from left to right (outermost to innermost).
+ *
+ * @param policies The policies to compose.
+ */
 export function compose(...policies: any[]): { execute<T>(fn: () => Promise<T>): Promise<T> };
-export function fallback(primary: any, secondary: any): { execute<T>(fn: () => Promise<T>): Promise<T> };
-export function race(primary: any, secondary: any): { execute<T>(fn: () => Promise<T>): Promise<T> };
 
+/**
+ * Creates a fallback policy. If the primary policy fails, the secondary is executed.
+ */
+export function fallback(
+  primary: any,
+  secondary: any
+): { execute<T>(fn: () => Promise<T>): Promise<T> };
+
+/**
+ * Creates a race policy. Executes both policies concurrently; the first to succeed wins.
+ */
+export function race(
+  primary: any,
+  secondary: any
+): { execute<T>(fn: () => Promise<T>): Promise<T> };
+
+/**
+ * Fluent API for building resilience policies.
+ */
 export class Policy {
   constructor(executor: (fn: () => Promise<any>) => Promise<any>);
+  /** Creates a Retry policy wrapper. */
   static retry(options?: RetryOptions): Policy;
+  /** Creates a Circuit Breaker policy wrapper. */
   static circuitBreaker(options: CircuitBreakerOptions): Policy;
-  static timeout(ms: number, options?: TimeoutOptions): Policy;
+  /** Creates a Timeout policy wrapper. */
+  static timeout(ms: Resolvable<number>, options?: TimeoutOptions): Policy;
+  /** Creates a Bulkhead policy wrapper. */
   static bulkhead(options: BulkheadOptions): Policy;
+  /** Creates a Hedge policy wrapper. */
+  static hedge(options: HedgeOptions): Policy;
+  /** Creates a pass-through (no-op) policy. */
   static noop(): Policy;
 
+  /** Wraps this policy with another (sequential composition). */
   wrap(otherPolicy: Policy): Policy;
+  /** Falls back to another policy if this one fails. */
   or(otherPolicy: Policy): Policy;
+  /** Races this policy against another. */
   race(otherPolicy: Policy): Policy;
+  /** Executes the policy chain. */
   execute<T>(fn: () => Promise<T>): Promise<T>;
 }