@git-stunts/alfred 0.2.0

package/src/testing.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/testing.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Testing utilities for @git-stunts/alfred.
+ * Provides tools for deterministic testing of resilience policies.
+ */
+
+// @ts-self-types="./testing.d.ts"
+
+export { TestClock } from './utils/clock.js';

package/src/utils/clock.js

@@ -0,0 +1,109 @@
+/**
+ * System clock using real time.
+ */
+export class SystemClock {
+  now() {
+    return Date.now();
+  }
+
+  async sleep(ms) {
+    return new Promise(resolve => {
+      const timer = setTimeout(resolve, ms);
+      if (typeof timer === 'object' && typeof timer.unref === 'function') {
+        timer.unref();
+      } else if (typeof Deno !== 'undefined' && typeof Deno.unrefTimer === 'function') {
+        // Deno returns a number ID
+        Deno.unrefTimer(timer);
+      }
+    });
+  }
+}
+
+/**
+ * Test clock for deterministic tests.
+ * Allows manual control of time progression.
+ */
+export class TestClock {
+  constructor() {
+    this._time = 0;
+    this._pendingTimers = [];
+  }
+
+  now() {
+    return this._time;
+  }
+
+  /**
+   * Creates a sleep promise that resolves when time is advanced.
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  sleep(ms) {
+    return new Promise(resolve => {
+      this._pendingTimers.push({
+        triggerAt: this._time + ms,
+        resolve
+      });
+      // Sort by trigger time
+      this._pendingTimers.sort((a, b) => a.triggerAt - b.triggerAt);
+    });
+  }
+
+  /**
+   * Advances time and resolves any pending timers.
+   * @param {number} ms - Milliseconds to advance
+   * @returns {Promise<void>}
+   */
+  async advance(ms) {
+    const targetTime = this._time + ms;
+
+    while (this._pendingTimers.length > 0) {
+      const next = this._pendingTimers[0];
+      if (next.triggerAt > targetTime) {
+        break;
+      }
+
+      this._time = next.triggerAt;
+      this._pendingTimers.shift();
+      next.resolve();
+
+      // Yield to allow async code to run
+      await Promise.resolve();
+    }
+
+    this._time = targetTime;
+  }
+
+  /**
+   * Process any timers ready at current time.
+   * @param {number} [ms=0] - Optional additional time to add
+   * @returns {Promise<void>}
+   */
+  async tick(ms = 0) {
+    await this.advance(ms);
+  }
+
+  /**
+   * Sets absolute time.
+   * @param {number} time - Time in milliseconds
+   */
+  setTime(time) {
+    this._time = time;
+  }
+
+  /**
+   * Returns number of pending timers.
+   * @returns {number}
+   */
+  get pendingCount() {
+    return this._pendingTimers.length;
+  }
+
+  /**
+   * Clears all pending timers.
+   */
+  reset() {
+    this._time = 0;
+    this._pendingTimers = [];
+  }
+}

package/src/utils/jitter.js

@@ -0,0 +1,74 @@
+/**
+ * Jitter strategies to prevent thundering herd problems.
+ *
+ * @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+ */
+
+/**
+ * No jitter - returns delay unchanged.
+ * @param {number} delay - Base delay
+ * @returns {number}
+ */
+export function noJitter(delay) {
+  return delay;
+}
+
+/**
+ * Full jitter - random delay between 0 and calculated delay.
+ * Most aggressive randomization, best for reducing collisions.
+ * @param {number} delay - Base delay
+ * @param {() => number} [random=Math.random] - Random function (0-1)
+ * @returns {number}
+ */
+export function fullJitter(delay, random = Math.random) {
+  return Math.floor(random() * delay);
+}
+
+/**
+ * Equal jitter - delay between 50% and 100% of calculated delay.
+ * Balances spread with guaranteed minimum delay.
+ * @param {number} delay - Base delay
+ * @param {() => number} [random=Math.random] - Random function (0-1)
+ * @returns {number}
+ */
+export function equalJitter(delay, random = Math.random) {
+  const half = delay / 2;
+  return Math.floor(half + random() * half);
+}
+
+/**
+ * Decorrelated jitter - AWS-style stateful jitter.
+ * Each delay is random between base delay and 3x previous delay.
+ * Creates a random walk with bounds.
+ * @param {number} baseDelay - Minimum delay
+ * @param {number} prevDelay - Previous delay (or baseDelay for first)
+ * @param {number} maxDelay - Maximum delay cap
+ * @param {() => number} [random=Math.random] - Random function (0-1)
+ * @returns {number}
+ */
+// eslint-disable-next-line max-params
+export function decorrelatedJitter(baseDelay, prevDelay, maxDelay, random = Math.random) {
+  const next = Math.floor(random() * (prevDelay * 3 - baseDelay)) + baseDelay;
+  return Math.min(next, maxDelay);
+}
+
+/**
+ * Creates a jitter function based on strategy name.
+ * @param {'none' | 'full' | 'equal' | 'decorrelated'} strategy
+ * @param {() => number} [random=Math.random]
+ * @returns {(delay: number, prevDelay?: number, maxDelay?: number) => number}
+ */
+export function createJitter(strategy, random = Math.random) {
+  switch (strategy) {
+    case 'full':
+      return (delay) => fullJitter(delay, random);
+    case 'equal':
+      return (delay) => equalJitter(delay, random);
+    case 'decorrelated':
+      return (delay, prevDelay, maxDelay) =>
+        decorrelatedJitter(delay, prevDelay || delay, maxDelay || delay * 10, random);
+    case 'none':
+    default:
+      return noJitter;
+  }
+}