@workerstack/database 0.22.0 → 0.23.0

package/src/migrate/core/proof-scope.ts

@@ -3,15 +3,17 @@
  * can observe, created, and the tables whose rows they can observe, seeded, so the copy refuses what the whole
  * schema would and costs what the files reach.
  *
- * - An object's references are every name its text spells (sql-code's lexer, compared folded, never as a substring)
- *   and, for a virtual table, each string and quoted name among its module's arguments, whole. A table's FK parents
- *   are the other tables it references; a reader is a view, a trigger or a virtual table, and reads what it references.
+ * - An object's references are every name its text spells where SQLite's grammar takes a name (sql-code's lexer,
+ *   compared folded, never as a substring: the `TABLE` of `CREATE TABLE` is no name) and, for a virtual table, each
+ *   word, string and quoted name among its module's arguments, whole. A table's FK parents are the other tables it
+ *   references; a reader is a view, a trigger or a virtual table, and reads what it references.
  * - N: each live object whose name a file spells, and the history table; S is N's tables, which a file creates,
  *   alters, drops, renames or writes.
  * - Rows go to S, each table a reader reached from S references (to a fixpoint), D (their FK descendants: a cascade
  *   reaches them) and A (the FK ancestors of all those: their keys must be met).
  * - The copy creates N, the seeded tables, and each reader that references an S table (SQLite checks views and
- *   triggers on DROP COLUMN and RENAME COLUMN, and a rename rewrites them). Then to a fixpoint each index and trigger
+ *   triggers on DROP COLUMN and RENAME COLUMN, and a rename rewrites them) or a view of N (a file that drops the
+ *   view leaves the reader unable to run, which the proof compiles it to see). Then to a fixpoint each index and trigger
  *   on a created table or view (a view's INSTEAD OF triggers carry out a write through it), each table and view a
  *   created reader references, and each created table's FK ancestors, which a write to it compiles checks against.
  * - Reflection reads the schema itself: a name with SQLite's reserved `sqlite_` prefix (its catalogs, sqlite_sequence,
@@ -66,24 +68,31 @@ const nameOf = ({ kind, text }: Token): string =>
 	asciiFold(kind === "literal" ? text.slice(1, -1).replaceAll("''", "'") : unquote(text))
 
 /**
- * Virtual table `object`'s module, the name after USING however it is written, and each string and quoted name among
- * the module's arguments, which the module may read as a table's name (fts5vocab, content=)
+ * Virtual table `object`'s module, the name after USING however it is written, each string and quoted name among
+ * the module's arguments, which the module may read as a table's name (fts5vocab, content=), and each bare word there
  */
-function virtualOf(object: LiveObject): { args: string[]; module: string } | undefined {
+function virtualOf(object: LiveObject): { args: string[]; module: string; words: string[] } | undefined {
 	if (!isVirtual(object)) return undefined
 	const tokens = tokensOf(object.sql)
 	const at = tokens.findIndex(({ kind, text }) => kind === "code" && /^using$/i.test(text)) + 1
-	const args = tokens[at + 1]?.text === "(" ? tokens.slice(at + 2).filter(({ kind }) => kind !== "code") : []
-	return { args: args.map(nameOf), module: nameOf(tokens[at] as Token) }
+	const inside = tokens[at + 1]?.text === "(" ? tokens.slice(at + 2) : []
+	return {
+		args: inside.filter(({ kind }) => kind !== "code").map(nameOf),
+		module: nameOf(tokens[at] as Token),
+		words: inside.filter(({ kind, text }) => kind === "code" && /^[A-Za-z_\u0080-\uffff]/.test(text)).map(nameOf),
+	}
 }
 
 /** The folded names of the shadow tables virtual table `object`'s module makes */
 const shadowsOf = (object: LiveObject): string[] =>
 	(SHADOWS[virtualOf(object)?.module as string] ?? []).map((suffix) => asciiFold(`${object.name}_${suffix}`))
 
-/** Every name `object` references, folded (see the module's comment) */
+/**
+ * Every name `object` references, folded (see the module's comment). A virtual table's module reads its own arguments,
+ * not SQL, so each bare word among them may name a table, `group` in `content=group` among them
+ */
 const referencesOf = (object: LiveObject): Set<string> =>
-	new Set([...sqliteNames(object.sql), ...(virtualOf(object)?.args ?? [])])
+	new Set([...sqliteNames(object.sql), ...(virtualOf(object)?.args ?? []), ...(virtualOf(object)?.words ?? [])])
 
 /* a name SQLite reserves for its own tables, or a pragma's table-valued function: either reads the schema itself */
 const REFLECTION = /^(?:sqlite_|pragma_)/
@@ -216,9 +225,13 @@ function observable(
 	const statements = files.flatMap(({ sql }) => splitSqlStatements(sql))
 	const checks = objects.filter((object) => object.type === "view" || object.type === "trigger")
 	/* a rename rewrites the text of each view and trigger naming an S table, and D1 then compiles the writes to its
-	   table; a virtual table reading one reads the rows a file writes */
+	   table; a virtual table reading one reads the rows a file writes; a drop of a view of N breaks each reading it */
+	const reached = new Set([
+		...s,
+		...n.filter((object) => object.type === "view").map((object) => asciiFold(object.name)),
+	])
 	const rewritten = objects.filter(
-		(object) => isReader(object) && [...(graph.names.get(object) as Set<string>)].some((name) => s.has(name)),
+		(object) => isReader(object) && [...(graph.names.get(object) as Set<string>)].some((name) => reached.has(name)),
 	)
 	/* a write to a created table compiles its keys' checks, which need each parent table */
 	let made = forward(graph, [...n, ...objectsOf(graph, seeded), ...rewritten])
@@ -240,4 +253,4 @@ function observable(
 	return { objects: kept, seeded }
 }
 
-export { isVirtual, observable, type Scope, shadowsOf, virtualOf }
+export { isVirtual, observable, referencesOf, type Scope, shadowsOf, virtualOf }

package/src/migrate/core/sql-code.ts

@@ -4,7 +4,8 @@
  * an action list splits only at its top-level commas.
  */
 import type { Dialect } from "../types.ts"
-import { bodyText, joined, segments } from "../../sql-lexer.ts"
+import { bodyText, segments } from "../../sql-lexer.ts"
+import { NEVER_NAMES } from "./sqlite-keywords.ts"
 
 /** One name part: double-quoted, backtick or bracket quoted, or bare */
 const IDENT: string = `(?:"(?:[^"]|"")*"|\`[^\`]*\`|\\[[^\\]]*\\]|[A-Za-z_\\u0080-\\uffff][\\w$\\u0080-\\uffff]*)`
@@ -100,13 +101,43 @@ function pragmaOf(code: string): Pragma | undefined {
 const qualifiedKey = (name: string): string =>
 	[...name.matchAll(PARTS)].map((match) => partKey(match[0], "sqlite")).join(".")
 
+/* the words and punctuation of SQLite code: a bare word, or one character that breaks a run of words */
+const CODE_TOKEN = /[A-Za-z_\u0080-\uffff][\w$\u0080-\uffff]*|\S/g
+
 /**
- * Every name SQLite code can spell, as SQLite resolves one: each bare word and each quoted name unquoted, and each
- * word of a string, which SQLite reads as a name where one stands (`FROM 'post'`) and a module as its option's
- * (`content='post'`), folded by asciiFold; never a word of a comment
+ * Every name SQLite code can spell, as SQLite resolves one: each quoted name unquoted, each word of a string, which
+ * SQLite reads as a name where one stands (`FROM 'post'`) and a module as its option's (`content='post'`), and each
+ * bare word that can be one, all folded by asciiFold; never a word of a comment. A bare keyword is no name
+ * where SQLite's grammar takes none: `TABLE`, `CREATE`, `NULL` and the rest of NEVER_NAMES whenever it is bare, and
+ * `KEY` after `PRIMARY` or `FOREIGN`, which no name can follow. So a table named `table` is named by `"table"` and
+ * not by the `CREATE TABLE` of every file. Any other bare word may be a name and is read as one: a name read
+ * where there is none only widens what a proof copies, a name missed would narrow it
  */
 function sqliteNames(sql: string): Set<string> {
-	return new Set([...joined(sql, "sqlite", true).matchAll(PARTS)].map((match) => partKey(match[0], "sqlite")))
+	const names = new Set<string>()
+	const quoted = (text: string) => {
+		for (const match of text.matchAll(PARTS)) names.add(partKey(match[0], "sqlite"))
+	}
+	let before: string | undefined
+	for (const { kind, text } of segments(sql, "sqlite")) {
+		if (kind === "comment") continue
+		if (kind !== "code") {
+			quoted(text)
+			before = undefined
+			continue
+		}
+		for (const [token] of text.matchAll(CODE_TOKEN)) {
+			if (!/^[A-Za-z_\u0080-\uffff]/.test(token)) {
+				before = undefined
+				continue
+			}
+			const word = asciiFold(token)
+			const keyword = NEVER_NAMES.has(word) || (word === "key" && (before === "primary" || before === "foreign"))
+			if (!keyword) names.add(word)
+			before = word
+		}
+	}
+	return names
 }
 
 /* a bare word in Postgres code, which may be a name */

package/src/migrate/core/sql-scan.ts

@@ -67,9 +67,15 @@ function readCode(reading: Reading, text: string): string[] {
 	return done
 }
 
+/* SQLITE_SPACE's whitespace at either end of a statement */
+const SQLITE_EDGE_SPACE = /^[\t\n\f\r ]+|[\t\n\f\r ]+$/g
+
 /** The statement read so far, reset for the next; empty when it held no code */
 function finish(reading: Reading): string {
-	const statement = reading.code.replace(/;/g, "").trim() === "" ? "" : reading.text.trim()
+	const statement =
+		reading.code.replace(/;/g, "").replace(SQLITE_EDGE_SPACE, "") === ""
+			? ""
+			: reading.text.replace(SQLITE_EDGE_SPACE, "")
 	reading.code = ""
 	reading.state = 0
 	reading.text = ""

package/src/migrate/core/sqlite-keywords.ts

@@ -0,0 +1,70 @@
+/**
+ * The words SQLite reads only as keywords when they stand bare in code: no table, column, index, view,
+ * trigger or alias can be named by one unless it is quoted. The other keywords (`key`, `end`, `action`, `left`,
+ * `if`) SQLite takes as a name where its grammar wants one, so a bare one may be a name and is read as one.
+ * The list is the engine's: tests/sqlite-keywords.test.ts holds every word here to SQLite's refusal as each kind of
+ * name, in node:sqlite's SQLite and libsql's. `nothing` and `returning` are left out, as an SQLite before 3.24 and
+ * 3.35 reads them as plain names.
+ */
+
+// lookup-table: the keywords no bare name can be, lower case, by the engine's own refusal
+const NEVER_NAMES: ReadonlySet<string> = /* @__PURE__ */ new Set([
+	"add",
+	"all",
+	"alter",
+	"and",
+	"as",
+	"autoincrement",
+	"between",
+	"case",
+	"check",
+	"collate",
+	"commit",
+	"constraint",
+	"create",
+	"default",
+	"deferrable",
+	"delete",
+	"distinct",
+	"drop",
+	"else",
+	"escape",
+	"except",
+	"exists",
+	"foreign",
+	"from",
+	"group",
+	"having",
+	"in",
+	"index",
+	"insert",
+	"intersect",
+	"into",
+	"is",
+	"isnull",
+	"join",
+	"limit",
+	"not",
+	"notnull",
+	"null",
+	"on",
+	"or",
+	"order",
+	"primary",
+	"references",
+	"select",
+	"set",
+	"table",
+	"then",
+	"to",
+	"transaction",
+	"union",
+	"unique",
+	"update",
+	"using",
+	"values",
+	"when",
+	"where",
+])
+
+export { NEVER_NAMES }

package/src/migrate/core/stopped.ts

@@ -0,0 +1,70 @@
+/**
+ * The one report of a run a signal stopped: which files applied and which did not, as an
+ * object both of a command's outputs render, the human line and the `--json` object. The loop that
+ * applies files holds a step for the length of its work; when a signal comes, the step reads what
+ * committed once the work in flight has ended, prints the line and returns the report, which the
+ * command's own step, held before the loop's and so run after it, reads and prints as JSON. A stop
+ * parks the loop itself (cleanup.ts pastStop), so a run it stopped never throws its own report.
+ */
+import { hold } from "./cleanup.ts"
+import { Refused } from "./refused.ts"
+
+/** The files a stop found applied by the run, and left pending */
+type Found = { applied: string[]; pending: string[] }
+
+/** A run a signal stopped: the signal, and as a Refused the files it applied, left, or may have applied */
+export class Stopped extends Refused {
+	readonly signal: NodeJS.Signals
+
+	constructor(signal: NodeJS.Signals, message: string, files: ConstructorParameters<typeof Refused>[1]) {
+		super(message, files)
+		this.name = "Stopped"
+		this.signal = signal
+	}
+}
+
+const list = (names: readonly string[]) => names.join(", ") || "none"
+
+/**
+ * The report of a run `signal` stopped, whose approved files are `names`: what `read` found, or,
+ * when it cannot read, every one of `names` as unknown, since any of them may have committed
+ */
+async function reportOf(
+	signal: NodeJS.Signals,
+	{ names, read }: { names: readonly string[]; read: () => Promise<Found> },
+): Promise<Stopped> {
+	try {
+		const { applied, pending } = await read()
+		return new Stopped(signal, `Stopped by ${signal}: applied ${list(applied)}; not applied ${list(pending)}`, {
+			applied,
+			pending,
+		})
+	} catch (error) {
+		return new Stopped(
+			signal,
+			`Stopped by ${signal}: comb could not read what was applied: ${(error as Error).message}`,
+			{ pending: [], unknown: names },
+		)
+	}
+}
+
+/**
+ * `work`, with a step held while it runs that, on a signal, says on `print` which of `names` the run
+ * applied and which it did not, as `read` finds them once the work in flight has ended (cleanup.ts
+ * runs a child's own step before this one), and returns the report. The process then ends by the signal.
+ */
+export async function whileStoppable<T>(
+	{ names, print, read }: { names: readonly string[]; print: (line: string) => void; read: () => Promise<Found> },
+	work: () => Promise<T>,
+): Promise<T> {
+	const release = hold(async (signal) => {
+		const stopped = await reportOf(signal, { names, read })
+		print(stopped.message)
+		return stopped
+	})
+	try {
+		return await work()
+	} finally {
+		release()
+	}
+}

package/src/migrate/core/trigger-write.d.mts

@@ -0,0 +1,7 @@
+/** A write a table takes */
+export type Event = "DELETE" | "INSERT" | "UPDATE"
+
+export const EVENTS: readonly ["INSERT", "UPDATE", "DELETE"]
+export function quote(name: string): string
+export function triggerEvent(sql: string): Event
+export function writeOf(table: string, event: Event, columns: readonly string[]): string

package/src/migrate/core/trigger-write.mjs

@@ -0,0 +1,42 @@
+/**
+ * The write that compiles a trigger: SQLite compiles a trigger's body into the program of each statement of its
+ * event on its table or view, so `EXPLAIN` of that statement resolves every name the body uses and every function
+ * it calls. A view takes a write only for an event an INSTEAD OF trigger on it fires on; for any other event SQLite
+ * answers "cannot modify ... because it is a view", and no program exists to fail. Plain JavaScript, shared by the
+ * D1 proof's child (d1-engine-child.mjs), which node runs untransformed, and the SQLite proof (proof-readers.ts).
+ */
+
+/** The writes a table takes, in the order the proofs compile them */
+export const EVENTS = /** @type {const} */ (["INSERT", "UPDATE", "DELETE"])
+
+/** @param {string} name */
+export const quote = (name) => `"${name.replaceAll('"', '""')}"`
+
+/* what in SQL text may spell any word: a comment, a string, a quoted name */
+const HIDDEN = /--[^\n]*|\/\*[\s\S]*?(?:\*\/|$)|'(?:[^']|'')*'|"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]*\]/g
+
+/**
+ * The event of trigger text `sql`, as sqlite_master holds it: the first bare INSERT, UPDATE or DELETE outside a
+ * comment, a string and a quoted name. CREATE TRIGGER's grammar puts the event before ON and the body, and no bare
+ * name before it can be one of those keywords
+ * @param {string} sql
+ * @returns {"DELETE" | "INSERT" | "UPDATE"}
+ */
+export function triggerEvent(sql) {
+	const event = /** @type {RegExpExecArray} */ (/\b(DELETE|INSERT|UPDATE)\b/i.exec(sql.replace(HIDDEN, " ")))
+	return /** @type {"DELETE" | "INSERT" | "UPDATE"} */ (/** @type {string} */ (event[1]).toUpperCase())
+}
+
+/**
+ * The statement of `event` on `table` that compiles each trigger it fires and each generated column it computes:
+ * an insert of defaults, an update assigning each of `columns` (the stored and virtual ones, by name) to itself, a
+ * delete
+ * @param {string} table
+ * @param {"DELETE" | "INSERT" | "UPDATE"} event
+ * @param {readonly string[]} columns
+ */
+export function writeOf(table, event, columns) {
+	if (event === "INSERT") return `INSERT INTO ${quote(table)} DEFAULT VALUES`
+	if (event === "DELETE") return `DELETE FROM ${quote(table)}`
+	return `UPDATE ${quote(table)} SET ${columns.map((column) => `${quote(column)} = ${quote(column)}`).join(", ")}`
+}

package/src/query/cursor-mint.ts

@@ -3,13 +3,12 @@
  * MAX_CURSOR_LENGTH, a value too long for it carried by reference (cursor-ref.ts) on a table's
  * list, and refused on a derived list, which no row holds to read a reference back from.
  */
-import { CombError } from "../error.ts"
-import { combErrorKeys } from "../types.ts"
 import { cursorBytes, CursorRef, MAX_CURSOR_LENGTH } from "./cursor.ts"
 import { readsApart } from "./cursor-reads.ts"
 import { type CursorOptions, seal, sealedLength } from "./cursor-seal.ts"
 import { roundedKey } from "./rounded-key.ts"
 import type { SortField } from "./types.ts"
+import { UnmintableRow } from "./cursor-refusals.ts"
 
 /**
  * The open's column check a builder hands the mint: the index of the first value, the tiebreak id last,
@@ -37,7 +36,7 @@ function longestFitting(record: Record<string, unknown>, field: string, fits: (r
 }
 
 /** The overflow, as paginate reports it on the page that met it: a 500 naming the field and the cap */
-function tooLong(fields: string, length: number, kind: KeysetKind | "unread"): CombError {
+function tooLong(fields: string, length: number, kind: KeysetKind | "unread"): UnmintableRow {
 	const reasons = {
 		derived: "a derived list reads no row to page by reference, so sort it by a key of bounded length",
 		merged:
@@ -47,11 +46,9 @@ function tooLong(fields: string, length: number, kind: KeysetKind | "unread"): C
 			"its long key is a column not of the anchor table, or an expression over one, so no reference reads its value back; sort by a key of bounded length, or by a column of the anchor table",
 	}
 	const reason = reasons[kind]
-	return new CombError({
-		cause: `a row's ${fields} is too long to page this list by: its cursor would be ${length} characters, past ${MAX_CURSOR_LENGTH}; ${reason}`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	return new UnmintableRow(
+		`a row's ${fields} is too long to page this list by: its cursor would be ${length} characters, past ${MAX_CURSOR_LENGTH}; ${reason}`,
+	)
 }
 
 /**
@@ -159,11 +156,9 @@ function refuseInvalidDate(
 		({ field }) => at.asRead(field) && row[field] instanceof Date && Number.isNaN((row[field] as Date).getTime()),
 	)
 	if (unheld === undefined) return
-	throw new CombError({
-		cause: `the sort by ${unheld.field} reads a date no JS Date holds (a Postgres 'infinity' read in date mode, or a SQLite timestamp holding ±Infinity), which this list has no row to read back by, ${at.derived ? "a derived list having none" : "its key being no column of the anchor table"}; select it in string mode or sort by another column`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	throw new UnmintableRow(
+		`the sort by ${unheld.field} reads a date no JS Date holds (a Postgres 'infinity' read in date mode, or a SQLite timestamp holding ±Infinity), which this list has no row to read back by, ${at.derived ? "a derived list having none" : "its key being no column of the anchor table"}; select it in string mode or sort by another column`,
+	)
 }
 
 /** A 500 naming the first value of `record` its column does not hold (ColumnCheck), the cursor the next page would refuse */
@@ -179,11 +174,9 @@ function refuseUnfit(
 	const index = options.holds(values, (i) => options.carried?.has(sort[i]?.field ?? "") ?? false)
 	if (index === -1) return
 	const named = sort[index] === undefined ? `the tiebreak id ${idField}` : `the sort by ${sort[index].field}`
-	throw new CombError({
-		cause: `${named} reads a value its column's mode does not hold (a JSON-mode key's, or a SQLite column's of another storage class than its mode reads), which no cursor of this list resumes after; sort by another column`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	throw new UnmintableRow(
+		`${named} reads a value its column's mode does not hold (a JSON-mode key's, or a SQLite column's of another storage class than its mode reads), which no cursor of this list resumes after; sort by another column`,
+	)
 }
 
 export { type ColumnCheck, createCursor, fitCursor, fittedCursor, type KeysetKind }

package/src/query/cursor-refusals.ts

@@ -1,12 +1,26 @@
 /**
  * What no cursor resumes after, refused by name when a cursor is minted: a computed sort, a tiebreak
  * id a JS number rounds, and a row without a sort value or its id, or with one no cursor carries.
+ * UnmintableRow tells a refusal of a row's own value from one of the list's wiring.
  */
 import { CombError } from "../error.ts"
 import { combErrorKeys } from "../types.ts"
 import { carried, decodeId, decodeValue } from "./cursor-codec.ts"
 import type { SortField } from "./types.ts"
 
+/**
+ * A 500 naming a row's value no cursor holds: a key too long for the cap, an Invalid Date or a rounded
+ * number as read, a value the cursor would not read back as itself, a class its column's mode reads as
+ * another. A page by cursor answers it on the page that serves the row; a page by number serves the row
+ * and, when its next cursor would be minted from it, answers `nextCursor: null` with `hasMore` still
+ * true. Any other mint refusal is the list's wiring or config, and every page answers it
+ */
+class UnmintableRow extends CombError {
+	constructor(cause: string) {
+		super({ cause, errorKey: combErrorKeys.SORT_NOT_WIRED, status: "internal_server_error" })
+	}
+}
+
 /** Whether `value` is an integer a JS number rounds: past ±(2^53 − 1), a lossy read of the row's key */
 const lossy = (value: unknown): value is number =>
 	typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value)
@@ -17,6 +31,7 @@ const lossy = (value: unknown): value is number =>
  */
 function refuseRoundedId(record: Record<string, unknown>, idField: string): void {
 	if (!lossy(record[idField])) return
+	/* the tiebreak column's read mode, which every row of the list shares, and the row's own identity: no page serves it */
 	throw new CombError({
 		cause: `the tiebreak id ${idField} reads ${String(record[idField])}, past 2^53, where a JS number rounds it, so no cursor can find its row; read it exactly (bun:sqlite safeIntegers, libsql intMode: "bigint", drizzle's mode: "bigint" on Postgres), or on D1 key the table by a text id`,
 		errorKey: combErrorKeys.SORT_NOT_WIRED,
@@ -71,18 +86,14 @@ function refuseUncarried(record: Record<string, unknown>, parsedSort: readonly S
 	}
 	const key = parsedSort.find(({ field }) => !carried(record[field], decodeValue))
 	if (key !== undefined) {
-		throw new CombError({
-			cause: `the sort by ${key.field} reads ${kindOf(record[key.field])}, which no cursor carries: sort by a column of text, numbers, booleans, times or bytes`,
-			errorKey: combErrorKeys.SORT_NOT_WIRED,
-			status: "internal_server_error",
-		})
+		throw new UnmintableRow(
+			`the sort by ${key.field} reads ${kindOf(record[key.field])}, which no cursor carries: sort by a column of text, numbers, booleans, times or bytes`,
+		)
 	}
 	if (carried(record[idField], decodeId)) return
-	throw new CombError({
-		cause: `the tiebreak id ${idField} reads ${kindOf(record[idField])}, which no cursor carries: key the table by text or an integer`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	throw new UnmintableRow(
+		`the tiebreak id ${idField} reads ${kindOf(record[idField])}, which no cursor carries: key the table by text or an integer`,
+	)
 }
 
-export { lossy, NO_KEYSET_CAUSE, refuseComputedSort, refuseRoundedId, refuseUncarried }
+export { lossy, NO_KEYSET_CAUSE, refuseComputedSort, refuseRoundedId, refuseUncarried, UnmintableRow }

package/src/query/descriptions.ts

@@ -7,7 +7,7 @@
  * same config that validates the request, so the text cannot drift from what
  * the parser accepts — and stays when a publisher strips `x-*` extensions.
  */
-import type { FilterLimits } from "./filter.ts"
+import { type FilterLimits, orderPattern } from "./filter.ts"
 import { REQUEST_BYTES } from "./schema-limits.ts"
 import type { FieldsConfig } from "./schema-types.ts"
 import type { FieldType, FilterOperator } from "./types.ts"
@@ -133,10 +133,6 @@ function filterParamMeta(
 	return { description, examples: [...examples] }
 }
 
-function escapeRegExp(value: string): string {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-}
-
 /** The `order` param's OpenAPI text over the sortable fields in `sort`, the first of which is the default, descending */
 function orderParamMeta(
 	sort: readonly string[],
@@ -146,18 +142,17 @@ function orderParamMeta(
 	pattern: string
 } {
 	const [first = "", second] = sort
-	const entry = `(?:${sort.map(escapeRegExp).join("|")})(?:\\.(?:asc|desc))?(?:\\.(?:nullsfirst|nullslast))?`
 	return {
 		description: [
-			`Sort keys, comma-separated, each \`field[.asc|.desc][.nullsfirst|.nullslast]\`; at most ${maxSortKeys}.`,
-			`Sortable: ${sort.join(", ")}. Default: ${first}.desc.`,
+			`Sort keys, comma-separated, each \`field[.asc|.desc][.nullsfirst|.nullslast]\` and each field at most once; at most ${maxSortKeys}.`,
+			`Sortable: ${sort.join(", ")}. Default, when absent or empty: ${first}.desc.`,
 			"Nulls sort last ascending and first descending unless stated.",
 		].join(" "),
 		/* a second key only where the endpoint takes two */
 		examples: second
 			? [`${first}.desc`, maxSortKeys > 1 ? `${second}.asc,${first}.desc` : `${second}.asc`]
 			: [`${first}.desc`, `${first}.asc`],
-		pattern: `^${entry}(?:,${entry}){0,${Math.max(0, maxSortKeys - 1)}}$`,
+		pattern: orderPattern(sort, maxSortKeys),
 	}
 }