safe-fetch-iq 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noteal Labs
+
+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,422 @@
+# safe-fetch-iq – Smart, Safe HTTP Fetch for JS/TS
+
+safe-fetch-iq is a small TypeScript library that makes `fetch` safe and ergonomic by default, powered internally by an intelligent retry engine.
+- Drop-in `fetch` replacement (`import fetch from "safe-fetch-iq"`)
+- Smart defaults: retry, timeout, auto JSON/text parsing
+- Request deduplication and response caching
+- Built on native `fetch` (Node 18+ and browsers)
+- Zero runtime dependencies, tiny bundle size
+
+## Installation
+
+```bash
+npm install safe-fetch-iq
+```
+
+If you use TypeScript, `typescript` and `@types/node` should be available in your project.
+
+## Quick Start
+
+```ts
+import fetch from "safe-fetch-iq";
+
+const users = await fetch("https://api.example.com/users");
+
+console.log(users);
+```
+
+Default behavior:
+
+- Retries network and transient errors up to 3 times
+- Per-attempt timeout of 30 seconds
+- Automatically parses JSON or text based on `Content-Type`
+- Follows redirects using native fetch behavior
+- Throws descriptive errors instead of silent failures
+
+## Smart Options
+
+safe-fetch-iq extends the standard `RequestInit` with a few focused options:
+
+```ts
+import fetch from "safe-fetch-iq";
+
+const data = await fetch("https://api.example.com/data", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ foo: "bar" }),
+
+  retry: 5,
+  timeout: 10_000,
+  retryOn: [429, 503],
+  retryDelay: attempt => attempt * 1000,
+  dedupe: true,
+  cache: "5m"
+});
+```
+
+Supported options:
+
+- `retry?: number`
+  - Maximum retry attempts (default: `3`)
+- `timeout?: number`
+  - Per-attempt timeout in milliseconds (default: `30000`)
+- `retryOn?: number[]`
+  - HTTP status codes to retry (e.g. `[429, 503]`)
+- `retryDelay?: (attempt: number) => number`
+  - Custom backoff function for delay in ms
+- `dedupe?: boolean`
+  - Request deduplication for identical in-flight `GET` requests (default: `true`)
+- `cache?: number | string`
+  - Response cache TTL for `GET` requests
+  - Number (ms) or string like `"10s"`, `"5m"`, `"1h"`
+
+All regular `fetch` options still work. You can also pass an `AbortSignal` via `signal` as usual.
+
+## Request Deduplication
+
+When `dedupe` is enabled (default), concurrent identical `GET` requests share the same promise:
+
+```ts
+import fetch from "safe-fetch-iq";
+
+const p1 = fetch("https://api.example.com/users");
+const p2 = fetch("https://api.example.com/users");
+
+// p1 and p2 resolve with the same underlying network response
+const [a, b] = await Promise.all([p1, p2]);
+```
+
+This avoids stampedes when multiple parts of your app request the same data at the same time.
+
+## Response Caching
+
+For `GET` requests, you can enable simple in-memory caching:
+
+```ts
+import fetch from "safe-fetch-iq";
+
+// Cache for 5 minutes
+const data = await fetch("https://api.example.com/data", {
+  cache: "5m"
+});
+```
+
+- The cache key is based on method+URL+body
+- Calls within the TTL return the cached parsed value
+- After TTL expires, a new request is made and cache is refreshed
+
+## Error Handling
+
+safe-fetch-iq throws when:
+
+- The response is not `ok` (non-2xx), after applying retries
+- Retries are exhausted or cancelled by rules
+
+Example:
+
+```ts
+import fetch, { RetryIQError } from "safe-fetch-iq";
+
+try {
+  const data = await fetch("https://api.example.com/data", {
+    retry: 5,
+    retryOn: [429, 503]
+  });
+  console.log(data);
+} catch (err) {
+  if (err instanceof RetryIQError) {
+    console.error("Retry failed", err.metadata);
+  } else {
+    console.error("Unexpected error", err);
+  }
+}
+```
+
+`RetryIQError` includes metadata:
+
+- `attempt` – last attempt index
+- `totalAttempts`
+- `errorType`
+- `elapsedMs`
+
+Non-OK HTTP responses are surfaced as errors that still carry the original `Response` for advanced handling.
+
+## Advanced Use: withRetry Engine
+
+Under the hood, safe-fetch-iq is powered by a generic intelligent retry engine. You can use it directly for other clients like `axios`, custom HTTP clients, or even non-HTTP operations.
+
+### Core Idea
+
+```ts
+import { withRetry } from "safe-fetch-iq";
+
+const result = await withRetry(async (attempt, signal) => {
+  return doSomethingHttpLike(attempt, signal);
+});
+```
+
+The engine decides when to retry, how long to wait, and when to give up.
+
+### Smart Behavior
+
+### 1. Detects Retry-After
+
+When the server returns `429` or `5xx` with a `Retry-After` header, the engine parses the header and waits at least that long before the next attempt.
+
+- `Retry-After: 10` is interpreted as 10 seconds
+- `Retry-After: Wed, 21 Oct 2015 07:28:00 GMT` is treated as an absolute time
+
+If no `Retry-After` header exists, standard backoff is used.
+
+### 2. Error-Aware Backoff
+
+Errors are classified into types:
+
+- `rateLimit` – typically HTTP `429`
+- `serverError` – HTTP `5xx`
+- `networkError` – connection resets, timeouts, DNS errors
+- `clientError` – `4xx` that should not be retried
+- `unknown` – anything else
+
+By default, only `rateLimit`, `serverError`, `networkError`, and `unknown` are retried. Client errors are treated as final.
+
+### 3. Budget-Aware Retries
+
+You control how aggressive the retries can be.
+
+```ts
+import { withRetry } from "safe-fetch-iq";
+
+const response = await withRetry(
+  () => fetch("https://api.example.com/data"),
+  {
+    budget: {
+      maxRetries: 5,
+      maxRetryTimeMs: 60_000
+    }
+  }
+);
+```
+
+- `maxRetries` – maximum number of retry attempts
+- `maxRetryTimeMs` – hard cap on total time spent retrying
+
+If the server sends rate-limit headers:
+
+- `X-RateLimit-Remaining`
+- `X-Rate-Limit-Remaining`
+
+and they indicate that you are out of quota, Retry IQ stops early instead of blindly continuing to hit the API.
+
+## Backoff Configuration
+
+```ts
+import { withRetry } from "safe-fetch-iq";
+
+await withRetry(
+  () => fetch("https://api.example.com/data"),
+  {
+    backoff: {
+      baseDelayMs: 250,
+      maxDelayMs: 30_000,
+      factor: 2,
+      jitter: "full",
+      perErrorType: {
+        rateLimit: {
+          baseDelayMs: 1000
+        }
+      }
+    }
+  }
+);
+```
+
+- `baseDelayMs` – first delay before backoff, default `250`
+- `factor` – exponential factor, default `2`
+- `maxDelayMs` – max per-attempt delay, default `30000`
+- `jitter`
+  - `"none"` – deterministic backoff
+  - `"full"` – random between `0` and `delay`
+  - `"decorrelated"` – random between `delay / 2` and `delay`
+- `perErrorType` – override backoff settings per error type
+
+## shouldRetry Hook
+
+Use `shouldRetry` to inject custom rules.
+
+```ts
+import { withRetry } from "safe-fetch-iq";
+
+await withRetry(
+  () => fetch("https://api.example.com/data"),
+  {
+    shouldRetry: (error, context) => {
+      if (context.errorType === "clientError") return false;
+      if (context.attempt > 3) return false;
+      return true;
+    }
+  }
+);
+```
+
+You receive both the error and detailed context, including the calculated next delay.
+
+## Logging
+
+Pass a logger to understand how retries behave in production.
+
+```ts
+import { withRetry } from "safe-fetch-iq";
+
+await withRetry(
+  () => fetch("https://api.example.com/data"),
+  {
+    logger: event => {
+      if (event.type === "retry") {
+        console.log(
+          `[RetryIQ] ${event.operationName ?? "operation"} attempt ${event.attempt} – waiting ${event.delayMs}ms`
+        );
+      }
+      if (event.type === "giveUp") {
+        console.warn(
+          `[RetryIQ] giving up after ${event.attempt} attempts due to ${event.reason} (${event.errorType})`
+        );
+      }
+      if (event.type === "succeeded") {
+        console.log(
+          `[RetryIQ] succeeded in ${event.elapsedMs}ms after ${event.attempt} attempts`
+        );
+      }
+    }
+  }
+);
+```
+
+## Using AbortSignal
+
+You can cancel the entire retry sequence with an `AbortSignal`.
+
+```ts
+import { withRetry } from "safe-fetch-iq";
+
+const controller = new AbortController();
+
+const promise = withRetry(
+  (attempt, signal) => fetch("https://api.example.com/data", { signal }),
+  {
+    signal: controller.signal
+  }
+);
+
+setTimeout(() => controller.abort(), 5000);
+
+await promise;
+```
+
+If the signal is aborted, Retry IQ stops immediately.
+
+## Error Handling
+
+When retries are exhausted or cancelled by rules, the engine throws a `RetryIQError`.
+
+```ts
+import { withRetry, RetryIQError } from "safe-fetch-iq";
+
+try {
+  await withRetry(() => fetch("https://api.example.com/data"));
+} catch (err) {
+  if (err instanceof RetryIQError) {
+    console.error("Retry failed", err.metadata);
+  } else {
+    console.error("Unexpected error", err);
+  }
+}
+```
+
+`RetryIQError` includes metadata:
+
+- `attempt` – last attempt index
+- `totalAttempts`
+- `errorType`
+- `elapsedMs`
+
+## Adapters
+
+### fetch adapter
+
+If you prefer a dedicated wrapper on top of native fetch:
+
+```ts
+import { withRetryFetch } from "safe-fetch-iq";
+
+const fetchWithRetry = withRetryFetch(fetch);
+
+const response = await fetchWithRetry("https://api.example.com/data");
+```
+
+You can pass options on each call:
+
+```ts
+const response = await fetchWithRetry(
+  "https://api.example.com/data",
+  { method: "GET" },
+  {
+    budget: { maxRetries: 3 }
+  }
+);
+```
+
+### axios adapter
+
+```ts
+import axios from "axios";
+import { withRetryAxios } from "safe-fetch-iq";
+
+const axiosClient = axios.create({ baseURL: "https://api.example.com" });
+
+const axiosWithRetryFactory = withRetryAxios(axiosClient);
+const axiosWithRetry = axiosWithRetryFactory({
+  budget: { maxRetries: 4 }
+});
+
+const response = await axiosWithRetry.request({ method: "GET", url: "/users" });
+console.log(response.data);
+```
+
+## API Reference
+
+### withRetry(operation, options?)
+
+Wraps any async operation with intelligent retry behavior.
+
+- `operation(attempt, signal)` – async function that performs the work
+- `options` – `RetryIQOptions`
+
+### RetryIQOptions
+
+- `operationName?: string`
+- `classifyError?: (error) => RetryErrorType`
+- `shouldRetry?: (error, context) => boolean | Promise<boolean>`
+- `budget?: RetryBudgetConfig`
+- `backoff?: RetryBackoffConfig`
+- `logger?: (event: RetryEvent) => void`
+- `respectRetryAfterHeader?: boolean` (default `true`)
+- `signal?: AbortSignal`
+
+### Backoff and budget types
+
+- `RetryBudgetConfig`
+  - `maxRetries: number`
+  - `maxRetryTimeMs?: number`
+- `RetryBackoffConfig`
+  - `baseDelayMs?: number`
+  - `maxDelayMs?: number`
+  - `factor?: number`
+  - `jitter?: "none" | "full" | "decorrelated"`
+  - `perErrorType?: Partial<Record<RetryErrorType, Partial<Omit<RetryBackoffConfig, "perErrorType">>>>`
+
+## When To Use safe-fetch-iq
+
+- You want a safer default `fetch` with retries and timeouts
+- You need simple request deduplication and caching without extra infra
+- You prefer zero-dependency utilities over heavyweight HTTP clients

