@workerstack/database 0.22.0 → 0.22.1

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),
 	}
 }
 

package/src/query/filter-parse.ts

@@ -4,7 +4,7 @@
  *
  * - `field.op.value`: one condition; `,` joins conditions with AND
  * - `or(...)`, `and(...)`: groups, nestable
- * - `in.(a,b)`, `nin.(a,b)`: lists
+ * - `in.(a,b)`, `nin.(a,b)`: lists; `in.()` is the one empty list, and a comma beside no member is malformed
  * - `"..."`: a quoted value may hold `,` `(` `)` and `.`; `\"` and `\\` escape inside it
  * - `@name`: a computed field
  */
@@ -31,34 +31,66 @@ const FILTER_OPERATORS: readonly [FilterOperator, ...FilterOperator[]] = [
 /** An operator and the `.` after it; longest first, so `neq.` is not read as `ne` then `q.` */
 const OPERATOR_PATTERN = /^(contains|ilike|like|neq|gte|lte|nin|eq|ne|gt|lt|in|is)\./
 
+/** What a refused filter is told: this alone when no more is known, else this and the reason */
+const SYNTAX = "Invalid filter syntax"
+
+/**
+ * The deepest nesting the parser reads, whatever cap a caller sets: it descends one call per group,
+ * so a bound keeps a deep filter a refusal instead of a stack overflow on every runtime comb runs on
+ */
+const FILTER_MAX_DEPTH = 256
+
 class FilterParser {
 	private pos = 0
-	private malformed = false
+	/** Why the input is untrustworthy, the first reason met; null while every term parsed */
+	private failure: string | null = null
 	private readonly input: string
+	/** Whitespace the caller's string held before the input: positions are told in the caller's string */
+	private readonly offset: number
+	/** The deepest group the input may open, the top level being 0 */
+	private readonly maxDepth: number
 
-	constructor(input: string) {
+	constructor(input: string, offset: number, maxDepth: number) {
 		this.input = input
+		this.offset = offset
+		this.maxDepth = Math.min(maxDepth, FILTER_MAX_DEPTH)
+	}
+
+	/** Why any term could not be parsed, or null: the input is not trustworthy while this is set. */
+	get error(): string | null {
+		return this.failure
+	}
+
+	/** Mark the input malformed; the first reason stays */
+	private fail(reason: string = SYNTAX): void {
+		this.failure ??= reason
 	}
 
-	/** True when any term could not be parsed: the input is not trustworthy. */
-	get hadError(): boolean {
-		return this.malformed
+	/** Mark a comma beside no member, told by where the member should stand */
+	private failEmptyMember(at: number): void {
+		this.fail(`${SYNTAX}: empty member at position ${at + this.offset}`)
 	}
 
 	parse(): FilterAST {
-		const root = this.parseGroup("and")
+		const root = this.parseGroup("and", 0)
 		/* a stray ")" stops the top-level group early; anything left is unparsed */
-		if (this.pos < this.input.length) this.malformed = true
+		if (this.pos < this.input.length) this.fail()
 		return { root }
 	}
 
-	private parseGroup(logic: "and" | "or"): FilterGroup {
+	private parseGroup(logic: "and" | "or", depth: number): FilterGroup {
 		const group: FilterGroup = { conditions: [], logic, subgroups: [] }
 		while (this.skipWhitespace() < this.input.length && this.peek() !== ")") {
 			const nested = this.matchKeyword("or(") ? "or" : this.matchKeyword("and(") ? "and" : null
+			if (nested && depth === this.maxDepth) {
+				/* the first group past the cap: the input is refused here, before the descent could overflow */
+				this.fail(`Filter nesting too deep at position ${this.pos + this.offset} (max ${this.maxDepth})`)
+				this.pos = this.input.length
+				break
+			}
 			if (nested) {
 				this.pos += nested.length + 1
-				group.subgroups.push(this.parseGroup(nested))
+				group.subgroups.push(this.parseGroup(nested, depth + 1))
 				this.expect(")")
 			} else {
 				this.parseTerm(group)
@@ -66,18 +98,26 @@ class FilterParser {
 			this.skipWhitespace()
 			if (this.peek() !== ",") break
 			this.pos++
+			/* a comma owes a member: a group that ends on one holds an empty member */
+			if (this.skipWhitespace() >= this.input.length || this.peek() === ")") {
+				this.failEmptyMember(this.pos)
+				break
+			}
 		}
 		return group
 	}
 
 	/** One condition into `group`; a term it cannot read is skipped and marks the input malformed */
 	private parseTerm(group: FilterGroup): void {
+		const start = this.pos
 		const condition = this.parseCondition()
 		if (condition) {
 			group.conditions.push(condition)
 			return
 		}
-		this.malformed = true
+		/* a term that starts at its comma is an empty member, beside another comma or leading the group */
+		if (this.input[start] === ",") this.failEmptyMember(start)
+		else this.fail()
 		while (this.pos < this.input.length && this.peek() !== "," && this.peek() !== ")") this.pos++
 	}
 
@@ -113,14 +153,21 @@ class FilterParser {
 		const values: string[] = []
 		while (this.skipWhitespace() < this.input.length && this.peek() !== ")") {
 			const quoted = this.peek() === '"'
+			const at = this.pos
 			const value = this.readValue()
+			/* a bare member with nothing in it stands beside a comma; only a quoted one may be empty */
 			if (quoted || value !== "") values.push(value)
+			else this.failEmptyMember(at)
 			/* a quoted member ends at its quote: only a comma or the list's end may follow */
 			if (quoted && this.skipWhitespace() < this.input.length && this.peek() !== "," && this.peek() !== ")") {
-				this.malformed = true
+				this.fail()
 				return values
 			}
-			if (this.peek() === ",") this.pos++
+			if (this.peek() === ",") {
+				this.pos++
+				/* a comma owes a member: `in.(x,)` holds an empty one, `in.()` is the only empty list */
+				if (this.skipWhitespace() >= this.input.length || this.peek() === ")") this.failEmptyMember(this.pos)
+			}
 		}
 		this.expect(")")
 		return values
@@ -135,7 +182,7 @@ class FilterParser {
 		const start = this.pos
 		while (this.pos < this.input.length && this.peek() !== "," && this.peek() !== ")") this.pos++
 		const value = this.input.slice(start, this.pos).trim()
-		if (value.includes("(")) this.malformed = true
+		if (value.includes("(")) this.fail()
 		return value
 	}
 
@@ -152,7 +199,7 @@ class FilterParser {
 			value += this.peek()
 		}
 		/* an unterminated quote */
-		this.malformed = true
+		this.fail()
 		return value
 	}
 
@@ -167,7 +214,7 @@ class FilterParser {
 	/** A group that is never closed leaves the input unbalanced: reject it. */
 	private expect(char: string): void {
 		if (this.peek() === char) this.pos++
-		else this.malformed = true
+		else this.fail()
 	}
 
 	/** Step past whitespace; returns the new position */
@@ -178,15 +225,26 @@ class FilterParser {
 }
 
 /**
- * The AST of a filter string, or null when there is none or any part of it cannot be read: a
+ * The AST of a non-blank filter string, or why it cannot be read, in words for a caller to show: a
  * filter the parser does not fully understand is refused, never reduced to "no filter", which
- * would widen the result to the whole table on a typo.
+ * would widen the result to the whole table on a typo. A group nested past `maxDepth`, or past
+ * FILTER_MAX_DEPTH whatever `maxDepth` is, is refused where it opens.
+ */
+function readFilter(input: string, maxDepth: number): { ast: FilterAST } | { error: string } {
+	const parser = new FilterParser(input.trim(), input.length - input.trimStart().length, maxDepth)
+	const ast = parser.parse()
+	return parser.error === null ? { ast } : { error: parser.error }
+}
+
+/**
+ * The AST of a filter string, or null when there is none or any part of it cannot be read, or it
+ * nests past FILTER_MAX_DEPTH: a filter the parser does not fully understand is refused, never
+ * reduced to "no filter", which would widen the result to the whole table on a typo.
  */
 function parseFilter(input: string | null | undefined): FilterAST | null {
 	if (!input || input.trim() === "") return null
-	const parser = new FilterParser(input.trim())
-	const ast = parser.parse()
-	return parser.hadError ? null : ast
+	const read = readFilter(input, FILTER_MAX_DEPTH)
+	return "ast" in read ? read.ast : null
 }
 
-export { FILTER_OPERATORS, parseFilter }
+export { FILTER_OPERATORS, parseFilter, readFilter }

package/src/query/filter-validate.ts

@@ -3,7 +3,7 @@
  * every value typed as its field declares, so SQL generation binds numbers as numbers and
  * booleans as booleans, and computed resolvers receive the declared type.
  */
-import { parseFilter } from "./filter-parse.ts"
+import { readFilter } from "./filter-parse.ts"
 import { type CheckedField, typedValue } from "./filter-typed.ts"
 import { patternOf } from "./like.ts"
 import type { FieldType, FilterAST, FilterCondition, FilterGroup, FilterOperator } from "./types.ts"
@@ -66,7 +66,7 @@ type FilterValidationResult =
 type FilterLimits = {
 	/** Conditions in the whole filter, every group counted */
 	maxConditions: number
-	/** Nested or()/and() groups below the top level */
+	/** Nested or()/and() groups below the top level; the parser reads no more than 256, whatever this is */
 	maxDepth: number
 	/** Members of one in/nin list */
 	maxInValues: number
@@ -168,17 +168,16 @@ function checkCondition(condition: FilterCondition, check: Check): FilterConditi
 	return { ...condition, value: typed.value }
 }
 
-/** The group with every condition checked and typed, and how many conditions and levels it holds */
-type Shape = { conditions: number; depth: number; group: FilterGroup; values: number }
+/** The group with every condition checked and typed, and how many conditions and values it holds */
+type Shape = { conditions: number; group: FilterGroup; values: number }
 
-function checkGroup(group: FilterGroup, check: Check, depth: number): Shape {
-	const subgroups = group.subgroups.map((subgroup) => checkGroup(subgroup, check, depth + 1))
+function checkGroup(group: FilterGroup, check: Check): Shape {
+	const subgroups = group.subgroups.map((subgroup) => checkGroup(subgroup, check))
 	/* counted on the typed conditions: is.true binds its boolean, is.null nothing */
 	const conditions = group.conditions.map((condition) => checkCondition(condition, check))
 	const values = conditions.reduce((total, condition) => total + boundBy(condition), 0)
 	return {
 		conditions: subgroups.reduce((total, sub) => total + sub.conditions, group.conditions.length),
-		depth: Math.max(depth, ...subgroups.map((sub) => sub.depth)),
 		values: subgroups.reduce((total, sub) => total + sub.values, values),
 		group: {
 			conditions,
@@ -201,20 +200,18 @@ function validateFilter(
 	const fields = checkedFields(allowedFields)
 	const caps = limitsOver("validateFilter", FILTER_LIMITS, limits)
 	if (!filterString || filterString.trim() === "") return null
-	const ast = parseFilter(filterString)
-	if (!ast) return { errors: ["Invalid filter syntax"], valid: false }
+	const read = readFilter(filterString, caps.maxDepth)
+	if ("error" in read) return { errors: [read.error], valid: false }
+	const ast = read.ast
 
 	const check: Check = { errors: [], fields, limits: caps }
-	const shape = checkGroup(ast.root, check, 0)
+	const shape = checkGroup(ast.root, check)
 	if (shape.conditions > check.limits.maxConditions) {
 		check.errors.push(`Too many filter conditions: ${shape.conditions} (max ${check.limits.maxConditions})`)
 	}
 	if (shape.values > check.limits.maxValues) {
 		check.errors.push(`Filter binds too many values: ${shape.values} (max ${check.limits.maxValues})`)
 	}
-	if (shape.depth > check.limits.maxDepth) {
-		check.errors.push(`Filter nesting too deep: ${shape.depth} (max ${check.limits.maxDepth})`)
-	}
 	return check.errors.length > 0 ? { errors: check.errors, valid: false } : { ast: { root: shape.group }, valid: true }
 }