pipework 0.290.0 → 0.292.0

package/src/data/write/state.ts

@@ -35,6 +35,12 @@ export interface WriteState {
   readonly onConflictColumns?: readonly string[]
   /** `ON CONFLICT DO NOTHING` for `insert`; `target` is field keys, absent for the bare clause. */
   readonly onConflict?: { readonly action: 'nothing'; readonly target?: readonly string[] }
+  /** `insert` only: send every row as one statement (`INSERT ... SELECT FROM unnest(...)`), whatever the row count. */
+  readonly batch?: boolean
+  /** `insert` batch only: the columns already encoded for this statement (set by the batch planner). */
+  readonly encoded?: unknown
+  /** `update` only: one update for many keys, `from` a keys rowset; the result is the row count per input key. */
+  readonly each?: { readonly source: unknown; readonly ordinal: SQL; readonly count: number }
   /** What `RETURNING` should produce. `null` (default) emits no RETURNING. */
   readonly returning?: ReturningShape
 }

package/src/data/write/update-each.ts

@@ -0,0 +1,120 @@
+// `pipe.updateEach(table, { keys, data, where, set })`: one UPDATE for many keys, a count per key.
+//
+//   UPDATE "t" SET ... FROM (select * from unnest($1::uuid[], $2::int[], $3::int[]) as "rows"("id", "ordinal", "_i")) "rows"
+//   WHERE <where> RETURNING "rows"."_i"
+//
+// The keys travel as `pipe.rows` columns (one parameter per column), each with its input index `_i`. The
+// rows the update returns are counted per `_i`, which is what tells a key that matched nothing (it never
+// appears in the result) from one that matched once. A key that did not match exactly once rolls the update
+// back (a savepoint inside the caller's transaction) and throws naming the key.
+
+import type { SQL } from '../db/types.js'
+import { pipe } from '../db/db.js'
+import { rows } from '../db/rows.js'
+import type { RowsColumns, RowsData, RowsSource } from '../db/rows.js'
+import type { PgTable } from '../query/pg-core/index.js'
+import { assertNotExternal } from '../domain/external-registry.js'
+import type { DefinedTable } from '../domain/types.js'
+import type { UpdateSetValues } from './values.js'
+import { executeWrite } from './execute.js'
+import { batchLimits } from './batch-insert.js'
+
+const ORDINAL = '_i'
+
+export interface UpdateEachOptions<T extends PgTable, TKeys extends RowsColumns> {
+  /** The key rowset's columns, each with its SQL type: `{ id: 'uuid', ordinal: 'int' }`. Read in `where` and `set` as `k.id`. */
+  readonly keys: TKeys
+  /** One array per column, all the same length; element i of each is input key i. */
+  readonly data: RowsData<TKeys>
+  /** Which columns identify an input key: they must be distinct across inputs, and name the key in an error. Default: all of `keys`. */
+  readonly key?: ReadonlyArray<keyof TKeys & string>
+  /** The match for one key, as for `pipe.update().where()`: `and(eq(t.id, k.id), isNull(t.closedAt))`. */
+  readonly where: (k: RowsSource<'rows', TKeys>) => SQL | undefined
+  /** What to set; a key column is a valid value: `{ closedAt: k.ordinal }`. */
+  readonly set: (k: RowsSource<'rows', TKeys>) => UpdateSetValues<T>
+  /** `'one'` (default): every key must update exactly one row or the update is refused. `'any'`: no refusal, read the counts. */
+  readonly expect?: 'one' | 'any'
+}
+
+function describeKey(columns: readonly string[], data: Record<string, readonly unknown[]>, i: number): string {
+  const part = (c: string): string => {
+    const v = data[c]![i]
+    return `${c}=${v instanceof Date ? v.toISOString() : JSON.stringify(v, (_k, x: unknown) => (typeof x === 'bigint' ? x.toString() : x))}`
+  }
+  return `{ ${columns.map(part).join(', ')} }`
+}
+
+/**
+ * Updates the rows each input key matches in one statement and returns how many rows each key updated, in
+ * input order. By default a key that updated zero rows or more than one makes the call throw, naming the key,
+ * with the whole update undone; so does a key repeated in `data`. Runs in the caller's transaction and is audited
+ * as `pipe.update()` is (one audit row per row changed). An empty `data` returns `[]` without a statement.
+ */
+export async function updateEach<T extends DefinedTable<any> & PgTable, const TKeys extends RowsColumns>( // eslint-disable-line @typescript-eslint/no-explicit-any
+  table: T,
+  options: UpdateEachOptions<T, TKeys>,
+): Promise<number[]> {
+  assertNotExternal(table, 'update')
+  const names = Object.keys(options.keys)
+  if (names.includes(ORDINAL)) throw new Error(`[pipework] pipe.updateEach: "${ORDINAL}" is reserved for the input index; rename that key column.`)
+  const data = options.data as Record<string, readonly unknown[]>
+  const count = names.length === 0 ? 0 : (data[names[0]!]?.length ?? 0)
+  const identity: readonly string[] = options.key ?? names
+  for (const c of identity) {
+    if (!names.includes(c)) throw new Error(`[pipework] pipe.updateEach: key column "${c}" is not one of the key rowset's columns (${names.join(', ')}).`)
+  }
+  const seen = new Map<string, number>()
+  for (let i = 0; i < count; i++) {
+    const id = describeKey(identity, data, i)
+    const first = seen.get(id)
+    if (first !== undefined) {
+      throw new Error(`[pipework] pipe.updateEach: key ${id} appears at inputs ${String(first)} and ${String(i)}. Pass each key once; a repeated key would update one row twice.`)
+    }
+    seen.set(id, i)
+  }
+  if (count === 0) return []
+
+  // Over `batchLimits` the keys go as consecutive slices, in order, in the one transaction below: a refusal
+  // anywhere undoes every slice.
+  const slices: [number, number][] = []
+  let from = 0
+  let bytes = 0
+  for (let i = 0; i < count; i++) {
+    let rowBytes = 0
+    for (const c of names) { const v = data[c]![i]; rowBytes += typeof v === 'string' ? Buffer.byteLength(v) : 8 }
+    if (i > from && (i - from >= batchLimits.rows || bytes + rowBytes > batchLimits.bytes)) { slices.push([from, i]); from = i; bytes = 0 }
+    bytes += rowBytes
+  }
+  slices.push([from, count])
+
+  const dbName = table.$options.database
+  const runSlice = async (a: number, b: number): Promise<number[]> => {
+    const part = Object.fromEntries(names.map(c => [c, data[c]!.slice(a, b)]))
+    const source = rows({ ...options.keys, [ORDINAL]: 'int' }, { ...part, [ORDINAL]: Array.from({ length: b - a }, (_, i) => i) } as never)
+    const k = source as unknown as RowsSource<'rows', TKeys>
+    const where = options.where(k)
+    if (where === undefined) throw new Error('[pipework] pipe.updateEach: where() returned no condition. Match each key, e.g. eq(t.id, k.id): without one every key would update every row.')
+    return await executeWrite({
+      verb: 'update' as const,
+      table,
+      set: options.set(k) as Record<string, unknown>,
+      where,
+      each: { source, ordinal: (source as unknown as Record<string, SQL>)[ORDINAL]!, count: b - a },
+    }) as number[]
+  }
+  const run = async (): Promise<number[]> => {
+    const counts: number[] = []
+    for (const [a, b] of slices) for (const n of await runSlice(a, b)) counts.push(n)
+    if ((options.expect ?? 'one') === 'one') {
+      const bad = counts.findIndex(n => n !== 1)
+      if (bad !== -1) {
+        throw new Error(
+          `[pipework] pipe.updateEach: key ${describeKey(identity, data, bad)} (input ${String(bad)}) matched ${String(counts[bad])} rows of "${table.$name}", expected exactly one. ` +
+          'Nothing was updated. A key matching none is absent or no longer eligible (check the where); a key matching several needs a narrower where. Pass expect: \'any\' to read the counts instead.',
+        )
+      }
+    }
+    return counts
+  }
+  return dbName === undefined ? pipe.transaction(run) : pipe.transaction(dbName, run)
+}

