@codingaryan/smoothapi 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,102 @@
+# @codingaryan/smoothapi
+
+API resilience library for TypeScript/JavaScript. It wraps the native `fetch` API with **exponential backoff, full jitter, and a finite-state machine circuit breaker** to protect against cascading failures.
+
+Zero dependencies. Small bundle size. Built for modern ESM.
+
+## Install
+
+```bash
+npm install @codingaryan/smoothapi
+```
+
+## Features
+
+- **Exponential Backoff with Full Jitter:** Prevents the "thundering herd" problem by randomizing retry delays.
+- **Circuit Breaker (FSM):** Isolated per-domain state machine (`CLOSED` → `OPEN` → `HALF_OPEN`).
+- **Smart Retries:** Automatically retries on specific HTTP status codes (e.g., 429, 500, 502, 503, 504) while throwing immediately on client errors (400, 401, 404).
+- **Graceful Fallbacks:** Optionally serve cached or default data instantly when the circuit is `OPEN`.
+
+## Usage
+
+### Basic Usage (Defaults)
+
+If you don't need custom configurations, you can instantiate the resilient fetch with its defaults by simply passing an empty object.
+
+```typescript
+import { createResilientFetch } from '@codingaryan/smoothapi';
+
+// Create it with default settings
+const fetchWithRetry = createResilientFetch({});
+
+async function main() {
+  try {
+    // Drop-in replacement for native fetch
+    const response = await fetchWithRetry('https://api.example.com/data');
+    const data = await response.json();
+    console.log(data);
+  } catch (err) {
+    console.error("Request failed completely:", err);
+  }
+}
+```
+
+**Default Settings provided automatically:**
+- **Retries**: 3 attempts
+- **Backoff Base Delay**: 100 milliseconds
+- **Circuit Failure Threshold**: Trips after 3 consecutive failures
+- **Circuit Cooldown**: Stays open for 10 seconds before probing
+- **Status Codes to Retry**: `429`, `500`, `502`, `503`, and `504`
+
+### Advanced Usage (Custom Settings)
+
+You can override any of the defaults to suit your application's needs, such as adding a fallback object.
+
+```typescript
+import { createResilientFetch } from '@codingaryan/smoothapi';
+
+const fetchWithRetry = createResilientFetch({
+  backoff: {
+    baseDelay: 100,      // ms to wait before first retry
+    maxDelay: 30000,     // cap on exponential growth
+    maxRetries: 3        // max number of retry attempts
+  },
+  circuitBreaker: {
+    failureThreshold: 3, // trip OPEN after 3 consecutive failures
+    cooldownMs: 10000    // stay OPEN for 10 seconds before probing
+  },
+  // Optional: Return this instead of throwing when the circuit is OPEN
+  fallback: { error: "Service degraded, returning stale data." },
+  // Optional: Custom status codes to retry on
+  retryOn: [429, 500, 502, 503, 504]
+});
+
+async function main() {
+  try {
+    const response = await fetchWithRetry('https://api.example.com/data');
+    
+    // If fallback triggered, it returns your fallback object directly
+    if ('error' in response) {
+        console.log("Fallback triggered:", response.error);
+        return;
+    }
+    
+    // Otherwise it's a standard Response object
+    const data = await response.json();
+    console.log(data);
+  } catch (err) {
+    console.error("Request failed completely:", err);
+  }
+}
+```
+
+## How It Works
+
+1. **Host Extraction:** The domain is automatically extracted from the URL. The circuit breaker state is isolated per host (e.g., `api.github.com` failing won't trip the circuit for `api.stripe.com`).
+2. **Circuit Check:** Before making a network request, the breaker checks the state. If it's `OPEN`, the request is blocked instantly (returning your fallback, or throwing a `CircuitOpenError`).
+3. **Execution & Retries:** If the response status is in your `retryOn` list, it's counted as a failure and retried with backoff.
+4. **Recovery:** After `cooldownMs`, the breaker enters `HALF_OPEN` state. The next request acts as a probe. If it succeeds, the circuit closes. If it fails, it snaps back to `OPEN` immediately.
+
+## License
+
+MIT

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,CA2CzB"}

package/dist/index.js

@@ -25,9 +25,14 @@ export function createResilientFetch(globalConfig) {
             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.
+                // treated as failures manually.
                 if (retryOn.includes(response.status)) {
-                    throw new Error(`HTTP ${response.status}`);
+                    breaker.recordFailure(domain);
+                    if (attempt < backoffConfig.maxRetries) {
+                        await sleep(calculateBackoff(attempt, backoffConfig));
+                        continue;
+                    }
+                    return response;
                 }
                 breaker.recordSuccess(domain);
                 return response;

package/dist/index.js.map

@@ -1 +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"}
+{"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,gCAAgC;gBAChC,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;oBACtC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;oBAC9B,IAAI,OAAO,GAAG,aAAa,CAAC,UAAU,EAAE,CAAC;wBACvC,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;wBACtD,SAAS;oBACX,CAAC;oBACD,OAAO,QAAQ,CAAC;gBAClB,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codingaryan/smoothapi",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "API resilience library — exponential backoff and circuit breaker for fetch",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,7 +11,9 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc --watch",
@@ -25,6 +27,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "keywords": ["resilience", "circuit-breaker", "retry", "backoff", "fetch"],
+  "keywords": [
+    "resilience",
+    "circuit-breaker",
+    "retry",
+    "backoff",
+    "fetch"
+  ],
   "license": "MIT"
 }