@ultimat3/db 1.0.0

package/src/sql.ts

@@ -0,0 +1,152 @@
+// Single responsibility: build parameterised SQL. String interpolation is how every SQL
+// injection ships, and an agent writing SQL cannot be trusted to remember the difference
+// between a value and a fragment — so the tag binds scalars to `$1..$n` and refuses anything
+// else outright. `raw()` is the one audited escape hatch, and it is visible in review.
+
+import { identifierUnsafe, sqlUnsafe } from './errors';
+
+export interface SqlFragment {
+  readonly text: string;
+  readonly values: readonly unknown[];
+}
+
+/** Only fragments carrying this brand may be spliced into another fragment. */
+const SQL_BRAND: unique symbol = Symbol.for('ultimate.db.sql');
+
+interface Compiled extends SqlFragment {
+  readonly [SQL_BRAND]: 'sql' | 'raw';
+  /**
+   * `chunks.length === values.length + 1`. Keeping the pre-split parts means nesting
+   * renumbers parameters by rebuilding, never by re-parsing `$n` out of `.text` — which
+   * would corrupt a `raw()` fragment that legitimately contains a `$` token.
+   */
+  readonly chunks: readonly string[];
+}
+
+export function isSqlFragment(value: unknown): value is SqlFragment {
+  return typeof value === 'object' && value !== null && SQL_BRAND in value;
+}
+
+const SCALAR_TYPES = new Set(['string', 'number', 'boolean', 'bigint', 'undefined']);
+
+/** What Postgres can accept as a bound parameter. Everything else is a programming error. */
+function isBoundValue(value: unknown): boolean {
+  if (value === null) return true;
+  if (SCALAR_TYPES.has(typeof value)) return true;
+  if (value instanceof Date) return true;
+  if (value instanceof Uint8Array) return true;
+  if (Array.isArray(value)) return value.every(isBoundValue);
+  return false;
+}
+
+function describe(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array containing a non-scalar';
+  if (typeof value === 'object' && 'text' in (value as Record<string, unknown>)) {
+    return 'an object shaped like a SqlFragment but not produced by sql`` or raw()';
+  }
+  return `a ${typeof value}`;
+}
+
+function render(chunks: readonly string[]): string {
+  let text = chunks[0] ?? '';
+  for (let index = 1; index < chunks.length; index += 1) {
+    text += `$${index}${chunks[index] ?? ''}`;
+  }
+  return text;
+}
+
+function compile(chunks: readonly string[], values: readonly unknown[]): Compiled {
+  return {
+    [SQL_BRAND]: 'sql',
+    chunks,
+    values,
+    text: render(chunks),
+  };
+}
+
+/** Accumulates chunks/values so appending a fragment is a splice, not a string rewrite. */
+class Builder {
+  private readonly chunks: string[] = [''];
+  private readonly values: unknown[] = [];
+
+  text(part: string): void {
+    this.chunks[this.chunks.length - 1] = `${this.chunks[this.chunks.length - 1] ?? ''}${part}`;
+  }
+
+  value(value: unknown): void {
+    this.values.push(value === undefined ? null : value);
+    this.chunks.push('');
+  }
+
+  fragment(nested: Compiled): void {
+    this.text(nested.chunks[0] ?? '');
+    for (let index = 1; index < nested.chunks.length; index += 1) {
+      this.value(nested.values[index - 1]);
+      this.text(nested.chunks[index] ?? '');
+    }
+  }
+
+  done(): Compiled {
+    return compile([...this.chunks], [...this.values]);
+  }
+}
+
+export function sql(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlFragment {
+  const builder = new Builder();
+  builder.text(strings[0] ?? '');
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (isSqlFragment(value)) builder.fragment(value as Compiled);
+    else if (isBoundValue(value)) builder.value(value);
+    else throw sqlUnsafe(describe(value), index + 1);
+    builder.text(strings[index + 1] ?? '');
+  }
+  return builder.done();
+}
+
+/**
+ * Mark a string as trusted SQL. Every call is an audit point: the argument must never be
+ * derived from a request, a row, or an LLM completion.
+ */
+export function raw(trusted: string): SqlFragment {
+  const fragment: Compiled = {
+    [SQL_BRAND]: 'raw',
+    chunks: [trusted],
+    values: [],
+    text: trusted,
+  };
+  return fragment;
+}
+
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * A quoted identifier — the safe answer to the `raw()` temptation. Table and column names
+ * cannot be bound as parameters, so they are validated and double-quoted instead.
+ */
+export function identifier(name: string): SqlFragment {
+  if (SAFE_IDENTIFIER.test(name)) return raw(`"${name}"`);
+  if (name.length === 0 || /[\s"\\]/.test(name)) throw identifierUnsafe(name);
+  return raw(`"${name}"`);
+}
+
+/**
+ * A quoted string literal. Postgres utility statements (`CREATE DATABASE`, `COMMENT ON`) reject
+ * bound parameters, so this is the only place a value may be inlined — and it escapes quotes.
+ * Never reach for it in a query: `sql` binds parameters there.
+ */
+export function literal(value: string): SqlFragment {
+  return raw(`'${value.replaceAll("'", "''")}'`);
+}
+
+/** `a, b, c` — the one blessed way to build an IN list or a column list. */
+export function join(fragments: readonly SqlFragment[], separator = ', '): SqlFragment {
+  const builder = new Builder();
+  fragments.forEach((fragment, index) => {
+    if (!isSqlFragment(fragment)) throw sqlUnsafe(describe(fragment), index + 1);
+    if (index > 0) builder.text(separator);
+    builder.fragment(fragment as Compiled);
+  });
+  return builder.done();
+}

package/src/transaction.ts

@@ -0,0 +1,124 @@
+// Single responsibility: transaction scope. The open `DbTx` rides an AsyncLocalStorage rather
+// than a parameter so `ctx.jobs.enqueue()` can write its outbox row on the caller's connection —
+// the transactional outbox is only atomic because `currentTx()` finds this store. Nesting maps
+// to SAVEPOINTs, so an inner failure never silently aborts the outer unit of work.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { nanoid } from '@ultimat3/core';
+import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
+import { raw, type SqlFragment } from './sql';
+
+export interface DbTx extends DbClient {
+  readonly id: string;
+  /** Fired in reverse registration order when this scope rolls back. Never on commit. */
+  onRollback(undo: () => void): void;
+}
+
+export type IsolationLevel = 'read committed' | 'repeatable read' | 'serializable';
+
+export interface TransactionOptions {
+  readonly isolation?: IsolationLevel | undefined;
+  readonly readOnly?: boolean | undefined;
+  /** Only meaningful with `serializable` + `readOnly`; lets Postgres wait instead of retrying. */
+  readonly deferrable?: boolean | undefined;
+  /** Override the ambient pool — tests and `x db branch` run against a specific client. */
+  readonly client?: DbClient | undefined;
+}
+
+interface TxState {
+  readonly tx: DbTx;
+  readonly connection: DbClient;
+  readonly undos: (() => void)[];
+  /** Shared by reference across nesting levels so savepoint names never collide. */
+  readonly savepoints: { value: number };
+}
+
+const storage = new AsyncLocalStorage<TxState>();
+
+/** The open transaction, or `undefined` outside one. `@ultimat3/jobs` calls this per enqueue. */
+export function currentTx(): DbTx | undefined {
+  return storage.getStore()?.tx;
+}
+
+export function beginStatement(options: TransactionOptions): string {
+  const modes: string[] = [];
+  if (options.isolation !== undefined) {
+    modes.push(`ISOLATION LEVEL ${options.isolation.toUpperCase()}`);
+  }
+  if (options.readOnly === true) modes.push('READ ONLY');
+  if (options.deferrable === true) modes.push('DEFERRABLE');
+  return modes.length === 0 ? 'BEGIN' : `BEGIN ${modes.join(' ')}`;
+}
+
+function makeTx(id: string, connection: DbClient, undos: (() => void)[]): DbTx {
+  return {
+    id,
+    query: <T>(fragment: SqlFragment) => connection.query<T>(fragment),
+    one: <T>(fragment: SqlFragment) => connection.one<T>(fragment),
+    execute: (fragment: SqlFragment) => connection.execute(fragment),
+    onRollback: (undo: () => void) => {
+      undos.push(undo);
+    },
+  };
+}
+
+/** Undo hooks are best-effort: one throwing must not mask the error that caused the rollback. */
+function runUndos(undos: readonly (() => void)[]): void {
+  for (let index = undos.length - 1; index >= 0; index -= 1) {
+    try {
+      undos[index]?.();
+    } catch {
+      // swallowed deliberately — see above
+    }
+  }
+}
+
+async function runNested<T>(outer: TxState, fn: (tx: DbTx) => Promise<T>): Promise<T> {
+  outer.savepoints.value += 1;
+  const name = `x_sp_${outer.savepoints.value}`;
+  const undos: (() => void)[] = [];
+  const tx = makeTx(`${outer.tx.id}/${name}`, outer.connection, undos);
+  await outer.connection.execute(raw(`SAVEPOINT ${name}`));
+  try {
+    const result = await storage.run({ ...outer, tx, undos }, () => fn(tx));
+    await outer.connection.execute(raw(`RELEASE SAVEPOINT ${name}`));
+    // The nested scope committed into an outer one that can still roll back, so its undos
+    // must survive: hand them to the parent rather than dropping them.
+    outer.undos.push(...undos);
+    return result;
+  } catch (error) {
+    await outer.connection.execute(raw(`ROLLBACK TO SAVEPOINT ${name}`));
+    runUndos(undos);
+    throw error;
+  }
+}
+
+export async function withTransaction<T>(
+  fn: (tx: DbTx) => Promise<T>,
+  options: TransactionOptions = {},
+): Promise<T> {
+  const outer = storage.getStore();
+  if (outer !== undefined) return runNested(outer, fn);
+
+  const client = options.client ?? baseClient();
+  const reserved: DbConnection | undefined = isReservable(client)
+    ? await client.reserve()
+    : undefined;
+  const connection: DbClient = reserved ?? client;
+  const undos: (() => void)[] = [];
+  const tx = makeTx(`tx_${nanoid(12)}`, connection, undos);
+
+  await connection.execute(raw(beginStatement(options)));
+  try {
+    const state: TxState = { tx, connection, undos, savepoints: { value: 0 } };
+    const result = await storage.run(state, () => fn(tx));
+    await connection.execute(raw('COMMIT'));
+    return result;
+  } catch (error) {
+    await connection.execute(raw('ROLLBACK')).catch(() => undefined);
+    runUndos(undos);
+    throw error;
+  } finally {
+    reserved?.release();
+  }
+}