@orkestrel/table 0.0.11 → 0.0.13

package/dist/src/core/index.d.ts

@@ -266,7 +266,7 @@ export declare interface EqualsFilter {
  * ```
  */
 export declare interface ExpansionManagerInterface {
-    /** Holds the keys of the rows opened right now. */
+    /** Holds the keys of the rows opened. */
     readonly keys: ReadonlySet<TableKey>;
     /** Opens every row the table holds, one row, or several. */
     expand(): void;
@@ -488,6 +488,10 @@ export declare function isTableColumn(input: unknown): input is TableColumn;
  * Determines whether a caught value is a table error, so a `catch` branches on `code` without an
  * assertion.
  *
+ * @remarks
+ * Recognizes self-branded errors across copies and subclasses and refuses transparent proxies.
+ * Validates the declared code and optional JSON context.
+ *
  * @param input - The value to inspect.
  * @returns True if the value is a {@link TableError} instance; false otherwise.
  */
@@ -611,7 +615,7 @@ export declare interface PaginationManagerInterface {
      * argument out to stop paging.
      *
      * @remarks
-     * The page moves to wherever that first row now falls.
+     * The page moves to wherever that first row falls.
      *
      * @param limit - How many rows a page holds. Leave it out to stop paging, and the view shows
      *   every row the filter admits.
@@ -773,7 +777,7 @@ export declare interface RowManagerInterface {
  * ```
  */
 export declare interface SelectionManagerInterface {
-    /** Holds the keys of the rows picked right now. */
+    /** Holds the keys of the rows picked. */
     readonly keys: ReadonlySet<TableKey>;
     /**
      * Picks every row the table holds, one row, or several. Every row, not every visible one.
@@ -1054,10 +1058,10 @@ export declare type TableErrorCode = 'SCHEMA' | 'COLUMN' | 'KEY' | 'CELL' | 'DES
  * `write` and `remove` carry one key and fire once per row, in the order the table wrote or
  * removed them. A listener that wants the row reads it back.
  *
- * `sort` and `filter` carry the whole axis as it now stands, and `select` and `expand` carry the
+ * `sort` and `filter` carry the whole axis as it stands, and `select` and `expand` carry the
  * whole key set. Each payload is owned by the listener, so nothing it holds moves underneath it.
  *
- * `paginate` carries the page the table now shows, and fires whenever the paged window moves,
+ * `paginate` carries the page the table shows, and fires whenever the paged window moves,
  * including a clamp and a change of page size.
  *
  * `clear` is a signal, and it is the whole announcement of that reset: a clear emits no `remove`,
@@ -1102,7 +1106,7 @@ export declare type TableFilter = ContainsFilter | BetweenFilter | EqualsFilter;
  * `pagination`. Nothing else is stored. `view` and `count` are worked out when they are read, so no
  * second copy of the answer can go stale.
  *
- * A write validates all of itself before any of it lands, and announces itself once it has.
+ * A write validates all of itself before any of it lands, and announces itself after it has.
  *
  * @example
  * ```ts
@@ -1129,7 +1133,7 @@ export declare interface TableInterface {
     /** Manages which stretch of them the view shows. */
     readonly pagination: PaginationManagerInterface;
     /**
-     * Returns the rows to draw right now: filtered, then sorted, then paged.
+     * Returns the rows to draw: filtered, then sorted, then paged.
      *
      * @remarks
      * It is worked out on every read and never stored, so it is right the instant anything moves.

package/dist/src/core/index.js

@@ -1,6 +1,6 @@
-import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isInstance, isRecord, isString, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
+import { GUARD_DEPTH_LIMIT, INTRINSICS, arrayOf, attempt, cloneJSONRecord, holds, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isRecord, isString, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
-//#region src/core/constants.ts
+// src/core/constants.ts
 /** Lists every column cell, in the order declared by the public contract. */
 var COLUMN_CELLS = Object.freeze([
 	"text",
@@ -22,8 +22,7 @@ var STRING_LIMIT = 65536;
 var TEXT_LIMIT = 1048576;
 /** Names the maximum total number of records, arrays, and leaves one schema retains: 16384. */
 var NODE_LIMIT = 16384;
-//#endregion
-//#region src/core/errors.ts
+// src/core/errors.ts
 /**
 * Represents an error raised by the table domain — a machine-readable `code` and optional
 * structured `context`.
@@ -42,6 +41,7 @@ var TableError = class extends Error {
 	*/
 	constructor(code, message, context) {
 		super(message);
+		INTRINSICS.define(this, Symbol.for("@orkestrel/table.TableError"), { value: this });
 		this.name = "TableError";
 		this.code = code;
 		if (context !== void 0) this.context = context;
@@ -51,14 +51,45 @@ var TableError = class extends Error {
 * Determines whether a caught value is a table error, so a `catch` branches on `code` without an
 * assertion.
 *
+* @remarks
+* Recognizes self-branded errors across copies and subclasses and refuses transparent proxies.
+* Validates the declared code and optional JSON context.
+*
 * @param input - The value to inspect.
 * @returns True if the value is a {@link TableError} instance; false otherwise.
 */
 function isTableError(input) {
-	return isInstance(input, TableError);
+	return holds(() => {
+		if (!(input instanceof Error) || INTRINSICS.prototype(input) === Error.prototype) return false;
+		if (INTRINSICS.describe(input, Symbol.for("@orkestrel/table.TableError"))?.value !== input) return false;
+		const code = INTRINSICS.reflect.read(input, "code");
+		const context = INTRINSICS.reflect.read(input, "context");
+		if (code !== "SCHEMA" && code !== "COLUMN" && code !== "KEY" && code !== "CELL" && code !== "DESTROYED") return false;
+		if (context === void 0) return true;
+		if (!isRecord(context)) return false;
+		const pending = [{
+			value: context,
+			ancestors: []
+		}];
+		for (const { value, ancestors } of pending) {
+			if (value === null || [
+				"string",
+				"number",
+				"boolean"
+			].includes(typeof value)) continue;
+			if (!Array.isArray(value) && !isRecord(value)) return false;
+			if (ancestors.length >= GUARD_DEPTH_LIMIT || ancestors.includes(value)) return false;
+			const path = [...ancestors, value];
+			const children = Array.isArray(value) ? Array.from({ length: value.length }, (_, index) => value[index]) : Object.values(value);
+			for (const child of children) pending.push({
+				value: child,
+				ancestors: path
+			});
+		}
+		return true;
+	});
 }
-//#endregion
-//#region src/core/helpers.ts
+// src/core/helpers.ts
 /**
 * Finds one column by key; `undefined` when the schema declares no such column.
 *
@@ -281,88 +312,102 @@ function sortRows(schema, rows, orders, comparators) {
 */
 function auditTable(schema) {
 	const faults = [];
-	const columns = /* @__PURE__ */ new Set();
-	let choiceExceeded;
-	let nameExceeded = schema.name !== void 0 && schema.name.length > 128;
+	const columns = [];
+	const longName = schema.name !== void 0 && schema.name.length > 128;
 	if (schema.columns.length > 256) faults.push(`schema declares more than 256 columns`);
 	const columnCount = Math.min(schema.columns.length, 257);
-	for (let index = 0; index < columnCount; index += 1) {
+	const indices = Array.from({ length: columnCount }, (_, index) => index);
+	const [choiceExceeded, nameExceeded] = indices.reduce(([choice, name], index) => {
 		const column = schema.columns[index];
-		if (column === void 0) continue;
-		if (column.key.length > 128) nameExceeded = true;
-		if (choiceExceeded === void 0 && column.cell === "choice" && column.choices.length > 1024) choiceExceeded = column.key;
-	}
+		if (column === void 0) return [choice, name];
+		const exceeded = column.key.length > 128;
+		return [choice === void 0 && column.cell === "choice" && column.choices.length > 1024 ? column.key : choice, name || exceeded];
+	}, [void 0, longName]);
 	if (choiceExceeded !== void 0) faults.push(`column "${choiceExceeded}" offers more than ${CHOICE_LIMIT} choices`);
 	if (nameExceeded) faults.push(`schema contains a name longer than 128`);
 	const pending = [schema];
 	const metadata = [false];
-	let position = 0;
-	let stringExceeded = false;
-	let textExceeded = false;
-	let nodeExceeded = false;
-	let text = 0;
-	while (position < pending.length) {
-		const node = pending[position];
+	const measurements = [];
+	for (const [position, node] of pending.entries()) {
 		const inMeta = metadata[position] === true;
-		position += 1;
 		if (isString(node)) {
-			if (node.length > 65536) stringExceeded = true;
-			text = Math.min(TEXT_LIMIT + 1, text + node.length);
-			if (text > 1048576) textExceeded = true;
+			measurements.push([
+				node.length,
+				node.length > STRING_LIMIT,
+				false
+			]);
 			continue;
 		}
 		if (isArray(node)) {
 			const read = readArrayEntries(node);
 			if (!read.success || !read.value.dense) continue;
-			for (const entry of read.value.entries) {
-				if (pending.length >= 16384) {
-					nodeExceeded = true;
-					continue;
-				}
+			const exceeded = read.value.entries.reduce((refused, entry) => {
+				if (pending.length >= 16384) return true;
 				pending.push(entry);
 				metadata.push(inMeta);
-			}
+				return refused;
+			}, false);
+			measurements.push([
+				0,
+				false,
+				exceeded
+			]);
 			continue;
 		}
 		if (!isRecord(node)) continue;
 		const keys = attempt(() => Object.keys(node));
 		if (!keys.success) continue;
-		for (const key of keys.value) {
-			if (inMeta) {
-				if (key.length > 65536) stringExceeded = true;
-				text = Math.min(TEXT_LIMIT + 1, text + key.length);
-				if (text > 1048576) textExceeded = true;
-			}
+		const measured = keys.value.reduce(([text, string, refused], key) => {
+			const length = text + (inMeta ? key.length : 0);
+			const oversized = string || inMeta && key.length > 65536;
 			const value = attempt(() => node[key]);
-			if (!value.success || value.value === void 0) continue;
-			if (pending.length >= 16384) {
-				nodeExceeded = true;
-				continue;
-			}
+			if (!value.success || value.value === void 0) return [
+				length,
+				oversized,
+				refused
+			];
+			if (pending.length >= 16384) return [
+				length,
+				oversized,
+				true
+			];
 			pending.push(value.value);
 			metadata.push(inMeta || key === "meta");
-		}
-	}
+			return [
+				length,
+				oversized,
+				refused
+			];
+		}, [
+			0,
+			false,
+			false
+		]);
+		measurements.push(measured);
+	}
+	const stringExceeded = measurements.some((entry) => entry[1]);
+	const textExceeded = measurements.reduce((total, entry) => total + entry[0], 0) > TEXT_LIMIT;
+	const nodeExceeded = measurements.some((entry) => entry[2]);
 	if (stringExceeded) faults.push(`schema contains a string longer than ${STRING_LIMIT}`);
 	if (textExceeded) faults.push(`schema retains more than ${TEXT_LIMIT} string code units`);
 	if (nodeExceeded) faults.push(`schema retains more than ${NODE_LIMIT} nodes`);
-	for (let index = 0; index < columnCount; index += 1) {
+	for (const index of indices) {
 		const column = schema.columns[index];
 		if (column === void 0) continue;
 		if (!nodeExceeded && column.meta !== void 0) {
 			if (!attempt(() => cloneJSONRecord(column.meta)).success) faults.push(`column "${column.key}" has metadata that cannot be owned`);
 		}
 		if (column.key.length === 0) faults.push("column \"\" has an empty key");
-		if (columns.has(column.key)) faults.push(`column "${column.key}" is declared more than once`);
-		columns.add(column.key);
+		if (columns.includes(column.key)) faults.push(`column "${column.key}" is declared more than once`);
+		columns.push(column.key);
 		if (column.cell === "choice") {
-			const choices = /* @__PURE__ */ new Set();
+			const choices = [];
 			const choiceCount = Math.min(column.choices.length, CHOICE_LIMIT + 1);
-			for (let choiceIndex = 0; choiceIndex < choiceCount; choiceIndex += 1) {
+			for (const choiceIndex of Array.from({ length: choiceCount }, (_, position) => position)) {
 				const choice = column.choices[choiceIndex];
 				if (choice === void 0) continue;
-				if (choices.has(choice.value)) faults.push(`column "${column.key}" offers choice "${choice.value}" more than once`);
-				choices.add(choice.value);
+				if (choices.includes(choice.value)) faults.push(`column "${column.key}" offers choice "${choice.value}" more than once`);
+				choices.push(choice.value);
 			}
 			if (column.choices.length === 0) faults.push(`column "${column.key}" offers no choices`);
 		}
@@ -447,8 +492,7 @@ function serializeRows(schema, rows) {
 function matchesTableRow(left, right) {
 	return left !== void 0 && Object.keys(left).length === Object.keys(right).length && Object.keys(right).every((key) => Object.hasOwn(left, key) && left[key] === right[key]);
 }
-//#endregion
-//#region src/core/validators.ts
+// src/core/validators.ts
 /**
 * Determines whether an unknown value has a table cell shape — a string, a finite number, or a
 * boolean.
@@ -579,8 +623,7 @@ function isTableSchema(input) {
 	const outcome = attempt(() => isStructuralTableSchema(input) && auditTable(input).length === 0);
 	return outcome.success && outcome.value;
 }
-//#endregion
-//#region src/core/cloners.ts
+// src/core/cloners.ts
 /**
 * Clones one row into an owned frozen snapshot.
 *
@@ -601,13 +644,12 @@ function cloneSchema(schema) {
 	return Object.freeze({
 		...schema,
 		columns: Object.freeze(schema.columns.map((column) => {
-			let meta = {};
-			if (column.meta !== void 0) try {
-				meta = { meta: cloneJSONRecord(column.meta) };
-			} catch (error) {
-				if (!isContractError(error)) throw error;
+			const owned = column.meta === void 0 ? void 0 : attempt(() => cloneJSONRecord(column.meta));
+			if (owned !== void 0 && !owned.success) {
+				if (!isContractError(owned.error)) throw owned.error;
 				throw new TableError("SCHEMA", `column "${column.key}" has metadata that cannot be owned`, { column: column.key });
 			}
+			const meta = owned === void 0 ? {} : { meta: owned.value };
 			if (column.cell === "choice") return Object.freeze({
 				...column,
 				...meta,
@@ -620,8 +662,7 @@ function cloneSchema(schema) {
 		}))
 	});
 }
-//#endregion
-//#region src/core/parsers.ts
+// src/core/parsers.ts
 /**
 * Parses unknown wire data into an owned, structurally valid, semantically sound table schema.
 *
@@ -659,12 +700,8 @@ function parseRows(schema, input) {
 				const column = extractColumn(schema, key);
 				if (column === void 0) return void 0;
 				const inputCell = candidate[key];
-				let cell = inputCell;
-				if (column.cell === "number" && isString(inputCell)) {
-					if (inputCell.length > 65536) return void 0;
-					cell = parseNumber(inputCell);
-				} else if (column.cell === "flag" && inputCell === "true") cell = true;
-				else if (column.cell === "flag" && inputCell === "false") cell = false;
+				if (column.cell === "number" && isString(inputCell) && inputCell.length > 65536) return void 0;
+				const cell = column.cell === "number" && isString(inputCell) ? parseNumber(inputCell) : column.cell === "flag" && inputCell === "true" ? true : column.cell === "flag" && inputCell === "false" ? false : inputCell;
 				if (!matchesCell(column, cell)) return void 0;
 				Object.defineProperty(row, key, {
 					value: cell,
@@ -683,8 +720,7 @@ function parseRows(schema, input) {
 	});
 	return outcome.success ? outcome.value : void 0;
 }
-//#endregion
-//#region src/core/tables/KeyManager.ts
+// 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;
@@ -711,7 +747,7 @@ var KeyManager = class {
 		this.#read = read;
 		this.#write = write;
 	}
-	/** Returns the keys held right now. */
+	/** Returns the keys held. */
 	get keys() {
 		return new Set(this.#read());
 	}
@@ -735,8 +771,7 @@ var KeyManager = class {
 		return input === void 0 ? void 0 : true;
 	}
 };
-//#endregion
-//#region src/core/tables/ExpansionManager.ts
+// src/core/tables/ExpansionManager.ts
 /** Manages the keys of the rows somebody has opened. */
 var ExpansionManager = class {
 	#keys;
@@ -752,7 +787,7 @@ var ExpansionManager = class {
 	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. */
+	/** Returns the keys of the rows opened. */
 	get keys() {
 		return this.#keys.keys;
 	}
@@ -769,8 +804,7 @@ var ExpansionManager = class {
 		return this.#keys.change(input, (included) => !included) === true;
 	}
 };
-//#endregion
-//#region src/core/tables/FilterManager.ts
+// src/core/tables/FilterManager.ts
 /** Manages the filters one table applies with and-only composition. */
 var FilterManager = class {
 	#schema;
@@ -844,8 +878,7 @@ var FilterManager = class {
 		return left.operator === "equals" && right.operator === "equals" && left.value === right.value;
 	}
 };
-//#endregion
-//#region src/core/tables/PaginationManager.ts
+// src/core/tables/PaginationManager.ts
 /** Manages the page arithmetic over one table's filtered rows. */
 var PaginationManager = class {
 	#emitter;
@@ -919,8 +952,7 @@ var PaginationManager = class {
 		return isFiniteNumber(value) ? Math.max(1, Math.trunc(value)) : 1;
 	}
 };
-//#endregion
-//#region src/core/tables/RowManager.ts
+// src/core/tables/RowManager.ts
 /** Manages the rows one table holds in its own order. */
 var RowManager = class {
 	#schema;
@@ -994,8 +1026,7 @@ var RowManager = class {
 		}
 		const next = [...current];
 		const moved = [];
-		for (let index = 0; index < updates.length; index += 1) {
-			const update = updates[index];
+		for (const [index, update] of updates.entries()) {
 			const location = locations[index];
 			if (update === void 0 || location === void 0) continue;
 			const previous = next[location];
@@ -1121,8 +1152,7 @@ var RowManager = class {
 		throw new TableError("KEY", message, { key });
 	}
 };
-//#endregion
-//#region src/core/tables/SelectionManager.ts
+// src/core/tables/SelectionManager.ts
 /** Manages the keys of the rows somebody has picked. */
 var SelectionManager = class {
 	#keys;
@@ -1138,7 +1168,7 @@ var SelectionManager = class {
 	constructor(emitter, gate, rows, read, write) {
 		this.#keys = new KeyManager(emitter, "select", gate, rows, read, write);
 	}
-	/** Returns the keys of the rows picked right now. */
+	/** Returns the keys of the rows picked. */
 	get keys() {
 		return this.#keys.keys;
 	}
@@ -1155,8 +1185,7 @@ var SelectionManager = class {
 		return this.#keys.change(input, (included) => !included) === true;
 	}
 };
-//#endregion
-//#region src/core/tables/SortManager.ts
+// src/core/tables/SortManager.ts
 /** Manages the ordered sort terms of one table. */
 var SortManager = class {
 	#schema;
@@ -1215,8 +1244,7 @@ var SortManager = class {
 		if (extractColumn(this.#schema, column) === void 0) throw new TableError("COLUMN", `The schema declares no column named "${column}"`, { column });
 	}
 };
-//#endregion
-//#region src/core/Table.ts
+// src/core/Table.ts
 /**
 * Holds a schema, its rows, and the lens through which they are read, implementing
 * {@link TableInterface} exactly.
@@ -1385,8 +1413,7 @@ var Table = class {
 		if (this.#destroyed) throw new TableError("DESTROYED", "The table was destroyed and cannot change");
 	}
 };
-//#endregion
-//#region src/core/factories.ts
+// src/core/factories.ts
 /**
 * Opens a table against a schema. The schema is copied, and the copy is what the table declares.
 *
@@ -1430,7 +1457,6 @@ var Table = class {
 function createTable(schema, options) {
 	return new Table(schema, options);
 }
-//#endregion
 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, matchesTableRow, matchesTerms, mergeTerms, parseRows, parseTable, removeTerms, serializeRows, serializeTable, sortRows };
 
 //# sourceMappingURL=index.js.map