@workerstack/database 0.21.0 → 0.22.1

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

package/src/query/filter.ts

@@ -16,6 +16,43 @@ import {
 } from "./filter-validate.ts"
 import type { SortDirection, SortField } from "./types.ts"
 
+/** The direction suffix an `order` entry may end in, before any nulls suffix, and what it reads as */
+const SORT_DIRECTIONS = { asc: "asc", desc: "desc" } as const satisfies Record<string, SortDirection>
+/** The nulls suffix an `order` entry may end in, and what it reads as */
+const SORT_NULLS = { nullsfirst: "first", nullslast: "last" } as const
+
+/** The value `suffixes` reads the last of `tokens` as, popping it, or undefined when it is none of them */
+function suffixOf<T extends string>(tokens: string[], suffixes: Readonly<Record<string, T>>): T | undefined {
+	for (const [suffix, value] of Object.entries(suffixes))
+		if (tokens.at(-1) === suffix) {
+			tokens.pop()
+			return value
+		}
+	return undefined
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+/** A regular expression taking any one of `names`, each literally */
+function anyOf(names: readonly string[]): string {
+	return `(?:${names.map(escapeRegExp).join("|")})`
+}
+
+/**
+ * A regular expression taking every `order` parseOrder reads over the fields in `sort`, up to
+ * `maxSortKeys` entries: the empty value, which reads as the default order, and each entry the field
+ * and the suffixes orderEntries reads off it. A field named twice is refused, so no order holds more
+ * entries than `sort` has fields; which field repeats needs a lookahead, which RE2 lacks, so the
+ * pattern leaves that to the description
+ */
+function orderPattern(sort: readonly string[], maxSortKeys: number): string {
+	const entry = `${anyOf(sort)}(?:\\.${anyOf(Object.keys(SORT_DIRECTIONS))})?(?:\\.${anyOf(Object.keys(SORT_NULLS))})?`
+	const keys = Math.min(maxSortKeys, sort.length)
+	return `^(?:${entry}(?:,${entry}){0,${Math.max(0, keys - 1)}})?$`
+}
+
 /**
  * Parse PostgREST-style `order` string into SortField array.
  *
@@ -67,24 +104,8 @@ function orderEntries(input: string | null | undefined): Array<SortField | strin
 
 		const tokens = trimmed.split(".")
 
-		let nulls: "first" | "last" | undefined
-		const last = tokens[tokens.length - 1]
-		if (last === "nullsfirst") {
-			nulls = "first"
-			tokens.pop()
-		} else if (last === "nullslast") {
-			nulls = "last"
-			tokens.pop()
-		}
-
-		let direction: SortDirection = "asc"
-		const newLast = tokens[tokens.length - 1]
-		if (newLast === "asc") {
-			tokens.pop()
-		} else if (newLast === "desc") {
-			direction = "desc"
-			tokens.pop()
-		}
+		const nulls = suffixOf(tokens, SORT_NULLS)
+		const direction: SortDirection = suffixOf(tokens, SORT_DIRECTIONS) ?? "asc"
 
 		const field = tokens.join(".")
 		if (!field || part !== trimmed) {
@@ -108,6 +129,7 @@ export {
 	parseFilterNumber,
 	namedTwice,
 	orderEntries,
+	orderPattern,
 	parseOrder,
 	validateFilter,
 	type FilterField,

package/src/query/list-extras.ts

@@ -16,6 +16,7 @@ import {
 	unprintedNumber,
 } from "./held-keys.ts"
 import type { SortField } from "./types.ts"
+import { UnmintableRow } from "./cursor-refusals.ts"
 
 /** The column every built list selects its tiebreak as, which the next cursor's id is minted from */
 const COMB_ID = "_combId" as const
@@ -140,19 +141,15 @@ const FLOAT_MARK = "!f"
  * which the read places nowhere a cursor resumes after
  */
 const storesUnread = (field: string, stored: string): CombError =>
-	new CombError({
-		cause: `${field} stores a ${stored.toUpperCase()} value its column's drizzle mode reads as another, which no cursor of a list that binds the key as read resumes after: store what the mode reads back (a timestamp's epoch number, a boolean's 0 or 1, a finite number), or sort by a column of the list's own table`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	new UnmintableRow(
+		`${field} stores a ${stored.toUpperCase()} value its column's drizzle mode reads as another, which no cursor of a list that binds the key as read resumes after: store what the mode reads back (a timestamp's epoch number, a boolean's 0 or 1, a finite number), or sort by a column of the list's own table`,
+	)
 
 /** The 500 for a SQLite number key no text SQLite prints of reads back as it, which no cursor binds exactly */
 const printsUnread = (field: string): CombError =>
-	new CombError({
-		cause: `${field} holds a REAL no text SQLite prints of it reads back as (D1 misprints some past about 1e100 and below 1e-100), which no cursor resumes after: store a number of fewer significant digits, or sort by another column`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	new UnmintableRow(
+		`${field} holds a REAL no text SQLite prints of it reads back as (D1 misprints some past about 1e100 and below 1e-100), which no cursor resumes after: store a number of fewer significant digits, or sort by another column`,
+	)
 
 /** The 500 for a Postgres float key read under extra_float_digits 0 or below: its read is rounded */
 const printsRounded = (field: string): CombError =>

package/src/query/list-schema.ts

@@ -24,7 +24,6 @@ import {
 	selectQueryFieldFor,
 	sortDirectionEnum,
 } from "./schema-params.ts"
-import { pageTooDeep } from "./trusted.ts"
 import type { ListQueryConfig, ListQueryLimits, ListQueryOutput, OutputStableShape } from "./schema-types.ts"
 import { validateSelectWithConfig } from "./select-validate.ts"
 import type { FieldType } from "./types.ts"
@@ -178,7 +177,6 @@ function createListQuerySchema<
 
 	const { maxLimit = PAGINATION_DEFAULTS.maxLimit, maxPage = PAGINATION_DEFAULTS.maxPage } = config.pagination ?? {}
 	const piped = schema.transform((data, ctx): ExtendedOutput => {
-		if (data.page !== undefined && data.page > maxPage) throw pageTooDeep(data.page, maxPage)
 		/* Optional params exist on `data` only when advertised above. */
 		const optional = data as {
 			filter?: string | undefined

package/src/query/merged.ts

@@ -18,6 +18,7 @@ import {
 	COMB_ID,
 	type ListPagination,
 	type ListRow,
+	nextCursorOf,
 	type PaginationResponse,
 	totalOf,
 } from "./pagination.ts"
@@ -238,8 +239,8 @@ function paginateMerged<T extends object>(
 	const window = rows.slice(start, start + limit + 1)
 	const hasMore = full || window.length > limit
 	const page = hasMore ? window.slice(0, limit) : window
-	/* every row served is one a cursor resumes after; the last one's is sealed */
-	const last = page.map((row) => pagination.fit(row)).at(-1)
+	/* the rows a cursor may be minted from are fitted; the last one's is sealed */
+	const last = nextCursorOf(page, { byCursor: cursor !== undefined, hasMore }, (row) => pagination.fit(row))
 	const meta: PaginationResponse = {
 		count: countOf(rowsPerShard, cursor),
 		hasMore,

package/src/query/pagination.ts

@@ -16,6 +16,7 @@ import { paginationIn, refuseGoneAnchor, refuseOverRead, refuseUnwired } from ".
 import type { paginationResponseSchema } from "./schema.ts"
 import type { ListQueryInput, ParsedFields, SortField } from "./types.ts"
 import type * as z from "zod"
+import { UnmintableRow } from "./cursor-refusals.ts"
 
 /**
  * The name of one column a builder selects for `paginate` to read, which no row it returns keeps: the
@@ -187,6 +188,28 @@ function fitFrom(
 	})
 }
 
+/**
+ * What seals a served page's next cursor, or undefined for none, `check` measuring a row's cursor. On
+ * a page by cursor it runs on every row: its client walks the list one cursor at a time, so a row no
+ * cursor resumes after is refused on the page that serves it, whatever the page size. On a page by
+ * number it runs only on the last row of a page with more, the one the cursor is minted from, as
+ * 0.20.1 did; a row whose own value no cursor holds (UnmintableRow) mints none, and the page serves it,
+ * its `hasMore` still saying a next page by number exists. A refusal of the list's wiring throws on both
+ */
+function nextCursorOf<T>(
+	page: readonly T[],
+	{ byCursor, hasMore }: { byCursor: boolean; hasMore: boolean },
+	check: (row: T) => (() => string) | undefined,
+): (() => string) | undefined {
+	if (byCursor) return page.map(check).at(-1)
+	try {
+		return (hasMore ? page.slice(-1) : []).map(check).at(-1)
+	} catch (error) {
+		if (error instanceof UnmintableRow) return undefined
+		throw error
+	}
+}
+
 /**
  * The page of `items`, read with `built`, and its pagination: count, whether there is more, and
  * the next cursor, sealed under the builder's options; none for a list no cursor can resume
@@ -207,12 +230,12 @@ function paginate<T extends object>(
 	refuseGoneAnchor(items)
 	const hasMore = items.length > pagination.limit
 	const sliced = hasMore ? items.slice(0, pagination.limit) : items
-	/* a key no cursor bound as read places is refused on the page that serves it, wherever its row lands */
-	for (const item of sliced) refuseUnheld(item as Record<string, unknown>, pagination.parsedSort)
-	/* every row served is one a cursor resumes after, checked from the fat row, under the sort the builder
-	   ordered by, so the next request's signature matches; the last one's is sealed */
-	const fitted = pagination.cursorable ? sliced.map((item) => pagination.fit(item)) : []
-	const last = fitted.at(-1)
+	/* a key no cursor bound as read places is refused as a mint is, checked from the fat row, under the
+	   sort the builder ordered by, so the next request's signature matches; the last one's is sealed */
+	const last = nextCursorOf(sliced, { byCursor: pagination.cursor !== undefined, hasMore }, (item) => {
+		refuseUnheld(item as Record<string, unknown>, pagination.parsedSort)
+		return pagination.cursorable ? pagination.fit(item) : undefined
+	})
 	const meta: PaginationResponse = {
 		count: countOf(items, pagination),
 		hasMore,
@@ -229,6 +252,7 @@ function paginate<T extends object>(
 export {
 	applySelect,
 	COMB_ID,
+	nextCursorOf,
 	type ListExtra,
 	type ListPagination,
 	type ListRow,

package/src/query/rounded-key.ts

@@ -7,10 +7,9 @@
  * selected does the value alone. A class is trusted only when it names a double, so one comb cannot
  * place, such as a type no family covers, is refused as an integer is.
  */
-import { CombError } from "../error.ts"
-import { combErrorKeys } from "../types.ts"
 import { storedClasses } from "./list-extras.ts"
 import type { SortField } from "./types.ts"
+import { UnmintableRow } from "./cursor-refusals.ts"
 
 // lookup-table: why a list cannot page an integer sort key the driver rounded, by the list
 const ROUNDED: Readonly<Record<"derived" | "merged" | "unread", string>> = {
@@ -45,7 +44,7 @@ function roundedKey(
 	row: Record<string, unknown>,
 	sort: readonly SortField[],
 	list: "derived" | "merged" | { unread: (field: string) => boolean },
-): CombError | undefined {
+): UnmintableRow | undefined {
 	const [kind, judged] = typeof list === "string" ? [list, () => true] : (["unread", list.unread] as const)
 	const stored = storedClasses(row)
 	const rounded = sort.find(({ field }, i) => {
@@ -60,13 +59,11 @@ function roundedKey(
 	})
 	if (rounded === undefined) return undefined
 	const value = row[rounded.field] as number
-	return new CombError({
-		cause: Number.isInteger(value)
+	return new UnmintableRow(
+		Number.isInteger(value)
 			? `${rounded.field} ${BigInt(value)} is past ±(2^53 − 1), where the driver rounded it: ${ROUNDED[kind]}`
 			: `${rounded.field} ${value} is a fraction under a type no driver reads exactly as a JS number, so the driver may have rounded it: ${FRACTION[kind]}: sort by a Postgres numeric, whose text comb carries, read the key as a string, or sort by a double precision or real`,
-		errorKey: combErrorKeys.SORT_NOT_WIRED,
-		status: "internal_server_error",
-	})
+	)
 }
 
 export { roundedKey }

package/src/query/schema-params.ts

@@ -14,7 +14,7 @@ import {
 import { FILTER_OPERATORS } from "./filter-parse.ts"
 import { PAGINATION_DEFAULTS } from "./schema-limits.ts"
 import type { FieldsConfig, PaginationConfig } from "./schema-types.ts"
-import { invalidPage } from "./trusted.ts"
+import { invalidPage, pageTooDeep } from "./trusted.ts"
 import type { FieldSelection, FilterAST, FilterGroup, ParsedFields } from "./types.ts"
 
 /** The `select` param for an endpoint of these fields, its text and examples theirs */
@@ -88,10 +88,17 @@ function fromDigits(raw: unknown, max: number): unknown {
 	return DECIMAL_DIGITS.test(raw) && !padded ? Number(raw) : Number.NaN
 }
 
-/** `raw` as a page, a whole number from 1; anything else is invalid_page, as the builders answer it */
+/**
+ * `raw` as a page, a whole number from 1 to `maxPage`: past it, whatever its size, is `page_too_deep`,
+ * decided here on the digits before any number the schema could refuse exists; anything else is
+ * invalid_page, as the builders answer it. A digit string past 1e308 reads as Infinity: it is whole
+ */
 function pageFrom(raw: unknown, maxPage: number): unknown {
 	const page = fromDigits(raw, maxPage)
-	if (typeof page !== "number" || !Number.isInteger(page) || page < 1) throw invalidPage(raw)
+	const isDigits = typeof raw === "string"
+	if (typeof page !== "number" || page < 1 || !(Number.isInteger(page) || (isDigits && page === Infinity)))
+		throw invalidPage(raw)
+	if (page > maxPage) throw pageTooDeep(isDigits ? raw.replace(/^0+/, "") : page, maxPage)
 	return page
 }
 
@@ -147,8 +154,8 @@ function limitSchemaFor(pagination: PaginationConfig | undefined): z.ZodDefault<
 /**
  * The `page` param: decimal digits or a number, a whole number from 1. Neither bound is a field
  * error, which would give one condition two contracts: a page that is no whole number from 1 is
- * `invalid_page`, and maxPage, published but not checked here, is the list schema's
- * `page_too_deep`, each as an unbounded list answers it
+ * `invalid_page`, and one past maxPage is `page_too_deep` at any size, each as an unbounded list
+ * answers it
  */
 function pageSchema(maxPage: number): z.ZodOptional<CountParam> {
 	const page = z