@orkestrel/table 0.0.3 → 0.0.5

package/dist/src/core/index.js

@@ -1,35 +1,40 @@
 import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isRecord, isString, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
-/** Every column cell, in the order declared by the public contract. */
+/** Lists every column cell, in the order declared by the public contract. */
 var COLUMN_CELLS = Object.freeze([
 	"text",
 	"number",
 	"flag",
 	"choice"
 ]);
-/** The maximum number of columns one schema may declare. */
+/** Names the maximum number of columns one schema may declare: 256. */
 var COLUMN_LIMIT = 256;
-/** The maximum number of choices one `choice` column may offer. */
+/** Names the maximum number of choices one `choice` column may offer: 1024. */
 var CHOICE_LIMIT = 1024;
-/** The maximum length, in UTF-16 code units, of a schema name or column key. */
+/** Names the maximum length of a schema name or column key: 128 UTF-16 code units. */
 var NAME_LIMIT = 128;
-/** The maximum length, in UTF-16 code units, of any single retained string. */
+/** Names the maximum length of any single retained string: 65536 UTF-16 code units. */
 var STRING_LIMIT = 65536;
-/** The maximum total length, in UTF-16 code units, of every string one schema retains. */
+/**
+* Names the maximum total length of every string one schema retains: 1048576 UTF-16 code units.
+*/
 var TEXT_LIMIT = 1048576;
-/** The maximum total number of records, arrays, and leaves one schema retains. */
+/** Names the maximum total number of records, arrays, and leaves one schema retains: 16384. */
 var NODE_LIMIT = 16384;
 //#endregion
 //#region src/core/errors.ts
