@vibeorm/runtime 1.1.8 → 1.3.0

package/package.json

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

package/src/client.ts

@@ -38,6 +38,8 @@ import {
 import { generateDefault } from "./id-generators.ts";
 import { createView } from "./view.ts";
 import type { ViewDefinition } from "./view.ts";
+import { coerceFieldTypes } from "./coerce.ts";
+import { resolveCountSpec, loadRelationCounts } from "./count-loader.ts";
 
 /**
  * Creates a VibeORM client instance.
@@ -181,14 +183,54 @@ export function createClient(params: {
     }
   }
 
-  // Create delegate for a model
+  // Build a one-off implicit transaction for a single write operation that
+  // has nested relation ops (Bug #8). Mirrors the executor-wrapping pattern
+  // used in `client.$transaction`'s callback path — same error normalisation,
+  // same PgArray formatting, same logging.
+  //
+  // The caller passes a `runFn` that takes the transactional executor and
+  // performs all writes; we then commit and return the result.
+  async function runInImplicitTx<T>(implicitParams: {
+    runFn: (txExec: typeof executeSql) => Promise<T>;
+  }): Promise<T> {
+    const { runFn } = implicitParams;
+    try {
+      return await adapter.transaction(async (txAdapter) => {
+        async function txExecutor(execParams: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
+          const values = execParams.values.map((v) => (v instanceof PgArray ? txAdapter.formatArrayParam(v.values) : v));
+          if (shouldLog) {
+            console.log(`[vibeorm:tx-implicit] ${execParams.text}`);
+            if (values.length > 0) console.log(`[vibeorm:tx-implicit] params:`, values);
+          }
+          try {
+            return await txAdapter.execute({ text: execParams.text, values });
+          } catch (err) {
+            throw normalizeError({ error: err });
+          }
+        }
+        return runFn(txExecutor);
+      });
+    } catch (err) {
+      throw normalizeError({ error: err });
+    }
+  }
+
+  // Create delegate for a model.
+  //
+  // `inTransaction` (default false) tells the delegate it's running inside
+  // an outer `$transaction(...)` callback. When true, write operations that
+  // contain nested relation ops skip their implicit-transaction wrap (Bug #8 —
+  // mirror Prisma behaviour) because the caller's `tx` already provides
+  // atomicity. Without this flag, we'd open a SAVEPOINT on the in-tx
+  // connection for every nested-write, which is correct but wasteful.
   function createDelegate(params: {
     modelKey: string;
     modelMeta: ModelMeta;
     executor: typeof executeSql;
     schemas?: ModelSchemas;
+    inTransaction?: boolean;
   }): Record<string, Function> {
-    const { modelKey, modelMeta, executor, schemas } = params;
+    const { modelKey, modelMeta, executor, schemas, inTransaction = false } = params;
 
     // Resolve validation mode from options
     const validateOpt = options?.validate;
@@ -517,43 +559,62 @@ export function createClient(params: {
       injectUpdatedAt({ data, modelMeta });
       injectAutoDefaults({ data, modelMeta, idGenerator: options?.idGenerator });
 
-      const { processedData, deferredCreates } = await processNestedCreates({
-        data,
-        modelMeta,
-        allModelsMeta,
-        executor,
-      });
+      // Bug #8: when the write has any nested relation ops, do the whole
+      // INSERT + nested-children sequence inside a single transaction so
+      // partial failures roll back atomically (Prisma parity). Skip the
+      // wrap when we're already inside a caller-supplied transaction.
+      const hasAnyNestedRelation = hasNestedRelationOps({ data, modelMeta });
+      const needsTxWrap = hasAnyNestedRelation && !inTransaction;
 
-      const query = buildInsertQuery({
-        modelMeta,
-        data: processedData,
-        args: deferredCreates.length === 0 ? args : undefined,
-      });
-      let records = await executor(query);
+      const runCreate = async (txExec: typeof executor): Promise<Record<string, unknown>[]> => {
+        const { processedData, deferredCreates } = await processNestedCreates({
+          data,
+          modelMeta,
+          allModelsMeta,
+          executor: txExec,
+        });
 
-      // Execute deferred creates (related records that hold the FK to this parent)
-      // Group by related model to batch multiple creates into single INSERT statements.
-      const parentRecord = records[0];
-      if (parentRecord && deferredCreates.length > 0) {
-        for (const deferred of deferredCreates) {
-          const parentRefValue = parentRecord[deferred.parentRefField];
-          if (parentRefValue != null) {
-            const createItems = Array.isArray(deferred.createData) ? deferred.createData : [deferred.createData];
-            const dataArray = createItems.map((createData) => {
-              (createData as Record<string, unknown>)[deferred.fkField] = parentRefValue;
-              return createData as Record<string, unknown>;
-            });
-            if (dataArray.length === 1) {
-              const insertQuery = buildInsertQuery({ modelMeta: deferred.relatedModelMeta, data: dataArray[0]! });
-              await executor(insertQuery);
-            } else if (dataArray.length > 1) {
-              const insertQuery = buildInsertManyQuery({ modelMeta: deferred.relatedModelMeta, data: dataArray, returning: false });
-              await executor(insertQuery);
+        const query = buildInsertQuery({
+          modelMeta,
+          data: processedData,
+          args: deferredCreates.length === 0 ? args : undefined,
+        });
+        const parentRows = await txExec(query);
+
+        const parentRecord = parentRows[0];
+        if (parentRecord && deferredCreates.length > 0) {
+          for (const deferred of deferredCreates) {
+            const parentRefValue = parentRecord[deferred.parentRefField];
+            if (parentRefValue != null) {
+              const createItems = Array.isArray(deferred.createData) ? deferred.createData : [deferred.createData];
+              const dataArray = createItems.map((createData) => {
+                (createData as Record<string, unknown>)[deferred.fkField] = parentRefValue;
+                return createData as Record<string, unknown>;
+              });
+              if (dataArray.length === 1) {
+                const insertQuery = buildInsertQuery({ modelMeta: deferred.relatedModelMeta, data: dataArray[0]! });
+                await txExec(insertQuery);
+              } else if (dataArray.length > 1) {
+                const insertQuery = buildInsertManyQuery({ modelMeta: deferred.relatedModelMeta, data: dataArray, returning: false });
+                await txExec(insertQuery);
+              }
             }
           }
         }
+
+        return parentRows;
+      };
+
+      let records: Record<string, unknown>[];
+      if (needsTxWrap) {
+        records = await runInImplicitTx({ runFn: runCreate });
+      } else {
+        records = await runCreate(executor);
       }
 
+      // Keep relation-loading + select-filtering + output validation OUTSIDE
+      // the transaction so we don't hold a connection longer than the
+      // actual write needs it.
       records = await loadRelationsForStrategy({
         records,
         modelMeta,
@@ -589,46 +650,57 @@ export function createClient(params: {
         modelMeta,
       });
 
-      const query = buildUpdateQuery({
-        modelMeta,
-        allModelsMeta,
-        where: whereInput,
-        data: scalarData,
-        args: nestedOps.length === 0 ? args : undefined,
-      });
-      let records = await executor(query);
-
-      if (records.length === 0) {
-        throw new VibeRequestError({
-          code: "NOT_FOUND",
-          message: `An operation failed because it depends on one or more records that were required but not found. No ${modelMeta.name} found for the given where clause.`,
-          meta: { model: modelMeta.name, operation: "update" },
-        });
-      }
+      // Bug #8: wrap UPDATE + nested ops in a single transaction so partial
+      // failures roll back atomically. Skip when already inside a caller tx.
+      const needsTxWrap = nestedOps.length > 0 && !inTransaction;
 
-      const updatedRecord = records[0]!;
-
-      // Process nested relation operations
-      if (nestedOps.length > 0) {
-        await processNestedUpdateOps({
-          parentRecord: updatedRecord,
-          nestedOps,
+      const runUpdate = async (txExec: typeof executor): Promise<Record<string, unknown>[]> => {
+        const query = buildUpdateQuery({
           modelMeta,
           allModelsMeta,
-          executor,
+          where: whereInput,
+          data: scalarData,
+          args: nestedOps.length === 0 ? args : undefined,
         });
+        let updateRows = await txExec(query);
 
-        // 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;
+        if (updateRows.length === 0) {
+          throw new VibeRequestError({
+            code: "NOT_FOUND",
+            message: `An operation failed because it depends on one or more records that were required but not found. No ${modelMeta.name} found for the given where clause.`,
+            meta: { model: modelMeta.name, operation: "update" },
+          });
+        }
+
+        if (nestedOps.length > 0) {
+          await processNestedUpdateOps({
+            parentRecord: updateRows[0]!,
+            nestedOps,
+            modelMeta,
+            allModelsMeta,
+            executor: txExec,
+          });
+
+          // 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 txExec(refreshQuery);
+          if (refreshed.length > 0) {
+            updateRows = refreshed;
+          }
         }
+        return updateRows;
+      };
+
+      let records: Record<string, unknown>[];
+      if (needsTxWrap) {
+        records = await runInImplicitTx({ runFn: runUpdate });
+      } else {
+        records = await runUpdate(executor);
       }
 
       records = await loadRelationsForStrategy({
@@ -1059,75 +1131,107 @@ export function createClient(params: {
     const fn = fnOrPromises as (tx: Record<string, unknown>) => Promise<T>;
     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 });
-          }
-        }
-
-        // 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);
-          }
-          try {
-            const result = await txAdapter.executeUnsafe({ text, values: sqlParams });
-            return result.rows as T[];
-          } catch (err) {
-            throw normalizeError({ error: err });
-          }
-        };
-
-        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);
+        return fn(buildTxClient({ txAdapter }));
       }, txOptions);
     } catch (err) {
       throw normalizeError({ error: err });
     }
   };
 
+  /**
+   * Build a transactional client backed by the given txAdapter. Recursive:
+   * the returned `$transaction` method opens a nested transaction (which
+   * the adapters realise as a SAVEPOINT) and rebuilds the same shape over
+   * the resulting innerTxAdapter, so arbitrarily-deep nesting works.
+   *
+   * Used by both the top-level `db.$transaction` callback path and by the
+   * `$transaction` exposed on tx clients (Bug #3 — nested transactions on
+   * the bun adapter previously crashed because they tried to call
+   * `sql.begin()` on a reserved connection).
+   */
+  function buildTxClient(builderParams: { txAdapter: DatabaseAdapter }): Record<string, unknown> {
+    const { txAdapter } = builderParams;
+
+    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 });
+      }
+    }
+
+    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],
+        inTransaction: true,
+      });
+    }
+
+    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 });
+      }
+    };
+
+    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 });
+      }
+    };
+
+    // Nested $transaction → SAVEPOINT through the adapter contract.
+    // The adapter implementation (bun, pg) knows whether the current source
+    // is a pool, a reserved connection, or an in-tx handle, and picks
+    // BEGIN/COMMIT vs SAVEPOINT/RELEASE accordingly.
+    txClient.$transaction = async function <U>(
+      nestedFn: (tx: Record<string, unknown>) => Promise<U>,
+      nestedOptions?: TransactionOptions
+    ): Promise<U> {
+      try {
+        return await txAdapter.transaction(async (innerTxAdapter) => {
+          return nestedFn(buildTxClient({ txAdapter: innerTxAdapter }));
+        }, nestedOptions);
+      } catch (err) {
+        throw normalizeError({ error: err });
+      }
+    };
+
+    return txClient;
+  }
+
   // $queryRaw — tagged template literal for safe parameterized queries
   client.$queryRaw = async function <T = unknown>(
     strings: TemplateStringsArray,
@@ -1168,7 +1272,12 @@ export function createClient(params: {
     }
   };
 
-  // $queryRawUnsafe — accepts a plain SQL string + params array
+  // $queryRawUnsafe — accepts a plain SQL string + params array.
+  // Routed through `executeUnsafe` (NOT `execute`) so that adapters know this
+  // is dynamic raw SQL and can skip prepared-statement caching. This also lets
+  // adapters apply raw-query-only param normalisation (e.g. bun:sql converting
+  // plain JS array params to PG array literals for `= ANY($N)`) without
+  // affecting the ORM hot path.
   client.$queryRawUnsafe = async function <T = unknown>(
     query: string,
     ...values: unknown[]
@@ -1180,12 +1289,11 @@ export function createClient(params: {
       }
     }
     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[];
+      const result = await adapter.executeUnsafe({
+        text: query,
+        values: values.length > 0 ? values : undefined,
+      });
+      return result.rows as T[];
     } catch (err) {
       throw normalizeError({ error: err });
     }
@@ -1247,39 +1355,6 @@ export function createClient(params: {
   return client;
 }
 
-/**
- * Coerce scalar field values to their correct JS types.
- * Currently handles BigInt fields: bun:sql returns PostgreSQL bigint as string,
- * but the application expects native BigInt values.
- */
-function coerceFieldTypes(params: {
-  records: Record<string, unknown>[];
-  modelMeta: ModelMeta;
-}): Record<string, unknown>[] {
-  const { records, modelMeta } = params;
-  if (records.length === 0) return records;
-
-  // Find fields that need coercion
-  const bigintFields = modelMeta.scalarFields.filter(
-    (f) => (f as { type?: string }).type === "BigInt"
-  );
-
-  if (bigintFields.length === 0) return records;
-
-  for (const record of records) {
-    for (const field of bigintFields) {
-      const val = record[field.name];
-      if (typeof val === "string") {
-        record[field.name] = BigInt(val);
-      } else if (typeof val === "number") {
-        record[field.name] = BigInt(val);
-      }
-    }
-  }
-
-  return records;
-}
-
 /**
  * Apply select filtering to returned records.
  * When args.select is specified, strips fields not in the select object
@@ -1499,137 +1574,35 @@ function parseAggregateResult(params: {
   return result;
 }
 
-/**
- * Resolve _count specification from include or select args.
- * Returns the list of relation names to count, or null if _count not requested.
- */
-function resolveCountSpec(params: { args: Record<string, unknown> }): string[] | null {
-  const { args } = params;
-  const include = args.include as Record<string, unknown> | undefined;
-  const select = args.select as Record<string, unknown> | undefined;
-
-  const countArg = include?._count ?? select?._count;
-  if (!countArg) return null;
-
-  if (countArg === true) {
-    // Count all list relations — will be resolved by loadRelationCounts
-    return ["__all__"];
-  }
-
-  if (typeof countArg === "object" && countArg !== null) {
-    const countObj = countArg as Record<string, unknown>;
-    const selectObj = countObj.select as Record<string, boolean> | undefined;
-    if (selectObj) {
-      return Object.entries(selectObj)
-        .filter(([_, enabled]) => enabled)
-        .map(([name]) => name);
-    }
-  }
-
-  return null;
-}
+type NestedOp = {
+  relationField: ModelMeta["relationFields"][number];
+  ops: Record<string, unknown>;
+};
 
 /**
- * Load relation counts and attach _count object to each record.
- * Uses COUNT subqueries grouped by parent FK.
+ * Cheap upfront detection: does this write `data` object contain any keys
+ * that correspond to a relation field on the model? Used by `create` (and
+ * by analogy, fits any nested-write op detection) to decide whether to wrap
+ * the operation in an implicit transaction (Bug #8).
+ *
+ * Doesn't try to verify the nested value is a well-formed `{ create | connect
+ * | … }` object — `processNestedCreates` does that validation while running.
+ * The conservative over-wrap (e.g. user passes `{ relationName: undefined }`)
+ * is cheap and still correct.
  */
-async function loadRelationCounts(params: {
-  records: Record<string, unknown>[];
+function hasNestedRelationOps(params: {
+  data: Record<string, unknown>;
   modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  countSpec: string[];
-  executor: (params: { text: string; values: unknown[] }) => Promise<Record<string, unknown>[]>;
-}): Promise<void> {
-  const { records, modelMeta, allModelsMeta, countSpec, executor } = params;
-  const modelMap = getModelByNameMap({ allModelsMeta });
-  const parentPk = modelMeta.primaryKey[0];
-  if (!parentPk) return;
-
-  const parentIds = records.map((r) => r[parentPk]).filter((id) => id != null);
-  if (parentIds.length === 0) return;
-
-  // Resolve which relations to count
-  const listRelations = modelMeta.relationFields.filter((r) => r.isList);
-  const relationsToCount = countSpec.includes("__all__")
-    ? listRelations
-    : listRelations.filter((r) => countSpec.includes(r.name));
-
-  // Initialize _count on all records
-  for (const record of records) {
-    const countObj: Record<string, number> = {};
-    for (const rel of relationsToCount) {
-      countObj[rel.name] = 0;
-    }
-    record._count = countObj;
+}): boolean {
+  const { data, modelMeta } = params;
+  for (const rf of modelMeta.relationFields) {
+    const v = data[rf.name];
+    if (v === undefined) continue;
+    if (v !== null && typeof v === "object") return true;
   }
-
-  // Run all relation COUNT queries in parallel — each hits a different table
-  // so there are no data races on the parent records.
-  await Promise.all(
-    relationsToCount.map(async (rel) => {
-      const relatedModelMeta = modelMap.get(rel.relatedModel);
-      if (!relatedModelMeta) return;
-
-      // M:N relation: count via join table
-      if (rel.type === "manyToMany" && (rel as { joinTable?: string }).joinTable) {
-        const joinTableName = (rel as { joinTable?: string }).joinTable!;
-        const sorted = [modelMeta.name, relatedModelMeta.name].sort();
-        const parentIsA = modelMeta.name === sorted[0];
-        const parentCol = parentIsA ? "A" : "B";
-
-        const text = `SELECT "${joinTableName}"."${parentCol}" AS "__fk", COUNT(*) AS "__count" FROM "${joinTableName}" WHERE "${joinTableName}"."${parentCol}" = ANY($1) GROUP BY "${joinTableName}"."${parentCol}"`;
-        const result = await executor({ text, values: [new PgArray(parentIds)] });
-
-        const countMap = new Map<unknown, number>();
-        for (const row of result) {
-          countMap.set(row.__fk, Number(row.__count ?? 0));
-        }
-
-        for (const record of records) {
-          const pkValue = record[parentPk];
-          const cnt = countMap.get(pkValue) ?? 0;
-          (record._count as Record<string, number>)[rel.name] = cnt;
-        }
-        return;
-      }
-
-      // Find the FK column on the related model (with relationName disambiguation)
-      const reverseRel = relatedModelMeta.relationFields.find(
-        (r) => r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0 &&
-          (!rel.relationName || r.relationName === rel.relationName)
-      );
-      if (!reverseRel) return;
-
-      const fkField = reverseRel.fields[0]!;
-      const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-      const fkScalar = relatedSfMap.get(fkField);
-      const fkDbName = fkScalar?.dbName ?? fkField;
-      const relatedTable = `"${relatedModelMeta.dbName}"`;
-
-      // Build: SELECT "fk" AS "__fk", COUNT(*) AS "__count" FROM "related" WHERE "fk" = ANY($1) GROUP BY "fk"
-      const text = `SELECT ${relatedTable}."${fkDbName}" AS "__fk", COUNT(*) AS "__count" FROM ${relatedTable} WHERE ${relatedTable}."${fkDbName}" = ANY($1) GROUP BY ${relatedTable}."${fkDbName}"`;
-      const result = await executor({ text, values: [new PgArray(parentIds)] });
-
-      // Map counts back to parent records
-      const countMap = new Map<unknown, number>();
-      for (const row of result) {
-        countMap.set(row.__fk, Number(row.__count ?? 0));
-      }
-
-      for (const record of records) {
-        const pkValue = record[parentPk];
-        const cnt = countMap.get(pkValue) ?? 0;
-        (record._count as Record<string, number>)[rel.name] = cnt;
-      }
-    })
-  );
+  return false;
 }
 
-type NestedOp = {
-  relationField: ModelMeta["relationFields"][number];
-  ops: Record<string, unknown>;
-};
-
 /**
  * Separate scalar data from nested relation operations in update data.
  */

package/src/coerce.ts

@@ -0,0 +1,184 @@
+/**
+ * Scalar value type coercion.
+ *
+ * Coerce raw DB driver output to the JS types declared in the Prisma schema.
+ * Currently handles `BigInt` (pg / bun:sql return PG `bigint` as a string,
+ * but the application expects native `BigInt`).
+ *
+ * Lives in its own module so all relation loaders (query strategy, lateral
+ * join strategy, post-write refresh, raw post-processing) can call it without
+ * creating circular imports between `client.ts` and the relation loaders.
+ *
+ * Mutates the records in place — callers rely on this for performance.
+ */
+
+import type { ModelMeta, ScalarFieldMeta } from "./types.ts";
+
+/**
+ * Per-model cache of names of fields that need BigInt coercion.
+ * Empty arrays are cached too, so the `length === 0` fast path costs one
+ * `WeakMap.get` after the first call per model.
+ *
+ * Keyed by the `scalarFields` array reference (the same hot-path cache key
+ * used by `getScalarFieldMap`), which is stable for the process lifetime
+ * because model metadata is generated once at startup.
+ */
+const _bigintFieldsCache = new WeakMap<
+  readonly ScalarFieldMeta[],
+  readonly string[]
+>();
+
+function getBigIntFieldNames(modelMeta: ModelMeta): readonly string[] {
+  const sf = modelMeta.scalarFields;
+  let names = _bigintFieldsCache.get(sf);
+  if (names) return names;
+  const arr: string[] = [];
+  for (const f of sf) {
+    if ((f as { type?: string }).type === "BigInt") arr.push(f.name);
+  }
+  names = arr;
+  _bigintFieldsCache.set(sf, names);
+  return names;
+}
+
+/**
+ * Per-model cache of enum-array field names. Same WeakMap shape and
+ * lifetime guarantees as `_bigintFieldsCache`.
+ *
+ * Enum-array columns need post-processing because neither `bun:sql` nor
+ * `node-postgres` knows the user-defined enum's array type OID, so the
+ * driver returns the raw PG array literal as a string (e.g. `"{ADMIN,USER}"`)
+ * instead of a JS array. Built-in scalar arrays (`text[]`, `int4[]`, …) ARE
+ * parsed by both drivers because their OIDs are well-known.
+ */
+const _enumListFieldsCache = new WeakMap<
+  readonly ScalarFieldMeta[],
+  readonly string[]
+>();
+
+function getEnumListFieldNames(modelMeta: ModelMeta): readonly string[] {
+  const sf = modelMeta.scalarFields;
+  let names = _enumListFieldsCache.get(sf);
+  if (names) return names;
+  const arr: string[] = [];
+  for (const f of sf) {
+    if (f.kind === "enum" && f.isList === true) arr.push(f.name);
+  }
+  names = arr;
+  _enumListFieldsCache.set(sf, names);
+  return names;
+}
+
+/**
+ * Parse a PostgreSQL array literal string into a JS array of strings.
+ *
+ * Format: `{val1,val2,"quoted,val",NULL,...}` with `""` quoting only when an
+ * element contains commas, double-quotes, backslashes, or is the literal
+ * `NULL`. PG uses backslash-escaping inside quoted elements.
+ *
+ * Returns `[]` for `{}`. Returns the input unchanged if it doesn't look like
+ * an array literal (defensive — should never happen for an enum-array column).
+ */
+function parsePgArrayLiteral(literal: string): string[] | string {
+  if (literal.length < 2 || literal.charCodeAt(0) !== 123 /* { */) return literal;
+  if (literal === "{}") return [];
+
+  const out: string[] = [];
+  const inner = literal.slice(1, -1);
+  let i = 0;
+  const len = inner.length;
+  while (i < len) {
+    if (inner.charCodeAt(i) === 34 /* " */) {
+      // Quoted element — read until matching close-quote, honouring \\ and \"
+      let s = "";
+      i++;
+      while (i < len) {
+        const ch = inner.charCodeAt(i);
+        if (ch === 92 /* \ */) {
+          s += inner[i + 1] ?? "";
+          i += 2;
+        } else if (ch === 34) {
+          i++;
+          break;
+        } else {
+          s += inner[i];
+          i++;
+        }
+      }
+      out.push(s);
+    } else {
+      // Unquoted element — read until next comma or end
+      let s = "";
+      while (i < len && inner.charCodeAt(i) !== 44 /* , */) {
+        s += inner[i];
+        i++;
+      }
+      out.push(s);
+    }
+    if (i < len && inner.charCodeAt(i) === 44 /* , */) i++;
+  }
+  return out;
+}
+
+/**
+ * Coerce scalar field values on the given records to their JS-native types.
+ *
+ * Today only `BigInt` fields are affected. Driver behaviour:
+ *  - `bun:sql` returns PG `bigint` as a JS `string`.
+ *  - `node-postgres` returns PG `bigint` as a JS `string` by default too.
+ *  - In both cases the Prisma type is `BigInt`, so we coerce.
+ *
+ * No-op when the model has no `BigInt` fields, or when `records` is empty.
+ */
+export function coerceFieldTypes(params: {
+  records: Record<string, unknown>[];
+  modelMeta: ModelMeta;
+}): void {
+  const { records, modelMeta } = params;
+  if (records.length === 0) return;
+
+  const bigintNames = getBigIntFieldNames(modelMeta);
+  const enumListNames = getEnumListFieldNames(modelMeta);
+  if (bigintNames.length === 0 && enumListNames.length === 0) return;
+
+  for (const record of records) {
+    for (const name of bigintNames) {
+      const val = record[name];
+      if (typeof val === "string") {
+        record[name] = BigInt(val);
+      } else if (typeof val === "number") {
+        record[name] = BigInt(val);
+      }
+    }
+    // Enum-array fields arrive as raw PG array literal strings from both
+    // bun:sql and node-postgres (the driver doesn't know the user-defined
+    // enum's array OID). Parse them into JS string arrays. Bug 2 + Bug 3.
+    for (const name of enumListNames) {
+      const val = record[name];
+      if (typeof val === "string") {
+        const parsed = parsePgArrayLiteral(val);
+        if (Array.isArray(parsed)) record[name] = parsed;
+      }
+    }
+  }
+}
+
+/**
+ * True iff the model has any `BigInt` fields that require coercion.
+ * Cheap O(1) lookup after first call per model. Hot-path callers (lateral-join
+ * builder, relation loaders) use this to skip the per-row coercion loop
+ * entirely for relations whose related model has no `BigInt` columns.
+ */
+export function modelHasBigInt(modelMeta: ModelMeta): boolean {
+  return getBigIntFieldNames(modelMeta).length > 0;
+}
+
+/**
+ * True iff the model has any fields that need post-driver coercion
+ * (BigInt OR enum-array). Use this in place of `modelHasBigInt` whenever
+ * the fast-path skip would otherwise miss enum-array fields (Bug 2).
+ */
+export function modelNeedsCoercion(modelMeta: ModelMeta): boolean {
+  return getBigIntFieldNames(modelMeta).length > 0
+    || getEnumListFieldNames(modelMeta).length > 0;
+}

package/src/count-loader.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared `_count` resolution + loader, used by both the "query" and "join"
+ * relation strategies.
+ *
+ * `resolveCountSpec` looks at `include._count` / `select._count` and returns
+ * the list of list-relation names to count (or `["__all__"]` for `_count: true`,
+ * or `null` when not requested).
+ *
+ * `loadRelationCounts` issues a single grouped `COUNT(*) GROUP BY <fk>` per
+ * relation (parallelised across relations) and attaches the result as a
+ * `_count` object on each parent record.
+ *
+ * Lives in its own module so the lateral-join path can call it without
+ * pulling in `client.ts` (which would create a circular import).
+ */
+
+import type { ModelMeta, ModelMetaMap } from "./types.ts";
+import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
+
+type SqlExecutor = (params: {
+  text: string;
+  values: unknown[];
+}) => Promise<Record<string, unknown>[]>;
+
+/**
+ * Resolve `_count` specification from `include` or `select` args.
+ * Returns the list of relation names to count, `["__all__"]` to count every
+ * list relation, or `null` if `_count` was not requested.
+ */
+export function resolveCountSpec(params: { args: Record<string, unknown> }): string[] | null {
+  const { args } = params;
+  const include = args.include as Record<string, unknown> | undefined;
+  const select = args.select as Record<string, unknown> | undefined;
+
+  const countArg = include?._count ?? select?._count;
+  if (!countArg) return null;
+
+  if (countArg === true) {
+    // Count all list relations — will be resolved by loadRelationCounts
+    return ["__all__"];
+  }
+
+  if (typeof countArg === "object" && countArg !== null) {
+    const countObj = countArg as Record<string, unknown>;
+    const selectObj = countObj.select as Record<string, boolean> | undefined;
+    if (selectObj) {
+      return Object.entries(selectObj)
+        .filter(([_, enabled]) => enabled)
+        .map(([name]) => name);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Load relation counts and attach a `_count` object to each parent record.
+ * Uses one grouped `COUNT(*)` query per relation, executed in parallel.
+ *
+ * Mutates the parent records in place.
+ */
+export async function loadRelationCounts(params: {
+  records: Record<string, unknown>[];
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+  countSpec: string[];
+  executor: SqlExecutor;
+}): Promise<void> {
+  const { records, modelMeta, allModelsMeta, countSpec, executor } = params;
+  const modelMap = getModelByNameMap({ allModelsMeta });
+  const parentPk = modelMeta.primaryKey[0];
+  if (!parentPk) return;
+
+  const parentIds = records.map((r) => r[parentPk]).filter((id) => id != null);
+  if (parentIds.length === 0) return;
+
+  // Resolve which relations to count
+  const listRelations = modelMeta.relationFields.filter((r) => r.isList);
+  const relationsToCount = countSpec.includes("__all__")
+    ? listRelations
+    : listRelations.filter((r) => countSpec.includes(r.name));
+
+  // Initialize _count on all records
+  for (const record of records) {
+    const countObj: Record<string, number> = {};
+    for (const rel of relationsToCount) {
+      countObj[rel.name] = 0;
+    }
+    record._count = countObj;
+  }
+
+  // Run all relation COUNT queries in parallel — each hits a different table
+  // so there are no data races on the parent records.
+  await Promise.all(
+    relationsToCount.map(async (rel) => {
+      const relatedModelMeta = modelMap.get(rel.relatedModel);
+      if (!relatedModelMeta) return;
+
+      // M:N relation: count via join table
+      if (rel.type === "manyToMany" && (rel as { joinTable?: string }).joinTable) {
+        const joinTableName = (rel as { joinTable?: string }).joinTable!;
+        const sorted = [modelMeta.name, relatedModelMeta.name].sort();
+        const parentIsA = modelMeta.name === sorted[0];
+        const parentCol = parentIsA ? "A" : "B";
+
+        const text = `SELECT "${joinTableName}"."${parentCol}" AS "__fk", COUNT(*) AS "__count" FROM "${joinTableName}" WHERE "${joinTableName}"."${parentCol}" = ANY($1) GROUP BY "${joinTableName}"."${parentCol}"`;
+        const result = await executor({ text, values: [new PgArray(parentIds)] });
+
+        const countMap = new Map<unknown, number>();
+        for (const row of result) {
+          countMap.set(row.__fk, Number(row.__count ?? 0));
+        }
+
+        for (const record of records) {
+          const pkValue = record[parentPk];
+          const cnt = countMap.get(pkValue) ?? 0;
+          (record._count as Record<string, number>)[rel.name] = cnt;
+        }
+        return;
+      }
+
+      // Find the FK column on the related model (with relationName disambiguation)
+      const reverseRel = relatedModelMeta.relationFields.find(
+        (r) => r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0 &&
+          (!rel.relationName || r.relationName === rel.relationName)
+      );
+      if (!reverseRel) return;
+
+      const fkField = reverseRel.fields[0]!;
+      const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+      const fkScalar = relatedSfMap.get(fkField);
+      const fkDbName = fkScalar?.dbName ?? fkField;
+      const relatedTable = `"${relatedModelMeta.dbName}"`;
+
+      // SELECT "fk" AS "__fk", COUNT(*) AS "__count" FROM "related" WHERE "fk" = ANY($1) GROUP BY "fk"
+      const text = `SELECT ${relatedTable}."${fkDbName}" AS "__fk", COUNT(*) AS "__count" FROM ${relatedTable} WHERE ${relatedTable}."${fkDbName}" = ANY($1) GROUP BY ${relatedTable}."${fkDbName}"`;
+      const result = await executor({ text, values: [new PgArray(parentIds)] });
+
+      // Map counts back to parent records
+      const countMap = new Map<unknown, number>();
+      for (const row of result) {
+        countMap.set(row.__fk, Number(row.__count ?? 0));
+      }
+
+      for (const record of records) {
+        const pkValue = record[parentPk];
+        const cnt = countMap.get(pkValue) ?? 0;
+        (record._count as Record<string, number>)[rel.name] = cnt;
+      }
+    })
+  );
+}

package/src/errors.ts

@@ -51,6 +51,7 @@ export type VibeRequestErrorCode =
   | "FOREIGN_KEY_VIOLATION"
   | "NOT_NULL_VIOLATION"
   | "CHECK_CONSTRAINT"
+  | "VALUE_OUT_OF_RANGE"
   | "NOT_FOUND"
   | "VALIDATION_ERROR"
   | "UNKNOWN_REQUEST_ERROR";
@@ -238,6 +239,16 @@ const CONSTRAINT_CODE_MAP: Record<string, VibeRequestErrorCode> = {
   "23514": "CHECK_CONSTRAINT",
 };
 
+/**
+ * SQLSTATE Class 22 — data exception. We map the specific codes we want to
+ * surface as actionable errors. 22003 is the canonical "value out of range
+ * for type" code; the most common way users hit it is inserting a `BigInt`
+ * value larger than 2^63-1 into a `bigint` column (Bug 9).
+ */
+const DATA_EXCEPTION_CODE_MAP: Record<string, VibeRequestErrorCode> = {
+  "22003": "VALUE_OUT_OF_RANGE",
+};
+
 /**
  * Extract a field name from a PostgreSQL detail string.
  *
@@ -410,6 +421,27 @@ export function normalizeError(params: {
       });
     }
 
+    // Data exception (Class 22): e.g. value out of range for the column type.
+    // Specifically: 22003 is what users see when a BigInt value overflows the
+    // signed-int64 limit on a `bigint` column. We surface a targeted hint for
+    // that case because the raw PG message ("value out of range for type
+    // bigint") is easy to misread as a driver bug. Bug 9.
+    const dataExceptionCode = DATA_EXCEPTION_CODE_MAP[pgCode];
+    if (dataExceptionCode) {
+      const isBigIntRange =
+        dataExceptionCode === "VALUE_OUT_OF_RANGE" &&
+        /out of range for type bigint/i.test(pgErr.message);
+      const message = isBigIntRange
+        ? `${pgErr.message} (PostgreSQL bigint is signed int64, max 0x7fffffffffffffff = 2^63-1. For unsigned 64-bit values, store as String or Decimal.)`
+        : pgErr.message;
+      return new VibeRequestError({
+        code: dataExceptionCode,
+        message,
+        meta,
+        cause,
+      });
+    }
+
     // Check transient by SQLSTATE class prefix
     if (pgCode.startsWith("08") || pgCode.startsWith("40")) {
       return new VibeTransientError({

package/src/index.ts

@@ -24,6 +24,7 @@ export { withRetry } from "./retry.ts";
 export { ViewResult, createView } from "./view.ts";
 export type { ViewDefinition } from "./view.ts";
 export type { RetryOptions } from "./retry.ts";
+export { PgArray } from "./types.ts";
 
 export type {
   DatabaseAdapter,

package/src/lateral-join-builder.ts

@@ -49,6 +49,8 @@ import { buildWhereClause } from "./where-builder.ts";
 import { sanitizeDirection } from "./query-builder.ts";
 import { loadRelations, resolveRelationsToLoad, hasNestedRelations } from "./relation-loader.ts";
 import type { RelationToLoad } from "./relation-loader.ts";
+import { coerceFieldTypes, modelNeedsCoercion } from "./coerce.ts";
+import { resolveCountSpec, loadRelationCounts } from "./count-loader.ts";
 
 type SqlExecutor = (params: {
   text: string;
@@ -452,12 +454,33 @@ export function buildLateralJoinQuery(params: {
           joinCondition = `${relatedAlias}."${fkDbName}" = ${table}."${pkDbName}"`;
         }
 
+        // Nested where filter from include/select args — mirrors the to-many branch.
+        // Without this the join silently ignored `include: { author: { where: {...} } }`.
+        let nestedWhereSql = "";
+        if (nestedArgs.where) {
+          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);
+          }
+        }
+
         lateralSubquery = `LEFT JOIN LATERAL (
     SELECT to_jsonb("__sub".*) AS "${colAlias}"
     FROM (
       SELECT ${columnAliases}
       FROM "${relatedModelMeta.dbName}" ${relatedAlias}
-      WHERE ${joinCondition}
+      WHERE ${joinCondition}${nestedWhereSql}
       LIMIT 1
     ) "__sub"
   ) ${alias} ON true`;
@@ -647,8 +670,24 @@ export async function executeLateralJoinQuery(params: {
 
   const t2 = profiling ? performance.now() : 0;
 
-  // Parse JSON relation columns
-  const pkField = modelMeta.primaryKey[0]!;
+  // Parse JSON relation columns + apply BigInt coercion in a single pass.
+  //
+  // The "query" strategy coerces both parents (via `loadRelationsForStrategy`)
+  // and children (via the per-loader calls in `relation-loader.ts`). The
+  // lateral-join strategy bypasses both, so we do the equivalent work here
+  // (Bug #6).
+  //
+  // Performance: pre-compute which relation aliases actually need coercion
+  // (BigInt or enum-array — see `modelNeedsCoercion`). Wide schemas with
+  // many includes thus pay nothing extra for relations whose child model
+  // has neither.
+  const nestedModelMap = getModelByNameMap({ allModelsMeta });
+  const relationCoerceMeta = relationAliases.map(({ relationMeta }) => {
+    const relatedModelMeta = nestedModelMap.get(relationMeta.relatedModel);
+    if (!relatedModelMeta) return null;
+    return modelNeedsCoercion(relatedModelMeta) ? relatedModelMeta : null;
+  });
+
   const results: Record<string, unknown>[] = [];
 
   for (const row of rows) {
@@ -661,30 +700,44 @@ export async function executeLateralJoinQuery(params: {
       }
     }
 
-    // Parse relation columns from JSON
-    for (const { alias, relationMeta } of relationAliases) {
+    // Parse relation columns from JSON (and coerce inline if needed)
+    for (let i = 0; i < relationAliases.length; i++) {
+      const { alias, relationMeta } = relationAliases[i]!;
       const jsonValue = row[alias];
+      let parsed: unknown;
       if (jsonValue === null || jsonValue === undefined) {
-        record[relationMeta.name] = relationMeta.isList ? [] : null;
+        parsed = relationMeta.isList ? [] : null;
       } else if (typeof jsonValue === "string") {
         try {
-          record[relationMeta.name] = JSON.parse(jsonValue);
+          parsed = JSON.parse(jsonValue);
         } catch {
-          record[relationMeta.name] = relationMeta.isList ? [] : null;
+          parsed = relationMeta.isList ? [] : null;
         }
       } else {
         // Already parsed by bun:sql (json/jsonb columns auto-parse)
-        record[relationMeta.name] = jsonValue;
+        parsed = jsonValue;
+      }
+      record[relationMeta.name] = parsed;
+
+      const coerceMeta = relationCoerceMeta[i];
+      if (coerceMeta) {
+        if (Array.isArray(parsed)) {
+          coerceFieldTypes({ records: parsed as Record<string, unknown>[], modelMeta: coerceMeta });
+        } else if (parsed && typeof parsed === "object") {
+          coerceFieldTypes({ records: [parsed as Record<string, unknown>], modelMeta: coerceMeta });
+        }
       }
     }
 
     results.push(record);
   }
 
+  // Coerce parent records once (whole batch) after the parse loop.
+  coerceFieldTypes({ records: results, modelMeta });
+
   const t3 = profiling ? performance.now() : 0;
 
   // Recursively load nested relations (deeper levels fall back to batched)
-  const nestedModelMap = getModelByNameMap({ allModelsMeta });
   await Promise.all(
     relationAliases
       .filter(({ nestedArgs }) => hasNestedRelations({ nestedArgs }))
@@ -713,6 +766,23 @@ export async function executeLateralJoinQuery(params: {
       })
   );
 
+  // ─── _count support (Bug #5) ─────────────────────────────────────
+  // The "query" strategy resolves `_count` after `loadRelations` (see
+  // `loadRelationsForStrategy` in client.ts). The lateral-join strategy
+  // historically returned BEFORE `_count` ran, silently dropping it whenever
+  // the user combined `include: { posts: true, _count: { … } }` with the
+  // join strategy. We mirror the query-strategy behaviour here.
+  const countSpec = resolveCountSpec({ args });
+  if (countSpec && results.length > 0) {
+    await loadRelationCounts({
+      records: results,
+      modelMeta,
+      allModelsMeta,
+      countSpec,
+      executor,
+    });
+  }
+
   // Populate profiling context with per-phase timings
   if (profilingCtx) {
     profilingCtx.queryBuildMs = t1 - t0;

package/src/relation-loader.ts

@@ -19,6 +19,7 @@ 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;
@@ -242,6 +243,10 @@ async function loadToManyRelation(params: {
     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];
@@ -345,6 +350,9 @@ async function loadToOneWithFk(params: {
     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];
@@ -411,6 +419,9 @@ async function loadToOneWithoutFk(params: {
     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];