@vibeorm/adapter-pg 1.1.8 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/adapter-pg",
-  "version": "1.1.8",
+  "version": "1.3.0",
   "description": "node-postgres adapter for VibeORM — use VibeORM with pg on Bun or Node.js",
   "license": "MIT",
   "keywords": [
@@ -31,7 +31,7 @@
     "url": "https://github.com/vibeorm/vibeorm/issues"
   },
   "dependencies": {
-    "@vibeorm/runtime": "1.1.8"
+    "@vibeorm/runtime": "1.3.0"
   },
   "peerDependencies": {
     "pg": ">=8"

package/src/index.ts

@@ -6,6 +6,7 @@
  */
 
 import type { DatabaseAdapter, QueryResult, TransactionOptions } from "@vibeorm/runtime";
+import { PgArray } from "@vibeorm/runtime";
 
 /**
  * Options for creating a pg adapter.
@@ -116,21 +117,40 @@ class PgArrayParam {
 // ─── Value Serialization ──────────────────────────────────────────
 
 /**
- * Pre-process query parameter values for the pg driver.
+ * Pre-process query parameter values for the pg driver — ORM hot path.
  *
  * The pg driver auto-converts JS arrays to PostgreSQL array literals (`{1,2,3}`)
- * and JS objects to `[object Object]`. For json/jsonb columns, we need these
- * serialized as JSON strings instead. Since the query builder is driver-agnostic
- * and doesn't serialize values, we handle it here at the adapter boundary.
+ * and JS objects to `[object Object]`. The ORM doesn't know which column a
+ * value lands in (it doesn't carry typed-parameter hints), and for `json` /
+ * `jsonb` columns it wants any JS object OR JS array passed through as JSON.
+ * Therefore on the ORM path we JSON.stringify both objects and arrays —
+ * scalar-list array values (`= ANY()` / `String[]` / `Int[]`) are already
+ * tagged with `PgArrayParam` by `formatArrayParam` and unwrapped here without
+ * stringification.
  *
- * - PgArrayParam wrappers are unwrapped to raw arrays (for = ANY() queries)
- * - Plain objects and arrays are JSON.stringify'd (for json/jsonb columns)
- * - Dates, Buffers, null, and primitives pass through unchanged
+ * Raw-query paths use `serializeParamsRaw` instead (see below) which does NOT
+ * stringify plain JS arrays so that `db.$queryRawUnsafe('… WHERE "id" = ANY($1)',
+ * [1, 2, 3])` actually matches rows.
+ *
+ * - PgArrayParam wrappers are unwrapped to raw arrays (for = ANY() queries
+ *   and for scalar-list array operations the ORM emits).
+ * - Plain objects and arrays are JSON.stringify'd (for json/jsonb columns).
+ * - Dates, Buffers, null, and primitives pass through unchanged.
+ *
+ * TODO: PgArrayParam nesting is not currently reachable through the public API,
+ * so the unwrap is intentionally non-recursive. If PgArrayParam ever becomes
+ * user-constructible and nestable inside other arrays/objects, make recursive.
  */
 function serializeParams(params: { values: unknown[] }): unknown[] {
   return params.values.map((v) => {
-    // Unwrap tagged array params — these are for = ANY() and must remain as raw arrays
-    if (v instanceof PgArrayParam) {
+    // Unwrap any array-param wrapper — covers BOTH the adapter's internal
+    // PgArrayParam (set by this adapter's formatArrayParam) AND the runtime's
+    // PgArray marker. The runtime's `client.ts` normally unwraps PgArray into
+    // PgArrayParam via `adapter.formatArrayParam(...)`, but recognising both
+    // here is defence-in-depth — any future executor path that bypasses that
+    // unwrap step would otherwise silently double-serialise the array as JSON.
+    // Bug 3 — see .ai/bug-report-2026-05-24.md.
+    if (v instanceof PgArrayParam || v instanceof PgArray) {
       return v.values;
     }
     // JSON.stringify plain objects and arrays for json/jsonb columns
@@ -148,6 +168,50 @@ function serializeParams(params: { values: unknown[] }): unknown[] {
   });
 }
 
+/**
+ * Pre-process query parameter values for the pg driver — RAW QUERY path.
+ *
+ * Identical to `serializeParams` EXCEPT that plain JS arrays are passed through
+ * to `pg` instead of being JSON.stringify'd. node-postgres natively converts a
+ * JS array to a PostgreSQL array literal, which is what users expect when they
+ * write raw queries like:
+ *
+ *   db.$queryRawUnsafe('SELECT * FROM "User" WHERE "id" = ANY($1)', [1, 2, 3])
+ *   db.$queryRaw`SELECT * FROM "User" WHERE "id" = ANY(${[1, 2, 3]})`
+ *
+ * (Previously the adapter JSON.stringify'd the array, producing `"[1,2,3]"` —
+ *  a JSON string that PG could not match against any row.)
+ *
+ * Tradeoff: a user who wants to bind a JS array INTO a `json` / `jsonb` column
+ * from a raw query must `JSON.stringify(...)` it themselves. Plain objects are
+ * still auto-stringified here, so the common `{ foo: "bar" }` case continues
+ * to work.
+ */
+function serializeParamsRaw(params: { values: unknown[] }): unknown[] {
+  return params.values.map((v) => {
+    // Recognise both wrappers — see serializeParams for rationale (Bug 3).
+    if (v instanceof PgArrayParam || v instanceof PgArray) {
+      return v.values;
+    }
+    // Plain JS arrays pass through — pg converts to PG array literal natively.
+    if (Array.isArray(v)) {
+      return v;
+    }
+    // JSON.stringify plain non-array objects for json/jsonb columns.
+    if (
+      v !== null &&
+      v !== undefined &&
+      typeof v === "object" &&
+      !(v instanceof Date) &&
+      !Buffer.isBuffer(v) &&
+      !(v instanceof Uint8Array)
+    ) {
+      return JSON.stringify(v);
+    }
+    return v;
+  });
+}
+
 /**
  * Create a VibeORM database adapter using node-postgres (pg).
  *
@@ -266,34 +330,48 @@ export function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter {
     };
   }
 
-  function createClientAdapter(client: PgPoolClient): DatabaseAdapter {
-    let savepointCounter = 0;
+  /**
+   * Build a client-scoped adapter (already inside a transaction). Nested
+   * `.transaction(fn)` calls open SAVEPOINTs on the same client.
+   *
+   * `savepointCounter` is shared by reference across every adapter created
+   * for one top-level transaction so sibling and deeply-nested savepoints
+   * never collide (Bug #11 — counter previously reset at each nesting level,
+   * so two sibling sub-transactions both got `vibeorm_sp_0`).
+   */
+  function createClientAdapter(params: {
+    client: PgPoolClient;
+    savepointCounter: { n: number };
+  }): DatabaseAdapter {
+    const { client, savepointCounter } = params;
 
     return {
-      async execute(params) {
-        const config = buildQueryConfig(params);
+      async execute(execParams) {
+        const config = buildQueryConfig(execParams);
         const result = await client.query(config);
         return result.rows;
       },
 
-      async executeUnsafe(params) {
-        const values = params.values ? serializeParams({ values: params.values }) : undefined;
-        const result = await client.query(params.text, values);
+      async executeUnsafe(execParams) {
+        const values = execParams.values ? serializeParamsRaw({ values: execParams.values }) : undefined;
+        const result = await client.query(execParams.text, values);
         const affectedRows = result.rowCount ?? 0;
         return { rows: result.rows, affectedRows };
       },
 
       async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T> {
-        // Nested transactions use unique SAVEPOINTs
-        const spName = `vibeorm_sp_${savepointCounter++}`;
+        // Nested transactions use unique SAVEPOINTs.
+        const spName = `vibeorm_sp_${savepointCounter.n++}`;
         await client.query(`SAVEPOINT ${spName}`);
         try {
-          const nestedAdapter = createClientAdapter(client);
+          const nestedAdapter = createClientAdapter({ client, savepointCounter });
           const result = await fn(nestedAdapter);
           await client.query(`RELEASE SAVEPOINT ${spName}`);
           return result;
         } catch (err) {
-          await client.query(`ROLLBACK TO SAVEPOINT ${spName}`);
+          // Bug #7: best-effort rollback — never mask the original error if
+          // `ROLLBACK TO SAVEPOINT` itself fails (e.g. the client died).
+          try { await client.query(`ROLLBACK TO SAVEPOINT ${spName}`); } catch { /* rollback best-effort */ }
           throw err;
         }
       },
@@ -331,7 +409,7 @@ export function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter {
 
     async executeUnsafe(params) {
       const p = getPool();
-      const values = params.values ? serializeParams({ values: params.values }) : undefined;
+      const values = params.values ? serializeParamsRaw({ values: params.values }) : undefined;
       const result = await p.query(params.text, values);
       const affectedRows = result.rowCount ?? 0;
       return { rows: result.rows, affectedRows };
@@ -340,6 +418,9 @@ export function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter {
     async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T> {
       const p = getPool();
       const client = await p.connect();
+      // Per top-level transaction: one shared savepoint counter for all
+      // sibling/nested SAVEPOINTs (Bug #11).
+      const savepointCounter = { n: 0 };
       try {
         const isolation = options?.isolationLevel
           ? ` ISOLATION LEVEL ${isolationLevelToSql({ level: options.isolationLevel })}`
@@ -350,12 +431,15 @@ export function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter {
           await client.query(`SET LOCAL statement_timeout = ${Number(options.timeout)}`);
         }
 
-        const txAdapter = createClientAdapter(client);
+        const txAdapter = createClientAdapter({ client, savepointCounter });
         const result = await fn(txAdapter);
         await client.query("COMMIT");
         return result;
       } catch (err) {
-        await client.query("ROLLBACK");
+        // Bug #7: best-effort ROLLBACK — never mask the original error if
+        // ROLLBACK itself fails (e.g. the connection was killed). pg's pool
+        // auto-discards the client on `release()` if its state is broken.
+        try { await client.query("ROLLBACK"); } catch { /* rollback best-effort */ }
         throw err;
       } finally {
         client.release();