@codingaryan/smoothapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aryan Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { ResilientFetchConfig } from "./types.js";
+export declare function createResilientFetch<T>(globalConfig: ResilientFetchConfig<T>): (url: string | URL, options?: RequestInit) => Promise<Response | T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAUpE,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,YAAY,EAAE,oBAAoB,CAAC,CAAC,CAAC,IAMzE,KAAK,MAAM,GAAG,GAAG,EACjB,UAAU,WAAW,KACpB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAsCzB"}

package/dist/index.js

@@ -0,0 +1,47 @@
+import { CircuitBreakerState } from "./state.js";
+import { calculateBackoff, sleep } from "./utils/backoff.js";
+import { CircuitOpenError } from "./types.js";
+const BACKOFF_DEFAULTS = {
+    baseDelay: 100,
+    maxDelay: 30_000,
+    maxRetries: 3,
+};
+const DEFAULT_RETRY_ON = [429, 500, 502, 503, 504];
+export function createResilientFetch(globalConfig) {
+    const backoffConfig = { ...BACKOFF_DEFAULTS, ...globalConfig.backoff };
+    const retryOn = globalConfig.retryOn ?? DEFAULT_RETRY_ON;
+    const breaker = new CircuitBreakerState(globalConfig.circuitBreaker);
+    return async function resilientFetch(url, options) {
+        const domain = new URL(url).hostname;
+        // Block before any network IO if the circuit is OPEN.
+        if (!breaker.canRequest(domain)) {
+            if (globalConfig.fallback !== undefined) {
+                return globalConfig.fallback;
+            }
+            throw new CircuitOpenError(domain);
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= backoffConfig.maxRetries; attempt++) {
+            try {
+                const response = await fetch(url, options);
+                // fetch() resolves for any HTTP status. Retryable codes need to be
+                // treated as failures manually so they dont throw on their own.
+                if (retryOn.includes(response.status)) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                breaker.recordSuccess(domain);
+                return response;
+            }
+            catch (err) {
+                lastError = err;
+                breaker.recordFailure(domain);
+                // Don't sleep after the final attempt
+                if (attempt < backoffConfig.maxRetries) {
+                    await sleep(calculateBackoff(attempt, backoffConfig));
+                }
+            }
+        }
+        throw lastError;
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAwB,MAAM,YAAY,CAAC;AAEpE,MAAM,gBAAgB,GAAG;IACvB,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,MAAM;IAChB,UAAU,EAAE,CAAC;CACd,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAEnD,MAAM,UAAU,oBAAoB,CAAI,YAAqC;IAC3E,MAAM,aAAa,GAAG,EAAE,GAAG,gBAAgB,EAAE,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC;IACvE,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,mBAAmB,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAErE,OAAO,KAAK,UAAU,cAAc,CAClC,GAAiB,EACjB,OAAqB;QAErB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QAErC,sDAAsD;QACtD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,IAAI,YAAY,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACxC,OAAO,YAAY,CAAC,QAAa,CAAC;YACpC,CAAC;YACD,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,SAAkB,CAAC;QAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YACrE,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBAE3C,mEAAmE;gBACnE,gEAAgE;gBAChE,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;oBACtC,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC7C,CAAC;gBAED,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;gBAC9B,OAAO,QAAQ,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,SAAS,GAAG,GAAG,CAAC;gBAChB,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;gBAE9B,sCAAsC;gBACtC,IAAI,OAAO,GAAG,aAAa,CAAC,UAAU,EAAE,CAAC;oBACvC,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;gBACxD,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,SAAS,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC"}

package/dist/state.d.ts

@@ -0,0 +1,12 @@
+import type { CircuitState, CircuitBreakerConfig } from "./types.js";
+export declare class CircuitBreakerState {
+    private readonly config;
+    private readonly map;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    private getOrCreate;
+    canRequest(domain: string): boolean;
+    recordSuccess(domain: string): void;
+    recordFailure(domain: string): void;
+    getState(domain: string): CircuitState;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAiB,MAAM,YAAY,CAAC;AAOpF,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAEpC,MAAM,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAKtD,OAAO,CAAC,WAAW;IAWnB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAcnC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAMnC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAcnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;CAKzC"}

package/dist/state.js

@@ -0,0 +1,57 @@
+const DEFAULTS = {
+    failureThreshold: 3,
+    cooldownMs: 10_000,
+};
+export class CircuitBreakerState {
+    config;
+    map;
+    constructor(config = {}) {
+        this.config = { ...DEFAULTS, ...config };
+        this.map = new Map();
+    }
+    getOrCreate(domain) {
+        if (!this.map.has(domain)) {
+            this.map.set(domain, {
+                state: 'CLOSED',
+                failureCount: 0,
+                lastFailureTime: 0,
+            });
+        }
+        return this.map.get(domain);
+    }
+    canRequest(domain) {
+        const entry = this.getOrCreate(domain);
+        if (entry.state === "CLOSED" || entry.state === "HALF_OPEN")
+            return true;
+        const elapsedTime = Date.now() - entry.lastFailureTime;
+        if (elapsedTime > this.config.cooldownMs) {
+            entry.state = "HALF_OPEN";
+            return true;
+        }
+        else {
+            return false;
+        }
+    }
+    recordSuccess(domain) {
+        const entry = this.getOrCreate(domain);
+        entry.state = "CLOSED";
+        entry.failureCount = 0;
+    }
+    recordFailure(domain) {
+        const entry = this.getOrCreate(domain);
+        entry.failureCount++;
+        if (entry.state === "HALF_OPEN") {
+            entry.state = "OPEN";
+            entry.lastFailureTime = Date.now();
+            return;
+        }
+        else if (entry.failureCount >= this.config.failureThreshold) {
+            entry.state = "OPEN";
+            entry.lastFailureTime = Date.now();
+        }
+    }
+    getState(domain) {
+        return this.getOrCreate(domain).state;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAmC;IAC7C,gBAAgB,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM;CACrB,CAAA;AAED,MAAM,OAAO,mBAAmB;IACX,MAAM,CAAiC;IACvC,GAAG,CAA4B;IAEhD,YAAY,SAAwC,EAAE;QAClD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAC,CAAC;QACxC,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IACzB,CAAC;IAEO,WAAW,CAAC,MAAc;QAClC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE;gBACrB,KAAK,EAAE,QAAQ;gBACf,YAAY,EAAE,CAAC;gBACf,eAAe,EAAE,CAAC;aACjB,CAAC,CAAC;QACP,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;IAC7B,CAAC;IAED,UAAU,CAAC,MAAc;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvC,IAAG,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,WAAW;YACtD,OAAO,IAAI,CAAC;QAChB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,eAAe,CAAC;QACvD,IAAG,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,EAAC,CAAC;YACrC,KAAK,CAAC,KAAK,GAAG,WAAW,CAAC;YAC1B,OAAO,IAAI,CAAC;QAChB,CAAC;aACG,CAAC;YACD,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;IAED,aAAa,CAAC,MAAc;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvC,KAAK,CAAC,KAAK,GAAG,QAAQ,CAAC;QACvB,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,aAAa,CAAC,MAAc;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvC,KAAK,CAAC,YAAY,EAAE,CAAC;QACrB,IAAG,KAAK,CAAC,KAAK,KAAK,WAAW,EAAC,CAAC;YAC5B,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC;YACrB,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACnC,OAAM;QACV,CAAC;aACI,IAAI,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAC,CAAC;YACzD,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC;YACrB,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvC,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC;IAC1C,CAAC;CAGJ"}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface CircuitEntry {
+    state: CircuitState;
+    failureCount: number;
+    lastFailureTime: number;
+}
+export interface BackoffConfig {
+    baseDelay: number;
+    maxDelay: number;
+    maxRetries: number;
+}
+export interface CircuitBreakerConfig {
+    failureThreshold: number;
+    cooldownMs: number;
+}
+export interface ResilientFetchConfig<T = unknown> {
+    backoff?: Partial<BackoffConfig>;
+    circuitBreaker?: Partial<CircuitBreakerConfig>;
+    fallback?: T;
+    retryOn?: number[];
+}
+export declare class CircuitOpenError extends Error {
+    readonly domain: string;
+    constructor(domain: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC/C,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAGD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAO3B"}

package/dist/types.js

@@ -0,0 +1,12 @@
+// Thrown when the circuit is OPEN and no fallback is configured.
+export class CircuitOpenError extends Error {
+    domain;
+    constructor(domain) {
+        super(`Circuit breaker is OPEN for domain: ${domain}`);
+        this.name = 'CircuitOpenError';
+        this.domain = domain;
+        // Fixes instanceof checks when output is downleveled past ES2022.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA4BA,iEAAiE;AACjE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,uCAAuC,MAAM,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,kEAAkE;QAClE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/utils/backoff.d.ts

@@ -0,0 +1,4 @@
+import type { BackoffConfig } from "../types.js";
+export declare function calculateBackoff(attempt: number, config: BackoffConfig): number;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/utils/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,wBAAgB,gBAAgB,CAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAI,MAAM,CAKjF;AAED,wBAAgB,KAAK,CAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhD"}

package/dist/utils/backoff.js

@@ -0,0 +1,10 @@
+export function calculateBackoff(attempt, config) {
+    const exponential = config.baseDelay * (2 ** attempt);
+    const capped = Math.min(config.maxDelay, exponential);
+    const jitter = Math.random() * capped;
+    return jitter;
+}
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=backoff.js.map

package/dist/utils/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAE,OAAe,EAAE,MAAqB;IACpE,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,GAAG,CAAE,CAAC,IAAE,OAAO,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAE,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;IACtC,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,KAAK,CAAE,EAAU;IAC7B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@codingaryan/smoothapi",
+  "version": "0.1.0",
+  "description": "API resilience library — exponential backoff and circuit breaker for fetch",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/tests/resilience.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["resilience", "circuit-breaker", "retry", "backoff", "fetch"],
+  "license": "MIT"
+}