pipework 0.251.0 → 0.252.1

package/src/core/validation/types.ts

@@ -0,0 +1,25 @@
+/** Which subsystem produced the validation issue. */
+export type ValidationPhase = 'config' | 'workspace' | 'database' | 'domain' | 'surface'
+
+/** A single validation problem with its phase and human-readable message. */
+export interface ValidationIssue {
+  readonly phase: ValidationPhase
+  readonly message: string
+}
+
+/** Thrown when startup validation finds issues — lists all problems across all phases. */
+export class StartupValidationError extends Error {
+  readonly issues: readonly ValidationIssue[]
+
+  constructor(issues: readonly ValidationIssue[]) {
+    const summary = issues
+      .map(i => `  [${i.phase}]${' '.repeat(Math.max(1, 12 - i.phase.length))}${i.message}`)
+      .join('\n')
+
+    super(
+      `Startup validation failed (${String(issues.length)} issue${issues.length === 1 ? '' : 's'}):\n\n${summary}\n\nFix these issues and restart.`,
+    )
+    this.name = 'StartupValidationError'
+    this.issues = issues
+  }
+}

package/src/data/db/advisory-lock.ts

@@ -0,0 +1,55 @@
+import { sql } from './sql.js'
+import type { DB, SQL } from './types.js'
+import { unscopedExecutor } from '../../auth/tenant/scoped-db.js'
+
+/** Validates the key arguments and builds the lock-argument fragment shared by
+ * advisoryLock and tryAdvisoryLock, so the two can never disagree about a key. */
+function lockArguments(fn: string, first: string | number | undefined, rest: string[]): SQL {
+  if (typeof first === 'number') {
+    const key = rest[0]
+    if (key === undefined) {
+      throw new Error(
+        `[pipework] ${fn}(db, namespace, key) requires a key string.\n\n` +
+        `  ${fn}(db, 1001, 'my-entity')  — numeric namespace + string key\n` +
+        `  ${fn}(db, 'key1', 'key2')      — two hashed string keys\n`,
+      )
+    }
+    return sql`${first}, hashtext(${key})`
+  }
+
+  if (first === undefined) {
+    throw new Error(
+      `[pipework] ${fn} requires at least one key.\n\n` +
+      `  ${fn}(db, 'my-lock')             — single hashed key\n` +
+      `  ${fn}(db, 'key1', 'key2')        — two hashed keys\n` +
+      `  ${fn}(db, 1001, 'my-entity')    — numeric namespace + hashed key\n`,
+    )
+  }
+
+  if (rest.length === 0) return sql`hashtext(${first})`
+  return sql`hashtext(${first}), hashtext(${rest[0]!})`
+}
+
+/** Acquires a transaction-scoped advisory lock. Released automatically at commit/rollback.
+ *
+ * String keys: hashed independently into the int4 arguments of pg_advisory_xact_lock.
+ * Numeric namespace: `advisoryLock(db, 1001, 'key')` → `pg_advisory_xact_lock(1001, hashtext('key'))`.
+ */
+export async function advisoryLock(db: DB, namespace: number, key: string): Promise<void>
+export async function advisoryLock(db: DB, ...keys: string[]): Promise<void>
+export async function advisoryLock(db: DB, first?: string | number, ...rest: string[]): Promise<void> {
+  const args = lockArguments('advisoryLock', first, rest)
+  await unscopedExecutor(db).db.execute(sql`SELECT pg_advisory_xact_lock(${args})`)
+}
+
+/** Non-blocking advisoryLock: takes the same lock (same key forms, same hashing) if it is free
+ * and returns true, or returns false at once when another transaction holds it.
+ * A lock won is held until commit/rollback.
+ */
+export async function tryAdvisoryLock(db: DB, namespace: number, key: string): Promise<boolean>
+export async function tryAdvisoryLock(db: DB, ...keys: string[]): Promise<boolean>
+export async function tryAdvisoryLock(db: DB, first?: string | number, ...rest: string[]): Promise<boolean> {
+  const args = lockArguments('tryAdvisoryLock', first, rest)
+  const rows = await unscopedExecutor(db).db.execute(sql`SELECT pg_try_advisory_xact_lock(${args}) AS locked`)
+  return rows[0]?.['locked'] === true
+}

package/src/data/db/aggregates.ts

