pipework 0.252.0 → 0.252.1

package/src/data/db/query-watch.ts

@@ -0,0 +1,116 @@
+import postgres from 'postgres'
+import { getLogger } from '../../core/logging/logger.js'
+import { currentQueryLabel } from './query-label.js'
+import type { StatementWatch } from '../query/postgres-js/session.js'
+
+const LABEL_SQL_CHARS = 120
+const SAMPLE_TIMEOUT_MS = 2_000
+const PG_TRUNCATED_QUERY_LENGTH = 1_000
+
+interface BackendSample {
+  pid: number | null
+  state: string | null
+  waitEventType: string | null
+  waitEvent: string | null
+}
+
+const UNKNOWN_BACKEND: BackendSample = { pid: null, state: null, waitEventType: null, waitEvent: null }
+
+/** What a pool's watch needs: where it logs, how slow is slow, and how to reach the server for a wait-event sample. */
+export interface StatementWatchOptions {
+  readonly database: string
+  readonly url: string
+  readonly slowQueryMs: number
+  /** Undefined: no timer is ever created. */
+  readonly inFlightQueryMs: number | undefined
+}
+
+export interface StatementWatchHandle {
+  readonly watch: StatementWatch
+  close(): Promise<void>
+}
+
+function labelFor(sqlText: string): string {
+  return currentQueryLabel() ?? sqlText.replace(/\s+/g, ' ').trim().slice(0, LABEL_SQL_CHARS)
+}
+
+/**
+ * Wraps each statement of one database's pool: a `query:slow` warning when it settles past
+ * `slowQueryMs`, and, when `inFlightQueryMs` is set, a `query:in-flight` warning at every
+ * multiple of it while the statement is still outstanding. Backend details are read over a
+ * dedicated connection, never the statement's own and never the app pool.
+ */
+export function createStatementWatch(options: StatementWatchOptions): StatementWatchHandle {
+  const { database, url, slowQueryMs, inFlightQueryMs } = options
+  let sampler: postgres.Sql | undefined
+  let sampling = false
+  let closed = false
+
+  function sampleBackend(sqlText: string, startedMs: number): Promise<BackendSample> {
+    if (sampling || closed) return Promise.resolve(UNKNOWN_BACKEND)
+    sampling = true
+    sampler ??= postgres(url, { max: 1, idle_timeout: 3, onnotice: () => {}, connect_timeout: 5 })
+    const client = sampler
+    const run = client.unsafe<Array<{ pid: number; state: string | null; wait_event_type: string | null; wait_event: string | null }>>(
+      `SELECT pid, state, wait_event_type, wait_event FROM pg_stat_activity
+       WHERE datname = current_database() AND pid <> pg_backend_pid() AND state <> 'idle'
+         AND (query = $1 OR (length(query) >= ${String(PG_TRUNCATED_QUERY_LENGTH)} AND left($1, length(query)) = query))
+       ORDER BY abs(extract(epoch FROM query_start) - $2::float8) LIMIT 1`,
+      [sqlText, startedMs / 1000],
+    ).then(rows => {
+      const row = rows[0]
+      return row === undefined
+        ? UNKNOWN_BACKEND
+        : { pid: row.pid, state: row.state, waitEventType: row.wait_event_type, waitEvent: row.wait_event }
+    })
+    void run.then(() => { sampling = false }, () => { sampling = false })
+    let timer: NodeJS.Timeout | undefined
+    const timeout = new Promise<BackendSample>(resolve => {
+      timer = setTimeout(() => { resolve(UNKNOWN_BACKEND) }, SAMPLE_TIMEOUT_MS)
+      timer.unref()
+    })
+    return Promise.race([run, timeout]).catch(() => UNKNOWN_BACKEND).finally(() => { clearTimeout(timer) })
+  }
+
+  const watch: StatementWatch = async <T>(sqlText: string, run: () => Promise<T>): Promise<T> => {
+    const startedMs = Date.now()
+    let interval: NodeJS.Timeout | undefined
+    let settled = false
+    if (inFlightQueryMs !== undefined) {
+      const log = getLogger()
+      const label = labelFor(sqlText)
+      interval = setInterval(() => {
+        const elapsedS = Math.round((Date.now() - startedMs) / 100) / 10
+        void sampleBackend(sqlText, startedMs).then(backend => {
+          if (settled) return
+          log.warn({
+            label, elapsedS, database,
+            pid: backend.pid, state: backend.state,
+            waitEventType: backend.waitEventType, waitEvent: backend.waitEvent,
+          }, 'query:in-flight')
+        })
+      }, inFlightQueryMs)
+      interval.unref()
+    }
+    try {
+      return await run()
+    } finally {
+      settled = true
+      if (interval !== undefined) clearInterval(interval)
+      const durationMs = Date.now() - startedMs
+      if (slowQueryMs > 0 && durationMs > slowQueryMs) {
+        getLogger().warn({ label: labelFor(sqlText), durationMs, database }, 'query:slow')
+      }
+    }
+  }
+
+  return {
+    watch,
+    async close() {
+      closed = true
+      const client = sampler
+      sampler = undefined
+      if (client) await client.end({ timeout: 1 }).catch(() => {})
+    },
+  }
+}

