@orkestrel/table 0.0.4 → 0.0.6

package/README.md

@@ -1,14 +1,14 @@
 # @orkestrel/table
 
-The environment-agnostic tabular document for the `@orkestrel` line — a schema of typed column cells,
-the rows held against it, and one lens of sort, filter, and page that decides which of them the view
-shows. A grid, a report, a terminal listing, and a CSV export hold the same thing in different
-places, so this package ships what they share and draws none of it. Every row carries its own
-identity in a column the schema names, so a pick survives a re-sort; `view` and every tally are
-worked out on read, so no second copy of an answer can go stale; and budgets bound what one
-schema may retain, so a document that arrives from a wire costs a known maximum before anything
-decides to trust it.
-Built on `@orkestrel/contract` and `@orkestrel/emitter`.
+> The environment-agnostic tabular document: a `TableSchema` declaring the columns, a `Table`
+> holding the rows given against it, and one lens of sort, filter, and page deciding which of them
+> the view shows.
+
+Open a table with the `createTable` function, seed or add its rows through `table.rows`, and read
+`table.view` for the rows to draw. Every row carries its own identity in a column the schema names,
+so a pick survives a re-sort, and budgets bound what one schema may retain, so a document that
+arrives from a wire costs a known maximum before anything decides to trust it. Built on
+`@orkestrel/contract` and `@orkestrel/emitter`, and part of the `@orkestrel` line.
 
 ## Install
 
@@ -23,8 +23,6 @@ npm install @orkestrel/table
 
 ## Usage
 
-Declare the columns, hold the rows, and read the ones to draw:
-
 ```ts
 import { createTable } from '@orkestrel/table'
 

package/dist/src/core/index.cjs

@@ -9,21 +9,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;
@@ -44,18 +49,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 (0, _orkestrel_contract.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.
@@ -65,7 +71,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.
@@ -77,7 +84,8 @@ function extractKey(schema, row) {
 	return (0, _orkestrel_contract.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.
@@ -87,7 +95,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 : (0, _orkestrel_contract.isArray)(input) ? input : [input];
 	const population = new Set(known);
 	if (requested.some((key) => !population.has(key))) return void 0;
 	const next = new Set(current);
@@ -96,7 +104,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.
@@ -114,7 +123,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.
@@ -125,7 +135,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.
@@ -140,7 +151,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.
@@ -156,7 +168,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.
@@ -182,7 +194,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.
@@ -197,7 +210,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.
@@ -213,7 +226,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.
@@ -231,7 +245,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.
@@ -259,7 +274,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.
@@ -358,7 +374,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.
@@ -397,7 +414,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.
@@ -425,7 +443,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.
@@ -434,7 +453,8 @@ function isTableCell(input) {
 	return (0, _orkestrel_contract.unionOf)(_orkestrel_contract.isString, _orkestrel_contract.isFiniteNumber, _orkestrel_contract.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.
@@ -456,7 +476,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.
@@ -473,7 +494,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.
@@ -515,7 +537,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.
@@ -538,7 +561,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
@@ -560,7 +584,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.
@@ -591,7 +616,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.
@@ -605,7 +630,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.
@@ -776,7 +802,7 @@ var FilterManager = class {
 	/** Filters one column or several. */
 	set(input) {
 		this.#gate();
-		const requested = Array.isArray(input) ? input : [input];
+		const requested = (0, _orkestrel_contract.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;
@@ -788,7 +814,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) : (0, _orkestrel_contract.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) {
@@ -883,7 +909,7 @@ var PaginationManager = class {
 		this.#emitter.emit("paginate", nextPage);
 	}
 	#normalize(value) {
-		return Number.isFinite(value) ? Math.max(1, Math.trunc(value)) : 1;
+		return (0, _orkestrel_contract.isFiniteNumber)(value) ? Math.max(1, Math.trunc(value)) : 1;
 	}
 };
 //#endregion
@@ -929,7 +955,7 @@ var RowManager = class {
 	/** Appends one row or several. */
 	add(input) {
 		this.#gate();
-		const rows = Array.isArray(input) ? input : [input];
+		const rows = (0, _orkestrel_contract.isArray)(input) ? input : [input];
 		const keys = /* @__PURE__ */ new Set();
 		for (const row of this.#read()) {
 			const key = extractKey(this.#schema, row);
@@ -948,7 +974,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 = ((0, _orkestrel_contract.isArray)(input) ? input : [input]).map((row) => cloneRow(row));
 		const current = this.#read();
 		const locations = [];
 		for (const update of updates) {
@@ -1008,7 +1034,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];
+		}) : (0, _orkestrel_contract.isArray)(input) ? input : [input];
 		const keys = new Set(requested);
 		const known = new Set(current.flatMap((row) => {
 			const key = extractKey(this.#schema, row);
@@ -1131,7 +1157,7 @@ var SortManager = class {
 	/** Sorts by one column or several. */
 	set(input) {
 		this.#gate();
-		const requested = Array.isArray(input) ? input : [input];
+		const requested = (0, _orkestrel_contract.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;
@@ -1141,7 +1167,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) : (0, _orkestrel_contract.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) {
@@ -1156,7 +1182,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;
@@ -1324,17 +1353,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) {