@zap-studio/retry 0.2.0 → 0.3.1

package/dist/throw-mode.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throw-mode.d.mts","names":[],"sources":["../src/throw-mode.ts"],"mappings":";;;;;;;;;;;;;;;;;cAyBa,eAAsB,GAAG,QAAQ,OAC5C,QAAQ,YAAY,QAAQ,QAC5B,UAAU,oBAAoB,QAAQ,IACtC,QAAQ,oBAAoB,eAC5B,SAAS,gBACR,QAAQ"}

package/dist/throw-mode.mjs

@@ -0,0 +1,49 @@
+import { sleepWithAbortSignal, throwIfAborted } from "./abort.mjs";
+//#region src/throw-mode.ts
+/**
+* Throw-mode execution path for `BaseRetryPolicy.run` (default when
+* `throwOnExhausted` is not `false`).
+*
+* @module @zap-studio/retry/throw-mode
+*/
+/**
+* Runs the throw-mode retry loop: throws `RetryError` on exhaustion and
+* `AbortError` when `signal` aborts.
+*
+* @param policy - Object providing `next` and `onExhausted` (same contract as
+*   `BaseRetryPolicy`).
+* @param execute - Async work callback per attempt.
+* @param sleep - Delay function between retries.
+* @param signal - Optional cancel signal.
+* @returns Resolves to the first successful return value.
+* @throws {RetryError} When retries are exhausted and `onExhausted` returns
+*   the terminal error.
+* @throws {AbortError} When `signal` is already aborted or aborts while waiting.
+* @throws {Error} Any error thrown by `next`, `onExhausted`, or `sleep`.
+*/
+const runThrowMode = async (policy, execute, sleep, signal) => {
+	let attempt = 1;
+	while (true) {
+		throwIfAborted(signal);
+		try {
+			return await execute(attempt);
+		} catch (error) {
+			throwIfAborted(signal);
+			const typedError = error;
+			const decision = policy.next({
+				attempt,
+				error: typedError
+			});
+			if (!decision.shouldRetry) throw policy.onExhausted({
+				attempts: attempt,
+				error: typedError
+			});
+			if (decision.delayMs > 0) await (signal === void 0 ? sleep(decision.delayMs) : sleepWithAbortSignal(sleep, decision.delayMs, signal));
+			attempt += 1;
+		}
+	}
+};
+//#endregion
+export { runThrowMode };
+
+//# sourceMappingURL=throw-mode.mjs.map

package/dist/throw-mode.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"throw-mode.mjs","names":[],"sources":["../src/throw-mode.ts"],"sourcesContent":["/**\n * Throw-mode execution path for `BaseRetryPolicy.run` (default when\n * `throwOnExhausted` is not `false`).\n *\n * @module @zap-studio/retry/throw-mode\n */\n\nimport { sleepWithAbortSignal, throwIfAborted } from \"./abort.js\";\nimport type { RetryPolicy } from \"./types.js\";\n\n/**\n * Runs the throw-mode retry loop: throws `RetryError` on exhaustion and\n * `AbortError` when `signal` aborts.\n *\n * @param policy - Object providing `next` and `onExhausted` (same contract as\n *   `BaseRetryPolicy`).\n * @param execute - Async work callback per attempt.\n * @param sleep - Delay function between retries.\n * @param signal - Optional cancel signal.\n * @returns Resolves to the first successful return value.\n * @throws {RetryError} When retries are exhausted and `onExhausted` returns\n *   the terminal error.\n * @throws {AbortError} When `signal` is already aborted or aborts while waiting.\n * @throws {Error} Any error thrown by `next`, `onExhausted`, or `sleep`.\n */\nexport const runThrowMode = async <T, TError, TData>(\n  policy: RetryPolicy<TError, TData>,\n  execute: (attempt: number) => Promise<T>,\n  sleep: (delayMs: number) => Promise<void>,\n  signal?: AbortSignal\n): Promise<T> => {\n  let attempt = 1;\n\n  while (true) {\n    throwIfAborted(signal);\n\n    try {\n      // oxlint-disable-next-line no-await-in-loop -- Retry attempts must run sequentially.\n      return await execute(attempt);\n    } catch (error) {\n      throwIfAborted(signal);\n\n      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Policy error generic represents the caller's thrown error domain.\n      const typedError = error as TError;\n      const decision = policy.next({\n        attempt,\n        error: typedError,\n      });\n\n      if (!decision.shouldRetry) {\n        throw policy.onExhausted({\n          attempts: attempt,\n          error: typedError,\n        });\n      }\n\n      if (decision.delayMs > 0) {\n        // oxlint-disable-next-line no-await-in-loop -- Delay belongs between sequential retry attempts.\n        await (signal === undefined\n          ? sleep(decision.delayMs)\n          : sleepWithAbortSignal(sleep, decision.delayMs, signal));\n      }\n\n      attempt += 1;\n    }\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,eAAe,OAC1B,QACA,SACA,OACA,WACe;CACf,IAAI,UAAU;CAEd,OAAO,MAAM;EACX,eAAe,MAAM;EAErB,IAAI;GAEF,OAAO,MAAM,QAAQ,OAAO;EAC9B,SAAS,OAAO;GACd,eAAe,MAAM;GAGrB,MAAM,aAAa;GACnB,MAAM,WAAW,OAAO,KAAK;IAC3B;IACA,OAAO;GACT,CAAC;GAED,IAAI,CAAC,SAAS,aACZ,MAAM,OAAO,YAAY;IACvB,UAAU;IACV,OAAO;GACT,CAAC;GAGH,IAAI,SAAS,UAAU,GAErB,OAAO,WAAW,KAAA,IACd,MAAM,SAAS,OAAO,IACtB,qBAAqB,OAAO,SAAS,SAAS,MAAM;GAG1D,WAAW;EACb;CACF;AACF"}

