@vibeorm/runtime 1.0.2 → 1.1.1

package/src/relation-loader.ts

@@ -18,6 +18,7 @@ import type {
 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";
 
 type SqlExecutor = (params: {
   text: string;
@@ -41,8 +42,9 @@ export async function loadRelations(params: {
   args: Record<string, unknown>;
   executor: SqlExecutor;
   profilingCtx?: ProfilingContext;
+  defaultOrderByPk?: boolean;
 }): Promise<Record<string, unknown>[]> {
-  const { parentRecords, parentModelMeta, allModelsMeta, args, executor, profilingCtx } =
+  const { parentRecords, parentModelMeta, allModelsMeta, args, executor, profilingCtx, defaultOrderByPk = false } =
     params;
 
   if (parentRecords.length === 0) return parentRecords;
@@ -86,6 +88,7 @@ export async function loadRelations(params: {
           executor,
           pkField,
           profilingCtx,
+          defaultOrderByPk,
         });
       } else if (relationMeta.isForeignKey) {
         await loadToOneWithFk({
@@ -110,6 +113,7 @@ export async function loadRelations(params: {
           executor,
           pkField,
           profilingCtx,
+          defaultOrderByPk,
         });
       }
     })
@@ -173,6 +177,7 @@ async function loadToManyRelation(params: {
   executor: SqlExecutor;
   pkField: string;
   profilingCtx?: ProfilingContext;
+  defaultOrderByPk?: boolean;
 }): Promise<void> {
   const {
     parentRecords,
@@ -185,6 +190,7 @@ async function loadToManyRelation(params: {
     executor,
     pkField,
     profilingCtx,
+    defaultOrderByPk = false,
   } = params;
 
   // Choose builder based on relation type
@@ -198,6 +204,7 @@ async function loadToManyRelation(params: {
         parentIds,
         args: nestedArgs,
         allModelsMeta,
+        defaultOrderByPk,
       })
     : buildRelationQuery({
         parentModelMeta,
@@ -206,6 +213,7 @@ async function loadToManyRelation(params: {
         parentIds,
         args: nestedArgs,
         allModelsMeta,
+        defaultOrderByPk,
       });
 
   const t0 = profilingCtx ? performance.now() : 0;
@@ -296,18 +304,38 @@ async function loadToOneWithFk(params: {
     .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,
-      });
+  // 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>>();
@@ -337,6 +365,7 @@ async function loadToOneWithoutFk(params: {
   executor: SqlExecutor;
   pkField: string;
   profilingCtx?: ProfilingContext;
+  defaultOrderByPk?: boolean;
 }): Promise<void> {
   const {
     parentRecords,
@@ -349,6 +378,7 @@ async function loadToOneWithoutFk(params: {
     executor,
     pkField,
     profilingCtx,
+    defaultOrderByPk = false,
   } = params;
 
   const query = buildRelationQuery({
@@ -358,6 +388,7 @@ async function loadToOneWithoutFk(params: {
     parentIds,
     args: nestedArgs,
     allModelsMeta,
+    defaultOrderByPk,
   });
 
   const t0 = profilingCtx ? performance.now() : 0;
@@ -389,12 +420,12 @@ async function loadToOneWithoutFk(params: {
 
 // ─── Helpers ──────────────────────────────────────────────────────
 
-type RelationToLoad = {
+export type RelationToLoad = {
   relationMeta: RelationFieldMeta;
   nestedArgs: Record<string, unknown>;
 };
 
-function resolveRelationsToLoad(params: {
+export function resolveRelationsToLoad(params: {
   parentModelMeta: ModelMeta;
   args: Record<string, unknown>;
 }): RelationToLoad[] {
@@ -436,7 +467,7 @@ function resolveRelationsToLoad(params: {
   return result;
 }
 
-function hasNestedRelations(params: {
+export function hasNestedRelations(params: {
   nestedArgs: Record<string, unknown>;
 }): boolean {
   const { nestedArgs } = params;
@@ -449,7 +480,7 @@ function hasNestedRelations(params: {
 function resolveSelectColumnsForRelation(params: {
   modelMeta: ModelMeta;
   args: Record<string, unknown>;
-}): { name: string; dbName: string; autoIncluded?: boolean }[] {
+}): { name: string; dbName: string }[] {
   const { modelMeta, args } = params;
   const select = args.select as Record<string, boolean | object> | undefined;
 
@@ -468,18 +499,21 @@ function resolveSelectColumnsForRelation(params: {
     .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 modelMeta.relationFields.some((r) => r.name === key);
+    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 (!columns.some((c) => c.name === pkName)) {
-        const sf = modelMeta.scalarFields.find((f) => f.name === pkName);
+      if (!selectedNames.has(pkName)) {
+        const sf = sfMap.get(pkName);
         if (sf) {
-          columns.push({ name: sf.name, dbName: sf.dbName, autoIncluded: true });
+          columns.push({ name: sf.name, dbName: sf.dbName });
         }
       }
     }

package/src/types.ts

@@ -27,6 +27,9 @@ export type VibeClientOptions = {
    *   PlanetScale, Supabase pooler) but disables parallel workers on standard
    *   PostgreSQL. Use this if count queries are consistently slow on your
    *   remote database.
+   *
+   * This can be overridden per operation with:
+   * `db.model.count({ where: {...}, countStrategy: "subquery" })`.
    */
   countStrategy?: "direct" | "subquery";
   /**
@@ -62,6 +65,28 @@ export type VibeClientOptions = {
    * ```
    */
   idGenerator?: (params: { model: string; field: string; defaultKind: string }) => string;
+  /**
+   * Add primary key as a default ORDER BY fallback when no explicit orderBy is given.
+   * Applies to: findMany, findFirst, relation loading (query + lateral join strategies).
+   * Does NOT affect: findUnique, create, update, delete, count, aggregate, groupBy.
+   *
+   * When enabled, queries without an explicit `orderBy` will append
+   * `ORDER BY "Table"."pk" ASC` to produce deterministic result ordering.
+   *
+   * @default false
+   */
+  defaultOrderByPk?: boolean;
+  /**
+   * Add primary key as a tie-breaker in DISTINCT ON queries when the user
+   * doesn't provide a secondary orderBy beyond the distinct columns.
+   * This ensures deterministic row selection per distinct group.
+   *
+   * When disabled, DISTINCT ON returns an arbitrary row per group
+   * (standard PostgreSQL behaviour).
+   *
+   * @default true
+   */
+  distinctOrderByPk?: boolean;
   /**
    * Enable per-query profiling with detailed timing breakdowns.
    * - false (default): no profiling — zero runtime overhead

package/src/where-builder.ts

@@ -145,6 +145,9 @@ export function buildWhereClause(params: {
       }
       continue;
     }
+
+    const modelLabel = modelMeta.name ?? modelMeta.dbName;
+    throw new Error(`Unknown filter field "${key}" for model "${modelLabel}"`);
   }
 
   const sql = conditions.length > 0 ? conditions.join(" AND ") : "";
@@ -209,6 +212,7 @@ function buildRelationFilter(params: {
     // To-many: some / none / every / shorthand
     return buildToManyRelationFilter({
       filter,
+      relationName: relationField.name,
       relatedModelMeta,
       relatedTable,
       relatedFrom,
@@ -221,6 +225,7 @@ function buildRelationFilter(params: {
     // To-one: is / isNot / shorthand (treated as "is")
     return buildToOneRelationFilter({
       filter,
+      relationName: relationField.name,
       parentModelMeta,
       relationField,
       relatedModelMeta,
@@ -237,6 +242,7 @@ function buildRelationFilter(params: {
 
 function buildToManyRelationFilter(params: {
   filter: Record<string, unknown>;
+  relationName: string;
   relatedModelMeta: ModelMeta;
   relatedTable: string;
   relatedFrom: string;
@@ -245,7 +251,7 @@ function buildToManyRelationFilter(params: {
   paramIdx: number;
   ctx: WhereContext;
 }): WhereClause {
-  const { filter, relatedModelMeta, relatedTable, relatedFrom, joinCondition, allModelsMeta, paramIdx, ctx } = params;
+  const { filter, relationName, relatedModelMeta, relatedTable, relatedFrom, joinCondition, allModelsMeta, paramIdx, ctx } = params;
 
   // For self-referential relations, create a modelMeta copy with the alias as dbName
   // so nested buildWhereClause generates column refs using the alias
@@ -311,6 +317,10 @@ function buildToManyRelationFilter(params: {
         );
         break; // We consumed the entire filter object
       }
+
+      throw new Error(
+        `Unsupported relation filter key "${op}" on list relation "${relationName}"`
+      );
     }
   }
 
@@ -322,6 +332,7 @@ function buildToManyRelationFilter(params: {
 
 function buildToOneRelationFilter(params: {
   filter: Record<string, unknown>;
+  relationName: string;
   parentModelMeta: ModelMeta;
   relationField: RelationFieldMeta;
   relatedModelMeta: ModelMeta;
@@ -334,7 +345,7 @@ function buildToOneRelationFilter(params: {
   ctx: WhereContext;
 }): WhereClause {
   const {
-    filter, parentModelMeta, relationField, relatedModelMeta,
+    filter, relationName, parentModelMeta, relationField, relatedModelMeta,
     parentTable, relatedTable, relatedFrom, joinCondition, allModelsMeta, paramIdx, ctx,
   } = params;
 
@@ -426,6 +437,10 @@ function buildToOneRelationFilter(params: {
         );
         break; // Consumed the whole filter
       }
+
+      throw new Error(
+        `Unsupported relation filter key "${op}" on relation "${relationName}"`
+      );
     }
   }
 
@@ -488,6 +503,20 @@ function resolveJoinCondition(params: {
   return `${relatedAlias}."${fkGuess}" = ${parentAlias}."${pkDbName}"`;
 }
 
+// ─── LIKE Escape Helper ───────────────────────────────────────────
+
+/**
+ * Escape SQL LIKE/ILIKE wildcard characters (% and _) in a user-supplied
+ * string so they are treated as literal characters. Uses backslash as the
+ * escape character — the generated LIKE clause MUST include `ESCAPE '\'`.
+ */
+function escapeLikePattern(params: { value: string }): string {
+  return params.value
+    .replace(/\\/g, "\\\\")
+    .replace(/%/g, "\\%")
+    .replace(/_/g, "\\_");
+}
+
 // ─── Scalar Filter Compiler ───────────────────────────────────────
 
 function buildScalarFilter(params: {
@@ -603,22 +632,25 @@ function buildScalarFilter(params: {
         case "contains": {
           idx++;
           const mode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
-          conditions.push(`${col} ${mode} $${idx}`);
-          values.push(`%${operand}%`);
+          const escaped = escapeLikePattern({ value: operand as string });
+          conditions.push(`${col} ${mode} $${idx} ESCAPE '\\'`);
+          values.push(`%${escaped}%`);
           break;
         }
         case "startsWith": {
           idx++;
           const mode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
-          conditions.push(`${col} ${mode} $${idx}`);
-          values.push(`${operand}%`);
+          const escaped = escapeLikePattern({ value: operand as string });
+          conditions.push(`${col} ${mode} $${idx} ESCAPE '\\'`);
+          values.push(`${escaped}%`);
           break;
         }
         case "endsWith": {
           idx++;
           const mode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
-          conditions.push(`${col} ${mode} $${idx}`);
-          values.push(`%${operand}`);
+          const escaped = escapeLikePattern({ value: operand as string });
+          conditions.push(`${col} ${mode} $${idx} ESCAPE '\\'`);
+          values.push(`%${escaped}`);
           break;
         }
         case "mode":
@@ -633,40 +665,43 @@ function buildScalarFilter(params: {
         case "string_contains": {
           const path = filter.path as string[] | undefined;
           const jsonCol = path && path.length > 0
-            ? `(${col}${path.map((p) => `->>'${p}'`).join("")})`
+            ? `(${col}${path.map((p) => `->>` + `'${p.replace(/'/g, "''")}'`).join("")})`
             : `(${col}#>>'{}')`;
           idx++;
           const jmode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
-          conditions.push(`${jsonCol} ${jmode} $${idx}`);
-          values.push(`%${operand}%`);
+          const escaped = escapeLikePattern({ value: operand as string });
+          conditions.push(`${jsonCol} ${jmode} $${idx} ESCAPE '\\'`);
+          values.push(`%${escaped}%`);
           break;
         }
         case "string_starts_with": {
           const path = filter.path as string[] | undefined;
           const jsonCol = path && path.length > 0
-            ? `(${col}${path.map((p) => `->>'${p}'`).join("")})`
+            ? `(${col}${path.map((p) => `->>` + `'${p.replace(/'/g, "''")}'`).join("")})`
             : `(${col}#>>'{}')`;
           idx++;
           const jmode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
-          conditions.push(`${jsonCol} ${jmode} $${idx}`);
-          values.push(`${operand}%`);
+          const escaped = escapeLikePattern({ value: operand as string });
+          conditions.push(`${jsonCol} ${jmode} $${idx} ESCAPE '\\'`);
+          values.push(`${escaped}%`);
           break;
         }
         case "string_ends_with": {
           const path = filter.path as string[] | undefined;
           const jsonCol = path && path.length > 0
-            ? `(${col}${path.map((p) => `->>'${p}'`).join("")})`
+            ? `(${col}${path.map((p) => `->>` + `'${p.replace(/'/g, "''")}'`).join("")})`
             : `(${col}#>>'{}')`;
           idx++;
           const jmode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
-          conditions.push(`${jsonCol} ${jmode} $${idx}`);
-          values.push(`%${operand}`);
+          const escaped = escapeLikePattern({ value: operand as string });
+          conditions.push(`${jsonCol} ${jmode} $${idx} ESCAPE '\\'`);
+          values.push(`%${escaped}`);
           break;
         }
         case "array_contains": {
           const path = filter.path as string[] | undefined;
           const target = path && path.length > 0
-            ? `${col}${path.map((p) => `->'${p}'`).join("")}`
+            ? `${col}${path.map((p) => `->'${p.replace(/'/g, "''")}'`).join("")}`
             : col;
           idx++;
           conditions.push(`${target} @> $${idx}::jsonb`);
@@ -676,7 +711,7 @@ function buildScalarFilter(params: {
         case "array_starts_with": {
           const path = filter.path as string[] | undefined;
           const target = path && path.length > 0
-            ? `${col}${path.map((p) => `->'${p}'`).join("")}`
+            ? `${col}${path.map((p) => `->'${p.replace(/'/g, "''")}'`).join("")}`
             : col;
           idx++;
           conditions.push(`${target}->0 = $${idx}::jsonb`);
@@ -686,7 +721,7 @@ function buildScalarFilter(params: {
         case "array_ends_with": {
           const path = filter.path as string[] | undefined;
           const target = path && path.length > 0
-            ? `${col}${path.map((p) => `->'${p}'`).join("")}`
+            ? `${col}${path.map((p) => `->'${p.replace(/'/g, "''")}'`).join("")}`
             : col;
           idx++;
           conditions.push(`${target}->-1 = $${idx}::jsonb`);
@@ -723,7 +758,7 @@ function buildScalarFilter(params: {
         }
 
         default:
-          break;
+          throw new Error(`Unsupported scalar filter operator "${op}" for ${col}`);
       }
     }