@async-kit/retryx 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+## 0.1.2 (2026-03-11)
+
+### 🩹 Fixes
+
+- **release:** add publishConfig access public to all packages ([82c12ca](https://github.com/NexaLeaf/async-kit/commit/82c12ca))
+
+### ❤️ Thank You
+
+- Palanisamy Muthusamy

package/README.md

@@ -0,0 +1,348 @@
+<div align="center">
+
+<img src="https://capsule-render.vercel.app/api?type=rect&color=gradient&customColorList=12&height=120&section=header&text=retryx&fontSize=60&fontColor=fff&animation=fadeIn&desc=%40async-kit%2Fretryx&descAlignY=75&descAlign=50" width="100%"/>
+
+<br/>
+
+[![npm](https://img.shields.io/npm/v/@async-kit/retryx?style=for-the-badge&logo=npm&color=4ECDC4)](https://www.npmjs.com/package/@async-kit/retryx)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](../../LICENSE)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/@async-kit/retryx?style=for-the-badge&color=4ECDC4)](https://bundlephobia.com/package/@async-kit/retryx)
+[![Node](https://img.shields.io/badge/Node-%3E%3D18-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Browser](https://img.shields.io/badge/Browser-Supported-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white)](#compatibility)
+
+**Smart async retry with exponential backoff, jitter strategies, circuit breaker, and AbortSignal support.**
+
+*Make any async operation resilient in one line.*
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install @async-kit/retryx
+```
+
+## Quick Start
+
+```typescript
+import { retry, createRetry, withRetry, CircuitBreaker } from '@async-kit/retryx';
+
+// One-shot retry
+const data = await retry(() => fetch('/api').then(r => r.json()), {
+  maxAttempts: 5,
+  jitter: 'full',
+});
+
+// Reusable retry function
+const resilient = createRetry({ maxAttempts: 3, initialDelay: 200 });
+await resilient(() => callApi());
+
+// Wrap any async function
+const safeFetch = withRetry(fetch, { maxAttempts: 3 });
+const resp = await safeFetch('/api/users', { method: 'GET' });
+
+// Circuit breaker
+const cb = new CircuitBreaker({ failureThreshold: 5, successThreshold: 2, openDurationMs: 10_000 });
+const result = await cb.run(() => callExternalService());
+```
+
+## API
+
+### `retry(task, options?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `maxAttempts` | `number` | `3` | Total attempts including the first |
+| `initialDelay` | `number` | `200` | Base delay in ms before the first retry |
+| `maxDelay` | `number` | `30_000` | Maximum delay cap in ms |
+| `factor` | `number` | `2` | Exponential backoff multiplier |
+| `jitter` | `JitterStrategy` | `'equal'` | Randomization strategy (see below) |
+| `retryIf` | `(err, ctx) => bool` | `() => true` | Return `false` to stop retrying; may be async |
+| `onRetry` | `(n, err, ms, ctx) => void` | — | Hook called before each retry delay |
+| `signal` | `AbortSignal` | — | Cancels pending retry delays |
+| `timeoutMs` | `number` | — | Per-attempt timeout; throws `RetryxTimeoutError` |
+
+### Jitter Strategies
+
+| Strategy | Formula | Best For |
+|---|---|---|
+| `'equal'` (default) | `cap/2 + random(0, cap/2)` | Preserves mean delay |
+| `'full'` | `random(0, cap)` | AWS-recommended; highest spread |
+| `'decorrelated'` | `min(cap, random(base, prev*3))` | Aggressive thundering-herd prevention |
+| `'none'` | `cap` | Deterministic testing |
+
+### `createRetry(defaults)`
+
+Creates a reusable retry function. Per-call `overrides` are merged with defaults.
+
+```typescript
+const resilient = createRetry({ maxAttempts: 5, jitter: 'full' });
+await resilient(() => fetchData(), { maxAttempts: 3 }); // override for this call
+```
+
+### `withRetry(fn, options)`
+
+Wraps an existing async function so every invocation is automatically retried.
+
+```typescript
+const safeFetch = withRetry(fetch, { maxAttempts: 3 });
+const resp = await safeFetch('/api/users', { method: 'GET' }); // retried transparently
+```
+
+### `RetryContext`
+
+Passed to `retryIf` and `onRetry`:
+
+```typescript
+interface RetryContext {
+  attemptNumber: number;  // 1-based attempt that just failed
+  totalAttempts: number;
+  elapsedMs: number;      // wall-clock ms since first attempt
+  errors: unknown[];      // all errors so far, in order
+}
+```
+
+## Circuit Breaker
+
+Prevents cascading failures by fast-failing calls when a service is degraded.
+
+```typescript
+const cb = new CircuitBreaker({
+  failureThreshold: 5,    // open after 5 consecutive failures
+  successThreshold: 2,    // close after 2 successes in HALF_OPEN
+  openDurationMs: 10_000, // stay open 10 s before probing
+  volumeThreshold: 10,    // require ≥ 10 calls before tripping
+  onStateChange: (from, to) => console.log(`${from} → ${to}`),
+});
+```
+
+#### States
+
+```
+CLOSED ──(failures >= threshold)──► OPEN ──(after openDurationMs)──► HALF_OPEN
+   ▲                                                                      │
+   └──────────(successes >= successThreshold)────────────────────────────┘
+```
+
+| Method | Description |
+|---|---|
+| `.run(task)` | Execute; throws `CircuitOpenError` when OPEN |
+| `.reset()` | Force to CLOSED state |
+| `.stats()` | Returns `{ failures, successes, calls, state }` |
+| `.currentState` | Current `CircuitState` |
+
+## Error Types
+
+| Class | When |
+|---|---|
+| `RetryxError` | All attempts exhausted — has `.attempts`, `.lastError`, `.allErrors` |
+| `RetryxTimeoutError` | Per-attempt `timeoutMs` exceeded — has `.attempt`, `.timeoutMs` |
+| `CircuitOpenError` | Call blocked by open circuit — has `.retryAfterMs` |
+
+## Examples
+
+### Retry only transient HTTP errors
+
+```typescript
+import { retry } from '@async-kit/retryx';
+
+const data = await retry(
+  () => fetch('/api/orders').then(async r => {
+    if (!r.ok) throw Object.assign(new Error(r.statusText), { status: r.status });
+    return r.json();
+  }),
+  {
+    maxAttempts: 5,
+    jitter: 'full',
+    retryIf: (err: any) => err.status == null || err.status >= 500,
+    onRetry: (attempt, err: any, delayMs) => {
+      console.warn(`[attempt ${attempt}] ${err.message} — retrying in ${delayMs}ms`);
+    },
+  }
+);
+```
+
+### App-wide resilience factory
+
+```typescript
+import { createRetry } from '@async-kit/retryx';
+
+// Define once, use everywhere
+export const resilient = createRetry({
+  maxAttempts: 4,
+  initialDelay: 300,
+  maxDelay: 15_000,
+  jitter: 'equal',
+});
+
+// In your service layer
+export const ordersApi = {
+  create: (payload: OrderPayload) =>
+    resilient(() => httpClient.post('/orders', payload)),
+  get: (id: string) =>
+    resilient(() => httpClient.get(`/orders/${id}`)),
+};
+```
+
+### `withRetry` — wrap third-party SDKs
+
+```typescript
+import { withRetry } from '@async-kit/retryx';
+import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+
+const s3 = new S3Client({});
+
+// Wrap the entire send method — every call is retried automatically
+const resilientSend = withRetry(
+  s3.send.bind(s3),
+  { maxAttempts: 4, jitter: 'decorrelated' }
+);
+
+const response = await resilientSend(
+  new GetObjectCommand({ Bucket: 'my-bucket', Key: 'data.json' })
+);
+```
+
+### Per-attempt timeout to bound total latency
+
+```typescript
+import { retry, RetryxTimeoutError } from '@async-kit/retryx';
+
+const result = await retry(
+  () => slowExternalService.query(params),
+  {
+    maxAttempts: 3,
+    timeoutMs: 2_000,    // each attempt must finish within 2 s
+    initialDelay: 500,
+  }
+).catch((err) => {
+  if (err instanceof RetryxTimeoutError)
+    console.error(`Attempt ${err.attempt} timed out after ${err.timeoutMs}ms`);
+  throw err;
+});
+```
+
+### Cancellable polling with AbortSignal
+
+```typescript
+import { retry } from '@async-kit/retryx';
+
+const controller = new AbortController();
+
+// Cancel from the UI
+document.getElementById('cancel')!.onclick = () => controller.abort();
+
+const result = await retry(
+  () => pollJobStatus(jobId).then(s => {
+    if (s.status !== 'done') throw new Error('not ready');
+    return s;
+  }),
+  {
+    maxAttempts: 120,
+    initialDelay: 1_000,
+    maxDelay: 10_000,
+    signal: controller.signal,
+  }
+);
+```
+
+### Circuit Breaker — protect a downstream service
+
+```typescript
+import { CircuitBreaker, CircuitOpenError } from '@async-kit/retryx';
+
+const inventoryCb = new CircuitBreaker({
+  failureThreshold: 5,
+  successThreshold: 2,
+  openDurationMs: 30_000,
+  onStateChange: (from, to) => {
+    logger.warn(`inventory circuit: ${from} → ${to}`);
+    metrics.increment(`circuit.inventory.${to.toLowerCase()}`);
+  },
+});
+
+async function getInventory(sku: string) {
+  try {
+    return await inventoryCb.run(() => inventoryService.get(sku));
+  } catch (err) {
+    if (err instanceof CircuitOpenError) {
+      // Serve from cache while circuit is open
+      return cache.get(`inventory:${sku}`) ?? { qty: 0 };
+    }
+    throw err;
+  }
+}
+```
+
+### Circuit Breaker + retry together
+
+```typescript
+import { retry, CircuitBreaker, CircuitOpenError } from '@async-kit/retryx';
+
+const cb = new CircuitBreaker({ failureThreshold: 3, successThreshold: 1, openDurationMs: 10_000 });
+
+const data = await retry(
+  () => cb.run(() => externalService.fetch(id)),
+  {
+    maxAttempts: 5,
+    retryIf: (err) => !(err instanceof CircuitOpenError), // don't retry open-circuit errors
+    onRetry: (n, err) => console.log(`retry ${n}: ${err}`),
+  }
+);
+```
+
+### Inspect all errors across attempts
+
+```typescript
+import { retry, RetryxError } from '@async-kit/retryx';
+
+try {
+  await retry(() => unstableService.call(), { maxAttempts: 3 });
+} catch (err) {
+  if (err instanceof RetryxError) {
+    console.error(`Failed after ${err.attempts} attempts`);
+    err.allErrors.forEach((e, i) =>
+      console.error(`  Attempt ${i + 1}:`, e)
+    );
+  }
+}
+```
+
+## Types
+
+```typescript
+import type {
+  JitterStrategy,
+  RetryContext,
+  RetryxOptions,
+  CircuitState,
+  CircuitBreakerOptions,
+  CircuitBreakerStats,
+} from '@async-kit/retryx';
+```
+
+## Compatibility
+
+| Environment | Support | Notes |
+|---|---|---|
+| **Node.js** | ≥ 18 | Recommended ≥ 24 for best performance |
+| **Deno** | ✅ | Via npm specifier (`npm:@async-kit/retryx`) |
+| **Bun** | ✅ | Full support |
+| **Chrome** | ≥ 80 | ESM via bundler or native import |
+| **Firefox** | ≥ 75 | ESM via bundler or native import |
+| **Safari** | ≥ 13.1 | ESM via bundler or native import |
+| **Edge** | ≥ 80 | ESM via bundler or native import |
+| **React Native** | ✅ | Via Metro bundler |
+| **Cloudflare Workers** | ✅ | ESM, `AbortSignal` natively supported |
+| **Vercel Edge Runtime** | ✅ | ESM, no `process` / `fs` dependencies |
+
+**No Node.js built-ins are used.** The package relies only on standard JavaScript (`Promise`, `setTimeout`, `clearTimeout`, `AbortSignal`, `DOMException`) — all available in any modern runtime.
+
+> **`AbortSignal` / `DOMException`** are part of the Web Platform API. In Node.js they are globals since v15. In older environments (Node 14 or old browsers) you may need to polyfill `AbortController` — e.g. [`abortcontroller-polyfill`](https://www.npmjs.com/package/abortcontroller-polyfill).
+
+## License
+
+MIT © async-kit contributors · Part of the [async-kit](../../README.md) ecosystem

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+/**
+ * Jitter strategy for exponential backoff.
+ * - `'equal'`        — `cap/2 + random(0, cap/2)`  (default, preserves mean delay)
+ * - `'full'`         — `random(0, cap)`              (AWS recommended for highest spread)
+ * - `'decorrelated'` — `min(cap, random(base, prev * 3))` (aggressive spread)
+ * - `'none'`         — no randomization
+ */
+type JitterStrategy = 'equal' | 'full' | 'decorrelated' | 'none';
+/** Context object passed to `retryIf` and `onRetry` callbacks. */
+interface RetryContext {
+    /** 1-based attempt number of the attempt that just failed. */
+    attemptNumber: number;
+    /** Total configured max attempts. */
+    totalAttempts: number;
+    /** Wall-clock ms elapsed since the first attempt started. */
+    elapsedMs: number;
+    /** All errors collected so far, in order. */
+    errors: unknown[];
+}
+/** Options for `retry()` and `createRetry()`. */
+interface RetryxOptions {
+    /** Total attempts including the first. Default: `3`. */
+    maxAttempts?: number;
+    /** Base delay in ms before the first retry. Default: `200`. */
+    initialDelay?: number;
+    /** Maximum delay cap in ms. Default: `30_000`. */
+    maxDelay?: number;
+    /** Backoff multiplier. Default: `2`. */
+    factor?: number;
+    /** Jitter strategy. Default: `'equal'`. */
+    jitter?: JitterStrategy;
+    /**
+     * Return `false` to stop retrying immediately.
+     * Receives the error and full context. May be async.
+     */
+    retryIf?: (error: unknown, context: RetryContext) => boolean | Promise<boolean>;
+    /** Called before each retry delay. */
+    onRetry?: (attemptNumber: number, error: unknown, delayMs: number, context: RetryContext) => void;
+    /** AbortSignal — cancels pending retry delays. */
+    signal?: AbortSignal;
+    /** Per-attempt timeout in ms. Throws `RetryxTimeoutError` if exceeded. */
+    timeoutMs?: number;
+}
+/** All possible circuit breaker states. */
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/** Constructor options for `CircuitBreaker`. */
+interface CircuitBreakerOptions {
+    /** Number of failures before opening the circuit. */
+    failureThreshold: number;
+    /** Successes in HALF_OPEN state needed to re-close. */
+    successThreshold: number;
+    /** How long (ms) to stay OPEN before moving to HALF_OPEN. */
+    openDurationMs: number;
+    /** Minimum calls in the window before the circuit can trip. Default: `1`. */
+    volumeThreshold?: number;
+    /** Called whenever the circuit transitions between states. */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+/** Snapshot of `CircuitBreaker` counters and state. */
+interface CircuitBreakerStats {
+    failures: number;
+    successes: number;
+    calls: number;
+    state: CircuitState;
+}
+
+declare class RetryxError extends Error {
+    readonly attempts: number;
+    readonly lastError: unknown;
+    /** Every error thrown across all attempts, in order. */
+    readonly allErrors: unknown[];
+    constructor(message: string, attempts: number, lastError: unknown, 
+    /** Every error thrown across all attempts, in order. */
+    allErrors: unknown[]);
+}
+declare class RetryxTimeoutError extends Error {
+    readonly attempt: number;
+    readonly timeoutMs: number;
+    constructor(attempt: number, timeoutMs: number);
+}
+/**
+ * Retry an async operation with exponential backoff, jitter, and context-aware hooks.
+ *
+ * @example
+ * const data = await retry(() => fetch('/api').then(r => r.json()), { maxAttempts: 5 });
+ */
+declare function retry<T>(task: () => Promise<T>, options?: RetryxOptions): Promise<T>;
+/**
+ * Create a reusable retry function with pre-configured options.
+ *
+ * @example
+ * const resilient = createRetry({ maxAttempts: 5 });
+ * await resilient(() => callApi());
+ */
+declare function createRetry(defaults: RetryxOptions): <T>(task: () => Promise<T>, overrides?: RetryxOptions) => Promise<T>;
+/**
+ * Wraps an async function so that every call is automatically retried.
+ *
+ * @example
+ * const resilientFetch = withRetry(fetch, { maxAttempts: 3 });
+ * const resp = await resilientFetch('/api/users'); // retried on failure
+ */
+declare function withRetry<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options: RetryxOptions): (...args: TArgs) => Promise<TReturn>;
+declare class CircuitOpenError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+/**
+ * Circuit breaker wrapping any async operation.
+ *
+ * States:
+ * - **CLOSED** — calls pass through normally.
+ * - **OPEN**   — calls fail fast with `CircuitOpenError`.
+ * - **HALF_OPEN** — one probe call is allowed; success closes, failure re-opens.
+ *
+ * @example
+ * const cb = new CircuitBreaker({ failureThreshold: 5, successThreshold: 2, openDurationMs: 10_000 });
+ * const result = await cb.run(() => callExternalService());
+ */
+declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private calls;
+    private openedAt;
+    private readonly failureThreshold;
+    private readonly successThreshold;
+    private readonly openDurationMs;
+    private readonly volumeThreshold;
+    private readonly onStateChange?;
+    constructor(options: CircuitBreakerOptions);
+    get currentState(): CircuitState;
+    run<T>(task: () => Promise<T>): Promise<T>;
+    /** Manually reset the circuit to CLOSED state. */
+    reset(): void;
+    stats(): CircuitBreakerStats;
+    private checkHalfOpen;
+    private onSuccess;
+    private onFailure;
+    private transition;
+}
+
+export { CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, CircuitOpenError, type CircuitState, type JitterStrategy, type RetryContext, RetryxError, type RetryxOptions, RetryxTimeoutError, createRetry, retry, withRetry };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Jitter strategy for exponential backoff.
+ * - `'equal'`        — `cap/2 + random(0, cap/2)`  (default, preserves mean delay)
+ * - `'full'`         — `random(0, cap)`              (AWS recommended for highest spread)
+ * - `'decorrelated'` — `min(cap, random(base, prev * 3))` (aggressive spread)
+ * - `'none'`         — no randomization
+ */
+type JitterStrategy = 'equal' | 'full' | 'decorrelated' | 'none';
+/** Context object passed to `retryIf` and `onRetry` callbacks. */
+interface RetryContext {
+    /** 1-based attempt number of the attempt that just failed. */
+    attemptNumber: number;
+    /** Total configured max attempts. */
+    totalAttempts: number;
+    /** Wall-clock ms elapsed since the first attempt started. */
+    elapsedMs: number;
+    /** All errors collected so far, in order. */
+    errors: unknown[];
+}
+/** Options for `retry()` and `createRetry()`. */
+interface RetryxOptions {
+    /** Total attempts including the first. Default: `3`. */
+    maxAttempts?: number;
+    /** Base delay in ms before the first retry. Default: `200`. */
+    initialDelay?: number;
+    /** Maximum delay cap in ms. Default: `30_000`. */
+    maxDelay?: number;
+    /** Backoff multiplier. Default: `2`. */
+    factor?: number;
+    /** Jitter strategy. Default: `'equal'`. */
+    jitter?: JitterStrategy;
+    /**
+     * Return `false` to stop retrying immediately.
+     * Receives the error and full context. May be async.
+     */
+    retryIf?: (error: unknown, context: RetryContext) => boolean | Promise<boolean>;
+    /** Called before each retry delay. */
+    onRetry?: (attemptNumber: number, error: unknown, delayMs: number, context: RetryContext) => void;
+    /** AbortSignal — cancels pending retry delays. */
+    signal?: AbortSignal;
+    /** Per-attempt timeout in ms. Throws `RetryxTimeoutError` if exceeded. */
+    timeoutMs?: number;
+}
+/** All possible circuit breaker states. */
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/** Constructor options for `CircuitBreaker`. */
+interface CircuitBreakerOptions {
+    /** Number of failures before opening the circuit. */
+    failureThreshold: number;
+    /** Successes in HALF_OPEN state needed to re-close. */
+    successThreshold: number;
+    /** How long (ms) to stay OPEN before moving to HALF_OPEN. */
+    openDurationMs: number;
+    /** Minimum calls in the window before the circuit can trip. Default: `1`. */
+    volumeThreshold?: number;
+    /** Called whenever the circuit transitions between states. */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+/** Snapshot of `CircuitBreaker` counters and state. */
+interface CircuitBreakerStats {
+    failures: number;
+    successes: number;
+    calls: number;
+    state: CircuitState;
+}
+
+declare class RetryxError extends Error {
+    readonly attempts: number;
+    readonly lastError: unknown;
+    /** Every error thrown across all attempts, in order. */
+    readonly allErrors: unknown[];
+    constructor(message: string, attempts: number, lastError: unknown, 
+    /** Every error thrown across all attempts, in order. */
+    allErrors: unknown[]);
+}
+declare class RetryxTimeoutError extends Error {
+    readonly attempt: number;
+    readonly timeoutMs: number;
+    constructor(attempt: number, timeoutMs: number);
+}
+/**
+ * Retry an async operation with exponential backoff, jitter, and context-aware hooks.
+ *
+ * @example
+ * const data = await retry(() => fetch('/api').then(r => r.json()), { maxAttempts: 5 });
+ */
+declare function retry<T>(task: () => Promise<T>, options?: RetryxOptions): Promise<T>;
+/**
+ * Create a reusable retry function with pre-configured options.
+ *
+ * @example
+ * const resilient = createRetry({ maxAttempts: 5 });
+ * await resilient(() => callApi());
+ */
+declare function createRetry(defaults: RetryxOptions): <T>(task: () => Promise<T>, overrides?: RetryxOptions) => Promise<T>;
+/**
+ * Wraps an async function so that every call is automatically retried.
+ *
+ * @example
+ * const resilientFetch = withRetry(fetch, { maxAttempts: 3 });
+ * const resp = await resilientFetch('/api/users'); // retried on failure
+ */
+declare function withRetry<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options: RetryxOptions): (...args: TArgs) => Promise<TReturn>;
+declare class CircuitOpenError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+/**
+ * Circuit breaker wrapping any async operation.
+ *
+ * States:
+ * - **CLOSED** — calls pass through normally.
+ * - **OPEN**   — calls fail fast with `CircuitOpenError`.
+ * - **HALF_OPEN** — one probe call is allowed; success closes, failure re-opens.
+ *
+ * @example
+ * const cb = new CircuitBreaker({ failureThreshold: 5, successThreshold: 2, openDurationMs: 10_000 });
+ * const result = await cb.run(() => callExternalService());
+ */
+declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private calls;
+    private openedAt;
+    private readonly failureThreshold;
+    private readonly successThreshold;
+    private readonly openDurationMs;
+    private readonly volumeThreshold;
+    private readonly onStateChange?;
+    constructor(options: CircuitBreakerOptions);
+    get currentState(): CircuitState;
+    run<T>(task: () => Promise<T>): Promise<T>;
+    /** Manually reset the circuit to CLOSED state. */
+    reset(): void;
+    stats(): CircuitBreakerStats;
+    private checkHalfOpen;
+    private onSuccess;
+    private onFailure;
+    private transition;
+}
+
+export { CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, CircuitOpenError, type CircuitState, type JitterStrategy, type RetryContext, RetryxError, type RetryxOptions, RetryxTimeoutError, createRetry, retry, withRetry };

package/dist/index.js

@@ -0,0 +1,224 @@
+'use strict';
+
+// src/retryx.ts
+var RetryxError = class extends Error {
+  constructor(message, attempts, lastError, allErrors) {
+    super(message);
+    this.attempts = attempts;
+    this.lastError = lastError;
+    this.allErrors = allErrors;
+    this.name = "RetryxError";
+  }
+};
+var RetryxTimeoutError = class extends Error {
+  constructor(attempt, timeoutMs) {
+    super(`Attempt ${attempt} timed out after ${timeoutMs}ms`);
+    this.attempt = attempt;
+    this.timeoutMs = timeoutMs;
+    this.name = "RetryxTimeoutError";
+  }
+};
+function abortableDelay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      },
+      { once: true }
+    );
+  });
+}
+function raceTimeout(promise, ms, attempt) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new RetryxTimeoutError(attempt, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function computeDelay(attempt, prevDelay, opts) {
+  const cap = Math.min(opts.initialDelay * Math.pow(opts.factor, attempt), opts.maxDelay);
+  switch (opts.jitter) {
+    case "none":
+      return cap;
+    case "full":
+      return Math.floor(Math.random() * cap);
+    case "decorrelated":
+      return Math.min(opts.maxDelay, Math.floor(opts.initialDelay + Math.random() * (prevDelay * 3 - opts.initialDelay)));
+    case "equal":
+    default:
+      return Math.floor(cap / 2 + Math.random() * (cap / 2));
+  }
+}
+async function retry(task, options = {}) {
+  const {
+    maxAttempts = 3,
+    initialDelay = 200,
+    maxDelay = 3e4,
+    factor = 2,
+    jitter = "equal",
+    retryIf = () => true,
+    onRetry,
+    signal,
+    timeoutMs
+  } = options;
+  const allErrors = [];
+  const startTime = Date.now();
+  let prevDelay = initialDelay;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return timeoutMs != null ? await raceTimeout(task(), timeoutMs, attempt + 1) : await task();
+    } catch (err) {
+      allErrors.push(err);
+      if (attempt === maxAttempts - 1) break;
+      const context = {
+        attemptNumber: attempt + 1,
+        totalAttempts: maxAttempts,
+        elapsedMs: Date.now() - startTime,
+        errors: [...allErrors]
+      };
+      const shouldRetry = await retryIf(err, context);
+      if (!shouldRetry) break;
+      const delayMs = computeDelay(attempt, prevDelay, { initialDelay, maxDelay, factor, jitter });
+      prevDelay = delayMs;
+      onRetry?.(attempt + 1, err, delayMs, context);
+      await abortableDelay(delayMs, signal);
+    }
+  }
+  throw allErrors.length === 1 && allErrors[0] instanceof RetryxTimeoutError ? allErrors[0] : new RetryxError(
+    `All ${maxAttempts} attempts failed`,
+    maxAttempts,
+    allErrors[allErrors.length - 1],
+    allErrors
+  );
+}
+function createRetry(defaults) {
+  return (task, overrides) => retry(task, { ...defaults, ...overrides });
+}
+function withRetry(fn, options) {
+  return (...args) => retry(() => fn(...args), options);
+}
+var CircuitOpenError = class extends Error {
+  constructor(retryAfterMs) {
+    super(`Circuit is OPEN. Retry after ${retryAfterMs}ms`);
+    this.retryAfterMs = retryAfterMs;
+    this.name = "CircuitOpenError";
+  }
+};
+var CircuitBreaker = class {
+  state = "CLOSED";
+  failures = 0;
+  successes = 0;
+  calls = 0;
+  openedAt = 0;
+  failureThreshold;
+  successThreshold;
+  openDurationMs;
+  volumeThreshold;
+  onStateChange;
+  constructor(options) {
+    this.failureThreshold = options.failureThreshold;
+    this.successThreshold = options.successThreshold;
+    this.openDurationMs = options.openDurationMs;
+    this.volumeThreshold = options.volumeThreshold ?? 1;
+    this.onStateChange = options.onStateChange;
+  }
+  get currentState() {
+    this.checkHalfOpen();
+    return this.state;
+  }
+  async run(task) {
+    this.checkHalfOpen();
+    if (this.state === "OPEN") {
+      const retryAfterMs = Math.max(0, this.openedAt + this.openDurationMs - Date.now());
+      throw new CircuitOpenError(retryAfterMs);
+    }
+    this.calls++;
+    try {
+      const result = await task();
+      this.onSuccess();
+      return result;
+    } catch (err) {
+      this.onFailure();
+      throw err;
+    }
+  }
+  /** Manually reset the circuit to CLOSED state. */
+  reset() {
+    const prev = this.state;
+    this.state = "CLOSED";
+    this.failures = 0;
+    this.successes = 0;
+    this.calls = 0;
+    this.openedAt = 0;
+    if (prev !== "CLOSED") this.onStateChange?.(prev, "CLOSED");
+  }
+  stats() {
+    return {
+      failures: this.failures,
+      successes: this.successes,
+      calls: this.calls,
+      state: this.state
+    };
+  }
+  checkHalfOpen() {
+    if (this.state === "OPEN" && Date.now() >= this.openedAt + this.openDurationMs) {
+      this.transition("HALF_OPEN");
+    }
+  }
+  onSuccess() {
+    this.failures = 0;
+    if (this.state === "HALF_OPEN") {
+      this.successes++;
+      if (this.successes >= this.successThreshold) {
+        this.transition("CLOSED");
+      }
+    }
+  }
+  onFailure() {
+    this.failures++;
+    if (this.state === "HALF_OPEN") {
+      this.openedAt = Date.now();
+      this.transition("OPEN");
+    } else if (this.state === "CLOSED" && this.calls >= this.volumeThreshold && this.failures >= this.failureThreshold) {
+      this.openedAt = Date.now();
+      this.transition("OPEN");
+    }
+  }
+  transition(next) {
+    const prev = this.state;
+    this.state = next;
+    if (next === "CLOSED") {
+      this.failures = 0;
+      this.successes = 0;
+    }
+    if (next === "HALF_OPEN") {
+      this.successes = 0;
+    }
+    this.onStateChange?.(prev, next);
+  }
+};
+
+exports.CircuitBreaker = CircuitBreaker;
+exports.CircuitOpenError = CircuitOpenError;
+exports.RetryxError = RetryxError;
+exports.RetryxTimeoutError = RetryxTimeoutError;
+exports.createRetry = createRetry;
+exports.retry = retry;
+exports.withRetry = withRetry;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retryx.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export type { JitterStrategy, RetryContext, RetryxOptions, CircuitState, CircuitBreakerOptions, CircuitBreakerStats } from './types.js';\nimport type { JitterStrategy, RetryContext, RetryxOptions, CircuitState, CircuitBreakerOptions, CircuitBreakerStats } from './types.js';\n\n// ─── Error Types ─────────────────────────────────────────────────────────────\n\nexport class RetryxError extends Error {\n  constructor(\n    message: string,\n    public readonly attempts: number,\n    public readonly lastError: unknown,\n    /** Every error thrown across all attempts, in order. */\n    public readonly allErrors: unknown[]\n  ) {\n    super(message);\n    this.name = 'RetryxError';\n  }\n}\n\nexport class RetryxTimeoutError extends Error {\n  constructor(\n    public readonly attempt: number,\n    public readonly timeoutMs: number\n  ) {\n    super(`Attempt ${attempt} timed out after ${timeoutMs}ms`);\n    this.name = 'RetryxTimeoutError';\n  }\n}\n\n// ─── Internal Helpers ────────────────────────────────────────────────────────\n\nfunction abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new DOMException('Aborted', 'AbortError'));\n      return;\n    }\n    const timer = setTimeout(resolve, ms);\n    signal?.addEventListener(\n      'abort',\n      () => { clearTimeout(timer); reject(new DOMException('Aborted', 'AbortError')); },\n      { once: true }\n    );\n  });\n}\n\nfunction raceTimeout<T>(promise: Promise<T>, ms: number, attempt: number): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timer = setTimeout(() => reject(new RetryxTimeoutError(attempt, ms)), ms);\n    promise.then(\n      (v) => { clearTimeout(timer); resolve(v); },\n      (e) => { clearTimeout(timer); reject(e); }\n    );\n  });\n}\n\nfunction computeDelay(\n  attempt: number,\n  prevDelay: number,\n  opts: Required<Pick<RetryxOptions, 'initialDelay' | 'maxDelay' | 'factor' | 'jitter'>>\n): number {\n  const cap = Math.min(opts.initialDelay * Math.pow(opts.factor, attempt), opts.maxDelay);\n\n  switch (opts.jitter) {\n    case 'none':\n      return cap;\n    case 'full':\n      return Math.floor(Math.random() * cap);\n    case 'decorrelated':\n      return Math.min(opts.maxDelay, Math.floor(opts.initialDelay + Math.random() * (prevDelay * 3 - opts.initialDelay)));\n    case 'equal':\n    default:\n      return Math.floor(cap / 2 + Math.random() * (cap / 2));\n  }\n}\n\n// ─── retry ───────────────────────────────────────────────────────────────────\n\n/**\n * Retry an async operation with exponential backoff, jitter, and context-aware hooks.\n *\n * @example\n * const data = await retry(() => fetch('/api').then(r => r.json()), { maxAttempts: 5 });\n */\nexport async function retry<T>(\n  task: () => Promise<T>,\n  options: RetryxOptions = {}\n): Promise<T> {\n  const {\n    maxAttempts = 3,\n    initialDelay = 200,\n    maxDelay = 30_000,\n    factor = 2,\n    jitter = 'equal',\n    retryIf = () => true,\n    onRetry,\n    signal,\n    timeoutMs,\n  } = options;\n\n  const allErrors: unknown[] = [];\n  const startTime = Date.now();\n  let prevDelay = initialDelay;\n\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    try {\n      return timeoutMs != null\n        ? await raceTimeout(task(), timeoutMs, attempt + 1)\n        : await task();\n    } catch (err) {\n      // Timeout errors always propagate — don't retry by default but respect retryIf\n      allErrors.push(err);\n\n      if (attempt === maxAttempts - 1) break;\n\n      const context: RetryContext = {\n        attemptNumber: attempt + 1,\n        totalAttempts: maxAttempts,\n        elapsedMs: Date.now() - startTime,\n        errors: [...allErrors],\n      };\n\n      const shouldRetry = await retryIf(err, context);\n      if (!shouldRetry) break;\n\n      const delayMs = computeDelay(attempt, prevDelay, { initialDelay, maxDelay, factor, jitter });\n      prevDelay = delayMs;\n\n      onRetry?.(attempt + 1, err, delayMs, context);\n      await abortableDelay(delayMs, signal);\n    }\n  }\n\n  throw allErrors.length === 1 && allErrors[0] instanceof RetryxTimeoutError\n    ? allErrors[0]\n    : new RetryxError(\n        `All ${maxAttempts} attempts failed`,\n        maxAttempts,\n        allErrors[allErrors.length - 1],\n        allErrors\n      );\n}\n\n// ─── createRetry ─────────────────────────────────────────────────────────────\n\n/**\n * Create a reusable retry function with pre-configured options.\n *\n * @example\n * const resilient = createRetry({ maxAttempts: 5 });\n * await resilient(() => callApi());\n */\nexport function createRetry(\n  defaults: RetryxOptions\n): <T>(task: () => Promise<T>, overrides?: RetryxOptions) => Promise<T> {\n  return (task, overrides) => retry(task, { ...defaults, ...overrides });\n}\n\n// ─── withRetry ───────────────────────────────────────────────────────────────\n\n/**\n * Wraps an async function so that every call is automatically retried.\n *\n * @example\n * const resilientFetch = withRetry(fetch, { maxAttempts: 3 });\n * const resp = await resilientFetch('/api/users'); // retried on failure\n */\nexport function withRetry<TArgs extends unknown[], TReturn>(\n  fn: (...args: TArgs) => Promise<TReturn>,\n  options: RetryxOptions\n): (...args: TArgs) => Promise<TReturn> {\n  return (...args: TArgs) => retry(() => fn(...args), options);\n}\n\n// ─── CircuitBreaker ──────────────────────────────────────────────────────────\n\nexport class CircuitOpenError extends Error {\n  constructor(public readonly retryAfterMs: number) {\n    super(`Circuit is OPEN. Retry after ${retryAfterMs}ms`);\n    this.name = 'CircuitOpenError';\n  }\n}\n\n/**\n * Circuit breaker wrapping any async operation.\n *\n * States:\n * - **CLOSED** — calls pass through normally.\n * - **OPEN**   — calls fail fast with `CircuitOpenError`.\n * - **HALF_OPEN** — one probe call is allowed; success closes, failure re-opens.\n *\n * @example\n * const cb = new CircuitBreaker({ failureThreshold: 5, successThreshold: 2, openDurationMs: 10_000 });\n * const result = await cb.run(() => callExternalService());\n */\nexport class CircuitBreaker {\n  private state: CircuitState = 'CLOSED';\n  private failures = 0;\n  private successes = 0;\n  private calls = 0;\n  private openedAt = 0;\n\n  private readonly failureThreshold: number;\n  private readonly successThreshold: number;\n  private readonly openDurationMs: number;\n  private readonly volumeThreshold: number;\n  private readonly onStateChange?: (from: CircuitState, to: CircuitState) => void;\n\n  constructor(options: CircuitBreakerOptions) {\n    this.failureThreshold = options.failureThreshold;\n    this.successThreshold = options.successThreshold;\n    this.openDurationMs = options.openDurationMs;\n    this.volumeThreshold = options.volumeThreshold ?? 1;\n    this.onStateChange = options.onStateChange;\n  }\n\n  get currentState(): CircuitState {\n    this.checkHalfOpen();\n    return this.state;\n  }\n\n  async run<T>(task: () => Promise<T>): Promise<T> {\n    this.checkHalfOpen();\n\n    if (this.state === 'OPEN') {\n      const retryAfterMs = Math.max(0, this.openedAt + this.openDurationMs - Date.now());\n      throw new CircuitOpenError(retryAfterMs);\n    }\n\n    this.calls++;\n\n    try {\n      const result = await task();\n      this.onSuccess();\n      return result;\n    } catch (err) {\n      this.onFailure();\n      throw err;\n    }\n  }\n\n  /** Manually reset the circuit to CLOSED state. */\n  reset(): void {\n    const prev = this.state;\n    this.state = 'CLOSED';\n    this.failures = 0;\n    this.successes = 0;\n    this.calls = 0;\n    this.openedAt = 0;\n    if (prev !== 'CLOSED') this.onStateChange?.(prev, 'CLOSED');\n  }\n\n  stats(): CircuitBreakerStats {\n    return {\n      failures: this.failures,\n      successes: this.successes,\n      calls: this.calls,\n      state: this.state,\n    };\n  }\n\n  private checkHalfOpen(): void {\n    if (this.state === 'OPEN' && Date.now() >= this.openedAt + this.openDurationMs) {\n      this.transition('HALF_OPEN');\n    }\n  }\n\n  private onSuccess(): void {\n    this.failures = 0;\n    if (this.state === 'HALF_OPEN') {\n      this.successes++;\n      if (this.successes >= this.successThreshold) {\n        this.transition('CLOSED');\n      }\n    }\n  }\n\n  private onFailure(): void {\n    this.failures++;\n    if (this.state === 'HALF_OPEN') {\n      this.openedAt = Date.now();\n      this.transition('OPEN');\n    } else if (this.state === 'CLOSED' && this.calls >= this.volumeThreshold && this.failures >= this.failureThreshold) {\n      this.openedAt = Date.now();\n      this.transition('OPEN');\n    }\n  }\n\n  private transition(next: CircuitState): void {\n    const prev = this.state;\n    this.state = next;\n    if (next === 'CLOSED') { this.failures = 0; this.successes = 0; }\n    if (next === 'HALF_OPEN') { this.successes = 0; }\n    this.onStateChange?.(prev, next);\n  }\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,216 @@
+// src/retryx.ts
+var RetryxError = class extends Error {
+  constructor(message, attempts, lastError, allErrors) {
+    super(message);
+    this.attempts = attempts;
+    this.lastError = lastError;
+    this.allErrors = allErrors;
+    this.name = "RetryxError";
+  }
+};
+var RetryxTimeoutError = class extends Error {
+  constructor(attempt, timeoutMs) {
+    super(`Attempt ${attempt} timed out after ${timeoutMs}ms`);
+    this.attempt = attempt;
+    this.timeoutMs = timeoutMs;
+    this.name = "RetryxTimeoutError";
+  }
+};
+function abortableDelay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      },
+      { once: true }
+    );
+  });
+}
+function raceTimeout(promise, ms, attempt) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new RetryxTimeoutError(attempt, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function computeDelay(attempt, prevDelay, opts) {
+  const cap = Math.min(opts.initialDelay * Math.pow(opts.factor, attempt), opts.maxDelay);
+  switch (opts.jitter) {
+    case "none":
+      return cap;
+    case "full":
+      return Math.floor(Math.random() * cap);
+    case "decorrelated":
+      return Math.min(opts.maxDelay, Math.floor(opts.initialDelay + Math.random() * (prevDelay * 3 - opts.initialDelay)));
+    case "equal":
+    default:
+      return Math.floor(cap / 2 + Math.random() * (cap / 2));
+  }
+}
+async function retry(task, options = {}) {
+  const {
+    maxAttempts = 3,
+    initialDelay = 200,
+    maxDelay = 3e4,
+    factor = 2,
+    jitter = "equal",
+    retryIf = () => true,
+    onRetry,
+    signal,
+    timeoutMs
+  } = options;
+  const allErrors = [];
+  const startTime = Date.now();
+  let prevDelay = initialDelay;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return timeoutMs != null ? await raceTimeout(task(), timeoutMs, attempt + 1) : await task();
+    } catch (err) {
+      allErrors.push(err);
+      if (attempt === maxAttempts - 1) break;
+      const context = {
+        attemptNumber: attempt + 1,
+        totalAttempts: maxAttempts,
+        elapsedMs: Date.now() - startTime,
+        errors: [...allErrors]
+      };
+      const shouldRetry = await retryIf(err, context);
+      if (!shouldRetry) break;
+      const delayMs = computeDelay(attempt, prevDelay, { initialDelay, maxDelay, factor, jitter });
+      prevDelay = delayMs;
+      onRetry?.(attempt + 1, err, delayMs, context);
+      await abortableDelay(delayMs, signal);
+    }
+  }
+  throw allErrors.length === 1 && allErrors[0] instanceof RetryxTimeoutError ? allErrors[0] : new RetryxError(
+    `All ${maxAttempts} attempts failed`,
+    maxAttempts,
+    allErrors[allErrors.length - 1],
+    allErrors
+  );
+}
+function createRetry(defaults) {
+  return (task, overrides) => retry(task, { ...defaults, ...overrides });
+}
+function withRetry(fn, options) {
+  return (...args) => retry(() => fn(...args), options);
+}
+var CircuitOpenError = class extends Error {
+  constructor(retryAfterMs) {
+    super(`Circuit is OPEN. Retry after ${retryAfterMs}ms`);
+    this.retryAfterMs = retryAfterMs;
+    this.name = "CircuitOpenError";
+  }
+};
+var CircuitBreaker = class {
+  state = "CLOSED";
+  failures = 0;
+  successes = 0;
+  calls = 0;
+  openedAt = 0;
+  failureThreshold;
+  successThreshold;
+  openDurationMs;
+  volumeThreshold;
+  onStateChange;
+  constructor(options) {
+    this.failureThreshold = options.failureThreshold;
+    this.successThreshold = options.successThreshold;
+    this.openDurationMs = options.openDurationMs;
+    this.volumeThreshold = options.volumeThreshold ?? 1;
+    this.onStateChange = options.onStateChange;
+  }
+  get currentState() {
+    this.checkHalfOpen();
+    return this.state;
+  }
+  async run(task) {
+    this.checkHalfOpen();
+    if (this.state === "OPEN") {
+      const retryAfterMs = Math.max(0, this.openedAt + this.openDurationMs - Date.now());
+      throw new CircuitOpenError(retryAfterMs);
+    }
+    this.calls++;
+    try {
+      const result = await task();
+      this.onSuccess();
+      return result;
+    } catch (err) {
+      this.onFailure();
+      throw err;
+    }
+  }
+  /** Manually reset the circuit to CLOSED state. */
+  reset() {
+    const prev = this.state;
+    this.state = "CLOSED";
+    this.failures = 0;
+    this.successes = 0;
+    this.calls = 0;
+    this.openedAt = 0;
+    if (prev !== "CLOSED") this.onStateChange?.(prev, "CLOSED");
+  }
+  stats() {
+    return {
+      failures: this.failures,
+      successes: this.successes,
+      calls: this.calls,
+      state: this.state
+    };
+  }
+  checkHalfOpen() {
+    if (this.state === "OPEN" && Date.now() >= this.openedAt + this.openDurationMs) {
+      this.transition("HALF_OPEN");
+    }
+  }
+  onSuccess() {
+    this.failures = 0;
+    if (this.state === "HALF_OPEN") {
+      this.successes++;
+      if (this.successes >= this.successThreshold) {
+        this.transition("CLOSED");
+      }
+    }
+  }
+  onFailure() {
+    this.failures++;
+    if (this.state === "HALF_OPEN") {
+      this.openedAt = Date.now();
+      this.transition("OPEN");
+    } else if (this.state === "CLOSED" && this.calls >= this.volumeThreshold && this.failures >= this.failureThreshold) {
+      this.openedAt = Date.now();
+      this.transition("OPEN");
+    }
+  }
+  transition(next) {
+    const prev = this.state;
+    this.state = next;
+    if (next === "CLOSED") {
+      this.failures = 0;
+      this.successes = 0;
+    }
+    if (next === "HALF_OPEN") {
+      this.successes = 0;
+    }
+    this.onStateChange?.(prev, next);
+  }
+};
+
+export { CircuitBreaker, CircuitOpenError, RetryxError, RetryxTimeoutError, createRetry, retry, withRetry };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retryx.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["export type { JitterStrategy, RetryContext, RetryxOptions, CircuitState, CircuitBreakerOptions, CircuitBreakerStats } from './types.js';\nimport type { JitterStrategy, RetryContext, RetryxOptions, CircuitState, CircuitBreakerOptions, CircuitBreakerStats } from './types.js';\n\n// ─── Error Types ─────────────────────────────────────────────────────────────\n\nexport class RetryxError extends Error {\n  constructor(\n    message: string,\n    public readonly attempts: number,\n    public readonly lastError: unknown,\n    /** Every error thrown across all attempts, in order. */\n    public readonly allErrors: unknown[]\n  ) {\n    super(message);\n    this.name = 'RetryxError';\n  }\n}\n\nexport class RetryxTimeoutError extends Error {\n  constructor(\n    public readonly attempt: number,\n    public readonly timeoutMs: number\n  ) {\n    super(`Attempt ${attempt} timed out after ${timeoutMs}ms`);\n    this.name = 'RetryxTimeoutError';\n  }\n}\n\n// ─── Internal Helpers ────────────────────────────────────────────────────────\n\nfunction abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new DOMException('Aborted', 'AbortError'));\n      return;\n    }\n    const timer = setTimeout(resolve, ms);\n    signal?.addEventListener(\n      'abort',\n      () => { clearTimeout(timer); reject(new DOMException('Aborted', 'AbortError')); },\n      { once: true }\n    );\n  });\n}\n\nfunction raceTimeout<T>(promise: Promise<T>, ms: number, attempt: number): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timer = setTimeout(() => reject(new RetryxTimeoutError(attempt, ms)), ms);\n    promise.then(\n      (v) => { clearTimeout(timer); resolve(v); },\n      (e) => { clearTimeout(timer); reject(e); }\n    );\n  });\n}\n\nfunction computeDelay(\n  attempt: number,\n  prevDelay: number,\n  opts: Required<Pick<RetryxOptions, 'initialDelay' | 'maxDelay' | 'factor' | 'jitter'>>\n): number {\n  const cap = Math.min(opts.initialDelay * Math.pow(opts.factor, attempt), opts.maxDelay);\n\n  switch (opts.jitter) {\n    case 'none':\n      return cap;\n    case 'full':\n      return Math.floor(Math.random() * cap);\n    case 'decorrelated':\n      return Math.min(opts.maxDelay, Math.floor(opts.initialDelay + Math.random() * (prevDelay * 3 - opts.initialDelay)));\n    case 'equal':\n    default:\n      return Math.floor(cap / 2 + Math.random() * (cap / 2));\n  }\n}\n\n// ─── retry ───────────────────────────────────────────────────────────────────\n\n/**\n * Retry an async operation with exponential backoff, jitter, and context-aware hooks.\n *\n * @example\n * const data = await retry(() => fetch('/api').then(r => r.json()), { maxAttempts: 5 });\n */\nexport async function retry<T>(\n  task: () => Promise<T>,\n  options: RetryxOptions = {}\n): Promise<T> {\n  const {\n    maxAttempts = 3,\n    initialDelay = 200,\n    maxDelay = 30_000,\n    factor = 2,\n    jitter = 'equal',\n    retryIf = () => true,\n    onRetry,\n    signal,\n    timeoutMs,\n  } = options;\n\n  const allErrors: unknown[] = [];\n  const startTime = Date.now();\n  let prevDelay = initialDelay;\n\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    try {\n      return timeoutMs != null\n        ? await raceTimeout(task(), timeoutMs, attempt + 1)\n        : await task();\n    } catch (err) {\n      // Timeout errors always propagate — don't retry by default but respect retryIf\n      allErrors.push(err);\n\n      if (attempt === maxAttempts - 1) break;\n\n      const context: RetryContext = {\n        attemptNumber: attempt + 1,\n        totalAttempts: maxAttempts,\n        elapsedMs: Date.now() - startTime,\n        errors: [...allErrors],\n      };\n\n      const shouldRetry = await retryIf(err, context);\n      if (!shouldRetry) break;\n\n      const delayMs = computeDelay(attempt, prevDelay, { initialDelay, maxDelay, factor, jitter });\n      prevDelay = delayMs;\n\n      onRetry?.(attempt + 1, err, delayMs, context);\n      await abortableDelay(delayMs, signal);\n    }\n  }\n\n  throw allErrors.length === 1 && allErrors[0] instanceof RetryxTimeoutError\n    ? allErrors[0]\n    : new RetryxError(\n        `All ${maxAttempts} attempts failed`,\n        maxAttempts,\n        allErrors[allErrors.length - 1],\n        allErrors\n      );\n}\n\n// ─── createRetry ─────────────────────────────────────────────────────────────\n\n/**\n * Create a reusable retry function with pre-configured options.\n *\n * @example\n * const resilient = createRetry({ maxAttempts: 5 });\n * await resilient(() => callApi());\n */\nexport function createRetry(\n  defaults: RetryxOptions\n): <T>(task: () => Promise<T>, overrides?: RetryxOptions) => Promise<T> {\n  return (task, overrides) => retry(task, { ...defaults, ...overrides });\n}\n\n// ─── withRetry ───────────────────────────────────────────────────────────────\n\n/**\n * Wraps an async function so that every call is automatically retried.\n *\n * @example\n * const resilientFetch = withRetry(fetch, { maxAttempts: 3 });\n * const resp = await resilientFetch('/api/users'); // retried on failure\n */\nexport function withRetry<TArgs extends unknown[], TReturn>(\n  fn: (...args: TArgs) => Promise<TReturn>,\n  options: RetryxOptions\n): (...args: TArgs) => Promise<TReturn> {\n  return (...args: TArgs) => retry(() => fn(...args), options);\n}\n\n// ─── CircuitBreaker ──────────────────────────────────────────────────────────\n\nexport class CircuitOpenError extends Error {\n  constructor(public readonly retryAfterMs: number) {\n    super(`Circuit is OPEN. Retry after ${retryAfterMs}ms`);\n    this.name = 'CircuitOpenError';\n  }\n}\n\n/**\n * Circuit breaker wrapping any async operation.\n *\n * States:\n * - **CLOSED** — calls pass through normally.\n * - **OPEN**   — calls fail fast with `CircuitOpenError`.\n * - **HALF_OPEN** — one probe call is allowed; success closes, failure re-opens.\n *\n * @example\n * const cb = new CircuitBreaker({ failureThreshold: 5, successThreshold: 2, openDurationMs: 10_000 });\n * const result = await cb.run(() => callExternalService());\n */\nexport class CircuitBreaker {\n  private state: CircuitState = 'CLOSED';\n  private failures = 0;\n  private successes = 0;\n  private calls = 0;\n  private openedAt = 0;\n\n  private readonly failureThreshold: number;\n  private readonly successThreshold: number;\n  private readonly openDurationMs: number;\n  private readonly volumeThreshold: number;\n  private readonly onStateChange?: (from: CircuitState, to: CircuitState) => void;\n\n  constructor(options: CircuitBreakerOptions) {\n    this.failureThreshold = options.failureThreshold;\n    this.successThreshold = options.successThreshold;\n    this.openDurationMs = options.openDurationMs;\n    this.volumeThreshold = options.volumeThreshold ?? 1;\n    this.onStateChange = options.onStateChange;\n  }\n\n  get currentState(): CircuitState {\n    this.checkHalfOpen();\n    return this.state;\n  }\n\n  async run<T>(task: () => Promise<T>): Promise<T> {\n    this.checkHalfOpen();\n\n    if (this.state === 'OPEN') {\n      const retryAfterMs = Math.max(0, this.openedAt + this.openDurationMs - Date.now());\n      throw new CircuitOpenError(retryAfterMs);\n    }\n\n    this.calls++;\n\n    try {\n      const result = await task();\n      this.onSuccess();\n      return result;\n    } catch (err) {\n      this.onFailure();\n      throw err;\n    }\n  }\n\n  /** Manually reset the circuit to CLOSED state. */\n  reset(): void {\n    const prev = this.state;\n    this.state = 'CLOSED';\n    this.failures = 0;\n    this.successes = 0;\n    this.calls = 0;\n    this.openedAt = 0;\n    if (prev !== 'CLOSED') this.onStateChange?.(prev, 'CLOSED');\n  }\n\n  stats(): CircuitBreakerStats {\n    return {\n      failures: this.failures,\n      successes: this.successes,\n      calls: this.calls,\n      state: this.state,\n    };\n  }\n\n  private checkHalfOpen(): void {\n    if (this.state === 'OPEN' && Date.now() >= this.openedAt + this.openDurationMs) {\n      this.transition('HALF_OPEN');\n    }\n  }\n\n  private onSuccess(): void {\n    this.failures = 0;\n    if (this.state === 'HALF_OPEN') {\n      this.successes++;\n      if (this.successes >= this.successThreshold) {\n        this.transition('CLOSED');\n      }\n    }\n  }\n\n  private onFailure(): void {\n    this.failures++;\n    if (this.state === 'HALF_OPEN') {\n      this.openedAt = Date.now();\n      this.transition('OPEN');\n    } else if (this.state === 'CLOSED' && this.calls >= this.volumeThreshold && this.failures >= this.failureThreshold) {\n      this.openedAt = Date.now();\n      this.transition('OPEN');\n    }\n  }\n\n  private transition(next: CircuitState): void {\n    const prev = this.state;\n    this.state = next;\n    if (next === 'CLOSED') { this.failures = 0; this.successes = 0; }\n    if (next === 'HALF_OPEN') { this.successes = 0; }\n    this.onStateChange?.(prev, next);\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@async-kit/retryx",
+  "version": "0.1.2",
+  "description": "Smart async retry system with exponential backoff, jitter, and circuit breaker for JavaScript/TypeScript",
+  "keywords": [
+    "async",
+    "retry",
+    "backoff",
+    "circuit-breaker",
+    "resilience",
+    "fault-tolerance"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NexaLeaf/async-kit",
+    "directory": "packages/retryx"
+  },
+  "homepage": "https://github.com/NexaLeaf/async-kit/tree/main/packages/retryx#readme",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.lib.json --noEmit"
+  },
+  "devDependencies": {}
+}