@vibeorm/runtime 1.0.2 → 1.1.1

package/src/lateral-join-builder.ts

@@ -37,13 +37,20 @@ import type {
 } from "./types.ts";
 import { getScalarFieldMap, getModelByNameMap } from "./types.ts";
 import { buildWhereClause } from "./where-builder.ts";
-import { loadRelations } from "./relation-loader.ts";
+import { sanitizeDirection } from "./query-builder.ts";
+import { loadRelations, resolveRelationsToLoad, hasNestedRelations } from "./relation-loader.ts";
+import type { RelationToLoad } from "./relation-loader.ts";
 
 type SqlExecutor = (params: {
   text: string;
   values: unknown[];
 }) => Promise<Record<string, unknown>[]>;
 
+function reverseDirection(params: { direction: string }): string {
+  const normalized = sanitizeDirection({ direction: params.direction });
+  return normalized === "ASC" ? "DESC" : "ASC";
+}
+
 // ─── Query Builder ────────────────────────────────────────────────
 
 /**
@@ -55,8 +62,9 @@ export function buildLateralJoinQuery(params: {
   allModelsMeta: ModelMetaMap;
   args: Record<string, unknown>;
   relationsToLoad: RelationToLoad[];
+  defaultOrderByPk?: boolean;
 }): { query: SqlQuery; relationAliases: RelationAlias[] } {
-  const { modelMeta, allModelsMeta, args, relationsToLoad } = params;
+  const { modelMeta, allModelsMeta, args, relationsToLoad, defaultOrderByPk = false } = params;
   const table = `"${modelMeta.dbName}"`;
   const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
   const modelMap = getModelByNameMap({ allModelsMeta });
@@ -87,6 +95,71 @@ export function buildLateralJoinQuery(params: {
   const allValues: unknown[] = [];
   let paramIdx = 0;
 
+  const take = typeof args.take === "number" ? (args.take as number) : undefined;
+  const isBackwardCursor = args.cursor !== undefined && take !== undefined && take < 0;
+
+  // Build WHERE — start with explicit where, then merge cursor conditions.
+  let where = args.where as Record<string, unknown> | undefined;
+  if (args.cursor) {
+    const cursorInput = args.cursor as Record<string, unknown>;
+    const cursorEntries = Object.entries(cursorInput).filter(([, v]) => v !== undefined);
+
+    const orderByDirMap = new Map<string, string>();
+    if (args.orderBy) {
+      const orderByItems = Array.isArray(args.orderBy)
+        ? (args.orderBy as Record<string, unknown>[])
+        : [args.orderBy as Record<string, unknown>];
+      for (const item of orderByItems) {
+        for (const [field, dir] of Object.entries(item)) {
+          if (!sfMap.has(field)) continue;
+          if (typeof dir === "string") {
+            orderByDirMap.set(field, dir.toUpperCase());
+          }
+        }
+      }
+    }
+
+    const cmpOpForField = (field: string): string => {
+      const dir = orderByDirMap.get(field) ?? "ASC";
+      const isDesc = dir === "DESC";
+      return (isDesc !== isBackwardCursor) ? "lt" : "gt";
+    };
+
+    let cursorWhere: Record<string, unknown> | undefined;
+    if (cursorEntries.length === 1) {
+      const [field, value] = cursorEntries[0]!;
+      if (!sfMap.has(field)) {
+        throw new Error(`Unknown field "${field}" in cursor for model "${modelMeta.name}"`);
+      }
+      cursorWhere = { [field]: { [cmpOpForField(field)]: value } };
+    } else if (cursorEntries.length > 1) {
+      const orBranches: Record<string, unknown>[] = [];
+      for (let i = 0; i < cursorEntries.length; i++) {
+        const branch: Record<string, unknown> = {};
+        for (let j = 0; j < i; j++) {
+          const [eqField, eqValue] = cursorEntries[j]!;
+          if (!sfMap.has(eqField)) {
+            throw new Error(`Unknown field "${eqField}" in cursor for model "${modelMeta.name}"`);
+          }
+          branch[eqField] = { equals: eqValue };
+        }
+        const [cmpField, cmpValue] = cursorEntries[i]!;
+        if (!sfMap.has(cmpField)) {
+          throw new Error(`Unknown field "${cmpField}" in cursor for model "${modelMeta.name}"`);
+        }
+        branch[cmpField] = { [cmpOpForField(cmpField)]: cmpValue };
+        orBranches.push(branch);
+      }
+      cursorWhere = { OR: orBranches };
+    }
+
+    if (cursorWhere) {
+      where = where
+        ? { AND: [where, cursorWhere] }
+        : cursorWhere;
+    }
+  }
+
   // Build LATERAL JOINs for each relation
   const lateralJoins: string[] = [];
   const lateralSelects: string[] = [];
@@ -127,25 +200,20 @@ export function buildLateralJoinQuery(params: {
       // Nested where filter from include/select args
       let nestedWhereSql = "";
       if (nestedArgs.where) {
-        // Build nested where using __rel alias for the related model
+        // Build nested where using __rel alias for the related model.
+        // This avoids brittle regex rewrites of generated SQL table refs.
         const relMetaWithAlias = {
           ...relatedModelMeta,
-          dbName: "__rel" as string, // temporarily override for SQL generation
-        } as unknown as typeof relatedModelMeta;
-        // We can't easily re-alias, so build with original and replace table ref
+          dbName: "__rel",
+        } as typeof relatedModelMeta;
         const nestedWhereResult = buildWhereClause({
           where: nestedArgs.where as Record<string, unknown>,
-          modelMeta: relatedModelMeta,
+          modelMeta: relMetaWithAlias,
           allModelsMeta,
           paramOffset: paramIdx,
         });
         if (nestedWhereResult.sql) {
-          // Replace "TableName". with __rel. for the subquery alias
-          const aliasedSql = nestedWhereResult.sql.replace(
-            new RegExp(`"${relatedModelMeta.dbName}"\\."`, "g"),
-            `__rel."`
-          );
-          nestedWhereSql = ` AND ${aliasedSql}`;
+          nestedWhereSql = ` AND ${nestedWhereResult.sql}`;
           paramIdx += nestedWhereResult.values.length;
           allValues.push(...nestedWhereResult.values);
         }
@@ -160,21 +228,42 @@ export function buildLateralJoinQuery(params: {
           : [nestedArgs.orderBy as Record<string, string>];
         const clauses = orderByItems.flatMap((item) =>
           Object.entries(item).map(([field, dir]) => {
+            if (typeof dir !== "string") {
+              throw new Error(
+                `Unsupported nested orderBy direction for field "${field}" on relation "${relationMeta.name}"`
+              );
+            }
             const sf = relatedSfMap.get(field);
-            const col = sf ? sf.dbName : field;
-            return `__rel."${col}" ${(dir as string).toUpperCase()}`;
+            if (!sf) {
+              throw new Error(
+                `Unknown nested orderBy field "${field}" on relation "${relationMeta.name}"`
+              );
+            }
+            return `__rel."${sf.dbName}" ${sanitizeDirection({ direction: dir })}`;
           })
         );
         if (clauses.length > 0) {
           orderBySql = ` ORDER BY ${clauses.join(", ")}`;
         }
+      } else if (defaultOrderByPk) {
+        // Default ORDER BY PK for deterministic array ordering in jsonb_agg
+        const pkOrderClauses: string[] = [];
+        for (const rpkName of relatedModelMeta.primaryKey) {
+          const rpkSf = relatedSfMap.get(rpkName);
+          if (rpkSf) {
+            pkOrderClauses.push(`__rel."${rpkSf.dbName}" ASC`);
+          }
+        }
+        if (pkOrderClauses.length > 0) {
+          orderBySql = ` ORDER BY ${pkOrderClauses.join(", ")}`;
+        }
       }
 
       let limitSql = "";
       if (nestedArgs.take !== undefined) {
         paramIdx++;
         limitSql = ` LIMIT $${paramIdx}`;
-        allValues.push(nestedArgs.take);
+        allValues.push(Math.abs(nestedArgs.take as number));
       }
 
       let offsetSql = "";
@@ -234,7 +323,7 @@ export function buildLateralJoinQuery(params: {
 
   // Build WHERE from args
   const whereResult = buildWhereClause({
-    where: args.where as Record<string, unknown> | undefined,
+    where,
     modelMeta,
     allModelsMeta,
     paramOffset: paramIdx,
@@ -251,23 +340,59 @@ export function buildLateralJoinQuery(params: {
 
     const orderClauses = orderByItems.flatMap((item) =>
       Object.entries(item).map(([field, direction]) => {
+        if (typeof direction !== "string") {
+          throw new Error(
+            `Unsupported orderBy direction for field "${field}" on model "${modelMeta.name}"`
+          );
+        }
         const scalarField = sfMap.get(field);
-        const col = scalarField ? scalarField.dbName : field;
-        return `${table}."${col}" ${direction.toUpperCase()}`;
+        if (!scalarField) {
+          throw new Error(`Unknown orderBy field "${field}" on model "${modelMeta.name}"`);
+        }
+        const resolvedDirection = isBackwardCursor
+          ? reverseDirection({ direction })
+          : direction;
+        return `${table}."${scalarField.dbName}" ${sanitizeDirection({ direction: resolvedDirection })}`;
       })
     );
 
     if (orderClauses.length > 0) {
       orderBySql = ` ORDER BY ${orderClauses.join(", ")}`;
     }
+  } else if (args.cursor) {
+    const cursorInput = args.cursor as Record<string, unknown>;
+    const cursorEntries = Object.entries(cursorInput).filter(([, v]) => v !== undefined);
+    const defaultDir = isBackwardCursor ? "DESC" : "ASC";
+    const cursorOrderClauses = cursorEntries.map(([field]) => {
+      const sf = sfMap.get(field);
+      if (!sf) {
+        throw new Error(`Unknown field "${field}" in cursor for model "${modelMeta.name}"`);
+      }
+      return `${table}."${sf.dbName}" ${defaultDir}`;
+    });
+    if (cursorOrderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${cursorOrderClauses.join(", ")}`;
+    }
+  } else if (defaultOrderByPk) {
+    // Default ORDER BY primary key for deterministic results
+    const pkOrderClauses: string[] = [];
+    for (const pn of modelMeta.primaryKey) {
+      const pSf = sfMap.get(pn);
+      if (pSf) {
+        pkOrderClauses.push(`${table}."${pSf.dbName}" ASC`);
+      }
+    }
+    if (pkOrderClauses.length > 0) {
+      orderBySql = ` ORDER BY ${pkOrderClauses.join(", ")}`;
+    }
   }
 
   // Build LIMIT / OFFSET
   let limitSql = "";
-  if (args.take !== undefined) {
+  if (take !== undefined) {
     paramIdx++;
     limitSql = ` LIMIT $${paramIdx}`;
-    allValues.push(args.take);
+    allValues.push(Math.abs(take));
   }
 
   let offsetSql = "";
@@ -295,7 +420,7 @@ export function buildLateralJoinQuery(params: {
   // lateral joins. Without it Postgres may evaluate every lateral for
   // every candidate row before the LIMIT prunes the result set.
   const hasRelFilter = whereHasRelationFilter({
-    where: args.where as Record<string, unknown> | undefined,
+    where,
     modelMeta,
   });
   const hasHeavyIncludes =
@@ -342,8 +467,9 @@ export async function executeLateralJoinQuery(params: {
   args: Record<string, unknown>;
   executor: SqlExecutor;
   profilingCtx?: ProfilingContext;
+  defaultOrderByPk?: boolean;
 }): Promise<Record<string, unknown>[]> {
-  const { modelMeta, allModelsMeta, args, executor, profilingCtx } = params;
+  const { modelMeta, allModelsMeta, args, executor, profilingCtx, defaultOrderByPk = false } = params;
   const profiling = !!profilingCtx;
 
   const t0 = profiling ? performance.now() : 0;
@@ -364,6 +490,7 @@ export async function executeLateralJoinQuery(params: {
     allModelsMeta,
     args,
     relationsToLoad,
+    defaultOrderByPk,
   });
 
   const t1 = profiling ? performance.now() : 0;
@@ -464,11 +591,12 @@ export async function loadRelationsWithLateralJoin(params: {
   args: Record<string, unknown>;
   executor: SqlExecutor;
   profilingCtx?: ProfilingContext;
+  defaultOrderByPk?: boolean;
 }): Promise<Record<string, unknown>[]> {
   // For the post-processing path (create, update, etc.), we still need
   // the 2-query approach since the parent records are already fetched.
   // But we can use the lateral join to load relations in 1 query instead of N.
-  const { parentRecords, parentModelMeta, allModelsMeta, args, executor, profilingCtx } = params;
+  const { parentRecords, parentModelMeta, allModelsMeta, args, executor, profilingCtx, defaultOrderByPk = false } = params;
 
   if (parentRecords.length === 0) return parentRecords;
 
@@ -505,6 +633,7 @@ export async function loadRelationsWithLateralJoin(params: {
     allModelsMeta,
     args: syntheticArgs,
     relationsToLoad,
+    defaultOrderByPk,
   });
 
   const rows = await executor(query);
@@ -581,67 +710,12 @@ export async function loadRelationsWithLateralJoin(params: {
 
 // ─── Helpers ──────────────────────────────────────────────────────
 
-type RelationToLoad = {
-  relationMeta: RelationFieldMeta;
-  nestedArgs: Record<string, unknown>;
-};
-
 type RelationAlias = {
   alias: string;
   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;
-}
-
-function hasNestedRelations(params: { nestedArgs: Record<string, unknown> }): boolean {
-  const { nestedArgs } = params;
-  return (
-    nestedArgs.include !== undefined ||
-    (typeof nestedArgs.select === "object" && nestedArgs.select !== null)
-  );
-}
-
 /**
  * Check whether a Prisma-style where object references any relation field
  * on the given model. Walks AND / OR / NOT combinators recursively.
@@ -701,15 +775,17 @@ function resolveRelatedScalars(params: {
   const omitArg = nestedArgs.omit as Record<string, boolean> | undefined;
 
   if (selectArg) {
+    const sfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
     const selected = relatedModelMeta.scalarFields.filter((f) => {
       const val = selectArg[f.name];
       return val === true || (typeof val === "object" && val !== null);
     });
 
     // Always include PK for relation stitching
+    const selectedNames = new Set(selected.map((f) => f.name));
     for (const pkName of relatedModelMeta.primaryKey) {
-      if (!selected.some((f) => f.name === pkName)) {
-        const sf = relatedModelMeta.scalarFields.find((f) => f.name === pkName);
+      if (!selectedNames.has(pkName)) {
+        const sf = sfMap.get(pkName);
         if (sf) selected.push(sf);
       }
     }