@jobrain/retry-x 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# retry-x
+
+![npm](https://img.shields.io/npm/v/retry-x)
+![license](https://img.shields.io/npm/l/retry-x)
+
+A tiny, framework-agnostic retry library that wraps any async function with smart backoff, jitter, and full control — done right.
+
+## Features
+
+- **Exponential backoff**: Wait grows after each failure.
+- **Jitter**: Adds randomness to backoff to prevent thundering herd.
+- **Max attempts**: Stop after N retries and throw the last error.
+- **Max timeout**: Stop retrying after a total elapsed time.
+- **`retryIf` condition**: Only retry when a custom function returns `true`.
+- **`onRetry` callback**: Hook into each retry attempt for logging / metrics.
+- **TypeScript types**: Full type safety out of the box.
+- **Zero dependencies**: Extremely lightweight.
+
+## Installation
+
+```bash
+npm install retry-x
+```
+
+## Usage
+
+### Minimal — works out of the box
+
+```ts
+import { retry } from "retry-x";
+
+const data = await retry(() => fetch("https://api.example.com/data"));
+```
+
+### Full control
+
+```ts
+import { retry } from "retry-x";
+
+const data = await retry(
+  () => fetch("https://api.example.com/data"),
+  {
+    attempts: 5,
+    backoff: "exponential",   // or "linear" or "fixed"
+    jitter: true,
+    timeout: 10_000,          // give up after 10 seconds total
+    retryIf: (err, attempt) => err.status === 503,
+    onRetry: (err, attempt) => {
+      console.log(`Retry #${attempt}:`, err.message);
+    },
+  }
+);
+```
+
+If all attempts fail, the last error is thrown — so your existing `try/catch` just works.
+
+## API
+
+### `retry(fn, options?)`
+
+Wraps an async function and retries it based on the provided options. Returns the result of `fn` on success, or throws the last error after all attempts are exhausted.
+
+#### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `attempts` | `number` | `3` | Maximum number of attempts |
+| `backoff` | `'exponential' \| 'linear' \| 'fixed'` | `'exponential'` | Backoff strategy between retries |
+| `initialDelay` | `number` | `1000` | Initial delay in milliseconds |
+| `maxDelay` | `number` | `30000` | Maximum delay in milliseconds |
+| `jitter` | `boolean` | `true` | Adds randomness to delay to avoid thundering herd |
+| `timeout` | `number` | — | Total timeout across all attempts in milliseconds |
+| `retryIf` | `(error, attempt) => boolean` | — | Return `false` to stop retrying early |
+| `onRetry` | `(error, attempt) => void` | — | Called before each retry attempt |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+type RetryBackoff = 'fixed' | 'linear' | 'exponential';
+interface RetryOptions {
+    /**
+     * Maximum number of attempts.
+     * @default 3
+     */
+    attempts?: number;
+    /**
+     * Backoff strategy to use.
+     * @default 'exponential'
+     */
+    backoff?: RetryBackoff;
+    /**
+     * Initial delay in milliseconds.
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds.
+     * @default 30000
+     */
+    maxDelay?: number;
+    /**
+     * Whether to add jitter to the delay.
+     * @default true
+     */
+    jitter?: boolean;
+    /**
+     * Total timeout for all attempts in milliseconds.
+     * If exceeded, the last error will be thrown.
+     */
+    timeout?: number;
+    /**
+     * Predicate function to determine if a retry should be attempted.
+     * If it returns false, retrying stops immediately.
+     */
+    retryIf?: (error: any, attempt: number) => boolean | Promise<boolean>;
+    /**
+     * Callback function called before each retry attempt.
+     */
+    onRetry?: (error: any, attempt: number) => void | Promise<void>;
+}
+
+declare function retry<T>(fn: () => T | Promise<T>, options?: RetryOptions): Promise<T>;
+
+export { type RetryBackoff, type RetryOptions, retry };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+type RetryBackoff = 'fixed' | 'linear' | 'exponential';
+interface RetryOptions {
+    /**
+     * Maximum number of attempts.
+     * @default 3
+     */
+    attempts?: number;
+    /**
+     * Backoff strategy to use.
+     * @default 'exponential'
+     */
+    backoff?: RetryBackoff;
+    /**
+     * Initial delay in milliseconds.
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds.
+     * @default 30000
+     */
+    maxDelay?: number;
+    /**
+     * Whether to add jitter to the delay.
+     * @default true
+     */
+    jitter?: boolean;
+    /**
+     * Total timeout for all attempts in milliseconds.
+     * If exceeded, the last error will be thrown.
+     */
+    timeout?: number;
+    /**
+     * Predicate function to determine if a retry should be attempted.
+     * If it returns false, retrying stops immediately.
+     */
+    retryIf?: (error: any, attempt: number) => boolean | Promise<boolean>;
+    /**
+     * Callback function called before each retry attempt.
+     */
+    onRetry?: (error: any, attempt: number) => void | Promise<void>;
+}
+
+declare function retry<T>(fn: () => T | Promise<T>, options?: RetryOptions): Promise<T>;
+
+export { type RetryBackoff, type RetryOptions, retry };

package/dist/index.js

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  retry: () => retry
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/backoff.ts
+function calculateDelay(strategy, attempt, initialDelay, maxDelay, jitter) {
+  let delay = 0;
+  switch (strategy) {
+    case "fixed":
+      delay = initialDelay;
+      break;
+    case "linear":
+      delay = initialDelay * attempt;
+      break;
+    case "exponential":
+      delay = initialDelay * Math.pow(2, attempt - 1);
+      break;
+  }
+  delay = Math.min(delay, maxDelay);
+  if (jitter) {
+    delay = Math.random() * delay;
+  }
+  return delay;
+}
+
+// src/retry.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function retry(fn, options = {}) {
+  const {
+    attempts = 3,
+    backoff = "exponential",
+    initialDelay = 1e3,
+    maxDelay = 3e4,
+    jitter = true,
+    timeout,
+    retryIf,
+    onRetry
+  } = options;
+  const startTime = Date.now();
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (attempt > 1 && timeout && Date.now() - startTime >= timeout) {
+      break;
+    }
+    try {
+      return await Promise.resolve().then(() => fn());
+    } catch (error) {
+      lastError = error;
+      if (attempt >= attempts) {
+        break;
+      }
+      if (retryIf && !await retryIf(error, attempt)) {
+        break;
+      }
+      if (onRetry) {
+        await onRetry(error, attempt);
+      }
+      const delay = calculateDelay(
+        backoff,
+        attempt,
+        initialDelay,
+        maxDelay,
+        jitter
+      );
+      if (timeout) {
+        const remainingTime = timeout - (Date.now() - startTime);
+        if (remainingTime <= 0) {
+          break;
+        }
+        await sleep(Math.min(delay, remainingTime));
+      } else {
+        await sleep(delay);
+      }
+    }
+  }
+  throw lastError;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  retry
+});

package/dist/index.mjs

@@ -0,0 +1,76 @@
+// src/backoff.ts
+function calculateDelay(strategy, attempt, initialDelay, maxDelay, jitter) {
+  let delay = 0;
+  switch (strategy) {
+    case "fixed":
+      delay = initialDelay;
+      break;
+    case "linear":
+      delay = initialDelay * attempt;
+      break;
+    case "exponential":
+      delay = initialDelay * Math.pow(2, attempt - 1);
+      break;
+  }
+  delay = Math.min(delay, maxDelay);
+  if (jitter) {
+    delay = Math.random() * delay;
+  }
+  return delay;
+}
+
+// src/retry.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function retry(fn, options = {}) {
+  const {
+    attempts = 3,
+    backoff = "exponential",
+    initialDelay = 1e3,
+    maxDelay = 3e4,
+    jitter = true,
+    timeout,
+    retryIf,
+    onRetry
+  } = options;
+  const startTime = Date.now();
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (attempt > 1 && timeout && Date.now() - startTime >= timeout) {
+      break;
+    }
+    try {
+      return await Promise.resolve().then(() => fn());
+    } catch (error) {
+      lastError = error;
+      if (attempt >= attempts) {
+        break;
+      }
+      if (retryIf && !await retryIf(error, attempt)) {
+        break;
+      }
+      if (onRetry) {
+        await onRetry(error, attempt);
+      }
+      const delay = calculateDelay(
+        backoff,
+        attempt,
+        initialDelay,
+        maxDelay,
+        jitter
+      );
+      if (timeout) {
+        const remainingTime = timeout - (Date.now() - startTime);
+        if (remainingTime <= 0) {
+          break;
+        }
+        await sleep(Math.min(delay, remainingTime));
+      } else {
+        await sleep(delay);
+      }
+    }
+  }
+  throw lastError;
+}
+export {
+  retry
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jobrain/retry-x",
+  "version": "1.0.0",
+  "description": "A tiny, framework-agnostic retry library with smart backoff and jitter.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "retry",
+    "backoff",
+    "exponential",
+    "jitter",
+    "async",
+    "promise"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.3",
+    "vitest": "^1.4.0"
+  }
+}