@vibeorm/runtime 1.0.0

package/src/relation-loader.ts

@@ -0,0 +1,489 @@
+/**
+ * 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";
+
+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;
+}): Promise<Record<string, unknown>[]> {
+  const { parentRecords, parentModelMeta, allModelsMeta, args, executor, profilingCtx } =
+    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,
+        });
+      } 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,
+        });
+      }
+    })
+  );
+
+  // 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;
+}): Promise<void> {
+  const {
+    parentRecords,
+    parentModelMeta,
+    relationMeta,
+    relatedModelMeta,
+    parentIds,
+    nestedArgs,
+    allModelsMeta,
+    executor,
+    pkField,
+    profilingCtx,
+  } = 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,
+      })
+    : buildRelationQuery({
+        parentModelMeta,
+        relationMeta,
+        relatedModelMeta,
+        parentIds,
+        args: nestedArgs,
+        allModelsMeta,
+      });
+
+  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);
+  }
+
+  // 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(", ");
+
+  const text = `SELECT ${columnsSql}, ${table}."${refDbName}" AS "__vibeorm_pk" FROM ${table} WHERE ${table}."${refDbName}" = ANY($1)`;
+
+    const t0 = profilingCtx ? performance.now() : 0;
+    const rows = await executor({ text, values: [new PgArray(fkValues)] });
+    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);
+  }
+
+  // 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;
+}): Promise<void> {
+  const {
+    parentRecords,
+    parentModelMeta,
+    relationMeta,
+    relatedModelMeta,
+    parentIds,
+    nestedArgs,
+    allModelsMeta,
+    executor,
+    pkField,
+    profilingCtx,
+  } = params;
+
+  const query = buildRelationQuery({
+    parentModelMeta,
+    relationMeta,
+    relatedModelMeta,
+    parentIds,
+    args: nestedArgs,
+    allModelsMeta,
+  });
+
+  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);
+  }
+
+  // Stitch
+  for (const parent of parentRecords) {
+    const parentId = parent[pkField];
+    parent[relationMeta.name] = byFk.get(parentId) ?? null;
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+type RelationToLoad = {
+  relationMeta: RelationFieldMeta;
+  nestedArgs: Record<string, unknown>;
+};
+
+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;
+}
+
+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; autoIncluded?: boolean }[] {
+  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 hasNested = Object.entries(select).some(([key, val]) => {
+    if (typeof val !== "object" || val === null) return false;
+    return modelMeta.relationFields.some((r) => r.name === key);
+  });
+
+  if (hasNested) {
+    // Auto-include PK fields if not already selected
+    for (const pkName of modelMeta.primaryKey) {
+      if (!columns.some((c) => c.name === pkName)) {
+        const sf = modelMeta.scalarFields.find((f) => f.name === pkName);
+        if (sf) {
+          columns.push({ name: sf.name, dbName: sf.dbName, autoIncluded: true });
+        }
+      }
+    }
+  }
+
+  return columns;
+}