fetch-shield 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dilan Weerasinghe
+
+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/README.md

@@ -0,0 +1,96 @@
+# fetch-shield
+
+[![npm version](https://img.shields.io/npm/v/fetch-shield)](https://www.npmjs.com/package/fetch-shield)
+[![npm downloads](https://img.shields.io/npm/dm/fetch-shield)](https://www.npmjs.com/package/fetch-shield)
+[![license](https://img.shields.io/npm/l/fetch-shield)](./LICENSE)
+
+> Lightweight fetch/axios wrapper with automatic retries, exponential backoff, and rate-limit handling.
+
+Every developer keeps rewriting the same retry logic. `fetch-shield` solves that once, cleanly, in TypeScript.
+
+## Features
+
+- 🔁 Auto-retry with exponential backoff
+- 🚦 Rate limit (429) handling with `Retry-After` header parsing
+- 📝 Structured logging of failed requests
+- 🪶 Zero runtime dependencies (axios is optional)
+- 🔷 Full TypeScript support with generics
+- 📦 Dual CJS/ESM output
+
+## Installation
+
+```bash
+npm install fetch-shield
+# if using axios adapter:
+npm install axios
+```
+
+## Usage
+
+### fetch adapter
+
+```ts
+import { guardedFetch } from 'fetch-shield';
+
+const response = await guardedFetch<{ id: number }>(
+  'https://api.example.com/users/1',
+  {
+    maxRetries: 3,
+    baseDelay: 300,
+    onRetry: (info) => console.log(`Retrying... attempt ${info.attempt + 1}`),
+  },
+);
+
+console.log(response.data); // typed as { id: number }
+console.log(response.status); // 200
+console.log(response.attempts); // number of attempts made
+```
+
+### axios adapter
+
+```ts
+import { guardedAxios } from 'fetch-shield';
+
+const response = await guardedAxios<{ id: number }>(
+  {
+    method: 'GET',
+    url: 'https://api.example.com/users/1',
+  },
+  {
+    maxRetries: 3,
+    baseDelay: 300,
+  },
+);
+
+console.log(response.data);
+```
+
+### With logger
+
+```ts
+import { guardedFetch, defaultRetryLogger } from 'fetch-shield';
+
+const response = await guardedFetch('https://api.example.com/data', {
+  maxRetries: 3,
+  onRetry: (info) =>
+    defaultRetryLogger(info, {
+      url: 'https://api.example.com/data',
+      method: 'GET',
+    }),
+});
+```
+
+## Options
+
+| Option             | Type       | Default                          | Description                                |
+| ------------------ | ---------- | -------------------------------- | ------------------------------------------ |
+| `maxRetries`       | `number`   | `3`                              | Max retry attempts after initial try       |
+| `baseDelay`        | `number`   | `300`                            | Base delay in ms for backoff               |
+| `maxDelay`         | `number`   | `10000`                          | Max delay cap in ms                        |
+| `jitter`           | `boolean`  | `true`                           | Add random jitter to avoid thundering herd |
+| `retryStatusCodes` | `number[]` | `[408, 429, 500, 502, 503, 504]` | Status codes that trigger a retry          |
+| `onRetry`          | `function` | `undefined`                      | Called before each retry with attempt info |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "fetch-shield",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "dev": "tsup --watch"
+  },
+  "vitest": {
+    "include": [
+      "src/**/*.test.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DIlANMW/fetch-shield-pkg.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/DIlANMW/fetch-shield-pkg/issues"
+  },
+  "homepage": "https://github.com/DIlANMW/fetch-shield-pkg#readme",
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "axios": "^1.17.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^1.6.1"
+  }
+}

package/src/adapters/axios.ts

@@ -0,0 +1,78 @@
+import type { AxiosInstance, AxiosRequestConfig, AxiosError } from "axios";
+import { withRetry, parseRetryAfter } from "../core/retry";
+import { RetryOptions, GuardianResponse } from "../core/types";
+
+export interface AxiosGuardianOptions extends RetryOptions {
+  /** An axios instance, or pass nothing to use axios's default export */
+  axiosInstance?: AxiosInstance;
+}
+
+/**
+ * Wraps an axios request with automatic retries, exponential backoff,
+ * and Retry-After header support.
+ *
+ * Note: axios is a peer dependency,if it's not installed, this function
+ * will throw a clear error when called (not at import time).
+ */
+export async function guardedAxios<T = unknown>(
+  config: AxiosRequestConfig,
+  options: AxiosGuardianOptions = {}
+): Promise<GuardianResponse<T>> {
+  const { axiosInstance, ...retryOptions } = options;
+
+  let client: AxiosInstance;
+  if (axiosInstance) {
+    client = axiosInstance;
+  } else {
+    try {
+      // Lazy require so axios stays optional at runtime
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const axiosModule = require("axios");
+      client = axiosModule.default ?? axiosModule;
+    } catch {
+      throw new Error(
+        "request-guardian: axios is not installed. Run `npm install axios` to use guardedAxios, or pass an axiosInstance."
+      );
+    }
+  }
+
+  return withRetry(async (attempt) => {
+    try {
+      const res = await client.request<T>(config);
+
+      const retryAfter = parseRetryAfter(
+        (res.headers["retry-after"] as string) ?? null
+      );
+
+      return {
+        data: res.data,
+        status: res.status,
+        headers: res.headers as Record<string, string>,
+        attempts: attempt + 1,
+        retryAfter,
+      };
+    } catch (err) {
+      const axiosErr = err as AxiosError;
+
+      // If axios got  429, 500 like, treat it as a result
+      // so withRetry can decide whether to retry based on status code.
+      if (axiosErr.response) {
+        const retryAfter = parseRetryAfter(
+          (axiosErr.response.headers["retry-after"] as string) ?? null
+        );
+
+        return {
+          data: axiosErr.response.data as T,
+          status: axiosErr.response.status,
+          headers: axiosErr.response.headers as Record<string, string>,
+          attempts: attempt + 1,
+          retryAfter,
+        };
+      }
+
+      // No response (network error, timeout) rethrow so withRetry
+      // retries based on the catch branch instead.
+      throw err;
+    }
+  }, retryOptions);
+}

package/src/adapters/fetch.ts

@@ -0,0 +1,44 @@
+import { withRetry, parseRetryAfter } from "../core/retry";
+import { RetryOptions, GuardianResponse } from "../core/types";
+
+export interface FetchGuardianOptions extends RetryOptions {
+  fetchOptions?: RequestInit;
+}
+
+/**
+ * Wraps native fetch with automatic retries, exponential backoff,
+ * and Retry-After header support for 429 responses.
+ */
+export async function guardedFetch<T = unknown>(
+  url: string,
+  options: FetchGuardianOptions = {}
+): Promise<GuardianResponse<T>> {
+  const { fetchOptions, ...retryOptions } = options;
+
+  return withRetry(async (attempt) => {
+    const res = await fetch(url, fetchOptions);
+
+    const headers: Record<string, string> = {};
+    res.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    let data: T;
+    const contentType = res.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      data = (await res.json()) as T;
+    } else {
+      data = (await res.text()) as unknown as T;
+    }
+
+    const retryAfter = parseRetryAfter(res.headers.get("retry-after"));
+
+    return {
+      data,
+      status: res.status,
+      headers,
+      attempts: attempt + 1,
+      retryAfter,
+    };
+  }, retryOptions);
+}

package/src/core/retry.ts

@@ -0,0 +1,103 @@
+import { RetryOptions, RetryInfo } from "./types";
+
+export const DEFAULT_OPTIONS: Required<Omit<RetryOptions, "onRetry">> = {
+  maxRetries: 3,
+  baseDelay: 300,
+  maxDelay: 10000,
+  jitter: true,
+  retryStatusCodes: [408, 429, 500, 502, 503, 504],
+};
+
+/**
+ * Calculates delay for a given attempt using exponential backoff.
+ * Formula: min(baseDelay * 2^attempt, maxDelay) + optional jitter
+ */
+export function calculateDelay(
+  attempt: number,
+  options: Required<Omit<RetryOptions, "onRetry">>
+): number {
+  const exponential = options.baseDelay * Math.pow(2, attempt);
+  const capped = Math.min(exponential, options.maxDelay);
+
+  if (options.jitter) {
+    // Add random jitter between 0 and capped delay (full jitter strategy)
+    return Math.floor(Math.random() * capped);
+  }
+
+  return capped;
+}
+
+/**
+ * Reads a Retry-After header value (seconds or HTTP date) and converts to ms.
+ * Returns null if header is missing or unparsable.
+ */
+export function parseRetryAfter(headerValue: string | null): number | null {
+  if (!headerValue) return null;
+
+  const seconds = Number(headerValue);
+  if (!Number.isNaN(seconds)) {
+    return seconds * 1000;
+  }
+
+  const date = new Date(headerValue).getTime();
+  if (!Number.isNaN(date)) {
+    const diff = date - Date.now();
+    return diff > 0 ? diff : 0;
+  }
+
+  return null;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Generic retry wrapper. Takes a function that performs one attempt
+ * and returns a result with a status field.
+ * Retries based on status code or thrown error, with exponential backoff.
+ */
+export async function withRetry<T extends { status?: number; retryAfter?: number | null }>(
+  fn: (attempt: number) => Promise<T>,
+  userOptions: RetryOptions = {}
+): Promise<T> {
+  const options: Required<Omit<RetryOptions, "onRetry">> = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+  };
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+    try {
+      const result = await fn(attempt);
+
+      const status = result.status;
+      const shouldRetry =
+        status !== undefined && options.retryStatusCodes.includes(status);
+
+      if (!shouldRetry || attempt === options.maxRetries) {
+        return result;
+      }
+
+      // Prefer Retry-After header if present, else exponential backoff
+      const delay =
+        result.retryAfter ?? calculateDelay(attempt, options);
+
+      userOptions.onRetry?.({ attempt, error: null, delay, status });
+      await sleep(delay);
+    } catch (err) {
+      lastError = err;
+
+      if (attempt === options.maxRetries) {
+        throw err;
+      }
+
+      const delay = calculateDelay(attempt, options);
+      userOptions.onRetry?.({ attempt, error: err, delay });
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}

package/src/core/types.ts

@@ -0,0 +1,28 @@
+export interface RetryOptions {
+  /** Max number of retry attempts (not counting the initial try) */
+  maxRetries?: number;
+  /** Base delay in ms for exponential backoff */
+  baseDelay?: number;
+  /** Max delay cap in ms */
+  maxDelay?: number;
+  /** Add random jitter to avoid thundering herd */
+  jitter?: boolean;
+  /** HTTP status codes that should trigger a retry */
+  retryStatusCodes?: number[];
+  /** Called before each retry attempt, useful for logging */
+  onRetry?: (info: RetryInfo) => void;
+}
+
+export interface RetryInfo {
+  attempt: number;
+  error: unknown;
+  delay: number;
+  status?: number;
+}
+
+export interface GuardianResponse<T = unknown> {
+  data: T;
+  status: number;
+  headers: Record<string, string>;
+  attempts: number;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { guardedFetch } from "./adapters/fetch";
+export type { FetchGuardianOptions } from "./adapters/fetch";
+
+
+export { guardedAxios } from "./adapters/axios";
+export type { AxiosGuardianOptions } from "./adapters/axios";
+
+export { defaultRetryLogger, logFinalFailure } from "./utils/logger";
+export type { LogContext } from "./utils/logger";
+
+export { calculateDelay, parseRetryAfter } from "./core/retry";
+export type { RetryOptions, RetryInfo, GuardianResponse } from "./core/types";

package/src/retry.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { calculateDelay, parseRetryAfter, withRetry, sleep } from "./core/retry";
+
+// ─── calculateDelay ───────────────────────────────────────────────────────────
+
+describe("calculateDelay", () => {
+  const baseOptions = {
+    baseDelay: 300,
+    maxDelay: 10000,
+    jitter: false,
+    maxRetries: 3,
+    retryStatusCodes: [429, 500],
+  };
+
+  it("doubles delay on each attempt", () => {
+    expect(calculateDelay(0, baseOptions)).toBe(300);
+    expect(calculateDelay(1, baseOptions)).toBe(600);
+    expect(calculateDelay(2, baseOptions)).toBe(1200);
+  });
+
+  it("caps at maxDelay", () => {
+    expect(calculateDelay(10, baseOptions)).toBe(10000);
+  });
+
+  it("returns value within range when jitter is enabled", () => {
+    const delay = calculateDelay(1, { ...baseOptions, jitter: true });
+    expect(delay).toBeGreaterThanOrEqual(0);
+    expect(delay).toBeLessThanOrEqual(600);
+  });
+});
+
+// ─── parseRetryAfter ──────────────────────────────────────────────────────────
+
+describe("parseRetryAfter", () => {
+  it("parses seconds value", () => {
+    expect(parseRetryAfter("5")).toBe(5000);
+  });
+
+  it("parses HTTP date string", () => {
+    const future = new Date(Date.now() + 10000).toUTCString();
+    const result = parseRetryAfter(future);
+    expect(result).toBeGreaterThan(0);
+    expect(result).toBeLessThanOrEqual(10000);
+  });
+
+  it("returns null for null input", () => {
+    expect(parseRetryAfter(null)).toBeNull();
+  });
+
+  it("returns null for garbage input", () => {
+    expect(parseRetryAfter("not-a-date")).toBeNull();
+  });
+});
+
+// ─── sleep ────────────────────────────────────────────────────────────────────
+
+describe("sleep", () => {
+  it("resolves after the given ms", async () => {
+    const start = Date.now();
+    await sleep(50);
+    expect(Date.now() - start).toBeGreaterThanOrEqual(45);
+  });
+});
+
+// ─── withRetry ────────────────────────────────────────────────────────────────
+
+describe("withRetry", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns immediately on success", async () => {
+    vi.useFakeTimers();
+    const fn = vi.fn().mockResolvedValue({ status: 200, data: "ok" });
+
+    const promise = withRetry(fn, { maxRetries: 3, baseDelay: 100, jitter: false });
+    await vi.runAllTimersAsync();
+    const result = await promise;
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(result.status).toBe(200);
+  });
+
+  it("retries on retryable status code", async () => {
+    vi.useFakeTimers();
+    const fn = vi
+      .fn()
+      .mockResolvedValueOnce({ status: 500 })
+      .mockResolvedValueOnce({ status: 500 })
+      .mockResolvedValue({ status: 200, data: "ok" });
+
+    const promise = withRetry(fn, { maxRetries: 3, baseDelay: 100, jitter: false });
+    await vi.runAllTimersAsync();
+    const result = await promise;
+
+    expect(fn).toHaveBeenCalledTimes(3);
+    expect(result.status).toBe(200);
+  });
+
+  it("retries on thrown error then succeeds", async () => {
+    vi.useFakeTimers();
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("network error"))
+      .mockResolvedValue({ status: 200, data: "ok" });
+
+    const promise = withRetry(fn, { maxRetries: 3, baseDelay: 100, jitter: false });
+    await vi.runAllTimersAsync();
+    const result = await promise;
+
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(result.status).toBe(200);
+  });
+
+  it("throws after maxRetries exhausted", async () => {
+    // Use real timers with a tiny delay to avoid unhandled rejection issues
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("always fails"))
+      .mockRejectedValueOnce(new Error("always fails"))
+      .mockRejectedValue(new Error("always fails"));
+
+    await expect(
+      withRetry(fn, { maxRetries: 2, baseDelay: 1, jitter: false })
+    ).rejects.toThrow("always fails");
+
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it("calls onRetry with correct info", async () => {
+    vi.useFakeTimers();
+    const onRetry = vi.fn();
+    const fn = vi
+      .fn()
+      .mockResolvedValueOnce({ status: 500 })
+      .mockResolvedValue({ status: 200 });
+
+    const promise = withRetry(fn, {
+      maxRetries: 3,
+      baseDelay: 100,
+      jitter: false,
+      onRetry,
+    });
+    await vi.runAllTimersAsync();
+    await promise;
+
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    expect(onRetry).toHaveBeenCalledWith(
+      expect.objectContaining({ attempt: 0, status: 500 })
+    );
+  });
+
+  it("respects retryAfter delay from response", async () => {
+    vi.useFakeTimers();
+    const fn = vi
+      .fn()
+      .mockResolvedValueOnce({ status: 429, retryAfter: 2000 })
+      .mockResolvedValue({ status: 200, data: "ok" });
+
+    const advanceSpy = vi.spyOn(globalThis, "setTimeout");
+
+    const promise = withRetry(fn, { maxRetries: 3, baseDelay: 100, jitter: false });
+    await vi.runAllTimersAsync();
+    await promise;
+
+    const delays = advanceSpy.mock.calls.map((c) => c[1]);
+    expect(delays).toContain(2000);
+  });
+});

package/src/utils/logger.ts

@@ -0,0 +1,46 @@
+import { RetryInfo } from "../core/types";
+
+export interface LogContext {
+  url?: string;
+  method?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Default logger prints structured info about retries and failures
+ * to the console. Pass your own function via onRetry to override.
+ */
+export function defaultRetryLogger(info: RetryInfo, context: LogContext = {}): void {
+  const { attempt, status, error, delay } = info;
+
+  const base = `[request-guardian] attempt ${attempt + 1} failed`;
+  const ctx = context.url ? ` for ${context.method ?? "GET"} ${context.url}` : "";
+
+  if (status !== undefined) {
+    console.warn(`${base}${ctx} — status ${status}. Retrying in ${delay}ms...`);
+  } else {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`${base}${ctx} — error: ${message}. Retrying in ${delay}ms...`);
+  }
+}
+
+/**
+ * Logs a final failure (after all retries exhausted) with full context.
+ */
+export function logFinalFailure(
+  info: { attempts: number; status?: number; error?: unknown },
+  context: LogContext = {}
+): void {
+  const ctx = context.url ? ` ${context.method ?? "GET"} ${context.url}` : "";
+
+  if (info.status !== undefined) {
+    console.error(
+      `[request-guardian] gave up${ctx} after ${info.attempts} attempt(s) — final status ${info.status}`
+    );
+  } else {
+    const message = info.error instanceof Error ? info.error.message : String(info.error);
+    console.error(
+      `[request-guardian] gave up${ctx} after ${info.attempts} attempt(s) — ${message}`
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "types": ["node"],
+    "ignoreDeprecations": "5.0"
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: false,
+  clean: true,
+  sourcemap: true,
+});