package/src/index.ts

@@ -11,7 +11,8 @@ export type { Aggregate, EmptyableAggregate, AggregateOptions, JsonOf } from './
 export type { ValueColumnDef } from './data/db/values.js'
 export type { RowsColumns, RowsData, RowsSource, RowsColumnValue } from './data/db/rows.js'
 export type { ArraySource, ElementOf, JsonbElements } from './data/db/array-elements.js'
-export type { FunctionSpec, FunctionSource, FunctionSourceFields } from './data/db/function-source.js'
+export type { FunctionSpec, ScalarFunctionSpec, FunctionSource, FunctionSourceFields, DefinedCall, FunctionRef } from './data/db/function-source.js'
+export type { FunctionDefinition, FunctionVolatility } from './data/db/function-definition.js'
 export type { SerializableOptions } from './data/db/serializable.js'
 export { StatementTimeoutError, LockTimeoutError } from './data/db/timeouts.js'
 export type { TimeoutOptions } from './data/db/timeouts.js'

package/src/test/function-reads.ts

@@ -0,0 +1,290 @@
+import { sql } from '../data/db/sql.js'
+import { quoteIdentifier } from '../data/db/identifiers.js'
+import type { PostgresJsDatabase } from '../data/query/postgres-js/index.js'
+import type { SQL } from '../data/db/types.js'
+import type { DefinedCall, FunctionRef } from '../data/db/function-source.js'
+
+/** The state of the planner's statistics a measurement was taken under. */
+export type StatisticsState = 'fresh' | 'stale' | 'missing'
+
+export interface FunctionReadMeasurement {
+  /** The `history` the seed was called with. */
+  readonly history: number
+  readonly statistics: StatisticsState
+  /** Rows scanned by the plan's relation scans: (rows returned + rows removed by filter or recheck) x loops, summed. */
+  readonly touched: number
+  /** The scans, largest first, for the message that names where the rows went. */
+  readonly scans: readonly { readonly node: string; readonly relation: string; readonly touched: number }[]
+  /** The plan has a Function Scan on the function, or its call text: the call was not inlined. */
+  readonly calledAsFunction: boolean
+  /** The plan has a CTE Scan. */
+  readonly cteScan: boolean
+}
+
+export interface FunctionReadReport {
+  readonly function: string
+  /** `not-checked` means the read touched no rows on the fixture, so nothing was proved either way. */
+  readonly status: 'passed' | 'failed' | 'not-checked'
+  readonly problems: readonly string[]
+  /** States that could not be measured (and why), so a pass never hides them: with any, `status` is `not-checked` unless something failed. */
+  readonly notChecked: readonly string[]
+  readonly measurements: readonly FunctionReadMeasurement[]
+}
+
+export interface FunctionReadOptions {
+  /** The function under test: what `pipe.fn(...)` returned. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- any typed call
+  readonly fn: DefinedCall<(...values: any[]) => unknown>
+  /** Representative arguments: keys that exist in the fixture at both sizes. */
+  readonly args: readonly unknown[]
+  /** The tables the function reads, `schema.table` (or `table` for public): their statistics are held and cleared by the check. */
+  readonly tables: readonly string[]
+  /**
+   * Leaves the database holding exactly `history` rows of history for the same keys the call looks up: it may
+   * truncate and refill. Called with the small size, then with the large one (ten times the small by default).
+   */
+  readonly seed: (db: PostgresJsDatabase, history: number) => Promise<void>
+  /** The two history sizes. Default `[200, 2000]`. */
+  readonly history?: readonly [number, number]
+  /** How far a count may exceed its baseline: `baseline * (1 + relative) + absolute`. Default 10% and 5 rows. */
+  readonly tolerance?: { readonly relative?: number; readonly absolute?: number }
+}
+
+interface PlanNode {
+  'Node Type'?: string
+  'Relation Name'?: string
+  'Schema'?: string
+  'Function Name'?: string
+  'Actual Rows'?: number
+  'Actual Loops'?: number
+  'Rows Removed by Filter'?: number
+  'Rows Removed by Index Recheck'?: number
+  Plans?: PlanNode[]
+  [key: string]: unknown
+}
+
+function walk(node: PlanNode, visit: (n: PlanNode) => void): void {
+  visit(node)
+  for (const child of node.Plans ?? []) walk(child, visit)
+}
+
+function qualified(ref: FunctionRef): string {
+  return ref.schema === 'public' ? ref.name : `${ref.schema}.${ref.name}`
+}
+
+/** Rows touched and the shape facts of one EXPLAIN (ANALYZE, VERBOSE, FORMAT JSON) plan. */
+export function measurePlan(root: PlanNode, ref: FunctionRef, history: number, statistics: StatisticsState): FunctionReadMeasurement {
+  const scans: { node: string; relation: string; touched: number }[] = []
+  let calledAsFunction = false
+  let cteScan = false
+  const callText = new RegExp(`(?:^|[^\\w])${ref.name}\\s*\\(`)
+  walk(root, node => {
+    if (node['Relation Name'] !== undefined) {
+      const loops = node['Actual Loops'] ?? 1
+      const rows = (node['Actual Rows'] ?? 0) + (node['Rows Removed by Filter'] ?? 0) + (node['Rows Removed by Index Recheck'] ?? 0)
+      scans.push({
+        node: node['Node Type'] ?? 'Scan',
+        relation: `${node['Schema'] ?? 'public'}.${node['Relation Name']}`,
+        touched: rows * loops,
+      })
+    }
+    if (node['Node Type'] === 'CTE Scan') cteScan = true
+    if (node['Function Name'] === ref.name) calledAsFunction = true
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'Plans') continue
+      if ((key === 'Output' || key === 'Function Call' || key.endsWith('Filter') || key === 'Join Filter' || key === 'Index Cond') && callText.test(JSON.stringify(value))) calledAsFunction = true
+    }
+  })
+  scans.sort((a, b) => b.touched - a.touched)
+  return { history, statistics, touched: scans.reduce((n, s) => n + s.touched, 0), scans, calledAsFunction, cteScan }
+}
+
+interface Catalog {
+  readonly language: string
+  readonly volatility: string
+  readonly config: readonly string[] | null
+  readonly securityDefiner: boolean
+  readonly strict: boolean
+}
+
+/** Why Postgres would not inline the function, from its catalog row: the settings a plan cannot show. */
+export function catalogProblems(name: string, c: Catalog | undefined): string[] {
+  if (c === undefined) return [`the function ${name} does not exist in the database. Run the migration that creates it before checking it.`]
+  const problems: string[] = []
+  if (c.config !== null && c.config.length > 0) {
+    problems.push(
+      `${name} has a SET clause (${c.config.join(', ')}). Postgres never inlines a function with a SET clause, so each call is a black box the planner cannot push keys into. ` +
+      'Remove it: a session setting such as jit belongs on the role (`ALTER ROLE app SET jit = off`).',
+    )
+  }
+  if (c.language !== 'sql') {
+    problems.push(`${name} is LANGUAGE ${c.language}. Postgres inlines only LANGUAGE sql functions. Write the read as one SELECT; a computation that is not one SELECT is a derivation, not a read.`)
+  }
+  if (c.volatility === 'v') problems.push(`${name} is VOLATILE. Postgres does not inline a volatile function. Declare it STABLE or IMMUTABLE.`)
+  if (c.securityDefiner) problems.push(`${name} is SECURITY DEFINER. Postgres does not inline a security definer function.`)
+  if (c.strict) problems.push(`${name} is STRICT. Postgres does not inline a strict set-returning function.`)
+  return problems
+}
+
+async function readCatalog(db: PostgresJsDatabase, ref: FunctionRef): Promise<Catalog | undefined> {
+  const signature = `${quoteIdentifier(ref.schema, 'schema')}.${quoteIdentifier(ref.name, 'function')}(${ref.args.join(', ')})`
+  const rows = await db.execute<{ lang: string; vol: string; config: string[] | null; secdef: boolean; strict: boolean }>(sql`
+    select l.lanname as lang, p.provolatile::text as vol, p.proconfig as config, p.prosecdef as secdef, p.proisstrict as strict
+    from pg_proc p join pg_language l on l.oid = p.prolang
+    where p.oid = to_regprocedure(${signature})`)
+  const r = rows[0]
+  return r === undefined ? undefined : { language: r.lang, volatility: r.vol, config: r.config, securityDefiner: r.secdef, strict: r.strict }
+}
+
+async function explain(db: PostgresJsDatabase, opts: FunctionReadOptions, history: number, statistics: StatisticsState): Promise<FunctionReadMeasurement> {
+  const source = opts.fn(...opts.args)
+  return await db.transaction(async tx => {
+    // Parallel workers would split the loop counts the measurement multiplies by.
+    await tx.execute(sql`set local max_parallel_workers_per_gather = 0`)
+    // The call is the typed source (or expression) pipe.fn returns, so the plan is the one the caller's own query gets.
+    const query = opts.fn.ref.setReturning
+      ? tx.select().from(source as unknown as Parameters<ReturnType<typeof tx.select>['from']>[0])
+      : sql`select ${source as unknown as SQL} as value`
+    const rows = await tx.execute<{ 'QUERY PLAN': unknown }>(sql`explain (analyze, verbose, format json) ${query as unknown as SQL}`)
+    const raw = rows[0]?.['QUERY PLAN']
+    const parsed = (typeof raw === 'string' ? JSON.parse(raw) : raw) as { Plan: PlanNode }[]
+    return measurePlan(parsed[0]!.Plan, opts.fn.ref, history, statistics)
+  })
+}
+
+async function setAutovacuum(db: PostgresJsDatabase, tables: readonly string[], on: boolean): Promise<void> {
+  for (const t of tables) {
+    try {
+      await db.execute(sql.raw(`alter table ${qualifiedTable(t)} ${on ? 'reset (autovacuum_enabled)' : 'set (autovacuum_enabled = false)'}`))
+    } catch (err) {
+      throw new Error(
+        `[pipework] checkFunctionRead cannot change autovacuum on ${t}: ${err instanceof Error ? err.message : String(err)}\n\n` +
+        '  Fix: run the check as the role that owns the tables (or a superuser). Autovacuum must be off on them for the run, or a background ANALYZE could turn the stale and missing measurements into fresh ones.\n',
+      )
+    }
+  }
+}
+
+function qualifiedTable(table: string): string {
+  const parts = table.split('.')
+  if (parts.length > 2) throw new Error(`[pipework] checkFunctionRead: "${table}" is not a table name; use "schema.table" or "table".`)
+  return parts.map(p => quoteIdentifier(p, 'table')).join('.')
+}
+
+const where = (m: FunctionReadMeasurement): string => m.scans.length === 0 ? '' : ` Largest scan: ${m.scans[0]!.node} on ${m.scans[0]!.relation} (${m.scans[0]!.touched} rows).`
+
+/**
+ * Plans one call of a pipework-defined read at two history sizes and under three states of the planner's
+ * statistics, and reports whether it is a key lookup: inlined into the calling query, touching a number of rows
+ * that does not grow with history, and no more of them under stale or missing statistics than after ANALYZE.
+ * Rows touched is counted from `EXPLAIN (ANALYZE)`: each relation scan's rows returned plus rows removed by
+ * filter or recheck, times its loops, summed. A read that touches no rows on the fixture is `not-checked`, never passed.
+ *
+ * The statistics states: after ANALYZE at the small size the large history is seeded without analyzing (stale), then
+ * analyzed (fresh), then the tables' pg_statistic rows are deleted (missing). Deleting them needs a superuser, as the
+ * test cluster's role is; autovacuum is switched off on the tables for the run and restored.
+ */
+export async function checkFunctionRead(db: PostgresJsDatabase, opts: FunctionReadOptions): Promise<FunctionReadReport> {
+  const ref = opts.fn.ref
+  const name = qualified(ref)
+  const [small, large] = opts.history ?? [200, 2000]
+  const relative = opts.tolerance?.relative ?? 0.1
+  const absolute = opts.tolerance?.absolute ?? 5
+  const analyze = async (): Promise<void> => { for (const t of opts.tables) await db.execute(sql.raw(`analyze ${qualifiedTable(t)}`)) }
+
+  const problems = catalogProblems(name, await readCatalog(db, ref))
+  const measurements: FunctionReadMeasurement[] = []
+  const role = (await db.execute<{ role: string; super: boolean }>(sql`select current_user::text as role, rolsuper as super from pg_roles where rolname = current_user`))[0]
+  const notChecked: string[] = []
+  if (role?.super !== true) {
+    notChecked.push(
+      `Missing statistics were not checked: role "${role?.role ?? 'unknown'}" is not a superuser, so it cannot delete the tables' pg_statistic rows. ` +
+      'Run the check as a superuser (the disposable test cluster\'s role; PIPEWORK_TEST_SUPERUSER_URL).',
+    )
+  }
+
+  await setAutovacuum(db, opts.tables, false)
+  try {
+    await opts.seed(db, small)
+    await analyze()
+    const freshSmall = await explain(db, opts, small, 'fresh')
+    await opts.seed(db, large)
+    const stale = await explain(db, opts, large, 'stale')
+    await analyze()
+    const freshLarge = await explain(db, opts, large, 'fresh')
+    measurements.push(freshSmall, stale, freshLarge)
+    if (notChecked.length === 0) {
+      for (const t of opts.tables) await db.execute(sql`delete from pg_statistic where starelid = ${qualifiedTable(t)}::regclass`)
+      measurements.push(await explain(db, opts, large, 'missing'))
+    }
+  } finally {
+    await setAutovacuum(db, opts.tables, true)
+  }
+
+  return judgeFunctionRead(name, problems, measurements, { relative, absolute }, notChecked)
+}
+
+/**
+ * The verdict on four measurements (fresh at the small history, then stale, fresh and missing at the large one)
+ * and the problems the catalog already named. Pure, so each verdict can be tested without a database.
+ */
+export function judgeFunctionRead(
+  name: string,
+  catalog: readonly string[],
+  measurements: readonly FunctionReadMeasurement[],
+  tolerance: { readonly relative: number; readonly absolute: number },
+  notChecked: readonly string[] = [],
+): FunctionReadReport {
+  const [freshSmall, stale, freshLarge, missing] = measurements as [FunctionReadMeasurement, FunctionReadMeasurement, FunctionReadMeasurement, FunctionReadMeasurement | undefined]
+  const allowed = (baseline: number): number => baseline * (1 + tolerance.relative) + tolerance.absolute
+  const problems = [...catalog]
+  const small = freshSmall.history
+  const large = freshLarge.history
+  const done = (status: FunctionReadReport['status']): FunctionReadReport => ({
+    function: name,
+    status: status === 'passed' && notChecked.length > 0 ? 'not-checked' : status,
+    problems: [...problems, ...notChecked],
+    notChecked,
+    measurements,
+  })
+
+  if (measurements.some(m => m.calledAsFunction)) {
+    if (problems.length === 0) {
+      problems.push(
+        `${name} was not inlined: the plan calls it as a function (a Function Scan), so the planner could not push the call's keys into its body. ` +
+        'Postgres inlines a function only when it is LANGUAGE sql, one SELECT, STABLE or IMMUTABLE, without SET, SECURITY DEFINER or STRICT, and (for a set) the body is a plain query.',
+      )
+    }
+    return done('failed')
+  }
+  if (freshLarge.touched === 0) {
+    if (problems.length > 0) return done('failed')
+    problems.push(`${name} was not exercised: the call touched no rows on the fixture at ${large} rows of history. Seed rows for the keys in \`args\` so the read has something to look up.`)
+    return done('not-checked')
+  }
+  if (freshLarge.touched > allowed(freshSmall.touched)) {
+    problems.push(
+      `${name} touched ${freshSmall.touched} rows at ${small} rows of history and ${freshLarge.touched} at ${large}: its rows touched grow with history, so it scans history instead of looking keys up.${where(freshLarge)}` +
+      (freshLarge.cteScan ? ' The plan has a CTE Scan: a MATERIALIZED CTE (or one used twice) is computed in full before the call\'s keys apply; use it once without MATERIALIZED, or write it as a subquery.' : '') +
+      ' Give the read an index on its key columns and filter on them in the body.',
+    )
+  }
+  for (const m of [stale, missing]) {
+    if (m !== undefined && m.touched > allowed(freshLarge.touched)) {
+      problems.push(
+        `${name} touched ${m.touched} rows with ${m.statistics} statistics against ${freshLarge.touched} after ANALYZE (at ${large} rows of history): its plan depends on the statistics being current.${where(m)} ` +
+        'Make the plan the only reasonable one: an index on the key columns, and a filter the index serves.',
+      )
+    }
+  }
+  return done(problems.length === 0 ? 'passed' : 'failed')
+}
+
+/** `checkFunctionRead`, throwing a `[pipework]` error unless the read passed; `not-checked` throws too. */
+export async function expectFunctionRead(db: PostgresJsDatabase, opts: FunctionReadOptions): Promise<FunctionReadReport> {
+  const report = await checkFunctionRead(db, opts)
+  if (report.status !== 'passed') {
+    throw new Error(`[pipework] function read ${report.function} ${report.status === 'failed' ? 'is not a key lookup' : 'was not checked'}:\n\n${report.problems.map(p => `  - ${p}`).join('\n')}\n`)
+  }
+  return report
+}

package/src/test/index.ts

@@ -17,3 +17,4 @@ export { pipework as vitestPlugin, type PipeworkVitestOptions } from './vitest-p
 export { resolveVitestConfig, resolveVitestModules } from './vitest-workspace.js'
 export { tap, type ManagedConnection, type ConnectOptions } from '../data/db/pool.js'
 export { crawlFixtureSite, type CrawlFixtureOptions, type CrawlFixtureRoute, type CrawlFixtureRequest, type CrawlFixtureSite } from './crawl-fixture.js'
+export { checkFunctionRead, expectFunctionRead, judgeFunctionRead, measurePlan, catalogProblems, type FunctionReadOptions, type FunctionReadReport, type FunctionReadMeasurement, type StatisticsState } from './function-reads.js'