package/src/data/db/raw-client-warning.ts

@@ -0,0 +1,37 @@
+import { getBaseLogger } from '../../core/logging/logger.js'
+
+const warned = new Set<string>()
+
+/**
+ * Announces the one place a statement observer does not carry its
+ * error-sanitization guarantee.
+ *
+ * `ManagedConnection.client` is the sanctioned raw-driver door, and it stays
+ * raw on purpose — queries issued through it bypass the driver error boundary,
+ * so on an observed connection their errors serialize the bind parameters
+ * postgres.js attached. Everything reached through `.drizzle` (which is every
+ * `pipe()` call, every `pipe.*` write, every transaction and savepoint) is
+ * inside the boundary and unaffected.
+ *
+ * Warns once per database name: this is a design fact about the code holding
+ * the connection, not a per-query event, and repeating it would train people to
+ * filter it out.
+ */
+export function warnRawClientIsUnsanitized(database: string): void {
+  if (warned.has(database)) return
+  warned.add(database)
+
+  getBaseLogger().warn(
+    { database },
+    '[pipework] raw .client read on a connection with observability.onStatement configured. ' +
+    'Queries issued through .client bypass pipework\'s driver error boundary, so their errors ' +
+    'serialize bind parameters (postgres.js marks query/parameters/args enumerable whenever its ' +
+    'debug hook is installed). Use connection.drizzle — or pipe() inside a managed context — to ' +
+    'stay inside the boundary. This warning is logged once per database.',
+  )
+}
+
+/** Test seam: forget which databases have already warned. */
+export function _resetRawClientWarnings(): void {
+  warned.clear()
+}

package/src/data/db/readonly.ts

@@ -0,0 +1,23 @@
+import type { Column } from '../query/column.js'
+import type { Placeholder, SQL } from '../query/sql/sql.js'
+
+/**
+ * A value type widened to also accept the readonly form of every tuple, array
+ * and plain object inside it, for parameters that are read and never changed.
+ * Dates, SQL, placeholders, columns, functions, maps, sets, regular expressions,
+ * typed arrays and primitives pass through; unions distribute.
+ *
+ * The result is the original type or its widened form, so anything the plain
+ * type accepted is still accepted (including a value typed by an unresolved
+ * generic such as `T['$inferInsert']`). The widening stops after a fixed number
+ * of levels, so wide nested json columns cannot exhaust instantiation depth.
+ */
+export type AcceptReadonly<V> = V | Widen<V, []>
+
+type Widen<V, D extends unknown[]> =
+  unknown extends V ? V
+  : D['length'] extends 4 ? V
+  : V extends Date | SQL | Placeholder | Column | Map<unknown, unknown> | Set<unknown> | RegExp | ArrayBufferView | ((...args: never[]) => unknown) ? V
+  : V extends readonly unknown[] ? Readonly<{ [I in keyof V]: Widen<V[I], [...D, unknown]> }>
+  : V extends object ? { [K in keyof V]: Widen<V[K], [...D, unknown]> }
+  : V