package/dist/types.d.mts

@@ -1,88 +1,141 @@
-import { t as RetryError } from "./error-CVW4I654.mjs";
-
+import { r as RetryError, t as AbortError } from "./errors-BVZjP1Q5.mjs";
 //#region src/types.d.ts
 /**
-* Retry policy contract used by `BaseRetryPolicy`.
-*
-* @example
-* const policy: RetryPolicy = {
-*   next: ({ attempt }) => ({ shouldRetry: attempt < 3, delayMs: 100 }),
-*   onExhausted: ({ attempts }) => new RetryError("done", { attempts }),
-* };
-*/
+ * Retry policy contract used by `BaseRetryPolicy`.
+ *
+ * @example
+ * const policy: RetryPolicy = {
+ *   next: ({ attempt }) => ({ shouldRetry: attempt < 3, delayMs: 100 }),
+ *   onExhausted: ({ attempts }) => new RetryError("done", { attempts }),
+ * };
+ */
 interface RetryPolicy<TError = unknown, TData = unknown> {
   /**
-  * Returns the retry decision for a failed attempt.
-  *
-  * @throws Any error thrown by the policy implementation.
-  */
-  next(input: RetryDecisionInput<TError, TData>): RetryDecision;
-  /**
-  * Builds the terminal error used when retries are exhausted.
-  *
-  * @throws Any error thrown by the policy implementation.
-  */
-  onExhausted(input: RetryExhaustedInput<TError, TData>): RetryError;
+   * Returns the retry decision for a failed attempt.
+   *
+   * @throws {Error} Any error thrown by the policy implementation.
+   */
+  next: (input: RetryDecisionInput<TError, TData>) => RetryDecision;
+  /**
+   * Builds the terminal error used when retries are exhausted.
+   *
+   * @throws {Error} Any error thrown by the policy implementation.
+   */
+  onExhausted: (input: RetryExhaustedInput<TError, TData>) => RetryError;
 }
 /**
-* Decision returned by a retry policy for a specific attempt.
-*/
+ * Decision returned by a retry policy for a specific attempt.
+ */
 interface RetryDecision {
+  /**
+   * When `true`, the runner may schedule another attempt (subject to
+   * `delayMs` and the runner's abort rules).
+   */
   readonly shouldRetry: boolean;
+  /**
+   * Milliseconds to wait before the next attempt when `shouldRetry` is `true`.
+   */
   readonly delayMs: number;
+  /**
+   * Optional machine-readable reason for the decision.
+   */
   readonly reason?: "retry" | "max-attempts-reached" | "policy-declined";
 }
 /**
-* Input passed to `RetryPolicy.next(...)` for each failed attempt.
-*/
+ * Input passed to `RetryPolicy.next(...)` for each failed attempt.
+ */
 interface RetryDecisionInput<TError = unknown, TData = unknown> {
+  /**
+   * One-based attempt number for the current failure.
+   */
   readonly attempt: number;
+  /**
+   * Optional policy-level maximum attempts, when a policy wants to pass it
+   * through to `next`.
+   */
   readonly maxAttempts?: number;
+  /**
+   * Error raised by the most recent `execute(attempt)` call, when a failure
+   * occurred.
+   */
   readonly error?: TError;
+  /**
+   * Optional data captured alongside the failure, when a policy populates
+   * it.
+   */
   readonly data?: TData;
 }
 /**
-* Input passed to `RetryPolicy.onExhausted(...)` when retries stop.
-*/
+ * Input passed to `RetryPolicy.onExhausted(...)` when retries stop.
+ */
 interface RetryExhaustedInput<TError = unknown, TData = unknown> {
+  /**
+   * Count of completed attempts that led to stopping retries.
+   */
   readonly attempts: number;
+  /**
+   * Last execution error, when available.
+   */
   readonly error?: TError;
+  /**
+   * Last captured data, when a policy or runner supplies it.
+   */
   readonly data?: TData;
 }
 /**
-* Options for `BaseRetryPolicy.run(...)`.
-*/
+ * Options for `BaseRetryPolicy.run(...)`.
+ */
 interface RetryRunOptions {
   /**
-  * Delay function used between retry attempts.
-  *
-  * @throws Any error thrown or rejected by the custom delay implementation.
-  */
+   * Delay function used between retry attempts.
+   *
+   * @throws {Error} Any error thrown or rejected by the custom delay implementation.
+   */
   readonly sleep?: (delayMs: number) => Promise<void>;
   /**
-  * Abort signal used to cancel retry orchestration.
-  *
-  * When aborted, the runner stops retrying and terminates immediately.
-  */
+   * Abort signal used to cancel retry orchestration.
+   *
+   * When aborted, the runner stops retrying and terminates immediately.
+   */
   readonly signal?: AbortSignal;
   /**
-  * When `true`, the runner throws a `RetryError` when retries are exhausted.
-  *
-  * When `false`, the runner returns a `RetryRunResult` discriminated union.
-  *
-  * @default false
-  */
+   * When `true`, the runner throws a `RetryError` when retries are exhausted.
+   *
+   * When `false`, the runner returns a `RetryRunResult` discriminated union.
+   *
+   * @default true
+   */
   readonly throwOnExhausted?: boolean;
 }
 /**
-* Result union returned by non-throw runner mode.
-*/
+ * Result union returned by non-throw runner mode.
+ *
+ * - Success: `ok: true` with the resolved `value`.
+ * - Failure: `ok: false` with terminal `error` and completed `attempts` count
+ *   (exhaustion or abort).
+ */
 type RetryRunResult<T> = {
+  /**
+   * Discriminator for a successful run.
+   */
   ok: true;
+  /**
+   * Successful return value from the final attempt.
+   */
   value: T;
 } | {
+  /**
+   * Discriminator for a failed or aborted run.
+   */
   ok: false;
-  error: RetryError;
+  /**
+   * Terminal error: `RetryError` when retries are exhausted, or
+   * `AbortError` when the run is canceled.
+   */
+  error: RetryError | AbortError;
+  /**
+   * Number of attempts that completed before the terminal outcome.
+   */
   attempts: number;
 };
 //#endregion