@@ -0,0 +1,172 @@
+import { avg, avgDistinct, count, countDistinct, max, min, sum, sumDistinct } from '../query/index.js'
+import type { SQLWrapper } from '../query/sql/sql.js'
+import { noopDecoder } from '../query/sql/sql.js'
+import { parsePgArray } from '../query/pg-core/utils/array.js'
+import { is } from '../query/entity.js'
+import { Column as DrizzleColumn } from '../query/column.js'
+import { sql } from './sql.js'
+import type { SQL, Column } from './types.js'
+
+/** An aggregate expression that can be narrowed with `FILTER (WHERE …)`; `undefined` leaves it unfiltered. */
+export type Aggregate<T> = SQL<T> & {
+  filterWhere(condition: SQL | undefined): SQL<T>
+}
+
+/** An array or jsonb aggregate; `orEmpty()` replaces the no-rows NULL with an empty array. */
+export type EmptyableAggregate<T, E> = SQL<T> & {
+  orEmpty(): SQL<E>
+  filterWhere(condition: SQL | undefined): SQL<T> & { orEmpty(): SQL<E> }
+}
+
+/**
+ * The type a value takes after a round trip through jsonb: Date -> string (ISO text),
+ * bigint -> number, Buffer/Uint8Array -> string, objects and arrays mapped recursively,
+ * null kept. Column decoders are not applied inside jsonb.
+ */
+export type JsonOf<T> =
+  T extends null | undefined ? T
+  : T extends Date ? string
+  : T extends bigint ? number
+  : T extends Uint8Array ? string
+  : T extends readonly (infer U)[] ? JsonOf<U>[]
+  : T extends object ? { [K in keyof T]: JsonOf<T[K]> }
+  : T
+
+type ColumnValue<C extends Column> = C['_']['notNull'] extends true ? C['_']['data'] : C['_']['data'] | null
+type ValueOf<E> = E extends Column ? ColumnValue<E> : E extends SQL<infer T> ? T : unknown
+/** The jsonb-side type of an expression: numeric columns come back as numbers, not strings. */
+type JsonValueOf<E> =
+  E extends Column
+    ? (E['_']['columnType'] extends 'PgNumeric' ? (E['_']['notNull'] extends true ? number : number | null) : JsonOf<ColumnValue<E>>)
+    : E extends SQL<infer T> ? JsonOf<T> : unknown
+
+/** `ORDER BY` terms inside an aggregate — `asc(col)` / `desc(col)` or an array of them. */
+export interface AggregateOptions {
+  readonly distinct?: boolean
+  readonly orderBy?: SQL | ReadonlyArray<SQL>
+}
+
+function withFilter<T>(base: SQL<T>): Aggregate<T> {
+  const agg = base as Aggregate<T>
+  agg.filterWhere = (condition) => {
+    if (condition === undefined) return base
+    return sql`${base} filter (where ${condition})`.mapWith(base.decoder) as SQL<T>
+  }
+  return agg
+}
+
+/** Parses an array literal the driver left as text, then decodes each non-null element with the argument's decoder. */
+function arrayDecoder(arg: Column | SQL): SQL['decoder'] | undefined {
+  const element = is(arg, DrizzleColumn)
+    ? (v: unknown) => (arg as Column).mapFromDriverValue(v)
+    : (arg as SQL).decoder !== noopDecoder
+      ? (v: unknown) => (arg as SQL).decoder.mapFromDriverValue(v)
+      : undefined
+  return {
+    mapFromDriverValue(value: unknown) {
+      const list = typeof value === 'string' ? parsePgArray(value) : value
+      if (element === undefined || !Array.isArray(list)) return list
+      return list.map(v => (v === null || v === undefined ? v : element(v)))
+    },
+  }
+}
+
+function withEmpty<T, E>(base: SQL<T>, empty: SQL, decoder?: SQL['decoder']): EmptyableAggregate<T, E> {
+  if (decoder !== undefined) base.mapWith(decoder)
+  const orEmpty = (inner: SQL<T>): SQL<E> => {
+    const out = sql`coalesce(${inner}, ${empty})`
+    if (decoder !== undefined) out.mapWith(decoder)
+    return out as SQL<E>
+  }
+  const agg = base as EmptyableAggregate<T, E>
+  agg.orEmpty = () => orEmpty(base)
+  agg.filterWhere = (condition) => {
+    const filtered = (condition === undefined ? base : sql`${base} filter (where ${condition})`.mapWith(base.decoder)) as SQL<T> & { orEmpty(): SQL<E> }
+    filtered.orEmpty = () => orEmpty(filtered)
+    return filtered
+  }
+  return agg
+}
+
+function inside(distinct: boolean | undefined, arg: SQL, orderBy: AggregateOptions['orderBy'], tail?: SQL): SQL {
+  const parts: SQL[] = []
+  if (distinct === true) parts.push(sql`distinct `)
+  parts.push(arg)
+  if (tail !== undefined) parts.push(sql`, ${tail}`)
+  if (orderBy !== undefined) {
+    const terms = Array.isArray(orderBy) ? orderBy : [orderBy]
+    if (terms.length > 0) parts.push(sql` order by ${sql.join(terms as SQL[], sql`, `)}`)
+  }
+  return sql.join(parts, sql``)
+}
+
+/** `count(expr)` or `count(*)`, with `.filterWhere(cond)`. */
+export function countAgg(expression?: SQLWrapper): Aggregate<number> {
+  return withFilter(count(expression))
+}
+/** `count(distinct expr)`, with `.filterWhere(cond)`. */
+export function countDistinctAgg(expression: SQLWrapper): Aggregate<number> {
+  return withFilter(countDistinct(expression))
+}
+/** `sum(expr)`, with `.filterWhere(cond)`. */
+export function sumAgg(expression: SQLWrapper): Aggregate<string | null> {
+  return withFilter(sum(expression))
+}
+/** `sum(distinct expr)`, with `.filterWhere(cond)`. */
+export function sumDistinctAgg(expression: SQLWrapper): Aggregate<string | null> {
+  return withFilter(sumDistinct(expression))
+}
+/** `avg(expr)`, with `.filterWhere(cond)`. */
+export function avgAgg(expression: SQLWrapper): Aggregate<string | null> {
+  return withFilter(avg(expression))
+}
+/** `avg(distinct expr)`, with `.filterWhere(cond)`. */
+export function avgDistinctAgg(expression: SQLWrapper): Aggregate<string | null> {
+  return withFilter(avgDistinct(expression))
+}
+/** `max(expr)`, with `.filterWhere(cond)`. */
+export function maxAgg<T extends SQLWrapper>(expression: T): Aggregate<ReturnType<typeof max<T>> extends SQL<infer R> ? R : never> {
+  return withFilter(max(expression)) as never
+}
+/** `min(expr)`, with `.filterWhere(cond)`. */
+export function minAgg<T extends SQLWrapper>(expression: T): Aggregate<ReturnType<typeof min<T>> extends SQL<infer R> ? R : never> {
+  return withFilter(min(expression)) as never
+}
+
+/** `bool_and(expr)` — NULL over zero rows. */
+export function boolAnd(expression: Column | SQL): Aggregate<boolean | null> {
+  return withFilter(sql<boolean | null>`bool_and(${expression})`)
+}
+/** `bool_or(expr)` — NULL over zero rows. */
+export function boolOr(expression: Column | SQL): Aggregate<boolean | null> {
+  return withFilter(sql<boolean | null>`bool_or(${expression})`)
+}
+
+/** `array_agg([distinct] expr [order by …])`; NULL over zero rows, `.orEmpty()` gives `{}`. */
+export function arrayAgg<E extends Column | SQL>(expression: E, options: AggregateOptions = {}): EmptyableAggregate<ValueOf<E>[] | null, ValueOf<E>[]> {
+  const base = sql<ValueOf<E>[] | null>`array_agg(${inside(options.distinct, sql`${expression}`, options.orderBy)})`
+  return withEmpty(base, sql`'{}'`, arrayDecoder(expression))
+}
+
+/** `string_agg([distinct] expr, delimiter [order by …])`; the delimiter is bound. */
+export function stringAgg(expression: Column | SQL, delimiter: string, options: AggregateOptions = {}): Aggregate<string | null> {
+  return withFilter(sql<string | null>`string_agg(${inside(options.distinct, sql`${expression}`, options.orderBy, sql`${delimiter}::text`)})`)
+}
+
+/** `jsonb_agg([distinct] expr [order by …])`; NULL over zero rows, `.orEmpty()` gives `[]`. Elements are typed by {@link JsonOf}. */
+export function jsonbAgg<E extends Column | SQL>(expression: E, options: AggregateOptions = {}): EmptyableAggregate<JsonValueOf<E>[] | null, JsonValueOf<E>[]> {
+  const base = sql<JsonValueOf<E>[] | null>`jsonb_agg(${inside(options.distinct, sql`${expression}`, options.orderBy)})`
+  return withEmpty(base, sql`'[]'::jsonb`)
+}
+
+/** `jsonb_object_agg(key, value)`; NULL over zero rows. */
+export function jsonbObjectAgg<V extends Column | SQL>(key: Column | SQL, value: V): Aggregate<Record<string, JsonValueOf<V>> | null> {
+  return withFilter(sql<Record<string, JsonValueOf<V>> | null>`jsonb_object_agg(${key}, ${value})`)
+}
+
+/** `jsonb_build_object('key', expr, …)` — keys are bound as text. Values are typed by {@link JsonOf}. */
+export function jsonbBuildObject<F extends Record<string, Column | SQL>>(fields: F): SQL<{ [K in keyof F]: JsonValueOf<F[K]> }> {
+  const args: SQL[] = []
+  for (const [key, value] of Object.entries(fields)) args.push(sql`${key}::text, ${value}`)
+  return sql<{ [K in keyof F]: JsonValueOf<F[K]> }>`jsonb_build_object(${sql.join(args, sql`, `)})`
+}

