@git-stunts/alfred 0.2.0 → 0.3.0

package/src/index.js

@@ -6,11 +6,11 @@
 // @ts-self-types="./index.d.ts"
 
 // Error types
-export { 
-  RetryExhaustedError, 
-  CircuitOpenError, 
+export {
+  RetryExhaustedError,
+  CircuitOpenError,
   TimeoutError,
-  BulkheadRejectedError 
+  BulkheadRejectedError,
 } from './errors.js';
 
 // Resilience policies
@@ -18,6 +18,7 @@ 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';
+export { hedge } from './policies/hedge.js';
 
 // Composition utilities
 export { compose, fallback, race } from './compose.js';
@@ -27,3 +28,6 @@ export { Policy, Policy as default } from './policy.js';
 
 // Clock utilities
 export { SystemClock, TestClock } from './utils/clock.js';
+
+// Telemetry
+export { InMemorySink, ConsoleSink, NoopSink, MultiSink, MetricsSink } from './telemetry.js';

package/src/policies/bulkhead.js

@@ -10,6 +10,7 @@
 import { BulkheadRejectedError } from '../errors.js';
 import { SystemClock } from '../utils/clock.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve as resolveValue } from '../utils/resolvable.js';
 
 /**
  * @typedef {Object} BulkheadOptions
@@ -28,11 +29,11 @@ import { NoopSink } from '../telemetry.js';
 
 class BulkheadPolicy {
   constructor(options) {
-    const { 
-      limit, 
-      queueLimit = 0, 
+    const {
+      limit,
+      queueLimit = 0,
       telemetry = new NoopSink(),
-      clock = new SystemClock() 
+      clock = new SystemClock(),
     } = options;
 
     if (limit <= 0) {
@@ -49,24 +50,38 @@ class BulkheadPolicy {
   }
 
   processQueue() {
-    if (this.active < this.limit && this.queue.length > 0) {
-      const { fn, resolve, reject } = this.queue.shift();
+    const limit = resolveValue(this.limit);
+    if (this.active < limit && this.queue.length > 0) {
+      const { fn, resolve: promiseResolve, reject } = this.queue.shift();
       this.active++;
-      
+
       this.emitEvent('bulkhead.execute', {
         active: this.active,
-        pending: this.queue.length
+        pending: this.queue.length,
       });
 
       Promise.resolve()
         .then(() => fn())
-        .then(resolve, reject)
+        .then(
+          (result) => {
+            this.emitEvent('bulkhead.complete', {
+              active: this.active,
+              pending: this.queue.length,
+              metrics: { successes: 1 },
+            });
+            promiseResolve(result);
+          },
+          (error) => {
+            this.emitEvent('bulkhead.complete', {
+              active: this.active,
+              pending: this.queue.length,
+              metrics: { failures: 1 },
+            });
+            reject(error);
+          }
+        )
         .finally(() => {
           this.active--;
-          this.emitEvent('bulkhead.complete', {
-            active: this.active,
-            pending: this.queue.length
-          });
           this.processQueue();
         });
     }
@@ -76,36 +91,48 @@ class BulkheadPolicy {
     this.telemetry.emit({
       type,
       timestamp: this.clock.now(),
-      ...data
+      ...data,
     });
   }
 
   async execute(fn) {
-    if (this.active < this.limit) {
+    const limit = resolveValue(this.limit);
+    const queueLimit = resolveValue(this.queueLimit);
+
+    if (this.active < limit) {
       this.active++;
       this.emitEvent('bulkhead.execute', {
         active: this.active,
-        pending: this.queue.length
+        pending: this.queue.length,
       });
 
       try {
-        return await fn();
-      } finally {
-        this.active--;
+        const result = await fn();
+        this.emitEvent('bulkhead.complete', {
+          active: this.active,
+          pending: this.queue.length,
+          metrics: { successes: 1 },
+        });
+        return result;
+      } catch (error) {
         this.emitEvent('bulkhead.complete', {
           active: this.active,
-          pending: this.queue.length
+          pending: this.queue.length,
+          metrics: { failures: 1 },
         });
+        throw error;
+      } finally {
+        this.active--;
         this.processQueue();
       }
     }
 
-    if (this.queue.length < this.queueLimit) {
+    if (this.queue.length < queueLimit) {
       this.emitEvent('bulkhead.queued', {
         active: this.active,
-        pending: this.queue.length + 1
+        pending: this.queue.length + 1,
       });
-      
+
       return new Promise((resolve, reject) => {
         this.queue.push({ fn, resolve, reject });
       });
@@ -113,16 +140,17 @@ class BulkheadPolicy {
 
     this.emitEvent('bulkhead.reject', {
       active: this.active,
-      pending: this.queue.length
+      pending: this.queue.length,
+      metrics: { bulkheadRejections: 1 },
     });
-    throw new BulkheadRejectedError(this.limit, this.queueLimit);
+    throw new BulkheadRejectedError(limit, queueLimit);
   }
 
   get stats() {
-    return { 
-      active: this.active, 
-      pending: this.queue.length, 
-      available: Math.max(0, this.limit - this.active) 
+    return {
+      active: this.active,
+      pending: this.queue.length,
+      available: Math.max(0, resolveValue(this.limit) - this.active),
     };
   }
 }
@@ -135,11 +163,11 @@ class BulkheadPolicy {
  */
 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

@@ -1,6 +1,7 @@
 import { CircuitOpenError } from '../errors.js';
 import { SystemClock } from '../utils/clock.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
 
 /**
  * Circuit breaker states.
@@ -10,7 +11,7 @@ import { NoopSink } from '../telemetry.js';
 const State = {
   CLOSED: 'CLOSED',
   OPEN: 'OPEN',
-  HALF_OPEN: 'HALF_OPEN'
+  HALF_OPEN: 'HALF_OPEN',
 };
 
 /**
@@ -43,7 +44,7 @@ class CircuitBreakerPolicy {
       onClose,
       onHalfOpen,
       clock = new SystemClock(),
-      telemetry = new NoopSink()
+      telemetry = new NoopSink(),
     } = options;
 
     if (threshold === undefined || threshold === null) {
@@ -62,7 +63,7 @@ class CircuitBreakerPolicy {
       onClose,
       onHalfOpen,
       clock,
-      telemetry
+      telemetry,
     };
 
     this._state = State.CLOSED;
@@ -79,7 +80,7 @@ class CircuitBreakerPolicy {
     this.options.telemetry.emit({
       type,
       timestamp: this.options.clock.now(),
-      ...data
+      ...data,
     });
   }
 
@@ -87,7 +88,10 @@ class CircuitBreakerPolicy {
     this._state = State.OPEN;
     this.openedAt = new Date(this.options.clock.now());
     this.options.onOpen?.();
-    this.emitEvent('circuit.open', { failureCount: this.failureCount });
+    this.emitEvent('circuit.open', {
+      failureCount: this.failureCount,
+      metrics: { circuitBreaks: 1 },
+    });
   }
 
   close() {
@@ -111,15 +115,18 @@ class CircuitBreakerPolicy {
       return false;
     }
     const elapsed = this.options.clock.now() - this.openedAt.getTime();
-    return elapsed >= this.options.duration;
+    return elapsed >= resolve(this.options.duration);
   }
 
   recordSuccess() {
-    this.emitEvent('circuit.success', { state: this._state });
+    this.emitEvent('circuit.success', {
+      state: this._state,
+      metrics: { successes: 1 },
+    });
 
     if (this._state === State.HALF_OPEN) {
       this.successCount++;
-      if (this.successCount >= this.options.successThreshold) {
+      if (this.successCount >= resolve(this.options.successThreshold)) {
         this.close();
       }
     } else if (this._state === State.CLOSED) {
@@ -134,14 +141,15 @@ class CircuitBreakerPolicy {
 
     this.emitEvent('circuit.failure', {
       error,
-      state: this._state
+      state: this._state,
+      metrics: { failures: 1 },
     });
 
     if (this._state === State.HALF_OPEN) {
       this.open();
     } else if (this._state === State.CLOSED) {
       this.failureCount++;
-      if (this.failureCount >= this.options.threshold) {
+      if (this.failureCount >= resolve(this.options.threshold)) {
         this.open();
       }
     }
@@ -155,7 +163,8 @@ class CircuitBreakerPolicy {
     if (this._state === State.OPEN) {
       this.emitEvent('circuit.reject', {
         openedAt: this.openedAt,
-        failureCount: this.failureCount
+        failureCount: this.failureCount,
+        metrics: { circuitRejections: 1 },
       });
       throw new CircuitOpenError(this.openedAt, this.failureCount);
     }
@@ -184,6 +193,6 @@ export function circuitBreaker(options) {
     execute: (fn) => policy.execute(fn),
     get state() {
       return policy.state;
-    }
+    },
   };
-}
+}

package/src/policies/hedge.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Hedge policy for speculative execution.
+ *
+ * Starts concurrent "hedged" attempts if the primary attempt takes too long,
+ * helping to reduce tail latency in distributed systems.
+ *
+ * @module @git-stunts/alfred/policies/hedge
+ */
+
+import { SystemClock } from '../utils/clock.js';
+import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
+
+/**
+ * @typedef {Object} HedgeOptions
+ * @property {number} delay - Milliseconds to wait before spawning a hedge.
+ * @property {number} [maxHedges=1] - Maximum number of hedged attempts to spawn.
+ * @property {import('../telemetry.js').TelemetrySink} [telemetry] - Telemetry sink.
+ * @property {{ now(): number, sleep(ms: number): Promise<void> }} [clock] - Clock for testing.
+ */
+
+class HedgeExecutor {
+  constructor(fn, options) {
+    this.fn = fn;
+    this.options = {
+      telemetry: new NoopSink(),
+      clock: new SystemClock(),
+      maxHedges: 1,
+      ...options,
+    };
+    this.abortControllers = [];
+    this._finished = false;
+  }
+
+  async execute() {
+    const delay = resolve(this.options.delay);
+    const maxHedges = resolve(this.options.maxHedges);
+    const attempts = [];
+
+    // Start primary attempt
+    attempts.push(this.createAttempt(0));
+
+    // Schedule hedges
+    for (let i = 1; i <= maxHedges; i++) {
+      attempts.push(this.scheduleHedge(i, delay * i));
+    }
+
+    try {
+      return await Promise.any(attempts);
+    } finally {
+      this.cancelAll();
+    }
+  }
+
+  createAttempt(index) {
+    const controller = new AbortController();
+    this.abortControllers.push(controller);
+    const { clock, telemetry } = this.options;
+
+    const startTime = clock.now();
+    telemetry.emit({
+      type: 'hedge.attempt',
+      timestamp: startTime,
+      index,
+      metrics: index > 0 ? { hedges: 1 } : {},
+    });
+
+    return this.fn(controller.signal)
+      .then((result) => {
+        const endTime = clock.now();
+        telemetry.emit({
+          type: 'hedge.success',
+          timestamp: endTime,
+          index,
+          duration: endTime - startTime,
+          metrics: { successes: 1 },
+        });
+        return result;
+      })
+      .catch((error) => {
+        if (error.name !== 'AbortError') {
+          const endTime = clock.now();
+          telemetry.emit({
+            type: 'hedge.failure',
+            timestamp: endTime,
+            index,
+            error,
+            duration: endTime - startTime,
+            metrics: { failures: 1 },
+          });
+        }
+        throw error;
+      });
+  }
+
+  scheduleHedge(index, delayMs) {
+    return this.options.clock.sleep(delayMs).then(() => {
+      if (this._finished) {
+        return new Promise(() => {}); // Never resolve if we are done
+      }
+      return this.createAttempt(index);
+    });
+  }
+
+  cancelAll() {
+    this._finished = true;
+    for (const controller of this.abortControllers) {
+      controller.abort();
+    }
+  }
+}
+
+/**
+ * Creates a Hedge policy.
+ *
+ * @param {HedgeOptions} options - Hedge configuration
+ * @returns {{ execute: <T>(fn: () => Promise<T>) => Promise<T> }}
+ */
+export function hedge(options) {
+  return {
+    execute: (fn) => new HedgeExecutor(fn, options).execute(),
+  };
+}

package/src/policies/retry.js

@@ -11,6 +11,7 @@ import { SystemClock } from '../utils/clock.js';
 import { createJitter } from '../utils/jitter.js';
 import { RetryExhaustedError } from '../errors.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
 
 /**
  * @typedef {'constant' | 'linear' | 'exponential'} BackoffStrategy
@@ -38,7 +39,7 @@ const DEFAULT_OPTIONS = {
   delay: 1000,
   maxDelay: 30000,
   backoff: 'constant',
-  jitter: 'none'
+  jitter: 'none',
 };
 
 function calculateBackoff(strategy, baseDelay, attempt) {
@@ -59,34 +60,38 @@ class RetryExecutor {
     this.options = { ...DEFAULT_OPTIONS, ...options };
     this.clock = options.clock || new SystemClock();
     this.telemetry = options.telemetry || new NoopSink();
-    this.applyJitter = createJitter(this.options.jitter);
-    this.prevDelay = this.options.delay;
+    // this.applyJitter is now created dynamically in calculateDelay
+    this.prevDelay = resolve(this.options.delay);
   }
 
   calculateDelay(attempt) {
-    const { backoff, delay: baseDelay, maxDelay, jitter } = this.options;
+    const backoff = resolve(this.options.backoff);
+    const baseDelay = resolve(this.options.delay);
+    const maxDelay = resolve(this.options.maxDelay);
+    const jitter = resolve(this.options.jitter);
+
     const rawDelay = calculateBackoff(backoff, baseDelay, attempt);
+    const applyJitter = createJitter(jitter);
 
     if (jitter === 'decorrelated') {
-      const actual = this.applyJitter(baseDelay, this.prevDelay, maxDelay);
+      const actual = applyJitter(baseDelay, this.prevDelay, maxDelay);
       this.prevDelay = actual;
       return actual;
     }
-    
-    return Math.min(this.applyJitter(rawDelay), maxDelay);
+
+    return Math.min(applyJitter(rawDelay), maxDelay);
   }
 
   async execute() {
-    const totalAttempts = this.options.retries + 1;
-
-    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
-      const shouldStop = await this.tryAttempt(attempt, totalAttempts);
+    // Loop condition: attempt <= (current_retries + 1)
+    // We start at 1.
+    for (let attempt = 1; attempt <= resolve(this.options.retries) + 1; attempt++) {
+      const shouldStop = await this.tryAttempt(attempt);
       if (shouldStop) {
         return shouldStop.result;
       }
     }
-    
-    // Should be unreachable if logic is correct, but satisfied strict returns
+
     throw new Error('Unexpected retry loop termination');
   }
 
@@ -102,22 +107,24 @@ class RetryExecutor {
       // But we need to calculate delay first
       const delay = this.calculateDelay(attempt);
       this.emitScheduled(attempt, delay, error);
-      
+
       if (this.options.onRetry) {
         this.options.onRetry(error, attempt, delay);
       }
-      
+
       await this.clock.sleep(delay);
       return null; // Continue loop
     }
   }
 
   emitSuccess(attempt, startTime) {
+    const endTime = this.clock.now();
     this.telemetry.emit({
       type: 'retry.success',
-      timestamp: this.clock.now(),
+      timestamp: endTime,
       attempt,
-      duration: this.clock.now() - startTime
+      duration: endTime - startTime,
+      metrics: { successes: 1 },
     });
   }
 
@@ -127,30 +134,33 @@ class RetryExecutor {
       timestamp: this.clock.now(),
       attempt,
       delay,
-      error
+      error,
+      metrics: { retries: 1 },
     });
   }
 
   handleFailure(error, attempt, startTime) {
+    const endTime = this.clock.now();
     this.telemetry.emit({
       type: 'retry.failure',
-      timestamp: this.clock.now(),
+      timestamp: endTime,
       attempt,
       error,
-      duration: this.clock.now() - startTime
+      duration: endTime - startTime,
+      metrics: { failures: 1 },
     });
 
     if (this.options.shouldRetry && !this.options.shouldRetry(error)) {
       throw error;
     }
 
-    const totalAttempts = this.options.retries + 1;
+    const totalAttempts = resolve(this.options.retries) + 1;
     if (attempt >= totalAttempts) {
       this.telemetry.emit({
         type: 'retry.exhausted',
-        timestamp: this.clock.now(),
+        timestamp: endTime,
         attempts: attempt,
-        error
+        error,
       });
       throw new RetryExhaustedError(attempt, error);
     }
@@ -167,4 +177,4 @@ class RetryExecutor {
  */
 export async function retry(fn, options = {}) {
   return new RetryExecutor(fn, options).execute();
-}
+}

