@vibeorm/runtime 1.0.1 → 1.1.0

package/README.md

@@ -36,6 +36,25 @@ const db = VibeClient({
 
 Creates a VibeORM client instance. Called by generated code — takes model metadata, optional Zod schemas, and client options.
 
+`countStrategy` can be set globally in client options and overridden per count call:
+
+```ts
+await db.user.count({
+  where: { isActive: true },
+  countStrategy: "subquery",
+});
+```
+
+Per-operation `countStrategy` takes precedence over the client default.
+
+### Mutation RETURNING behavior
+
+`create`, `update`, `delete`, and `upsert` now narrow SQL `RETURNING` columns when `select` is provided, reducing row payload size.
+
+- Default behavior: full scalar row is returned (same as before)
+- With `select`: only selected scalar columns are returned (plus internal keys when needed)
+- With `returning: true`: force full scalar `RETURNING` payload even when `select` is present
+
 ### `toSqlExecutor({ adapter })`
 
 Bridges a `DatabaseAdapter` to a `SqlExecutor` for use with the migrate package.

package/package.json

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

package/src/adapter.ts

@@ -6,6 +6,35 @@
  * and interacts with the database exclusively through this contract.
  */
 
+// ─── Transaction Options ──────────────────────────────────────────
+
+/**
+ * Options for controlling transaction behavior.
+ *
+ * @example
+ * ```ts
+ * await db.$transaction(async (tx) => {
+ *   await tx.account.update({ where: { id: 1 }, data: { balance: { decrement: 100 } } });
+ *   await tx.account.update({ where: { id: 2 }, data: { balance: { increment: 100 } } });
+ * }, { isolationLevel: "Serializable", timeout: 5000 });
+ * ```
+ */
+export type TransactionOptions = {
+  /**
+   * PostgreSQL isolation level for the transaction.
+   * - "ReadCommitted" (default): Standard PostgreSQL default.
+   * - "RepeatableRead": Prevents non-repeatable reads.
+   * - "Serializable": Full serializability — conflicts throw serialization_failure.
+   */
+  isolationLevel?: "ReadCommitted" | "RepeatableRead" | "Serializable";
+  /**
+   * Maximum time in milliseconds the transaction may run before being cancelled.
+   * Implemented via `SET LOCAL statement_timeout = N` inside the transaction,
+   * so it is scoped to the transaction and does not affect other connections.
+   */
+  timeout?: number;
+};
+
 // ─── Core Adapter Interface ───────────────────────────────────────
 
 /**
@@ -38,8 +67,11 @@ export type DatabaseAdapter = {
    * Run a function inside a database transaction.
    * The callback receives a transactional adapter with the same interface.
    * If the callback throws, the transaction is automatically rolled back.
+   *
+   * @param fn - The transactional callback.
+   * @param options - Optional isolation level and timeout.
    */
-  transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T>;
+  transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T>;
 
   /**
    * Eagerly warm up the connection pool.

package/src/client.ts

@@ -16,8 +16,8 @@ import type {
   ProfilingContext,
 } from "./types.ts";
 import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
-import type { DatabaseAdapter } from "./adapter.ts";
-import { VibeValidationError } from "./errors.ts";
+import type { DatabaseAdapter, TransactionOptions } from "./adapter.ts";
+import { VibeValidationError, VibeRequestError, normalizeError } from "./errors.ts";
 import {
   buildSelectQuery,
   buildInsertQuery,
@@ -30,11 +30,10 @@ import {
   buildGroupByQuery,
   buildUpsertQuery,
 } from "./query-builder.ts";
-import { loadRelations } from "./relation-loader.ts";
+import { loadRelations, resolveRelationsToLoad } from "./relation-loader.ts";
 import {
   loadRelationsWithLateralJoin,
   executeLateralJoinQuery,
-  resolveRelationsToLoad,
 } from "./lateral-join-builder.ts";
 import { generateDefault } from "./id-generators.ts";
 
@@ -51,6 +50,8 @@ export function createClient(params: {
   const adapter = options.adapter;
   const shouldLog = options?.log === true || options?.log === "query";
   const shouldDebug = !!options?.debug;
+  const defaultOrderByPk = options?.defaultOrderByPk ?? false;
+  const distinctOrderByPk = options?.distinctOrderByPk ?? true;
 
   /** Emit a query profile to the user's debug handler or console. */
   function debugEmit(profile: QueryProfile): void {
@@ -158,6 +159,7 @@ export function createClient(params: {
   // SQL executor function — delegates to the adapter.
   // Array values are converted via adapter.formatArrayParam so that
   // = ANY($1) works correctly.
+  // Database errors are normalized into VibeRequestError / VibeTransientError.
   async function executeSql(params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
     const { text, values: rawValues } = params;
     // Convert PgArray instances - let the adapter handle the format
@@ -170,7 +172,11 @@ export function createClient(params: {
       }
     }
 
-    return adapter.execute({ text, values });
+    try {
+      return await adapter.execute({ text, values });
+    } catch (err) {
+      throw normalizeError({ error: err });
+    }
   }
 
   // Create delegate for a model
@@ -252,6 +258,7 @@ export function createClient(params: {
             args,
             executor: executeSql,
             profilingCtx,
+            defaultOrderByPk,
           });
           const t1 = performance.now();
           const sizeBytes = estimateResultSize({ records: result });
@@ -278,6 +285,7 @@ export function createClient(params: {
           allModelsMeta,
           args,
           executor,
+          defaultOrderByPk,
         });
         validateOutput({ records: result, operation: "findMany" });
         return result;
@@ -291,6 +299,8 @@ export function createClient(params: {
           modelMeta,
           allModelsMeta,
           args,
+          defaultOrderByPk,
+          distinctOrderByPk,
         });
         const t1 = performance.now();
         let records = await profExec(query);
@@ -327,6 +337,8 @@ export function createClient(params: {
         modelMeta,
         allModelsMeta,
         args,
+        defaultOrderByPk,
+        distinctOrderByPk,
       });
       let records = await executor(query);
 
@@ -352,6 +364,7 @@ export function createClient(params: {
           allModelsMeta,
           args: argsWithLimit,
           executor,
+          defaultOrderByPk,
         });
         validateOutput({ records, operation: "findFirst" });
         return records[0] ?? null;
@@ -361,7 +374,7 @@ export function createClient(params: {
         const profilingCtx: ProfilingContext = { relationProfiles: [] };
         const { executor: profExec } = createProfiledExecutor(profilingCtx);
         const t0 = performance.now();
-        const query = buildSelectQuery({ modelMeta, allModelsMeta, args: argsWithLimit });
+        const query = buildSelectQuery({ modelMeta, allModelsMeta, args: argsWithLimit, defaultOrderByPk, distinctOrderByPk });
         const t1 = performance.now();
         let records = await profExec(query);
         const t2 = performance.now();
@@ -385,6 +398,8 @@ export function createClient(params: {
         modelMeta,
         allModelsMeta,
         args: argsWithLimit,
+        defaultOrderByPk,
+        distinctOrderByPk,
       });
       let records = await executor(query);
 
@@ -414,6 +429,7 @@ export function createClient(params: {
           allModelsMeta,
           args: argsWithLimit,
           executor,
+          defaultOrderByPk,
         });
         validateOutput({ records, operation: "findUnique" });
         return records[0] ?? null;
@@ -423,7 +439,7 @@ export function createClient(params: {
         const profilingCtx: ProfilingContext = { relationProfiles: [] };
         const { executor: profExec } = createProfiledExecutor(profilingCtx);
         const t0 = performance.now();
-        const query = buildSelectQuery({ modelMeta, allModelsMeta, args: argsWithLimit });
+        const query = buildSelectQuery({ modelMeta, allModelsMeta, args: argsWithLimit, defaultOrderByPk, distinctOrderByPk });
         const t1 = performance.now();
         let records = await profExec(query);
         const t2 = performance.now();
@@ -447,6 +463,8 @@ export function createClient(params: {
         modelMeta,
         allModelsMeta,
         args: argsWithLimit,
+        defaultOrderByPk,
+        distinctOrderByPk,
       });
       let records = await executor(query);
 
@@ -466,9 +484,11 @@ export function createClient(params: {
     async function findUniqueOrThrow(args: Record<string, unknown>) {
       const result = await findUnique(args);
       if (!result) {
-        throw new Error(
-          `No ${modelMeta.name} found for the given where clause`
-        );
+        throw new VibeRequestError({
+          code: "NOT_FOUND",
+          message: `No ${modelMeta.name} found for the given where clause`,
+          meta: { model: modelMeta.name, operation: "findUniqueOrThrow" },
+        });
       }
       return result;
     }
@@ -476,9 +496,11 @@ export function createClient(params: {
     async function findFirstOrThrow(args: Record<string, unknown> = {}) {
       const result = await findFirst(args);
       if (!result) {
-        throw new Error(
-          `No ${modelMeta.name} found for the given where clause`
-        );
+        throw new VibeRequestError({
+          code: "NOT_FOUND",
+          message: `No ${modelMeta.name} found for the given where clause`,
+          meta: { model: modelMeta.name, operation: "findFirstOrThrow" },
+        });
       }
       return result;
     }
@@ -503,6 +525,7 @@ export function createClient(params: {
       const query = buildInsertQuery({
         modelMeta,
         data: processedData,
+        args: deferredCreates.length === 0 ? args : undefined,
       });
       let records = await executor(query);
 
@@ -537,7 +560,7 @@ export function createClient(params: {
         executor,
       });
 
-      records = applySelectFiltering({ records, args, modelMeta });
+      records = applySelectFiltering({ records, args, modelMeta, allowReturningOverride: true });
 
       validateOutput({ records, operation: "create" });
       return records[0]!;
@@ -569,13 +592,16 @@ export function createClient(params: {
         allModelsMeta,
         where: whereInput,
         data: scalarData,
+        args: nestedOps.length === 0 ? args : undefined,
       });
       let records = await executor(query);
 
       if (records.length === 0) {
-        throw new Error(
-          `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.`
-        );
+        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" },
+        });
       }
 
       const updatedRecord = records[0]!;
@@ -599,7 +625,7 @@ export function createClient(params: {
         executor,
       });
 
-      records = applySelectFiltering({ records, args, modelMeta });
+      records = applySelectFiltering({ records, args, modelMeta, allowReturningOverride: true });
 
       validateOutput({ records, operation: "update" });
       return records[0]!;
@@ -629,6 +655,7 @@ export function createClient(params: {
         where: whereInput,
         create: createData,
         update: updateData,
+        args,
       });
 
       let records = await executor(query);
@@ -638,7 +665,11 @@ export function createClient(params: {
       if (records.length === 0) {
         const existing = await findUnique({ where, select: args.select, include: args.include });
         if (existing) return existing;
-        throw new Error(`Upsert failed: could not insert or find ${modelMeta.name}`);
+        throw new VibeRequestError({
+          code: "NOT_FOUND",
+          message: `Upsert failed: could not insert or find ${modelMeta.name}`,
+          meta: { model: modelMeta.name, operation: "upsert" },
+        });
       }
 
       records = await loadRelationsForStrategy({
@@ -649,7 +680,7 @@ export function createClient(params: {
         executor,
       });
 
-      records = applySelectFiltering({ records, args, modelMeta });
+      records = applySelectFiltering({ records, args, modelMeta, allowReturningOverride: true });
 
       validateOutput({ records, operation: "upsert" });
       return records[0]!;
@@ -666,17 +697,20 @@ export function createClient(params: {
         modelMeta,
         allModelsMeta,
         where: whereInput,
+        args,
       });
       let records = await executor(query);
 
       if (records.length === 0) {
-        throw new Error(
-          `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.`
-        );
+        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: "delete" },
+        });
       }
 
       coerceFieldTypes({ records, modelMeta });
-      records = applySelectFiltering({ records, args, modelMeta });
+      records = applySelectFiltering({ records, args, modelMeta, allowReturningOverride: true });
 
       validateOutput({ records, operation: "delete" });
       return records[0]!;
@@ -704,7 +738,11 @@ export function createClient(params: {
     }
 
     async function count(args: Record<string, unknown> = {}) {
-      const countStrategy = options?.countStrategy ?? "direct";
+      const operationCountStrategy = args.countStrategy;
+      const countStrategy =
+        operationCountStrategy === "direct" || operationCountStrategy === "subquery"
+          ? operationCountStrategy
+          : options?.countStrategy ?? "direct";
 
       if (shouldDebug) {
         const t0 = performance.now();
@@ -817,7 +855,7 @@ export function createClient(params: {
         executor,
       });
 
-      records = applySelectFiltering({ records, args, modelMeta });
+      records = applySelectFiltering({ records, args, modelMeta, allowReturningOverride: true });
 
       validateOutput({ records, operation: "createManyAndReturn" });
       return records;
@@ -940,6 +978,7 @@ export function createClient(params: {
         args: params.args,
         executor: params.executor,
         profilingCtx: params.profilingCtx,
+        defaultOrderByPk,
       });
     } else {
       records = await loadRelations({
@@ -949,6 +988,7 @@ export function createClient(params: {
         args: params.args,
         executor: params.executor,
         profilingCtx: params.profilingCtx,
+        defaultOrderByPk,
       });
     }
 
@@ -979,21 +1019,28 @@ export function createClient(params: {
     });
   }
 
-  // $transaction — supports both callback style and array-of-promises style
+  // $transaction — supports both callback style and array-of-promises style.
+  //
+  // Array-of-promises style: wraps pre-created promises in a transaction.
+  // Note: The promises must be created from THIS client's delegates.
+  // They execute within the transaction's commit/rollback boundary, but
+  // their SQL was dispatched on the non-transactional adapter. For full
+  // transactional isolation, use the callback style instead.
   client.$transaction = async function <T>(
-    fnOrPromises: ((tx: Record<string, unknown>) => Promise<T>) | Promise<unknown>[]
+    fnOrPromises: ((tx: Record<string, unknown>) => Promise<T>) | Promise<unknown>[],
+    txOptions?: TransactionOptions
   ): Promise<T | unknown[]> {
     // Array-of-promises style
     if (Array.isArray(fnOrPromises)) {
       return adapter.transaction(async () => {
         return Promise.all(fnOrPromises);
-      });
+      }, txOptions);
     }
 
     // Callback style
     const fn = fnOrPromises as (tx: Record<string, unknown>) => Promise<T>;
     return adapter.transaction(async (txAdapter) => {
-      // Create a transactional executor
+      // 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) {
@@ -1002,7 +1049,11 @@ export function createClient(params: {
             console.log(`[vibeorm:tx] params:`, values);
           }
         }
-        return txAdapter.execute({ text: txParams.text, values });
+        try {
+          return await txAdapter.execute({ text: txParams.text, values });
+        } catch (err) {
+          throw normalizeError({ error: err });
+        }
       }
 
       // Build transactional delegates
@@ -1044,7 +1095,7 @@ export function createClient(params: {
       };
 
       return fn(txClient);
-    });
+    }, txOptions);
   };
 
   // $queryRaw — tagged template literal for safe parameterized queries
@@ -1179,8 +1230,12 @@ function applySelectFiltering(params: {
   records: Record<string, unknown>[];
   args: Record<string, unknown>;
   modelMeta: ModelMeta;
+  allowReturningOverride?: boolean;
 }): Record<string, unknown>[] {
-  const { records, args, modelMeta } = params;
+  const { records, args, modelMeta, allowReturningOverride = false } = params;
+  if (allowReturningOverride && args.returning === true) {
+    return records;
+  }
   const select = args.select as Record<string, boolean | object> | undefined;
   if (!select) return records;