@zap-studio/retry 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0]
+
+### Added
+
+`exponentialBackoff(...)` and `linearBackoff(...)` gain an optional `jitter?: "full" | "equal" | JitterOptions` option, applied to the computed delay after it's capped at `maxDelayMs`. `"full"` randomizes across `[0, delayMs]`; `"equal"` keeps a floor at half the delay, randomizing across `[delayMs/2, delayMs]`. Pass `{ mode, random }` to override the random source, useful for deterministic tests.
+
+New export: `applyJitter(delayMs, jitter?)`, also available from the `./jitter` subpath. See [Jitter](https://www.zapstudio.dev/retry/jitter).
+
 ## [1.0.0]
 
 ### Added

package/README.md

@@ -13,6 +13,7 @@ npm install @zap-studio/retry
 ## Features
 
 - **Built-in policies**: `fixedDelay(...)`, `linearBackoff(...)`, and `exponentialBackoff(...)`.
+- **Jitter**: `"full"` or `"equal"` jitter on `exponentialBackoff`/`linearBackoff`, to avoid synchronized retries against a shared upstream.
 - **A shared runner** via `runRetryPolicy(policy, execute, options?)` with attempt-aware callbacks and custom sleep injection.
 - **Structured terminal errors**: `RetryError` on exhaustion, `AbortError` on cancellation.
 - **Non-throw mode** (`throwOnExhausted: false`) returns a `RetryRunResult` instead of throwing.
@@ -65,6 +66,19 @@ const linear = linearBackoff({
 const fixed = fixedDelay({ maxAttempts: 4, delayMs: 300 });
 ```
 
+## Jitter
+
+`"full"` or `"equal"` jitter on `exponentialBackoff`/`linearBackoff`, applied to the delay after it's capped, to avoid synchronized retries against a shared upstream.
+
+```ts
+const policy = exponentialBackoff({
+  maxAttempts: 5,
+  baseDelayMs: 100,
+  maxDelayMs: 2_000,
+  jitter: "full",
+});
+```
+
 ## Shared Runner
 
 Via `runRetryPolicy(policy, execute, options?)` with attempt-aware callbacks and custom sleep injection.

package/dist/exponential-backoff.d.ts

@@ -1,4 +1,5 @@
 import { RetryPolicy } from "./types.js";
+import { JitterMode, JitterOptions } from "./jitter.js";
 //#region src/exponential-backoff.d.ts
 /**
  * Configuration for `exponentialBackoff(...)`.
@@ -8,6 +9,7 @@ import { RetryPolicy } from "./types.js";
  *   maxAttempts: 5,
  *   baseDelayMs: 100,
  *   maxDelayMs: 2_000,
+ *   jitter: "full",
  * };
  */
 interface ExponentialBackoffOptions {
@@ -23,6 +25,11 @@ interface ExponentialBackoffOptions {
    * Hard upper bound in milliseconds for computed exponential delay.
    */
   maxDelayMs: number;
+  /**
+   * Optional jitter applied to the computed delay, after capping at
+   * `maxDelayMs`.
+   */
+  jitter?: JitterMode | JitterOptions;
 }
 /**
  * Creates a retry policy with exponential delay growth up to a max cap.

package/dist/exponential-backoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exponential-backoff.d.ts","names":[],"sources":["../src/exponential-backoff.ts"],"mappings":";;;;;;;;;;;;UAsBiB;;;;EAIf;;;;EAIA;;;;EAIA;;;;;;;;;;;;cAaW,qBACX,SAAS,8BACR"}
+{"version":3,"file":"exponential-backoff.d.ts","names":[],"sources":["../src/exponential-backoff.ts"],"mappings":";;;;;;;;;;;;;;UAyBiB;;;;EAIf;;;;EAIA;;;;EAIA;;;;;EAKA,SAAS,aAAa;;;;;;;;;;;;cAaX,qBACX,SAAS,8BACR"}

package/dist/exponential-backoff.js

@@ -1,5 +1,11 @@
+import { applyJitter } from "./jitter.js";
 //#region src/exponential-backoff.ts
 /**
+* Exponential backoff retry strategy.
+*
+* @module @zap-studio/retry/exponential-backoff
+*/
+/**
 * Creates a retry policy with exponential delay growth up to a max cap.
 *
 * @example
@@ -10,7 +16,7 @@
 * });
 */
 const exponentialBackoff = (options) => {
-	const { maxAttempts, baseDelayMs, maxDelayMs } = options;
+	const { maxAttempts, baseDelayMs, maxDelayMs, jitter } = options;
 	return { 
 	/**
 	* Computes retry decision for the current attempt.
@@ -22,8 +28,9 @@ next(input) {
 			shouldRetry: false
 		};
 		const exponent = Math.max(0, input.attempt - 1);
+		const cappedDelayMs = Math.min(maxDelayMs, baseDelayMs * 2 ** exponent);
 		return {
-			delayMs: Math.min(maxDelayMs, baseDelayMs * 2 ** exponent),
+			delayMs: applyJitter(cappedDelayMs, jitter),
 			reason: "retry",
 			shouldRetry: true
 		};

package/dist/exponential-backoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"exponential-backoff.js","names":[],"sources":["../src/exponential-backoff.ts"],"sourcesContent":["/**\n * Exponential backoff retry strategy.\n *\n * @module @zap-studio/retry/exponential-backoff\n */\n\nimport type {\n  RetryDecision,\n  RetryDecisionInput,\n  RetryPolicy,\n} from \"./types.js\";\n\n/**\n * Configuration for `exponentialBackoff(...)`.\n *\n * @example\n * const options: ExponentialBackoffOptions = {\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   maxDelayMs: 2_000,\n * };\n */\nexport interface ExponentialBackoffOptions {\n  /**\n   * Maximum number of attempts (including the first) before giving up.\n   */\n  maxAttempts: number;\n  /**\n   * Initial delay in milliseconds, doubled each retry until capped.\n   */\n  baseDelayMs: number;\n  /**\n   * Hard upper bound in milliseconds for computed exponential delay.\n   */\n  maxDelayMs: number;\n}\n\n/**\n * Creates a retry policy with exponential delay growth up to a max cap.\n *\n * @example\n * const policy = exponentialBackoff({\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   maxDelayMs: 2_000,\n * });\n */\nexport const exponentialBackoff = (\n  options: ExponentialBackoffOptions\n): RetryPolicy => {\n  const { maxAttempts, baseDelayMs, maxDelayMs } = options;\n\n  return {\n    /**\n     * Computes retry decision for the current attempt.\n     */\n    next(input: RetryDecisionInput): RetryDecision {\n      if (input.attempt >= maxAttempts) {\n        return {\n          delayMs: 0,\n          reason: \"max-attempts-reached\",\n          shouldRetry: false,\n        };\n      }\n\n      const exponent = Math.max(0, input.attempt - 1);\n      const delayMs = Math.min(maxDelayMs, baseDelayMs * 2 ** exponent);\n\n      return { delayMs, reason: \"retry\", shouldRetry: true };\n    },\n  };\n};\n"],"mappings":";;;;;;;;;;;AA+CA,MAAa,sBACX,YACgB;CAChB,MAAM,EAAE,aAAa,aAAa,eAAe;CAEjD,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;EAGF,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,UAAU,CAAC;EAG9C,OAAO;GAAE,SAFO,KAAK,IAAI,YAAY,cAAc,KAAK,QAEzC;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}
+{"version":3,"file":"exponential-backoff.js","names":[],"sources":["../src/exponential-backoff.ts"],"sourcesContent":["/**\n * Exponential backoff retry strategy.\n *\n * @module @zap-studio/retry/exponential-backoff\n */\n\nimport { applyJitter } from \"./jitter.js\";\nimport type { JitterMode, JitterOptions } from \"./jitter.js\";\nimport type {\n  RetryDecision,\n  RetryDecisionInput,\n  RetryPolicy,\n} from \"./types.js\";\n\n/**\n * Configuration for `exponentialBackoff(...)`.\n *\n * @example\n * const options: ExponentialBackoffOptions = {\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   maxDelayMs: 2_000,\n *   jitter: \"full\",\n * };\n */\nexport interface ExponentialBackoffOptions {\n  /**\n   * Maximum number of attempts (including the first) before giving up.\n   */\n  maxAttempts: number;\n  /**\n   * Initial delay in milliseconds, doubled each retry until capped.\n   */\n  baseDelayMs: number;\n  /**\n   * Hard upper bound in milliseconds for computed exponential delay.\n   */\n  maxDelayMs: number;\n  /**\n   * Optional jitter applied to the computed delay, after capping at\n   * `maxDelayMs`.\n   */\n  jitter?: JitterMode | JitterOptions;\n}\n\n/**\n * Creates a retry policy with exponential delay growth up to a max cap.\n *\n * @example\n * const policy = exponentialBackoff({\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   maxDelayMs: 2_000,\n * });\n */\nexport const exponentialBackoff = (\n  options: ExponentialBackoffOptions\n): RetryPolicy => {\n  const { maxAttempts, baseDelayMs, maxDelayMs, jitter } = options;\n\n  return {\n    /**\n     * Computes retry decision for the current attempt.\n     */\n    next(input: RetryDecisionInput): RetryDecision {\n      if (input.attempt >= maxAttempts) {\n        return {\n          delayMs: 0,\n          reason: \"max-attempts-reached\",\n          shouldRetry: false,\n        };\n      }\n\n      const exponent = Math.max(0, input.attempt - 1);\n      const cappedDelayMs = Math.min(maxDelayMs, baseDelayMs * 2 ** exponent);\n      const delayMs = applyJitter(cappedDelayMs, jitter);\n\n      return { delayMs, reason: \"retry\", shouldRetry: true };\n    },\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAuDA,MAAa,sBACX,YACgB;CAChB,MAAM,EAAE,aAAa,aAAa,YAAY,WAAW;CAEzD,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;EAGF,MAAM,WAAW,KAAK,IAAI,GAAG,MAAM,UAAU,CAAC;EAC9C,MAAM,gBAAgB,KAAK,IAAI,YAAY,cAAc,KAAK,QAAQ;EAGtE,OAAO;GAAE,SAFO,YAAY,eAAe,MAE5B;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { i as RetryErrorContext, n as AbortErrorContext, r as RetryError, t as AbortError } from "./errors-CS5UPJWs.js";
 import { RetryDecision, RetryDecisionInput, RetryExhaustedInput, RetryPolicy, RetryRunOptions, RetryRunResult } from "./types.js";
 import { defaultSleep, runRetryPolicy } from "./base-policy.js";
+import { JitterMode, JitterOptions, applyJitter } from "./jitter.js";
 import { ExponentialBackoffOptions, exponentialBackoff } from "./exponential-backoff.js";
 import { FixedDelayOptions, fixedDelay } from "./fixed-delay.js";
 import { LinearBackoffOptions, linearBackoff } from "./linear-backoff.js";
-export { AbortError, type AbortErrorContext, type ExponentialBackoffOptions, type FixedDelayOptions, type LinearBackoffOptions, type RetryDecision, type RetryDecisionInput, RetryError, type RetryErrorContext, type RetryExhaustedInput, type RetryPolicy, type RetryRunOptions, type RetryRunResult, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };
+export { AbortError, type AbortErrorContext, type ExponentialBackoffOptions, type FixedDelayOptions, type JitterMode, type JitterOptions, type LinearBackoffOptions, type RetryDecision, type RetryDecisionInput, RetryError, type RetryErrorContext, type RetryExhaustedInput, type RetryPolicy, type RetryRunOptions, type RetryRunResult, applyJitter, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { AbortError, RetryError } from "./errors.js";
 import { defaultSleep, runRetryPolicy } from "./base-policy.js";
+import { applyJitter } from "./jitter.js";
 import { exponentialBackoff } from "./exponential-backoff.js";
 import { fixedDelay } from "./fixed-delay.js";
 import { linearBackoff } from "./linear-backoff.js";
-export { AbortError, RetryError, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };
+export { AbortError, RetryError, applyJitter, defaultSleep, exponentialBackoff, fixedDelay, linearBackoff, runRetryPolicy };

package/dist/jitter.d.ts

@@ -0,0 +1,48 @@
+//#region src/jitter.d.ts
+/**
+ * Jitter strategies applied to a computed backoff delay.
+ *
+ * @module @zap-studio/retry/jitter
+ */
+/**
+ * Supported jitter strategies.
+ *
+ * - `"full"`: `random(0, delayMs)` — max spread, best thundering-herd
+ *   protection.
+ * - `"equal"`: `delayMs/2 + random(0, delayMs/2)` — keeps a floor at half
+ *   the computed delay, less spread than full jitter.
+ */
+type JitterMode = "equal" | "full";
+/**
+ * Configuration for jitter application.
+ *
+ * @example
+ * const jitter: JitterOptions = { mode: "full" };
+ */
+interface JitterOptions {
+  /**
+   * Jitter strategy to apply.
+   */
+  mode: JitterMode;
+  /**
+   * Random source in `[0, 1)`, overridable for deterministic tests.
+   *
+   * @default Math.random
+   */
+  random?: () => number;
+}
+/**
+ * Applies a jitter strategy to a computed delay.
+ *
+ * @param delayMs - Delay in milliseconds before jitter.
+ * @param jitter - Jitter mode shorthand, full `JitterOptions`, or `undefined`
+ *   to leave `delayMs` untouched.
+ * @returns Jittered delay in milliseconds, rounded to the nearest integer.
+ *
+ * @example
+ * const delayMs = applyJitter(1000, "full"); // 0-1000
+ */
+declare const applyJitter: (delayMs: number, jitter?: JitterMode | JitterOptions) => number;
+//#endregion
+export { JitterMode, JitterOptions, applyJitter };
+//# sourceMappingURL=jitter.d.ts.map

package/dist/jitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitter.d.ts","names":[],"sources":["../src/jitter.ts"],"mappings":";;;;;;;;;;;;;;KAcY;;;;;;;UAQK;;;;EAIf,MAAM;;;;;;EAMN;;;;;;;;;;;;;cAcW,cACX,iBACA,SAAS,aAAa"}

package/dist/jitter.js

@@ -0,0 +1,24 @@
+//#region src/jitter.ts
+/**
+* Applies a jitter strategy to a computed delay.
+*
+* @param delayMs - Delay in milliseconds before jitter.
+* @param jitter - Jitter mode shorthand, full `JitterOptions`, or `undefined`
+*   to leave `delayMs` untouched.
+* @returns Jittered delay in milliseconds, rounded to the nearest integer.
+*
+* @example
+* const delayMs = applyJitter(1000, "full"); // 0-1000
+*/
+const applyJitter = (delayMs, jitter) => {
+	if (jitter === void 0) return delayMs;
+	const mode = typeof jitter === "string" ? jitter : jitter.mode;
+	const random = (typeof jitter === "string" ? void 0 : jitter.random) ?? Math.random;
+	if (mode === "full") return Math.round(random() * delayMs);
+	const half = delayMs / 2;
+	return Math.round(half + random() * half);
+};
+//#endregion
+export { applyJitter };
+
+//# sourceMappingURL=jitter.js.map

package/dist/jitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitter.js","names":[],"sources":["../src/jitter.ts"],"sourcesContent":["/**\n * Jitter strategies applied to a computed backoff delay.\n *\n * @module @zap-studio/retry/jitter\n */\n\n/**\n * Supported jitter strategies.\n *\n * - `\"full\"`: `random(0, delayMs)` — max spread, best thundering-herd\n *   protection.\n * - `\"equal\"`: `delayMs/2 + random(0, delayMs/2)` — keeps a floor at half\n *   the computed delay, less spread than full jitter.\n */\nexport type JitterMode = \"equal\" | \"full\";\n\n/**\n * Configuration for jitter application.\n *\n * @example\n * const jitter: JitterOptions = { mode: \"full\" };\n */\nexport interface JitterOptions {\n  /**\n   * Jitter strategy to apply.\n   */\n  mode: JitterMode;\n  /**\n   * Random source in `[0, 1)`, overridable for deterministic tests.\n   *\n   * @default Math.random\n   */\n  random?: () => number;\n}\n\n/**\n * Applies a jitter strategy to a computed delay.\n *\n * @param delayMs - Delay in milliseconds before jitter.\n * @param jitter - Jitter mode shorthand, full `JitterOptions`, or `undefined`\n *   to leave `delayMs` untouched.\n * @returns Jittered delay in milliseconds, rounded to the nearest integer.\n *\n * @example\n * const delayMs = applyJitter(1000, \"full\"); // 0-1000\n */\nexport const applyJitter = (\n  delayMs: number,\n  jitter?: JitterMode | JitterOptions\n): number => {\n  if (jitter === undefined) {\n    return delayMs;\n  }\n\n  const mode = typeof jitter === \"string\" ? jitter : jitter.mode;\n  const random =\n    (typeof jitter === \"string\" ? undefined : jitter.random) ?? Math.random;\n\n  if (mode === \"full\") {\n    return Math.round(random() * delayMs);\n  }\n\n  const half = delayMs / 2;\n  return Math.round(half + random() * half);\n};\n"],"mappings":";;;;;;;;;;;;AA8CA,MAAa,eACX,SACA,WACW;CACX,IAAI,WAAW,KAAA,GACb,OAAO;CAGT,MAAM,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO;CAC1D,MAAM,UACH,OAAO,WAAW,WAAW,KAAA,IAAY,OAAO,WAAW,KAAK;CAEnE,IAAI,SAAS,QACX,OAAO,KAAK,MAAM,OAAO,IAAI,OAAO;CAGtC,MAAM,OAAO,UAAU;CACvB,OAAO,KAAK,MAAM,OAAO,OAAO,IAAI,IAAI;AAC1C"}

package/dist/linear-backoff.d.ts

@@ -1,4 +1,5 @@
 import { RetryPolicy } from "./types.js";
+import { JitterMode, JitterOptions } from "./jitter.js";
 //#region src/linear-backoff.d.ts
 /**
  * Configuration for `linearBackoff(...)`.
@@ -9,6 +10,7 @@ import { RetryPolicy } from "./types.js";
  *   baseDelayMs: 100,
  *   incrementMs: 100,
  *   maxDelayMs: 2_000,
+ *   jitter: "equal",
  * };
  */
 interface LinearBackoffOptions {
@@ -28,6 +30,11 @@ interface LinearBackoffOptions {
    * Hard upper bound in milliseconds for computed linear delay.
    */
   maxDelayMs: number;
+  /**
+   * Optional jitter applied to the computed delay, after capping at
+   * `maxDelayMs`.
+   */
+  jitter?: JitterMode | JitterOptions;
 }
 /**
  * Creates a retry policy with linear delay growth up to a max cap.

package/dist/linear-backoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linear-backoff.d.ts","names":[],"sources":["../src/linear-backoff.ts"],"mappings":";;;;;;;;;;;;;UAuBiB;;;;EAIf;;;;EAIA;;;;EAIA;;;;EAIA;;;;;;;;;;;;;cAcW,gBAAiB,SAAS,yBAAuB"}
+{"version":3,"file":"linear-backoff.d.ts","names":[],"sources":["../src/linear-backoff.ts"],"mappings":";;;;;;;;;;;;;;;UA0BiB;;;;EAIf;;;;EAIA;;;;EAIA;;;;EAIA;;;;;EAKA,SAAS,aAAa;;;;;;;;;;;;;cAcX,gBAAiB,SAAS,yBAAuB"}

package/dist/linear-backoff.js

@@ -1,5 +1,11 @@
+import { applyJitter } from "./jitter.js";
 //#region src/linear-backoff.ts
 /**
+* Linear backoff retry strategy.
+*
+* @module @zap-studio/retry/linear-backoff
+*/
+/**
 * Creates a retry policy with linear delay growth up to a max cap.
 *
 * @example
@@ -11,7 +17,7 @@
 * });
 */
 const linearBackoff = (options) => {
-	const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs } = options;
+	const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs, jitter } = options;
 	return { 
 	/**
 	* Computes retry decision for the current attempt.
@@ -22,8 +28,9 @@ next(input) {
 			reason: "max-attempts-reached",
 			shouldRetry: false
 		};
+		const cappedDelayMs = Math.min(maxDelayMs, baseDelayMs + incrementMs * (input.attempt - 1));
 		return {
-			delayMs: Math.min(maxDelayMs, baseDelayMs + incrementMs * (input.attempt - 1)),
+			delayMs: applyJitter(cappedDelayMs, jitter),
 			reason: "retry",
 			shouldRetry: true
 		};

package/dist/linear-backoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"linear-backoff.js","names":[],"sources":["../src/linear-backoff.ts"],"sourcesContent":["/**\n * Linear backoff retry strategy.\n *\n * @module @zap-studio/retry/linear-backoff\n */\n\nimport type {\n  RetryDecision,\n  RetryDecisionInput,\n  RetryPolicy,\n} from \"./types.js\";\n\n/**\n * Configuration for `linearBackoff(...)`.\n *\n * @example\n * const options: LinearBackoffOptions = {\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   incrementMs: 100,\n *   maxDelayMs: 2_000,\n * };\n */\nexport interface LinearBackoffOptions {\n  /**\n   * Maximum number of attempts (including the first) before giving up.\n   */\n  maxAttempts: number;\n  /**\n   * Delay in milliseconds after the first failed attempt.\n   */\n  baseDelayMs: number;\n  /**\n   * Amount added to the delay for each subsequent retry.\n   */\n  incrementMs: number;\n  /**\n   * Hard upper bound in milliseconds for computed linear delay.\n   */\n  maxDelayMs: number;\n}\n\n/**\n * Creates a retry policy with linear delay growth up to a max cap.\n *\n * @example\n * const policy = linearBackoff({\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   incrementMs: 100,\n *   maxDelayMs: 2_000,\n * });\n */\nexport const linearBackoff = (options: LinearBackoffOptions): RetryPolicy => {\n  const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs } = options;\n\n  return {\n    /**\n     * Computes retry decision for the current attempt.\n     */\n    next(input: RetryDecisionInput): RetryDecision {\n      if (input.attempt >= maxAttempts) {\n        return {\n          delayMs: 0,\n          reason: \"max-attempts-reached\",\n          shouldRetry: false,\n        };\n      }\n\n      const delayMs = Math.min(\n        maxDelayMs,\n        baseDelayMs + incrementMs * (input.attempt - 1)\n      );\n\n      return { delayMs, reason: \"retry\", shouldRetry: true };\n    },\n  };\n};\n"],"mappings":";;;;;;;;;;;;AAqDA,MAAa,iBAAiB,YAA+C;CAC3E,MAAM,EAAE,aAAa,aAAa,aAAa,eAAe;CAE9D,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;EAQF,OAAO;GAAE,SALO,KAAK,IACnB,YACA,cAAc,eAAe,MAAM,UAAU,EAGhC;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}
+{"version":3,"file":"linear-backoff.js","names":[],"sources":["../src/linear-backoff.ts"],"sourcesContent":["/**\n * Linear backoff retry strategy.\n *\n * @module @zap-studio/retry/linear-backoff\n */\n\nimport { applyJitter } from \"./jitter.js\";\nimport type { JitterMode, JitterOptions } from \"./jitter.js\";\nimport type {\n  RetryDecision,\n  RetryDecisionInput,\n  RetryPolicy,\n} from \"./types.js\";\n\n/**\n * Configuration for `linearBackoff(...)`.\n *\n * @example\n * const options: LinearBackoffOptions = {\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   incrementMs: 100,\n *   maxDelayMs: 2_000,\n *   jitter: \"equal\",\n * };\n */\nexport interface LinearBackoffOptions {\n  /**\n   * Maximum number of attempts (including the first) before giving up.\n   */\n  maxAttempts: number;\n  /**\n   * Delay in milliseconds after the first failed attempt.\n   */\n  baseDelayMs: number;\n  /**\n   * Amount added to the delay for each subsequent retry.\n   */\n  incrementMs: number;\n  /**\n   * Hard upper bound in milliseconds for computed linear delay.\n   */\n  maxDelayMs: number;\n  /**\n   * Optional jitter applied to the computed delay, after capping at\n   * `maxDelayMs`.\n   */\n  jitter?: JitterMode | JitterOptions;\n}\n\n/**\n * Creates a retry policy with linear delay growth up to a max cap.\n *\n * @example\n * const policy = linearBackoff({\n *   maxAttempts: 5,\n *   baseDelayMs: 100,\n *   incrementMs: 100,\n *   maxDelayMs: 2_000,\n * });\n */\nexport const linearBackoff = (options: LinearBackoffOptions): RetryPolicy => {\n  const { maxAttempts, baseDelayMs, incrementMs, maxDelayMs, jitter } = options;\n\n  return {\n    /**\n     * Computes retry decision for the current attempt.\n     */\n    next(input: RetryDecisionInput): RetryDecision {\n      if (input.attempt >= maxAttempts) {\n        return {\n          delayMs: 0,\n          reason: \"max-attempts-reached\",\n          shouldRetry: false,\n        };\n      }\n\n      const cappedDelayMs = Math.min(\n        maxDelayMs,\n        baseDelayMs + incrementMs * (input.attempt - 1)\n      );\n      const delayMs = applyJitter(cappedDelayMs, jitter);\n\n      return { delayMs, reason: \"retry\", shouldRetry: true };\n    },\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6DA,MAAa,iBAAiB,YAA+C;CAC3E,MAAM,EAAE,aAAa,aAAa,aAAa,YAAY,WAAW;CAEtE,OAAO;;;;AAIL,KAAK,OAA0C;EAC7C,IAAI,MAAM,WAAW,aACnB,OAAO;GACL,SAAS;GACT,QAAQ;GACR,aAAa;EACf;EAGF,MAAM,gBAAgB,KAAK,IACzB,YACA,cAAc,eAAe,MAAM,UAAU,EAC/C;EAGA,OAAO;GAAE,SAFO,YAAY,eAAe,MAE5B;GAAG,QAAQ;GAAS,aAAa;EAAK;CACvD,EACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/retry",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "private": false,
   "description": "Composable, tree-shakeable retry policies for resilient async operations.",
   "keywords": [
@@ -35,6 +35,7 @@
     "./errors": "./dist/errors.js",
     "./exponential-backoff": "./dist/exponential-backoff.js",
     "./fixed-delay": "./dist/fixed-delay.js",
+    "./jitter": "./dist/jitter.js",
     "./linear-backoff": "./dist/linear-backoff.js",
     "./types": "./dist/types.js",
     "./package.json": "./package.json"