package/dist/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;UAiBiB,WAAA;;;;;;EAMf,IAAA,CAAK,KAAA,EAAO,kBAAA,CAAmB,MAAA,EAAQ,KAAA,IAAS,aAAA;;;;;;EAMhD,WAAA,CAAY,KAAA,EAAO,mBAAA,CAAoB,MAAA,EAAQ,KAAA,IAAS,UAAA;AAAA;AAM1D;;;AAAA,UAAiB,aAAA;EAAA,SACN,WAAA;EAAA,SACA,OAAA;EAAA,SACA,MAAA;AAAA;;AAMX;;UAAiB,kBAAA;EAAA,SACN,OAAA;EAAA,SACA,WAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,mBAAA;EAAA,SACN,QAAA;EAAA,SACA,KAAA,GAAQ,MAAA;EAAA,SACR,IAAA,GAAO,KAAA;AAAA;;;;UAMD,eAAA;EANC;AAMlB;;;;EANkB,SAYP,KAAA,IAAS,OAAA,aAAoB,OAAA;;;;;;WAM7B,MAAA,GAAS,WAAA;EAQT;AAMX;;;;;;EANW,SAAA,gBAAA;AAAA;;;;KAMC,cAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,UAAA;EACP,QAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;UAiBiB,YAAY,kBAAkB;;;;;;EAM7C,OAAO,OAAO,mBAAmB,QAAQ,WAAW;;;;;;EAMpD,cAAc,OAAO,oBAAoB,QAAQ,WAAW;;;;;UAM7C;;;;;WAKN;;;;WAIA;;;;WAIA;;;;;UAMM,mBAAmB,kBAAkB;;;;WAI3C;;;;;WAKA;;;;;WAKA,QAAQ;;;;;WAKR,OAAO;;;;;UAMD,oBAAoB,kBAAkB;;;;WAI5C;;;;WAIA,QAAQ;;;;WAIR,OAAO;;;;;UAMD;;;;;;WAMN,SAAS,oBAAoB;;;;;;WAM7B,SAAS;;;;;;;;WAQT;;;;;;;;;KAUC,eAAe;;;;EAKrB;;;;EAIA,OAAO;;;;;EAMP;;;;;EAKA,OAAO,aAAa;;;;EAIpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/retry",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": false,
   "description": "Composable retry policies for resilient async operations.",
   "keywords": [
@@ -30,9 +30,13 @@
   "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
-    "./error": "./dist/error.mjs",
+    "./abort": "./dist/abort.mjs",
+    "./errors": "./dist/errors.mjs",
     "./exponential-backoff": "./dist/exponential-backoff.mjs",
     "./fixed-delay": "./dist/fixed-delay.mjs",
+    "./result-mode": "./dist/result-mode.mjs",
+    "./sleep": "./dist/sleep.mjs",
+    "./throw-mode": "./dist/throw-mode.mjs",
     "./types": "./dist/types.mjs",
     "./package.json": "./package.json"
   },