package/src/data/db/array-elements.ts

@@ -0,0 +1,111 @@
+import { sql } from './sql.js'
+import type { SQL, Column } from './types.js'
+import { is } from '../query/entity.js'
+import { Column as DrizzleColumn } from '../query/column.js'
+import { SQL as DrizzleSQL } from '../query/sql/sql.js'
+
+const jsonbElementsBrand: unique symbol = Symbol('pipework.jsonbElements')
+
+/** A jsonb array read as its elements' text. Produced by {@link jsonbElements}. */
+export interface JsonbElements {
+  readonly [jsonbElementsBrand]: SQL
+}
+
+/** Something whose elements `arrayAny` / `arrayAll` can test. */
+export type ArraySource =
+  | (Column & { _: { data: readonly unknown[] } })
+  | SQL<readonly unknown[] | null>
+  | JsonbElements
+  | readonly string[]
+  | readonly number[]
+
+/** The element type of an {@link ArraySource}. */
+export type ElementOf<S> =
+  S extends readonly (infer E)[] ? E
+  : S extends JsonbElements ? string
+  : S extends { _: { data: infer D } } ? (D extends readonly (infer E)[] ? E : never)
+  : S extends SQL<infer A> ? (A extends readonly (infer E)[] ? E : never)
+  : never
+
+/** Marks a jsonb array (a column or `SQL`) to be tested element by element, as text: `jsonb_array_elements_text(<jsonb>)`. */
+export function jsonbElements(jsonb: Column | SQL): JsonbElements {
+  return { [jsonbElementsBrand]: sql`${jsonb}` }
+}
+
+let counter = 0
+
+function isJsonbElements(value: unknown): value is JsonbElements {
+  return typeof value === 'object' && value !== null && jsonbElementsBrand in value
+}
+
+function elementsFrom(source: ArraySource, alias: string): SQL {
+  if (Array.isArray(source)) {
+    const items = source as readonly (string | number)[]
+    const numeric = items.length > 0 && typeof items[0] === 'number'
+    if (items.some(v => numeric ? typeof v !== 'number' : typeof v !== 'string')) {
+      throw new Error(
+        '[pipework] arrayAny/arrayAll: a JS array source must hold only strings or only numbers.\n\n' +
+        '  Fix: pass an array of one type, or cast the values before passing them.\n',
+      )
+    }
+    const type = numeric ? 'numeric[]' : 'text[]'
+    return sql`unnest(${sql.param(items)}::${sql.raw(type)}) AS ${sql.raw(alias)}(v)`
+  }
+  if (isJsonbElements(source)) {
+    return sql`jsonb_array_elements_text(${source[jsonbElementsBrand]}) AS ${sql.raw(alias)}(v)`
+  }
+  if (is(source, DrizzleColumn) || is(source, DrizzleSQL)) {
+    return sql`unnest(${source}) AS ${sql.raw(alias)}(v)`
+  }
+  throw new Error(
+    '[pipework] arrayAny/arrayAll: the source is not an array column, SQL array expression, JS array or jsonbElements(...).\n\n' +
+    '  Fix: pass one of those.\n',
+  )
+}
+
+function build<S extends ArraySource>(
+  negate: boolean,
+  source: S,
+  predicate: (element: SQL<ElementOf<S>>) => SQL | undefined,
+): SQL<boolean> {
+  const alias = `pw_el_${++counter}`
+  const element = sql<ElementOf<S>>`${sql.raw(alias)}.v`
+  const test = predicate(element)
+  if (test === undefined) {
+    throw new Error(
+      '[pipework] arrayAny/arrayAll: the test returned nothing (and()/or() of no conditions is undefined).\n\n' +
+      '  Fix: return a condition from the test.\n',
+    )
+  }
+  const from = elementsFrom(source, alias)
+  return negate
+    ? sql<boolean>`NOT EXISTS (SELECT 1 FROM ${from} WHERE NOT (${test}))`
+    : sql<boolean>`EXISTS (SELECT 1 FROM ${from} WHERE ${test})`
+}
+
+/**
+ * True when at least one element of the array satisfies the test:
+ * `EXISTS (SELECT 1 FROM unnest(<source>) AS pw_el_<n>(v) WHERE <test>)`.
+ * False for an empty array. A JS array is bound as one parameter cast `::text[]` (strings, also when empty)
+ * or `::numeric[]` (numbers). Calls nest; each gets its own alias.
+ * To test a column's value against an array column so its index can be used, use `filter.arrayHas(arrayCol, col)`.
+ */
+export function arrayAny<S extends ArraySource>(
+  source: S,
+  predicate: (element: SQL<ElementOf<S>>) => SQL | undefined,
+): SQL<boolean> {
+  return build(false, source, predicate)
+}
+
+/**
+ * True when every element of the array satisfies the test:
+ * `NOT EXISTS (SELECT 1 FROM unnest(<source>) AS pw_el_<n>(v) WHERE NOT (<test>))`.
+ * True for an empty array. An element for which the test is null counts as not failing it,
+ * so a null element passes (SQL three-valued logic: `NOT NULL` is null, and a null WHERE row is dropped).
+ */
+export function arrayAll<S extends ArraySource>(
+  source: S,
+  predicate: (element: SQL<ElementOf<S>>) => SQL | undefined,
+): SQL<boolean> {
+  return build(true, source, predicate)
+}

