@codingaryan/smoothapi 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,72 @@
+# @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
+
+Create your resilient fetch wrapper once and use it throughout your application:
+
+```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 {
+    // Drop-in replacement for native fetch
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codingaryan/smoothapi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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"
 }