jitterbug 1.0.0-alpha.4 → 1.0.0-alpha.6

package/README.md

@@ -1,11 +1,17 @@
-# jitterbug
-
-Jitterbug is a lightweight library for building reliable retry behavior in distributed systems and API clients.
+![Jitterbug Logo](https://raw.githubusercontent.com/mecharmor/jitterbug/main/assets/logo.png)
 
 ![Build Status](https://github.com/mecharmor/jitterbug/actions/workflows/build.yml/badge.svg?branch=main)
 ![Tests](https://img.shields.io/github/actions/workflow/status/mecharmor/jitterbug/build.yml?branch=main&label=tests)
-![Version](https://img.shields.io/npm/v/jitterbug?label=version)
+[![npm version](https://img.shields.io/npm/v/jitterbug.svg)](https://www.npmjs.com/package/jitterbug)
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Coverage](https://img.shields.io/badge/coverage-100.00%25-brightgreen)
+
+
+Jitterbug is a modern, type‑safe retry engine for Node.js  and browser environments. It provides predictable backoff behavior and a suite of configurable jitter strategies, all wrapped in a clean, minimal API. The library is intentionally lightweight and dependency‑free to keep integration simple and reduce risk for consumers.
+
+Designed to be framework‑agnostic and easy to adopt, Jitterbug emphasizes clarity, reliability, and maintainability. Its implementation is backed by comprehensive automated testing to ensure consistent behavior and to support confident contributions from the community.
+
+
 
 ## Installation
 
@@ -35,7 +41,8 @@ const fetchWithRetry = retry(async (url) => {
 }, {
   maxAttempts: 5,
   delay: 1000,
-  backoff: 'exponential', // 'exponential', 'linear', or 'fixed'
+  backoff: 'exponential',
+  jitterConfig: { type: 'equal' }, // optional jitter
   onRetry: (error, attempt, waitTime) => {
     console.log(`Retry attempt ${attempt} after ${waitTime}ms`);
   }
@@ -50,6 +57,43 @@ try {
 }
 ```
 
+### Jitter Utility Functions
+
+Jitterbug also exports its jitter calculation helpers directly.  
+These functions are pure, deterministic (when `Math.random` is mocked), and can be used independently of the retry system.
+
+---
+
+#### **`calculateEqualJitter(baseDelayMs: number): number`**  
+Produces a delay between **50% and 100%** of the base delay.  
+Useful for predictable but desynchronized retry timing.
+
+---
+
+#### **`calculateFullJitter(minDelayMs: number, maxDelayMs: number): number`**  
+Returns a completely random delay between `minDelayMs` (inclusive) and `maxDelayMs` (exclusive).  
+Ideal for aggressively spreading retries under heavy load.
+
+---
+
+#### **`calculateFixedJitter(baseDelayMs: number, jitterAmount: number): number`**  
+Subtracts a constant amount from the base delay, never below zero.  
+Useful when you want consistent desynchronization without randomness.
+
+---
+
+#### **`calculateRandomJitter(baseDelayMs: number, jitterFraction: number): number`**  
+Applies a symmetric ±fraction jitter around the base delay.  
+Example: `fraction = 0.2` → delay may vary between 80% and 120% of the base.
+
+---
+
+#### **`calculateDecorrelatedJitter(baseDelayMs: number, maxDelayMs: number, prevDelayMs?: number): number`**  
+Implements AWS‑style decorrelated jitter.  
+Each retry picks a random delay between the base delay and **3× the previous delay**, capped at `maxDelayMs`.  
+Excellent for large distributed systems where synchronized retries can overwhelm downstream services.
+
+
 ## API
 
 ### `retry<T>(fn: T, options?: RetryOptions): T`
@@ -62,6 +106,7 @@ Creates a retry wrapper function.
   - `maxAttempts` (number, default: 3): Maximum number of retry attempts
   - `delay` (number, default: 1000): Base delay in milliseconds
   - `backoff` ('exponential' | 'linear' | 'fixed', default: 'exponential'): Backoff strategy
+  - `jitterConfig` (`JitterConfig` | `undefined`): Optional jitter strategy applied on top of the base dela
   - `onRetry` ((error: Error, attempt: number, waitTime: number) => void, optional): Callback called before each retry
 
 **Returns:** A function that wraps the original function with retry logic
@@ -71,93 +116,26 @@ Creates a retry wrapper function.
 import type { RetryOptions, BackoffStrategy } from 'jitterbug';
 ```
 
-## Development
+### Jitter Configuration Options
 
-### Building
+- **`{ type: 'none' }`**  
+  No jitter applied. Retries use the exact backoff delay.
 
-```bash
-# Build the project
-npm run build
+- **`{ type: 'equal' }`**  
+  Splits the delay into a fixed half and a random half. Produces predictable but desynchronized retry timing.
 
-# Build in watch mode
-npm run dev
+- **`{ type: 'full', min, max }`**  
+  Picks a completely random delay between `min` and `max`. Best for aggressively spreading retries under heavy load.
 
-# Type check without building
-npm run typecheck
-```
+- **`{ type: 'fixed', amount }`**  
+  Subtracts a constant amount from the base delay (never below zero). Useful for consistent, predictable desynchronization.
 
-### Running Tests
+- **`{ type: 'random', fraction }`**  
+  Applies a symmetric ±fraction jitter around the base delay (e.g., `0.2` = ±20%). Light, centered randomness.
 
-```bash
-# Run tests in watch mode
-npm test
-
-# Run tests once
-npm run test:run
-
-# Run tests with coverage
-npm run test:coverage
-```
-
-### Publishing
-
-Publishing to npm is automated via GitHub Actions. To publish a new version:
-
-```bash
-# Choose one based on the type of change:
-npm version patch  # Bug fixes: 0.1.0 -> 0.1.1
-npm version minor  # New features: 0.1.0 -> 0.2.0
-npm version major  # Breaking changes: 0.1.0 -> 1.0.0
-
-# This automatically:
-# - Updates package.json version
-# - Builds the project (via version script)
-# - Creates a git commit
-# - Creates a git tag (v0.1.1, v0.2.0, etc.)
-
-# Then push both the commit and tags:
-git push && git push --tags
-```
-
-**Publishing alpha/beta versions:**
-
-For pre-release versions (alpha, beta, rc):
+- **`{ type: 'decorrelated', maxDelay }`**  
+  AWS‑style decorrelated jitter. Each retry picks a random delay between the base delay and 3× the previous jittered delay, capped at `maxDelay`.
 
-```bash
-# Create an alpha version
-npm version prepatch --preid=alpha  # 0.1.0 -> 0.1.1-alpha.0
-npm version preminor --preid=alpha  # 0.1.0 -> 0.2.0-alpha.0
-npm version premajor --preid=alpha  # 0.1.0 -> 1.0.0-alpha.0
-
-# Increment alpha version
-npm version prerelease --preid=alpha  # 0.1.1-alpha.0 -> 0.1.1-alpha.1
-
-# Push the commit and tag
-git push && git push --tags
-```
-
-The CI/CD pipeline will automatically:
-- Run all tests
-- Build the project
-- Verify version matches the tag
-- Publish to npm (if tests pass)
-
-**Note:** `NPM_TOKEN` secret needs to be setupas a GitHub secret with your npm access token.
-
-### Project Structure
-
-```
-jitterbug/
-├── src/              # TypeScript source code
-│   ├── retry.ts      # Core retry implementation
-│   └── index.ts      # Main entry point
-├── dist/             # Built output (ESM + CJS + types)
-├── test/             # Test files
-│   └── retry.test.js
-├── tsconfig.json     # TypeScript configuration
-├── tsup.config.ts    # Build configuration
-└── package.json
-```
 
 ## Test Coverage
 
@@ -166,7 +144,7 @@ jitterbug/
 | Metric | Coverage |
 |--------|----------|
 | Statements | 100.00% |
-| Branches | 95.00% |
+| Branches | 96.67% |
 | Functions | 100.00% |
 | Lines | 100.00% |
 

package/dist/index.cjs

@@ -8,6 +8,35 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/jitter.ts
+var jitter_exports = {};
+__export(jitter_exports, {
+  calculateDecorrelatedJitter: () => calculateDecorrelatedJitter,
+  calculateEqualJitter: () => calculateEqualJitter,
+  calculateFixedJitter: () => calculateFixedJitter,
+  calculateFullJitter: () => calculateFullJitter,
+  calculateRandomJitter: () => calculateRandomJitter
+});
+function calculateFullJitter(minDelayMs, maxDelayMs) {
+  return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;
+}
+function calculateEqualJitter(baseDelayMs) {
+  const halfDelay = baseDelayMs / 2;
+  return halfDelay + Math.random() * halfDelay;
+}
+function calculateFixedJitter(maxDelayMs, jitterAmount) {
+  return Math.max(0, maxDelayMs - jitterAmount);
+}
+function calculateRandomJitter(baseDelayMs, jitterFraction) {
+  const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;
+  return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));
+}
+function calculateDecorrelatedJitter(baseDelayMs, maxDelayMs, prevDelayMs = 0) {
+  const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);
+  const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);
+  return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay);
+}
+
 // src/retry.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -23,16 +52,37 @@ function calculateDelay(baseDelay, attempt, backoff) {
       return baseDelay;
   }
 }
+function applyJitter(baseDelay, jitter, prevDelay) {
+  if (!jitter || jitter.type === "none") return 0;
+  switch (jitter.type) {
+    case "equal":
+      return calculateEqualJitter(baseDelay);
+    case "full":
+      return calculateFullJitter(jitter.min, jitter.max);
+    case "fixed":
+      return calculateFixedJitter(baseDelay, jitter.amount);
+    case "random":
+      return calculateRandomJitter(baseDelay, jitter.fraction);
+    case "decorrelated":
+      return calculateDecorrelatedJitter(
+        baseDelay,
+        jitter.maxDelay,
+        prevDelay
+      );
+  }
+}
 function retry(fn, options = {}) {
   const {
     maxAttempts = 3,
     delay = 1e3,
     backoff = "exponential",
+    jitterConfig,
     onRetry = () => {
     }
   } = options;
   return (async function(...args) {
     let lastError;
+    let prevJitterDelay = 0;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       try {
         return await fn(...args);
@@ -40,8 +90,11 @@ function retry(fn, options = {}) {
         lastError = error instanceof Error ? error : new Error(String(error));
         if (attempt < maxAttempts) {
           const waitTime = calculateDelay(delay, attempt, backoff);
-          onRetry(lastError, attempt, waitTime);
-          await sleep(waitTime);
+          const jitterMs = applyJitter(waitTime, jitterConfig, prevJitterDelay);
+          prevJitterDelay = jitterMs;
+          const delayTimeMs = waitTime + jitterMs;
+          onRetry(lastError, attempt, delayTimeMs);
+          await sleep(delayTimeMs);
         }
       }
     }
@@ -49,35 +102,6 @@ function retry(fn, options = {}) {
   });
 }
 
-// src/jitter.ts
-var jitter_exports = {};
-__export(jitter_exports, {
-  calculateDecorrelatedJitter: () => calculateDecorrelatedJitter,
-  calculateEqualJitter: () => calculateEqualJitter,
-  calculateFixedJitter: () => calculateFixedJitter,
-  calculateFullJitter: () => calculateFullJitter,
-  calculateRandomJitter: () => calculateRandomJitter
-});
-function calculateFullJitter(minDelayMs, maxDelayMs) {
-  return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;
-}
-function calculateEqualJitter(baseDelayMs) {
-  const halfDelay = baseDelayMs / 2;
-  return halfDelay + Math.random() * halfDelay;
-}
-function calculateFixedJitter(maxDelayMs, jitterAmount) {
-  return Math.max(0, maxDelayMs - jitterAmount);
-}
-function calculateRandomJitter(baseDelayMs, jitterFraction) {
-  const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;
-  return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));
-}
-function calculateDecorrelatedJitter(baseDelayMs, maxDelayMs, prevDelayMs = 0) {
-  const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);
-  const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);
-  return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay);
-}
-
 // src/index.ts
 var index_default = {
   retry,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/retry.ts","../src/jitter.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Core retry logic implementation\n */\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nfunction calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number {\n  switch (backoff) {\n    case 'exponential':\n      return baseDelay * Math.pow(2, attempt - 1);\n    case 'linear':\n      return baseDelay * attempt;\n    case 'fixed':\n    default:\n      return baseDelay;\n  }\n}\n\nexport type BackoffStrategy = 'exponential' | 'linear' | 'fixed';\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxAttempts?: number;\n  /** Base delay in milliseconds (default: 1000) */\n  delay?: number;\n  /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Callback called before each retry (error, attempt, waitTime) */\n  onRetry?: (error: Error, attempt: number, waitTime: number) => void;\n}\n\n/**\n * Creates a retry wrapper function\n * @param fn - The async function to retry\n * @param options - Retry configuration\n * @returns A function that wraps the original function with retry logic\n */\n// @typescript-eslint/no-explicit-any\nexport function retry<T extends (...args: unknown[]) => Promise<unknown>>(\n  fn: T,\n  options: RetryOptions = {}\n): T {\n  const {\n    maxAttempts = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    onRetry = () => {}\n  } = options;\n\n  return (async function(...args: Parameters<T>): Promise<ReturnType<T>> {\n    let lastError: Error;\n    \n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      try {\n        return await fn(...args) as ReturnType<T>;\n      } catch (error) {\n        lastError = error instanceof Error ? error : new Error(String(error));\n        \n        if (attempt < maxAttempts) {\n          const waitTime = calculateDelay(delay, attempt, backoff);\n          onRetry(lastError, attempt, waitTime);\n          await sleep(waitTime);\n        }\n      }\n    }\n    \n    throw lastError!;\n  }) as T;\n}\n\nexport { calculateDelay, sleep };\n\n","/**\n * Generates a full‑jitter delay within the given range.\n *\n * Full jitter selects a completely random delay between `minDelay` and\n * `maxDelay`, spreading numbers across the entire interval to create jitter.\n *\n * @param {number} minDelayMs - The minimum delay (inclusive).\n * @param {number} maxDelayMs - The maximum delay (exclusive).\n * @returns {number} A random delay between `minDelay` and `maxDelay`.\n * @description Full jitter is ideal when many clients may retry at the same time and you need to aggressively spread those retries out. It’s especially useful under high contention or bursty failure conditions, where a wide range of random delays helps prevent retry storms and reduces load on downstream services.\n */\nexport function calculateFullJitter(minDelayMs: number, maxDelayMs: number): number {\n    return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;\n}\n\n/**\n * Calculates an equal‑jitter backoff delay.\n *\n * Equal jitter splits the delay into a fixed half and a random half.\n * This reduces synchronization between clients while avoiding the\n * extremely low delays produced by full jitter.\n *\n * @param {number} baseDelayMs - The original backoff delay before jitter.\n * @returns {number} A delay between half of `baseDelay` and the full `baseDelay`.\n * @description Equal jitter is useful when you want a smoother, more predictable retry pattern that still avoids synchronized retries. It guarantees at least half of the base delay while adding randomness to the other half, giving you a balanced backoff that reduces contention without the extreme variability of full jitter.\n */\nexport function calculateEqualJitter(baseDelayMs: number): number {\n    const halfDelay = baseDelayMs / 2;\n    return halfDelay + Math.random() * halfDelay;\n}\n\n\n/**\n * Calculates a fixed‑jitter delay by subtracting a constant amount from the base delay. Unlike random jitter strategies, fixed jitter provides predictable timing while still preventing perfectly aligned retries.\n * Use this when you want a small, consistent desynchronization between clients without introducing randomness — ideal for stable systems where timing consistency matters more than wide jitter distribution.\n * @param {number} maxDelayMs - The original delay before applying jitter.\n * @param {number} jitterAmount - The fixed amount to subtract.\n * @returns {number} The delay after subtracting `jitterAmount`, never below zero.\n */\nexport function calculateFixedJitter(maxDelayMs: number, jitterAmount: number): number {\n    return Math.max(0, maxDelayMs - jitterAmount);\n}\n\n/**\n * Calculates a random‑jitter backoff delay by applying a symmetric\n * random variation around the base delay. The jitter fraction determines\n * how far the delay may swing above or below the original value.\n *\n * Random jitter is useful when you want to “wiggle” the delay without\n * dramatically changing its overall shape. It provides light\n * desynchronization between clients while keeping the delay centered\n * around the base value — ideal for systems that need some variability\n * but not the wide spread of full jitter.\n *\n * @param {number} baseDelayMs - The original delay before jitter is applied.\n * @param {number} jitterFraction - Maximum fractional deviation (e.g., 0.2 for ±20%).\n * @returns {number} A jittered delay, clamped to zero if the calculation goes negative.\n */\nexport function calculateRandomJitter(baseDelayMs: number, jitterFraction: number): number {\n    // Math.random() gives us 0 to 1 so multiply by 2 and subtract 1 to get -1 to 1 range\n    const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;\n    return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));\n}\n\n/**\n * Calculates a decorrelated jitter backoff delay using the algorithm\n * popularized by AWS. Each retry delay is chosen randomly between the\n * base delay and three times the previous delay, then capped at the\n * maximum allowed delay. This prevents synchronized retry spikes and\n * produces a smooth, adaptive backoff pattern.\n *\n * Use this when you need highly desynchronized retries across many\n * clients—especially in distributed systems or high‑traffic services\n * where coordinated retry storms can overwhelm downstream resources.\n *\n * AWS reference:\n * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/\n *\n * @param {number} baseDelayMs - The minimum delay for any retry attempt.\n * @param {number} maxDelayMs - The maximum allowed delay.\n * @param {number} [prevDelayMs=0] - The delay used for the previous retry.\n * @returns {number} A jittered delay capped at `maxDelayMs`.\n */\nexport function calculateDecorrelatedJitter(baseDelayMs: number, maxDelayMs: number, prevDelayMs: number = 0): number {\n    const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);\n    const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);\n    return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay)\n}","/**\n * Jitterbug - A lightweight library for building reliable retry behavior\n */\n\nexport { retry, calculateDelay, sleep, type RetryOptions, type BackoffStrategy } from './retry';\n\nimport * as jitterFunctions from './jitter';\nimport { retry } from './retry';\n\nexport default {\n  retry,\n  ...jitterFunctions\n};\n"]}
