@orkestrel/table 0.0.4 → 0.0.6

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isRecord, isString, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
+import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isInstance, isRecord, isString, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /** Lists every column cell, in the order declared by the public contract. */
@@ -8,21 +8,26 @@ var COLUMN_CELLS = Object.freeze([
 	"flag",
 	"choice"
 ]);
-/** Names the maximum number of columns one schema may declare. */
+/** Names the maximum number of columns one schema may declare: 256. */
 var COLUMN_LIMIT = 256;
-/** Names 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;
-/** Names 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;
-/** Names 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;
-/** Names 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;
-/** Names 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
-/** Represents 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 {
 	/** Holds the machine-readable reason for this failure. */
 	code;
@@ -43,18 +48,19 @@ var TableError = class extends Error {
 	}
 };
 /**
-* Determines 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 True if the value is a {@link TableError} instance; false otherwise.
 */
 function isTableError(input) {
-	return input instanceof TableError;
+	return isInstance(input, TableError);
 }
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Finds 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);
 }
 /**
-* Reads 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;
 }
 /**
-* Computes 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.
@@ -86,7 +94,7 @@ function extractKey(schema, row) {
 *   set when membership changes.
 */
 function computeKeys(known, current, input, include) {
-	const requested = input === void 0 ? known : Array.isArray(input) ? input : [input];
+	const requested = input === void 0 ? known : isArray(input) ? input : [input];
 	const population = new Set(known);
 	if (requested.some((key) => !population.has(key))) return void 0;
 	const next = new Set(current);
@@ -95,7 +103,8 @@ function computeKeys(known, current, input, include) {
 	return next.size !== current.size || [...next].some((key) => !current.has(key)) ? next : current;
 }
 /**
-* Merges lens terms into a column-keyed list, replacing the entry that names the same column.
+* 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.
@@ -113,7 +122,8 @@ function mergeTerms(current, requested) {
 	return Object.freeze(next);
 }
 /**
-* Removes every lens term naming one of the given columns.
+* 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.
@@ -124,7 +134,8 @@ function removeTerms(current, columns) {
 	return Object.freeze(current.filter((term) => !removed.has(term.column)));
 }
 /**
-* Checks whether two lens lists hold the same terms in the same order.
+* 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.
@@ -139,7 +150,8 @@ function matchesTerms(left, right, equal) {
 	});
 }
 /**
-* Checks whether a value has the shape required by one column cell.
+* 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.
@@ -155,7 +167,7 @@ function matchesCell(column, value) {
 	}
 }
 /**
-* Compares 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.
@@ -181,7 +193,8 @@ function compareCells(column, left, right) {
 	}
 }
 /**
-* Checks 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.
@@ -196,7 +209,7 @@ function admitsFilter(column, filter) {
 	}
 }
 /**
-* Tests 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.
@@ -212,7 +225,8 @@ function matchesFilter(column, cell, filter) {
 	}
 }
 /**
-* Keeps 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.
@@ -230,7 +244,8 @@ function filterRows(schema, rows, filters, matchers) {
 	})));
 }
 /**
-* Orders 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.
@@ -258,7 +273,8 @@ function sortRows(schema, rows, orders, comparators) {
 	return Object.freeze(indexed.map((entry) => entry.row));
 }
 /**
-* Audits 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.
@@ -357,7 +373,8 @@ function auditTable(schema) {
 	return Object.freeze(faults);
 }
 /**
-* Projects 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.
@@ -396,7 +413,8 @@ function serializeTable(schema) {
 	}
 }
 /**
-* Projects 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.
@@ -424,7 +442,8 @@ function serializeRows(schema, rows) {
 //#endregion
 //#region src/core/validators.ts
 /**
-* Determines 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 True if the value is a string, finite number, or boolean; false otherwise.
@@ -433,7 +452,8 @@ function isTableCell(input) {
 	return unionOf(isString, isFiniteNumber, isBoolean)(input);
 }
 /**
-* Determines 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 True if every own key is a string and every value is a table cell; false otherwise.
@@ -455,7 +475,8 @@ function isColumnCell(input) {
 	return COLUMN_CELLS.some((cell) => cell === input);
 }
 /**
-* Determines 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 True if the value is a column choice; false otherwise.
@@ -472,7 +493,8 @@ function isColumnChoice(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determines 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 True if the value is a structurally valid table column; false otherwise.
@@ -514,7 +536,8 @@ function isTableColumn(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determines 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 True if the value has the exact structure of a table schema; false otherwise.
@@ -537,7 +560,8 @@ function isStructuralTableSchema(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determines 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 True if the value has valid structure, domain relationships, and
@@ -559,7 +583,8 @@ function cloneRow(row) {
 	return Object.freeze({ ...row });
 }
 /**
-* Clones 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.
@@ -590,7 +615,7 @@ function cloneSchema(schema) {
 //#endregion
 //#region src/core/parsers.ts
 /**
-* Parses 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.
@@ -604,7 +629,8 @@ function parseTable(input) {
 	return outcome.success ? outcome.value : void 0;
 }
 /**
-* Parses 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.
@@ -775,7 +801,7 @@ var FilterManager = class {
 	/** Filters one column or several. */
 	set(input) {
 		this.#gate();
-		const requested = Array.isArray(input) ? input : [input];
+		const requested = isArray(input) ? input : [input];
 		for (const filter of requested) this.#validate(filter);
 		const next = mergeTerms(this.#read(), requested);
 		if (matchesTerms(next, this.#read(), (filter, other) => this.#operands(filter, other))) return;
@@ -787,7 +813,7 @@ var FilterManager = class {
 	/** 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];
+		const columns = input === void 0 ? this.#schema.columns.map((column) => column.key) : isArray(input) ? input : [input];
 		for (const column of columns) if (extractColumn(this.#schema, column) === void 0) return false;
 		const next = removeTerms(this.#read(), columns);
 		if (next.length !== this.#read().length) {
@@ -882,7 +908,7 @@ var PaginationManager = class {
 		this.#emitter.emit("paginate", nextPage);
 	}
 	#normalize(value) {
-		return Number.isFinite(value) ? Math.max(1, Math.trunc(value)) : 1;
+		return isFiniteNumber(value) ? Math.max(1, Math.trunc(value)) : 1;
 	}
 };
 //#endregion
@@ -928,7 +954,7 @@ var RowManager = class {
 	/** Appends one row or several. */
 	add(input) {
 		this.#gate();
-		const rows = Array.isArray(input) ? input : [input];
+		const rows = isArray(input) ? input : [input];
 		const keys = /* @__PURE__ */ new Set();
 		for (const row of this.#read()) {
 			const key = extractKey(this.#schema, row);
@@ -947,7 +973,7 @@ var RowManager = class {
 	/** 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));
+		const updates = (isArray(input) ? input : [input]).map((row) => cloneRow(row));
 		const current = this.#read();
 		const locations = [];
 		for (const update of updates) {
@@ -1007,7 +1033,7 @@ var RowManager = class {
 		const requested = input === void 0 ? current.flatMap((row) => {
 			const key = extractKey(this.#schema, row);
 			return key === void 0 ? [] : [key];
-		}) : Array.isArray(input) ? input : [input];
+		}) : isArray(input) ? input : [input];
 		const keys = new Set(requested);
 		const known = new Set(current.flatMap((row) => {
 			const key = extractKey(this.#schema, row);
@@ -1130,7 +1156,7 @@ var SortManager = class {
 	/** Sorts by one column or several. */
 	set(input) {
 		this.#gate();
-		const requested = Array.isArray(input) ? input : [input];
+		const requested = isArray(input) ? input : [input];
 		for (const order of requested) this.#require(order.column);
 		const next = mergeTerms(this.#read(), requested);
 		if (matchesTerms(next, this.#read(), (order, other) => order.direction === other.direction)) return;
@@ -1140,7 +1166,7 @@ var SortManager = class {
 	/** 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];
+		const columns = input === void 0 ? this.#schema.columns.map((column) => column.key) : isArray(input) ? input : [input];
 		for (const column of columns) if (extractColumn(this.#schema, column) === void 0) return false;
 		const next = removeTerms(this.#read(), columns);
 		if (next.length !== this.#read().length) {
@@ -1155,7 +1181,10 @@ var SortManager = class {
 };
 //#endregion
 //#region src/core/Table.ts
-/** Holds 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;
@@ -1323,17 +1352,43 @@ var Table = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Opens 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) {