pipework 0.291.0 → 0.293.0

package/src/auth/tenant/scoped-db.ts

@@ -34,6 +34,19 @@ export function unscopedExecutor(db: DB): { readonly db: DB; readonly tenant: st
   return scoped === undefined ? { db, tenant: null } : { db: scoped.raw, tenant: scoped.tenantId }
 }
 
+/**
+ * For a batch insert that writes its own SQL: runs the connection's policy for an insert into `table` (a guard,
+ * `pipe.system()` or a door refuses a tenant table exactly as `insert(table)` does) and returns the tenant column
+ * and value the rows must carry, or null when the table is not tenant-scoped or the handle has no tenant.
+ */
+export function insertTenant(db: DB, table: unknown): { readonly columnKey: string; readonly tenantId: string } | null {
+  ;(db as unknown as { insert: (t: unknown) => unknown }).insert(table)
+  const scoped = scopedHandles.get(db as object)
+  if (scoped === undefined) return null
+  const config = getScopeConfig(table as PgTable)
+  return config === null ? null : { columnKey: config.columnKey, tenantId: scoped.tenantId }
+}
+
 /** The API's name and why it cannot be confined to one tenant, for the error a scoped handle gets. */
 function refuseScopedMessage(api: string, tenant: string, reason: string): string {
   return (

package/src/core/errors/http.ts

@@ -39,10 +39,10 @@ export class CrossSiteRequestError extends PipeworkError {
   }
 }
 
-/** Where the failing input came from: the request parts a route validates, or the handler's own response. */
-export type ValidationSource = 'body' | 'query' | 'params' | 'headers' | 'response'
+/** Where the failing input came from: the request parts a route validates. */
+export type ValidationSource = 'body' | 'query' | 'params' | 'headers'
 
-/** One failed check: the path to the field (empty for the root) and the schema's message. Never the input value. */
+/** One failed check: the path to the field (empty for the root) and the schema's message. Never the value. A null source means it did not come from a request part (a hand-raised error, or a handler's reply). */
 export interface ValidationFieldIssue {
   readonly source: ValidationSource | null
   readonly path: readonly string[]
@@ -78,6 +78,21 @@ export class ValidationError extends PipeworkError {
   }
 }
 
+/**
+ * A handler's own reply failed the output schema its route declares. The fault is the server's, not the
+ * caller's: 500, never the 422 of {@link ValidationError}. Carries the failing paths, never the value.
+ */
+export class OutputValidationError extends PipeworkError {
+  readonly code = 'OUTPUT_VALIDATION_ERROR' as const
+  readonly httpStatus = 500 as const
+  readonly issues: readonly ValidationFieldIssue[]
+
+  constructor(issues: readonly ValidationFieldIssue[], message: string = 'The server\'s reply failed its declared output schema') {
+    super(message, { issues: issues.map(i => ({ path: i.path.join('.'), message: i.message })) })
+    this.issues = issues
+  }
+}
+
 export class TooManyRequestsError extends PipeworkError {
   readonly code = 'TOO_MANY_REQUESTS' as const
   readonly httpStatus = 429 as const

package/src/core/errors/index.ts

@@ -1,2 +1,2 @@
 export { PipeworkError, isPipeworkError } from './base.js'
-export { NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError, AuthConfigurationError, AuthUnavailableError, ValidationError, type ValidationSource, type ValidationFieldIssue, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './http.js'
+export { NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError, AuthConfigurationError, AuthUnavailableError, ValidationError, OutputValidationError, type ValidationSource, type ValidationFieldIssue, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './http.js'

package/src/core/errors/namespace.ts

@@ -1,4 +1,4 @@
-import { PipeworkError, NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError, AuthConfigurationError, AuthUnavailableError, ValidationError, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './index.js'
+import { PipeworkError, NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError, AuthConfigurationError, AuthUnavailableError, ValidationError, OutputValidationError, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './index.js'
 
 /** Standard error classes — all extend PipeworkError with structured error codes and actionable messages. */
 export const errors = {
@@ -18,6 +18,8 @@ export const errors = {
   AuthUnavailable: AuthUnavailableError,
   /** 422 — input validation failed, carries field-level details. */
   Validation: ValidationError,
+  /** 500 `OUTPUT_VALIDATION_ERROR` — a handler's own reply failed its declared output schema; the server's fault, not the caller's. */
+  OutputValidation: OutputValidationError,
   /** 409 — resource state conflict (duplicate, version mismatch). */
   Conflict: ConflictError,
   /** 429 — too many attempts; carries `retryAfterSeconds`, sent in both the `Retry-After` header and the body's `error.retryAfterSeconds`. */

package/src/data/db/namespace.ts

@@ -11,7 +11,7 @@ import { bulkSet } from './bulk-set.js'
 import { values } from './values.js'
 import { rows } from './rows.js'
 import { fn } from './function-source.js'
-import { update, insert, remove, upsert } from '../write/index.js'
+import { update, updateEach, insert, remove, upsert } from '../write/index.js'
 
 import { aliasedRelation, aliasedTable, aliasedTableColumn, getTableColumns, getTableName, getViewName, getViewSelectedFields, isTable, createMany, createOne, relations } from '../query/index.js'
 
@@ -102,7 +102,9 @@ export const pipe = Object.assign(getDb, {
 
   /** Pipework-owned UPDATE builder — the only consumer-facing way to update pipework-managed tables (Q8). */
   update,
-  /** Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction. */
+  /** One UPDATE for many keys, returning how many rows each key updated (in input order); refuses, naming the key, when a key does not match exactly one row — `pipe.updateEach(t, { keys: { id: 'uuid', n: 'int' }, data: { id, n }, where: k => eq(t.id, k.id), set: k => ({ n: k.n }) })`. In the caller's transaction, audited as `pipe.update`. */
+  updateEach,
+  /** Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction; `.batch(rows)` sends every row as one statement instead, arrays and NULLs included. */
   insert,
   /** Pipework-owned DELETE builder — the only consumer-facing way to delete from pipework-managed tables (Q8). */
   delete: remove,

package/src/data/db/rows.ts

@@ -49,7 +49,7 @@ function quote(name: string): string {
 // One column as a Postgres array literal, sent as a single text parameter and cast to `T[]`. postgres.js
 // serialises a JS array only for the few element types it knows (text, int, uuid ...), so a `timestamptz[]`
 // parameter would throw; a literal string is parsed by Postgres for any type.
-function arrayLiteral(cells: readonly unknown[]): string {
+export function arrayLiteral(cells: readonly unknown[]): string {
   const item = (v: unknown): string => {
     if (v === null || v === undefined) return 'NULL'
     const text = v instanceof Date ? v.toISOString()

package/src/data/schema/parse.ts

@@ -1,5 +1,5 @@
 import type { z } from 'zod/v4'
-import { ValidationError, type ValidationSource } from '../../core/errors/index.js'
+import { ValidationError, OutputValidationError, type ValidationSource } from '../../core/errors/index.js'
 
 export function parse<T extends z.ZodType>(schema: T, data: unknown, source?: ValidationSource): z.infer<T> {
   const result = schema.safeParse(data)
@@ -16,7 +16,42 @@ export function parse<T extends z.ZodType>(schema: T, data: unknown, source?: Va
 
   throw source === undefined
     ? new ValidationError(fieldErrors)
-    : new ValidationError(fieldErrors, undefined, { source, paths: result.error.issues.map(i => ({ path: i.path.map(String), message: i.message })) })
+    : new ValidationError(fieldErrors, undefined, { source, paths: issuesOf(result.error.issues, false) })
+}
+
+/** Parses a handler's reply against its declared output schema; a failure is the server's (500), carrying paths and messages, never the value. */
+export function parseOutput<T extends z.ZodType>(schema: T, data: unknown): z.infer<T> {
+  const result = schema.safeParse(data)
+  if (result.success) return result.data
+  throw new OutputValidationError(issuesOf(result.error.issues, true).map(i => ({ source: null, ...i })))
+}
+
+type FlatIssue = { path: string[]; message: string }
+
+/**
+ * The one mapping from zod issues to `{ path, message }` (never the value). With `flattenUnions`, a union
+ * failure (one issue at the union's own path) is replaced by its branches' issues (nested `errors`), each with
+ * the union's path prefixed, and exact duplicates (same path and message) are dropped, first seen kept.
+ */
+function issuesOf(issues: ReadonlyArray<z.core.$ZodIssue>, flattenUnions: boolean, prefix: readonly string[] = []): FlatIssue[] {
+  if (!flattenUnions) return issues.map(i => ({ path: i.path.map(String), message: i.message }))
+  const seen = new Set<string>()
+  return flattenBranches(issues, prefix).filter(i => {
+    const key = `${i.path.join('.')}\u0000${i.message}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+function flattenBranches(issues: ReadonlyArray<z.core.$ZodIssue>, prefix: readonly string[]): FlatIssue[] {
+  return issues.flatMap(i => {
+    const path = [...prefix, ...i.path.map(String)]
+    if (i.code === 'invalid_union' && i.errors.some(branch => branch.length > 0)) {
+      return i.errors.flatMap(branch => flattenBranches(branch, path))
+    }
+    return [{ path, message: i.message }]
+  })
 }
 
 export function tryParse<T extends z.ZodType>(

package/src/data/write/audit/verb-insert.ts

@@ -9,6 +9,7 @@ import { buildAuditInserts, buildEntityIdExpr, type AuditSelectContext } from '.
 import { AUDIT_COLUMNS_SQL } from './audit-columns.js'
 import { buildFinalSelect } from './final-select.js'
 import { applyOnConflict } from '../conflict.js'
+import { batchInsertSql } from '../batch-insert.js'
 import type { SQL } from '../../db/types.js'
 import type { WriteState } from '../state.js'
 
@@ -19,7 +20,9 @@ export function compileInsertAudit(db: AnyDb, state: WriteState, ctx: AuditSelec
   // `.getSQL()` strips the auto-paren drizzle adds around SQLWrapper builders
   // when they are templated — we add explicit parens at the CTE boundary so
   // the WITH clause keeps a uniform shape across verbs.
-  const inner = applyOnConflict(db.insert(state.table).values(state.values ?? []), state).returning().getSQL()
+  const inner = state.batch === true
+    ? sql`${batchInsertSql(state)} RETURNING *`
+    : applyOnConflict(db.insert(state.table).values(state.values ?? []), state).returning().getSQL()
   const after = buildTraceSafeProjection(state.table, 'inserted') ?? sql`NULL::jsonb`
   const auditSelect = buildAuditInserts(ctx, sql`FROM inserted`, buildEntityIdExpr(state.table, 'inserted'), sql`NULL::jsonb`, after)
   const finalSelect = buildFinalSelect(state, 'inserted')

package/src/data/write/audit/verb-update.ts

@@ -7,6 +7,7 @@
 // zero rows from `before`, suppressing the audit insert.
 
 import { sql } from '../../db/sql.js'
+import { getTableColumns } from '../../query/index.js'
 import { quoteIdentifier } from '../../db/identifiers.js'
 import { camelToSnake } from '../../domain/naming.js'
 import { buildTraceSafeProjection } from './projection.js'
@@ -26,11 +27,20 @@ export function compileUpdateAudit(db: AnyDb, state: WriteState, ctx: AuditSelec
   // `.getSQL()` strips the auto-paren drizzle adds around SQLWrapper builders
   // when they are templated — we add explicit parens at the CTE boundary so
   // the WITH clause keeps a uniform shape across verbs.
+  const each = state.each
   let updateChain = db.update(state.table).set(set)
+  if (each !== undefined) updateChain = updateChain.from(each.source)
   if (state.where !== undefined) updateChain = updateChain.where(state.where)
-  const updateInner = updateChain.returning().getSQL()
+  // An update for many keys also returns the index of the key each row matched, to count rows per key.
+  const updateInner = (each === undefined
+    ? updateChain.returning()
+    : updateChain.returning({ ...(getTableColumns(state.table as never) as Record<string, unknown>), __i: each.ordinal.as('__i') })).getSQL()
 
-  let beforeChain = db.select().from(state.table)
+  // Over many keys a row can match several of them; it is snapshotted once, as the update changes it once.
+  let beforeChain = each === undefined
+    ? db.select().from(state.table)
+    : db.selectDistinctOn(pk.map(k => (state.table as unknown as Record<string, unknown>)[k]), getTableColumns(state.table as never))
+      .from(state.table).crossJoin(each.source)
   if (state.where !== undefined) beforeChain = beforeChain.where(state.where)
   const beforeInner = beforeChain.getSQL()
 
@@ -45,7 +55,7 @@ export function compileUpdateAudit(db: AnyDb, state: WriteState, ctx: AuditSelec
   const after = buildTraceSafeProjection(state.table, 'updated') ?? sql`NULL::jsonb`
   const fromClause = sql.raw(`FROM updated JOIN before ON ${joinOn}`)
   const auditSelect = buildAuditInserts(ctx, fromClause, buildEntityIdExpr(state.table, 'updated'), before, after)
-  const finalSelect = buildFinalSelect(state, 'updated')
+  const finalSelect = each === undefined ? buildFinalSelect(state, 'updated') : sql.raw('SELECT "__i" FROM updated')
 
   return sql`
     WITH before AS (${beforeInner}),

package/src/data/write/batch-insert.ts

@@ -0,0 +1,179 @@
+// `pipe.insert(table).batch(rows)`: many rows as ONE statement, whatever the row count.
+//
+//   INSERT INTO "t" ("a", "b") SELECT "batch"."a"::uuid, "batch"."b"::text[] FROM unnest($1::text[], $2::text[]) AS "batch"("a", "b")
+//
+// Each column travels as one text-array parameter holding the cells exactly as the column's own driver
+// encoding (`mapToDriverValue`) would send them for a single-row insert, and is cast back to the column's SQL
+// type in the SELECT. Two parameters per two columns, not one per cell, so the row count never reaches
+// Postgres's parameter limit; and because the cast happens per cell, an array column (any dimension) needs no
+// `unnest` of its own, which would flatten it. It is plain INSERT ... SELECT, so RLS insert policies, `ON CONFLICT`,
+// `RETURNING` and the audit CTE all apply as they do to a `values()` insert (`COPY FROM` does none of these: see REFERENCE.md).
+
+import { getTableColumns, is, SQL as SQLClass } from '../query/index.js'
+import { getTableConfig } from '../query/pg-core/index.js'
+import type { PgTable } from '../query/pg-core/index.js'
+import { sql } from '../db/sql.js'
+import type { SQL } from '../db/types.js'
+import { arrayLiteral } from '../db/rows.js'
+import { insertTenant } from '../../auth/tenant/scoped-db.js'
+import type { WriteState } from './state.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's column type is deeply generic; only the members read below are used
+type AnyColumn = any
+
+const SQL_TYPE = /^[A-Za-z_"][A-Za-z0-9_". ]*(\([0-9, ]+\))?(\[[0-9]*\])*$/
+const SERIAL_AS: Record<string, string> = { serial: 'integer', bigserial: 'bigint', smallserial: 'smallint' }
+
+function fail(problem: string, fix: string): never {
+  throw new Error(`[pipework] pipe.insert().batch(): ${problem}\n\n  Fix: ${fix}\n`)
+}
+
+function quote(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+/** The table's name as SQL: schema-qualified when it has a schema. */
+export function qualifiedName(table: PgTable): string {
+  const config = getTableConfig(table)
+  return config.schema === undefined ? quote(config.name) : `${quote(config.schema)}.${quote(config.name)}`
+}
+
+/**
+ * The state with the tenant column set on every row when the connection is tenant-scoped (a row naming another
+ * tenant throws, as `values()` does). Also runs the connection's insert policy, so a guard refuses a tenant table.
+ */
+export function scopeBatchRows(state: WriteState, db: unknown): WriteState {
+  const tenant = insertTenant(db as never, state.table)
+  if (tenant === null || state.values === undefined) return state
+  const { columnKey, tenantId } = tenant
+  const values = state.values.map(row => {
+    const existing = row[columnKey]
+    if (existing !== undefined && existing !== tenantId) {
+      throw new Error(
+        `[pipework] Tenant-scoped insert: value has ${columnKey} "${String(existing)}" ` +
+        `but the current context tenant is "${tenantId}".\n\n` +
+        `  Remove the explicit ${columnKey} from your insert values — it's set automatically.\n` +
+        '  If you need cross-tenant writes, file an issue on the pipework repo.\n',
+      )
+    }
+    return { ...row, [columnKey]: tenantId }
+  })
+  return { ...state, values }
+}
+
+function cellText(column: AnyColumn, key: string, index: number, value: unknown): string | null {
+  if (value === null) return null
+  if (is(value, SQLClass)) {
+    fail(`row ${String(index)} sets "${key}" to a sql expression.`, 'a batch carries values only; use pipe.insert().values() for a row that needs an expression.')
+  }
+  const driver: unknown = column.mapToDriverValue(value)
+  if (driver === null || driver === undefined) return null
+  if (typeof driver === 'string') return driver
+  if (typeof driver === 'number' || typeof driver === 'bigint' || typeof driver === 'boolean') return String(driver)
+  if (driver instanceof Date) return driver.toISOString()
+  if (driver instanceof Uint8Array) return `\\x${Buffer.from(driver).toString('hex')}`
+  return JSON.stringify(driver)
+}
+
+/**
+ * When a batch is split: the library sends at most this many rows, and at most this many bytes of parameter
+ * text, per statement, several in order in one transaction. Measured on the test cluster, 139,000 rows of a
+ * uuid, a text, an int and a text[] were one statement of 19 MB of parameters in 2.4 s; the bounds sit well
+ * above that and well under Postgres's 1 GB cap on a single parameter. Mutable so tests can shrink them.
+ */
+export const batchLimits = { rows: 250_000, bytes: 256 * 1024 * 1024 }
+
+export interface BatchColumn { readonly key: string; readonly name: string; readonly type: string; readonly cells: (string | null)[] }
+
+export function encode(state: WriteState): BatchColumn[] {
+  const rows = state.values ?? []
+  const columns = getTableColumns(state.table as unknown as PgTable) as Record<string, AnyColumn>
+  for (let i = 0; i < rows.length; i++) {
+    for (const key of Object.keys(rows[i]!)) {
+      if (columns[key] === undefined) {
+        fail(`row ${String(i)} has "${key}", which is not a field of "${state.table.$name}".`, `use the table's field keys: ${Object.keys(columns).join(', ')}.`)
+      }
+    }
+  }
+  const out: BatchColumn[] = []
+  for (const [key, column] of Object.entries(columns)) {
+    if (column.shouldDisableInsert() === true) continue
+    const given = rows.map(row => row[key])
+    const supplied = given.filter(v => v !== undefined).length
+    // A JS-side default (`$defaultFn`, `$onUpdateFn`) fills an omitted cell as `values()` does.
+    const jsDefault = column.defaultFn ?? (column.default === undefined || column.default === null ? column.onUpdateFn : undefined)
+    if (supplied === 0 && jsDefault === undefined) continue
+    if (supplied > 0 && supplied < rows.length && jsDefault === undefined) {
+      const missing = given.findIndex(v => v === undefined)
+      fail(
+        `row ${String(missing)} omits "${key}" while ${String(supplied)} of ${String(rows.length)} rows set it.`,
+        `a batch is one statement, so every row names the same columns: pass null for NULL, a value for each row, or omit "${key}" from all of them (its column default applies).`,
+      )
+    }
+    const cells = given.map((v, i) => {
+      if (v !== undefined) return cellText(column, key, i, v)
+      return cellText(column, key, i, (jsDefault as () => unknown)())
+    })
+    const raw = String(column.getSQLType())
+    const type = SERIAL_AS[raw] ?? raw
+    if (!SQL_TYPE.test(type)) fail(`column "${key}" has the SQL type "${type}", which a batch cannot cast to.`, 'use pipe.insert().values() for this table.')
+    out.push({ key, name: String(column.name), type, cells })
+  }
+  if (out.length === 0) fail('no row sets a column.', 'give at least one column a value in some row, or a column with a JS-side default.')
+  return out
+}
+
+/**
+ * The statements a batch is sent as: the whole list in one when it fits `batchLimits`, otherwise consecutive
+ * slices (each slice's rows, in input order) that each fit. Every slice carries its already-encoded columns.
+ */
+export function planBatch(state: WriteState): WriteState[] {
+  const rows = state.values ?? []
+  const columns = encode(state)
+  const slices: [number, number][] = []
+  let from = 0
+  let bytes = 0
+  for (let i = 0; i < rows.length; i++) {
+    let rowBytes = 0
+    for (const c of columns) rowBytes += c.cells[i] === null ? 0 : Buffer.byteLength(c.cells[i]!)
+    if (i > from && (i - from >= batchLimits.rows || bytes + rowBytes > batchLimits.bytes)) {
+      slices.push([from, i])
+      from = i
+      bytes = 0
+    }
+    bytes += rowBytes
+  }
+  slices.push([from, rows.length])
+  if (slices.length === 1) return [{ ...state, encoded: columns }]
+  return slices.map(([a, b]) => ({
+    ...state,
+    values: rows.slice(a, b),
+    encoded: columns.map(c => ({ ...c, cells: c.cells.slice(a, b) })),
+  }))
+}
+
+/** Row i of the result is row i of `state.values`; the statement is `INSERT ... SELECT FROM unnest(...)` with the state's `ON CONFLICT` clause, no RETURNING. */
+export function batchInsertSql(state: WriteState): SQL {
+  const columns = (state.encoded as BatchColumn[] | undefined) ?? encode(state)
+  const table = state.table as unknown as PgTable
+  const names = columns.map(c => quote(c.name))
+  const arrays = columns.map(c => sql`${sql.param(arrayLiteral(c.cells))}::text[]`)
+  const picked = columns.map(c => `"batch".${quote(c.name)}::${c.type}`)
+  let conflict = sql.raw('')
+  if (state.onConflict !== undefined) {
+    const target = state.onConflict.target
+    if (target === undefined) {
+      conflict = sql` ON CONFLICT DO NOTHING`
+    } else {
+      const cols = getTableColumns(table) as Record<string, AnyColumn>
+      const list = target.map(k => {
+        if (cols[k] === undefined) {
+          throw new Error(`pipe.insert: onConflictDoNothing target "${k}" is not a field of "${state.table.$name}". Use a field key declared on the table.`)
+        }
+        return quote(String(cols[k].name))
+      })
+      conflict = sql` ON CONFLICT (${sql.raw(list.join(', '))}) DO NOTHING`
+    }
+  }
+  return sql`INSERT INTO ${sql.raw(qualifiedName(table))} (${sql.raw(names.join(', '))}) SELECT ${sql.raw(picked.join(', '))} FROM unnest(${sql.join(arrays, sql`, `)}) AS "batch"(${sql.raw(names.join(', '))})${conflict}`
+}

package/src/data/write/execute.ts

@@ -26,9 +26,17 @@ import { resolveActorId } from './audit/actor.js'
 import type { AuditSelectContext } from './audit/audit-select.js'
 import { rowsPerStatement } from '../db/insert-split.js'
 import { applyOnConflict, reportSkipped } from './conflict.js'
+import { batchInsertSql, planBatch, scopeBatchRows } from './batch-insert.js'
+import { buildFinalSelect } from './audit/final-select.js'
+import { sql } from '../db/sql.js'
 
-export async function executeWrite(state: WriteState): Promise<unknown> {
-  const db = pipe(state.table.$options.database)
+export async function executeWrite(input: WriteState): Promise<unknown> {
+  const db = pipe(input.table.$options.database)
+  // A batch carries the tenant on its rows before the audit and vanilla paths read them.
+  const state = input.batch === true ? scopeBatchRows(input, db) : input
+  if (state.batch === true && (state.values === undefined || state.values.length === 0)) {
+    return state.returning === undefined || state.returning === null ? undefined : []
+  }
   const flow = getContext()
   if (flow !== undefined && flow.trace !== null) {
     const stepCtx = flow.trace.buffer.currentStep()
@@ -51,6 +59,7 @@ export async function executeWrite(state: WriteState): Promise<unknown> {
       if (chunkValueSize !== null) {
         return executeChunkedAuditWrite(state, auditCtx, chunkValueSize)
       }
+      if (state.batch === true) return executeBatchAudit(state, auditCtx)
       const stmt = compileAuditWrite(db, state, auditCtx)
       // The compiled CTE is already tenant-scoped at compile time (the user
       // write inside the CTE was built against the scoped `pipe()` DB, so it
@@ -60,10 +69,12 @@ export async function executeWrite(state: WriteState): Promise<unknown> {
       const rawDb = pipeRaw(state.table.$options.database)
       const rows = await rawDb.execute(stmt)
       for (const touch of selection.written) stepCtx.markWrote(touch)
+      if (state.each !== undefined) return tally(state.each.count, rows, '__i')
       if (state.onConflict !== undefined) reportSkipped(state, Array.isArray(rows) ? rows.length : 0)
       return decodeReturning(state, rows)
     }
   }
+  if (state.batch === true) return executeBatchInsert(state)
   if ((state.verb === 'insert' || state.verb === 'upsert') && state.values !== undefined) {
     const size = rowsPerStatement(state.table)
     if (state.values.length > size) return executeChunkedWrite(state, size)
@@ -90,6 +101,8 @@ function computeChunkValueSize(
   if (state.verb !== 'insert' && state.verb !== 'upsert') return null
   if (state.values === undefined) return null
   if (touches === 0) return null
+  // A batch is one statement by contract: its audit rows come from one INSERT ... SELECT, with no parameter per row.
+  if (state.batch === true) return null
 
   const limit = flow.instance.config.trace.auditChunkSize
   const projectedAuditRows = state.values.length * touches
@@ -176,8 +189,70 @@ type AnyDb = any
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyChain = any
 
+/** Rows per input index of a keys rowset: how many table rows each key updated. */
+function tally(count: number, rows: unknown, column: string): number[] {
+  const counts = new Array<number>(count).fill(0)
+  if (Array.isArray(rows)) for (const row of rows as Record<string, unknown>[]) counts[Number(row[column])]! += 1
+  return counts
+}
+
+/**
+ * Runs the statements of a batch plan in order. A batch over `batchLimits` is several statements, so they run in
+ * one transaction (a savepoint when nested): all of it lands or none, and each statement reads the one before.
+ */
+async function inBatches(state: WriteState, one: (chunk: WriteState) => Promise<unknown[]>): Promise<unknown[]> {
+  const plan = planBatch(state)
+  if (plan.length === 1) return one(plan[0]!)
+  const out: unknown[] = []
+  const run = async (): Promise<void> => {
+    for (const chunk of plan) for (const row of await one(chunk)) out.push(row)
+  }
+  const dbName = state.table.$options.database
+  if (dbName === undefined) await pipe.transaction(run)
+  else await pipe.transaction(dbName, run)
+  return out
+}
+
+/** `INSERT ... SELECT FROM unnest(...)`, one statement per plan slice; rows come back as `values()` returns them, in input order. */
+async function executeBatchInsert(state: WriteState): Promise<unknown> {
+  const dbName = state.table.$options.database
+  const returns = state.returning !== undefined && state.returning !== null
+  const rows = await inBatches(state, async chunk => {
+    const rawDb = pipeRaw(dbName)
+    const insertSql = batchInsertSql(chunk)
+    if (!returns && state.onConflict === undefined) {
+      await rawDb.execute(insertSql)
+      return []
+    }
+    // Under onConflictDoNothing the rows written are the rows returned, so they are asked for even when the caller did not.
+    const out = await rawDb.execute(sql`WITH inserted AS (${insertSql} RETURNING *) ${buildFinalSelect(state, 'inserted')}`)
+    return Array.isArray(out) ? [...out] : []
+  })
+  if (state.onConflict !== undefined) reportSkipped(state, rows.length)
+  if (!returns) return state.onConflict === undefined ? undefined : []
+  return decodeReturning(state, rows)
+}
+
+/** The write-and-audit statement, one per plan slice, in one transaction when there are several; each slice's audit rows land with its rows. */
+async function executeBatchAudit(state: WriteState, ctx: AuditSelectContext): Promise<unknown> {
+  const dbName = state.table.$options.database
+  const rows = await inBatches(state, async chunk => {
+    const stmt = compileAuditWrite(pipe(dbName), chunk, ctx)
+    const out = await pipeRaw(dbName).execute(stmt)
+    return Array.isArray(out) ? [...out] : []
+  })
+  for (const touch of ctx.written) ctx.step.markWrote(touch)
+  if (state.onConflict !== undefined) reportSkipped(state, rows.length)
+  return decodeReturning(state, rows)
+}
+
 async function executeUpdate(db: AnyDb, state: WriteState): Promise<unknown> {
   let q: AnyChain = db.update(state.table).set(state.set ?? {})
+  if (state.each !== undefined) {
+    q = q.from(state.each.source)
+    if (state.where !== undefined) q = q.where(state.where)
+    return tally(state.each.count, await q.returning({ i: state.each.ordinal }), 'i')
+  }
   if (state.where !== undefined) q = q.where(state.where)
   return runWithReturning(q, state.returning)
 }

package/src/data/write/index.ts

@@ -9,3 +9,5 @@ export { insert, InsertBuilder } from './insert.js'
 export { remove, DeleteBuilder } from './delete.js'
 export { upsert, UpsertBuilder } from './upsert.js'
 export type { WriteState, WriteVerb, ReturningShape } from './state.js'
+export { updateEach } from './update-each.js'
+export type { UpdateEachOptions } from './update-each.js'

package/src/data/write/insert.ts

@@ -19,6 +19,21 @@ export class InsertBuilder<T extends PgTable, TResult = unknown> implements Prom
     })
   }
 
+  /**
+   * Sends the rows as ONE statement up to 250,000 rows or 256 MiB of parameter text, then as consecutive statements of that size in one transaction (the library splits, never the caller): each column travels as a single array parameter
+   * (so no parameter limit and no chunking) and is cast back per cell, which carries array columns, NULLs and
+   * every type `values()` carries, encoded as `values()` would. Every row must name the same columns; a column
+   * no row names takes its default. Composes with `onConflictDoNothing()` and `returning()`; the rows come back in
+   * input order. Runs under RLS insert policies and audits as `values()` does, in the caller's transaction.
+   */
+  batch(rows: ReadonlyArray<InsertValues<T>>): InsertBuilder<T, TResult> {
+    return new InsertBuilder<T, TResult>({
+      ...this.state,
+      batch: true,
+      values: rows as ReadonlyArray<Record<string, unknown>>,
+    })
+  }
+
   /**
    * Leaves a row that conflicts with an existing one and inserts the rest.
    * Without `target`, any unique or exclusion constraint conflict is skipped.

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
 }