pipework 0.251.0 → 0.252.1

package/src/data/db/expressions.ts

@@ -0,0 +1,473 @@
+import { sql } from './sql.js'
+import type { SQL, Column } from './types.js'
+import type { SQLWrapper } from '../query/sql/sql.js'
+import { bindIfParam } from '../query/index.js'
+import { PgArray } from '../query/pg-core/index.js'
+import { quoteCollation, type CollationName } from '../query/collation.js'
+import { is } from '../query/entity.js'
+import { Column as DrizzleColumn } from '../query/column.js'
+import { noopDecoder, SQL as DrizzleSQL } from '../query/sql/sql.js'
+
+/** Returns `column + amount`. Use negative amounts for subtraction. */
+export function increment(column: Column | SQL, amount: number): SQL<number> {
+  return sql<number>`${column} + ${amount}`
+}
+
+/** Returns `column - amount`. Convenience wrapper — equivalent to `increment(column, -amount)`. */
+export function decrement(column: Column | SQL, amount: number): SQL<number> {
+  return sql<number>`${column} - ${amount}`
+}
+
+/** Returns `left + right` for two SQL expressions. For column + literal number, use `increment`. */
+export function add<T = unknown>(left: Column | SQL, right: Column | SQL): SQL<T> {
+  return sql<T>`${left} + ${right}`
+}
+
+/** Returns `left - right` for two SQL expressions. For column - literal number, use `decrement`. */
+export function subtract<T = unknown>(left: Column | SQL, right: Column | SQL): SQL<T> {
+  return sql<T>`${left} - ${right}`
+}
+
+/** Wraps an expression with COALESCE — returns `defaultValue` when the expression is NULL. Given a column, the default is bound the way that column's values are on insert (jsonb as JSON, dates, arrays). */
+export function coalesce<T>(expression: SQL | Column, defaultValue: T): SQL<T> {
+  return sql<T>`coalesce(${expression}, ${bindIfParam(defaultValue, expression)})`
+}
+
+/** Returns a SQL expression for PostgreSQL `now()` — the current transaction timestamp. */
+export function now(): SQL<Date> {
+  return sql<Date>`now()`
+}
+
+/** Wraps a select query as a scalar subquery expression, usable in `.values()` and `.set()`. */
+export function scalar<T>(subquery: SQLWrapper): SQL<T> {
+  return sql<T>`(${subquery})`
+}
+
+/** A PostgreSQL interval/`date_trunc` field unit (`'days'`, `'months'`, …). */
+export type IntervalUnit = 'microseconds' | 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years'
+
+/** PostgreSQL type cast: `expression::pgType`. */
+export function cast<T = unknown>(expression: SQL | Column | SQLWrapper, pgType: string): SQL<T> {
+  return sql<T>`(${expression})::${sql.raw(pgType)}`
+}
+
+/** What `collate` accepts: a text column or an SQL expression typed `string` or `string | null`. */
+export type CollatableOperand = (Column & { _: { data: string } }) | SQL<string> | SQL<string | null>
+
+/**
+ * `(expr) collate "name"` — sorts, groups and compares the expression under that collation.
+ * A string is one quoted identifier, dots included (`'en_US.utf8'` -> `"en_US.utf8"`); a tuple is
+ * schema-qualified (`['pg_catalog', 'C']` -> `"pg_catalog"."C"`). A column keeps its decoder, so the selected value decodes as the column does.
+ */
+export function collate<E extends CollatableOperand>(
+  expr: E,
+  collation: CollationName,
+): SQL<E extends Column ? (E['_']['notNull'] extends true ? E['_']['data'] : E['_']['data'] | null) : E extends SQL<infer T> ? T : unknown> {
+  const name = sql.raw(quoteCollation(collation))
+  const out = sql`(${expr}) collate ${name}`
+  if (is(expr, DrizzleColumn)) out.mapWith(expr as Column)
+  else if ((expr as SQL).decoder !== noopDecoder) out.mapWith((expr as SQL).decoder)
+  return out as never
+}
+
+const INTERVAL_UNIT_SINGULAR: Readonly<Record<IntervalUnit, string>> = {
+  microseconds: 'microsecond',
+  milliseconds: 'millisecond',
+  seconds: 'second',
+  minutes: 'minute',
+  hours: 'hour',
+  days: 'day',
+  weeks: 'week',
+  months: 'month',
+  years: 'year',
+}
+
+/** PostgreSQL interval of `amount` units, `amount` bound as a parameter: `($1::double precision * interval '1 minute')`. Throws for a non-finite amount. */
+export function interval(amount: number, unit: IntervalUnit): SQL {
+  if (!Number.isFinite(amount)) {
+    throw new Error(
+      `[pipework] interval() needs a finite amount, got ${String(amount)}.\n\n` +
+      '  NaN and Infinity are not valid interval amounts.\n' +
+      "  Fix: pass a finite number: interval(5, 'minutes').\n",
+    )
+  }
+  return sql`(${amount}::double precision * interval '1 ${sql.raw(INTERVAL_UNIT_SINGULAR[unit])}')`
+}
+
+/** PostgreSQL `clock_timestamp()` — the actual wall-clock time, which advances within a transaction (unlike `now()`). */
+export function clockTimestamp(): SQL<Date> {
+  return sql<Date>`clock_timestamp()`
+}
+
+/** A text operand: a column, an expression, or a string (bound as `$n::text`). */
+export type TextArg = Column | SQL | string
+
+function textArg(value: TextArg): SQL {
+  return typeof value === 'string' ? sql`${value}::text` : sql`${value}`
+}
+
+function intArg(value: number | Column | SQL): SQL {
+  return typeof value === 'number' ? sql`${value}::int` : sql`${value}`
+}
+
+/** PostgreSQL `strpos(a, b)` — 1-based position of `b` in `a`, 0 when absent. Strings are bound as text, so `%`, `_` and `\` are plain characters. */
+export function strpos(a: TextArg, b: TextArg): SQL<number> {
+  return sql<number>`strpos(${textArg(a)}, ${textArg(b)})`
+}
+
+/** True when `a` contains the exact text `b`: `strpos(a, b) > 0`. Unlike `like`, no character in `b` is a wildcard. */
+export function textContains(a: TextArg, b: TextArg): SQL<boolean> {
+  return sql<boolean>`${strpos(a, b)} > 0`
+}
+
+/** PostgreSQL `starts_with(a, prefix)` — true when `a` begins with the exact text `prefix`; no wildcards. */
+export function startsWith(a: TextArg, prefix: TextArg): SQL<boolean> {
+  return sql<boolean>`starts_with(${textArg(a)}, ${textArg(prefix)})`
+}
+
+/** PostgreSQL `left(a, n)` — the first `n` characters of `a`. */
+export function left(a: TextArg, n: number | Column | SQL): SQL<string> {
+  return sql<string>`left(${textArg(a)}, ${intArg(n)})`
+}
+
+/** PostgreSQL `right(a, n)` — the last `n` characters of `a`. */
+export function right(a: TextArg, n: number | Column | SQL): SQL<string> {
+  return sql<string>`right(${textArg(a)}, ${intArg(n)})`
+}
+
+/** PostgreSQL `length(a)` — the number of characters in `a`. */
+export function length(a: TextArg): SQL<number> {
+  return sql<number>`length(${textArg(a)})`
+}
+
+function wholeNumber(value: number, helper: string, what: string): number {
+  if (!Number.isInteger(value)) {
+    throw new Error(
+      `[pipework] ${helper}() needs a finite integer ${what}, got ${String(value)}.\n\n` +
+      '  NaN, Infinity and fractions are not valid positions or counts.\n' +
+      `  Fix: pass an integer: ${helper}(..., 1).\n`,
+    )
+  }
+  return value
+}
+
+function checkedIntArg(value: number | Column | SQL, helper: string, what: string): SQL {
+  return typeof value === 'number' ? sql`${wholeNumber(value, helper, what)}::int` : sql`${value}`
+}
+
+/** PostgreSQL `split_part(a, delimiter, n)` — the `n`th (1-based) field of `a`; negative `n` counts from the end (PostgreSQL 14+). `delimiter` is bound. */
+export function splitPart(a: TextArg, delimiter: string, n: number | Column | SQL): SQL<string> {
+  return sql<string>`split_part(${textArg(a)}, ${delimiter}::text, ${checkedIntArg(n, 'splitPart', 'field number')})`
+}
+
+/** PostgreSQL `lower(a)`. */
+export function lower(a: TextArg): SQL<string> {
+  return sql<string>`lower(${textArg(a)})`
+}
+
+/** PostgreSQL `upper(a)`. */
+export function upper(a: TextArg): SQL<string> {
+  return sql<string>`upper(${textArg(a)})`
+}
+
+const TRIM_SIDES: ReadonlySet<string> = new Set(['both', 'leading', 'trailing'])
+
+/** Which end of the text `trim` strips. */
+export type TrimSide = 'both' | 'leading' | 'trailing'
+
+/** PostgreSQL `trim(<side> [characters] from a)` — strips spaces, or any of `characters` (bound), from the chosen end; `side` defaults to `'both'`. */
+export function trim(a: TextArg, options: { readonly side?: TrimSide; readonly characters?: string } = {}): SQL<string> {
+  const side = options.side ?? 'both'
+  if (!TRIM_SIDES.has(side)) {
+    throw new Error(
+      `[pipework] trim() side must be 'both', 'leading' or 'trailing', got ${String(side)}.\n\n` +
+      "  Fix: trim(column, { side: 'leading' }).\n",
+    )
+  }
+  const kw = sql.raw(side)
+  if (options.characters === undefined) return sql<string>`trim(${kw} from ${textArg(a)})`
+  return sql<string>`trim(${kw} ${options.characters}::text from ${textArg(a)})`
+}
+
+/** PostgreSQL `replace(a, from, to)` — every occurrence of the exact text `from` becomes `to`. */
+export function replace(a: TextArg, from: TextArg, to: TextArg): SQL<string> {
+  return sql<string>`replace(${textArg(a)}, ${textArg(from)}, ${textArg(to)})`
+}
+
+/** PostgreSQL `substring(a, from[, count])` — 1-based start, optional length. */
+export function substring(a: TextArg, from: number | Column | SQL, count?: number | Column | SQL): SQL<string> {
+  const start = checkedIntArg(from, 'substring', 'start')
+  if (count === undefined) return sql<string>`substring(${textArg(a)}, ${start})`
+  return sql<string>`substring(${textArg(a)}, ${start}, ${checkedIntArg(count, 'substring', 'count')})`
+}
+
+/** PostgreSQL `reverse(a)`. */
+export function reverse(a: TextArg): SQL<string> {
+  return sql<string>`reverse(${textArg(a)})`
+}
+
+/** PostgreSQL `lpad(a, length[, fill])` — pads on the left (or truncates) to `length` characters; `fill` defaults to a space. */
+export function lpad(a: TextArg, length: number | Column | SQL, fill?: string): SQL<string> {
+  const len = checkedIntArg(length, 'lpad', 'length')
+  if (fill === undefined) return sql<string>`lpad(${textArg(a)}, ${len})`
+  return sql<string>`lpad(${textArg(a)}, ${len}, ${fill}::text)`
+}
+
+/** PostgreSQL `rpad(a, length[, fill])` — pads on the right (or truncates) to `length` characters; `fill` defaults to a space. */
+export function rpad(a: TextArg, length: number | Column | SQL, fill?: string): SQL<string> {
+  const len = checkedIntArg(length, 'rpad', 'length')
+  if (fill === undefined) return sql<string>`rpad(${textArg(a)}, ${len})`
+  return sql<string>`rpad(${textArg(a)}, ${len}, ${fill}::text)`
+}
+
+/** PostgreSQL `regexp_replace(a, pattern, replacement[, flags])` — POSIX regex; `flags` such as `'g'` or `'i'`. Pattern, replacement and flags are bound. */
+export function regexpReplace(a: TextArg, pattern: string, replacement: string, flags?: string): SQL<string> {
+  if (flags === undefined) return sql<string>`regexp_replace(${textArg(a)}, ${pattern}::text, ${replacement}::text)`
+  return sql<string>`regexp_replace(${textArg(a)}, ${pattern}::text, ${replacement}::text, ${flags}::text)`
+}
+
+/** True when `a` matches the POSIX regex `pattern` (bound): `a ~ pattern`, or `a ~* pattern` with `caseInsensitive`. */
+export function regexpMatch(a: TextArg, pattern: string, options: { readonly caseInsensitive?: boolean } = {}): SQL<boolean> {
+  const op = options.caseInsensitive === true ? sql.raw('~*') : sql.raw('~')
+  return sql<boolean>`${textArg(a)} ${op} ${pattern}::text`
+}
+
+/** PostgreSQL `string_to_array(a, delimiter)` — splits `a` into a text array; `delimiter` is bound. An empty `a` gives `{}`. */
+export function stringToArray(a: TextArg, delimiter: string): SQL<string[]> {
+  return sql<string[]>`string_to_array(${textArg(a)}, ${delimiter}::text)`
+}
+
+/**
+ * Text concatenation: `(p1 || p2 || ...)`. Strings are bound as text. A null part makes
+ * the whole result null (SQL `||`); wrap such a part in `coalesce` if that is not wanted.
+ * Wrap a subquery with `scalar(...)`.
+ */
+export function concat(...parts: Array<string | Column | SQL>): SQL<string> {
+  if (parts.length < 2) {
+    throw new Error(
+      `[pipework] concat() needs at least two parts, got ${parts.length}.\n\n` +
+      '  A concatenation of fewer than two parts is not a concatenation.\n' +
+      "  Fix: pass two or more parts: concat('prefix: ', column).\n",
+    )
+  }
+  return sql<string>`(${sql.join(parts.map(textArg), sql` || `)})`
+}
+
+function elementType(column: Column, helper: string): string {
+  const type = column.getSQLType()
+  if (!type.endsWith('[]')) {
+    throw new Error(
+      `[pipework] ${helper}() needs an array column, got "${column.name}" of type ${type}.\n\n` +
+      '  The element type is read from the column, so it must be an array column.\n' +
+      `  Fix: pass an array column (for example uuid('ids').array()) to ${helper}().\n`,
+    )
+  }
+  return type.slice(0, -2)
+}
+
+/** Binds `value` as one element of an array column, converted by the element column's driver mapping. */
+function element(col: Column, value: unknown): unknown {
+  if (value === null || !is(col, PgArray)) return value
+  const base = (col as unknown as { baseColumn: { mapToDriverValue(v: unknown): unknown } }).baseColumn
+  return sql.param(value, { mapToDriverValue: v => base.mapToDriverValue(v) })
+}
+
+type ElementOf<C extends Column> = C['_']['data'] extends ReadonlyArray<infer E> ? E : never
+
+/** PostgreSQL `array_replace(col, from, to)` — every element equal to `from` becomes `to`. `from`/`to` are bound and cast to the column's element type. */
+export function arrayReplace<C extends Column>(col: C, from: ElementOf<C>, to: ElementOf<C>): SQL<C['_']['data']> {
+  const el = sql.raw(elementType(col, 'arrayReplace'))
+  return sql<C['_']['data']>`array_replace(${col}, ${element(col, from)}::${el}, ${element(col, to)}::${el})`
+}
+
+/** A column or expression whose value is one element of `C`'s array. */
+type ElementValue<C extends Column> =
+  | (Column & { _: { data: ElementOf<C> | null } })
+  | SQL<ElementOf<C>>
+  | SQL<ElementOf<C> | null>
+
+/**
+ * True when the array column holds `value`.
+ * A JS value is bound and cast to the element type: `$value::<element> = ANY(col)`.
+ * A column or SQL expression is used as is, with no bind and no cast: `<value> = ANY(col)`,
+ * so the index on `value` can serve a join against the array.
+ */
+export function arrayHas<C extends Column>(col: C, value: ElementOf<C>): SQL<boolean>
+export function arrayHas<C extends Column>(col: C, value: ElementValue<C>): SQL<boolean>
+export function arrayHas(col: Column, value: unknown): SQL<boolean> {
+  const el = sql.raw(elementType(col, 'arrayHas'))
+  if (is(value, DrizzleColumn) || is(value, DrizzleSQL)) return sql<boolean>`${value} = ANY(${col})`
+  return sql<boolean>`${element(col, value)}::${el} = ANY(${col})`
+}
+
+/** PostgreSQL `cardinality(arr)` — the number of elements; 0 for `'{}'`, NULL for a NULL array. */
+export function cardinality(arr: Column | SQL): SQL<number | null> {
+  return sql<number | null>`cardinality(${arr})`
+}
+
+/**
+ * One element by 1-based index: `(arr)[n]`; a negative `n` counts from the end,
+ * `(arr)[cardinality(arr) + n + 1]`. NULL for 0, out of range, or an empty array. `n` is bound.
+ */
+export function arrayAt<C extends Column>(arr: C, n: number): SQL<ElementOf<C> | null>
+export function arrayAt<T>(arr: SQL<readonly T[]>, n: number): SQL<T | null>
+export function arrayAt(arr: Column | SQL, n: number): SQL {
+  wholeNumber(n, 'arrayAt', 'index')
+  if (n < 0) return sql`(${arr})[cardinality(${arr}) + ${n + 1}::int]`
+  return sql`(${arr})[${n}::int]`
+}
+
+/** PostgreSQL `array_position(col, value)` — 1-based index of the first `value`, NULL when absent. `value` is bound and cast to the element type. */
+export function arrayPosition<C extends Column>(col: C, value: ElementOf<C>): SQL<number | null> {
+  const el = sql.raw(elementType(col, 'arrayPosition'))
+  return sql<number | null>`array_position(${col}, ${element(col, value)}::${el})`
+}
+
+/** Array slice `(col)[from:to]`, 1-based and inclusive; out-of-range bounds are clipped. `from`/`to` are bound. */
+export function arraySlice<C extends Column>(col: C, from: number, to: number): SQL<C['_']['data']> {
+  wholeNumber(from, 'arraySlice', 'start')
+  wholeNumber(to, 'arraySlice', 'end')
+  return sql<C['_']['data']>`(${col})[(${from}::int):(${to}::int)]`
+}
+
+/** PostgreSQL `array_to_string(arr, delimiter)` — joins the elements (NULL elements skipped); `delimiter` is bound. */
+export function arrayToString(arr: Column | SQL, delimiter: string): SQL<string> {
+  return sql<string>`array_to_string(${arr}, ${delimiter}::text)`
+}
+
+/** PostgreSQL `array_append(col, value)` — `value` goes last. `value` is bound and cast to the element type. */
+export function arrayAppend<C extends Column>(col: C, value: ElementOf<C>): SQL<C['_']['data']> {
+  const el = sql.raw(elementType(col, 'arrayAppend'))
+  return sql<C['_']['data']>`array_append(${col}, ${element(col, value)}::${el})`
+}
+
+/** PostgreSQL `array_remove(col, value)` — drops every element equal to `value`. `value` is bound and cast to the element type. */
+export function arrayRemove<C extends Column>(col: C, value: ElementOf<C>): SQL<C['_']['data']> {
+  const el = sql.raw(elementType(col, 'arrayRemove'))
+  return sql<C['_']['data']>`array_remove(${col}, ${element(col, value)}::${el})`
+}
+
+/** PostgreSQL `date_trunc('unit', column)` — truncates a timestamp to the given precision. */
+export function dateTrunc(unit: 'microseconds' | 'milliseconds' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'decade' | 'century' | 'millennium', column: Column | SQL): SQL<Date> {
+  return sql<Date>`date_trunc('${sql.raw(unit)}', ${column})`
+}
+
+/** PostgreSQL `ROW_NUMBER()` window function. Use with `over()` to apply a window specification. */
+export function rowNumber(): SQL<number> {
+  return sql<number>`row_number()`
+}
+
+/** PostgreSQL `RANK()` window function. Use with `over()` to apply a window specification. */
+export function rank(): SQL<number> {
+  return sql<number>`rank()`
+}
+
+/** PostgreSQL `DENSE_RANK()` window function. Use with `over()` to apply a window specification. */
+export function denseRank(): SQL<number> {
+  return sql<number>`dense_rank()`
+}
+
+/** A window-frame specification — the `PARTITION BY` / `ORDER BY` clauses applied by {@link over}. */
+export interface WindowSpec {
+  readonly partitionBy?: Column | SQL | ReadonlyArray<Column | SQL>
+  readonly orderBy?: SQL | ReadonlyArray<SQL>
+  readonly frame?: WindowFrame
+}
+
+/** One end of a window frame. `{ preceding: n }` / `{ following: n }` take a non-negative integer. */
+export type FrameBound = 'unboundedPreceding' | 'currentRow' | 'unboundedFollowing' | { readonly preceding: number } | { readonly following: number }
+
+/** A window frame: `rows|range|groups [between] start [and end]`. */
+export interface WindowFrame {
+  readonly mode: 'rows' | 'range' | 'groups'
+  readonly start: FrameBound
+  readonly end?: FrameBound
+}
+
+function frameBound(bound: FrameBound): string {
+  if (bound === 'unboundedPreceding') return 'unbounded preceding'
+  if (bound === 'currentRow') return 'current row'
+  if (bound === 'unboundedFollowing') return 'unbounded following'
+  const [dir, n] = 'preceding' in bound ? ['preceding', bound.preceding] as const : ['following', bound.following] as const
+  if (!Number.isInteger(n) || n < 0) throw new Error(`over: frame ${dir} must be a non-negative integer, got ${String(n)}`)
+  return `${n} ${dir}`
+}
+
+/** Applies a window specification to a window function or aggregate: `fn OVER (PARTITION BY ... ORDER BY ...)`. */
+export function over<T>(fn: SQL<T>, spec: WindowSpec): SQL<T> {
+  const parts: SQL[] = []
+  if (spec.partitionBy !== undefined) {
+    const cols = Array.isArray(spec.partitionBy) ? spec.partitionBy : [spec.partitionBy]
+    parts.push(sql`partition by ${sql.join(cols.map(c => sql`${c}`), sql`, `)}`)
+  }
+  if (spec.orderBy !== undefined) {
+    const cols = Array.isArray(spec.orderBy) ? spec.orderBy : [spec.orderBy]
+    parts.push(sql`order by ${sql.join(cols, sql`, `)}`)
+  }
+  if (spec.frame !== undefined) {
+    const { mode, start, end } = spec.frame
+    const text = end === undefined ? `${mode} ${frameBound(start)}` : `${mode} between ${frameBound(start)} and ${frameBound(end)}`
+    parts.push(sql.raw(text))
+  }
+  if (parts.length === 0) return sql<T>`${fn} over ()`
+  return sql<T>`${fn} over (${sql.join(parts, sql` `)})`
+}
+
+/**
+ * PostgreSQL quoted identifier. One part renders `"name"`; multiple parts
+ * dot-qualify: `identifier('t', 'n')` → `"t"."n"`. Each part is one
+ * identifier — a dot inside a part is quoted literally, not a qualifier.
+ */
+export function identifier(first: string, ...rest: string[]): SQL {
+  let qualified = sql`${sql.identifier(first)}`
+  for (const part of rest) {
+    qualified = sql`${qualified}.${sql.identifier(part)}`
+  }
+  return qualified
+}
+
+/** PostgreSQL `WITH RECURSIVE alias AS (seed UNION ALL step) finalQuery`. If `finalQuery` is omitted, defaults to `SELECT * FROM alias`. */
+export function withRecursive(alias: string, seed: SQL, step: SQL, finalQuery?: SQL): SQL {
+  const cte = sql`WITH RECURSIVE ${sql.identifier(alias)} AS (${seed} UNION ALL ${step})`
+  if (finalQuery !== undefined) {
+    return sql`${cte} ${finalQuery}`
+  }
+  return sql`${cte} SELECT * FROM ${sql.identifier(alias)}`
+}
+
+/** One `WHEN <when> THEN <then>` branch of a {@link caseWhen} expression. */
+export interface CaseBranch<T = unknown> {
+  readonly when: SQL | Column
+  readonly then: T | SQL<T> | Column
+}
+
+/** PostgreSQL `CASE WHEN .. THEN .. [ELSE ..] END`. Branches evaluate in order; without `elseValue` an unmatched row yields NULL. */
+export function caseWhen<T = unknown>(branches: ReadonlyArray<CaseBranch<T>>, elseValue?: T | SQL<T> | Column): SQL<T> {
+  if (branches.length === 0) {
+    throw new Error(
+      '[pipework] caseWhen() requires at least one branch.\n\n' +
+      '  A CASE expression with no WHEN clauses is not valid SQL.\n' +
+      "  Pass at least one branch: caseWhen([{ when: filter.eq(col, 1), then: 'one' }], 'other').\n",
+    )
+  }
+  const parts: SQL[] = branches.map(b => sql`when ${b.when} then ${b.then}`)
+  if (elseValue !== undefined) {
+    parts.push(sql`else ${elseValue}`)
+  }
+  return sql<T>`case ${sql.join(parts, sql` `)} end`
+}
+
+/** PostgreSQL `pg_current_wal_lsn()` — returns the current WAL write position on the primary, as text. */
+export function walCurrentLsn(): SQL<string> {
+  return sql<string>`pg_current_wal_lsn()::text`
+}
+
+/** PostgreSQL `pg_last_wal_replay_lsn()` — returns the last replayed WAL position on a replica, as text. Returns NULL on the primary. */
+export function walReplayLsn(): SQL<string | null> {
+  return sql<string | null>`pg_last_wal_replay_lsn()::text`
+}
+
+/** PostgreSQL `pg_last_wal_replay_lsn() >= lsn::pg_lsn` — true once a replica has replayed up to the given LSN. Yields NULL (not true) on a primary, where there is no replay position. */
+export function replicaFresh(createdLsn: string | Column | SQL): SQL<boolean | null> {
+  return sql<boolean | null>`pg_last_wal_replay_lsn() >= ${createdLsn}::pg_lsn`
+}

