@git-stunts/alfred 0.2.0

package/src/compose.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Composition utilities for combining resilience policies.
+ *
+ * Provides functions to compose, fallback, and race policies, enabling
+ * complex resilience strategies through simple primitives.
+ *
+ * @module @git-stunts/alfred/compose
+ */
+
+/**
+ * @typedef {Object} Policy
+ * @property {<T>(fn: () => Promise<T>) => Promise<T>} execute - Executes the function with the policy applied
+ */
+
+/**
+ * Composes multiple policies into a single policy.
+ *
+ * Policies are applied from outermost to innermost. The first policy wraps
+ * the second, which wraps the third, and so on. Each policy's execute method
+ * receives a function that invokes the next policy in the chain.
+ *
+ * @param {...Policy} policies - Policies to compose (outer to inner order)
+ * @returns {Policy} - Combined policy
+ *
+ * @example
+ * const resilient = compose(
+ *   { execute: (fn) => timeout(5000, fn) },
+ *   { execute: (fn) => retry(fn, { retries: 3 }) }
+ * );
+ * // timeout wraps retry: timeout(5000, () => retry(fn, { retries: 3 }))
+ * await resilient.execute(() => fetch(url));
+ */
+export function compose(...policies) {
+  if (policies.length === 0) {
+    return {
+      execute: (fn) => fn()
+    };
+  }
+
+  return {
+    /**
+     * @template T
+     * @param {() => Promise<T>} fn - Function to execute
+     * @returns {Promise<T>}
+     */
+    execute(fn) {
+      // Build the chain from innermost to outermost
+      // policies[0] is outermost, policies[n-1] is innermost
+      let chain = fn;
+
+      for (let i = policies.length - 1; i >= 0; i--) {
+        const policy = policies[i];
+        const next = chain;
+        chain = () => policy.execute(next);
+      }
+
+      return chain();
+    }
+  };
+}
+
+/**
+ * Creates a fallback policy that tries a secondary policy if the primary fails.
+ *
+ * @param {Policy} primary - Primary policy to attempt first
+ * @param {Policy} secondary - Secondary policy to attempt on failure
+ * @returns {Policy} - Fallback policy
+ *
+ * @example
+ * const withFallback = fallback(
+ *   { execute: (fn) => fastCache.get(key) ?? fn() },
+ *   { execute: (fn) => slowDatabase.get(key) ?? fn() }
+ * );
+ * await withFallback.execute(() => computeExpensiveValue());
+ */
+export function fallback(primary, secondary) {
+  return {
+    /**
+     * @template T
+     * @param {() => Promise<T>} fn - Function to execute
+     * @returns {Promise<T>}
+     */
+    async execute(fn) {
+      try {
+        return await primary.execute(fn);
+      } catch {
+        return await secondary.execute(fn);
+      }
+    }
+  };
+}
+
+/**
+ * Creates a racing policy that runs two policies concurrently.
+ *
+ * Returns the result of whichever policy succeeds first.
+ * If both fail, throws the error from the first policy.
+ *
+ * @param {Policy} policyA - First policy to race
+ * @param {Policy} policyB - Second policy to race
+ * @returns {Policy} - Racing policy
+ *
+ * @example
+ * const fastest = race(
+ *   { execute: (fn) => primaryServer.fetch(url) },
+ *   { execute: (fn) => backupServer.fetch(url) }
+ * );
+ * await fastest.execute(() => defaultFetch(url));
+ */
+export function race(policyA, policyB) {
+  return {
+    /**
+     * @template T
+     * @param {() => Promise<T>} fn - Function to execute
+     * @returns {Promise<T>}
+     */
+    execute(fn) {
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        /** @type {Error | null} */
+        let firstError = null;
+        let failureCount = 0;
+
+        const handleSuccess = (result) => {
+          if (!settled) {
+            settled = true;
+            resolve(result);
+          }
+        };
+
+        const handleFailure = (error, isFirst) => {
+          if (settled) {
+            return;
+          }
+
+          if (isFirst) {
+            firstError = error;
+          }
+          failureCount++;
+
+          // If both have failed, reject with first error
+          if (failureCount === 2) {
+            settled = true;
+            reject(firstError);
+          }
+        };
+
+        policyA.execute(fn).then(handleSuccess, (e) => handleFailure(e, true));
+        policyB.execute(fn).then(handleSuccess, (e) => handleFailure(e, false));
+      });
+    }
+  };
+}

