@vibeorm/runtime 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/runtime",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Driver-agnostic query engine and client runtime for VibeORM",
   "license": "MIT",
   "keywords": [

package/src/client.ts

@@ -615,6 +615,18 @@ export function createClient(params: {
           allModelsMeta,
           executor,
         });
+
+        // Re-read the parent record after nested ops to reflect FK changes
+        // (e.g., connect/disconnect may have updated FK columns)
+        const refreshQuery = buildSelectQuery({
+          modelMeta,
+          allModelsMeta,
+          args: { where: whereInput, take: 1 },
+        });
+        const refreshed = await executor(refreshQuery);
+        if (refreshed.length > 0) {
+          records = refreshed;
+        }
       }
 
       records = await loadRelationsForStrategy({
@@ -1032,70 +1044,86 @@ export function createClient(params: {
   ): Promise<T | unknown[]> {
     // Array-of-promises style
     if (Array.isArray(fnOrPromises)) {
-      return adapter.transaction(async () => {
-        return Promise.all(fnOrPromises);
-      }, txOptions);
+      try {
+        return await adapter.transaction(async () => {
+          return Promise.all(fnOrPromises);
+        }, txOptions);
+      } catch (err) {
+        throw normalizeError({ error: err });
+      }
     }
 
     // Callback style
     const fn = fnOrPromises as (tx: Record<string, unknown>) => Promise<T>;
-    return adapter.transaction(async (txAdapter) => {
-      // Create a transactional executor — normalizes DB errors
-      async function txExecutor(txParams: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
-        const values = txParams.values.map((v) => (v instanceof PgArray ? txAdapter.formatArrayParam(v.values) : v));
-        if (shouldLog) {
-          console.log(`[vibeorm:tx] ${txParams.text}`);
-          if (values.length > 0) {
-            console.log(`[vibeorm:tx] params:`, values);
+    try {
+      return await adapter.transaction(async (txAdapter) => {
+        // Create a transactional executor — normalizes DB errors
+        async function txExecutor(txParams: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
+          const values = txParams.values.map((v) => (v instanceof PgArray ? txAdapter.formatArrayParam(v.values) : v));
+          if (shouldLog) {
+            console.log(`[vibeorm:tx] ${txParams.text}`);
+            if (values.length > 0) {
+              console.log(`[vibeorm:tx] params:`, values);
+            }
+          }
+          try {
+            return await txAdapter.execute({ text: txParams.text, values });
+          } catch (err) {
+            throw normalizeError({ error: err });
           }
         }
-        try {
-          return await txAdapter.execute({ text: txParams.text, values });
-        } catch (err) {
-          throw normalizeError({ error: err });
-        }
-      }
-
-      // Build transactional delegates
-      const txClient: Record<string, unknown> = {};
-      for (const [key, meta] of Object.entries(allModelsMeta)) {
-        txClient[key] = createDelegate({
-          modelKey: key,
-          modelMeta: meta,
-          executor: txExecutor,
-          schemas: params.schemas?.[key],
-        });
-      }
 
-      // Add $queryRaw and $executeRaw to transactional client
-      txClient.$queryRaw = async function <T = unknown>(
-        strings: TemplateStringsArray,
-        ...values: unknown[]
-      ): Promise<T[]> {
-        const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
-        if (shouldLog) {
-          console.log(`[vibeorm:tx] ${text}`);
-          if (sqlParams.length > 0) console.log(`[vibeorm:tx] params:`, sqlParams);
+        // Build transactional delegates
+        const txClient: Record<string, unknown> = {};
+        for (const [key, meta] of Object.entries(allModelsMeta)) {
+          txClient[key] = createDelegate({
+            modelKey: key,
+            modelMeta: meta,
+            executor: txExecutor,
+            schemas: params.schemas?.[key],
+          });
         }
-        const result = await txAdapter.executeUnsafe({ text, values: sqlParams });
-        return result.rows as T[];
-      };
 
-      txClient.$executeRaw = async function (
-        strings: TemplateStringsArray,
-        ...values: unknown[]
-      ): Promise<number> {
-        const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
-        if (shouldLog) {
-          console.log(`[vibeorm:tx] ${text}`);
-          if (sqlParams.length > 0) console.log(`[vibeorm:tx] params:`, sqlParams);
-        }
-        const result = await txAdapter.executeUnsafe({ text, values: sqlParams });
-        return result.affectedRows;
-      };
+        // Add $queryRaw and $executeRaw to transactional client
+        txClient.$queryRaw = async function <T = unknown>(
+          strings: TemplateStringsArray,
+          ...values: unknown[]
+        ): Promise<T[]> {
+          const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
+          if (shouldLog) {
+            console.log(`[vibeorm:tx] ${text}`);
+            if (sqlParams.length > 0) console.log(`[vibeorm:tx] params:`, sqlParams);
+          }
+          try {
+            const result = await txAdapter.executeUnsafe({ text, values: sqlParams });
+            return result.rows as T[];
+          } catch (err) {
+            throw normalizeError({ error: err });
+          }
+        };
 
-      return fn(txClient);
-    }, txOptions);
+        txClient.$executeRaw = async function (
+          strings: TemplateStringsArray,
+          ...values: unknown[]
+        ): Promise<number> {
+          const { text, params: sqlParams } = buildTaggedTemplateSql({ strings, values });
+          if (shouldLog) {
+            console.log(`[vibeorm:tx] ${text}`);
+            if (sqlParams.length > 0) console.log(`[vibeorm:tx] params:`, sqlParams);
+          }
+          try {
+            const result = await txAdapter.executeUnsafe({ text, values: sqlParams });
+            return result.affectedRows;
+          } catch (err) {
+            throw normalizeError({ error: err });
+          }
+        };
+
+        return fn(txClient);
+      }, txOptions);
+    } catch (err) {
+      throw normalizeError({ error: err });
+    }
   };
 
   // $queryRaw — tagged template literal for safe parameterized queries
@@ -1110,8 +1138,12 @@ export function createClient(params: {
         console.log(`[vibeorm:raw] params:`, sqlParams);
       }
     }
-    const result = await adapter.executeUnsafe({ text, values: sqlParams });
-    return result.rows as T[];
+    try {
+      const result = await adapter.executeUnsafe({ text, values: sqlParams });
+      return result.rows as T[];
+    } catch (err) {
+      throw normalizeError({ error: err });
+    }
   };
 
   // $executeRaw — tagged template literal for INSERT/UPDATE/DELETE returning affected count
@@ -1126,8 +1158,12 @@ export function createClient(params: {
         console.log(`[vibeorm:raw] params:`, sqlParams);
       }
     }
-    const result = await adapter.executeUnsafe({ text, values: sqlParams });
-    return result.affectedRows;
+    try {
+      const result = await adapter.executeUnsafe({ text, values: sqlParams });
+      return result.affectedRows;
+    } catch (err) {
+      throw normalizeError({ error: err });
+    }
   };
 
   // $queryRawUnsafe — accepts a plain SQL string + params array
@@ -1141,12 +1177,16 @@ export function createClient(params: {
         console.log(`[vibeorm:raw] params:`, values);
       }
     }
-    if (values.length === 0) {
-      const result = await adapter.executeUnsafe({ text: query });
-      return result.rows as T[];
+    try {
+      if (values.length === 0) {
+        const result = await adapter.executeUnsafe({ text: query });
+        return result.rows as T[];
+      }
+      const rows = await adapter.execute({ text: query, values });
+      return rows as T[];
+    } catch (err) {
+      throw normalizeError({ error: err });
     }
-    const rows = await adapter.execute({ text: query, values });
-    return rows as T[];
   };
 
   // $executeRawUnsafe — accepts a plain SQL string + params array, returns affected count
@@ -1160,8 +1200,12 @@ export function createClient(params: {
         console.log(`[vibeorm:raw] params:`, values);
       }
     }
-    const result = await adapter.executeUnsafe({ text: query, values: values.length > 0 ? values : undefined });
-    return result.affectedRows;
+    try {
+      const result = await adapter.executeUnsafe({ text: query, values: values.length > 0 ? values : undefined });
+      return result.affectedRows;
+    } catch (err) {
+      throw normalizeError({ error: err });
+    }
   };
 
   // $connect
@@ -2073,6 +2117,35 @@ async function processNestedCreates(params: {
             }
           }
         }
+
+        if (ops.connectOrCreate) {
+          // ConnectOrCreate: try to find existing, else create, then set FK on parent
+          const relatedMeta = modelMap.get(relationField.relatedModel);
+          if (relatedMeta) {
+            const { where: corWhere, create: corCreate } = ops.connectOrCreate as {
+              where: Record<string, unknown>;
+              create: Record<string, unknown>;
+            };
+            // Try to find existing record
+            const selectQuery = buildSelectQuery({
+              modelMeta: relatedMeta,
+              allModelsMeta,
+              args: { where: corWhere, take: 1 },
+            });
+            const existingRows = await executor(selectQuery);
+            if (existingRows.length > 0) {
+              processedData[fkField] = existingRows[0]![refField];
+            } else {
+              // Create new record
+              const insertQuery = buildInsertQuery({ modelMeta: relatedMeta, data: corCreate });
+              const insertedRows = await executor(insertQuery);
+              const inserted = insertedRows[0];
+              if (inserted) {
+                processedData[fkField] = inserted[refField];
+              }
+            }
+          }
+        }
       }
       // Case 2: Related model holds the FK (e.g., User.posts where Post has userId)
       else if (!relationField.isForeignKey) {

package/src/lateral-join-builder.ts

@@ -96,6 +96,14 @@ export function buildLateralJoinQuery(params: {
   let paramIdx = 0;
 
   const take = typeof args.take === "number" ? (args.take as number) : undefined;
+
+  // Negative take is only valid with cursor-based pagination (backward page)
+  if (take !== undefined && take < 0 && args.cursor === undefined) {
+    throw new Error(
+      `Negative \`take\` (${take}) is only supported with cursor-based pagination on model "${modelMeta.name}". Provide a \`cursor\` argument or use a positive \`take\` value.`
+    );
+  }
+
   const isBackwardCursor = args.cursor !== undefined && take !== undefined && take < 0;
 
   // Build WHERE — start with explicit where, then merge cursor conditions.
@@ -169,18 +177,12 @@ export function buildLateralJoinQuery(params: {
     const { relationMeta, nestedArgs } = relationsToLoad[i]!;
     const alias = `__lat_${i}`;
     const colAlias = `__vibeorm_rel_${relationMeta.name}`;
+    const relatedAlias = `"__rel"`;
 
     // Find the related model meta
     const relatedModelMeta = modelMap.get(relationMeta.relatedModel);
     if (!relatedModelMeta) continue;
 
-    // Determine FK column and join condition
-    const { fkDbName, fkTable } = resolveFkColumn({
-      parentModelMeta: modelMeta,
-      relationMeta,
-      relatedModelMeta,
-    });
-
     // Build json_build_object fields for the related model.
     // Respect nested select/omit to avoid serialising columns the caller doesn't need.
     const relatedScalars = resolveRelatedScalars({
@@ -188,20 +190,36 @@ export function buildLateralJoinQuery(params: {
       nestedArgs,
     });
     const jsonFields = relatedScalars
-      .map((f) => `'${f.name}', __rel."${f.dbName}"`)
+      .map((f) => `'${f.name}', ${relatedAlias}."${f.dbName}"`)
       .join(", ");
 
     let lateralSubquery: string;
 
-    if (relationMeta.isList) {
-      // To-many: use json_agg with COALESCE for empty arrays
-      const subWhere = `__rel."${fkDbName}" = ${table}."${pkDbName}"`;
+    // ─── M:N relations via junction table ─────────────────────────
+    const isM2M = relationMeta.type === "manyToMany" && (relationMeta as { joinTable?: string }).joinTable;
+
+    if (isM2M) {
+      const jtName = (relationMeta as { joinTable: string }).joinTable;
+      const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+
+      // Determine A vs B column: Prisma implicit junction tables use alphabetical model name order
+      const sorted = [modelMeta.name, relatedModelMeta.name].sort();
+      const parentIsA = modelMeta.name === sorted[0];
+      const parentCol = parentIsA ? "A" : "B";
+      const relatedCol = parentIsA ? "B" : "A";
+
+      // Related model PK for junction join condition
+      const relatedPk = relatedModelMeta.primaryKey[0]!;
+      const relatedPkSf = relatedSfMap.get(relatedPk);
+      const relatedPkDb = relatedPkSf?.dbName ?? relatedPk;
+
+      // Junction join: __jt."B" = __rel."id" WHERE __jt."A" = parent."id"
+      const junctionJoin = `INNER JOIN "${jtName}" __jt ON __jt."${relatedCol}" = ${relatedAlias}."${relatedPkDb}"`;
+      const subWhere = `__jt."${parentCol}" = ${table}."${pkDbName}"`;
 
       // Nested where filter from include/select args
       let nestedWhereSql = "";
       if (nestedArgs.where) {
-        // 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",
@@ -219,8 +237,6 @@ export function buildLateralJoinQuery(params: {
         }
       }
 
-      const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-
       let orderBySql = "";
       if (nestedArgs.orderBy) {
         const orderByItems = Array.isArray(nestedArgs.orderBy)
@@ -239,19 +255,18 @@ export function buildLateralJoinQuery(params: {
                 `Unknown nested orderBy field "${field}" on relation "${relationMeta.name}"`
               );
             }
-            return `__rel."${sf.dbName}" ${sanitizeDirection({ direction: dir })}`;
+            return `${relatedAlias}."${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
+      } else if (defaultOrderByPk || nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
         const pkOrderClauses: string[] = [];
         for (const rpkName of relatedModelMeta.primaryKey) {
           const rpkSf = relatedSfMap.get(rpkName);
           if (rpkSf) {
-            pkOrderClauses.push(`__rel."${rpkSf.dbName}" ASC`);
+            pkOrderClauses.push(`${relatedAlias}."${rpkSf.dbName}" ASC`);
           }
         }
         if (pkOrderClauses.length > 0) {
@@ -276,44 +291,153 @@ export function buildLateralJoinQuery(params: {
       // When take or skip is specified, use a subquery to apply per-parent LIMIT/OFFSET properly
       if (nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
         lateralSubquery = `LEFT JOIN LATERAL (
-    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})), '[]'::jsonb) AS "${colAlias}"
+    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
     FROM (
-      SELECT * FROM "${relatedModelMeta.dbName}" __rel
+      SELECT ${relatedAlias}.* FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+      ${junctionJoin}
       WHERE ${subWhere}${nestedWhereSql}${orderBySql}${limitSql}${offsetSql}
-    ) __rel
+    ) ${relatedAlias}
   ) ${alias} ON true`;
       } else {
         lateralSubquery = `LEFT JOIN LATERAL (
     SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
-    FROM "${relatedModelMeta.dbName}" __rel
+    FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+    ${junctionJoin}
     WHERE ${subWhere}${nestedWhereSql}
   ) ${alias} ON true`;
       }
+
+    // ─── Direct FK relations (1:N, 1:1) ──────────────────────────
     } else {
-      // To-one: use json_build_object with LIMIT 1
-      let joinCondition: string;
-
-      if (fkTable === "parent") {
-        // Parent holds FK (e.g., Post.authorId -> User.id)
-        const parentFkField = relationMeta.fields[0]!;
-        const parentFkScalar = sfMap.get(parentFkField);
-        const parentFkDbName = parentFkScalar?.dbName ?? parentFkField;
-        const refField = relationMeta.references[0]!;
-        const relatedSfMapForOne = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-        const refScalar = relatedSfMapForOne.get(refField);
-        const refDbName = refScalar?.dbName ?? refField;
-        joinCondition = `__rel."${refDbName}" = ${table}."${parentFkDbName}"`;
+      // Determine FK column and join condition
+      const { fkDbName, fkTable } = resolveFkColumn({
+        parentModelMeta: modelMeta,
+        relationMeta,
+        relatedModelMeta,
+      });
+
+      if (relationMeta.isList) {
+        // To-many: use json_agg with COALESCE for empty arrays
+        const subWhere = `${relatedAlias}."${fkDbName}" = ${table}."${pkDbName}"`;
+
+        // Nested where filter from include/select args
+        let nestedWhereSql = "";
+        if (nestedArgs.where) {
+          // 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 typeof relatedModelMeta;
+          const nestedWhereResult = buildWhereClause({
+            where: nestedArgs.where as Record<string, unknown>,
+            modelMeta: relMetaWithAlias,
+            allModelsMeta,
+            paramOffset: paramIdx,
+          });
+          if (nestedWhereResult.sql) {
+            nestedWhereSql = ` AND ${nestedWhereResult.sql}`;
+            paramIdx += nestedWhereResult.values.length;
+            allValues.push(...nestedWhereResult.values);
+          }
+        }
+
+        const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+
+        let orderBySql = "";
+        if (nestedArgs.orderBy) {
+          const orderByItems = Array.isArray(nestedArgs.orderBy)
+            ? (nestedArgs.orderBy as Record<string, string>[])
+            : [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);
+              if (!sf) {
+                throw new Error(
+                  `Unknown nested orderBy field "${field}" on relation "${relationMeta.name}"`
+                );
+              }
+              return `${relatedAlias}."${sf.dbName}" ${sanitizeDirection({ direction: dir })}`;
+            })
+          );
+          if (clauses.length > 0) {
+            orderBySql = ` ORDER BY ${clauses.join(", ")}`;
+          }
+        } else if (defaultOrderByPk || nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
+          // 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(`${relatedAlias}."${rpkSf.dbName}" ASC`);
+            }
+          }
+          if (pkOrderClauses.length > 0) {
+            orderBySql = ` ORDER BY ${pkOrderClauses.join(", ")}`;
+          }
+        }
+
+        let limitSql = "";
+        if (nestedArgs.take !== undefined) {
+          paramIdx++;
+          limitSql = ` LIMIT $${paramIdx}`;
+          allValues.push(Math.abs(nestedArgs.take as number));
+        }
+
+        let offsetSql = "";
+        if (nestedArgs.skip !== undefined) {
+          paramIdx++;
+          offsetSql = ` OFFSET $${paramIdx}`;
+          allValues.push(nestedArgs.skip);
+        }
+
+        // When take or skip is specified, use a subquery to apply per-parent LIMIT/OFFSET properly
+        if (nestedArgs.take !== undefined || nestedArgs.skip !== undefined) {
+          lateralSubquery = `LEFT JOIN LATERAL (
+    SELECT COALESCE(jsonb_agg(json_build_object(${jsonFields})${orderBySql}), '[]'::jsonb) AS "${colAlias}"
+    FROM (
+      SELECT * FROM "${relatedModelMeta.dbName}" ${relatedAlias}
+      WHERE ${subWhere}${nestedWhereSql}${orderBySql}${limitSql}${offsetSql}
+    ) ${relatedAlias}
+  ) ${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}
+  ) ${alias} ON true`;
+        }
       } else {
-        // Related model holds FK (e.g., User.profile -> Profile.userId)
-        joinCondition = `__rel."${fkDbName}" = ${table}."${pkDbName}"`;
-      }
+        // To-one: use json_build_object with LIMIT 1
+        let joinCondition: string;
+
+        if (fkTable === "parent") {
+          // Parent holds FK (e.g., Post.authorId -> User.id)
+          const parentFkField = relationMeta.fields[0]!;
+          const parentFkScalar = sfMap.get(parentFkField);
+          const parentFkDbName = parentFkScalar?.dbName ?? parentFkField;
+          const refField = relationMeta.references[0]!;
+          const relatedSfMapForOne = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+          const refScalar = relatedSfMapForOne.get(refField);
+          const refDbName = refScalar?.dbName ?? refField;
+          joinCondition = `${relatedAlias}."${refDbName}" = ${table}."${parentFkDbName}"`;
+        } else {
+          // Related model holds FK (e.g., User.profile -> Profile.userId)
+          joinCondition = `${relatedAlias}."${fkDbName}" = ${table}."${pkDbName}"`;
+        }
 
-      lateralSubquery = `LEFT JOIN LATERAL (
+        lateralSubquery = `LEFT JOIN LATERAL (
     SELECT json_build_object(${jsonFields}) AS "${colAlias}"
-    FROM "${relatedModelMeta.dbName}" __rel
+    FROM "${relatedModelMeta.dbName}" ${relatedAlias}
     WHERE ${joinCondition}
     LIMIT 1
   ) ${alias} ON true`;
+      }
     }
 
     lateralJoins.push(lateralSubquery);

package/src/query-builder.ts

@@ -15,6 +15,20 @@ import type {
 import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
 import { buildWhereClause } from "./where-builder.ts";
 
+// ─── Scalar List Helpers ──────────────────────────────────────────
+
+/**
+ * Wrap a value in PgArray if the corresponding field is a scalar list (e.g. String[], Int[]).
+ * This ensures adapters serialize the JS array as a PostgreSQL array literal
+ * rather than passing it as a raw array or JSON string.
+ */
+function wrapListValue(params: { value: unknown; field: ScalarFieldMeta }): unknown {
+  if (params.field.isList && Array.isArray(params.value)) {
+    return new PgArray(params.value);
+  }
+  return params.value;
+}
+
 // ─── SQL Direction Sanitizer ──────────────────────────────────────
 
 const VALID_DIRECTIONS = new Set(["ASC", "DESC"]);
@@ -79,6 +93,14 @@ export function buildSelectQuery(params: {
   const table = `"${modelMeta.dbName}"`;
   const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
   const take = getTakeValue({ args });
+
+  // Negative take is only valid with cursor-based pagination (backward page)
+  if (take !== undefined && take < 0 && args.cursor === undefined) {
+    throw new Error(
+      `Negative \`take\` (${take}) is only supported with cursor-based pagination on model "${modelMeta.name}". Provide a \`cursor\` argument or use a positive \`take\` value.`
+    );
+  }
+
   const isBackwardCursor = args.cursor !== undefined && take !== undefined && take < 0;
 
   // Determine which columns to select
@@ -510,7 +532,7 @@ export function buildInsertQuery(params: {
     if (value === undefined) continue;
     const scalarField = sfMap.get(key);
     if (scalarField) {
-      entries.push({ dbName: scalarField.dbName, value });
+      entries.push({ dbName: scalarField.dbName, value: wrapListValue({ value, field: scalarField }) });
     }
   }
 
@@ -560,6 +582,7 @@ export function buildUpdateQuery(params: {
       dbName: scalarField.dbName,
       value,
       paramIdx,
+      field: scalarField,
     });
     setClauses.push(setResult.sql);
     allValues.push(...setResult.values);
@@ -839,7 +862,10 @@ export function buildRelationQuery(params: {
       rnConditions.push(`__ranked."__vibeorm_rn" <= $${paramIdx}`);
     }
 
-    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")}`;
+    const fkOrderExpr = fkAlreadySelected && fkFieldName
+      ? `__ranked."${fkFieldName}"`
+      : `__ranked."__vibeorm_fk"`;
+    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")} ORDER BY ${fkOrderExpr} ASC, __ranked."__vibeorm_rn" ASC`;
 
     return { text, values: allValues, fkFieldName: fkAlreadySelected ? fkFieldName : undefined };
   }
@@ -980,7 +1006,7 @@ export function buildManyToManyQuery(params: {
       rnConditions.push(`__ranked."__vibeorm_rn" <= $${paramIdx}`);
     }
 
-    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")}`;
+    const text = `SELECT * FROM (${innerSql}) __ranked WHERE ${rnConditions.join(" AND ")} ORDER BY __ranked."__vibeorm_fk" ASC, __ranked."__vibeorm_rn" ASC`;
     return { text, values: allValues };
   }
 
@@ -1094,10 +1120,10 @@ export function buildInsertManyQuery(params: {
     };
   }
 
-  // Map keys to DB column names
+  // Map keys to DB column names (keep field ref for isList wrapping)
   const columnMap = orderedKeys.map((key) => {
     const scalarField = sfMap.get(key)!;
-    return { key, dbName: scalarField.dbName };
+    return { key, dbName: scalarField.dbName, field: scalarField };
   });
 
   const columns = columnMap.map((c) => `"${c.dbName}"`).join(", ");
@@ -1109,14 +1135,14 @@ export function buildInsertManyQuery(params: {
 
   for (const record of data) {
     const placeholders: string[] = [];
-    for (const { key } of columnMap) {
+    for (const { key, field } of columnMap) {
       const value = record[key];
       if (value === undefined) {
         placeholders.push("DEFAULT");
       } else {
         paramIdx++;
         placeholders.push(`$${paramIdx}`);
-        allValues.push(value);
+        allValues.push(wrapListValue({ value, field }));
       }
     }
     valueRows.push(`(${placeholders.join(", ")})`);
@@ -1190,6 +1216,7 @@ export function buildUpdateManyQuery(params: {
       dbName: scalarField.dbName,
       value,
       paramIdx,
+      field: scalarField,
     });
     setClauses.push(setResult.sql);
     allValues.push(...setResult.values);
@@ -1549,9 +1576,14 @@ function buildSetClause(params: {
   dbName: string;
   value: unknown;
   paramIdx: number;
+  field: ScalarFieldMeta;
+  /** Optional table prefix for qualifying column self-references (e.g. in ON CONFLICT DO UPDATE SET) */
+  tablePrefix?: string;
 }): { sql: string; values: unknown[] } {
-  const { dbName, value, paramIdx } = params;
+  const { dbName, value, paramIdx, field, tablePrefix } = params;
   let idx = paramIdx;
+  // Qualified column reference for the RHS (e.g. "Product"."price" in upsert context)
+  const colRef = tablePrefix ? `${tablePrefix}."${dbName}"` : `"${dbName}"`;
 
   // Check for atomic number operations: { increment, decrement, multiply, divide, set }
   if (typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
@@ -1559,19 +1591,19 @@ function buildSetClause(params: {
 
     if (ops.increment !== undefined) {
       idx++;
-      return { sql: `"${dbName}" = "${dbName}" + $${idx}`, values: [ops.increment] };
+      return { sql: `"${dbName}" = ${colRef} + $${idx}`, values: [ops.increment] };
     }
     if (ops.decrement !== undefined) {
       idx++;
-      return { sql: `"${dbName}" = "${dbName}" - $${idx}`, values: [ops.decrement] };
+      return { sql: `"${dbName}" = ${colRef} - $${idx}`, values: [ops.decrement] };
     }
     if (ops.multiply !== undefined) {
       idx++;
-      return { sql: `"${dbName}" = "${dbName}" * $${idx}`, values: [ops.multiply] };
+      return { sql: `"${dbName}" = ${colRef} * $${idx}`, values: [ops.multiply] };
     }
     if (ops.divide !== undefined) {
       idx++;
-      return { sql: `"${dbName}" = "${dbName}" / $${idx}`, values: [ops.divide] };
+      return { sql: `"${dbName}" = ${colRef} / $${idx}`, values: [ops.divide] };
     }
 
     // Scalar list operations: { set: [...] } or { push: value }
@@ -1580,23 +1612,23 @@ function buildSetClause(params: {
       if (Array.isArray(pushVal)) {
         // Push multiple: "col" = "col" || $N
         idx++;
-        return { sql: `"${dbName}" = "${dbName}" || $${idx}`, values: [pushVal] };
+        return { sql: `"${dbName}" = ${colRef} || $${idx}`, values: [wrapListValue({ value: pushVal, field })] };
       } else {
         // Push single: "col" = array_append("col", $N)
         idx++;
-        return { sql: `"${dbName}" = array_append("${dbName}", $${idx})`, values: [pushVal] };
+        return { sql: `"${dbName}" = array_append(${colRef}, $${idx})`, values: [pushVal] };
       }
     }
 
     if ("set" in ops) {
       idx++;
-      return { sql: `"${dbName}" = $${idx}`, values: [ops.set] };
+      return { sql: `"${dbName}" = $${idx}`, values: [wrapListValue({ value: ops.set, field })] };
     }
   }
 
-  // Plain value
+  // Plain value (wrap if scalar list)
   idx++;
-  return { sql: `"${dbName}" = $${idx}`, values: [value] };
+  return { sql: `"${dbName}" = $${idx}`, values: [wrapListValue({ value, field })] };
 }
 
 // ─── UPSERT Builder (INSERT ... ON CONFLICT) ─────────────────────
@@ -1651,7 +1683,7 @@ export function buildUpsertQuery(params: {
     if (value === undefined) continue;
     const sf = sfMap.get(key);
     if (sf) {
-      insertEntries.push({ dbName: sf.dbName, value });
+      insertEntries.push({ dbName: sf.dbName, value: wrapListValue({ value, field: sf }) });
     }
   }
 
@@ -1666,6 +1698,8 @@ export function buildUpsertQuery(params: {
   }).join(", ");
 
   // Build UPDATE SET part from update data (using atomic operations)
+  // In ON CONFLICT DO UPDATE SET context, column self-references must be table-qualified
+  // to avoid ambiguity (e.g. "Product"."price" instead of just "price").
   const updateClauses: string[] = [];
   for (const [key, value] of Object.entries(update)) {
     if (value === undefined) continue;
@@ -1676,6 +1710,8 @@ export function buildUpsertQuery(params: {
       dbName: sf.dbName,
       value,
       paramIdx,
+      field: sf,
+      tablePrefix: table,
     });
     updateClauses.push(setResult.sql);
     allValues.push(...setResult.values);
@@ -1778,7 +1814,7 @@ function resolveMutationReturningColumns(params: {
   const { modelMeta, args } = params;
   const shouldForceFullReturning = args?.returning === true;
 
-  if (!shouldForceFullReturning && args?.select) {
+  if (!shouldForceFullReturning && (args?.select || args?.omit)) {
     const columns = resolveSelectColumns({
       modelMeta,
       args,

package/src/types.ts

@@ -191,6 +191,8 @@ export type ScalarFieldMeta = {
   readonly isUpdatedAt?: boolean;
   /** Prisma type for runtime coercion (e.g., BigInt values from the DB driver) */
   readonly type?: string;
+  /** Whether this field is a scalar list (e.g., String[], Int[]) */
+  readonly isList?: boolean;
   /**
    * Default value kind for application-level generation.
    * - "uuid" | "cuid" | "nanoid" | "ulid": runtime generates the value if not provided

package/src/where-builder.ts

@@ -739,13 +739,13 @@ function buildScalarFilter(params: {
         case "hasEvery": {
           idx++;
           conditions.push(`${col} @> $${idx}`);
-          values.push(operand);
+          values.push(Array.isArray(operand) ? new PgArray(operand) : operand);
           break;
         }
         case "hasSome": {
           idx++;
           conditions.push(`${col} && $${idx}`);
-          values.push(operand);
+          values.push(Array.isArray(operand) ? new PgArray(operand) : operand);
           break;
         }
         case "isEmpty": {