package/src/data/db/reservation.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from 'node:crypto'
+import postgres from 'postgres'
+import { getBaseLogger } from '../../core/logging/index.js'
+
+/**
+ * What this process has reserved on each Postgres server, published to the
+ * server itself: one presence connection per server whose `application_name`
+ * is `pipework:<id>:<reservation>`, plus pool connections tagged
+ * `pipework:<id>`. The session is the liveness signal: a dead process's
+ * presence row leaves pg_stat_activity with its connection.
+ */
+export interface ReservationPublisher {
+  readonly id: string
+  /** application_name for a publishing pool's connections. */
+  readonly poolTag: string
+  /** Adds `max` to the reservation on the URL's server; the returned function subtracts it (once). */
+  reserve(url: string, max: number): () => void
+  /** Settles when every publication started so far has landed. */
+  settled(): Promise<void>
+  /** Ends every presence connection. */
+  closeAll(): Promise<void>
+}
+
+interface ServerEntry {
+  url: string
+  reservation: number
+  client: postgres.Sql | undefined
+  chain: Promise<void>
+}
+
+export function serverKey(url: string): string {
+  const parsed = new URL(url)
+  return `${parsed.hostname}:${parsed.port === '' ? '5432' : parsed.port}`
+}
+
+export function createReservationPublisher(): ReservationPublisher {
+  const id = randomUUID()
+  const servers = new Map<string, ServerEntry>()
+  const name = (reservation: number): string => `pipework:${id}:${String(reservation)}`
+
+  const publish = (entry: ServerEntry): void => {
+    entry.chain = entry.chain.then(async () => {
+      try {
+        if (entry.reservation <= 0) {
+          const client = entry.client
+          entry.client = undefined
+          if (client) await client.end({ timeout: 5 })
+          return
+        }
+        const value = name(entry.reservation)
+        if (!entry.client) {
+          entry.client = postgres(entry.url, {
+            max: 1,
+            idle_timeout: 0,
+            onnotice: () => {},
+            connection: { application_name: value },
+          })
+        }
+        // A reconnect re-sends the startup packet; keep it current.
+        entry.client.options.connection['application_name'] = value
+        await entry.client.unsafe('SELECT set_config(\'application_name\', $1, false)', [value])
+      } catch (err) {
+        getBaseLogger().warn({ err }, 'Could not publish the connection reservation')
+      }
+    })
+  }
+
+  return {
+    id,
+    poolTag: `pipework:${id}`,
+    reserve(url, max) {
+      const key = serverKey(url)
+      let entry = servers.get(key)
+      if (!entry) {
+        entry = { url, reservation: 0, client: undefined, chain: Promise.resolve() }
+        servers.set(key, entry)
+      }
+      const target = entry
+      target.reservation += max
+      publish(target)
+      let released = false
+      return () => {
+        if (released) return
+        released = true
+        target.reservation -= max
+        publish(target)
+      }
+    },
+    async settled() {
+      await Promise.all([...servers.values()].map(e => e.chain))
+    },
+    async closeAll() {
+      for (const entry of servers.values()) {
+        entry.reservation = 0
+        publish(entry)
+      }
+      await this.settled()
+    },
+  }
+}
+
+export interface ConnectionBudget {
+  /** The server's `max_connections`. */
+  readonly maxConnections: number
+  /** `superuser_reserved_connections` plus `reserved_connections` (PG16+; 0 before). */
+  readonly reserved: number
+  /** Client backends open now, across the whole server, plus other roles' background workers that the reading role cannot tell apart. */
+  readonly held: number
+  /** For every other live publishing pipework process on this server: its reservation minus the connections it holds (never below 0), summed. */
+  readonly othersUnopened: number
+  /** `maxConnections - reserved - held - othersUnopened`. */
+  readonly free: number
+}
+
+const PRESENCE = /^pipework:([0-9a-f-]{36}):(\d+)$/
+const POOL_TAG = /^pipework:([0-9a-f-]{36})$/
+
+export const BUDGET_QUERY = `
+SELECT current_setting('max_connections')::int AS max_connections,
+  current_setting('superuser_reserved_connections')::int + coalesce(current_setting('reserved_connections', true)::int, 0) AS reserved,
+  (SELECT count(*)::int FROM pg_stat_activity WHERE datid IS NOT NULL AND (backend_type = 'client backend' OR backend_type IS NULL)) AS held,
+  coalesce((SELECT array_agg(application_name::text) FROM pg_stat_activity WHERE application_name LIKE 'pipework:%'), '{}') AS names`
+
+export function computeBudget(
+  row: { max_connections: number; reserved: number; held: number; names: readonly string[] },
+  ownId: string,
+): ConnectionBudget {
+  const reservation = new Map<string, number>()
+  const holding = new Map<string, number>()
+  for (const n of row.names) {
+    const presence = PRESENCE.exec(n)
+    if (presence) {
+      reservation.set(presence[1]!, Number(presence[2]))
+      continue
+    }
+    const pool = POOL_TAG.exec(n)
+    if (pool) holding.set(pool[1]!, (holding.get(pool[1]!) ?? 0) + 1)
+  }
+  let othersUnopened = 0
+  for (const [pid, reserved] of reservation) {
+    if (pid === ownId) continue
+    othersUnopened += Math.max(0, reserved - (holding.get(pid) ?? 0))
+  }
+  return {
+    maxConnections: row.max_connections,
+    reserved: row.reserved,
+    held: row.held,
+    othersUnopened,
+    free: row.max_connections - row.reserved - row.held - othersUnopened,
+  }
+}