-/** An error raised by the table domain. */
+/**
+* Represents an error raised by the table domain — a machine-readable `code` and optional
+* structured `context`.
+*/
 var TableError = class extends Error {
-	/** The machine-readable reason for this failure. */
+	/** Holds the machine-readable reason for this failure. */
 	code;
-	/** Structured values that locate or explain this failure. */
+	/** Holds structured values that locate or explain this failure. */
 	context;
 	/**
-	* Create a table error.
+	* Creates a table error.
 	*
 	* @param code - The machine-readable reason.
 	* @param message - The human-readable failure text.
@@ -43,10 +48,11 @@ var TableError = class extends Error {
 	}
 };
 /**
-* Determine whether an unknown value is a table error.
+* Determines whether a caught value is a table error, so a `catch` branches on `code` without an
+* assertion.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a {@link TableError} instance.
+* @returns True if the value is a {@link TableError} instance; false otherwise.
 */
 function isTableError(input) {
 	return input instanceof TableError;
@@ -54,7 +60,7 @@ function isTableError(input) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Find one column by key.
+* Finds one column by key; `undefined` when the schema declares no such column.
 *
 * @param schema - The schema whose columns to search.
 * @param key - The column key to find.
@@ -64,7 +70,8 @@ function extractColumn(schema, key) {
 	return schema.columns.find((column) => column.key === key);
 }
 /**
-* Read one row's declared identity.
+* Reads one row's declared identity; `undefined` when its key cell is missing, empty, or not a
+* string.
 *
 * @param schema - The schema that names the identity column.
 * @param row - The row whose identity to read.
@@ -76,7 +83,8 @@ function extractKey(schema, row) {
 	return isString(key) && key.length > 0 ? key : void 0;
 }
 /**
-* Compute one atomic 0/1/N membership change over known keys.
+* Computes one atomic 0/1/N membership change over the keys a caller may address — the engine
+* selection and expansion share.
 *
 * @param known - Every key the caller may change.
 * @param current - The current key set.
@@ -95,11 +103,59 @@ function computeKeys(known, current, input, include) {
 	return next.size !== current.size || [...next].some((key) => !current.has(key)) ? next : current;
 }
 /**
-* Check whether a value has the shape required by one column cell.
+* Merges lens terms into a column-keyed list, replacing the entry that names the same column —
+* the `set` write.
+*
+* @param current - The list as it stands.
+* @param requested - The terms to write, in the order they are written.
+* @returns A frozen list holding one owned entry per column, in the order the columns first
+*   appeared.
+*/
+function mergeTerms(current, requested) {
+	const next = [...current];
+	for (const term of requested) {
+		const owned = Object.freeze({ ...term });
+		const index = next.findIndex((candidate) => candidate.column === term.column);
+		if (index === -1) next.push(owned);
+		else next[index] = owned;
+	}
+	return Object.freeze(next);
+}
+/**
+* Removes every lens term naming one of the given columns — the drop `sort.remove` and
+* `filter.remove` share.
+*
+* @param current - The list as it stands.
+* @param columns - The column keys to drop.
+* @returns A frozen list holding the entries no named column matched, in their original order.
+*/
+function removeTerms(current, columns) {
+	const removed = new Set(columns);
+	return Object.freeze(current.filter((term) => !removed.has(term.column)));
+}
+/**
+* Checks whether two lens lists hold the same terms in the same order, with the supplied test
+* deciding the operands.
+*
+* @param left - The first list.
+* @param right - The second list.
+* @param equal - Decide whether two terms naming one column carry the same operands.
+* @returns True if the lists are the same length and every position names the same column and
+*   carries the same operands; false otherwise.
+*/
+function matchesTerms(left, right, equal) {
+	return left.length === right.length && left.every((term, index) => {
+		const other = right[index];
+		return other !== void 0 && term.column === other.column && equal(term, other);
+	});
+}
+/**
+* Checks whether one column can hold a value — the shape gate every write and every seed passes
+* through.
 *
 * @param column - The column that owns the cell.
 * @param value - The unknown value to inspect.
-* @returns Whether the column can hold the value.
+* @returns True if the column can hold the value; false otherwise.
 */
 function matchesCell(column, value) {
 	if (isString(value) && value.length > 65536) return false;
@@ -111,7 +167,7 @@ function matchesCell(column, value) {
 	}
 }
 /**
-* Compare two cells in ascending order according to one column.
+* Compares two of one column's cells the way its `cell` fixes, describing ascending order.
 *
 * @param column - The column that fixes the comparison.
 * @param left - The first cell, or absence.
@@ -137,11 +193,12 @@ function compareCells(column, left, right) {
 	}
 }
 /**
-* Check whether one column admits a filter and all its operands.
+* Checks whether one column admits a filter and every operand it carries — the gate `filter.set`
+* and {@link matchesFilter} share.
 *
 * @param column - The column that fixes the accepted operators and cell shapes.
 * @param filter - The filter to inspect.
-* @returns Whether the filter belongs to the column and the column can apply it.
+* @returns True if the filter belongs to the column and the column can apply it; false otherwise.
 */
 function admitsFilter(column, filter) {
 	if (filter.column !== column.key) return false;
@@ -152,12 +209,12 @@ function admitsFilter(column, filter) {
 	}
 }
 /**
-* Test one cell against a filter according to its column.
+* Tests one of a column's cells against one filter the way its `cell` fixes.
 *
 * @param column - The column that fixes the accepted operators.
 * @param cell - The cell to test, or absence.
 * @param filter - The filter to apply.
-* @returns Whether the filter accepts the cell.
+* @returns True if the filter accepts the cell; false otherwise.
 */
 function matchesFilter(column, cell, filter) {
 	if (cell === void 0 || !admitsFilter(column, filter) || !matchesCell(column, cell)) return false;
@@ -168,7 +225,8 @@ function matchesFilter(column, cell, filter) {
 	}
 }
 /**
-* Keep the rows accepted by every filter.
+* Keeps the rows every filter accepts, in the order given; a supplied {@link CellMatcher}
+* replaces the default per column.
 *
 * @param schema - The schema that declares the filtered columns.
 * @param rows - The rows to filter.
@@ -186,7 +244,8 @@ function filterRows(schema, rows, filters, matchers) {
 	})));
 }
 /**
-* Order rows stably by a sequence of terms.
+* Orders rows by the terms given, stably; a supplied {@link CellComparator} replaces the default
+* per column.
 *
 * @param schema - The schema that declares the sorted columns.
 * @param rows - The rows to order.
@@ -214,7 +273,8 @@ function sortRows(schema, rows, orders, comparators) {
 	return Object.freeze(indexed.map((entry) => entry.row));
 }
 /**
-* Audit a structurally valid schema for domain and budget faults.
+* Audits a structurally valid schema for domain faults and budget breaches, returning human
+* diagnostics.
 *
 * @param schema - The table schema to audit.
 * @returns Frozen human-readable diagnostics, or an empty list when the schema is sound.
@@ -313,7 +373,8 @@ function auditTable(schema) {
 	return Object.freeze(faults);
 }
 /**
-* Project a schema into declaration-ordered JSON.
+* Projects a schema into JSON in declaration order, dropping every absent member; raises `SCHEMA`
+* for a `meta` it cannot own.
 *
 * @param schema - The schema to project.
 * @returns A deeply owned JSON record with absent members omitted.
@@ -352,7 +413,8 @@ function serializeTable(schema) {
 	}
 }
 /**
-* Project rows into schema-column-ordered JSON.
+* Projects rows into JSON with each row's cells in the schema's column order, dropping every
+* absent cell.
 *
 * @param schema - The schema that fixes cell order.
 * @param rows - The rows to project.
@@ -380,19 +442,21 @@ function serializeRows(schema, rows) {
 //#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether an unknown value has a table cell shape.
+* Determines whether an unknown value has a table cell shape — a string, a finite number, or a
+* boolean.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a string, finite number, or boolean.
+* @returns True if the value is a string, finite number, or boolean; false otherwise.
 */
 function isTableCell(input) {
 	return unionOf(isString, isFiniteNumber, isBoolean)(input);
 }
 /**
-* Determine whether an unknown value is a record of table cells.
+* Determines whether an unknown value is a record whose every own key is a string and every value
+* a {@link TableCell}.
 *
 * @param input - The value to inspect.
-* @returns Whether every own key is a string and every value is a table cell.
+* @returns True if every own key is a string and every value is a table cell; false otherwise.
 */
 function isTableRow(input) {
 	const outcome = attempt(() => {
@@ -402,19 +466,20 @@ function isTableRow(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value is a declared column cell.
+* Determines whether an unknown value is a declared column cell.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is one of the four column cells.
+* @returns True if the value is a declared column cell; false otherwise.
 */
 function isColumnCell(input) {
 	return COLUMN_CELLS.some((cell) => cell === input);
 }
 /**
-* Determine whether an unknown value is one exact column choice record.
+* Determines whether an unknown value is one exact {@link ColumnChoice} record; an unknown member
+* refuses it.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a column choice.
+* @returns True if the value is a column choice; false otherwise.
 */
 function isColumnChoice(input) {
 	const outcome = attempt(() => {
@@ -428,10 +493,11 @@ function isColumnChoice(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value is one exact discriminated table column.
+* Determines whether an unknown value is one exact discriminated {@link TableColumn}, checked
+* against its cell's own options.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a structurally valid table column.
+* @returns True if the value is a structurally valid table column; false otherwise.
 */
 function isTableColumn(input) {
 	const outcome = attempt(() => {
@@ -470,10 +536,11 @@ function isTableColumn(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value has one exact structural table-schema shape.
+* Determines whether an unknown value has the exact shape of a {@link TableSchema} — the shape
+* alone, with no domain check.
 *
 * @param input - The value to inspect.
-* @returns Whether the value has the exact structure of a table schema.
+* @returns True if the value has the exact structure of a table schema; false otherwise.
 */
 function isStructuralTableSchema(input) {
 	const outcome = attempt(() => {
@@ -493,10 +560,12 @@ function isStructuralTableSchema(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value is one semantically sound table schema.
+* Determines whether an unknown value is a {@link TableSchema} a table can be opened against —
+* the exact shape, and an audit that finds nothing.
 *
 * @param input - The value to inspect.
-* @returns Whether the value has valid structure, domain relationships, and budgets.
+* @returns True if the value has valid structure, domain relationships, and
+*   budgets; false otherwise.
 */
 function isTableSchema(input) {
 	const outcome = attempt(() => isStructuralTableSchema(input) && auditTable(input).length === 0);
@@ -505,7 +574,7 @@ function isTableSchema(input) {
 //#endregion
 //#region src/core/cloners.ts
 /**
-* Clone one row into an owned frozen snapshot.
+* Clones one row into an owned frozen snapshot.
 *
 * @param row - The row to own.
 * @returns A frozen copy of the row's cells.
@@ -514,7 +583,8 @@ function cloneRow(row) {
 	return Object.freeze({ ...row });
 }
 /**
-* Clone a table schema into an owned frozen snapshot.
+* Clones a whole schema into an owned frozen snapshot, freezing every nested column, choice list,
+* choice, and `meta`; raises `SCHEMA` for a `meta` it cannot own.
 *
 * @param schema - The schema to own.
 * @returns A frozen schema with every nested column, choice, list, and metadata record owned.
@@ -545,7 +615,7 @@ function cloneSchema(schema) {
 //#endregion
 //#region src/core/parsers.ts
 /**
-* Parse unknown wire data into an owned, semantically sound table schema.
+* Parses unknown wire data into an owned, structurally valid, semantically sound table schema.
 *
 * @param input - The unknown schema value to parse.
 * @returns An owned table schema, or `undefined` on refusal.
@@ -559,7 +629,8 @@ function parseTable(input) {
 	return outcome.success ? outcome.value : void 0;
 }
 /**
-* Parse unknown wire rows against one table schema.
+* Parses unknown wire data into owned rows against one table schema, coercing a numeric string
+* and `'true'` / `'false'`.
 *
 * @param schema - The schema that declares the accepted keys and cell shapes.
 * @param input - The unknown row-list value to parse.
@@ -605,63 +676,94 @@ function parseRows(schema, input) {
 	return outcome.success ? outcome.value : void 0;
 }
 //#endregion
-//#region src/core/tables/ExpansionManager.ts
-/** The keys of the rows somebody has opened. */
-var ExpansionManager = class {
+//#region src/core/tables/KeyManager.ts
+/** Manages the key set one table axis holds, and the event it announces when that set moves. */
+var KeyManager = class {
 	#emitter;
+	#event;
 	#gate;
 	#rows;
 	#read;
 	#write;
 	/**
-	* Create an expansion manager over one table's private stores.
+	* Creates a key-set shell over one table's private store.
 	*
 	* @param emitter - The table's event emitter.
+	* @param event - The event this axis announces when its key set moves.
 	* @param gate - The table lifecycle gate.
 	* @param rows - A read of every row key.
-	* @param read - A read of the expanded keys.
-	* @param write - The expanded-key commit boundary.
+	* @param read - A read of the held keys.
+	* @param write - The held-key commit boundary.
 	*/
-	constructor(emitter, gate, rows, read, write) {
+	constructor(emitter, event, gate, rows, read, write) {
 		this.#emitter = emitter;
+		this.#event = event;
 		this.#gate = gate;
 		this.#rows = rows;
 		this.#read = read;
 		this.#write = write;
 	}
-	/** The keys of the rows opened right now. */
+	/** Returns the keys held right now. */
 	get keys() {
 		return new Set(this.#read());
 	}
-	/** Open one or more rows. */
-	expand(input) {
-		this.#gate();
-		return this.#change(input, () => true);
-	}
-	/** Close one or more rows. */
-	clear(input) {
-		this.#gate();
-		return this.#change(input, () => false);
-	}
-	/** Turn one or more rows around independently. */
-	toggle(input) {
+	/**
+	* Applies one atomic 0/1/N membership change, announcing it only when the set moves.
+	*
+	* @param input - Every known key, one key, or a key list.
+	* @param include - Decides the next membership from each key's membership at that step.
+	* @returns `undefined` for the no-argument form, `false` when any requested key names no row
+	*   the table holds, and `true` otherwise.
+	*/
+	change(input, include) {
 		this.#gate();
-		return this.#change(input, (included) => !included) === true;
-	}
-	#change(input, include) {
 		const previous = this.#read();
 		const next = computeKeys(this.#rows(), previous, input, include);
 		if (next === void 0) return false;
 		if (next !== previous) {
 			this.#write(next);
-			this.#emitter.emit("expand", new Set(next));
+			this.#emitter.emit(this.#event, new Set(next));
 		}
 		return input === void 0 ? void 0 : true;
 	}
 };
 //#endregion
+//#region src/core/tables/ExpansionManager.ts
+/** Manages the keys of the rows somebody has opened. */
+var ExpansionManager = class {
+	#keys;
+	/**
+	* Creates an expansion manager over one table's private stores.
+	*
+	* @param emitter - The table's event emitter.
+	* @param gate - The table lifecycle gate.
+	* @param rows - A read of every row key.
+	* @param read - A read of the expanded keys.
+	* @param write - The expanded-key commit boundary.
+	*/
+	constructor(emitter, gate, rows, read, write) {
+		this.#keys = new KeyManager(emitter, "expand", gate, rows, read, write);
+	}
+	/** Returns the keys of the rows opened right now. */
+	get keys() {
+		return this.#keys.keys;
+	}
+	/** Opens one or more rows. */
+	expand(input) {
+		return this.#keys.change(input, () => true);
+	}
+	/** Closes one or more rows. */
+	clear(input) {
+		return this.#keys.change(input, () => false);
+	}
+	/** Turns one or more rows around independently. */
+	toggle(input) {
+		return this.#keys.change(input, (included) => !included) === true;
+	}
+};
+//#endregion
 //#region src/core/tables/FilterManager.ts
-/** The filters one table applies with and-only composition. */
+/** Manages the filters one table applies with and-only composition. */
 var FilterManager = class {
 	#schema;
 	#emitter;
@@ -670,7 +772,7 @@ var FilterManager = class {
 	#write;
 	#clamp;
 	/**
-	* Create a filter manager over one table's private filter store.
+	* Creates a filter manager over one table's private filter store.
 	*
 	* @param schema - The table schema.
 	* @param emitter - The table's event emitter.
@@ -687,42 +789,35 @@ var FilterManager = class {
 		this.#write = write;
 		this.#clamp = clamp;
 	}
-	/** Find one column's filter. */
+	/** Finds one column's filter. */
 	filter(column) {
 		const filter = this.#read().find((candidate) => candidate.column === column);
 		return filter === void 0 ? void 0 : Object.freeze({ ...filter });
 	}
-	/** Read every filter as an owned frozen snapshot. */
+	/** Reads every filter as an owned frozen snapshot. */
 	filters() {
 		return Object.freeze(this.#read().map((filter) => Object.freeze({ ...filter })));
 	}
-	/** Filter one column or several. */
+	/** Filters one column or several. */
 	set(input) {
 		this.#gate();
 		const requested = Array.isArray(input) ? input : [input];
 		for (const filter of requested) this.#validate(filter);
-		const next = [...this.#read()];
-		for (const filter of requested) {
-			const owned = Object.freeze({ ...filter });
-			const index = next.findIndex((candidate) => candidate.column === filter.column);
-			if (index === -1) next.push(owned);
-			else next[index] = owned;
-		}
-		if (this.#same(next, this.#read())) return;
-		this.#write(Object.freeze(next));
+		const next = mergeTerms(this.#read(), requested);
+		if (matchesTerms(next, this.#read(), (filter, other) => this.#operands(filter, other))) return;
+		this.#write(next);
 		const page = this.#clamp();
 		this.#emitter.emit("filter", this.filters());
 		if (page !== void 0) this.#emitter.emit("paginate", page);
 	}
-	/** Stop filtering by one or more columns. */
+	/** Stops filtering by one or more columns. */
 	remove(input) {
 		this.#gate();
 		const columns = input === void 0 ? this.#schema.columns.map((column) => column.key) : Array.isArray(input) ? input : [input];
 		for (const column of columns) if (extractColumn(this.#schema, column) === void 0) return false;
-		const removed = new Set(columns);
-		const next = this.#read().filter((filter) => !removed.has(filter.column));
+		const next = removeTerms(this.#read(), columns);
 		if (next.length !== this.#read().length) {
-			this.#write(Object.freeze(next));
+			this.#write(next);
 			const page = this.#clamp();
 			this.#emitter.emit("filter", this.filters());
 			if (page !== void 0) this.#emitter.emit("paginate", page);
@@ -734,19 +829,16 @@ var FilterManager = class {
 		if (column === void 0) throw new TableError("COLUMN", `The schema declares no column named "${filter.column}"`, { column: filter.column });
 		if (!admitsFilter(column, filter)) throw new TableError("CELL", `Column "${filter.column}" cannot apply that filter`, { column: filter.column });
 	}
-	#same(left, right) {
-		return left.length === right.length && left.every((filter, index) => {
-			const other = right[index];
-			if (other === void 0 || filter.column !== other.column || filter.operator !== other.operator) return false;
-			if (filter.operator === "contains" && other.operator === "contains") return filter.text === other.text;
-			if (filter.operator === "between" && other.operator === "between") return filter.minimum === other.minimum && filter.maximum === other.maximum;
-			return filter.operator === "equals" && other.operator === "equals" && filter.value === other.value;
-		});
+	#operands(left, right) {
+		if (left.operator !== right.operator) return false;
+		if (left.operator === "contains" && right.operator === "contains") return left.text === right.text;
+		if (left.operator === "between" && right.operator === "between") return left.minimum === right.minimum && left.maximum === right.maximum;
+		return left.operator === "equals" && right.operator === "equals" && left.value === right.value;
 	}
 };
 //#endregion
 //#region src/core/tables/PaginationManager.ts
-/** The page arithmetic over one table's filtered rows. */
+/** Manages the page arithmetic over one table's filtered rows. */
 var PaginationManager = class {
 	#emitter;
 	#gate;
@@ -756,7 +848,7 @@ var PaginationManager = class {
 	#readLimit;
 	#writeLimit;
 	/**
-	* Create a pagination manager over one table's private stores.
+	* Creates a pagination manager over one table's private stores.
 	*
 	* @param emitter - The table's event emitter.
 	* @param gate - The table lifecycle gate.
@@ -777,33 +869,33 @@ var PaginationManager = class {
 		const limit = this.#readLimit();
 		if (limit !== void 0) this.#writeLimit(this.#normalize(limit));
 	}
-	/** The page shown, counted from one. */
+	/** Returns the page shown, counted from one. */
 	get page() {
 		return this.#readLimit() === void 0 ? 1 : this.#readPage();
 	}
-	/** The number of rows one page holds. */
+	/** Returns the number of rows one page holds. */
 	get limit() {
 		return this.#readLimit();
 	}
-	/** The number of filtered rows skipped before this page. */
+	/** Returns the number of filtered rows skipped before this page. */
 	get offset() {
 		const limit = this.#readLimit();
 		return limit === void 0 ? 0 : (this.#readPage() - 1) * limit;
 	}
-	/** The number of pages filled by the filtered rows. */
+	/** Returns the number of pages filled by the filtered rows. */
 	get count() {
 		const limit = this.#readLimit();
 		return limit === void 0 ? 1 : Math.max(1, Math.ceil(this.#rows() / limit));
 	}
-	/** Show another page, clamped to the pages that exist. */
+	/** Shows another page, clamped to the pages that exist. */
 	move(page) {
 		this.#gate();
-		const next = this.#readLimit() === void 0 ? 1 : Math.min(this.count, this.#normalize(page));
+		const next = this.#readLimit() === void 0 || Number.isNaN(page) ? 1 : Math.min(this.count, Math.max(1, Math.trunc(page)));
 		if (next === this.#readPage()) return;
 		this.#writePage(next);
 		this.#emitter.emit("paginate", next);
 	}
-	/** Change the page size while keeping the first row previously shown. */
+	/** Changes the page size while keeping the first row previously shown. */
 	resize(limit) {
 		this.#gate();
 		const previous = this.#readLimit();
@@ -821,7 +913,7 @@ var PaginationManager = class {
 };
 //#endregion
 //#region src/core/tables/RowManager.ts
-/** The rows one table holds in its own order. */
+/** Manages the rows one table holds in its own order. */
 var RowManager = class {
 	#schema;
 	#emitter;
@@ -830,7 +922,7 @@ var RowManager = class {
 	#write;
 	#settle;
 	/**
-	* Create a row manager over one table's private row store.
+	* Creates a row manager over one table's private row store.
 	*
 	* @param schema - The table schema.
 	* @param emitter - The table's event emitter.
@@ -850,16 +942,16 @@ var RowManager = class {
 		const seeded = this.#prepare(rows, /* @__PURE__ */ new Set());
 		if (seeded.length > 0) this.#write(Object.freeze(seeded));
 	}
-	/** Find one row by key as an owned frozen snapshot. */
+	/** Finds one row by key as an owned frozen snapshot. */
 	row(key) {
 		const row = this.#read().find((candidate) => extractKey(this.#schema, candidate) === key);
 		return row === void 0 ? void 0 : cloneRow(row);
 	}
-	/** Read every row as owned frozen snapshots in table order. */
+	/** Reads every row as owned frozen snapshots in table order. */
 	rows() {
 		return Object.freeze(this.#read().map((row) => cloneRow(row)));
 	}
-	/** Append one row or several. */
+	/** Appends one row or several. */
 	add(input) {
 		this.#gate();
 		const rows = Array.isArray(input) ? input : [input];
@@ -878,7 +970,7 @@ var RowManager = class {
 			}
 		});
 	}
-	/** Merge one row or several into the rows their keys name. */
+	/** Merges one row or several into the rows their keys name. */
 	update(input) {
 		this.#gate();
 		const updates = (Array.isArray(input) ? input : [input]).map((row) => cloneRow(row));
@@ -917,13 +1009,13 @@ var RowManager = class {
 		});
 		return true;
 	}
-	/** Move one row to a clamped index in table order. */
+	/** Moves one row to a clamped index in table order. */
 	move(key, index) {
 		this.#gate();
 		const current = this.#read();
 		const origin = current.findIndex((row) => extractKey(this.#schema, row) === key);
 		if (origin === -1) return false;
-		const target = Math.min(current.length - 1, Number.isFinite(index) ? Math.max(0, Math.trunc(index)) : 0);
+		const target = Math.min(current.length - 1, Number.isNaN(index) ? 0 : Math.max(0, Math.trunc(index)));
 		if (origin === target) return true;
 		const row = current[origin];
 		if (row === void 0) return false;
@@ -934,7 +1026,7 @@ var RowManager = class {
 		this.#settle([], () => this.#emitter.emit("write", key));
 		return true;
 	}
-	/** Remove one or more rows. */
+	/** Removes one or more rows. */
 	remove(input) {
 		this.#gate();
 		const current = this.#read();
@@ -995,15 +1087,11 @@ var RowManager = class {
 };
 //#endregion
 //#region src/core/tables/SelectionManager.ts
-/** The keys of the rows somebody has picked. */
+/** Manages the keys of the rows somebody has picked. */
 var SelectionManager = class {
-	#emitter;
-	#gate;
-	#rows;
-	#read;
-	#write;
+	#keys;
 	/**
-	* Create a selection manager over one table's private stores.
+	* Creates a selection manager over one table's private stores.
 	*
 	* @param emitter - The table's event emitter.
 	* @param gate - The table lifecycle gate.
@@ -1012,45 +1100,28 @@ var SelectionManager = class {
 	* @param write - The selected-key commit boundary.
 	*/
 	constructor(emitter, gate, rows, read, write) {
-		this.#emitter = emitter;
-		this.#gate = gate;
-		this.#rows = rows;
-		this.#read = read;
-		this.#write = write;
+		this.#keys = new KeyManager(emitter, "select", gate, rows, read, write);
 	}
-	/** The keys of the rows picked right now. */
+	/** Returns the keys of the rows picked right now. */
 	get keys() {
-		return new Set(this.#read());
+		return this.#keys.keys;
 	}
-	/** Pick one or more rows. */
+	/** Picks one or more rows. */
 	select(input) {
-		this.#gate();
-		return this.#change(input, () => true);
+		return this.#keys.change(input, () => true);
 	}
-	/** Drop one or more picks. */
+	/** Drops one or more picks. */
 	clear(input) {
-		this.#gate();
-		return this.#change(input, () => false);
+		return this.#keys.change(input, () => false);
 	}
-	/** Turn one or more rows around independently. */
+	/** Turns one or more rows around independently. */
 	toggle(input) {
-		this.#gate();
-		return this.#change(input, (included) => !included) === true;
-	}
-	#change(input, include) {
-		const previous = this.#read();
-		const next = computeKeys(this.#rows(), previous, input, include);
-		if (next === void 0) return false;
-		if (next !== previous) {
-			this.#write(next);
-			this.#emitter.emit("select", new Set(next));
-		}
-		return input === void 0 ? void 0 : true;
+		return this.#keys.change(input, (included) => !included) === true;
 	}
 };
 //#endregion
 //#region src/core/tables/SortManager.ts
-/** The ordered sort terms of one table. */
+/** Manages the ordered sort terms of one table. */
 var SortManager = class {
 	#schema;
 	#emitter;
@@ -1058,7 +1129,7 @@ var SortManager = class {
 	#read;
 	#write;
 	/**
-	* Create a sort manager over one table's private term store.
+	* Creates a sort manager over one table's private term store.
 	*
 	* @param schema - The table schema.
 	* @param emitter - The table's event emitter.
@@ -1073,41 +1144,33 @@ var SortManager = class {
 		this.#read = read;
 		this.#write = write;
 	}
-	/** Find one column's sort term. */
+	/** Finds one column's sort term. */
 	order(column) {
 		const order = this.#read().find((candidate) => candidate.column === column);
 		return order === void 0 ? void 0 : Object.freeze({ ...order });
 	}
-	/** Read every sort term as an owned frozen snapshot. */
+	/** Reads every sort term as an owned frozen snapshot. */
 	orders() {
 		return Object.freeze(this.#read().map((order) => Object.freeze({ ...order })));
 	}
-	/** Sort by one column or several. */
+	/** Sorts by one column or several. */
 	set(input) {
 		this.#gate();
 		const requested = Array.isArray(input) ? input : [input];
 		for (const order of requested) this.#require(order.column);
-		const next = [...this.#read()];
-		for (const order of requested) {
-			const owned = Object.freeze({ ...order });
-			const index = next.findIndex((candidate) => candidate.column === order.column);
-			if (index === -1) next.push(owned);
-			else next[index] = owned;
-		}
-		if (this.#same(next, this.#read())) return;
-		const committed = Object.freeze(next);
-		this.#write(committed);
+		const next = mergeTerms(this.#read(), requested);
+		if (matchesTerms(next, this.#read(), (order, other) => order.direction === other.direction)) return;
+		this.#write(next);
 		this.#emitter.emit("sort", this.orders());
 	}
-	/** Stop sorting by one or more columns. */
+	/** Stops sorting by one or more columns. */
 	remove(input) {
 		this.#gate();
 		const columns = input === void 0 ? this.#schema.columns.map((column) => column.key) : Array.isArray(input) ? input : [input];
 		for (const column of columns) if (extractColumn(this.#schema, column) === void 0) return false;
-		const removed = new Set(columns);
-		const next = this.#read().filter((order) => !removed.has(order.column));
+		const next = removeTerms(this.#read(), columns);
 		if (next.length !== this.#read().length) {
-			this.#write(Object.freeze(next));
+			this.#write(next);
 			this.#emitter.emit("sort", this.orders());
 		}
 		return input === void 0 ? void 0 : true;
@@ -1115,16 +1178,13 @@ var SortManager = class {
 	#require(column) {
 		if (extractColumn(this.#schema, column) === void 0) throw new TableError("COLUMN", `The schema declares no column named "${column}"`, { column });
 	}
-	#same(left, right) {
-		return left.length === right.length && left.every((order, index) => {
-			const other = right[index];
-			return other !== void 0 && order.column === other.column && order.direction === other.direction;
-		});
-	}
 };
 //#endregion
 //#region src/core/Table.ts
-/** A schema, its rows, and the lens through which they are read. */
+/**
+* Holds a schema, its rows, and the lens through which they are read, implementing
+* {@link TableInterface} exactly.
+*/
 var Table = class {
 	#emitter;
 	#schema;
@@ -1146,7 +1206,7 @@ var Table = class {
 	#expansion;
 	#pagination;
 	/**
-	* Open a table against a schema.
+	* Opens a table against a schema.
 	*
 	* @param schema - The table declaration to own.
 	* @param options - Initial rows, lens overrides, pagination, and emitter wiring.
@@ -1154,9 +1214,13 @@ var Table = class {
 	*   identity is unusable or repeated, and `CELL` when a seeded cell is invalid.
 	*/
 	constructor(schema, options) {
-		const problems = isStructuralTableSchema(schema) ? auditTable(schema) : ["The schema is not a table schema"];
+		const unusable = "The schema is not a table schema";
+		const owned = isStructuralTableSchema(schema) ? attempt(() => cloneSchema(schema)) : void 0;
+		if (owned !== void 0 && !owned.success && isTableError(owned.error)) throw owned.error;
+		if (owned === void 0 || !owned.success) throw new TableError("SCHEMA", `The table schema is unusable: ${unusable}`, { problems: [unusable] });
+		const problems = isStructuralTableSchema(owned.value) ? auditTable(owned.value) : [unusable];
 		if (problems.length > 0) throw new TableError("SCHEMA", `The table schema is unusable: ${problems.join("; ")}`, { problems: [...problems] });
-		this.#schema = cloneSchema(schema);
+		this.#schema = owned.value;
 		this.#comparators = options?.comparators === void 0 ? void 0 : Object.freeze({ ...options.comparators });
 		this.#matchers = options?.matchers === void 0 ? void 0 : Object.freeze({ ...options.matchers });
 		this.#limit = options?.limit;
@@ -1186,54 +1250,54 @@ var Table = class {
 			this.#rowStore = rows;
 		}, (removed, announce) => this.#settle(removed, announce), options?.rows);
 	}
-	/** The table's event emitter. */
+	/** Holds the table's event emitter. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The owned frozen schema. */
+	/** Holds the owned frozen schema. */
 	get schema() {
 		return this.#schema;
 	}
-	/** The rows the table holds. */
+	/** Manages the rows the table holds. */
 	get rows() {
 		return this.#rows;
 	}
-	/** The ordered sort terms. */
+	/** Manages the ordered sort terms. */
 	get sort() {
 		return this.#sort;
 	}
-	/** The filters applied with and-only composition. */
+	/** Manages the filters applied with and-only composition. */
 	get filter() {
 		return this.#filter;
 	}
-	/** The selected row keys. */
+	/** Manages the selected row keys. */
 	get selection() {
 		return this.#selection;
 	}
-	/** The expanded row keys. */
+	/** Manages the expanded row keys. */
 	get expansion() {
 		return this.#expansion;
 	}
-	/** The page arithmetic. */
+	/** Manages the page arithmetic. */
 	get pagination() {
 		return this.#pagination;
 	}
-	/** The filtered, sorted, and paged rows as owned frozen snapshots. */
+	/** Returns the filtered, sorted, and paged rows as owned frozen snapshots. */
 	get view() {
 		const ordered = sortRows(this.#schema, this.#filtered(), this.#orderStore, this.#comparators);
 		const limit = this.#limit;
 		const page = limit === void 0 ? ordered : ordered.slice(this.#pagination.offset, this.#pagination.offset + limit);
 		return Object.freeze(page.map((row) => cloneRow(row)));
 	}
-	/** The number of rows admitted by the filters. */
+	/** Returns the number of rows admitted by the filters. */
 	get count() {
 		return this.#filtered().length;
 	}
-	/** Whether the table has been torn down. */
+	/** Reports whether the table has been torn down. */
 	get destroyed() {
 		return this.#destroyed;
 	}
-	/** Reset every moving axis to its opening state. */
+	/** Resets every moving axis to its opening state. */
 	clear() {
 		this.#gate();
 		if (!(this.#rowStore.length > 0 || this.#orderStore.length > 0 || this.#filterStore.length > 0 || this.#selected.size > 0 || this.#expanded.size > 0 || this.#page !== 1 || this.#limit !== this.#initialLimit)) return;
@@ -1246,7 +1310,7 @@ var Table = class {
 		this.#limit = this.#initialLimit;
 		this.#emitter.emit("clear");
 	}
-	/** Tear the table down while leaving every getter readable. */
+	/** Tears the table down while leaving every getter readable. */
 	destroy() {
 		if (this.#destroyed) return;
 		this.#destroyed = true;
@@ -1288,23 +1352,49 @@ var Table = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Open a table against a schema.
+* Opens a table against a schema. The schema is copied, and the copy is what the table declares.
 *
 * @param schema - The table declaration to own.
 * @param options - Initial rows, lens overrides, pagination, and emitter wiring.
 * @returns A live table interface.
 * @throws A {@link TableError} coded `SCHEMA` when the schema is unusable, `KEY` when a seeded
 *   identity is unusable or repeated, and `CELL` when a seeded cell is invalid.
-* @example
+* @example Open a table
 * ```ts
-* const table = createTable({ key: 'id', columns: [{ cell: 'text', key: 'id' }] })
-* table.rows.add({ id: '1' })
+* import { createTable } from '@orkestrel/table'
+*
+* const table = createTable(
+* 	{
+* 		label: 'People',
+* 		key: 'id',
+* 		columns: [
+* 			{ cell: 'text', key: 'id', label: 'Reference' },
+* 			{ cell: 'text', key: 'name', label: 'Name' },
+* 			{ cell: 'number', key: 'age', label: 'Age' },
+* 		],
+* 	},
+* 	{
+* 		rows: [
+* 			{ id: '1', name: 'Ada', age: 36 },
+* 			{ id: '2', name: 'Grace', age: 45 },
+* 			{ id: '3', name: 'Alan', age: 41 },
+* 		],
+* 		limit: 2,
+* 	},
+* )
+*
+* table.filter.set({ column: 'name', operator: 'contains', text: 'a' })
+* table.sort.set({ column: 'age', direction: 'descending' })
+*
+* table.count // 3 — every name holds a lowercase 'a'
+* table.pagination.count // 2 — two pages of two
+* table.view.map((row) => row.name) // ['Grace', 'Alan'] — page one, oldest first
 * ```
 */
 function createTable(schema, options) {
 	return new Table(schema, options);
 }
 //#endregion
-export { CHOICE_LIMIT, COLUMN_CELLS, COLUMN_LIMIT, ExpansionManager, FilterManager, NAME_LIMIT, NODE_LIMIT, PaginationManager, RowManager, STRING_LIMIT, SelectionManager, SortManager, TEXT_LIMIT, Table, TableError, admitsFilter, auditTable, cloneRow, cloneSchema, compareCells, computeKeys, createTable, extractColumn, extractKey, filterRows, isColumnCell, isColumnChoice, isStructuralTableSchema, isTableCell, isTableColumn, isTableError, isTableRow, isTableSchema, matchesCell, matchesFilter, parseRows, parseTable, serializeRows, serializeTable, sortRows };
+export { CHOICE_LIMIT, COLUMN_CELLS, COLUMN_LIMIT, NAME_LIMIT, NODE_LIMIT, STRING_LIMIT, TEXT_LIMIT, Table, TableError, admitsFilter, auditTable, cloneRow, cloneSchema, compareCells, computeKeys, createTable, extractColumn, extractKey, filterRows, isColumnCell, isColumnChoice, isStructuralTableSchema, isTableCell, isTableColumn, isTableError, isTableRow, isTableSchema, matchesCell, matchesFilter, matchesTerms, mergeTerms, parseRows, parseTable, removeTerms, serializeRows, serializeTable, sortRows };
 
 //# sourceMappingURL=index.js.map