@vibeorm/runtime 1.1.4 → 1.1.5

package/README.md

@@ -59,6 +59,54 @@ Per-operation `countStrategy` takes precedence over the client default.
 
 Bridges a `DatabaseAdapter` to a `SqlExecutor` for use with the migrate package.
 
+### `withRetry(fn, options?)`
+
+Retry utility with exponential backoff and jitter. Only retries `VibeTransientError` instances (connection failures, deadlocks, serialization conflicts, statement timeouts, pool exhaustion). Deterministic errors (`VibeRequestError`) are never retried.
+
+```ts
+import { withRetry } from "@vibeorm/runtime";
+
+// Basic — 3 retries, exponential backoff with jitter
+const users = await withRetry(() =>
+  db.user.findMany({ where: { active: true } })
+);
+
+// Custom options
+const user = await withRetry(
+  () => db.user.create({ data: { email: "new@example.com" } }),
+  { maxRetries: 5, baseDelay: 100, maxDelay: 10000 },
+);
+
+// Retry only specific error codes
+const result = await withRetry(
+  () => db.$transaction(async (tx) => {
+    /* ... */
+  }, { isolationLevel: "Serializable" }),
+  { retryOn: ["SERIALIZATION_FAILURE", "DEADLOCK"] },
+);
+
+// With abort signal
+const controller = new AbortController();
+const result = await withRetry(
+  () => db.user.findFirst({ where: { id: 1 } }),
+  { signal: controller.signal },
+);
+```
+
+**Options (`RetryOptions`):**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `maxRetries` | `3` | Max retry attempts (total executions = maxRetries + 1) |
+| `baseDelay` | `50` | Base delay in ms for exponential backoff |
+| `maxDelay` | `5000` | Maximum delay cap in ms |
+| `maxJitter` | `50` | Random jitter added per retry to prevent thundering herd |
+| `signal` | — | `AbortSignal` to cancel pending retries |
+| `retryOn` | — | Filter to retry only specific `VibeTransientErrorCode`s |
+| `onRetry` | — | Callback `({ error, attempt, delay }) => void` for logging/metrics |
+
+Backoff formula: `min(baseDelay * 2^attempt + random(0, maxJitter), maxDelay)`
+
 ### `VibeValidationError`
 
 Custom error class thrown when Zod validation fails on input or output data.