package/src/data/db/schema-features.ts

@@ -0,0 +1,14 @@
+// Schema-level features — manual layer (wrappable)
+// e.g., `table` could auto-inject tenant_id columns for tenant-scoped tables.
+
+export {
+  pgTable as table,
+  pgView as view,
+  pgMaterializedView as materializedView,
+  pgSchema,
+  pgSequence as sequence,
+  pgPolicy as policy,
+  pgRole as role,
+  pgTableCreator as tableCreator,
+  withReplicas,
+} from '../query/pg-core/index.js'

package/src/data/db/serializable.ts

@@ -0,0 +1,83 @@
+import type { DB } from './types.js'
+
+/** Retry policy for {@link serializable}: how many attempts on a serialization failure / deadlock, and the base backoff between them. */
+export interface SerializableOptions {
+  readonly maxAttempts?: number
+  readonly backoffMs?: number
+}
+
+const PG_SERIALIZATION_FAILURE = '40001'
+const PG_DEADLOCK_DETECTED = '40P01'
+const PG_SET_TRANSACTION_AFTER_QUERY = '25001'
+
+/** The Postgres SQLSTATE carried by an error (or by its cause), or undefined for a non-Postgres error. */
+export function pgErrorCode(err: unknown): unknown {
+  if (typeof err !== 'object' || err === null) return undefined
+  if ('code' in err) return (err as { code: unknown }).code
+  if ('cause' in err) return pgErrorCode((err as { cause: unknown }).cause)
+  return undefined
+}
+
+/** True for Postgres serialization failures (40001) and deadlocks (40P01) — errors a retry can resolve. */
+export function isTransientConcurrencyError(err: unknown): boolean {
+  const code = pgErrorCode(err)
+  return code === PG_SERIALIZATION_FAILURE || code === PG_DEADLOCK_DETECTED
+}
+
+// Only a postgres.js transaction client exposes savepoint(), so its presence
+// on the session's client means this db already sits inside an open
+// transaction — a drizzle transaction object included.
+function insideTransaction(db: unknown): boolean {
+  const session = (db as { session?: { client?: { savepoint?: unknown } } }).session
+  return typeof session?.client?.savepoint === 'function'
+}
+
+function nestedSerializableError(cause?: unknown): Error {
+  return new Error(
+    '[pipework] serializable() cannot run inside an open transaction.\n\n' +
+    '  Postgres refuses to raise the isolation level of a transaction that has\n' +
+    '  already run a query (25001), and a nested transaction is a savepoint that\n' +
+    '  inherits the outer, weaker level. Open the SERIALIZABLE transaction at the\n' +
+    '  outermost level instead of inside another one.\n',
+    cause !== undefined ? { cause } : undefined,
+  )
+}
+
+/** Runs `fn` in a SERIALIZABLE transaction, retrying on serialization failures (40001) and deadlocks (40P01) with exponential backoff. */
+export async function serializable<T>(
+  db: DB,
+  fn: (tx: DB) => Promise<T>,
+  options?: SerializableOptions,
+): Promise<T> {
+  const maxAttempts = options?.maxAttempts ?? 3
+  const backoffMs = options?.backoffMs ?? 50
+
+  if (maxAttempts < 1) {
+    throw new Error(
+      '[pipework] serializable() requires maxAttempts >= 1.\n\n' +
+      '  pipe.serializable(db, fn)                     — default 3 attempts\n' +
+      '  pipe.serializable(db, fn, { maxAttempts: 5 }) — custom attempts\n',
+    )
+  }
+
+  if (insideTransaction(db)) throw nestedSerializableError()
+
+  let lastError: unknown
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (attempt > 0) {
+      await new Promise<void>(resolve => setTimeout(resolve, backoffMs * 2 ** (attempt - 1)))
+    }
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's transaction generic requires concrete schema types; the DB alias erases them
+      return await (db as any).transaction(fn, { isolationLevel: 'serializable' })
+    } catch (err) {
+      if (pgErrorCode(err) === PG_SET_TRANSACTION_AFTER_QUERY) throw nestedSerializableError(err)
+      if (isTransientConcurrencyError(err) && attempt < maxAttempts - 1) {
+        lastError = err
+        continue
+      }
+      throw err
+    }
+  }
+  throw lastError
+}

