@vibeorm/adapter-bun 1.1.8 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/adapter-bun",
-  "version": "1.1.8",
+  "version": "1.3.0",
   "description": "Bun-native database adapter for VibeORM using bun:sql",
   "license": "MIT",
   "keywords": [
@@ -33,7 +33,7 @@
     "bun": ">=1.1.0"
   },
   "dependencies": {
-    "@vibeorm/runtime": "1.1.8"
+    "@vibeorm/runtime": "1.3.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -7,6 +7,7 @@
  */
 
 import type { DatabaseAdapter, QueryResult, TransactionOptions } from "@vibeorm/runtime";
+import { PgArray } from "@vibeorm/runtime";
 
 export type BunAdapterOptions = {
   /** PostgreSQL connection URL. Falls back to DATABASE_URL env var if not provided. */
@@ -30,13 +31,21 @@ export type BunAdapterOptions = {
    */
   statementTimeout?: number;
   /**
-   * Maximum time in milliseconds to wait for a connection from the pool (default: none).
+   * Maximum time in milliseconds to wait when establishing a new connection (default: none).
    *
-   * When set, connection acquisition that exceeds this duration will throw.
-   * Prevents indefinite blocking when the pool is exhausted under load.
+   * Maps directly to bun:sql's `connectionTimeout` constructor option (which expects
+   * seconds — we convert ms → seconds for you). If a connection cannot be established
+   * within this duration, bun:sql throws `ERR_POSTGRES_CONNECTION_TIMEOUT`.
    *
-   * Injected as `connect_timeout` in the PostgreSQL connection URL. Note that
-   * bun:sql uses this for initial TCP connection establishment, not pool checkout.
+   * Note: this is for the initial TCP/handshake establishment, NOT for waiting on
+   * pool checkout once the pool is saturated.
+   *
+   * Historically this was injected as a `connect_timeout=…` URL parameter, but
+   * bun:sql forwards unrecognised URL parameters to PostgreSQL as runtime
+   * configuration settings, and `connect_timeout` is a libpq *client-side* option
+   * (not a server GUC), so PostgreSQL would error with
+   * `unrecognized configuration parameter "connect_timeout"`. The constructor
+   * option is the canonical way to set it.
    */
   connectionTimeout?: number;
   /**
@@ -97,20 +106,60 @@ export type BunAdapterOptions = {
 
 // ─── Internal bun:sql types ───────────────────────────────────────
 
+/**
+ * A bun:sql "reserved" connection (single physical connection checked out
+ * from the pool). Used by the manual `BEGIN … COMMIT` transaction path.
+ *
+ * Note: a reserved connection has NO `.begin()` or `.reserve()` — any nested
+ * transaction must be implemented via SAVEPOINTs on the same connection.
+ */
 type SqlReserved = {
   (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
   unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
   release(): void;
 };
 
+/**
+ * The transactional handle passed to the `sql.begin(callback)` callback.
+ * Modern bun:sql exposes `.savepoint(fn)` which creates a savepoint-scoped
+ * sub-transaction (the correct API for nested transactions). Calling
+ * `.begin()` here throws "cannot call begin inside a transaction use
+ * savepoint() instead" — so we always prefer `savepoint` when present.
+ *
+ * Older / minimal bun:sql versions may lack `.savepoint`, in which case we
+ * fall back to explicit `SAVEPOINT <name>` SQL via `.unsafe()`.
+ */
+type SqlTransaction = {
+  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
+  unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
+  savepoint?: <T>(fn: (tx: SqlTransaction) => Promise<T>) => Promise<T>;
+};
+
 type SqlInstance = {
   (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
   unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
-  begin<T>(fn: (tx: SqlInstance) => Promise<T>): Promise<T>;
+  begin<T>(fn: (tx: SqlTransaction) => Promise<T>): Promise<T>;
   reserve(): Promise<SqlReserved>;
   close(): Promise<void>;
 };
 
+/**
+ * Anything that can execute SQL through bun:sql — pool, reserved connection,
+ * or in-transaction handle. Used by the unified adapter created at every
+ * nesting level.
+ */
+type SqlSource = SqlInstance | SqlReserved | SqlTransaction;
+
+/**
+ * Whether the SQL source is the outermost pool (can issue real BEGIN/COMMIT
+ * or use `sql.begin()`) or is already inside a transaction (must use
+ * SAVEPOINTs for nesting).
+ */
+type ParentMode = "pool" | "tx";
+
+/** Shared monotonic counter for savepoint naming across one top-level tx. */
+type SavepointCounter = { n: number };
+
 /**
  * Create a VibeORM database adapter using Bun's built-in SQL driver.
  *
@@ -152,16 +201,19 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
    * Resolve the connection URL, injecting startup parameters as needed.
    * Falls back to DATABASE_URL env var when no explicit URL is provided.
    *
-   * Injects via the PostgreSQL `options` startup parameter:
+   * Injects via the PostgreSQL `options` startup parameter (server-side runtime
+   * configuration; valid because `options` is a real Postgres startup-protocol
+   * parameter that the server parses for `-c key=value` settings):
    * - plan_cache_mode (unless "auto")
    * - statement_timeout (if configured)
    *
-   * Injects as a URL parameter:
-   * - connect_timeout (if configured, converted to seconds for PG)
+   * `connect_timeout` is NOT injected here — it's a libpq client-side option,
+   * not a server GUC, and bun:sql would forward it to the server as an
+   * unrecognised configuration parameter. We pass it via the bun:sql
+   * `connectionTimeout` constructor option instead (see getSql()).
    */
   function resolveConnectionUrl(): string | undefined {
     const STATEMENT_TIMEOUT = options?.statementTimeout;
-    const CONNECTION_TIMEOUT = options?.connectionTimeout;
 
     // Build startup options string (for -c parameters)
     const startupParts: string[] = [];
@@ -172,29 +224,16 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
       startupParts.push(`-c statement_timeout=${Number(STATEMENT_TIMEOUT)}`);
     }
 
-    const needsUrlMutation = startupParts.length > 0 || CONNECTION_TIMEOUT !== undefined;
+    const needsUrlMutation = startupParts.length > 0;
     if (!needsUrlMutation) return options?.url;
 
     const baseUrl = options?.url ?? process.env.DATABASE_URL;
     if (!baseUrl) return undefined;
 
-    let url = baseUrl;
-
-    // Inject startup options (-c params)
-    if (startupParts.length > 0) {
-      url = appendStartupOption({
-        url,
-        option: startupParts.join(" "),
-      });
-    }
-
-    // Inject connect_timeout as a URL parameter (PG uses seconds)
-    if (CONNECTION_TIMEOUT !== undefined) {
-      const separator = url.includes("?") ? "&" : "?";
-      url = `${url}${separator}connect_timeout=${Math.ceil(CONNECTION_TIMEOUT / 1000)}`;
-    }
-
-    return url;
+    return appendStartupOption({
+      url: baseUrl,
+      option: startupParts.join(" "),
+    });
   }
 
   function getSql(): SqlInstance {
@@ -215,6 +254,13 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
       // See: https://github.com/oven-sh/bun/issues/20294
     };
 
+    // Connection establishment timeout — bun:sql expects seconds.
+    // We accept milliseconds in our public API to stay consistent with pgAdapter
+    // and Node convention, then convert here.
+    if (options?.connectionTimeout !== undefined) {
+      sqlOptions.connectionTimeout = Math.max(1, Math.ceil(options.connectionTimeout / 1000));
+    }
+
     const connectionUrl = resolveConnectionUrl();
     if (connectionUrl) {
       sqlInstance = new SQL(connectionUrl, sqlOptions) as unknown as SqlInstance;
@@ -260,29 +306,107 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
    * Convert a JS array to a PostgreSQL array literal string `{val1,val2,...}`.
    * bun:sql's extended query protocol sends values as strings, so PostgreSQL
    * needs array parameters in its native array literal format.
+   *
+   * Element handling:
+   *  - `null` / `undefined` → `NULL`
+   *  - `number` / `bigint` / `boolean` → unquoted primitive
+   *  - `Date` → ISO-8601 string (quoted+escaped) so PG can parse it as
+   *    `timestamp[]` / `timestamptz[]`. Using the default `String(d)` would
+   *    yield a non-ISO format like `Mon May 24 2026 …` that PG cannot parse.
+   *  - `Buffer` / `Uint8Array` → not supported inside array literals; throw
+   *    a clear error instead of silently producing `[object Object]`.
+   *  - `string` → quoted with `"`/`\` escaping
+   *  - other `object` → `JSON.stringify` then quoted+escaped (covers users
+   *    putting plain objects into a `Json[]` / `Jsonb[]` scalar list).
    */
   function toPgArrayLiteral(arr: unknown[]): string {
+    const escape = (str: string): string =>
+      `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
     const escaped = arr.map((v) => {
       if (v === null || v === undefined) return "NULL";
-      if (typeof v === "number" || typeof v === "bigint" || typeof v === "boolean") return String(v);
-      const str = String(v);
-      return `"${str.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+      if (typeof v === "number" || typeof v === "bigint" || typeof v === "boolean") {
+        return String(v);
+      }
+      if (v instanceof Date) {
+        return escape(v.toISOString());
+      }
+      if (Buffer.isBuffer(v) || v instanceof Uint8Array) {
+        throw new Error(
+          "toPgArrayLiteral: Buffer/Uint8Array array elements are not supported"
+        );
+      }
+      if (typeof v === "string") {
+        return escape(v);
+      }
+      if (typeof v === "object") {
+        return escape(JSON.stringify(v));
+      }
+      return escape(String(v));
     });
     return `{${escaped.join(",")}}`;
   }
 
+  /**
+   * Normalise raw-path parameter values for bun:sql.
+   *
+   * bun:sql's extended query protocol sends params as strings, so a plain JS
+   * array binding cannot be auto-converted to a PG array literal by the driver.
+   * The ORM hot path wraps array params in `PgArray` and converts them via
+   * `formatArrayParam` before they reach the adapter — but raw queries
+   * (`$queryRawUnsafe`, `$queryRaw` template-literal, `$executeRaw*`) hand the
+   * user's array straight through.
+   *
+   * To make `db.$queryRawUnsafe('… WHERE "id" = ANY($1)', [1,2,3])` actually
+   * match rows, we convert any plain JS array element in the param list to a
+   * PG array literal here. Non-array values pass through unchanged so that
+   * bun:sql's native handling (numbers, strings, Dates, Buffers, plain objects
+   * for json columns when bun supports it) remains in effect.
+   */
+  function normalizeRawValues(values: unknown[] | undefined): unknown[] | undefined {
+    if (!values || values.length === 0) return values;
+    let mutated: unknown[] | null = null;
+    for (let i = 0; i < values.length; i++) {
+      const v = values[i];
+      if (Array.isArray(v)) {
+        if (!mutated) mutated = values.slice();
+        mutated[i] = toPgArrayLiteral(v);
+      }
+    }
+    return mutated ?? values;
+  }
+
   /**
    * Execute a query using the configured strategy.
    * - preparedStatements=true: uses synthetic tagged templates (named prepared stmts)
    * - preparedStatements=false: uses sql.unsafe() (replanned each time)
+   *
+   * Note: this is the ORM hot path. Scalar-list / `= ANY()` array values are
+   * already wrapped in `PgArray` by the query builder and converted to a PG
+   * array literal string via `formatArrayParam` before they reach here, so we
+   * intentionally do NOT touch raw JS arrays here (that would corrupt JSON
+   * column writes that genuinely pass a JS array as a JSON value).
    */
   async function executeQuery(sql: SqlInstance, params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> {
+    // Defence-in-depth: if any value is a runtime PgArray that slipped through
+    // (e.g. a caller bypassed `client.ts`'s formatArrayParam unwrap), convert
+    // it to the PG array literal string that bun:sql actually needs. The
+    // standard ORM path has already done this conversion via `formatArrayParam`,
+    // so the loop is a near-zero-cost guard for the normal case.
+    // Bug 3 — see .ai/bug-report-2026-05-24.md.
+    let values: unknown[] = params.values;
+    for (let i = 0; i < params.values.length; i++) {
+      if (params.values[i] instanceof PgArray) {
+        if (values === params.values) values = params.values.slice();
+        values[i] = toPgArrayLiteral((params.values[i] as PgArray).values);
+      }
+    }
     if (USE_PREPARED) {
       const strings = getOrCreateTemplate({ text: params.text });
-      const result = await sql(strings, ...params.values);
+      const result = await sql(strings, ...values);
       return result as Record<string, unknown>[];
     }
-    const result = await sql.unsafe(params.text, params.values);
+    const result = await sql.unsafe(params.text, values);
     return result as Record<string, unknown>[];
   }
 
@@ -294,14 +418,118 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
     }
   }
 
-  function createAdapter(sql: SqlInstance): DatabaseAdapter {
+  /**
+   * Build the typed adapter facade over any bun:sql source — the pool, a
+   * reserved connection, or an in-transaction handle. The `parentMode`
+   * discriminator tells `.transaction()` whether a nested call should issue
+   * a real BEGIN/COMMIT (or `sql.begin()`) at the pool level, or open a
+   * SAVEPOINT on the current connection.
+   *
+   * `savepointCounter` is shared by reference across every adapter created
+   * for one top-level transaction, so sibling and deeply-nested transactions
+   * always get distinct savepoint names like `vibeorm_sp_0`, `vibeorm_sp_1`,
+   * `vibeorm_sp_2`, …
+   */
+  function createAdapter(params: {
+    sql: SqlSource;
+    parentMode: ParentMode;
+    savepointCounter: SavepointCounter;
+  }): DatabaseAdapter {
+    const { sql, parentMode, savepointCounter } = params;
+
+    async function txViaSavepoint<T>(innerFn: (txAdapter: DatabaseAdapter) => Promise<T>): Promise<T> {
+      // We're inside a transaction already — open a SAVEPOINT on this
+      // connection. Prefer the driver's native `tx.savepoint()` if exposed
+      // (modern bun:sql); else fall back to explicit `SAVEPOINT` SQL on
+      // either the in-tx handle (which lacks `.savepoint`) or a reserved
+      // connection holding a manual `BEGIN`.
+      const txSql = sql as SqlTransaction;
+      if (typeof txSql.savepoint === "function") {
+        return txSql.savepoint(async (sp) => {
+          const nestedAdapter = createAdapter({
+            sql: sp,
+            parentMode: "tx",
+            savepointCounter,
+          });
+          return innerFn(nestedAdapter);
+        });
+      }
+
+      // Fallback: explicit SAVEPOINT via unsafe(). The counter is shared by
+      // reference, so sibling/nested SAVEPOINTs never collide.
+      const spName = `vibeorm_sp_${savepointCounter.n++}`;
+      await txSql.unsafe(`SAVEPOINT ${spName}`);
+      try {
+        const nestedAdapter = createAdapter({
+          sql: txSql,
+          parentMode: "tx",
+          savepointCounter,
+        });
+        const result = await innerFn(nestedAdapter);
+        await txSql.unsafe(`RELEASE SAVEPOINT ${spName}`);
+        return result;
+      } catch (err) {
+        // Best-effort rollback — mirror pg adapter behaviour so we never
+        // mask the original error if the ROLLBACK itself fails.
+        try { await txSql.unsafe(`ROLLBACK TO SAVEPOINT ${spName}`); } catch { /* rollback best-effort */ }
+        throw err;
+      }
+    }
+
+    async function txViaPool<T>(
+      innerFn: (txAdapter: DatabaseAdapter) => Promise<T>,
+      options?: TransactionOptions
+    ): Promise<T> {
+      const pool = sql as SqlInstance;
+
+      // Fast path: no custom options — use native sql.begin() for best perf.
+      if (!options?.isolationLevel && !options?.timeout) {
+        return pool.begin(async (txSql: SqlTransaction) => {
+          const txAdapter = createAdapter({
+            sql: txSql,
+            parentMode: "tx",
+            savepointCounter,
+          });
+          return innerFn(txAdapter);
+        });
+      }
+
+      // Manual path: reserve a single connection for custom BEGIN options.
+      const reserved = await pool.reserve();
+      try {
+        const isolation = options.isolationLevel
+          ? ` ISOLATION LEVEL ${isolationLevelToSql({ level: options.isolationLevel })}`
+          : "";
+        await reserved.unsafe(`BEGIN${isolation}`);
+
+        if (options.timeout) {
+          await reserved.unsafe(`SET LOCAL statement_timeout = ${Number(options.timeout)}`);
+        }
+
+        const txAdapter = createAdapter({
+          sql: reserved,
+          parentMode: "tx",
+          savepointCounter,
+        });
+        const result = await innerFn(txAdapter);
+        await reserved.unsafe("COMMIT");
+        return result;
+      } catch (err) {
+        try { await reserved.unsafe("ROLLBACK"); } catch { /* rollback best-effort */ }
+        throw err;
+      } finally {
+        reserved.release();
+      }
+    }
+
     return {
-      async execute(params) {
-        return executeQuery(sql, params);
+      async execute(execParams) {
+        return executeQuery(sql as SqlInstance, execParams);
       },
 
-      async executeUnsafe(params) {
-        const result = await sql.unsafe(params.text, params.values);
+      async executeUnsafe(execParams) {
+        const values = normalizeRawValues(execParams.values);
+        const result = await sql.unsafe(execParams.text, values);
         const resultAny = result as unknown as Record<string, unknown>;
         let affectedRows: number;
         if (typeof resultAny.count === "number") {
@@ -318,46 +546,27 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
       },
 
       async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T> {
-        // Fast path: no custom options — use native sql.begin() for best performance
-        if (!options?.isolationLevel && !options?.timeout) {
-          return sql.begin(async (txSql: SqlInstance) => {
-            const txAdapter = createAdapter(txSql);
-            return fn(txAdapter);
-          });
-        }
-
-        // Manual path: reserve a connection for custom BEGIN options
-        const reserved = await sql.reserve();
-        try {
-          const isolation = options?.isolationLevel
-            ? ` ISOLATION LEVEL ${isolationLevelToSql({ level: options.isolationLevel })}`
-            : "";
-          await reserved.unsafe(`BEGIN${isolation}`);
-
-          if (options?.timeout) {
-            await reserved.unsafe(`SET LOCAL statement_timeout = ${Number(options.timeout)}`);
-          }
-
-          const txAdapter = createAdapter(reserved as unknown as SqlInstance);
-          const result = await fn(txAdapter);
-          await reserved.unsafe("COMMIT");
-          return result;
-        } catch (err) {
-          try { await reserved.unsafe("ROLLBACK"); } catch { /* rollback best-effort */ }
-          throw err;
-        } finally {
-          reserved.release();
-        }
+        return parentMode === "pool"
+          ? txViaPool(fn, options)
+          : txViaSavepoint(fn);
       },
 
       async connect() {
-        const reserved = await sql.reserve();
-        reserved.release();
+        // Only the pool-level adapter can reserve a fresh connection.
+        // Adapters scoped to a reserved/tx connection are already connected.
+        if (parentMode === "pool") {
+          const reserved = await (sql as SqlInstance).reserve();
+          reserved.release();
+        }
       },
 
       async disconnect() {
-        await sql.close();
-        sqlInstance = null;
+        if (parentMode === "pool") {
+          await (sql as SqlInstance).close();
+          sqlInstance = null;
+        }
+        // Inside a transaction `.disconnect()` is a no-op — the pool owns
+        // the connection lifecycle.
       },
 
       formatArrayParam(values: unknown[]): unknown {
@@ -366,22 +575,34 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
     };
   }
 
-  // Create a lazy adapter that initializes the SQL connection on first use
+  // Create a lazy adapter that initializes the SQL connection on first use.
+  // Each top-level call lazily resolves the underlying `SqlInstance`. The
+  // `savepointCounter` for every top-level transaction is freshly created
+  // inside that transaction's own `txViaPool` / `txViaSavepoint` — at the
+  // pool level there's no shared counter to manage.
+  function poolAdapter(): DatabaseAdapter {
+    return createAdapter({
+      sql: getSql(),
+      parentMode: "pool",
+      savepointCounter: { n: 0 },
+    });
+  }
+
   const adapter: DatabaseAdapter = {
     async execute(params) {
-      return createAdapter(getSql()).execute(params);
+      return poolAdapter().execute(params);
     },
 
     async executeUnsafe(params) {
-      return createAdapter(getSql()).executeUnsafe(params);
+      return poolAdapter().executeUnsafe(params);
     },
 
     async transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T> {
-      return createAdapter(getSql()).transaction(fn, options);
+      return poolAdapter().transaction(fn, options);
     },
 
     async connect() {
-      return createAdapter(getSql()).connect();
+      return poolAdapter().connect();
     },
 
     async disconnect() {