@@ -86,7 +134,7 @@ type DatabaseAdapter = {
 
 ### Exported Types
 
-`DatabaseAdapter`, `QueryResult`, `SqlExecutor`, `VibeClientOptions`, `ModelMeta`, `ModelMetaMap`, `ModelSchemas`, `ValidationSchema`, `QueryProfile`, `RelationProfile`, `ScalarFieldMeta`, `RelationFieldMeta`, `SqlQuery`, `Operation`.
+`DatabaseAdapter`, `QueryResult`, `SqlExecutor`, `VibeClientOptions`, `ModelMeta`, `ModelMetaMap`, `ModelSchemas`, `ValidationSchema`, `QueryProfile`, `RelationProfile`, `ScalarFieldMeta`, `RelationFieldMeta`, `SqlQuery`, `Operation`, `RetryOptions`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/runtime",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Driver-agnostic query engine and client runtime for VibeORM",
   "license": "MIT",
   "keywords": [

package/src/index.ts

@@ -20,8 +20,10 @@ export {
   executeLateralJoinQuery,
 } from "./lateral-join-builder.ts";
 export { toSqlExecutor } from "./adapter.ts";
+export { withRetry } from "./retry.ts";
 export { ViewResult, createView } from "./view.ts";
 export type { ViewDefinition } from "./view.ts";
+export type { RetryOptions } from "./retry.ts";
 
 export type {
   DatabaseAdapter,

package/src/retry.ts

@@ -0,0 +1,183 @@
+/**
+ * Retry utility with exponential backoff and jitter.
+ *
+ * Only retries on transient errors (VibeTransientError) — connection failures,
+ * deadlocks, serialization failures, statement timeouts, and pool exhaustion.
+ * Deterministic errors (VibeRequestError) are never retried.
+ *
+ * @example
+ * ```ts
+ * import { withRetry } from "@vibeorm/runtime";
+ *
+ * // Basic — 3 retries, exponential backoff with jitter
+ * const users = await withRetry(() =>
+ *   db.user.findMany({ where: { active: true } })
+ * );
+ *
+ * // Custom options
+ * const user = await withRetry(
+ *   () => db.user.create({ data: { email: "new@example.com" } }),
+ *   { maxRetries: 5, baseDelay: 100, maxDelay: 10000 },
+ * );
+ *
+ * // With abort signal
+ * const controller = new AbortController();
+ * const result = await withRetry(
+ *   () => db.user.findFirst({ where: { id: 1 } }),
+ *   { signal: controller.signal },
+ * );
+ *
+ * // Retry only specific error codes
+ * const result = await withRetry(
+ *   () => db.$transaction(async (tx) => { ... }, { isolationLevel: "Serializable" }),
+ *   { retryOn: ["SERIALIZATION_FAILURE", "DEADLOCK"] },
+ * );
+ * ```
+ */
+
+import { VibeTransientError } from "./errors.ts";
+import type { VibeTransientErrorCode } from "./errors.ts";
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/**
+ * Options for configuring retry behavior.
+ */
+export type RetryOptions = {
+  /**
+   * Maximum number of retry attempts (default: 3).
+   * The first execution is not counted as a retry, so the operation
+   * may execute up to `maxRetries + 1` times total.
+   */
+  maxRetries?: number;
+  /**
+   * Base delay in milliseconds for exponential backoff (default: 50).
+   * Actual delay = min(baseDelay * 2^attempt + jitter, maxDelay).
+   */
+  baseDelay?: number;
+  /**
+   * Maximum delay in milliseconds between retries (default: 5000).
+   * Caps the exponential growth to prevent excessively long waits.
+   */
+  maxDelay?: number;
+  /**
+   * Maximum jitter in milliseconds added to each delay (default: 50).
+   * Randomized per retry to prevent thundering herd effects when
+   * many clients retry simultaneously after a shared failure.
+   */
+  maxJitter?: number;
+  /**
+   * Optional AbortSignal to cancel pending retries.
+   * When aborted, the last error is thrown immediately without
+   * further retry attempts.
+   */
+  signal?: AbortSignal;
+  /**
+   * Optional filter to retry only specific transient error codes.
+   * When provided, only errors with matching codes are retried;
+   * other transient errors are thrown immediately.
+   *
+   * When not provided, all transient errors are retried.
+   */
+  retryOn?: VibeTransientErrorCode[];
+  /**
+   * Optional callback invoked before each retry attempt.
+   * Useful for logging or metrics.
+   */
+  onRetry?: (params: { error: VibeTransientError; attempt: number; delay: number }) => void;
+};
+
+// ─── Implementation ──────────────────────────────────────────────
+
+/**
+ * Compute the delay for a retry attempt using exponential backoff with jitter.
+ * Formula: min(baseDelay * 2^attempt + random(0, maxJitter), maxDelay)
+ */
+function computeDelay(params: {
+  attempt: number;
+  baseDelay: number;
+  maxDelay: number;
+  maxJitter: number;
+}): number {
+  const { attempt, baseDelay, maxDelay, maxJitter } = params;
+  const exponential = baseDelay * Math.pow(2, attempt);
+  const jitter = Math.random() * maxJitter;
+  return Math.min(exponential + jitter, maxDelay);
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ * Resolves immediately if the signal is already aborted.
+ */
+function sleep(params: { ms: number; signal?: AbortSignal }): Promise<void> {
+  const { ms, signal } = params;
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+}
+
+/**
+ * Execute a function with automatic retry on transient errors.
+ *
+ * Uses exponential backoff with jitter to space out retries and
+ * prevent thundering herd effects. Only retries `VibeTransientError`
+ * instances — deterministic errors (constraint violations, validation
+ * errors, etc.) are thrown immediately.
+ *
+ * @param fn - The async operation to execute and potentially retry.
+ * @param options - Optional retry configuration.
+ * @returns The result of the first successful execution.
+ * @throws The last error if all retries are exhausted.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options?: RetryOptions,
+): Promise<T> {
+  const maxRetries = options?.maxRetries ?? 3;
+  const baseDelay = options?.baseDelay ?? 50;
+  const maxDelay = options?.maxDelay ?? 5000;
+  const maxJitter = options?.maxJitter ?? 50;
+  const signal = options?.signal;
+  const retryOn = options?.retryOn;
+  const onRetry = options?.onRetry;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+
+      // Only retry transient errors
+      if (!(err instanceof VibeTransientError)) throw err;
+
+      // If retryOn filter is set, only retry matching codes
+      if (retryOn && !retryOn.includes(err.code)) throw err;
+
+      // Don't retry if we've exhausted attempts
+      if (attempt >= maxRetries) throw err;
+
+      // Don't retry if aborted
+      if (signal?.aborted) throw err;
+
+      const delay = computeDelay({ attempt, baseDelay, maxDelay, maxJitter });
+
+      // Notify before sleeping
+      onRetry?.({ error: err, attempt: attempt + 1, delay });
+
+      await sleep({ ms: delay, signal });
+
+      // Check abort again after sleep
+      if (signal?.aborted) throw err;
+    }
+  }
+
+  // Should never reach here, but TypeScript needs it
+  throw lastError;
+}