@vibeorm/adapter-pg 1.3.0 → 2.0.0-alpha.10

package/dist/index.js

@@ -0,0 +1,686 @@
+// @bun
+// packages/adapter-pg/src/index.ts
+import pg from "pg";
+
+// packages/adapter-pg/src/errors.ts
+import { VibeError } from "@vibeorm/schema";
+var PG_SQLSTATE_ERROR_CODES = Object.freeze({
+  "23505": "VIBE_UNIQUE_VIOLATION",
+  "23503": "VIBE_FK_VIOLATION",
+  "23502": "VIBE_VALIDATION",
+  "23514": "VIBE_VALIDATION",
+  "22P02": "VIBE_VALIDATION",
+  "42501": "VIBE_PERMISSION_DENIED",
+  "40001": "VIBE_TRANSACTION",
+  "40P01": "VIBE_TRANSACTION",
+  "57014": "VIBE_TRANSACTION"
+});
+var PG_SQLSTATE_REASONS = Object.freeze({
+  "57014": "timeout"
+});
+var SQLSTATE_PATTERN = /^[0-9A-Z]{5}$/;
+function readStringField(params) {
+  const value = params.source[params.key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function pgErrorSqlstate(params) {
+  const { error } = params;
+  if (error === null || typeof error !== "object")
+    return;
+  const code = readStringField({ source: error, key: "code" });
+  return code !== undefined && SQLSTATE_PATTERN.test(code) ? code : undefined;
+}
+function mapPgDriverError(params) {
+  const { error } = params;
+  if (error instanceof VibeError)
+    return error;
+  const source = error !== null && typeof error === "object" ? error : {};
+  const sqlstate = pgErrorSqlstate({ error });
+  const code = (sqlstate === undefined ? undefined : PG_SQLSTATE_ERROR_CODES[sqlstate]) ?? "VIBE_ADAPTER";
+  const meta = {};
+  if (sqlstate !== undefined)
+    meta.sqlstate = sqlstate;
+  const constraint = readStringField({ source, key: "constraint" });
+  if (constraint !== undefined)
+    meta.constraint = constraint;
+  const table = readStringField({ source, key: "table" });
+  if (table !== undefined)
+    meta.table = table;
+  const column = readStringField({ source, key: "column" });
+  if (column !== undefined)
+    meta.column = column;
+  const reason = sqlstate === undefined ? undefined : PG_SQLSTATE_REASONS[sqlstate];
+  if (reason !== undefined)
+    meta.reason = reason;
+  const message = readStringField({ source, key: "message" }) ?? (typeof error === "string" ? error : "unknown postgres driver error");
+  return new VibeError({ code, message, meta, cause: error });
+}
+async function runMapped(fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw mapPgDriverError({ error });
+  }
+}
+
+// packages/adapter-pg/src/params.ts
+class PgArrayParam {
+  values;
+  constructor(values) {
+    this.values = values;
+  }
+}
+function isDriverNativeValue(value) {
+  return value === null || value === undefined || typeof value !== "object" || value instanceof Date || ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
+}
+function serializeParams(params) {
+  return params.values.map((value) => {
+    if (value instanceof PgArrayParam)
+      return value.values;
+    if (isDriverNativeValue(value))
+      return value;
+    return JSON.stringify(value);
+  });
+}
+function serializeParamsRaw(params) {
+  return params.values.map((value) => {
+    if (value instanceof PgArrayParam)
+      return value.values;
+    if (Array.isArray(value))
+      return value;
+    if (isDriverNativeValue(value))
+      return value;
+    return JSON.stringify(value);
+  });
+}
+
+// packages/adapter-pg/src/savepoint-gate.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// packages/adapter-pg/src/savepoints.ts
+function createSavepointCounter() {
+  return { n: 0 };
+}
+function nextSavepointName(params) {
+  return `vibeorm_sp_${params.counter.n++}`;
+}
+
+// packages/adapter-pg/src/savepoint-gate.ts
+var CURRENT = new AsyncLocalStorage;
+function createSavepointScope() {
+  return { depth: 0, state: { counter: createSavepointCounter(), open: null } };
+}
+function runRootScope(params) {
+  return CURRENT.run(params.scope, params.body);
+}
+function scopeTurn(params) {
+  const open = params.scope.state.open;
+  if (mayProceed({ scope: params.scope, open }))
+    return;
+  return waitForTurn({ scope: params.scope });
+}
+async function runNestedSavepoint(params) {
+  const { scope, execute, body } = params;
+  const node = await acquire({ scope });
+  try {
+    if (execute !== undefined)
+      await execute(`SAVEPOINT ${node.name}`);
+    let result;
+    try {
+      result = await CURRENT.run(node.scope, () => body(node.scope));
+    } catch (error) {
+      await drainDescendants({ node });
+      if (execute !== undefined) {
+        try {
+          await execute(`ROLLBACK TO SAVEPOINT ${node.name}`);
+        } catch {}
+      }
+      throw error;
+    }
+    await drainDescendants({ node });
+    if (execute !== undefined)
+      await execute(`RELEASE SAVEPOINT ${node.name}`);
+    return result;
+  } finally {
+    closeNode({ node });
+  }
+}
+function mayProceed(params) {
+  const { scope, open } = params;
+  if (open === null)
+    return true;
+  if (open.scope === scope)
+    return true;
+  if (open.scope.depth < scope.depth)
+    return true;
+  return CURRENT.getStore() === open.scope;
+}
+async function waitForTurn(params) {
+  for (;; ) {
+    const open = params.scope.state.open;
+    if (open === null || mayProceed({ scope: params.scope, open }))
+      return;
+    await open.settled;
+  }
+}
+async function acquire(params) {
+  const { scope } = params;
+  for (;; ) {
+    const open = scope.state.open;
+    if (mayProceed({ scope, open }))
+      return pushNode({ scope, parent: open });
+    await open.settled;
+  }
+}
+function pushNode(params) {
+  const { scope, parent } = params;
+  const state = scope.state;
+  let settle = () => {
+    return;
+  };
+  const settled = new Promise((resolve) => {
+    settle = () => resolve();
+  });
+  const node = {
+    scope: { depth: (parent === null ? 0 : parent.scope.depth) + 1, state },
+    name: nextSavepointName({ counter: state.counter }),
+    parent,
+    settled,
+    settle
+  };
+  state.open = node;
+  return node;
+}
+function closeNode(params) {
+  const { node } = params;
+  const state = node.scope.state;
+  if (state.open === node)
+    state.open = node.parent;
+  node.settle();
+}
+async function drainDescendants(params) {
+  const state = params.node.scope.state;
+  for (;; ) {
+    const open = state.open;
+    if (open === null || open === params.node || open.scope.depth <= params.node.scope.depth)
+      return;
+    await open.settled;
+  }
+}
+
+// packages/adapter-pg/src/statement-cache.ts
+function createStatementNameCache(params) {
+  const max = Math.max(0, params.max);
+  const names = new Map;
+  let counter = 0;
+  return {
+    getName(nameParams) {
+      const { text } = nameParams;
+      const existing = names.get(text);
+      if (existing !== undefined)
+        return existing;
+      if (names.size >= max)
+        return;
+      const name = `vibeorm_${counter++}`;
+      names.set(text, name);
+      return name;
+    },
+    size() {
+      return names.size;
+    }
+  };
+}
+
+// packages/adapter-pg/src/transaction-budget.ts
+import { VibeError as VibeError2 } from "@vibeorm/schema";
+var DEFAULT_DEADLINE_CLOCK = () => Date.now();
+function validateTransactionDeadline(params) {
+  const { options, support, provider } = params;
+  const deadline = options?.deadline;
+  if (deadline === undefined)
+    return;
+  if (support === "unsupported") {
+    throw new VibeError2({
+      code: "VIBE_UNSUPPORTED_CAPABILITY",
+      message: `${provider} cannot enforce a transaction deadline \u2014 remove the \`deadline\` option`,
+      meta: { provider, feature: "transactionDeadline", supported: support }
+    });
+  }
+  if (!Number.isInteger(deadline.totalMs) || deadline.totalMs <= 0) {
+    throw new VibeError2({
+      code: "VIBE_VALIDATION",
+      message: `transaction deadline \`totalMs\` must be a positive integer of milliseconds, received ${String(deadline.totalMs)}`,
+      meta: { provider, feature: "transactionDeadline", totalMs: deadline.totalMs }
+    });
+  }
+  const requested = deadline.enforcement ?? "between-statements";
+  if (requested === "cancel-running-statements" && support !== "cancel-running-statements") {
+    throw new VibeError2({
+      code: "VIBE_UNSUPPORTED_CAPABILITY",
+      message: `${provider} cannot cancel a statement that is already running, so the requested ` + "`cancel-running-statements` deadline guarantee is refused rather than silently downgraded \u2014 " + 'ask for "between-statements" if a budget checked between statements is enough',
+      meta: { provider, feature: "transactionDeadline", requested, supported: support }
+    });
+  }
+}
+function startTransactionBudget(params) {
+  const { options, provider } = params;
+  const clock = params.clock ?? DEFAULT_DEADLINE_CLOCK;
+  const deadline = options?.deadline;
+  const totalMs = deadline === undefined ? null : deadline.totalMs;
+  const enforcement = deadline === undefined ? null : deadline.enforcement ?? "between-statements";
+  const expiresAt = totalMs === null ? null : clock() + totalMs;
+  let outcome = null;
+  const budget = {
+    enforcement,
+    totalMs,
+    statementTimeoutMs: options?.timeout ?? null,
+    remainingMs() {
+      return expiresAt === null ? null : Math.max(0, expiresAt - clock());
+    },
+    expired() {
+      return expiresAt !== null && clock() >= expiresAt;
+    },
+    assertUsable(assertParams) {
+      if (outcome !== null) {
+        throw transactionClosedError({ provider, outcome, stage: assertParams.stage });
+      }
+      if (expiresAt !== null && clock() >= expiresAt) {
+        throw transactionDeadlineError({
+          provider,
+          stage: assertParams.stage,
+          totalMs,
+          overdueMs: clock() - expiresAt
+        });
+      }
+    },
+    close(closeParams) {
+      if (outcome === null)
+        outcome = closeParams.outcome;
+    },
+    get outcome() {
+      return outcome;
+    }
+  };
+  return budget;
+}
+function engineStatementBudgetMs(params) {
+  const { budget } = params;
+  if (budget.enforcement !== "cancel-running-statements")
+    return null;
+  const remaining = budget.remainingMs();
+  if (remaining === null)
+    return null;
+  const totalBound = Math.max(1, Math.ceil(remaining));
+  return budget.statementTimeoutMs !== null && budget.statementTimeoutMs > 0 ? Math.min(totalBound, budget.statementTimeoutMs) : totalBound;
+}
+function transactionDeadlineError(params) {
+  const { provider, stage, totalMs, overdueMs } = params;
+  const what = stage === "commit" ? "the transaction was rolled back instead of committed" : "the statement was never sent and the transaction is being rolled back";
+  return new VibeError2({
+    code: "VIBE_TRANSACTION",
+    message: `transaction deadline of ${totalMs} ms expired ${Math.max(0, Math.round(overdueMs))} ms ago \u2014 ${what}. ` + "Nothing is retried automatically: work the callback did outside the database may already have happened.",
+    meta: { provider, reason: "transaction-deadline", stage, totalMs, overdueMs: Math.max(0, Math.round(overdueMs)) }
+  });
+}
+function transactionClosedError(params) {
+  const { provider, outcome, stage } = params;
+  return new VibeError2({
+    code: "VIBE_TRANSACTION",
+    message: `this transaction has already finished (${outcome}), so its client can no longer be used \u2014 ` + "a handle kept past the end of `$transaction` would run outside the transaction, on a connection " + "that now belongs to someone else",
+    meta: { provider, reason: "transaction-closed", outcome, stage }
+  });
+}
+function transactionOutcomeUnknownError(params) {
+  const { provider, totalMs, cause } = params;
+  return new VibeError2({
+    code: "VIBE_TRANSACTION",
+    message: `transaction deadline of ${totalMs} ms expired and the rollback that should have cleaned up failed \u2014 ` + "the commit state of this transaction is UNKNOWN. It is not retried automatically; inspect the data " + "before deciding.",
+    meta: {
+      provider,
+      reason: "transaction-outcome-unknown",
+      outcome: "unknown",
+      totalMs,
+      rollbackFailed: true
+    },
+    cause
+  });
+}
+function isTransactionDeadlineError(error) {
+  const reason = error?.meta?.reason;
+  return reason === "transaction-deadline";
+}
+
+// packages/adapter-pg/src/transaction-sql.ts
+import { VibeError as VibeError3 } from "@vibeorm/schema";
+var ISOLATION_LEVEL_SQL = Object.freeze({
+  ReadCommitted: "READ COMMITTED",
+  RepeatableRead: "REPEATABLE READ",
+  Serializable: "SERIALIZABLE"
+});
+function beginStatement(params) {
+  const { isolationLevel } = params;
+  return isolationLevel === undefined ? "BEGIN" : `BEGIN ISOLATION LEVEL ${ISOLATION_LEVEL_SQL[isolationLevel]}`;
+}
+function statementTimeoutStatement(params) {
+  const { timeout } = params;
+  if (!Number.isInteger(timeout) || timeout < 0) {
+    throw new VibeError3({
+      code: "VIBE_VALIDATION",
+      message: `transaction timeout must be a non-negative integer of milliseconds, received ${String(timeout)}`,
+      meta: { timeout }
+    });
+  }
+  return `SET LOCAL statement_timeout = ${timeout}`;
+}
+var RAW_OPEN_PATTERN = /^\s*(?:begin|start\s+transaction)\b[^;]*;?\s*$/i;
+var RAW_CLOSE_PATTERN = /^\s*(?:commit|end|rollback|abort)(?:\s+(?:transaction|work))?\s*;?\s*$/i;
+function classifyRawTransactionControl(params) {
+  if (RAW_OPEN_PATTERN.test(params.text))
+    return "open";
+  if (RAW_CLOSE_PATTERN.test(params.text))
+    return "close";
+  return null;
+}
+function refuseNestedTransactionOptions(params) {
+  const { options, provider } = params;
+  if (options === undefined)
+    return;
+  const passed = [];
+  if (options.isolationLevel !== undefined)
+    passed.push("isolationLevel");
+  if (options.timeout !== undefined)
+    passed.push("timeout");
+  if (options.deadline !== undefined)
+    passed.push("deadline");
+  if (passed.length === 0)
+    return;
+  const meta = { provider, nested: true };
+  if (options.isolationLevel !== undefined)
+    meta.isolationLevel = options.isolationLevel;
+  if (options.timeout !== undefined)
+    meta.timeout = options.timeout;
+  if (options.deadline !== undefined)
+    meta.deadline = options.deadline;
+  throw new VibeError3({
+    code: "VIBE_VALIDATION",
+    message: `nested transactions run as savepoints and cannot honor ${passed.join(" or ")} \u2014 a savepoint cannot change the isolation level of the transaction it joins, a nested timeout is not enforceable, and a nested deadline would need its own session setting on a connection it does not own (it inherits the top-level one instead); pass options on the top-level $transaction`,
+    meta
+  });
+}
+
+// packages/adapter-pg/src/index.ts
+var POOL_STATEMENT_NAMES = new WeakMap;
+function guardBackgroundErrors(params) {
+  const { client } = params;
+  if (typeof client.on !== "function")
+    return () => {
+      return;
+    };
+  const swallow = () => {};
+  client.on("error", swallow);
+  return () => {
+    client.removeListener?.("error", swallow);
+  };
+}
+var DIALECT = "postgres";
+var PROVIDER = "postgresql";
+var WIRE = Object.freeze({ dateTime: "native", json: "parsed", numbers: "native" });
+var BUDGETS = Object.freeze({
+  acquireTimeout: true,
+  statementTimeout: "all-statements",
+  transactionDeadline: "cancel-running-statements"
+});
+var NUMERIC_ARRAY_OID = 1231;
+var TEXT_ARRAY_OID = 1009;
+var EXACT_TYPES = {
+  getTypeParser(oid, format) {
+    if (oid === NUMERIC_ARRAY_OID && (format === undefined || format === "text")) {
+      return driverTypeParser(TEXT_ARRAY_OID, "text");
+    }
+    return driverTypeParser(oid, format);
+  }
+};
+var driverTypeParser = pg.types.getTypeParser;
+function pgAdapter(options) {
+  const usePrepared = options?.preparedStatements ?? false;
+  const stmtCacheMax = options?.stmtCacheMax ?? 1000;
+  let pool = null;
+  let ownsPool = false;
+  let rawSession = null;
+  let rawSessionUnguard = null;
+  function getPool() {
+    if (pool !== null)
+      return pool;
+    if (options?.pool !== undefined) {
+      pool = options.pool;
+      ownsPool = false;
+      return pool;
+    }
+    const config = {
+      connectionString: options?.connectionString ?? process.env.DATABASE_URL,
+      max: options?.max ?? 10
+    };
+    if (options?.statementTimeout !== undefined) {
+      config.statement_timeout = options.statementTimeout;
+    }
+    if (options?.connectionTimeout !== undefined) {
+      config.connectionTimeoutMillis = options.connectionTimeout;
+    }
+    const PoolCtor = pg.Pool;
+    pool = new PoolCtor(config);
+    pool.on?.("error", () => {});
+    ownsPool = true;
+    return pool;
+  }
+  function statementNamesFor(params) {
+    const existing = POOL_STATEMENT_NAMES.get(params.pool);
+    if (existing !== undefined)
+      return existing;
+    const created = createStatementNameCache({ max: stmtCacheMax });
+    POOL_STATEMENT_NAMES.set(params.pool, created);
+    return created;
+  }
+  function buildQueryConfig(params) {
+    const values = serializeParams({ values: params.values });
+    if (!usePrepared)
+      return { text: params.text, values, types: EXACT_TYPES };
+    const name = statementNamesFor({ pool: getPool() }).getName({ text: params.text });
+    return name === undefined ? { text: params.text, values, types: EXACT_TYPES } : { name, text: params.text, values, types: EXACT_TYPES };
+  }
+  async function runExecute(params) {
+    const config = buildQueryConfig({ text: params.text, values: params.values });
+    const result = await runMapped(() => params.queryable.query(config));
+    return result.rows;
+  }
+  async function runExecuteUnsafe(params) {
+    const values = params.values === undefined ? undefined : serializeParamsRaw({ values: params.values });
+    const result = await runMapped(() => params.queryable.query({ text: params.text, values, types: EXACT_TYPES }));
+    return { rows: result.rows, affectedRows: result.rowCount ?? 0 };
+  }
+  function createClientAdapter(params) {
+    const { client, scope, budget } = params;
+    async function applyEngineBudget() {
+      const ms = engineStatementBudgetMs({ budget });
+      if (ms === null)
+        return;
+      await runMapped(() => client.query({ text: statementTimeoutStatement({ timeout: ms }) }));
+    }
+    return {
+      dialect: DIALECT,
+      provider: PROVIDER,
+      wire: WIRE,
+      budgets: BUDGETS,
+      async execute(execParams) {
+        const turn = scopeTurn({ scope });
+        if (turn !== undefined)
+          await turn;
+        budget.assertUsable({ stage: "statement" });
+        await applyEngineBudget();
+        return runExecute({ queryable: client, ...execParams });
+      },
+      async executeUnsafe(execParams) {
+        const turn = scopeTurn({ scope });
+        if (turn !== undefined)
+          await turn;
+        budget.assertUsable({ stage: "statement" });
+        await applyEngineBudget();
+        return runExecuteUnsafe({ queryable: client, ...execParams });
+      },
+      async transaction(fn, nestedOptions) {
+        refuseNestedTransactionOptions({ options: nestedOptions, provider: PROVIDER });
+        budget.assertUsable({ stage: "nested" });
+        return runNestedSavepoint({
+          scope,
+          execute: (statement) => runMapped(() => client.query({ text: statement })),
+          body: (child) => fn(createClientAdapter({ client, scope: child, budget }))
+        });
+      },
+      async connect() {},
+      async disconnect() {},
+      formatArrayParam(values) {
+        return new PgArrayParam(values);
+      }
+    };
+  }
+  return {
+    dialect: DIALECT,
+    provider: PROVIDER,
+    wire: WIRE,
+    budgets: BUDGETS,
+    async execute(params) {
+      return runExecute({ queryable: getPool(), ...params });
+    },
+    async executeUnsafe(params) {
+      const control = classifyRawTransactionControl({ text: params.text });
+      if (rawSession !== null) {
+        if (control === "close") {
+          const session = rawSession;
+          const unguard = rawSessionUnguard;
+          rawSession = null;
+          rawSessionUnguard = null;
+          try {
+            return await runExecuteUnsafe({ queryable: session, ...params });
+          } finally {
+            unguard?.();
+            session.release();
+          }
+        }
+        return runExecuteUnsafe({ queryable: rawSession, ...params });
+      }
+      if (control === "open") {
+        const client = await runMapped(() => getPool().connect());
+        const unguard = guardBackgroundErrors({ client });
+        try {
+          const result = await runExecuteUnsafe({ queryable: client, ...params });
+          rawSession = client;
+          rawSessionUnguard = unguard;
+          return result;
+        } catch (error) {
+          unguard();
+          client.release();
+          throw error;
+        }
+      }
+      return runExecuteUnsafe({ queryable: getPool(), ...params });
+    },
+    async transaction(fn, transactionOptions) {
+      validateTransactionDeadline({
+        options: transactionOptions,
+        support: BUDGETS.transactionDeadline,
+        provider: PROVIDER
+      });
+      const client = await runMapped(() => getPool().connect());
+      const unguard = guardBackgroundErrors({ client });
+      const scope = createSavepointScope();
+      const budget = startTransactionBudget({ options: transactionOptions, provider: PROVIDER });
+      let discard = false;
+      try {
+        await runMapped(() => client.query({ text: beginStatement({ isolationLevel: transactionOptions?.isolationLevel }) }));
+        if (transactionOptions?.timeout !== undefined) {
+          const text = statementTimeoutStatement({ timeout: transactionOptions.timeout });
+          await runMapped(() => client.query({ text }));
+        }
+        const result = await runRootScope({
+          scope,
+          body: () => fn(createClientAdapter({ client, scope, budget }))
+        });
+        budget.assertUsable({ stage: "commit" });
+        await runMapped(() => client.query({ text: "COMMIT" }));
+        budget.close({ outcome: "committed" });
+        return result;
+      } catch (error) {
+        try {
+          await client.query({ text: "ROLLBACK" });
+          budget.close({ outcome: "rolled-back" });
+        } catch {
+          discard = true;
+          budget.close({ outcome: "unknown" });
+          if (budget.totalMs !== null && isTransactionDeadlineError(error)) {
+            throw transactionOutcomeUnknownError({
+              provider: PROVIDER,
+              totalMs: budget.totalMs,
+              cause: error
+            });
+          }
+        }
+        throw error;
+      } finally {
+        unguard();
+        client.release(discard);
+      }
+    },
+    async connect() {
+      const client = await runMapped(() => getPool().connect());
+      client.release();
+    },
+    async disconnect() {
+      if (rawSession !== null) {
+        const session = rawSession;
+        const unguard = rawSessionUnguard;
+        rawSession = null;
+        rawSessionUnguard = null;
+        try {
+          await session.query({ text: "ROLLBACK" });
+        } catch {}
+        unguard?.();
+        session.release();
+      }
+      if (pool !== null && ownsPool) {
+        const closing = pool;
+        pool = null;
+        await runMapped(() => closing.end());
+      }
+    },
+    formatArrayParam(values) {
+      return new PgArrayParam(values);
+    }
+  };
+}
+export {
+  validateTransactionDeadline,
+  transactionOutcomeUnknownError,
+  transactionDeadlineError,
+  transactionClosedError,
+  statementTimeoutStatement,
+  startTransactionBudget,
+  serializeParamsRaw,
+  serializeParams,
+  refuseNestedTransactionOptions,
+  pgErrorSqlstate,
+  pgAdapter,
+  nextSavepointName,
+  mapPgDriverError,
+  isTransactionDeadlineError,
+  engineStatementBudgetMs,
+  createStatementNameCache,
+  createSavepointCounter,
+  classifyRawTransactionControl,
+  beginStatement,
+  PgArrayParam,
+  PG_SQLSTATE_REASONS,
+  PG_SQLSTATE_ERROR_CODES,
+  ISOLATION_LEVEL_SQL,
+  DEFAULT_DEADLINE_CLOCK
+};
+
+//# debugId=17E44C1AF7E3C0D164756E2164756E21