package/src/errors.js

@@ -0,0 +1,63 @@
+/**
+ * Error thrown when all retry attempts are exhausted.
+ */
+export class RetryExhaustedError extends Error {
+  /**
+   * @param {number} attempts - Total attempts made
+   * @param {Error} cause - The last error that caused the failure
+   */
+  constructor(attempts, cause) {
+    super(`Retry exhausted after ${attempts} attempts: ${cause.message}`);
+    this.name = 'RetryExhaustedError';
+    this.attempts = attempts;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Error thrown when circuit breaker is open.
+ */
+export class CircuitOpenError extends Error {
+  /**
+   * @param {Date} openedAt - When the circuit opened
+   * @param {number} failureCount - Number of failures that triggered opening
+   */
+  constructor(openedAt, failureCount) {
+    super(`Circuit breaker is open (since ${openedAt.toISOString()}, ${failureCount} failures)`);
+    this.name = 'CircuitOpenError';
+    this.openedAt = openedAt;
+    this.failureCount = failureCount;
+  }
+}
+
+/**
+ * Error thrown when an operation times out.
+ */
+export class TimeoutError extends Error {
+  /**
+   * @param {number} timeout - Configured timeout in ms
+   * @param {number} elapsed - Actual elapsed time in ms
+   */
+  constructor(timeout, elapsed) {
+    super(`Operation timed out after ${elapsed}ms (limit: ${timeout}ms)`);
+    this.name = 'TimeoutError';
+    this.timeout = timeout;
+    this.elapsed = elapsed;
+  }
+}
+
+/**
+ * Error thrown when bulkhead queue is full.
+ */
+export class BulkheadRejectedError extends Error {
+  /**
+   * @param {number} limit - Max concurrent executions
+   * @param {number} queueLimit - Max pending requests
+   */
+  constructor(limit, queueLimit) {
+    super(`Bulkhead rejected: queue full (limit: ${limit}, queue: ${queueLimit})`);
+    this.name = 'BulkheadRejectedError';
+    this.limit = limit;
+    this.queueLimit = queueLimit;
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,136 @@
+export interface RetryOptions {
+  retries?: number;
+  delay?: number;
+  maxDelay?: number;
+  backoff?: 'constant' | 'linear' | 'exponential';
+  jitter?: 'none' | 'full' | 'equal' | 'decorrelated';
+  shouldRetry?: (error: Error) => boolean;
+  onRetry?: (error: Error, attempt: number, delay: number) => void;
+  telemetry?: TelemetrySink;
+  clock?: any;
+}
+
+export interface CircuitBreakerOptions {
+  threshold: number;
+  duration: number;
+  successThreshold?: number;
+  shouldTrip?: (error: Error) => boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onHalfOpen?: () => void;
+  telemetry?: TelemetrySink;
+  clock?: any;
+}
+
+export interface TimeoutOptions {
+  onTimeout?: (elapsed: number) => void;
+  telemetry?: TelemetrySink;
+}
+
+export interface BulkheadOptions {
+  limit: number;
+  queueLimit?: number;
+  telemetry?: TelemetrySink;
+  clock?: any;
+}
+
+export interface TelemetryEvent {
+  type: string;
+  timestamp: number;
+  [key: string]: any;
+}
+
+export interface TelemetrySink {
+  emit(event: TelemetryEvent): void;
+}
+
+export class InMemorySink implements TelemetrySink {
+  events: TelemetryEvent[];
+  emit(event: TelemetryEvent): void;
+  clear(): void;
+}
+
+export class ConsoleSink implements TelemetrySink {
+  emit(event: TelemetryEvent): void;
+}
+
+export class NoopSink implements TelemetrySink {
+  emit(event: TelemetryEvent): void;
+}
+
+export class MultiSink implements TelemetrySink {
+  constructor(sinks: TelemetrySink[]);
+  emit(event: TelemetryEvent): void;
+}
+
+export class RetryExhaustedError extends Error {
+  attempts: number;
+  cause: Error;
+  constructor(attempts: number, cause: Error);
+}
+
+export class CircuitOpenError extends Error {
+  openedAt: Date;
+  failureCount: number;
+  constructor(openedAt: Date, failureCount: number);
+}
+
+export class TimeoutError extends Error {
+  timeout: number;
+  elapsed: number;
+  constructor(timeout: number, elapsed: number);
+}
+
+export class BulkheadRejectedError extends Error {
+  limit: number;
+  queueLimit: number;
+  constructor(limit: number, queueLimit: number);
+}
+
+export function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+export interface CircuitBreaker {
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+  readonly state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+}
+
+export function circuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
+
+export function timeout<T>(ms: number, fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>), options?: TimeoutOptions): Promise<T>;
+
+export interface Bulkhead {
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+  readonly stats: { active: number; pending: number; available: number };
+}
+
+export function bulkhead(options: BulkheadOptions): Bulkhead;
+
+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> };
+
+export class Policy {
+  constructor(executor: (fn: () => Promise<any>) => Promise<any>);
+  static retry(options?: RetryOptions): Policy;
+  static circuitBreaker(options: CircuitBreakerOptions): Policy;
+  static timeout(ms: number, options?: TimeoutOptions): Policy;
+  static bulkhead(options: BulkheadOptions): Policy;
+  static noop(): Policy;
+
+  wrap(otherPolicy: Policy): Policy;
+  or(otherPolicy: Policy): Policy;
+  race(otherPolicy: Policy): Policy;
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+export class SystemClock {
+  now(): number;
+  sleep(ms: number): Promise<void>;
+}
+
+export class TestClock {
+  now(): number;
+  sleep(ms: number): Promise<void>;
+  tick(ms?: number): Promise<void>;
+  advance(ms: number): Promise<void>;
+}

package/src/index.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Main entry point for @git-stunts/alfred resilience library.
+ * Exports all public APIs for building resilient applications.
+ */
+
+// @ts-self-types="./index.d.ts"
+
+// Error types
+export { 
+  RetryExhaustedError, 
+  CircuitOpenError, 
+  TimeoutError,
+  BulkheadRejectedError 
+} from './errors.js';
+
+// Resilience policies
+export { retry } from './policies/retry.js';
+export { circuitBreaker } from './policies/circuit-breaker.js';
+export { timeout } from './policies/timeout.js';
+export { bulkhead } from './policies/bulkhead.js';
+
+// Composition utilities
+export { compose, fallback, race } from './compose.js';
+
+// Base policy class
+export { Policy, Policy as default } from './policy.js';
+
+// Clock utilities
+export { SystemClock, TestClock } from './utils/clock.js';

package/src/policies/bulkhead.js

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Bulkhead policy for concurrency limiting.
+ *
+ * Limits the number of concurrent executions of an operation,
+ * optionally queuing excess requests up to a limit.
+ *
+ * @module @git-stunts/alfred/policies/bulkhead
+ */
+
+import { BulkheadRejectedError } from '../errors.js';
+import { SystemClock } from '../utils/clock.js';
+import { NoopSink } from '../telemetry.js';
+
+/**
+ * @typedef {Object} BulkheadOptions
+ * @property {number} limit - Maximum concurrent executions
+ * @property {number} [queueLimit=0] - Maximum pending requests in queue
+ * @property {import('../telemetry.js').TelemetrySink} [telemetry] - Telemetry sink
+ * @property {{ now(): number }} [clock] - Clock for timestamps
+ */
+
+/**
+ * @typedef {Object} BulkheadStats
+ * @property {number} active - Currently executing requests
+ * @property {number} pending - Requests waiting in queue
+ * @property {number} available - Remaining execution slots
+ */
+
+class BulkheadPolicy {
+  constructor(options) {
+    const { 
+      limit, 
+      queueLimit = 0, 
+      telemetry = new NoopSink(),
+      clock = new SystemClock() 
+    } = options;
+
+    if (limit <= 0) {
+      throw new Error('Bulkhead limit must be greater than 0');
+    }
+
+    this.limit = limit;
+    this.queueLimit = queueLimit;
+    this.telemetry = telemetry;
+    this.clock = clock;
+
+    this.active = 0;
+    this.queue = [];
+  }
+
+  processQueue() {
+    if (this.active < this.limit && this.queue.length > 0) {
+      const { fn, resolve, reject } = this.queue.shift();
+      this.active++;
+      
+      this.emitEvent('bulkhead.execute', {
+        active: this.active,
+        pending: this.queue.length
+      });
+
+      Promise.resolve()
+        .then(() => fn())
+        .then(resolve, reject)
+        .finally(() => {
+          this.active--;
+          this.emitEvent('bulkhead.complete', {
+            active: this.active,
+            pending: this.queue.length
+          });
+          this.processQueue();
+        });
+    }
+  }
+
+  emitEvent(type, data) {
+    this.telemetry.emit({
+      type,
+      timestamp: this.clock.now(),
+      ...data
+    });
+  }
+
+  async execute(fn) {
+    if (this.active < this.limit) {
+      this.active++;
+      this.emitEvent('bulkhead.execute', {
+        active: this.active,
+        pending: this.queue.length
+      });
+
+      try {
+        return await fn();
+      } finally {
+        this.active--;
+        this.emitEvent('bulkhead.complete', {
+          active: this.active,
+          pending: this.queue.length
+        });
+        this.processQueue();
+      }
+    }
+
+    if (this.queue.length < this.queueLimit) {
+      this.emitEvent('bulkhead.queued', {
+        active: this.active,
+        pending: this.queue.length + 1
+      });
+      
+      return new Promise((resolve, reject) => {
+        this.queue.push({ fn, resolve, reject });
+      });
+    }
+
+    this.emitEvent('bulkhead.reject', {
+      active: this.active,
+      pending: this.queue.length
+    });
+    throw new BulkheadRejectedError(this.limit, this.queueLimit);
+  }
+
+  get stats() {
+    return { 
+      active: this.active, 
+      pending: this.queue.length, 
+      available: Math.max(0, this.limit - this.active) 
+    };
+  }
+}
+
+/**
+ * Creates a bulkhead policy.
+ *
+ * @param {BulkheadOptions} options - Bulkhead configuration
+ * @returns {{ execute: <T>(fn: () => Promise<T>) => Promise<T>, stats: BulkheadStats }}
+ */
+export function bulkhead(options) {
+  const policy = new BulkheadPolicy(options);
+  
+  return {
+    execute: (fn) => policy.execute(fn),
+    get stats() {
+      return policy.stats;
+    }
+  };
+}

package/src/policies/circuit-breaker.js

@@ -0,0 +1,189 @@
+import { CircuitOpenError } from '../errors.js';
+import { SystemClock } from '../utils/clock.js';
+import { NoopSink } from '../telemetry.js';
+
+/**
+ * Circuit breaker states.
+ * @readonly
+ * @enum {string}
+ */
+const State = {
+  CLOSED: 'CLOSED',
+  OPEN: 'OPEN',
+  HALF_OPEN: 'HALF_OPEN'
+};
+
+/**
+ * @typedef {Object} CircuitBreakerOptions
+ * @property {number} threshold - Number of failures before opening circuit (required)
+ * @property {number} duration - Milliseconds to stay open before transitioning to half-open (required)
+ * @property {number} [successThreshold=1] - Consecutive successes in half-open to close circuit
+ * @property {(error: Error) => boolean} [shouldTrip] - Predicate to determine if error should count as failure
+ * @property {() => void} [onOpen] - Callback when circuit opens
+ * @property {() => void} [onClose] - Callback when circuit closes
+ * @property {() => void} [onHalfOpen] - Callback when circuit transitions to half-open
+ * @property {{ now(): number }} [clock] - Clock implementation for testing
+ * @property {import('../telemetry.js').TelemetrySink} [telemetry] - Telemetry sink
+ */
+
+/**
+ * @typedef {Object} CircuitBreaker
+ * @property {<T>(fn: () => Promise<T>) => Promise<T>} execute - Executes function with circuit breaker protection
+ * @property {string} state - Current circuit state (CLOSED, OPEN, HALF_OPEN)
+ */
+
+class CircuitBreakerPolicy {
+  constructor(options) {
+    const {
+      threshold,
+      duration,
+      successThreshold = 1,
+      shouldTrip = () => true,
+      onOpen,
+      onClose,
+      onHalfOpen,
+      clock = new SystemClock(),
+      telemetry = new NoopSink()
+    } = options;
+
+    if (threshold === undefined || threshold === null) {
+      throw new Error('threshold is required');
+    }
+    if (duration === undefined || duration === null) {
+      throw new Error('duration is required');
+    }
+
+    this.options = {
+      threshold,
+      duration,
+      successThreshold,
+      shouldTrip,
+      onOpen,
+      onClose,
+      onHalfOpen,
+      clock,
+      telemetry
+    };
+
+    this._state = State.CLOSED;
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.openedAt = null;
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  emitEvent(type, data) {
+    this.options.telemetry.emit({
+      type,
+      timestamp: this.options.clock.now(),
+      ...data
+    });
+  }
+
+  open() {
+    this._state = State.OPEN;
+    this.openedAt = new Date(this.options.clock.now());
+    this.options.onOpen?.();
+    this.emitEvent('circuit.open', { failureCount: this.failureCount });
+  }
+
+  close() {
+    this._state = State.CLOSED;
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.openedAt = null;
+    this.options.onClose?.();
+    this.emitEvent('circuit.close');
+  }
+
+  halfOpen() {
+    this._state = State.HALF_OPEN;
+    this.successCount = 0;
+    this.options.onHalfOpen?.();
+    this.emitEvent('circuit.half-open');
+  }
+
+  shouldAttemptReset() {
+    if (this._state !== State.OPEN || !this.openedAt) {
+      return false;
+    }
+    const elapsed = this.options.clock.now() - this.openedAt.getTime();
+    return elapsed >= this.options.duration;
+  }
+
+  recordSuccess() {
+    this.emitEvent('circuit.success', { state: this._state });
+
+    if (this._state === State.HALF_OPEN) {
+      this.successCount++;
+      if (this.successCount >= this.options.successThreshold) {
+        this.close();
+      }
+    } else if (this._state === State.CLOSED) {
+      this.failureCount = 0;
+    }
+  }
+
+  recordFailure(error) {
+    if (!this.options.shouldTrip(error)) {
+      return;
+    }
+
+    this.emitEvent('circuit.failure', {
+      error,
+      state: this._state
+    });
+
+    if (this._state === State.HALF_OPEN) {
+      this.open();
+    } else if (this._state === State.CLOSED) {
+      this.failureCount++;
+      if (this.failureCount >= this.options.threshold) {
+        this.open();
+      }
+    }
+  }
+
+  async execute(fn) {
+    if (this.shouldAttemptReset()) {
+      this.halfOpen();
+    }
+
+    if (this._state === State.OPEN) {
+      this.emitEvent('circuit.reject', {
+        openedAt: this.openedAt,
+        failureCount: this.failureCount
+      });
+      throw new CircuitOpenError(this.openedAt, this.failureCount);
+    }
+
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (error) {
+      this.recordFailure(error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Creates a circuit breaker that prevents cascading failures by failing fast
+ * when a dependency is unhealthy.
+ *
+ * @param {CircuitBreakerOptions} options - Configuration options
+ * @returns {CircuitBreaker} Circuit breaker instance
+ */
+export function circuitBreaker(options) {
+  const policy = new CircuitBreakerPolicy(options);
+  return {
+    execute: (fn) => policy.execute(fn),
+    get state() {
+      return policy.state;
+    }
+  };
+}