@rafaelsilvadeveloper/resilient-fetch 1.0.2

package/README.md

@@ -0,0 +1,85 @@
+# @rafaelsilvadeveloper/resilient-fetch
+
+A strongly typed, zero-dependency TypeScript wrapper adding retries, exponential backoff, jitter, and circuit breaker patterns to native fetch.
+
+[![NPM Version](https://img.shields.io/npm/v/@rafaelsilvadeveloper/resilient-fetch.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/resilient-fetch)
+[![Discord Support](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=flat-square)](https://discord.gg/7Fw7snafYS)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-blueviolet.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/resilient-fetch)
+
+## Features
+
+*   🛡️ **TypeScript Definitions**: Matches standard `fetch` signatures out-of-the-box.
+*   📦 **Zero Dependencies**: Built on native `fetch` API. Ideal for Cloudflare Workers, Edge runtimes, Bun, and Node.js.
+*   🚦 **Smart Retries & Backoff**: Exponential backoff with randomized jitter to prevent server overload.
+*   🔌 **Circuit Breaker**: Auto-trip requests going to failing host domains to protect application resources.
+*   ⏱️ **Timeout Handling**: Built-in request timeouts utilizing native AbortControllers.
+
+## Installation
+
+```bash
+npm install @rafaelsilvadeveloper/resilient-fetch
+```
+
+## Getting Started
+
+Replace your native `fetch` with `resilientFetch` for automatic protection:
+
+```typescript
+import { resilientFetch } from '@rafaelsilvadeveloper/resilient-fetch';
+
+async function run() {
+  // Works exactly like standard fetch, but retries under 429, 500, 502, 503, 504 errors!
+  const response = await resilientFetch('https://api.example.com/users');
+  const data = await response.json();
+  console.log(data);
+}
+
+run();
+```
+
+## Custom Resilience Options
+
+Create a custom configured resilient fetch instance:
+
+```typescript
+import { createResilientFetch } from '@rafaelsilvadeveloper/resilient-fetch';
+
+const customFetch = createResilientFetch({
+  retries: 4,               // Retry up to 4 times
+  initialDelayMs: 250,      // Start backing off at 250ms
+  maxDelayMs: 5000,         // Backoff capped at 5 seconds
+  timeoutMs: 3000,          // Abort request if it takes longer than 3 seconds
+  retryOnStatus: [429, 503], // Only retry on Rate Limit and Service Unavailable
+  circuitBreaker: {
+    failureThreshold: 5,    // Trip breaker after 5 failures to the same host
+    cooldownMs: 30000       // Cooldown host for 30 seconds before retrying
+  }
+});
+
+async function run() {
+  const response = await customFetch('https://api.my-service.com/data');
+}
+
+run();
+```
+
+## Error Handling
+
+Throws standard fetch errors or AbortErrors on timeout.
+
+```typescript
+try {
+  await resilientFetch('https://failing-api.com');
+} catch (error) {
+  console.error('Request failed after all retries:', error);
+}
+```
+
+## Support
+
+For support, questions, or discussions, join our Discord server:
+
+[![Discord Server](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=for-the-badge)](https://discord.gg/7Fw7snafYS)
+
+## License
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createResilientFetch, resilientFetch } from './resilientFetch';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resilientFetch = exports.createResilientFetch = void 0;
+var resilientFetch_1 = require("./resilientFetch");
+Object.defineProperty(exports, "createResilientFetch", { enumerable: true, get: function () { return resilientFetch_1.createResilientFetch; } });
+Object.defineProperty(exports, "resilientFetch", { enumerable: true, get: function () { return resilientFetch_1.resilientFetch; } });

package/dist/resilientFetch.d.ts

@@ -0,0 +1,6 @@
+import type { ResilientOptions } from './types';
+/**
+ * Creates a fetch client wrapped in resilience logic.
+ */
+export declare function createResilientFetch(globalOptions?: ResilientOptions): typeof fetch;
+export declare const resilientFetch: typeof fetch;

package/dist/resilientFetch.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resilientFetch = void 0;
+exports.createResilientFetch = createResilientFetch;
+class CircuitBreaker {
+    constructor(threshold = 5, cooldown = 10000) {
+        this.failures = 0;
+        this.state = 'CLOSED';
+        this.nextAttemptTime = 0;
+        this.threshold = threshold;
+        this.cooldown = cooldown;
+    }
+    checkCall() {
+        if (this.state === 'OPEN') {
+            if (Date.now() >= this.nextAttemptTime) {
+                this.state = 'HALF_OPEN';
+                return true;
+            }
+            return false;
+        }
+        return true;
+    }
+    recordSuccess() {
+        this.failures = 0;
+        this.state = 'CLOSED';
+    }
+    recordFailure() {
+        this.failures++;
+        if (this.failures >= this.threshold) {
+            this.state = 'OPEN';
+            this.nextAttemptTime = Date.now() + this.cooldown;
+        }
+    }
+}
+const breakers = new Map();
+function getBreaker(key, threshold, cooldown) {
+    let breaker = breakers.get(key);
+    if (!breaker) {
+        breaker = new CircuitBreaker(threshold, cooldown);
+        breakers.set(key, breaker);
+    }
+    return breaker;
+}
+/**
+ * Creates a fetch client wrapped in resilience logic.
+ */
+function createResilientFetch(globalOptions = {}) {
+    return async (input, init) => {
+        const urlString = input instanceof URL ? input.toString() : typeof input === 'string' ? input : input.url;
+        let host = 'global';
+        try {
+            host = new URL(urlString).host;
+        }
+        catch (_) {
+            // Ignored
+        }
+        const retries = globalOptions.retries ?? 3;
+        const initialDelay = globalOptions.initialDelayMs ?? 500;
+        const maxDelay = globalOptions.maxDelayMs ?? 10000;
+        const backoffFactor = globalOptions.backoffFactor ?? 2;
+        const retryOnStatus = globalOptions.retryOnStatus ?? [429, 500, 502, 503, 504];
+        const timeout = globalOptions.timeoutMs;
+        const cbOptions = globalOptions.circuitBreaker || {};
+        const breaker = getBreaker(host, cbOptions.failureThreshold, cbOptions.cooldownMs);
+        if (!breaker.checkCall()) {
+            throw new Error(`Circuit Breaker is OPEN for host ${host}. Request blocked.`);
+        }
+        let attempt = 0;
+        const executeWithTimeout = async (requestInit) => {
+            if (!timeout) {
+                return fetch(input, requestInit);
+            }
+            const controller = new AbortController();
+            const signal = controller.signal;
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            try {
+                const res = await fetch(input, { ...requestInit, signal });
+                clearTimeout(timeoutId);
+                return res;
+            }
+            catch (err) {
+                clearTimeout(timeoutId);
+                throw err;
+            }
+        };
+        while (true) {
+            try {
+                const response = await executeWithTimeout(init || {});
+                if (retryOnStatus.includes(response.status) && attempt < retries) {
+                    throw new Error(`Status ${response.status} triggered retry.`);
+                }
+                breaker.recordSuccess();
+                return response;
+            }
+            catch (err) {
+                attempt++;
+                breaker.recordFailure();
+                if (attempt > retries || err.name === 'AbortError') {
+                    throw err;
+                }
+                const delay = Math.min(maxDelay, initialDelay * Math.pow(backoffFactor, attempt - 1));
+                const jitter = Math.random() * 0.3 * delay; // 30% randomized jitter
+                const finalDelay = delay + jitter;
+                await new Promise((resolve) => setTimeout(resolve, finalDelay));
+            }
+        }
+    };
+}
+exports.resilientFetch = createResilientFetch();

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+export interface ResilientOptions {
+    retries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+    retryOnStatus?: number[];
+    timeoutMs?: number;
+    circuitBreaker?: {
+        failureThreshold?: number;
+        cooldownMs?: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@rafaelsilvadeveloper/resilient-fetch",
+  "version": "1.0.2",
+  "description": "A strongly typed, zero-dependency TypeScript wrapper adding retries, exponential backoff, jitter, and circuit breaker patterns to native fetch.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafael-packages/resilient-fetch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rafael-packages/resilient-fetch/issues"
+  },
+  "homepage": "https://github.com/rafael-packages/resilient-fetch#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "prepare": "bun run build",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts tests/**/*.ts"
+  },
+  "keywords": [
+    "fetch",
+    "retry",
+    "backoff",
+    "resilience",
+    "circuit-breaker",
+    "jitter",
+    "typescript"
+  ],
+  "author": "realkalashnikov",
+  "license": "MIT",
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.3"
+  }
+}