package/src/data/db/sql.ts

@@ -0,0 +1 @@
+export { sql } from '../query/index.js'

package/src/data/db/timeouts.ts

@@ -0,0 +1,76 @@
+import { sql } from './sql.js'
+import { pgErrorCode } from './serializable.js'
+import type { DB } from './types.js'
+import { unscopedExecutor } from '../../auth/tenant/scoped-db.js'
+
+const PG_QUERY_CANCELED = '57014'
+const PG_LOCK_NOT_AVAILABLE = '55P03'
+
+/** Which timeouts {@link withTimeouts} sets; each a positive integer number of milliseconds. */
+export interface TimeoutOptions {
+  readonly statementTimeoutMs?: number
+  readonly lockTimeoutMs?: number
+}
+
+/** A statement was cancelled by Postgres for running past the statement timeout a {@link withTimeouts} call set. `cause` is the driver error. */
+export class StatementTimeoutError extends Error {
+  constructor(readonly statementTimeoutMs: number, cause: unknown) {
+    super(`[pipework] a statement ran past the ${statementTimeoutMs} ms statement timeout set by withTimeouts`, { cause })
+    this.name = 'StatementTimeoutError'
+  }
+}
+
+/** A statement gave up waiting for a lock past the lock timeout a {@link withTimeouts} call set. `cause` is the driver error. */
+export class LockTimeoutError extends Error {
+  constructor(readonly lockTimeoutMs: number, cause: unknown) {
+    super(`[pipework] a statement waited past the ${lockTimeoutMs} ms lock timeout set by withTimeouts`, { cause })
+    this.name = 'LockTimeoutError'
+  }
+}
+
+function positiveInteger(name: string, value: number | undefined): void {
+  if (value === undefined) return
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(
+      `[pipework] withTimeouts: ${name} must be a positive integer number of milliseconds, got ${String(value)}.\n\n` +
+      '  Fix: pipe.withTimeouts(db, { statementTimeoutMs: 5000, lockTimeoutMs: 1000 }, fn)\n',
+    )
+  }
+}
+
+/**
+ * Sets `statement_timeout` and/or `lock_timeout` for the current transaction in one statement, then runs `fn`.
+ * `db` is the transaction-bound DB the caller already has (`pipe(name)` inside a flow, or a `tx`).
+ *
+ * The settings hold until the transaction ends, as `SET LOCAL` does; nothing is restored after `fn`, so statements
+ * after it in the same transaction keep the timeouts. Outside a transaction `set_config(..., true)` has no
+ * effect, so call this only inside one.
+ *
+ * A statement Postgres cancels for a timeout this call set rejects with {@link StatementTimeoutError} (SQLSTATE 57014)
+ * or {@link LockTimeoutError} (55P03), the driver error as `cause`. Any other error passes through unchanged.
+ */
+export async function withTimeouts<T>(db: DB, options: TimeoutOptions, fn: () => Promise<T>): Promise<T> {
+  const { statementTimeoutMs, lockTimeoutMs } = options
+  if (statementTimeoutMs === undefined && lockTimeoutMs === undefined) {
+    throw new Error(
+      '[pipework] withTimeouts: give statementTimeoutMs, lockTimeoutMs, or both.\n\n' +
+      '  Fix: pipe.withTimeouts(db, { statementTimeoutMs: 5000 }, fn)\n',
+    )
+  }
+  positiveInteger('statementTimeoutMs', statementTimeoutMs)
+  positiveInteger('lockTimeoutMs', lockTimeoutMs)
+
+  const settings = []
+  if (statementTimeoutMs !== undefined) settings.push(sql`set_config('statement_timeout', ${`${statementTimeoutMs}ms`}, true)`)
+  if (lockTimeoutMs !== undefined) settings.push(sql`set_config('lock_timeout', ${`${lockTimeoutMs}ms`}, true)`)
+  await unscopedExecutor(db).db.execute(sql`SELECT ${sql.join(settings, sql`, `)}`)
+
+  try {
+    return await fn()
+  } catch (err) {
+    const code = pgErrorCode(err)
+    if (code === PG_QUERY_CANCELED && statementTimeoutMs !== undefined) throw new StatementTimeoutError(statementTimeoutMs, err)
+    if (code === PG_LOCK_NOT_AVAILABLE && lockTimeoutMs !== undefined) throw new LockTimeoutError(lockTimeoutMs, err)
+    throw err
+  }
+}