package/src/data/db/bulk-set.ts

@@ -0,0 +1,53 @@
+import type { DB, Table } from './types.js'
+import { getTableName, getTableColumns } from '../query/index.js'
+import { values } from './values.js'
+import type { ValueColumnDef } from './values.js'
+import { identifier } from './expressions.js'
+import { sql } from './sql.js'
+import { unscopedExecutor } from '../../auth/tenant/scoped-db.js'
+import { getScopeConfig } from '../../auth/tenant/scope.js'
+
+type PgCastType = 'uuid' | 'text' | 'integer' | 'bigint' | 'boolean' | 'jsonb' | 'timestamptz' | 'timestamp' | 'date' | 'numeric' | 'real' | 'double precision' | 'smallint' | 'interval'
+
+interface BulkSetOptions<TRow extends Record<string, unknown>> {
+  readonly match: keyof TRow & string
+  readonly set: ReadonlyArray<keyof TRow & string>
+  readonly types: Readonly<Record<keyof TRow & string, PgCastType>>
+}
+
+/** Executes UPDATE ... FROM (VALUES ...) for bulk per-row updates in a single statement. */
+export async function bulkSet<TRow extends Record<string, unknown>>(
+  handle: DB,
+  table: Table,
+  rows: readonly TRow[],
+  options: BulkSetOptions<TRow>,
+): Promise<void> {
+  if (rows.length === 0) return
+
+  const { db, tenant } = unscopedExecutor(handle)
+  const tableName = getTableName(table)
+  const columns = getTableColumns(table)
+  const allKeys = [options.match, ...options.set] as string[]
+
+  const columnDefs: ValueColumnDef[] = allKeys.map(key => ({
+    name: columns[key]?.name ?? key,
+    type: options.types[key as keyof TRow & string] as PgCastType,
+  }))
+
+  const rowArrays = rows.map(row => allKeys.map(key => row[key as keyof TRow]))
+  const valuesClause = values(rowArrays, columnDefs)
+
+  const colNames = columnDefs.map(c => c.name)
+  const matchCol = columns[options.match]?.name ?? options.match
+
+  const setClauses = (options.set as string[]).map(key => {
+    const colName = columns[key]?.name ?? key
+    return sql`${identifier(colName)} = ${sql.raw('_vals.' + '"' + colName + '"')}`
+  })
+
+  const scope = tenant === null ? null : getScopeConfig(table as never)
+  const tenantFilter = scope == null ? sql`` : sql` AND ${identifier(tableName)}.${identifier(columns[scope.columnKey]?.name ?? scope.columnKey)} = ${tenant}`
+  await db.execute(
+    sql`UPDATE ${identifier(tableName)} SET ${sql.join(setClauses, sql`, `)} FROM ${valuesClause} AS _vals(${sql.raw(colNames.join(', '))}) WHERE ${identifier(tableName)}.${identifier(matchCol)} = ${sql.raw('_vals.' + '"' + matchCol + '"')}${tenantFilter}`,
+  )
+}

