@orkestrel/table 0.0.11 → 0.0.13

package/dist/src/browser/index.js

@@ -1,6 +1,7 @@
-import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isInstance, isRecord, isString, parseJSON, parseNumber, readArrayEntries, recordOf } from "@orkestrel/contract";
+import { INTRINSICS, attempt, holds, parseJSON, parseNumber } from "@orkestrel/contract";
+import { extractKey, matchesTableRow, parseRows, parseTable } from "../core/index.js";
 import { Emitter } from "@orkestrel/emitter";
-//#region src/browser/errors.ts
+// src/browser/errors.ts
 /** Represents a native table binding failure with a machine-readable code. */
 var TableBindingError = class extends Error {
 	code;
@@ -10,435 +11,24 @@ var TableBindingError = class extends Error {
 	*/
 	constructor(code, message) {
 		super(message);
+		INTRINSICS.define(this, Symbol.for("@orkestrel/table.TableBindingError"), { value: this });
 		this.name = "TableBindingError";
 		this.code = code;
 	}
 };
 /** Checks whether a caught value is a native table binding error.
+* @remarks
+* Recognizes self-branded errors across copies and subclasses and refuses transparent proxies.
 * @param value - The caught value.
 * @returns Whether the value is a binding error.
 */
 function isTableBindingError(value) {
-	return isInstance(value, TableBindingError);
-}
-//#endregion
-//#region src/core/errors.ts
-/**
-* Represents an error raised by the table domain — a machine-readable `code` and optional
-* structured `context`.
-*/
-var TableError = class extends Error {
-	/** Holds the machine-readable reason for this failure. */
-	code;
-	/** Holds structured values that locate or explain this failure. */
-	context;
-	/**
-	* Creates a table error.
-	*
-	* @param code - The machine-readable reason.
-	* @param message - The human-readable failure text.
-	* @param context - Optional structured failure details.
-	*/
-	constructor(code, message, context) {
-		super(message);
-		this.name = "TableError";
-		this.code = code;
-		if (context !== void 0) this.context = context;
-	}
-};
-//#endregion
-//#region src/core/cloners.ts
-/**
-* Clones one row into an owned frozen snapshot.
-*
-* @param row - The row to own.
-* @returns A frozen copy of the row's cells.
-*/
-function cloneRow(row) {
-	return Object.freeze({ ...row });
-}
-//#endregion
-//#region src/core/constants.ts
-/** Lists every column cell, in the order declared by the public contract. */
-var COLUMN_CELLS = Object.freeze([
-	"text",
-	"number",
-	"flag",
-	"choice"
-]);
-/** Names the maximum number of choices one `choice` column may offer: 1024. */
-var CHOICE_LIMIT = 1024;
-/** Names the maximum length of any single retained string: 65536 UTF-16 code units. */
-var STRING_LIMIT = 65536;
-/**
-* Names the maximum total length of every string one schema retains: 1048576 UTF-16 code units.
-*/
-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/helpers.ts
-/**
-* 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.
-* @returns The declared column, or `undefined` when no column has that key.
-*/
-function extractColumn(schema, key) {
-	return schema.columns.find((column) => column.key === key);
-}
-/**
-* 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.
-* @returns The non-empty string identity, or `undefined` when it is unusable.
-*/
-function extractKey(schema, row) {
-	if (!Object.hasOwn(row, schema.key)) return void 0;
-	const key = row[schema.key];
-	return isString(key) && key.length > 0 ? key : void 0;
-}
-/**
-* 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 True if the column can hold the value; false otherwise.
-*/
-function matchesCell(column, value) {
-	if (isString(value) && value.length > 65536) return false;
-	switch (column.cell) {
-		case "text": return isString(value);
-		case "number": return isFiniteNumber(value);
-		case "flag": return isBoolean(value);
-		case "choice": return isString(value) && column.choices.some((choice) => choice.value === value);
-	}
-}
-/**
-* 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.
-*/
-function auditTable(schema) {
-	const faults = [];
-	const columns = /* @__PURE__ */ new Set();
-	let choiceExceeded;
-	let nameExceeded = 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 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 (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 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;
-			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;
-				}
-				pending.push(entry);
-				metadata.push(inMeta);
-			}
-			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 value = attempt(() => node[key]);
-			if (!value.success || value.value === void 0) continue;
-			if (pending.length >= 16384) {
-				nodeExceeded = true;
-				continue;
-			}
-			pending.push(value.value);
-			metadata.push(inMeta || key === "meta");
-		}
-	}
-	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) {
-		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 (column.cell === "choice") {
-			const choices = /* @__PURE__ */ new Set();
-			const choiceCount = Math.min(column.choices.length, CHOICE_LIMIT + 1);
-			for (let choiceIndex = 0; choiceIndex < choiceCount; choiceIndex += 1) {
-				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 (column.choices.length === 0) faults.push(`column "${column.key}" offers no choices`);
-		}
-	}
-	const key = extractColumn(schema, schema.key);
-	if (key === void 0) faults.push(`schema key "${schema.key}" names no declared column`);
-	else if (key.cell === "number" || key.cell === "flag") faults.push(`schema key "${schema.key}" names a ${key.cell} column, which holds no identity`);
-	return Object.freeze(faults);
-}
-/**
-* 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.
-* @throws A {@link TableError} coded `SCHEMA` when metadata cannot be owned.
-*/
-function serializeTable(schema) {
-	const output = {};
-	if (schema.name !== void 0) output.name = schema.name;
-	if (schema.label !== void 0) output.label = schema.label;
-	if (schema.help !== void 0) output.help = schema.help;
-	output.key = schema.key;
-	output.columns = schema.columns.map((column) => {
-		const entry = {
-			cell: column.cell,
-			key: column.key
-		};
-		if (column.label !== void 0) entry.label = column.label;
-		if (column.help !== void 0) entry.help = column.help;
-		if (column.hidden !== void 0) entry.hidden = column.hidden;
-		if (column.meta !== void 0) entry.meta = column.meta;
-		if (column.cell === "choice") entry.choices = column.choices.map((choice) => {
-			const option = {
-				value: choice.value,
-				label: choice.label
-			};
-			if (choice.help !== void 0) option.help = choice.help;
-			return option;
-		});
-		return entry;
-	});
-	try {
-		return cloneJSONRecord(output);
-	} catch (error) {
-		if (!isContractError(error)) throw error;
-		throw new TableError("SCHEMA", "schema contains metadata that cannot be owned");
-	}
-}
-/** Compares complete row values independently of their snapshot identities.
-* @param left - The previous row, if present.
-* @param right - The next row.
-* @returns Whether both rows carry exactly the same cells.
-*/
-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
-/**
-* Determines whether an unknown value is a declared column cell.
-*
-* @param input - The value to inspect.
-* @returns True if the value is a declared column cell; false otherwise.
-*/
-function isColumnCell(input) {
-	return COLUMN_CELLS.some((cell) => cell === input);
-}
-/**
-* Determines whether an unknown value is one exact {@link ColumnChoice} record; an unknown member
-* refuses it.
-*
-* @param input - The value to inspect.
-* @returns True if the value is a column choice; false otherwise.
-*/
-function isColumnChoice(input) {
-	const outcome = attempt(() => {
-		if (!isRecord(input) || !Reflect.ownKeys(input).every((key) => isString(key))) return false;
-		return recordOf({
-			value: isString,
-			label: isString,
-			help: isString
-		}, ["help"])(input);
-	});
-	return outcome.success && outcome.value;
-}
-/**
-* 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 True if the value is a structurally valid table column; false otherwise.
-*/
-function isTableColumn(input) {
-	const outcome = attempt(() => {
-		if (!isRecord(input) || !Object.hasOwn(input, "cell") || !Object.hasOwn(input, "key")) return false;
-		const cell = input.cell;
-		if (!isColumnCell(cell)) return false;
-		if (!Reflect.ownKeys(input).every((key) => {
-			if (!isString(key)) return false;
-			if ([
-				"cell",
-				"key",
-				"label",
-				"help",
-				"hidden",
-				"meta"
-			].includes(key)) return true;
-			return cell === "choice" && key === "choices";
-		})) return false;
-		const key = input.key;
-		const hasLabel = Object.hasOwn(input, "label");
-		const label = hasLabel ? input.label : void 0;
-		const hasHelp = Object.hasOwn(input, "help");
-		const help = hasHelp ? input.help : void 0;
-		const hasHidden = Object.hasOwn(input, "hidden");
-		const hidden = hasHidden ? input.hidden : void 0;
-		const hasMeta = Object.hasOwn(input, "meta");
-		const meta = hasMeta ? input.meta : void 0;
-		if (hasMeta) {
-			if (!isBoundedJSONRecord(meta)) return false;
-			if (!attempt(() => cloneJSONRecord(meta)).success) return false;
-		}
-		if (!isString(key) || hasLabel && !isString(label) || hasHelp && !isString(help) || hasHidden && !isBoolean(hidden)) return false;
-		if (cell !== "choice") return !Object.hasOwn(input, "choices");
-		return Object.hasOwn(input, "choices") && arrayOf(isColumnChoice)(input.choices);
-	});
-	return outcome.success && outcome.value;
-}
-/**
-* 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 True if the value has the exact structure of a table schema; false otherwise.
-*/
-function isStructuralTableSchema(input) {
-	const outcome = attempt(() => {
-		if (!isRecord(input) || !Reflect.ownKeys(input).every((key) => isString(key))) return false;
-		return recordOf({
-			name: isString,
-			label: isString,
-			help: isString,
-			key: isString,
-			columns: arrayOf(isTableColumn)
-		}, [
-			"name",
-			"label",
-			"help"
-		])(input);
-	});
-	return outcome.success && outcome.value;
-}
-/**
-* 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 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);
-	return outcome.success && outcome.value;
-}
-//#endregion
-//#region src/core/parsers.ts
-/**
-* 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.
-*/
-function parseTable(input) {
-	const outcome = attempt(() => {
-		if (!isTableSchema(input)) return void 0;
-		const projected = serializeTable(input);
-		return isTableSchema(projected) ? projected : void 0;
+	return holds(() => {
+		if (!(value instanceof Error) || INTRINSICS.prototype(value) === Error.prototype) return false;
+		return INTRINSICS.describe(value, Symbol.for("@orkestrel/table.TableBindingError"))?.value === value && INTRINSICS.reflect.read(value, "code") === "STRUCTURE";
 	});
-	return outcome.success ? outcome.value : void 0;
 }
-/**
-* 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.
-* @returns Frozen owned rows, or `undefined` when any row is refused.
-*/
-function parseRows(schema, input) {
-	const outcome = attempt(() => {
-		if (!isTableSchema(schema) || !isArray(input)) return;
-		const read = readArrayEntries(input);
-		if (!read.success || !read.value.dense) return void 0;
-		const keys = /* @__PURE__ */ new Set();
-		const rows = [];
-		for (const candidate of read.value.entries) {
-			if (!isRecord(candidate)) return void 0;
-			const row = {};
-			for (const key of Reflect.ownKeys(candidate)) {
-				if (!isString(key) || !Object.hasOwn(candidate, key)) return void 0;
-				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 (!matchesCell(column, cell)) return void 0;
-				Object.defineProperty(row, key, {
-					value: cell,
-					enumerable: true,
-					configurable: true,
-					writable: true
-				});
-			}
-			const owned = cloneRow(row);
-			const key = extractKey(schema, owned);
-			if (key === void 0 || keys.has(key)) return void 0;
-			keys.add(key);
-			rows.push(owned);
-		}
-		return Object.freeze(rows);
-	});
-	return outcome.success ? outcome.value : void 0;
-}
-//#endregion
-//#region src/browser/helpers.ts
+// src/browser/helpers.ts
 /** Reads declared header metadata and explicit row keys into a validated core projection.
 * @param element - A native table with data-table-key naming its identity column.
 * @returns The schema and rows, validated together before any mutation.
@@ -486,7 +76,7 @@ function readTableSchema(element) {
 * @throws A binding error for duplicate keys, undeclared cells, or malformed values.
 */
 function readTableRows(schema, elements) {
-	const rows = parseRows(schema, elements.map((element) => {
+	const candidates = elements.map((element) => {
 		const cells = { [schema.key]: element.getAttribute("data-table-key") };
 		const seen = /* @__PURE__ */ new Set();
 		for (const cell of element.cells) {
@@ -504,12 +94,12 @@ function readTableRows(schema, elements) {
 			});
 		}
 		return cells;
-	}));
+	});
+	const rows = parseRows(schema, candidates);
 	if (rows === void 0) throw new TableBindingError("STRUCTURE", "Native row keys or cells are invalid");
 	return rows;
 }
-//#endregion
-//#region src/browser/TableBinding.ts
+// src/browser/TableBinding.ts
 /** Retains keyed native rows while projecting every core table manager. */
 var TableBinding = class {
 	#element;
@@ -749,13 +339,7 @@ var TableBinding = class {
 		for (const row of view) {
 			const key = extractKey(this.#document.schema, row);
 			if (key === void 0) continue;
-			let node = this.#rows.get(key);
-			if (node === void 0) {
-				if (this.#options.row === void 0) throw new TableBindingError("STRUCTURE", "An authored document row has no native row");
-				node = this.#element.ownerDocument.createElement("tr");
-				node.setAttribute("data-table-key", key);
-				this.#rows.set(key, node);
-			}
+			const node = this.#rows.get(key) ?? this.#createRow(key);
 			if (this.#options.row !== void 0 && !matchesTableRow(this.#values.get(key), row)) {
 				this.#options.row(node, row);
 				if (this.destroyed) return;
@@ -781,6 +365,20 @@ var TableBinding = class {
 		this.#observe();
 		if (this.#records.length > 0) this.#enqueue();
 	}
+	#createRow(key) {
+		if (this.#options.row === void 0) throw new TableBindingError("STRUCTURE", "An authored document row has no native row");
+		const node = this.#element.ownerDocument.createElement("tr");
+		node.setAttribute("data-table-key", key);
+		this.#rows.set(key, node);
+		return node;
+	}
+	#createDetail(key) {
+		const detail = this.#element.ownerDocument.createElement("tr");
+		detail.id = `table-detail-${crypto.randomUUID()}`;
+		detail.insertCell().colSpan = Math.max(1, this.#rows.get(key)?.cells.length ?? this.#document.schema.columns.length);
+		this.#details.set(key, detail);
+		return detail;
+	}
 	#restoreFocus(focused, hidden = false) {
 		if (focused !== void 0 && this.#element.ownerDocument.activeElement !== focused && (this.#element.ownerDocument.activeElement === this.#element.ownerDocument.body || this.#element.ownerDocument.activeElement === null)) {
 			if (focused.isConnected) focused.focus({ preventScroll: true });
@@ -794,13 +392,7 @@ var TableBinding = class {
 	}
 	#detail(key, row) {
 		if (this.#options.detail === void 0 || !this.#document.expansion.keys.has(key)) return void 0;
-		let detail = this.#details.get(key);
-		if (detail === void 0) {
-			detail = this.#element.ownerDocument.createElement("tr");
-			detail.id = `table-detail-${crypto.randomUUID()}`;
-			detail.insertCell().colSpan = Math.max(1, this.#rows.get(key)?.cells.length ?? this.#document.schema.columns.length);
-			this.#details.set(key, detail);
-		}
+		const detail = this.#details.get(key) ?? this.#createDetail(key);
 		if (!matchesTableRow(this.#detailValues.get(key), row)) {
 			this.#options.detail(detail, row);
 			if (!this.destroyed) this.#detailValues.set(key, row);
@@ -816,11 +408,9 @@ var TableBinding = class {
 		this.#observe();
 	}
 	#attribute(element, name, value) {
-		let attributes = this.#attributes.get(element);
-		if (attributes === void 0) {
-			attributes = /* @__PURE__ */ new Map();
-			this.#attributes.set(element, attributes);
-		}
+		if (!this.#attributes.has(element)) this.#attributes.set(element, /* @__PURE__ */ new Map());
+		const attributes = this.#attributes.get(element);
+		if (attributes === void 0) return;
 		const entry = attributes.get(name);
 		if (entry === void 0) attributes.set(name, {
 			original: element.getAttribute(name),
@@ -1064,8 +654,7 @@ var TableBinding = class {
 		});
 	}
 };
-//#endregion
-//#region src/browser/factories.ts
+// src/browser/factories.ts
 /** Creates a native table binding with one retained row owner.
 * @param element - The native table to bind.
 * @param document - The borrowed core document.
@@ -1075,7 +664,6 @@ var TableBinding = class {
 function createTableBinding(element, document, options) {
 	return new TableBinding(element, document, options);
 }
-//#endregion
 export { TableBinding, TableBindingError, createTableBinding, isTableBindingError, readTable, readTableRows, readTableSchema };
 
 //# sourceMappingURL=index.js.map