package/src/data/db/filter.ts

@@ -0,0 +1,90 @@
+import {
+  and, arrayContained, arrayContains, arrayOverlaps, asc, between, desc, eq, exists, gt, gte,
+  ilike, inArray, is, isNotNull, isNull, like, lt, lte, ne, not, notBetween, notExists, notIlike,
+  notInArray, notLike, or,
+} from '../query/index.js'
+import { countAgg, countDistinctAgg, sumAgg, sumDistinctAgg, avgAgg, avgDistinctAgg, maxAgg, minAgg, boolAnd, boolOr, arrayAgg, stringAgg, jsonbAgg, jsonbObjectAgg, jsonbBuildObject } from './aggregates.js'
+import { except, exceptAll, intersect, intersectAll, union, unionAll } from '../query/pg-core/index.js'
+import { increment, decrement, add, subtract, coalesce, now, scalar, cast, collate, interval, clockTimestamp, strpos, textContains, startsWith, left, right, length, concat, arrayReplace, arrayHas, splitPart, lower, upper, trim, replace, substring, reverse, lpad, rpad, regexpReplace, regexpMatch, stringToArray, cardinality, arrayAt, arrayPosition, arraySlice, arrayToString, arrayAppend, arrayRemove, dateTrunc, rowNumber, rank, denseRank, over, identifier, withRecursive, caseWhen, walCurrentLsn, walReplayLsn, replicaFresh } from './expressions.js'
+import { ago, castUuid, castJsonb, castTimestamp, castBoolean, castNumeric, castInteger, castText, nextSequence } from './composed.js'
+import { json as jsonbExtract, pathText as jsonbExtractText, contains as jsonbContains, merge as jsonbMerge, remove as jsonbRemove } from '../jsonb/query.js'
+import { arrayAny, arrayAll, jsonbElements } from './array-elements.js'
+import { inList, notInList } from './in-list.js'
+
+export const filter = {
+  and, arrayContained, arrayContains, arrayOverlaps, asc, between, desc, eq, exists, gt, gte,
+  ilike, inArray, is, isNotNull, isNull, like, lt, lte, ne, not, notBetween, notExists, notIlike,
+  notInArray, notLike, or,
+  avg: avgAgg, avgDistinct: avgDistinctAgg, count: countAgg, countDistinct: countDistinctAgg, max: maxAgg, min: minAgg, sum: sumAgg, sumDistinct: sumDistinctAgg,
+  boolAnd, boolOr, arrayAgg, stringAgg, jsonbAgg, jsonbObjectAgg, jsonbBuildObject,
+  except, exceptAll, intersect, intersectAll, union, unionAll,
+  increment,
+  decrement,
+  add,
+  subtract,
+  coalesce,
+  now,
+  scalar,
+  cast,
+  collate,
+  interval,
+  clockTimestamp,
+  strpos,
+  textContains,
+  startsWith,
+  left,
+  right,
+  length,
+  concat,
+  arrayReplace,
+  arrayHas,
+  splitPart,
+  lower,
+  upper,
+  trim,
+  replace,
+  substring,
+  reverse,
+  lpad,
+  rpad,
+  regexpReplace,
+  regexpMatch,
+  stringToArray,
+  cardinality,
+  arrayAt,
+  arrayPosition,
+  arraySlice,
+  arrayToString,
+  arrayAppend,
+  arrayRemove,
+  dateTrunc,
+  rowNumber,
+  rank,
+  denseRank,
+  over,
+  identifier,
+  withRecursive,
+  ago,
+  castUuid,
+  castJsonb,
+  castTimestamp,
+  castBoolean,
+  castNumeric,
+  castInteger,
+  castText,
+  nextSequence,
+  caseWhen,
+  walCurrentLsn,
+  walReplayLsn,
+  replicaFresh,
+  jsonbExtract,
+  jsonbExtractText,
+  jsonbContains,
+  jsonbMerge,
+  jsonbRemove,
+  arrayAny,
+  arrayAll,
+  jsonbElements,
+  inList,
+  notInList,
+} as const

