@vibeorm/adapter-pg 1.2.0 → 2.0.0-alpha.1

package/src/index.ts

@@ -1,461 +0,0 @@
-/**
- * @vibeorm/adapter-pg — node-postgres (pg) adapter for VibeORM.
- *
- * Uses the `pg` package's Pool for connection pooling with optional
- * named prepared statement caching for PostgreSQL plan reuse.
- */
-
-import type { DatabaseAdapter, QueryResult, TransactionOptions } from "@vibeorm/runtime";
-
-/**
- * Options for creating a pg adapter.
- * Either provide connection parameters or an existing Pool instance.
- */
-export type PgAdapterOptions = {
-  /** PostgreSQL connection URL. Falls back to DATABASE_URL env var if not provided. */
-  connectionString?: string;
-  /** Maximum number of connections in the pool (default: 10). */
-  max?: number;
-  /**
-   * Default statement timeout in milliseconds for all queries (default: none).
-   *
-   * Sets PostgreSQL's `statement_timeout` at the pool level via the pg driver's
-   * `statement_timeout` option, so every query on every connection inherits it
-   * automatically. Queries exceeding this duration are cancelled by PostgreSQL
-   * with SQLSTATE 57014, which VibeORM surfaces as a `VibeTransientError` with
-   * code `STATEMENT_TIMEOUT`.
-   *
-   * Transaction-level `timeout` (via `$transaction` options) overrides this
-   * default for the duration of that transaction using `SET LOCAL statement_timeout`.
-   *
-   * Recommended: Set to a value appropriate for your workload (e.g. 30000 for
-   * general use, 250–1000 for latency-sensitive OLTP services).
-   */
-  statementTimeout?: number;
-  /**
-   * Maximum time in milliseconds to wait for a connection from the pool (default: none).
-   *
-   * When set, pool checkout that exceeds this duration throws an error.
-   * Prevents indefinite blocking when the pool is exhausted under load.
-   *
-   * Maps to pg Pool's `connectionTimeoutMillis` option.
-   */
-  connectionTimeout?: number;
-  /**
-   * Whether to use named prepared statements for read queries (default: false).
-   *
-   * When `true`, the adapter assigns a deterministic name to each unique SQL text,
-   * creating named prepared statements that PostgreSQL caches execution plans for.
-   * This saves ~0.1ms of planning time per query but can cause PostgreSQL to
-   * switch to a "generic plan" after 5 executions, which may choose a worse
-   * index for queries with range filters or skewed data distributions.
-   *
-   * When `false` (default), the adapter sends queries without a statement name.
-   * PostgreSQL replans each execution using the actual parameter values, always
-   * choosing the optimal index.
-   *
-   * Recommendation: Leave as `false` unless profiling shows planning overhead
-   * is a bottleneck (rare — typically only for sub-millisecond queries at
-   * very high throughput).
-   */
-  preparedStatements?: boolean;
-  /**
-   * Maximum number of entries in the prepared statement name cache (default: 1000).
-   * Only used when `preparedStatements: true`.
-   * Each unique SQL text gets a deterministic name for PostgreSQL plan caching.
-   * LRU eviction when full.
-   */
-  stmtCacheMax?: number;
-} | {
-  /** An existing pg Pool instance to use. */
-  pool: PgPool;
-  /**
-   * Whether to use named prepared statements for read queries (default: false).
-   * See the other overload for full documentation.
-   */
-  preparedStatements?: boolean;
-  /**
-   * Maximum number of entries in the prepared statement name cache (default: 1000).
-   * Only used when `preparedStatements: true`.
-   */
-  stmtCacheMax?: number;
-};
-
-// ─── Minimal pg types (avoids hard dependency on @types/pg) ───────
-
-type PgPoolClient = {
-  query(config: { text: string; values?: unknown[]; name?: string }): Promise<PgQueryResult>;
-  query(text: string, values?: unknown[]): Promise<PgQueryResult>;
-  release(): void;
-};
-
-type PgQueryResult = {
-  rows: Record<string, unknown>[];
-  rowCount: number | null;
-  command: string;
-};
-
-type PgPool = {
-  connect(): Promise<PgPoolClient>;
-  query(config: { text: string; values?: unknown[]; name?: string }): Promise<PgQueryResult>;
-  query(text: string, values?: unknown[]): Promise<PgQueryResult>;
-  end(): Promise<void>;
-};
-
-// ─── Internal marker for array params ─────────────────────────────
-
-/**
- * Internal wrapper to tag a value as a PostgreSQL array parameter (for = ANY()).
- * This distinguishes array params from JSON array values so the adapter
- * can JSON.stringify JSON values without affecting array params.
- */
-class PgArrayParam {
-  constructor(public readonly values: unknown[]) {}
-}
-
-// ─── Value Serialization ──────────────────────────────────────────
-
-/**
- * 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]`. 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.
- *
- * 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) {
-      return v.values;
-    }
-    // JSON.stringify plain objects and arrays 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;
-  });
-}
-
-/**
- * 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) => {
-    if (v instanceof PgArrayParam) {
-      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).
- *
- * @example
- * ```ts
- * import { pgAdapter } from "@vibeorm/adapter-pg";
- * import { VibeClient } from "./generated/vibeorm";
- *
- * // With connection string
- * const db = VibeClient({
- *   adapter: pgAdapter({ connectionString: "postgres://...", max: 20 }),
- * });
- *
- * // With existing pg Pool
- * import { Pool } from "pg";
- * const pool = new Pool({ connectionString: "postgres://..." });
- * const db = VibeClient({
- *   adapter: pgAdapter({ pool }),
- * });
- *
- * // With prepared statements enabled (for high-throughput local scenarios)
- * const db2 = VibeClient({
- *   adapter: pgAdapter({ connectionString: "postgres://...", preparedStatements: true }),
- * });
- * ```
- */
-export function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter {
-  const USE_PREPARED = (options && "preparedStatements" in options ? options.preparedStatements : undefined) ?? false;
-  const stmtCacheMax = (options && "stmtCacheMax" in options ? options.stmtCacheMax : undefined) ?? 1000;
-
-  // LRU cache: SQL text -> deterministic prepared statement name
-  const stmtNameCache = new Map<string, string>();
-  let stmtCounter = 0;
-
-  function getOrCreateStmtName(params: { text: string }): string {
-    const { text } = params;
-    let name = stmtNameCache.get(text);
-    if (name) {
-      // Move to end (most recently used)
-      stmtNameCache.delete(text);
-      stmtNameCache.set(text, name);
-      return name;
-    }
-    name = `vibeorm_${stmtCounter++}`;
-    if (stmtNameCache.size >= stmtCacheMax) {
-      const oldestKey = stmtNameCache.keys().next().value;
-      if (oldestKey !== undefined) stmtNameCache.delete(oldestKey);
-    }
-    stmtNameCache.set(text, name);
-    return name;
-  }
-
-  let pool: PgPool | null = null;
-  let ownsPool = false;
-
-  function getPool(): PgPool {
-    if (pool) return pool;
-
-    // Dynamic import of pg to avoid bundling issues
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const pg = require("pg");
-    const Pool = pg.Pool ?? pg.default?.Pool;
-
-    if (options && "pool" in options && options.pool) {
-      pool = options.pool;
-      ownsPool = false;
-    } else {
-      const connectionString =
-        (options && "connectionString" in options ? options.connectionString : undefined) ??
-        process.env.DATABASE_URL;
-      const max = (options && "max" in options ? options.max : undefined) ?? 10;
-      const statementTimeout =
-        options && "statementTimeout" in options ? options.statementTimeout : undefined;
-      const connectionTimeout =
-        options && "connectionTimeout" in options ? options.connectionTimeout : undefined;
-
-      const poolConfig: Record<string, unknown> = {
-        connectionString,
-        max,
-      };
-
-      // Set statement_timeout at the pool level — every connection inherits it
-      if (statementTimeout !== undefined) {
-        poolConfig.statement_timeout = Number(statementTimeout);
-      }
-
-      // Set connectionTimeoutMillis — pool.connect() throws if exceeded
-      if (connectionTimeout !== undefined) {
-        poolConfig.connectionTimeoutMillis = Number(connectionTimeout);
-      }
-
-      pool = new Pool(poolConfig) as PgPool;
-      ownsPool = true;
-    }
-
-    return pool;
-  }
-
-  /**
-   * Execute a parameterized query through a pg client or pool.
-   * - preparedStatements=true: uses named statements for plan caching
-   * - preparedStatements=false: uses unnamed statements (replanned each time)
-   */
-  function buildQueryConfig(params: { text: string; values: unknown[] }): { text: string; values: unknown[]; name?: string } {
-    const serialized = serializeParams({ values: params.values });
-    if (USE_PREPARED) {
-      return {
-        name: getOrCreateStmtName({ text: params.text }),
-        text: params.text,
-        values: serialized,
-      };
-    }
-    return {
-      text: params.text,
-      values: serialized,
-    };
-  }
-
-  /**
-   * 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(execParams) {
-        const config = buildQueryConfig(execParams);
-        const result = await client.query(config);
-        return result.rows;
-      },
-
-      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.n++}`;
-        await client.query(`SAVEPOINT ${spName}`);
-        try {
-          const nestedAdapter = createClientAdapter({ client, savepointCounter });
-          const result = await fn(nestedAdapter);
-          await client.query(`RELEASE SAVEPOINT ${spName}`);
-          return result;
-        } catch (err) {
-          // 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;
-        }
-      },
-
-      async connect() {
-        // No-op for client-level adapter (already connected)
-      },
-
-      async disconnect() {
-        // No-op for client-level adapter (pool manages connections)
-      },
-
-      formatArrayParam(values: unknown[]): unknown {
-        // Wrap in PgArrayParam so serializeParams knows not to JSON.stringify it
-        return new PgArrayParam(values);
-      },
-    };
-  }
-
-  function isolationLevelToSql(params: { level: NonNullable<TransactionOptions["isolationLevel"]> }): string {
-    switch (params.level) {
-      case "ReadCommitted": return "READ COMMITTED";
-      case "RepeatableRead": return "REPEATABLE READ";
-      case "Serializable": return "SERIALIZABLE";
-    }
-  }
-
-  const adapter: DatabaseAdapter = {
-    async execute(params) {
-      const p = getPool();
-      const config = buildQueryConfig(params);
-      const result = await p.query(config);
-      return result.rows;
-    },
-
-    async executeUnsafe(params) {
-      const p = getPool();
-      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 };
-    },
-
-    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 })}`
-          : "";
-        await client.query(`BEGIN${isolation}`);
-
-        if (options?.timeout) {
-          await client.query(`SET LOCAL statement_timeout = ${Number(options.timeout)}`);
-        }
-
-        const txAdapter = createClientAdapter({ client, savepointCounter });
-        const result = await fn(txAdapter);
-        await client.query("COMMIT");
-        return result;
-      } catch (err) {
-        // 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();
-      }
-    },
-
-    async connect() {
-      const p = getPool();
-      const client = await p.connect();
-      client.release();
-    },
-
-    async disconnect() {
-      if (pool && ownsPool) {
-        await pool.end();
-        pool = null;
-      }
-    },
-
-    formatArrayParam(values: unknown[]): unknown {
-      // Wrap in PgArrayParam so serializeParams knows not to JSON.stringify it
-      return new PgArrayParam(values);
-    },
-  };
-
-  return adapter;
-}