package/src/policies/timeout.js

@@ -9,6 +9,7 @@
 
 import { TimeoutError } from '../errors.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
 
 /**
  * @typedef {Object} TimeoutOptions
@@ -45,6 +46,7 @@ import { NoopSink } from '../telemetry.js';
  */
 export async function timeout(ms, fn, options = {}) {
   const { onTimeout, telemetry = new NoopSink() } = options;
+  const timeoutMs = resolve(ms);
   const controller = new AbortController();
   const startTime = Date.now();
 
@@ -58,16 +60,17 @@ export async function timeout(ms, fn, options = {}) {
       if (onTimeout) {
         onTimeout(elapsed);
       }
-      
+
       telemetry.emit({
         type: 'timeout',
         timestamp: Date.now(),
-        timeout: ms,
-        elapsed
+        timeout: timeoutMs,
+        elapsed,
+        metrics: { timeouts: 1, failures: 1 },
       });
 
-      reject(new TimeoutError(ms, elapsed));
-    }, ms);
+      reject(new TimeoutError(timeoutMs, elapsed));
+    }, timeoutMs);
   });
 
   try {

package/src/policy.js

@@ -34,6 +34,7 @@ import { retry } from './policies/retry.js';
 import { circuitBreaker } from './policies/circuit-breaker.js';
 import { timeout } from './policies/timeout.js';
 import { bulkhead } from './policies/bulkhead.js';
+import { hedge } from './policies/hedge.js';
 import { compose, fallback, race } from './compose.js';
 
 /**
@@ -134,6 +135,17 @@ export class Policy {
     return new Policy((fn) => limiter.execute(fn));
   }
 
+  /**
+   * Creates a Policy that speculatively executes hedged attempts.
+   *
+   * @param {import('./policies/hedge.js').HedgeOptions} options
+   * @returns {Policy}
+   */
+  static hedge(options) {
+    const hedger = hedge(options);
+    return new Policy((fn) => hedger.execute(fn));
+  }
+
   /**
    * Creates a no-op Policy that passes through to the function directly.
    *
@@ -181,10 +193,7 @@ export class Policy {
     return new Policy((fn) => {
       // Compose: outer wraps inner
       // When outer calls its "fn", that fn is actually inner's execution
-      return compose(
-        { execute: outer },
-        { execute: inner }
-      ).execute(fn);
+      return compose({ execute: outer }, { execute: inner }).execute(fn);
     });
   }
 
@@ -212,10 +221,7 @@ export class Policy {
     const secondary = otherPolicy._executor;
 
     return new Policy((fn) => {
-      return fallback(
-        { execute: primary },
-        { execute: secondary }
-      ).execute(fn);
+      return fallback({ execute: primary }, { execute: secondary }).execute(fn);
     });
   }
 
@@ -243,10 +249,7 @@ export class Policy {
     const second = otherPolicy._executor;
 
     return new Policy((fn) => {
-      return race(
-        { execute: first },
-        { execute: second }
-      ).execute(fn);
+      return race({ execute: first }, { execute: second }).execute(fn);
     });
   }