sentra

Async retry with configurable backoff for Node.js and browsers. Retries on thrown or rejected errors; supports per-attempt timeout, optional jitter, circuit breaker, and cancellation via AbortSignal.

Table of Contents

• Installation
• Usage
• Options
• AbortSignal
• API
• Requirements
• Contributing
• Security
• License

Installation

npm install sentra

Usage

import { retry } from "sentra";

const data = await retry(
  async () => {
    const res = await fetch("https://api.example.com/data");
    if (!res.ok) throw new Error(res.statusText);
    return res.json();
  },
  { retries: 5, delay: 200, factor: 2 }
);

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | retries | number | 3 | Number of retries after the first attempt. | | delay | number | (attempt: number) => number | 100 | Initial delay in ms, or function for custom delay per attempt. | | maxDelay | number | — | Maximum delay between attempts (caps exponential backoff). | | factor | number | 2 | Multiplier for delay after each attempt. | | jitter | boolean | "full" | "equal" | — | Add randomness: true/"full" = 0..delay, "equal" = delay/2..delay. | | timeout | number | — | Per-attempt timeout in ms. | | maxDuration | number | — | Stop retrying after this many ms from the start. | | signal | AbortSignal | — | Abort retries when signal is aborted. | | retryOn | (error, attempt) => boolean | Promise<boolean> | — | Predicate to decide whether to retry; if false, last error is thrown. | | onRetry | (error, attempt, nextDelay) => void | — | Called before each wait. | | circuitBreaker | object | — | { failureThreshold, cooldown, state } to fail fast after N failures until cooldown. |

After all attempts are used (or maxDuration / retryOn stops retries), the last error is rethrown with a wrapper that includes attempt count and elapsed time as cause.

AbortSignal

Pass an AbortSignal to cancel retries when the user navigates away or a parent operation is cancelled.

import { retry } from "sentra";

const controller = new AbortController();

const result = await retry(
  async () => fetch("https://api.example.com/data").then((r) => r.json()),
  { retries: 10, delay: 1000, signal: controller.signal }
);

// Later: controller.abort() rejects with DOMException "AbortError"

API

The package exports:

• retry<T>(fn, options?) — Runs the async function with retries. Returns a Promise that resolves with the function’s result or rejects with the last error (with attempt info on cause).

TypeScript types are included.

Requirements

• Node.js: >= 18 (see engines)
• Browsers: Any environment that supports Promise, AbortSignal, and ES modules.

Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.

Security

To report a security vulnerability, please open a GitHub Security Advisory or contact the maintainers responsibly. Do not open public issues for security-sensitive topics.

License

MIT License. You may use, copy, modify, and distribute this software under the terms of the MIT License. See the LICENSE file in the repository for the full text.