@git-stunts/alfred 0.2.0 → 0.3.0

package/src/telemetry.js

@@ -5,8 +5,9 @@
 
 /**
  * @typedef {Object} TelemetryEvent
- * @property {string} type - Event type (e.g. 'retry', 'circuit.open')
+ * @property {string} type - Event type (e.g. 'retry.failure', 'circuit.open')
  * @property {number} timestamp - Event timestamp
+ * @property {Record<string, number>} [metrics] - Metric increments (counters)
  * @property {Object} [metadata] - Additional event data
  */
 
@@ -73,3 +74,85 @@ export class MultiSink {
     }
   }
 }
+
+/**
+ * Sink that aggregates metrics in memory based on the `metrics` field in events.
+ * @implements {TelemetrySink}
+ */
+export class MetricsSink {
+  constructor() {
+    this.clear();
+  }
+
+  /**
+   * Processes a telemetry event and updates internal counters.
+   * @param {TelemetryEvent} event
+   */
+  emit(event) {
+    const { duration, metrics } = event;
+
+    if (metrics && typeof metrics === 'object') {
+      this._updateMetrics(metrics);
+    }
+
+    if (typeof duration === 'number' && Number.isFinite(duration) && duration >= 0) {
+      this._updateLatency(duration);
+    }
+  }
+
+  _updateMetrics(metrics) {
+    for (const [key, value] of Object.entries(metrics)) {
+      if (typeof value !== 'number') {
+        continue;
+      }
+
+      const current = this.metrics[key];
+      if (current === undefined || typeof current === 'number') {
+        this.metrics[key] = (current || 0) + value;
+      }
+    }
+  }
+
+  _updateLatency(ms) {
+    const { latency } = this.metrics;
+    latency.count++;
+    latency.sum += ms;
+    latency.min = Math.min(latency.min, ms);
+    latency.max = Math.max(latency.max, ms);
+  }
+
+  /**
+   * Returns a snapshot of the current metrics.
+   */
+  get stats() {
+    const { latency, ...rest } = this.metrics;
+    const hasData = latency.count > 0;
+
+    return {
+      ...rest,
+      latency: {
+        ...latency,
+        min: hasData ? latency.min : 0,
+        max: hasData ? latency.max : 0,
+        avg: hasData ? latency.sum / latency.count : 0,
+      },
+    };
+  }
+
+  /**
+   * Resets all metrics to zero.
+   */
+  clear() {
+    this.metrics = {
+      retries: 0,
+      failures: 0,
+      successes: 0,
+      circuitBreaks: 0,
+      circuitRejections: 0,
+      bulkheadRejections: 0,
+      timeouts: 0,
+      hedges: 0,
+      latency: { count: 0, sum: 0, min: Infinity, max: 0 },
+    };
+  }
+}

package/src/testing.d.ts

@@ -37,6 +37,7 @@ export interface BulkheadOptions {
 export interface TelemetryEvent {
   type: string;
   timestamp: number;
+  metrics?: Record<string, number>;
   [key: string]: any;
 }
 
@@ -96,7 +97,11 @@ export interface CircuitBreaker {
 
 export function circuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
 
-export function timeout<T>(ms: number, fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>), options?: TimeoutOptions): Promise<T>;
+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>;
@@ -106,8 +111,14 @@ export interface Bulkhead {
 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 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>);

package/src/utils/clock.js

@@ -7,7 +7,7 @@ export class SystemClock {
   }
 
   async sleep(ms) {
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
       const timer = setTimeout(resolve, ms);
       if (typeof timer === 'object' && typeof timer.unref === 'function') {
         timer.unref();
@@ -39,10 +39,10 @@ export class TestClock {
    * @returns {Promise<void>}
    */
   sleep(ms) {
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
       this._pendingTimers.push({
         triggerAt: this._time + ms,
-        resolve
+        resolve,
       });
       // Sort by trigger time
       this._pendingTimers.sort((a, b) => a.triggerAt - b.triggerAt);

package/src/utils/resolvable.js

@@ -0,0 +1,10 @@
+/**
+ * Resolves a value that might be dynamic.
+ *
+ * @template T
+ * @param {T | (() => T)} value - The value or a function returning the value.
+ * @returns {T} The resolved value.
+ */
+export function resolve(value) {
+  return typeof value === 'function' ? value() : value;
+}