package/src/data/db/col/index.ts

@@ -0,0 +1,14 @@
+// Column type builders — manual layer (wrappable)
+// Each re-export can be replaced with a pipework wrapper as needed.
+// e.g., `timestamp` could enforce withTimezone by default.
+
+export {
+  text, uuid, serial, integer, bigint, boolean,
+  timestamp, jsonb, varchar, real, doublePrecision, numeric,
+  char, smallint, smallserial, bigserial,
+  date, time, interval, json, inet, cidr, macaddr, macaddr8,
+  bit, decimal, geometry, point, line,
+  vector, halfvec, sparsevec,
+  customType,
+  pgEnum as enumType,
+} from '../../query/pg-core/index.js'

package/src/data/db/composed.ts

@@ -0,0 +1,53 @@
+import type { SQL, Column, DB } from './types.js'
+import { now, subtract, interval, cast, scalar, coalesce, increment } from './expressions.js'
+import type { IntervalUnit } from './expressions.js'
+import { max } from '../query/index.js'
+import type { SQLWrapper } from '../query/sql/sql.js'
+
+/** `now() - interval '5 minutes'`. Composes `now`, `subtract`, and `interval`. */
+export function ago(amount: number, unit: IntervalUnit): SQL<Date> {
+  return subtract<Date>(now(), interval(amount, unit))
+}
+
+/** Shorthand for `cast(expr, 'uuid')`. */
+export function castUuid(expression: SQL | Column | SQLWrapper): SQL<string> {
+  return cast<string>(expression, 'uuid')
+}
+
+/** Shorthand for `cast(expr, 'jsonb')`. */
+export function castJsonb(expression: SQL | Column | SQLWrapper): SQL {
+  return cast(expression, 'jsonb')
+}
+
+/** Shorthand for `cast(expr, 'timestamptz')`. */
+export function castTimestamp(expression: SQL | Column | SQLWrapper): SQL<Date> {
+  return cast<Date>(expression, 'timestamptz')
+}
+
+/** Shorthand for `cast(expr, 'boolean')`. */
+export function castBoolean(expression: SQL | Column | SQLWrapper): SQL<boolean> {
+  return cast<boolean>(expression, 'boolean')
+}
+
+/** Shorthand for `cast(expr, 'numeric')`. */
+export function castNumeric(expression: SQL | Column | SQLWrapper): SQL<number> {
+  return cast<number>(expression, 'numeric')
+}
+
+/** Shorthand for `cast(expr, 'integer')`. */
+export function castInteger(expression: SQL | Column | SQLWrapper): SQL<number> {
+  return cast<number>(expression, 'integer')
+}
+
+/** Shorthand for `cast(expr, 'text')`. */
+export function castText(expression: SQL | Column | SQLWrapper): SQL<string> {
+  return cast<string>(expression, 'text')
+}
+
+/** `COALESCE((SELECT MAX(column) FROM table WHERE condition), 0) + 1`. Composes scalar, coalesce, max, increment. */
+export function nextSequence(db: DB, column: Column, where?: SQL): SQL<number> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's select/from generics require concrete schema types
+  const base = (db as any).select({ v: max(column) }).from(column.table)
+  const subquery = where !== undefined ? base.where(where) : base
+  return increment(coalesce<number>(scalar<number>(subquery), 0), 1)
+}