+{"version":3,"sources":["../src/jitter.ts","../src/retry.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Generates a full‑jitter delay within the given range.\n *\n * Full jitter selects a completely random delay between `minDelay` and\n * `maxDelay`, spreading numbers across the entire interval to create jitter.\n *\n * @param {number} minDelayMs - The minimum delay (inclusive).\n * @param {number} maxDelayMs - The maximum delay (exclusive).\n * @returns {number} A random delay between `minDelay` and `maxDelay`.\n * @description Full jitter is ideal when many clients may retry at the same time and you need to aggressively spread those retries out. It’s especially useful under high contention or bursty failure conditions, where a wide range of random delays helps prevent retry storms and reduces load on downstream services.\n */\nexport function calculateFullJitter(minDelayMs: number, maxDelayMs: number): number {\n    return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;\n}\n\n/**\n * Calculates an equal‑jitter backoff delay.\n *\n * Equal jitter splits the delay into a fixed half and a random half.\n * This reduces synchronization between clients while avoiding the\n * extremely low delays produced by full jitter.\n *\n * @param {number} baseDelayMs - The original backoff delay before jitter.\n * @returns {number} A delay between half of `baseDelay` and the full `baseDelay`.\n * @description Equal jitter is useful when you want a smoother, more predictable retry pattern that still avoids synchronized retries. It guarantees at least half of the base delay while adding randomness to the other half, giving you a balanced backoff that reduces contention without the extreme variability of full jitter.\n */\nexport function calculateEqualJitter(baseDelayMs: number): number {\n    const halfDelay = baseDelayMs / 2;\n    return halfDelay + Math.random() * halfDelay;\n}\n\n/**\n * Calculates a fixed‑jitter delay by subtracting a constant amount from the base delay. Unlike random jitter strategies, fixed jitter provides predictable timing while still preventing perfectly aligned retries.\n * Use this when you want a small, consistent desynchronization between clients without introducing randomness — ideal for stable systems where timing consistency matters more than wide jitter distribution.\n * @param {number} maxDelayMs - The original delay before applying jitter.\n * @param {number} jitterAmount - The fixed amount to subtract.\n * @returns {number} The delay after subtracting `jitterAmount`, never below zero.\n */\nexport function calculateFixedJitter(maxDelayMs: number, jitterAmount: number): number {\n    return Math.max(0, maxDelayMs - jitterAmount);\n}\n\n/**\n * Calculates a random‑jitter backoff delay by applying a symmetric\n * random variation around the base delay. The jitter fraction determines\n * how far the delay may swing above or below the original value.\n *\n * Random jitter is useful when you want to “wiggle” the delay without\n * dramatically changing its overall shape. It provides light\n * desynchronization between clients while keeping the delay centered\n * around the base value — ideal for systems that need some variability\n * but not the wide spread of full jitter.\n *\n * @param {number} baseDelayMs - The original delay before jitter is applied.\n * @param {number} jitterFraction - Maximum fractional deviation (e.g., 0.2 for ±20%).\n * @returns {number} A jittered delay, clamped to zero if the calculation goes negative.\n */\nexport function calculateRandomJitter(baseDelayMs: number, jitterFraction: number): number {\n    // Math.random() gives us 0 to 1 so multiply by 2 and subtract 1 to get -1 to 1 range\n    const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;\n    return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));\n}\n\n/**\n * Calculates a decorrelated jitter backoff delay using the algorithm\n * popularized by AWS. Each retry delay is chosen randomly between the\n * base delay and three times the previous delay, then capped at the\n * maximum allowed delay. This prevents synchronized retry spikes and\n * produces a smooth, adaptive backoff pattern.\n *\n * Use this when you need highly desynchronized retries across many\n * clients—especially in distributed systems or high‑traffic services\n * where coordinated retry storms can overwhelm downstream resources.\n *\n * AWS reference:\n * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/\n *\n * @param {number} baseDelayMs - The minimum delay for any retry attempt.\n * @param {number} maxDelayMs - The maximum allowed delay.\n * @param {number} [prevDelayMs=0] - The delay used for the previous retry.\n * @returns {number} A jittered delay capped at `maxDelayMs`.\n */\nexport function calculateDecorrelatedJitter(baseDelayMs: number, maxDelayMs: number, prevDelayMs: number = 0): number {\n    const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);\n    const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);\n    return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay)\n}","/**\n * Core retry logic implementation\n */\n\nimport { calculateDecorrelatedJitter, calculateEqualJitter, calculateFixedJitter, calculateFullJitter, calculateRandomJitter } from \"./jitter\";\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nexport type BackoffStrategy = 'exponential' | 'linear' | 'fixed';\nfunction calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number {\n  switch (backoff) {\n    case 'exponential':\n      return baseDelay * Math.pow(2, attempt - 1);\n    case 'linear':\n      return baseDelay * attempt;\n    case 'fixed':\n    default:\n      return baseDelay;\n  }\n}\n\nexport type JitterConfig =\n  | { type: 'none' }\n  | { type: 'equal' }\n  | { type: 'full', min: number, max: number }\n  | { type: 'fixed', amount: number }\n  | { type: 'random', fraction: number }\n  | { type: 'decorrelated', maxDelay: number };\n\n  function applyJitter(\n    baseDelay: number,\n    jitter: JitterConfig | undefined,\n    prevDelay: number\n  ): number {\n    if (!jitter || jitter.type === 'none') return 0;\n  \n    switch (jitter.type) {\n      case 'equal':\n        return calculateEqualJitter(baseDelay);\n  \n      case 'full':\n        return calculateFullJitter(jitter.min, jitter.max);\n  \n      case 'fixed':\n        return calculateFixedJitter(baseDelay, jitter.amount);\n  \n      case 'random':\n        return calculateRandomJitter(baseDelay, jitter.fraction);\n  \n      case 'decorrelated':\n        return calculateDecorrelatedJitter(\n          baseDelay,\n          jitter.maxDelay,\n          prevDelay\n        );\n    }\n  }\n  \n\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxAttempts?: number;\n  /** Base delay in milliseconds (default: 1000) */\n  delay?: number;\n  /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Callback called before each retry (error, attempt, waitTime) */\n  onRetry?: (error: Error, attempt: number, waitTime: number) => void;\n  /** Jitter settings */\n  jitterConfig?: JitterConfig\n}\n\n/**\n * @param fn - The async function to retry\n * @param options - Retry configuration\n * @returns A function that wraps the original function with retry logic\n */\n// @typescript-eslint/no-explicit-any\nexport function retry<T extends (...args: unknown[]) => Promise<unknown>>(\n  fn: T,\n  options: RetryOptions = {}\n): T {\n  const {\n    maxAttempts = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    jitterConfig,\n    onRetry = () => {}\n  } = options;\n\n  return (async function(...args: Parameters<T>): Promise<ReturnType<T>> {\n    let lastError: Error;\n    \n    let prevJitterDelay = 0;\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      try {\n        return await fn(...args) as ReturnType<T>;\n      } catch (error) {\n        lastError = error instanceof Error ? error : new Error(String(error));\n        \n        if (attempt < maxAttempts) {\n          const waitTime = calculateDelay(delay, attempt, backoff);\n          const jitterMs = applyJitter(waitTime, jitterConfig, prevJitterDelay)\n          prevJitterDelay = jitterMs;\n          const delayTimeMs = waitTime + jitterMs;\n          onRetry(lastError, attempt, delayTimeMs);\n          await sleep(delayTimeMs);\n        }\n      }\n    }\n    \n    throw lastError!;\n  }) as T;\n}\n\nexport { calculateDelay, sleep, applyJitter };\n\n","/**\n * Jitterbug - A lightweight library for building reliable retry behavior\n */\n\nexport { retry, calculateDelay, sleep, type RetryOptions, type BackoffStrategy } from './retry';\n\nimport * as jitterFunctions from './jitter';\nimport { retry } from './retry';\n\nexport default {\n  retry,\n  ...jitterFunctions\n};\n"]}