@@ -46,16 +50,15 @@
     "exponential-backoff": "^3.1.3",
     "p-retry": "^8.0.0",
     "promise-retry": "^2.0.1",
-    "typescript": "^6.0.3",
-    "vite-plus": "^0.1.19",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
     "@zap-studio/typescript": "0.0.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "vp pack",
-    "test": "vp test run",
-    "test:watch": "vp test watch"
+    "build": "tsdown --config ./tsdown.config.ts"
   }
 }

package/dist/error-CVW4I654.d.mts

@@ -1,44 +0,0 @@
-//#region src/error.d.ts
-/**
-* Terminal error types used by retry policies and runners.
-*
-* @module @zap-studio/retry/error
-*/
-/**
-* Context payload attached to `RetryError`.
-*/
-interface RetryErrorContext {
-  readonly attempts: number;
-  readonly lastError?: unknown;
-  readonly lastData?: unknown;
-}
-/**
-* Error thrown when retries are exhausted.
-*
-* @example
-* throw new RetryError("Retry exhausted", {
-*   attempts: 3,
-*   lastError: new Error("network"),
-* });
-*/
-declare class RetryError extends Error {
-  /**
-  * Total attempts performed before exhaustion.
-  */
-  readonly attempts: number;
-  /**
-  * Last captured error from execution.
-  */
-  readonly lastError?: unknown;
-  /**
-  * Last captured data value, when available.
-  */
-  readonly lastData?: unknown;
-  /**
-  * Creates a RetryError with structured terminal context.
-  */
-  constructor(message: string, context: RetryErrorContext);
-}
-//#endregion
-export { RetryErrorContext as n, RetryError as t };
-//# sourceMappingURL=error-CVW4I654.d.mts.map

package/dist/error-CVW4I654.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"error-CVW4I654.d.mts","names":[],"sources":["../src/error.ts"],"mappings":";;AASA;;;;;;;UAAiB,iBAAA;EAAA,SACN,QAAA;EAAA,SACA,SAAA;EAAA,SACA,QAAA;AAAA;;;;;;;;;;cAYE,UAAA,SAAmB,KAAA;EAiBQ;;;EAAA,SAbtB,QAAA;;;;WAIA,SAAA;;;;WAIA,QAAA;;;;EAKhB,WAAA,CAAY,OAAA,UAAiB,OAAA,EAAS,iBAAA;AAAA"}

package/dist/error.d.mts

@@ -1,2 +0,0 @@
-import { n as RetryErrorContext, t as RetryError } from "./error-CVW4I654.mjs";
-export { RetryError, RetryErrorContext };

package/dist/error.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"error.mjs","names":[],"sources":["../src/error.ts"],"sourcesContent":["/**\n * Terminal error types used by retry policies and runners.\n *\n * @module @zap-studio/retry/error\n */\n\n/**\n * Context payload attached to `RetryError`.\n */\nexport interface RetryErrorContext {\n  readonly attempts: number;\n  readonly lastError?: unknown;\n  readonly lastData?: unknown;\n}\n\n/**\n * Error thrown when retries are exhausted.\n *\n * @example\n * throw new RetryError(\"Retry exhausted\", {\n *   attempts: 3,\n *   lastError: new Error(\"network\"),\n * });\n */\nexport class RetryError extends Error {\n  /**\n   * Total attempts performed before exhaustion.\n   */\n  public readonly attempts: number;\n  /**\n   * Last captured error from execution.\n   */\n  public readonly lastError?: unknown;\n  /**\n   * Last captured data value, when available.\n   */\n  public readonly lastData?: unknown;\n\n  /**\n   * Creates a RetryError with structured terminal context.\n   */\n  constructor(message: string, context: RetryErrorContext) {\n    super(message);\n    this.name = \"RetryError\";\n    this.attempts = context.attempts;\n    this.lastError = context.lastError;\n    this.lastData = context.lastData;\n  }\n}\n"],"mappings":";;;;;;;;;;AAwBA,IAAa,aAAb,cAAgC,MAAM;;;;CAIpC;;;;CAIA;;;;CAIA;;;;CAKA,YAAY,SAAiB,SAA4B;AACvD,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,WAAW,QAAQ;AACxB,OAAK,YAAY,QAAQ;AACzB,OAAK,WAAW,QAAQ"}