package/src/data/db/types.ts

@@ -0,0 +1,18 @@
+import type { SQL as _SQL } from '../query/index.js'
+import type { PgTable, PgColumn } from '../query/pg-core/index.js'
+
+/** Drizzle database instance — use pipe() to get one inside a managed context. */
+export type { PostgresJsDatabase as DB } from '../query/postgres-js/index.js'
+/** SQL expression type — created by pipe.sql template tag or query operators. */
+export type SQL<T = unknown> = _SQL<T>
+/** Drizzle table definition type — created by schema.table(). */
+export type Table = PgTable
+/** Drizzle column type — created by schema.col.* builders. */
+export type Column = PgColumn
+
+/** Options for pipe.transaction(). Nested transactions (savepoints) inherit the outer transaction's isolation level — isolationLevel is silently dropped when nested. */
+export interface TransactionConfig {
+  isolationLevel?: 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable'
+  accessMode?: 'read only' | 'read write'
+  deferrable?: boolean
+}

package/src/data/db/unbound.ts

@@ -0,0 +1,33 @@
+import type { DB } from './index.js'
+import type { Flow } from '../../request/context/types.js'
+import type { ResolvedDatabase } from '../../core/config/load.js'
+
+/**
+ * The database handle for a Flow with no bound transaction on `dbName`: the
+ * pooled connection.
+ *
+ * On a platform-mode database that connection is the platform role, which sees
+ * no tenant row until the tenant setting is set, and the setting can only be
+ * set for a transaction. A builder from `pipe()` runs lazily on the handle it
+ * was built from, with nothing wrapping the statement, so there is no per-statement
+ * place to set it (src/data/query/postgres-js/session.ts sends each statement on
+ * the pool client). A Flow with a tenant is therefore refused here, naming the fix;
+ * a Flow with no tenant gets the connection as is and tenant tables return nothing.
+ * Under a test connection override the test's own connection is used.
+ */
+export function unboundDb(ctx: Flow, dbName: string, dbConfig: ResolvedDatabase, caller: string): DB {
+  if (
+    dbConfig.rls?.platformRole !== undefined
+    && ctx.tenant !== null
+    && !ctx.instance.pool.isOverridden(dbName)
+  ) {
+    throw new Error(
+      `[pipework] ${caller} has no transaction bound for database "${dbName}", and this Flow has a tenant.\n\n` +
+      `  "${dbName}" is in platform mode (rls.platformRole): its pooled connection is the platform role, which\n` +
+      '  sees no tenant row, and the tenant setting can only be set per transaction.\n' +
+      '  Fix: run the code in a request or job (each binds a tenant-scoped transaction), or wrap it in\n' +
+      '  pipe.transaction(async (tx) => { ... }).\n',
+    )
+  }
+  return ctx.instance.pool.getOrCreate(dbConfig).drizzle
+}