package/dist/abort.d.ts

@@ -0,0 +1,3 @@
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function mergeAbortSignals(inner: AbortSignal, outer?: AbortSignal): AbortSignal;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAEA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBrE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,CAiBtF"}

package/dist/abort.js

@@ -0,0 +1,48 @@
+import { RetryAbortError } from "./errors";
+export function delay(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(onDone, ms);
+        function onDone() {
+            if (signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
+            resolve();
+        }
+        function onAbort() {
+            clearTimeout(timeout);
+            reject(new RetryAbortError());
+        }
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(timeout);
+                reject(new RetryAbortError());
+            }
+            else {
+                signal.addEventListener("abort", onAbort);
+            }
+        }
+    });
+}
+export function mergeAbortSignals(inner, outer) {
+    if (!outer)
+        return inner;
+    if (outer.aborted)
+        return outer;
+    const controller = new AbortController();
+    const onOuterAbort = () => {
+        controller.abort();
+        inner.removeEventListener("abort", onInnerAbort);
+        outer.removeEventListener("abort", onOuterAbort);
+    };
+    const onInnerAbort = () => {
+        controller.abort();
+        inner.removeEventListener("abort", onInnerAbort);
+        outer.removeEventListener("abort", onOuterAbort);
+    };
+    inner.addEventListener("abort", onInnerAbort);
+    outer.addEventListener("abort", onOuterAbort);
+    return controller.signal;
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IACtC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACvC,SAAS,MAAM;YACb,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,SAAS,OAAO;YACd,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,YAAY,CAAC,OAAO,CAAC,CAAC;gBACtB,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAkB,EAAE,KAAmB;IACvE,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAChC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACjD,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACnD,CAAC,CAAC;IACF,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACjD,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACnD,CAAC,CAAC;IACF,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC9C,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC9C,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC"}

package/dist/adapters.d.ts

@@ -0,0 +1,9 @@
+import { WithRetryOptions } from "./types";
+export type FetchLike = (input: unknown, init?: unknown) => Promise<unknown>;
+export declare function withRetryFetch(fetchImpl: FetchLike): (input: unknown, init?: unknown, options?: WithRetryOptions) => Promise<unknown>;
+export declare function withRetryAxios<TInstance extends {
+    request(config: any): Promise<any>;
+}>(axiosInstance: TInstance): (defaultOptions?: WithRetryOptions) => {
+    request(config: any, options?: WithRetryOptions): Promise<any>;
+};
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7E,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,IAE/C,OAAO,OAAO,EACd,OAAO,OAAO,EACd,UAAU,gBAAgB,KACzB,OAAO,CAAC,OAAO,CAAC,CAMpB;AAED,wBAAgB,cAAc,CAAC,SAAS,SAAS;IAAE,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;CAAE,EACrF,aAAa,EAAE,SAAS,IAEa,iBAAiB,gBAAgB;oBAGlD,GAAG,YAAY,gBAAgB;EASpD"}

package/dist/adapters.js

@@ -0,0 +1,18 @@
+import { withRetry } from "./core";
+export function withRetryFetch(fetchImpl) {
+    return async function fetchWithRetry(input, init, options) {
+        return withRetry(() => fetchImpl(input, init), options);
+    };
+}
+export function withRetryAxios(axiosInstance) {
+    return function createAxiosWithRetry(defaultOptions) {
+        const instance = axiosInstance;
+        return {
+            request(config, options) {
+                const mergedOptions = { ...(defaultOptions !== null && defaultOptions !== void 0 ? defaultOptions : {}), ...(options !== null && options !== void 0 ? options : {}) };
+                return withRetry(() => instance.request(config), mergedOptions);
+            }
+        };
+    };
+}
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAKnC,MAAM,UAAU,cAAc,CAAC,SAAoB;IACjD,OAAO,KAAK,UAAU,cAAc,CAClC,KAAc,EACd,IAAc,EACd,OAA0B;QAE1B,OAAO,SAAS,CACd,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,EAC5B,OAAO,CACR,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,aAAwB;IAExB,OAAO,SAAS,oBAAoB,CAAC,cAAiC;QACpE,MAAM,QAAQ,GAAG,aAAa,CAAC;QAC/B,OAAO;YACL,OAAO,CAAC,MAAW,EAAE,OAA0B;gBAC7C,MAAM,aAAa,GAAqB,EAAE,GAAG,CAAC,cAAc,aAAd,cAAc,cAAd,cAAc,GAAI,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC,EAAE,CAAC;gBAC1F,OAAO,SAAS,CACd,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAC9B,aAAa,CACd,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/backoff.d.ts

@@ -0,0 +1,9 @@
+import { RetryBackoffConfig, RetryBudgetConfig, RetryErrorType } from "./types";
+export declare const defaultBudget: RetryBudgetConfig;
+export declare const defaultBackoff: RetryBackoffConfig;
+export declare function defaultClassifyError(error: unknown): RetryErrorType;
+export declare function isRetriableType(errorType: RetryErrorType): boolean;
+export declare function mergeBackoffConfig(base: RetryBackoffConfig, errorType: RetryErrorType): Required<Omit<RetryBackoffConfig, "perErrorType">>;
+export declare function computeBackoffDelayMs(baseConfig: RetryBackoffConfig, errorType: RetryErrorType, attempt: number): number;
+export declare function selectClassifier(classifyError: ((error: unknown) => RetryErrorType) | undefined): (error: unknown) => RetryErrorType;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGhF,eAAO,MAAM,aAAa,EAAE,iBAG3B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,kBAK5B,CAAC;AAaF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAmBnE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAOlE;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,kBAAkB,EACxB,SAAS,EAAE,cAAc,GACxB,QAAQ,CAAC,IAAI,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAC,CAepD;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,kBAAkB,EAC9B,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,MAAM,GACd,MAAM,CAYR;AAED,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAAC,GAAG,SAAS,GAC9D,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAGpC"}

package/dist/backoff.js

@@ -0,0 +1,83 @@
+import { classifyHttpStatus, detectHttpResponse } from "./http";
+export const defaultBudget = {
+    maxRetries: 5,
+    maxRetryTimeMs: 60000
+};
+export const defaultBackoff = {
+    baseDelayMs: 250,
+    maxDelayMs: 30000,
+    factor: 2,
+    jitter: "full"
+};
+function random() {
+    return Math.random();
+}
+function isAbortError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const name = error.name;
+    const code = error.code;
+    return name === "AbortError" || code === "ABORT_ERR";
+}
+export function defaultClassifyError(error) {
+    if (isAbortError(error))
+        return "clientError";
+    const response = detectHttpResponse(error);
+    if (response) {
+        return classifyHttpStatus(response.status);
+    }
+    if (typeof error === "object" && error !== null) {
+        const code = error.code;
+        if (code === "ECONNRESET" ||
+            code === "ENOTFOUND" ||
+            code === "ETIMEDOUT" ||
+            code === "EAI_AGAIN" ||
+            code === "ECONNREFUSED") {
+            return "networkError";
+        }
+    }
+    return "unknown";
+}
+export function isRetriableType(errorType) {
+    return (errorType === "rateLimit" ||
+        errorType === "serverError" ||
+        errorType === "networkError" ||
+        errorType === "unknown");
+}
+export function mergeBackoffConfig(base, errorType) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const perType = (_b = (_a = base.perErrorType) === null || _a === void 0 ? void 0 : _a[errorType]) !== null && _b !== void 0 ? _b : {};
+    const merged = {
+        baseDelayMs: (_c = base.baseDelayMs) !== null && _c !== void 0 ? _c : defaultBackoff.baseDelayMs,
+        maxDelayMs: (_d = base.maxDelayMs) !== null && _d !== void 0 ? _d : defaultBackoff.maxDelayMs,
+        factor: (_e = base.factor) !== null && _e !== void 0 ? _e : defaultBackoff.factor,
+        jitter: (_f = base.jitter) !== null && _f !== void 0 ? _f : defaultBackoff.jitter,
+        ...perType
+    };
+    return {
+        baseDelayMs: (_g = merged.baseDelayMs) !== null && _g !== void 0 ? _g : defaultBackoff.baseDelayMs,
+        maxDelayMs: (_h = merged.maxDelayMs) !== null && _h !== void 0 ? _h : defaultBackoff.maxDelayMs,
+        factor: (_j = merged.factor) !== null && _j !== void 0 ? _j : defaultBackoff.factor,
+        jitter: (_k = merged.jitter) !== null && _k !== void 0 ? _k : defaultBackoff.jitter
+    };
+}
+export function computeBackoffDelayMs(baseConfig, errorType, attempt) {
+    const cfg = mergeBackoffConfig(baseConfig, errorType);
+    const exp = Math.max(attempt - 1, 0);
+    const rawDelay = cfg.baseDelayMs * Math.pow(cfg.factor, exp);
+    const clamped = Math.min(rawDelay, cfg.maxDelayMs);
+    if (cfg.jitter === "none")
+        return clamped;
+    if (cfg.jitter === "full") {
+        return random() * clamped;
+    }
+    const min = clamped / 2;
+    const max = clamped;
+    return min + random() * (max - min);
+}
+export function selectClassifier(classifyError) {
+    if (classifyError)
+        return classifyError;
+    return defaultClassifyError;
+}
+//# sourceMappingURL=backoff.js.map

package/dist/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"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"}

package/dist/core.d.ts

@@ -0,0 +1,3 @@
+import { RetryIQOptions } from "./types";
+export declare function withRetry<T>(operation: (attempt: number, signal: AbortSignal) => Promise<T>, options?: RetryIQOptions): Promise<T>;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,cAAc,EAEf,MAAM,SAAS,CAAC;AAgBjB,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/D,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CA2LZ"}