package/dist/index.d.cts

@@ -2,8 +2,26 @@
  * Core retry logic implementation
  */
 declare function sleep(ms: number): Promise<void>;
-declare function calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number;
 type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+declare function calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number;
+type JitterConfig = {
+    type: 'none';
+} | {
+    type: 'equal';
+} | {
+    type: 'full';
+    min: number;
+    max: number;
+} | {
+    type: 'fixed';
+    amount: number;
+} | {
+    type: 'random';
+    fraction: number;
+} | {
+    type: 'decorrelated';
+    maxDelay: number;
+};
 interface RetryOptions {
     /** Maximum number of retry attempts (default: 3) */
     maxAttempts?: number;
@@ -13,9 +31,10 @@ interface RetryOptions {
     backoff?: BackoffStrategy;
     /** Callback called before each retry (error, attempt, waitTime) */
     onRetry?: (error: Error, attempt: number, waitTime: number) => void;
+    /** Jitter settings */
+    jitterConfig?: JitterConfig;
 }
 /**
- * Creates a retry wrapper function
  * @param fn - The async function to retry
  * @param options - Retry configuration
  * @returns A function that wraps the original function with retry logic

package/dist/index.d.ts

@@ -2,8 +2,26 @@
  * Core retry logic implementation
  */
 declare function sleep(ms: number): Promise<void>;
-declare function calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number;
 type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+declare function calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number;
+type JitterConfig = {
+    type: 'none';
+} | {
+    type: 'equal';
+} | {
+    type: 'full';
+    min: number;
+    max: number;
+} | {
+    type: 'fixed';
+    amount: number;
+} | {
+    type: 'random';
+    fraction: number;
+} | {
+    type: 'decorrelated';
+    maxDelay: number;
+};
 interface RetryOptions {
     /** Maximum number of retry attempts (default: 3) */
     maxAttempts?: number;
@@ -13,9 +31,10 @@ interface RetryOptions {
     backoff?: BackoffStrategy;
     /** Callback called before each retry (error, attempt, waitTime) */
     onRetry?: (error: Error, attempt: number, waitTime: number) => void;
+    /** Jitter settings */
+    jitterConfig?: JitterConfig;
 }
 /**
- * Creates a retry wrapper function
  * @param fn - The async function to retry
  * @param options - Retry configuration
  * @returns A function that wraps the original function with retry logic

package/dist/index.js

@@ -4,6 +4,35 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/jitter.ts
+var jitter_exports = {};
+__export(jitter_exports, {
+  calculateDecorrelatedJitter: () => calculateDecorrelatedJitter,
+  calculateEqualJitter: () => calculateEqualJitter,
+  calculateFixedJitter: () => calculateFixedJitter,
+  calculateFullJitter: () => calculateFullJitter,
+  calculateRandomJitter: () => calculateRandomJitter
+});
+function calculateFullJitter(minDelayMs, maxDelayMs) {
+  return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;
+}
+function calculateEqualJitter(baseDelayMs) {
+  const halfDelay = baseDelayMs / 2;
+  return halfDelay + Math.random() * halfDelay;
+}
+function calculateFixedJitter(maxDelayMs, jitterAmount) {
+  return Math.max(0, maxDelayMs - jitterAmount);
+}
+function calculateRandomJitter(baseDelayMs, jitterFraction) {
+  const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;
+  return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));
+}
+function calculateDecorrelatedJitter(baseDelayMs, maxDelayMs, prevDelayMs = 0) {
+  const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);
+  const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);
+  return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay);
+}
+
 // src/retry.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -19,16 +48,37 @@ function calculateDelay(baseDelay, attempt, backoff) {
       return baseDelay;
   }
 }
+function applyJitter(baseDelay, jitter, prevDelay) {
+  if (!jitter || jitter.type === "none") return 0;
+  switch (jitter.type) {
+    case "equal":
+      return calculateEqualJitter(baseDelay);
+    case "full":
+      return calculateFullJitter(jitter.min, jitter.max);
+    case "fixed":
+      return calculateFixedJitter(baseDelay, jitter.amount);
+    case "random":
+      return calculateRandomJitter(baseDelay, jitter.fraction);
+    case "decorrelated":
+      return calculateDecorrelatedJitter(
+        baseDelay,
+        jitter.maxDelay,
+        prevDelay
+      );
+  }
+}
 function retry(fn, options = {}) {
   const {
     maxAttempts = 3,
     delay = 1e3,
     backoff = "exponential",
+    jitterConfig,
     onRetry = () => {
     }
   } = options;
   return (async function(...args) {
     let lastError;
+    let prevJitterDelay = 0;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       try {
         return await fn(...args);
@@ -36,8 +86,11 @@ function retry(fn, options = {}) {
         lastError = error instanceof Error ? error : new Error(String(error));
         if (attempt < maxAttempts) {
           const waitTime = calculateDelay(delay, attempt, backoff);
-          onRetry(lastError, attempt, waitTime);
-          await sleep(waitTime);
+          const jitterMs = applyJitter(waitTime, jitterConfig, prevJitterDelay);
+          prevJitterDelay = jitterMs;
+          const delayTimeMs = waitTime + jitterMs;
+          onRetry(lastError, attempt, delayTimeMs);
+          await sleep(delayTimeMs);
         }
       }
     }
@@ -45,35 +98,6 @@ function retry(fn, options = {}) {
   });
 }
 
-// src/jitter.ts
-var jitter_exports = {};
-__export(jitter_exports, {
-  calculateDecorrelatedJitter: () => calculateDecorrelatedJitter,
-  calculateEqualJitter: () => calculateEqualJitter,
-  calculateFixedJitter: () => calculateFixedJitter,
-  calculateFullJitter: () => calculateFullJitter,
-  calculateRandomJitter: () => calculateRandomJitter
-});
-function calculateFullJitter(minDelayMs, maxDelayMs) {
-  return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;
-}
-function calculateEqualJitter(baseDelayMs) {
-  const halfDelay = baseDelayMs / 2;
-  return halfDelay + Math.random() * halfDelay;
-}
-function calculateFixedJitter(maxDelayMs, jitterAmount) {
-  return Math.max(0, maxDelayMs - jitterAmount);
-}
-function calculateRandomJitter(baseDelayMs, jitterFraction) {
-  const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;
-  return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));
-}
-function calculateDecorrelatedJitter(baseDelayMs, maxDelayMs, prevDelayMs = 0) {
-  const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);
-  const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);
-  return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay);
-}
-
 // src/index.ts
 var index_default = {
   retry,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/retry.ts","../src/jitter.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Core retry logic implementation\n */\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nfunction calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number {\n  switch (backoff) {\n    case 'exponential':\n      return baseDelay * Math.pow(2, attempt - 1);\n    case 'linear':\n      return baseDelay * attempt;\n    case 'fixed':\n    default:\n      return baseDelay;\n  }\n}\n\nexport type BackoffStrategy = 'exponential' | 'linear' | 'fixed';\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxAttempts?: number;\n  /** Base delay in milliseconds (default: 1000) */\n  delay?: number;\n  /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Callback called before each retry (error, attempt, waitTime) */\n  onRetry?: (error: Error, attempt: number, waitTime: number) => void;\n}\n\n/**\n * Creates a retry wrapper function\n * @param fn - The async function to retry\n * @param options - Retry configuration\n * @returns A function that wraps the original function with retry logic\n */\n// @typescript-eslint/no-explicit-any\nexport function retry<T extends (...args: unknown[]) => Promise<unknown>>(\n  fn: T,\n  options: RetryOptions = {}\n): T {\n  const {\n    maxAttempts = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    onRetry = () => {}\n  } = options;\n\n  return (async function(...args: Parameters<T>): Promise<ReturnType<T>> {\n    let lastError: Error;\n    \n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      try {\n        return await fn(...args) as ReturnType<T>;\n      } catch (error) {\n        lastError = error instanceof Error ? error : new Error(String(error));\n        \n        if (attempt < maxAttempts) {\n          const waitTime = calculateDelay(delay, attempt, backoff);\n          onRetry(lastError, attempt, waitTime);\n          await sleep(waitTime);\n        }\n      }\n    }\n    \n    throw lastError!;\n  }) as T;\n}\n\nexport { calculateDelay, sleep };\n\n","/**\n * Generates a full‑jitter delay within the given range.\n *\n * Full jitter selects a completely random delay between `minDelay` and\n * `maxDelay`, spreading numbers across the entire interval to create jitter.\n *\n * @param {number} minDelayMs - The minimum delay (inclusive).\n * @param {number} maxDelayMs - The maximum delay (exclusive).\n * @returns {number} A random delay between `minDelay` and `maxDelay`.\n * @description Full jitter is ideal when many clients may retry at the same time and you need to aggressively spread those retries out. It’s especially useful under high contention or bursty failure conditions, where a wide range of random delays helps prevent retry storms and reduces load on downstream services.\n */\nexport function calculateFullJitter(minDelayMs: number, maxDelayMs: number): number {\n    return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;\n}\n\n/**\n * Calculates an equal‑jitter backoff delay.\n *\n * Equal jitter splits the delay into a fixed half and a random half.\n * This reduces synchronization between clients while avoiding the\n * extremely low delays produced by full jitter.\n *\n * @param {number} baseDelayMs - The original backoff delay before jitter.\n * @returns {number} A delay between half of `baseDelay` and the full `baseDelay`.\n * @description Equal jitter is useful when you want a smoother, more predictable retry pattern that still avoids synchronized retries. It guarantees at least half of the base delay while adding randomness to the other half, giving you a balanced backoff that reduces contention without the extreme variability of full jitter.\n */\nexport function calculateEqualJitter(baseDelayMs: number): number {\n    const halfDelay = baseDelayMs / 2;\n    return halfDelay + Math.random() * halfDelay;\n}\n\n\n/**\n * Calculates a fixed‑jitter delay by subtracting a constant amount from the base delay. Unlike random jitter strategies, fixed jitter provides predictable timing while still preventing perfectly aligned retries.\n * Use this when you want a small, consistent desynchronization between clients without introducing randomness — ideal for stable systems where timing consistency matters more than wide jitter distribution.\n * @param {number} maxDelayMs - The original delay before applying jitter.\n * @param {number} jitterAmount - The fixed amount to subtract.\n * @returns {number} The delay after subtracting `jitterAmount`, never below zero.\n */\nexport function calculateFixedJitter(maxDelayMs: number, jitterAmount: number): number {\n    return Math.max(0, maxDelayMs - jitterAmount);\n}\n\n/**\n * Calculates a random‑jitter backoff delay by applying a symmetric\n * random variation around the base delay. The jitter fraction determines\n * how far the delay may swing above or below the original value.\n *\n * Random jitter is useful when you want to “wiggle” the delay without\n * dramatically changing its overall shape. It provides light\n * desynchronization between clients while keeping the delay centered\n * around the base value — ideal for systems that need some variability\n * but not the wide spread of full jitter.\n *\n * @param {number} baseDelayMs - The original delay before jitter is applied.\n * @param {number} jitterFraction - Maximum fractional deviation (e.g., 0.2 for ±20%).\n * @returns {number} A jittered delay, clamped to zero if the calculation goes negative.\n */\nexport function calculateRandomJitter(baseDelayMs: number, jitterFraction: number): number {\n    // Math.random() gives us 0 to 1 so multiply by 2 and subtract 1 to get -1 to 1 range\n    const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;\n    return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));\n}\n\n/**\n * Calculates a decorrelated jitter backoff delay using the algorithm\n * popularized by AWS. Each retry delay is chosen randomly between the\n * base delay and three times the previous delay, then capped at the\n * maximum allowed delay. This prevents synchronized retry spikes and\n * produces a smooth, adaptive backoff pattern.\n *\n * Use this when you need highly desynchronized retries across many\n * clients—especially in distributed systems or high‑traffic services\n * where coordinated retry storms can overwhelm downstream resources.\n *\n * AWS reference:\n * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/\n *\n * @param {number} baseDelayMs - The minimum delay for any retry attempt.\n * @param {number} maxDelayMs - The maximum allowed delay.\n * @param {number} [prevDelayMs=0] - The delay used for the previous retry.\n * @returns {number} A jittered delay capped at `maxDelayMs`.\n */\nexport function calculateDecorrelatedJitter(baseDelayMs: number, maxDelayMs: number, prevDelayMs: number = 0): number {\n    const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);\n    const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);\n    return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay)\n}","/**\n * Jitterbug - A lightweight library for building reliable retry behavior\n */\n\nexport { retry, calculateDelay, sleep, type RetryOptions, type BackoffStrategy } from './retry';\n\nimport * as jitterFunctions from './jitter';\nimport { retry } from './retry';\n\nexport default {\n  retry,\n  ...jitterFunctions\n};\n"]}
+{"version":3,"sources":["../src/jitter.ts","../src/retry.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Generates a full‑jitter delay within the given range.\n *\n * Full jitter selects a completely random delay between `minDelay` and\n * `maxDelay`, spreading numbers across the entire interval to create jitter.\n *\n * @param {number} minDelayMs - The minimum delay (inclusive).\n * @param {number} maxDelayMs - The maximum delay (exclusive).\n * @returns {number} A random delay between `minDelay` and `maxDelay`.\n * @description Full jitter is ideal when many clients may retry at the same time and you need to aggressively spread those retries out. It’s especially useful under high contention or bursty failure conditions, where a wide range of random delays helps prevent retry storms and reduces load on downstream services.\n */\nexport function calculateFullJitter(minDelayMs: number, maxDelayMs: number): number {\n    return Math.random() * (maxDelayMs - minDelayMs) + minDelayMs;\n}\n\n/**\n * Calculates an equal‑jitter backoff delay.\n *\n * Equal jitter splits the delay into a fixed half and a random half.\n * This reduces synchronization between clients while avoiding the\n * extremely low delays produced by full jitter.\n *\n * @param {number} baseDelayMs - The original backoff delay before jitter.\n * @returns {number} A delay between half of `baseDelay` and the full `baseDelay`.\n * @description Equal jitter is useful when you want a smoother, more predictable retry pattern that still avoids synchronized retries. It guarantees at least half of the base delay while adding randomness to the other half, giving you a balanced backoff that reduces contention without the extreme variability of full jitter.\n */\nexport function calculateEqualJitter(baseDelayMs: number): number {\n    const halfDelay = baseDelayMs / 2;\n    return halfDelay + Math.random() * halfDelay;\n}\n\n/**\n * Calculates a fixed‑jitter delay by subtracting a constant amount from the base delay. Unlike random jitter strategies, fixed jitter provides predictable timing while still preventing perfectly aligned retries.\n * Use this when you want a small, consistent desynchronization between clients without introducing randomness — ideal for stable systems where timing consistency matters more than wide jitter distribution.\n * @param {number} maxDelayMs - The original delay before applying jitter.\n * @param {number} jitterAmount - The fixed amount to subtract.\n * @returns {number} The delay after subtracting `jitterAmount`, never below zero.\n */\nexport function calculateFixedJitter(maxDelayMs: number, jitterAmount: number): number {\n    return Math.max(0, maxDelayMs - jitterAmount);\n}\n\n/**\n * Calculates a random‑jitter backoff delay by applying a symmetric\n * random variation around the base delay. The jitter fraction determines\n * how far the delay may swing above or below the original value.\n *\n * Random jitter is useful when you want to “wiggle” the delay without\n * dramatically changing its overall shape. It provides light\n * desynchronization between clients while keeping the delay centered\n * around the base value — ideal for systems that need some variability\n * but not the wide spread of full jitter.\n *\n * @param {number} baseDelayMs - The original delay before jitter is applied.\n * @param {number} jitterFraction - Maximum fractional deviation (e.g., 0.2 for ±20%).\n * @returns {number} A jittered delay, clamped to zero if the calculation goes negative.\n */\nexport function calculateRandomJitter(baseDelayMs: number, jitterFraction: number): number {\n    // Math.random() gives us 0 to 1 so multiply by 2 and subtract 1 to get -1 to 1 range\n    const randomNumberBetweenJitterFraction = (Math.random() * 2 - 1) * jitterFraction;\n    return Math.max(0, baseDelayMs * (1 + randomNumberBetweenJitterFraction));\n}\n\n/**\n * Calculates a decorrelated jitter backoff delay using the algorithm\n * popularized by AWS. Each retry delay is chosen randomly between the\n * base delay and three times the previous delay, then capped at the\n * maximum allowed delay. This prevents synchronized retry spikes and\n * produces a smooth, adaptive backoff pattern.\n *\n * Use this when you need highly desynchronized retries across many\n * clients—especially in distributed systems or high‑traffic services\n * where coordinated retry storms can overwhelm downstream resources.\n *\n * AWS reference:\n * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/\n *\n * @param {number} baseDelayMs - The minimum delay for any retry attempt.\n * @param {number} maxDelayMs - The maximum allowed delay.\n * @param {number} [prevDelayMs=0] - The delay used for the previous retry.\n * @returns {number} A jittered delay capped at `maxDelayMs`.\n */\nexport function calculateDecorrelatedJitter(baseDelayMs: number, maxDelayMs: number, prevDelayMs: number = 0): number {\n    const upperDelayMs = Math.max(baseDelayMs, prevDelayMs * 3);\n    const randomValueBetweenBaseDelayAnd3xPrevoiusDelay = baseDelayMs + Math.random() * (upperDelayMs - baseDelayMs);\n    return Math.min(maxDelayMs, randomValueBetweenBaseDelayAnd3xPrevoiusDelay)\n}","/**\n * Core retry logic implementation\n */\n\nimport { calculateDecorrelatedJitter, calculateEqualJitter, calculateFixedJitter, calculateFullJitter, calculateRandomJitter } from \"./jitter\";\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nexport type BackoffStrategy = 'exponential' | 'linear' | 'fixed';\nfunction calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number {\n  switch (backoff) {\n    case 'exponential':\n      return baseDelay * Math.pow(2, attempt - 1);\n    case 'linear':\n      return baseDelay * attempt;\n    case 'fixed':\n    default:\n      return baseDelay;\n  }\n}\n\nexport type JitterConfig =\n  | { type: 'none' }\n  | { type: 'equal' }\n  | { type: 'full', min: number, max: number }\n  | { type: 'fixed', amount: number }\n  | { type: 'random', fraction: number }\n  | { type: 'decorrelated', maxDelay: number };\n\n  function applyJitter(\n    baseDelay: number,\n    jitter: JitterConfig | undefined,\n    prevDelay: number\n  ): number {\n    if (!jitter || jitter.type === 'none') return 0;\n  \n    switch (jitter.type) {\n      case 'equal':\n        return calculateEqualJitter(baseDelay);\n  \n      case 'full':\n        return calculateFullJitter(jitter.min, jitter.max);\n  \n      case 'fixed':\n        return calculateFixedJitter(baseDelay, jitter.amount);\n  \n      case 'random':\n        return calculateRandomJitter(baseDelay, jitter.fraction);\n  \n      case 'decorrelated':\n        return calculateDecorrelatedJitter(\n          baseDelay,\n          jitter.maxDelay,\n          prevDelay\n        );\n    }\n  }\n  \n\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxAttempts?: number;\n  /** Base delay in milliseconds (default: 1000) */\n  delay?: number;\n  /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Callback called before each retry (error, attempt, waitTime) */\n  onRetry?: (error: Error, attempt: number, waitTime: number) => void;\n  /** Jitter settings */\n  jitterConfig?: JitterConfig\n}\n\n/**\n * @param fn - The async function to retry\n * @param options - Retry configuration\n * @returns A function that wraps the original function with retry logic\n */\n// @typescript-eslint/no-explicit-any\nexport function retry<T extends (...args: unknown[]) => Promise<unknown>>(\n  fn: T,\n  options: RetryOptions = {}\n): T {\n  const {\n    maxAttempts = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    jitterConfig,\n    onRetry = () => {}\n  } = options;\n\n  return (async function(...args: Parameters<T>): Promise<ReturnType<T>> {\n    let lastError: Error;\n    \n    let prevJitterDelay = 0;\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      try {\n        return await fn(...args) as ReturnType<T>;\n      } catch (error) {\n        lastError = error instanceof Error ? error : new Error(String(error));\n        \n        if (attempt < maxAttempts) {\n          const waitTime = calculateDelay(delay, attempt, backoff);\n          const jitterMs = applyJitter(waitTime, jitterConfig, prevJitterDelay)\n          prevJitterDelay = jitterMs;\n          const delayTimeMs = waitTime + jitterMs;\n          onRetry(lastError, attempt, delayTimeMs);\n          await sleep(delayTimeMs);\n        }\n      }\n    }\n    \n    throw lastError!;\n  }) as T;\n}\n\nexport { calculateDelay, sleep, applyJitter };\n\n","/**\n * Jitterbug - A lightweight library for building reliable retry behavior\n */\n\nexport { retry, calculateDelay, sleep, type RetryOptions, type BackoffStrategy } from './retry';\n\nimport * as jitterFunctions from './jitter';\nimport { retry } from './retry';\n\nexport default {\n  retry,\n  ...jitterFunctions\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jitterbug",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.6",
   "description": "A lightweight library for building reliable retry behavior in distributed systems and API clients",
   "main": "./dist/index.js",
   "module": "./dist/index.js",