package/src/data/db/values.ts

@@ -0,0 +1,29 @@
+import { sql } from './sql.js'
+import type { SQL } from './types.js'
+
+type PgCastType = 'uuid' | 'text' | 'integer' | 'bigint' | 'boolean' | 'jsonb' | 'timestamptz' | 'timestamp' | 'date' | 'numeric' | 'real' | 'double precision' | 'smallint' | 'interval'
+
+/** One column of a typed `VALUES` clause: its name and the PostgreSQL type each value in that column is cast to. See {@link values}. */
+export interface ValueColumnDef {
+  readonly name: string
+  readonly type: PgCastType
+}
+
+/** Produces a typed VALUES clause: `(VALUES ($1::uuid, $2::text), ($3::uuid, $4::text))`. Each value is cast to its declared type. JSONB values are JSON-stringified and Dates sent as ISO text, as a column does on insert; null is SQL NULL. */
+export function values(rows: ReadonlyArray<readonly unknown[]>, columns: readonly ValueColumnDef[]): SQL {
+  if (rows.length === 0) throw new Error('[pipework] values() requires at least one row')
+  if (columns.length === 0) throw new Error('[pipework] values() requires at least one column definition')
+
+  const valueRows: SQL[] = rows.map(row => {
+    const cells = columns.map((col, i) => {
+      const val = row[i]
+      if (val === null || val === undefined) return sql`${null}::${sql.raw(col.type)}`
+      if (col.type === 'jsonb') return sql`${JSON.stringify(val)}::jsonb`
+      const bound = val instanceof Date ? val.toISOString() : val
+      return sql`${bound as string | number | boolean | bigint}::${sql.raw(col.type)}`
+    })
+    return sql`(${sql.join(cells, sql`, `)})`
+  })
+
+  return sql`(VALUES ${sql.join(valueRows, sql`, `)})`
+}

package/src/data/domain/brand.ts

@@ -0,0 +1,15 @@
+declare const __brand: unique symbol
+
+/** Phantom brand marker — attaches a nominal tag to a base type. */
+export type Brand<B extends string> = { readonly [__brand]: B }
+
+/** Nominal type — `Branded<string, 'UserId'>` is not assignable to `Branded<string, 'PostId'>`. */
+export type Branded<T, B extends string> = T & Brand<B>
+
+/** Extracts the phantom output type from a FieldDescriptor. */
+export type InferFieldOutput<F> = F extends { readonly _output?: infer O } ? O : unknown
+
+/** Projects field output types into a readonly record — used for DomainDefinition.Select. */
+export type InferSelect<T extends Record<string, { readonly _output?: unknown }>> = {
+  readonly [K in keyof T]: InferFieldOutput<T[K]>
+}