@vibeorm/runtime 1.1.4 → 1.1.6

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.6",
   "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/lateral-join-builder.ts

@@ -12,20 +12,29 @@
  *   __lat_1."__vibeorm_rel_profile"
  * FROM "User"
  * LEFT JOIN LATERAL (
- *   SELECT COALESCE(json_agg(json_build_object(
- *     'id', __rel."id", 'title', __rel."title", ...
- *   )), '[]'::json) AS "__vibeorm_rel_posts"
- *   FROM "Post" __rel WHERE __rel."authorId" = "User"."id"
+ *   SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb)
+ *     AS "__vibeorm_rel_posts"
+ *   FROM (
+ *     SELECT __rel."id" AS "id", __rel."title" AS "title", ...
+ *     FROM "Post" __rel WHERE __rel."authorId" = "User"."id"
+ *   ) "__sub"
  * ) __lat_0 ON true
  * LEFT JOIN LATERAL (
- *   SELECT json_build_object(
- *     'id', __rel."id", 'bio', __rel."bio", ...
- *   ) AS "__vibeorm_rel_profile"
- *   FROM "Profile" __rel WHERE __rel."userId" = "User"."id" LIMIT 1
+ *   SELECT to_jsonb("__sub".*) AS "__vibeorm_rel_profile"
+ *   FROM (
+ *     SELECT __rel."id" AS "id", __rel."bio" AS "bio", ...
+ *     FROM "Profile" __rel WHERE __rel."userId" = "User"."id"
+ *     LIMIT 1
+ *   ) "__sub"
  * ) __lat_1 ON true
  * WHERE "User"."role" = $1
  * ORDER BY "User"."id" ASC
  * LIMIT 20
+ *
+ * Uses to_jsonb() on a subselect instead of json_build_object() to avoid
+ * PostgreSQL's 100-argument function limit (models with >50 scalar fields
+ * would exceed this). Column aliases in the inner SELECT handle the
+ * dbName→tsName remapping at zero cost.
  */
 
 import type {
@@ -183,14 +192,16 @@ export function buildLateralJoinQuery(params: {
     const relatedModelMeta = modelMap.get(relationMeta.relatedModel);
     if (!relatedModelMeta) continue;
 
-    // Build json_build_object fields for the related model.
+    // Build aliased column list for the inner subquery.
+    // Uses to_jsonb("__sub".*) instead of json_build_object() to avoid
+    // PostgreSQL's 100-argument function limit on wide models.
     // Respect nested select/omit to avoid serialising columns the caller doesn't need.
     const relatedScalars = resolveRelatedScalars({
       relatedModelMeta,
       nestedArgs,
     });
-    const jsonFields = relatedScalars
-      .map((f) => `'${f.name}', ${relatedAlias}."${f.dbName}"`)
+    const columnAliases = relatedScalars
+      .map((f) => `${relatedAlias}."${f.dbName}" AS "${f.name}"`)
       .join(", ");
 
     let lateralSubquery: string;
@@ -288,22 +299,27 @@ export function buildLateralJoinQuery(params: {
         allValues.push(nestedArgs.skip);
       }
 
-      // When take or skip is specified, use a subquery to apply per-parent LIMIT/OFFSET properly
+      // Wrap in inner subquery with column aliases + to_jsonb to avoid
+      // PostgreSQL's 100-argument limit on json_build_object.
       if (nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
         lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
+    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
     FROM (
-      SELECT ${relatedAlias}.* FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+      SELECT ${columnAliases}
+      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
       ${junctionJoin}
       WHERE ${subWhere}${nestedWhereSql}${orderBySql}${limitSql}${offsetSql}
-    ) ${relatedAlias}
+    ) "__sub"
   ) ${alias} ON true`;
       } else {
         lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
-    FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-    ${junctionJoin}
-    WHERE ${subWhere}${nestedWhereSql}
+    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
+    FROM (
+      SELECT ${columnAliases}
+      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+      ${junctionJoin}
+      WHERE ${subWhere}${nestedWhereSql}${orderBySql}
+    ) "__sub"
   ) ${alias} ON true`;
       }
 
@@ -396,24 +412,29 @@ export function buildLateralJoinQuery(params: {
           allValues.push(nestedArgs.skip);
         }
 
-        // When take or skip is specified, use a subquery to apply per-parent LIMIT/OFFSET properly
+        // Wrap in inner subquery with column aliases + to_jsonb to avoid
+        // PostgreSQL's 100-argument limit on json_build_object.
         if (nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
           lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
+    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
     FROM (
-      SELECT * FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+      SELECT ${columnAliases}
+      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
       WHERE ${subWhere}${nestedWhereSql}${orderBySql}${limitSql}${offsetSql}
-    ) ${relatedAlias}
+    ) "__sub"
   ) ${alias} ON true`;
         } else {
           lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
-    FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-    WHERE ${subWhere}${nestedWhereSql}
+    SELECT COALESCE(jsonb_agg(to_jsonb("__sub".*)), '[]'::jsonb) AS "${colAlias}"
+    FROM (
+      SELECT ${columnAliases}
+      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+      WHERE ${subWhere}${nestedWhereSql}${orderBySql}
+    ) "__sub"
   ) ${alias} ON true`;
         }
       } else {
-        // To-one: use json_build_object with LIMIT 1
+        // To-one: use to_jsonb on subselect with LIMIT 1
         let joinCondition: string;
 
         if (fkTable === "parent") {
@@ -432,10 +453,13 @@ export function buildLateralJoinQuery(params: {
         }
 
         lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT json_build_object(${jsonFields}) AS "${colAlias}"
-    FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-    WHERE ${joinCondition}
-    LIMIT 1
+    SELECT to_jsonb("__sub".*) AS "${colAlias}"
+    FROM (
+      SELECT ${columnAliases}
+      FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+      WHERE ${joinCondition}
+      LIMIT 1
+    ) "__sub"
   ) ${alias} ON true`;
       }
     }
@@ -886,7 +910,7 @@ export function whereHasRelationFilter(params: {
 }
 
 /**
- * Resolve which scalar columns to include in a lateral join's json_build_object.
+ * Resolve which scalar columns to include in a lateral join's inner subquery.
  * Respects nested select/omit so we don't serialise unnecessary columns.
  * Always includes the PK so nested relation loading can stitch correctly.
  */

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;
+}