package/src/data/db/function-source.ts

@@ -0,0 +1,114 @@
+import { sql } from './sql.js'
+import type { SQL } from './types.js'
+import { Subquery } from '../query/subquery.js'
+import { SelectionProxyHandler } from '../query/selection-proxy.js'
+import { getTableColumns } from '../query/utils.js'
+import { bindIfParam } from '../query/index.js'
+import type { Column } from './types.js'
+import type { InferFieldOutput } from '../domain/brand.js'
+import type { FieldDescriptor } from '../domain/types.js'
+import { projectTable } from '../domain/build-table.js'
+import { camelToSnake } from '../domain/naming.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- variance-safe bound for descriptors with any output/flags
+type AnyField = FieldDescriptor<any, any>
+
+const NAME_PART = /^[a-z_][a-z0-9_]*$/
+
+/** Declares a SQL function's argument and result-column shapes. See {@link fn}. */
+export interface FunctionSpec<TArgs extends readonly AnyField[], TColumns extends Record<string, AnyField>> {
+  /** One `pipe.field.*` descriptor per argument, in call order. */
+  readonly args: readonly [...TArgs]
+  /** One `pipe.field.*` descriptor per result column; keys are camelCase, columns are their snake_case. */
+  readonly columns: TColumns
+}
+
+type ArgValues<TArgs extends readonly AnyField[]> = { [K in keyof TArgs]: InferFieldOutput<TArgs[K]> }
+
+/** The selected fields of a function source: each result column as a typed SQL expression. */
+export type FunctionSourceFields<TColumns extends Record<string, AnyField>> = {
+  [K in keyof TColumns]: SQL<InferFieldOutput<TColumns[K]>>
+}
+
+/** A function call usable in `.from()` and joins; its result columns are properties of it. */
+export type FunctionSource<TAlias extends string, TColumns extends Record<string, AnyField>> =
+  & Subquery<TAlias, FunctionSourceFields<TColumns>>
+  & FunctionSourceFields<TColumns>
+  & {
+    /** The same call under another alias — needed to use one function twice in a query. */
+    as<TNew extends string>(alias: TNew): FunctionSource<TNew, TColumns>
+  }
+
+function fail(message: string, fix: string): never {
+  throw new Error(`[pipework] ${message}\n\n  Fix: ${fix}\n`)
+}
+
+function quote(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+/**
+ * Declares a set-returning SQL function and returns a callable that yields a source for `.from()` and joins.
+ * Each argument is bound as a parameter, converted the way a column of that field is on insert (jsonb as JSON text,
+ * dates, bigints, arrays), and cast to its declared SQL type: `ext.f($1::uuid, $2::text)`. A null binds SQL NULL.
+ * An array argument (`field.uuid().array()`) is one parameter: `ext.f($1::uuid[])`.
+ * Result columns are typed from `columns`; the default alias is the function's unqualified name.
+ */
+export function fn<const TArgs extends readonly AnyField[], TColumns extends Record<string, AnyField>>(
+  name: string,
+  spec: FunctionSpec<TArgs, TColumns>,
+): (...values: ArgValues<TArgs>) => FunctionSource<string, TColumns> {
+  const parts = name.split('.')
+  if (parts.length > 2 || parts.some(p => !NAME_PART.test(p))) {
+    fail(
+      `pipe.fn: "${name}" is not a function name.`,
+      'use "fn" or "schema.fn", each part lowercase letters, digits and underscores, not starting with a digit.',
+    )
+  }
+  const keys = Object.keys(spec.columns)
+  if (keys.length === 0) fail(`pipe.fn("${name}"): columns is empty.`, 'declare at least one result column.')
+  for (const key of keys) {
+    if (key === 'as' || key === '_') {
+      fail(`pipe.fn("${name}"): a result column cannot be named "${key}".`, 'rename the key; the column name comes from camelToSnake(key).')
+    }
+  }
+
+  const argFields: Record<string, AnyField> = {}
+  spec.args.forEach((a, i) => { argFields[`a${i}`] = a })
+  const argCols = getTableColumns(projectTable('pw_fn_args', argFields, {})) as Record<string, { getSQLType(): string; mapToDriverValue(value: unknown): unknown }>
+  const argTypes = spec.args.map((_, i) => {
+    const t = argCols[`a${i}`]!.getSQLType()
+    return t === 'serial' ? 'integer' : t === 'bigserial' ? 'bigint' : t
+  })
+
+  const fnSql = sql.raw(parts.map(quote).join('.'))
+  const defaultAlias = parts[parts.length - 1]!
+
+  const build = (values: readonly unknown[], alias: string): FunctionSource<string, TColumns> => {
+    const columnList = sql.join(keys.map(k => sql.raw(quote(camelToSnake(k)))), sql`, `)
+    const argList = sql.join(values.map((v, i) => sql`${bindIfParam(v, argCols[`a${i}`] as unknown as Column)}::${sql.raw(argTypes[i]!)}`), sql`, `)
+    const inner = sql`select ${columnList} from ${fnSql}(${argList})`
+    const fields: Record<string, SQL> = {}
+    for (const k of keys) {
+      fields[k] = sql.raw(`${quote(alias)}.${quote(camelToSnake(k))}`)
+    }
+    const subquery = new Subquery(inner, fields, alias)
+    const selection = new SelectionProxyHandler<Subquery>({ alias, sqlAliasedBehavior: 'alias', sqlBehavior: 'sql' })
+    return new Proxy(subquery, {
+      get(target, prop) {
+        if (prop === 'as') return (next: string) => build(values, next)
+        return selection.get(target, prop)
+      },
+    }) as unknown as FunctionSource<string, TColumns>
+  }
+
+  return (...values: ArgValues<TArgs>) => {
+    if (values.length !== spec.args.length) {
+      fail(
+        `pipe.fn("${name}"): called with ${values.length} argument(s), declared ${spec.args.length}.`,
+        'pass one value per declared argument.',
+      )
+    }
+    return build(values, defaultAlias)
+  }
+}