@vibeorm/runtime 1.3.0 → 2.0.0-alpha.2

package/src/relation-loader.ts

@@ -1,534 +0,0 @@
-/**
- * Relation Loader
- *
- * Implements the hybrid loading strategy:
- * - To-one relations: LEFT JOIN in the main query (future optimization)
- * - To-many relations: Separate batched WHERE IN queries
- *
- * Currently uses batched queries for all relation types for simplicity.
- * The JOIN strategy for to-one can be added later as an optimization.
- */
-
-import type {
-  ModelMeta,
-  ModelMetaMap,
-  RelationFieldMeta,
-  ProfilingContext,
-} from "./types.ts";
-import { getModelByNameMap, getScalarFieldMap, PgArray } from "./types.ts";
-import { buildRelationQuery, buildManyToManyQuery, buildSelectQuery } from "./query-builder.ts";
-import type { RelationSqlQuery } from "./query-builder.ts";
-import { buildWhereClause } from "./where-builder.ts";
-import { coerceFieldTypes } from "./coerce.ts";
-
-type SqlExecutor = (params: {
-  text: string;
-  values: unknown[];
-}) => Promise<Record<string, unknown>[]>;
-
-/**
- * Load relations for a set of parent records.
- *
- * Examines the select/include args to determine which relations to load,
- * executes batched queries in PARALLEL, and stitches the results onto
- * parent records.
- *
- * Sibling relations are independent — they query different tables and write
- * to different keys on the parent records — so they can safely run concurrently.
- */
-export async function loadRelations(params: {
-  parentRecords: Record<string, unknown>[];
-  parentModelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  args: Record<string, unknown>;
-  executor: SqlExecutor;
-  profilingCtx?: ProfilingContext;
-  defaultOrderByPk?: boolean;
-}): Promise<Record<string, unknown>[]> {
-  const { parentRecords, parentModelMeta, allModelsMeta, args, executor, profilingCtx, defaultOrderByPk = false } =
-    params;
-
-  if (parentRecords.length === 0) return parentRecords;
-
-  const relationsToLoad = resolveRelationsToLoad({
-    parentModelMeta,
-    args,
-  });
-
-  if (relationsToLoad.length === 0) return parentRecords;
-
-  const modelMap = getModelByNameMap({ allModelsMeta });
-  const pkField = parentModelMeta.primaryKey[0]!;
-  const parentIds = [
-    ...new Set(
-      parentRecords
-        .map((r) => r[pkField])
-        .filter((id) => id !== undefined && id !== null)
-    ),
-  ];
-
-  if (parentIds.length === 0) return parentRecords;
-
-  // Phase 1: Load all sibling relations in parallel.
-  // Each relation query hits a different table and writes to a unique key
-  // on the parent records, so there are no data races.
-  await Promise.all(
-    relationsToLoad.map(async ({ relationMeta, nestedArgs }) => {
-      const relatedModelMeta = modelMap.get(relationMeta.relatedModel);
-      if (!relatedModelMeta) return;
-
-      if (relationMeta.isList) {
-        await loadToManyRelation({
-          parentRecords,
-          parentModelMeta,
-          relationMeta,
-          relatedModelMeta,
-          parentIds,
-          nestedArgs,
-          allModelsMeta,
-          executor,
-          pkField,
-          profilingCtx,
-          defaultOrderByPk,
-        });
-      } else if (relationMeta.isForeignKey) {
-        await loadToOneWithFk({
-          parentRecords,
-          parentModelMeta,
-          relationMeta,
-          relatedModelMeta,
-          nestedArgs,
-          allModelsMeta,
-          executor,
-          profilingCtx,
-        });
-      } else {
-        await loadToOneWithoutFk({
-          parentRecords,
-          parentModelMeta,
-          relationMeta,
-          relatedModelMeta,
-          parentIds,
-          nestedArgs,
-          allModelsMeta,
-          executor,
-          pkField,
-          profilingCtx,
-          defaultOrderByPk,
-        });
-      }
-    })
-  );
-
-  // Phase 2: Recursively load nested relations in parallel.
-  // Each nested load operates on a different set of child records.
-  await Promise.all(
-    relationsToLoad
-      .filter(({ nestedArgs }) => hasNestedRelations({ nestedArgs }))
-      .map(async ({ relationMeta, nestedArgs }) => {
-        const relatedModelMeta = modelMap.get(relationMeta.relatedModel);
-        if (!relatedModelMeta) return;
-
-        const loadedRecords = parentRecords
-          .flatMap((r) => {
-            const val = r[relationMeta.name];
-            if (Array.isArray(val)) return val;
-            if (val && typeof val === "object") return [val];
-            return [];
-          })
-          .filter((r): r is Record<string, unknown> => r !== null);
-
-        if (loadedRecords.length > 0) {
-          await loadRelations({
-            parentRecords: loadedRecords,
-            parentModelMeta: relatedModelMeta,
-            allModelsMeta,
-            args: nestedArgs,
-            executor,
-          });
-
-          // Strip auto-included PKs from child records if user's select didn't include them
-          const nestedSelect = nestedArgs.select as Record<string, boolean | object> | undefined;
-          if (nestedSelect) {
-            for (const pkName of relatedModelMeta.primaryKey) {
-              if (nestedSelect[pkName] === undefined) {
-                for (const rec of loadedRecords) {
-                  delete rec[pkName];
-                }
-              }
-            }
-          }
-        }
-      })
-  );
-
-  return parentRecords;
-}
-
-// ─── To-Many Loader ───────────────────────────────────────────────
-
-async function loadToManyRelation(params: {
-  parentRecords: Record<string, unknown>[];
-  parentModelMeta: ModelMeta;
-  relationMeta: RelationFieldMeta;
-  relatedModelMeta: ModelMeta;
-  parentIds: unknown[];
-  nestedArgs: Record<string, unknown>;
-  allModelsMeta: ModelMetaMap;
-  executor: SqlExecutor;
-  pkField: string;
-  profilingCtx?: ProfilingContext;
-  defaultOrderByPk?: boolean;
-}): Promise<void> {
-  const {
-    parentRecords,
-    parentModelMeta,
-    relationMeta,
-    relatedModelMeta,
-    parentIds,
-    nestedArgs,
-    allModelsMeta,
-    executor,
-    pkField,
-    profilingCtx,
-    defaultOrderByPk = false,
-  } = params;
-
-  // Choose builder based on relation type
-  const isM2M = relationMeta.type === "manyToMany" && (relationMeta as { joinTable?: string }).joinTable;
-
-  const query = isM2M
-    ? buildManyToManyQuery({
-        parentModelMeta,
-        relationMeta,
-        relatedModelMeta,
-        parentIds,
-        args: nestedArgs,
-        allModelsMeta,
-        defaultOrderByPk,
-      })
-    : buildRelationQuery({
-        parentModelMeta,
-        relationMeta,
-        relatedModelMeta,
-        parentIds,
-        args: nestedArgs,
-        allModelsMeta,
-        defaultOrderByPk,
-      });
-
-  const t0 = profilingCtx ? performance.now() : 0;
-  const rows = await executor(query);
-  if (profilingCtx) {
-    profilingCtx.relationProfiles.push({
-      relation: relationMeta.name,
-      sqlExecMs: performance.now() - t0,
-      rowCount: rows.length,
-      sql: query.text,
-    });
-  }
-
-  // Group by FK — use the already-selected field name when FK was deduped,
-  // otherwise use the __vibeorm_fk alias
-  const fkKey = query.fkFieldName ?? "__vibeorm_fk";
-  const grouped = new Map<unknown, Record<string, unknown>[]>();
-  for (const row of rows) {
-    const fk = row[fkKey];
-    if (!query.fkFieldName) delete row.__vibeorm_fk;
-    // Also clean up __vibeorm_rn from ROW_NUMBER windowed queries
-    if ("__vibeorm_rn" in row) delete row.__vibeorm_rn;
-    if (!grouped.has(fk)) {
-      grouped.set(fk, []);
-    }
-    grouped.get(fk)!.push(row);
-  }
-
-  // Coerce scalar types on the loaded child records (e.g., BigInt from string).
-  // Mirrors what `loadRelationsForStrategy` does on parent records.
-  coerceFieldTypes({ records: rows, modelMeta: relatedModelMeta });
-
-  // Stitch onto parent records
-  for (const parent of parentRecords) {
-    const parentId = parent[pkField];
-    parent[relationMeta.name] = grouped.get(parentId) ?? [];
-  }
-}
-
-// ─── To-One with FK (this side has foreignKey) ────────────────────
-
-async function loadToOneWithFk(params: {
-  parentRecords: Record<string, unknown>[];
-  parentModelMeta: ModelMeta;
-  relationMeta: RelationFieldMeta;
-  relatedModelMeta: ModelMeta;
-  nestedArgs: Record<string, unknown>;
-  allModelsMeta: ModelMetaMap;
-  executor: SqlExecutor;
-  profilingCtx?: ProfilingContext;
-}): Promise<void> {
-  const {
-    parentRecords,
-    parentModelMeta,
-    relationMeta,
-    relatedModelMeta,
-    nestedArgs,
-    allModelsMeta,
-    executor,
-    profilingCtx,
-  } = params;
-
-  // Get FK values from parent records (deduplicated for smaller IN clauses)
-  const fkFieldName = relationMeta.fields[0]!;
-  const fkValues = [
-    ...new Set(
-      parentRecords
-        .map((r) => r[fkFieldName])
-        .filter((v) => v !== undefined && v !== null)
-    ),
-  ];
-
-  if (fkValues.length === 0) {
-    for (const parent of parentRecords) {
-      parent[relationMeta.name] = null;
-    }
-    return;
-  }
-
-  // Query related model by its PK (which is what our FK references)
-  const refField = relationMeta.references[0]!;
-  const sfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-  const refScalarField = sfMap.get(refField);
-  const refDbName = refScalarField?.dbName ?? refField;
-
-  const columns = resolveSelectColumnsForRelation({
-    modelMeta: relatedModelMeta,
-    args: nestedArgs,
-  });
-  const table = `"${relatedModelMeta.dbName}"`;
-  const columnsSql = columns
-    .map((c) => `${table}."${c.dbName}" AS "${c.name}"`)
-    .join(", ");
-
-  // Build the base WHERE: pk = ANY($1) for batched loading
-  const allValues: unknown[] = [new PgArray(fkValues)];
-  let paramIdx = 1;
-  let whereSql = `${table}."${refDbName}" = ANY($${paramIdx})`;
-
-  // Apply nested where filters (e.g., include: { author: { where: { isActive: true } } })
-  if (nestedArgs.where) {
-    const subWhere = buildWhereClause({
-      where: nestedArgs.where as Record<string, unknown>,
-      modelMeta: relatedModelMeta,
-      allModelsMeta,
-      paramOffset: paramIdx,
-    });
-    if (subWhere.sql) {
-      whereSql += ` AND (${subWhere.sql})`;
-      allValues.push(...subWhere.values);
-      paramIdx += subWhere.values.length;
-    }
-  }
-
-  const text = `SELECT ${columnsSql}, ${table}."${refDbName}" AS "__vibeorm_pk" FROM ${table} WHERE ${whereSql}`;
-
-  const t0 = profilingCtx ? performance.now() : 0;
-  const rows = await executor({ text, values: allValues });
-  if (profilingCtx) {
-    profilingCtx.relationProfiles.push({
-      relation: relationMeta.name,
-      sqlExecMs: performance.now() - t0,
-      rowCount: rows.length,
-      sql: text,
-    });
-  }
-
-  // Index by PK
-  const byPk = new Map<unknown, Record<string, unknown>>();
-  for (const row of rows) {
-    const pk = row.__vibeorm_pk;
-    delete row.__vibeorm_pk;
-    byPk.set(pk, row);
-  }
-
-  // Coerce scalar types on the loaded child records before stitching.
-  coerceFieldTypes({ records: rows, modelMeta: relatedModelMeta });
-
-  // Stitch
-  for (const parent of parentRecords) {
-    const fkValue = parent[fkFieldName];
-    parent[relationMeta.name] = byPk.get(fkValue) ?? null;
-  }
-}
-
-// ─── To-One without FK (other side has FK) ────────────────────────
-
-async function loadToOneWithoutFk(params: {
-  parentRecords: Record<string, unknown>[];
-  parentModelMeta: ModelMeta;
-  relationMeta: RelationFieldMeta;
-  relatedModelMeta: ModelMeta;
-  parentIds: unknown[];
-  nestedArgs: Record<string, unknown>;
-  allModelsMeta: ModelMetaMap;
-  executor: SqlExecutor;
-  pkField: string;
-  profilingCtx?: ProfilingContext;
-  defaultOrderByPk?: boolean;
-}): Promise<void> {
-  const {
-    parentRecords,
-    parentModelMeta,
-    relationMeta,
-    relatedModelMeta,
-    parentIds,
-    nestedArgs,
-    allModelsMeta,
-    executor,
-    pkField,
-    profilingCtx,
-    defaultOrderByPk = false,
-  } = params;
-
-  const query = buildRelationQuery({
-    parentModelMeta,
-    relationMeta,
-    relatedModelMeta,
-    parentIds,
-    args: nestedArgs,
-    allModelsMeta,
-    defaultOrderByPk,
-  });
-
-  const t0 = profilingCtx ? performance.now() : 0;
-  const rows = await executor(query);
-  if (profilingCtx) {
-    profilingCtx.relationProfiles.push({
-      relation: relationMeta.name,
-      sqlExecMs: performance.now() - t0,
-      rowCount: rows.length,
-      sql: query.text,
-    });
-  }
-
-  // Index by FK (each FK should map to at most one record for to-one)
-  const fkKey = query.fkFieldName ?? "__vibeorm_fk";
-  const byFk = new Map<unknown, Record<string, unknown>>();
-  for (const row of rows) {
-    const fk = row[fkKey];
-    if (!query.fkFieldName) delete row.__vibeorm_fk;
-    byFk.set(fk, row);
-  }
-
-  // Coerce scalar types on the loaded child records before stitching.
-  coerceFieldTypes({ records: rows, modelMeta: relatedModelMeta });
-
-  // Stitch
-  for (const parent of parentRecords) {
-    const parentId = parent[pkField];
-    parent[relationMeta.name] = byFk.get(parentId) ?? null;
-  }
-}
-
-// ─── Helpers ──────────────────────────────────────────────────────
-
-export type RelationToLoad = {
-  relationMeta: RelationFieldMeta;
-  nestedArgs: Record<string, unknown>;
-};
-
-export function resolveRelationsToLoad(params: {
-  parentModelMeta: ModelMeta;
-  args: Record<string, unknown>;
-}): RelationToLoad[] {
-  const { parentModelMeta, args } = params;
-  const result: RelationToLoad[] = [];
-
-  const select = args.select as Record<string, unknown> | undefined;
-  const include = args.include as Record<string, unknown> | undefined;
-
-  for (const relationMeta of parentModelMeta.relationFields) {
-    let shouldLoad = false;
-    let nestedArgs: Record<string, unknown> = {};
-
-    if (select) {
-      const val = select[relationMeta.name];
-      if (val === true) {
-        shouldLoad = true;
-      } else if (typeof val === "object" && val !== null) {
-        shouldLoad = true;
-        nestedArgs = val as Record<string, unknown>;
-      }
-    }
-
-    if (include) {
-      const val = include[relationMeta.name];
-      if (val === true) {
-        shouldLoad = true;
-      } else if (typeof val === "object" && val !== null) {
-        shouldLoad = true;
-        nestedArgs = val as Record<string, unknown>;
-      }
-    }
-
-    if (shouldLoad) {
-      result.push({ relationMeta, nestedArgs });
-    }
-  }
-
-  return result;
-}
-
-export function hasNestedRelations(params: {
-  nestedArgs: Record<string, unknown>;
-}): boolean {
-  const { nestedArgs } = params;
-  return (
-    nestedArgs.include !== undefined ||
-    (typeof nestedArgs.select === "object" && nestedArgs.select !== null)
-  );
-}
-
-function resolveSelectColumnsForRelation(params: {
-  modelMeta: ModelMeta;
-  args: Record<string, unknown>;
-}): { name: string; dbName: string }[] {
-  const { modelMeta, args } = params;
-  const select = args.select as Record<string, boolean | object> | undefined;
-
-  if (!select) {
-    return modelMeta.scalarFields.map((f) => ({
-      name: f.name,
-      dbName: f.dbName,
-    }));
-  }
-
-  const columns = modelMeta.scalarFields
-    .filter((f) => {
-      const val = select[f.name];
-      return val === true || (typeof val === "object" && val !== null);
-    })
-    .map((f) => ({ name: f.name, dbName: f.dbName }));
-
-  // Check if select has nested relations (object values referencing relation fields)
-  const relationNameSet = new Set(modelMeta.relationFields.map((r) => r.name));
-  const hasNested = Object.entries(select).some(([key, val]) => {
-    if (typeof val !== "object" || val === null) return false;
-    return relationNameSet.has(key);
-  });
-
-  if (hasNested) {
-    // Auto-include PK fields if not already selected
-    const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
-    const selectedNames = new Set(columns.map((c) => c.name));
-    for (const pkName of modelMeta.primaryKey) {
-      if (!selectedNames.has(pkName)) {
-        const sf = sfMap.get(pkName);
-        if (sf) {
-          columns.push({ name: sf.name, dbName: sf.dbName });
-        }
-      }
-    }
-  }
-
-  return columns;
-}

package/src/retry.ts

@@ -1,183 +0,0 @@
-/**
- * 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;
-}