@node-yalc/resilience 0.0.0-stage → 0.0.3

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './resilience';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./resilience"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../resilience/src/index.ts"],"names":[],"mappings":";;;AAAA,uDAA6B"}

package/dist/resilience.d.ts

@@ -0,0 +1,26 @@
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export declare class CircuitBreaker {
+    private failureThreshold;
+    private recoveryTimeMs;
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    constructor(failureThreshold?: number, recoveryTimeMs?: number);
+    execute<T>(fn: () => Promise<T>, fallback?: () => T): Promise<T>;
+    private recordFailure;
+    reset(): void;
+    getState(): CircuitState;
+}
+export declare class RateLimiter {
+    private capacity;
+    private refillRatePerSec;
+    private tokens;
+    private lastRefillTimestamp;
+    constructor(capacity?: number, refillRatePerSec?: number);
+    allowRequest(tokensRequested?: number): boolean;
+    private refill;
+}
+export declare class Singleflight {
+    private inFlightCalls;
+    do<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/resilience.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Singleflight = exports.RateLimiter = exports.CircuitBreaker = void 0;
+class CircuitBreaker {
+    constructor(failureThreshold = 5, recoveryTimeMs = 10000) {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.lastFailureTime = 0;
+        this.failureThreshold = failureThreshold;
+        this.recoveryTimeMs = recoveryTimeMs;
+    }
+    async execute(fn, fallback) {
+        const now = Date.now();
+        if (this.state === 'OPEN') {
+            if (now - this.lastFailureTime > this.recoveryTimeMs) {
+                this.state = 'HALF_OPEN';
+            }
+            else {
+                if (fallback)
+                    return fallback();
+                throw new Error('CircuitBreaker is OPEN. Execution blocked.');
+            }
+        }
+        try {
+            const result = await fn();
+            if (this.state === 'HALF_OPEN') {
+                this.reset();
+            }
+            return result;
+        }
+        catch (err) {
+            this.recordFailure();
+            if (fallback)
+                return fallback();
+            throw err;
+        }
+    }
+    recordFailure() {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        if (this.failureCount >= this.failureThreshold) {
+            this.state = 'OPEN';
+        }
+    }
+    reset() {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+    }
+    getState() {
+        return this.state;
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+class RateLimiter {
+    constructor(capacity = 100, refillRatePerSec = 10) {
+        this.capacity = capacity;
+        this.refillRatePerSec = refillRatePerSec;
+        this.tokens = capacity;
+        this.lastRefillTimestamp = Date.now();
+    }
+    allowRequest(tokensRequested = 1) {
+        this.refill();
+        if (this.tokens >= tokensRequested) {
+            this.tokens -= tokensRequested;
+            return true;
+        }
+        return false;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsedSecs = (now - this.lastRefillTimestamp) / 1000;
+        this.tokens = Math.min(this.capacity, this.tokens + elapsedSecs * this.refillRatePerSec);
+        this.lastRefillTimestamp = now;
+    }
+}
+exports.RateLimiter = RateLimiter;
+class Singleflight {
+    constructor() {
+        this.inFlightCalls = new Map();
+    }
+    async do(key, fn) {
+        if (this.inFlightCalls.has(key)) {
+            return this.inFlightCalls.get(key);
+        }
+        const promise = (async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                this.inFlightCalls.delete(key);
+            }
+        })();
+        this.inFlightCalls.set(key, promise);
+        return promise;
+    }
+}
+exports.Singleflight = Singleflight;
+//# sourceMappingURL=resilience.js.map

package/dist/resilience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.js","sourceRoot":"","sources":["../../../resilience/src/resilience.ts"],"names":[],"mappings":";;;AAaA,MAAa,cAAc;IAazB,YAAY,mBAA2B,CAAC,EAAE,iBAAyB,KAAK;QAVhE,UAAK,GAAiB,QAAQ,CAAC;QAC/B,iBAAY,GAAW,CAAC,CAAC;QACzB,oBAAe,GAAW,CAAC,CAAC;QASlC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAWM,KAAK,CAAC,OAAO,CAAI,EAAoB,EAAE,QAAkB;QAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,IAAI,GAAG,GAAG,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;gBACrD,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,IAAI,QAAQ;oBAAE,OAAO,QAAQ,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;gBAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,IAAI,QAAQ;gBAAE,OAAO,QAAQ,EAAE,CAAC;YAChC,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAMO,aAAa;QACnB,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC/C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACtB,CAAC;IACH,CAAC;IAKM,KAAK;QACV,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IACxB,CAAC;IAMM,QAAQ;QACb,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF;AA/ED,wCA+EC;AAMD,MAAa,WAAW;IAYtB,YAAY,WAAmB,GAAG,EAAE,mBAA2B,EAAE;QAC/D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACxC,CAAC;IAQM,YAAY,CAAC,kBAA0B,CAAC;QAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAMO,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;QAC5D,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACzF,IAAI,CAAC,mBAAmB,GAAG,GAAG,CAAC;IACjC,CAAC;CACF;AA5CD,kCA4CC;AAQD,MAAa,YAAY;IAAzB;QACU,kBAAa,GAA8B,IAAI,GAAG,EAAE,CAAC;IA0B/D,CAAC;IAhBQ,KAAK,CAAC,EAAE,CAAI,GAAW,EAAE,EAAoB;QAClD,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAe,CAAC;QACnD,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QAEL,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AA3BD,oCA2BC"}

package/package.json

@@ -1,6 +1,7 @@
-{
-  "name": "@node-yalc/resilience",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+    "name": "@node-yalc/resilience",
+    "version": "0.0.3",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module"
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './resilience';

package/src/resilience.ts

@@ -0,0 +1,178 @@
+/**
+ * Represents the current state of a Circuit Breaker.
+ * - `CLOSED`: Operations are permitted (normal operation).
+ * - `OPEN`: Operations are blocked because the failure threshold was exceeded.
+ * - `HALF_OPEN`: Circuit is testing the underlying service to see if it recovered.
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+/**
+ * Enterprise Circuit Breaker pattern.
+ * Prevents catastrophic cascading failures by temporarily blocking execution of 
+ * a degraded operation, giving the underlying service time to recover.
+ */
+export class CircuitBreaker {
+  private failureThreshold: number;
+  private recoveryTimeMs: number;
+  private state: CircuitState = 'CLOSED';
+  private failureCount: number = 0;
+  private lastFailureTime: number = 0;
+
+  /**
+   * Initializes the Circuit Breaker.
+   * 
+   * @param failureThreshold The number of consecutive failures before the circuit trips (opens).
+   * @param recoveryTimeMs The duration in milliseconds to remain OPEN before shifting to HALF_OPEN.
+   */
+  constructor(failureThreshold: number = 5, recoveryTimeMs: number = 10000) {
+    this.failureThreshold = failureThreshold;
+    this.recoveryTimeMs = recoveryTimeMs;
+  }
+
+  /**
+   * Executes a potentially failing asynchronous function through the circuit breaker.
+   * 
+   * @template T The expected return type of the wrapped function.
+   * @param {() => Promise<T>} fn The asynchronous operation to wrap.
+   * @param {() => T} [fallback] Optional synchronous fallback logic if the circuit is OPEN or fails.
+   * @returns {Promise<T>} The successful result of `fn` or `fallback`.
+   * @throws {Error} If execution fails and no fallback is provided, or if the circuit is OPEN.
+   */
+  public async execute<T>(fn: () => Promise<T>, fallback?: () => T): Promise<T> {
+    const now = Date.now();
+
+    if (this.state === 'OPEN') {
+      if (now - this.lastFailureTime > this.recoveryTimeMs) {
+        this.state = 'HALF_OPEN';
+      } else {
+        if (fallback) return fallback();
+        throw new Error('CircuitBreaker is OPEN. Execution blocked.');
+      }
+    }
+
+    try {
+      const result = await fn();
+      if (this.state === 'HALF_OPEN') {
+        this.reset();
+      }
+      return result;
+    } catch (err) {
+      this.recordFailure();
+      if (fallback) return fallback();
+      throw err;
+    }
+  }
+
+  /**
+   * Internal routine to increment failure metrics and trip the circuit if needed.
+   * @private
+   */
+  private recordFailure(): void {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+    if (this.failureCount >= this.failureThreshold) {
+      this.state = 'OPEN';
+    }
+  }
+
+  /**
+   * Manually resets the circuit breaker back to its baseline CLOSED state.
+   */
+  public reset(): void {
+    this.state = 'CLOSED';
+    this.failureCount = 0;
+  }
+
+  /**
+   * Returns the current operational state of the circuit.
+   * @returns {CircuitState}
+   */
+  public getState(): CircuitState {
+    return this.state;
+  }
+}
+
+/**
+ * Enterprise Token Bucket Rate Limiter.
+ * Used to throttle API usage or heavy background jobs, preventing resource exhaustion.
+ */
+export class RateLimiter {
+  private capacity: number;
+  private refillRatePerSec: number;
+  private tokens: number;
+  private lastRefillTimestamp: number;
+
+  /**
+   * Initializes the Rate Limiter.
+   * 
+   * @param capacity The maximum number of tokens the bucket can hold.
+   * @param refillRatePerSec The number of tokens added back to the bucket every second.
+   */
+  constructor(capacity: number = 100, refillRatePerSec: number = 10) {
+    this.capacity = capacity;
+    this.refillRatePerSec = refillRatePerSec;
+    this.tokens = capacity;
+    this.lastRefillTimestamp = Date.now();
+  }
+
+  /**
+   * Attempts to consume the specified number of tokens from the bucket.
+   * 
+   * @param tokensRequested The number of tokens needed for the operation (default 1).
+   * @returns {boolean} True if the tokens were successfully consumed; false if rate limited.
+   */
+  public allowRequest(tokensRequested: number = 1): boolean {
+    this.refill();
+    if (this.tokens >= tokensRequested) {
+      this.tokens -= tokensRequested;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Internal routine that mathematically calculates and adds tokens based on elapsed time.
+   * @private
+   */
+  private refill(): void {
+    const now = Date.now();
+    const elapsedSecs = (now - this.lastRefillTimestamp) / 1000;
+    this.tokens = Math.min(this.capacity, this.tokens + elapsedSecs * this.refillRatePerSec);
+    this.lastRefillTimestamp = now;
+  }
+}
+
+/**
+ * Enterprise Singleflight (Promise Coalescing) Pattern.
+ * Prevents redundant concurrent executions of an identical heavy operation.
+ * If 10 requests ask for the same data simultaneously, only 1 function execution occurs
+ * and all 10 await the single shared promise.
+ */
+export class Singleflight {
+  private inFlightCalls: Map<string, Promise<any>> = new Map();
+
+  /**
+   * Executes a deduplicated function call keyed by a unique string.
+   * 
+   * @template T The expected return type.
+   * @param key A unique identifier representing the operation (e.g., 'getUser_123').
+   * @param fn The heavy asynchronous function to execute if no flight is already active.
+   * @returns {Promise<T>} The result of the operation.
+   */
+  public async do<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    if (this.inFlightCalls.has(key)) {
+      return this.inFlightCalls.get(key) as Promise<T>;
+    }
+
+    const promise = (async () => {
+      try {
+        return await fn();
+      } finally {
+        this.inFlightCalls.delete(key);
+      }
+    })();
+
+    this.inFlightCalls.set(key, promise);
+    return promise;
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.