@orkestrel/table 0.0.4 → 0.0.6

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

@@ -1,10 +1,11 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { JSONRecord } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { JSONRecord } from '@orkestrel/contract';
 
 /**
- * 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.
@@ -13,7 +14,8 @@ import { JSONRecord } from '@orkestrel/contract';
 export declare function admitsFilter(column: TableColumn, filter: TableFilter): boolean;
 
 /**
- * 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.
@@ -21,11 +23,12 @@ export declare function admitsFilter(column: TableColumn, filter: TableFilter):
 export declare function auditTable(schema: TableSchema): readonly string[];
 
 /**
- * Keeps the rows whose cell falls between these bounds, both included.
+ * Keeps the rows whose cell falls between `minimum` and `maximum`, both included, compared the
+ * way the column compares.
  *
  * @remarks
- * The bounds compare the way the column compares, so a `text` column holding ISO strings takes a
- * pair of ISO strings and reads as a date range.
+ * A `text` column holding ISO strings therefore takes a pair of ISO strings and reads as a date
+ * range.
  */
 export declare interface BetweenFilter {
     readonly column: string;
@@ -35,13 +38,13 @@ export declare interface BetweenFilter {
 }
 
 /**
- * Compares two cells of one column.
+ * Compares two cells of one column, replacing what its `cell` fixes. Always describes ascending
+ * order; direction is applied afterwards.
  *
  * @remarks
- * It replaces the comparison the column's {@link ColumnCell} fixes, for that column alone, and it
- * receives `undefined` for a row carrying no cell there. Sorting reads the result the way
- * `Array.prototype.sort` does and applies {@link TableDirection} afterwards, so a comparator
- * always describes ascending order.
+ * The replacement covers that column alone, and it receives `undefined` for a row carrying no
+ * cell there. Sorting reads the result the way `Array.prototype.sort` does and applies
+ * {@link TableDirection} to it.
  *
  * @param left - The first row's cell, or `undefined` when it carries none.
  * @param right - The second row's cell, or `undefined` when it carries none.
@@ -55,11 +58,12 @@ export declare interface BetweenFilter {
 export declare type CellComparator = (left: TableCell | undefined, right: TableCell | undefined) => number;
 
 /**
- * Tests one column's cell against a filter.
+ * Tests one column's cell against a filter, replacing what its `cell` fixes. Receives every
+ * filter the table holds against that column.
  *
  * @remarks
- * It replaces the test the column's {@link ColumnCell} fixes, for that column alone, and it
- * receives every filter the table holds against that column.
+ * The replacement covers that column alone, and it receives `undefined` for a row carrying no
+ * cell there.
  *
  * @param cell - The row's cell, or `undefined` when it carries none.
  * @param filter - The filter the table is applying.
@@ -72,11 +76,12 @@ export declare type CellComparator = (left: TableCell | undefined, right: TableC
  */
 export declare type CellMatcher = (cell: TableCell | undefined, filter: TableFilter) => boolean;
 
-/** Names the maximum number of choices one `choice` column may offer. */
+/** Names the maximum number of choices one `choice` column may offer: 1024. */
 export declare const CHOICE_LIMIT = 1024;
 
 /**
- * Represents a column drawn from a declared list, compared by the order that list declares.
+ * Represents a column drawn from a declared list, compared by the order that list declares. It
+ * requires `choices`.
  *
  * @remarks
  * A cell holding a value the list does not offer is refused at admission.
@@ -95,7 +100,8 @@ export declare interface ChoiceColumn extends ColumnBase {
 export declare function cloneRow(row: TableRow): TableRow;
 
 /**
- * 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.
@@ -105,11 +111,12 @@ export declare function cloneSchema(schema: TableSchema): TableSchema;
 /** Lists every column cell, in the order declared by the public contract. */
 export declare const COLUMN_CELLS: readonly ColumnCell[];
 
-/** Names the maximum number of columns one schema may declare. */
+/** Names the maximum number of columns one schema may declare: 256. */
 export declare const COLUMN_LIMIT = 256;
 
 /**
- * Describes what every column carries, whatever its cells hold.
+ * Describes what every column carries, whatever its cells hold — the name a row's cell uses, the
+ * text a reader sees, whether a host draws the column, and the metadata a host attaches to it.
  *
  * @remarks
  * `key` names the column, and it is the name a row uses for that column's cell. `label` is the
@@ -134,11 +141,12 @@ export declare interface ColumnBase {
 }
 
 /**
- * Names what a column's cells hold.
+ * Names what a column's cells hold — the discriminant that fixes the column's options, its
+ * comparison, and the filters that apply to it.
  *
  * @remarks
- * The cell is the discriminant of every {@link TableColumn} variant, so choosing it fixes what the
- * cells hold, how the column compares, and which filter operators apply to it.
+ * Every {@link TableColumn} variant is discriminated by it, so narrowing on the member reaches
+ * that variant's own options.
  *
  * A date, a time, and a timestamp are `text` holding a canonically spelled ISO string. Lexical
  * order is chronological only when a column uses one offset, one precision, and normalized
@@ -152,10 +160,10 @@ export declare interface ColumnBase {
 export declare type ColumnCell = 'text' | 'number' | 'flag' | 'choice';
 
 /**
- * Represents one value a `choice` column offers.
+ * Represents one value a `choice` column offers — `value` is stored, `label` is read, and `help`
+ * explains.
  *
  * @remarks
- * `value` is what the cell holds and `label` is what a reader sees. `help` explains the choice.
  * The order a column declares its choices in is the order that column sorts by, which is what
  * lets a status column sort draft before live before archived rather than alphabetically.
  */
@@ -166,7 +174,7 @@ export declare interface ColumnChoice {
 }
 
 /**
- * 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.
@@ -176,7 +184,8 @@ export declare interface ColumnChoice {
 export declare function compareCells(column: TableColumn, left: TableCell | undefined, right: TableCell | undefined): number;
 
 /**
- * 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.
@@ -187,7 +196,7 @@ export declare function compareCells(column: TableColumn, left: TableCell | unde
  */
 export declare function computeKeys(known: readonly TableKey[], current: ReadonlySet<TableKey>, input: TableKey | readonly TableKey[] | undefined, include: (included: boolean) => boolean): ReadonlySet<TableKey> | undefined;
 
-/** Keeps the rows whose cell holds this text somewhere inside it. */
+/** Keeps the rows whose cell holds this `text` somewhere inside it. */
 export declare interface ContainsFilter {
     readonly column: string;
     readonly operator: 'contains';
@@ -195,22 +204,48 @@ export declare interface ContainsFilter {
 }
 
 /**
- * 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
  * ```
  */
 export declare function createTable(schema: TableSchema, options?: TableOptions): TableInterface;
 
-/** Keeps the rows whose cell holds exactly this value. */
+/** Keeps the rows whose cell holds exactly this `value`. */
 export declare interface EqualsFilter {
     readonly column: string;
     readonly operator: 'equals';
@@ -233,7 +268,7 @@ export declare interface EqualsFilter {
 export declare interface ExpansionManagerInterface {
     /** Holds the keys of the rows opened right now. */
     readonly keys: ReadonlySet<TableKey>;
-    /** Opens every row the table holds. */
+    /** Opens every row the table holds, one row, or several. */
     expand(): void;
     /**
      * Opens one row.
@@ -250,7 +285,9 @@ export declare interface ExpansionManagerInterface {
      *   checked before any row opens.
      */
     expand(keys: readonly TableKey[]): boolean;
-    /** Closes every row. */
+    /**
+     * Closes every row, one row, or several. A known key that was not open still answers `true`.
+     */
     clear(): void;
     /**
      * Closes one row.
@@ -269,7 +306,8 @@ export declare interface ExpansionManagerInterface {
      */
     clear(keys: readonly TableKey[]): boolean;
     /**
-     * Opens one row, or closes it when it is already open.
+     * Opens one row, or closes it when it is already open; over a list, turns each row around on
+     * its own.
      *
      * @param key - The row's key.
      * @returns True if the key named a row the table holds; false otherwise.
@@ -286,7 +324,7 @@ export declare interface ExpansionManagerInterface {
 }
 
 /**
- * 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.
@@ -295,7 +333,8 @@ export declare interface ExpansionManagerInterface {
 export declare function extractColumn(schema: TableSchema, key: string): TableColumn | undefined;
 
 /**
- * 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.
@@ -317,20 +356,22 @@ export declare function extractKey(schema: TableSchema, row: TableRow): TableKey
  */
 export declare interface FilterManagerInterface {
     /**
-     * Finds one column's filter.
+     * Finds one column's filter; `undefined` when nothing filters that column.
      *
      * @param column - The column's key.
      * @returns The filter, or `undefined` when nothing filters that column.
      */
     filter(column: string): TableFilter | undefined;
     /**
-     * Reads every filter the table keeps rows by.
+     * Reads every filter the table keeps rows by, in the order they were set.
      *
-     * @returns The filters, in the order they were set.
+     * @returns The filters the table keeps rows by.
      */
     filters(): readonly TableFilter[];
     /**
-     * Filters several columns.
+     * Filters one column or several. A filter for a column already filtered replaces it; every
+     * other one joins the end. An undeclared column raises `COLUMN`, and a filter the column does
+     * not admit raises `CELL`.
      *
      * @param filters - The filters to set. A filter for a column already filtered replaces that
      *   column's filter; every other one joins the end of the list.
@@ -347,7 +388,10 @@ export declare interface FilterManagerInterface {
      *   not declare, and `CELL` when an operand is one the column cannot hold.
      */
     set(filter: TableFilter): void;
-    /** Stops filtering by anything. */
+    /**
+     * Stops filtering everything, one column, or several. An undeclared column returns `false` and
+     * stops nothing.
+     */
     remove(): void;
     /**
      * Stops filtering one column.
@@ -367,7 +411,7 @@ export declare interface FilterManagerInterface {
 }
 
 /**
- * Names how a filter tests a cell.
+ * Names how a filter tests a cell — the operator each filter carries.
  *
  * @remarks
  * `contains` looks for text inside a `text` or `choice` cell. `between` accepts a cell inside a
@@ -380,7 +424,8 @@ export declare interface FilterManagerInterface {
 export declare type FilterOperator = 'contains' | 'between' | 'equals';
 
 /**
- * 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.
@@ -404,7 +449,8 @@ export declare interface FlagColumn extends ColumnBase {
 export declare function isColumnCell(input: unknown): input is ColumnCell;
 
 /**
- * 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.
@@ -412,7 +458,8 @@ export declare function isColumnCell(input: unknown): input is ColumnCell;
 export declare function isColumnChoice(input: unknown): input is ColumnChoice;
 
 /**
- * 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.
@@ -420,7 +467,8 @@ export declare function isColumnChoice(input: unknown): input is ColumnChoice;
 export declare function isStructuralTableSchema(input: unknown): input is TableSchema;
 
 /**
- * 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.
@@ -428,7 +476,8 @@ export declare function isStructuralTableSchema(input: unknown): input is TableS
 export declare function isTableCell(input: unknown): input is TableCell;
 
 /**
- * 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.
@@ -436,7 +485,8 @@ export declare function isTableCell(input: unknown): input is TableCell;
 export declare function isTableColumn(input: unknown): input is TableColumn;
 
 /**
- * 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.
@@ -444,7 +494,8 @@ export declare function isTableColumn(input: unknown): input is TableColumn;
 export declare function isTableError(input: unknown): input is TableError;
 
 /**
- * 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.
@@ -452,7 +503,8 @@ export declare function isTableError(input: unknown): input is TableError;
 export declare function isTableRow(input: unknown): input is TableRow;
 
 /**
- * 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
@@ -461,7 +513,8 @@ export declare function isTableRow(input: unknown): input is TableRow;
 export declare function isTableSchema(input: unknown): input is TableSchema;
 
 /**
- * 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.
@@ -470,7 +523,7 @@ export declare function isTableSchema(input: unknown): input is TableSchema;
 export declare function matchesCell(column: TableColumn, value: unknown): value is TableCell;
 
 /**
- * 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.
@@ -480,7 +533,8 @@ export declare function matchesCell(column: TableColumn, value: unknown): value
 export declare function matchesFilter(column: TableColumn, cell: TableCell | undefined, filter: TableFilter): boolean;
 
 /**
- * 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.
@@ -491,7 +545,8 @@ export declare function matchesFilter(column: TableColumn, cell: TableCell | und
 export declare function matchesTerms<Term extends TableTerm>(left: readonly Term[], right: readonly Term[], equal: (left: Term, right: Term) => boolean): boolean;
 
 /**
- * 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.
@@ -500,10 +555,10 @@ export declare function matchesTerms<Term extends TableTerm>(left: readonly Term
  */
 export declare function mergeTerms<Term extends TableTerm>(current: readonly Term[], requested: readonly Term[]): readonly Term[];
 
-/** 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. */
 export declare const NAME_LIMIT = 128;
 
-/** 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. */
 export declare const NODE_LIMIT = 16384;
 
 /** Represents a column of numbers, compared by magnitude. */
@@ -538,18 +593,18 @@ export declare interface PaginationManagerInterface {
     /** Counts the pages the rows admitted by the filter fill, and `1` when the table is not paged. */
     readonly count: number;
     /**
-     * Shows another page.
+     * Shows another page, counted from one and clamped to the pages that exist.
      *
      * @param page - The page to show, counted from one and clamped to the pages that exist. `NaN`
      *   shows the first page.
      */
     move(page: number): void;
     /**
-     * Sets how many rows a page holds.
+     * Sets how many rows a page holds, keeping the first row the view was showing. Leave the
+     * argument out to stop paging.
      *
      * @remarks
-     * The view keeps showing the first of the rows it was showing, so the page moves to wherever
-     * that row now falls.
+     * The page moves to wherever that first row now falls.
      *
      * @param limit - How many rows a page holds. Leave it out to stop paging, and the view shows
      *   every row the filter admits.
@@ -558,7 +613,8 @@ export declare interface PaginationManagerInterface {
 }
 
 /**
- * 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.
@@ -567,7 +623,7 @@ export declare interface PaginationManagerInterface {
 export declare function parseRows(schema: TableSchema, input: unknown): readonly TableRow[] | undefined;
 
 /**
- * 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.
@@ -575,7 +631,8 @@ export declare function parseRows(schema: TableSchema, input: unknown): readonly
 export declare function parseTable(input: unknown): TableSchema | undefined;
 
 /**
- * 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.
@@ -598,20 +655,21 @@ export declare function removeTerms<Term extends TableTerm>(current: readonly Te
  */
 export declare interface RowManagerInterface {
     /**
-     * Finds one row by key.
+     * Finds one row by key; `undefined` when the table holds no such key.
      *
      * @param key - The row's key.
      * @returns The row, or `undefined` when the table holds no such key.
      */
     row(key: TableKey): TableRow | undefined;
     /**
-     * Reads every row the table holds, in its own order.
+     * Reads every row the table holds, in its own order — unfiltered, unsorted, and unpaged.
      *
-     * @returns The rows, unfiltered, unsorted, and unpaged.
+     * @returns The rows, in the order the table holds them.
      */
     rows(): readonly TableRow[];
     /**
-     * Takes in several rows, appending them in the order given.
+     * Takes in one row or several, appending them in the order given. Every row is checked before
+     * any is admitted.
      *
      * @param rows - The rows to admit.
      * @throws A {@link TableError} coded `KEY` when a row's key is missing, unusable, already
@@ -628,7 +686,8 @@ export declare interface RowManagerInterface {
      */
     add(row: TableRow): void;
     /**
-     * Writes over several rows, each found by the key it carries.
+     * Writes over one row or several, each found by the key it carries. The cells given replace;
+     * the cells left out stay.
      *
      * @param rows - The rows to write, each carrying the key of the row it writes over.
      * @returns True if every key named a row the table holds; false otherwise.
@@ -649,7 +708,8 @@ export declare interface RowManagerInterface {
      */
     update(row: TableRow): boolean;
     /**
-     * Moves one row to another place in the table's own order.
+     * Moves one row to another place in the table's own order, counted from zero and clamped to the
+     * rows that exist.
      *
      * @param key - The row's key.
      * @param index - Where to put it, counted from zero and clamped to the rows that exist. `NaN`
@@ -658,10 +718,8 @@ export declare interface RowManagerInterface {
      */
     move(key: TableKey, index: number): boolean;
     /**
-     * Takes out every row.
-     *
-     * @remarks
-     * Selection and expansion drop the keys they held, because those rows are gone.
+     * Takes out every row, one row, or several. Selection and expansion drop the keys of the rows
+     * that went.
      */
     remove(): void;
     /**
@@ -698,11 +756,10 @@ export declare interface SelectionManagerInterface {
     /** Holds the keys of the rows picked right now. */
     readonly keys: ReadonlySet<TableKey>;
     /**
-     * Picks every row the table holds.
+     * Picks every row the table holds, one row, or several. Every row, not every visible one.
      *
      * @remarks
-     * Every row, not every visible one. A host picking one page hands that page's keys over
-     * instead.
+     * A host picking one page hands that page's keys over instead.
      */
     select(): void;
     /**
@@ -720,7 +777,9 @@ export declare interface SelectionManagerInterface {
      *   checked before any row is picked.
      */
     select(keys: readonly TableKey[]): boolean;
-    /** Drops every pick. */
+    /**
+     * Drops every pick, one pick, or several. A known key that was not picked still answers `true`.
+     */
     clear(): void;
     /**
      * Drops one pick.
@@ -739,7 +798,8 @@ export declare interface SelectionManagerInterface {
      */
     clear(keys: readonly TableKey[]): boolean;
     /**
-     * Picks one row, or drops it when it is already picked.
+     * Picks one row, or drops it when it is already picked; over a list, turns each row around on
+     * its own.
      *
      * @param key - The row's key.
      * @returns True if the key named a row the table holds; false otherwise.
@@ -756,7 +816,8 @@ export declare interface SelectionManagerInterface {
 }
 
 /**
- * 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.
@@ -765,7 +826,8 @@ export declare interface SelectionManagerInterface {
 export declare function serializeRows(schema: TableSchema, rows: readonly TableRow[]): readonly JSONRecord[];
 
 /**
- * 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.
@@ -789,20 +851,21 @@ export declare function serializeTable(schema: TableSchema): JSONRecord;
  */
 export declare interface SortManagerInterface {
     /**
-     * Finds one column's term.
+     * Finds one column's term; `undefined` when nothing sorts that column.
      *
      * @param column - The column's key.
      * @returns The term, or `undefined` when nothing sorts that column.
      */
     order(column: string): TableOrder | undefined;
     /**
-     * Reads every term the table sorts by.
+     * Reads every term the table sorts by, first to last, in the order they decide.
      *
-     * @returns The terms, first to last, in the order they decide.
+     * @returns The terms the table sorts by.
      */
     orders(): readonly TableOrder[];
     /**
-     * Sorts by several columns.
+     * Sorts by one column or several. A term for a column already sorted replaces its direction in
+     * place; every other term joins the end. An undeclared column raises `COLUMN`.
      *
      * @param orders - The terms to set. A term for a column already sorted replaces that column's
      *   direction in place; every other term joins the end of the list.
@@ -818,7 +881,10 @@ export declare interface SortManagerInterface {
      *   declare.
      */
     set(order: TableOrder): void;
-    /** Stops sorting by anything. */
+    /**
+     * Stops sorting by everything, by one column, or by several. An undeclared column returns
+     * `false` and stops nothing.
+     */
     remove(): void;
     /**
      * Stops sorting by one column.
@@ -838,7 +904,8 @@ export declare interface SortManagerInterface {
 }
 
 /**
- * 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.
@@ -848,10 +915,13 @@ export declare interface SortManagerInterface {
  */
 export declare function sortRows(schema: TableSchema, rows: readonly TableRow[], orders: readonly TableOrder[], comparators?: Readonly<Record<string, CellComparator>>): readonly TableRow[];
 
-/** 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. */
 export declare const STRING_LIMIT = 65536;
 
-/** 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.
+ */
 export declare class Table implements TableInterface {
     #private;
     /**
@@ -892,7 +962,7 @@ export declare class Table implements TableInterface {
 }
 
 /**
- * Represents every value a cell can hold.
+ * Represents every value a cell can hold — a `string`, a `number`, or a `boolean`.
  *
  * @remarks
  * The variant follows the column: `text` and `choice` hold a `string`, `number` holds a `number`,
@@ -902,11 +972,10 @@ export declare class Table implements TableInterface {
 export declare type TableCell = string | number | boolean;
 
 /**
- * Represents any column a schema can declare.
+ * Represents any column a schema can declare — the union discriminated on `cell`.
  *
  * @remarks
- * The union discriminates on `cell`, so narrowing on that member reaches each variant's own
- * members.
+ * Narrowing on `cell` reaches each variant's own members.
  *
  * @example
  * ```ts
@@ -918,15 +987,17 @@ export declare type TableCell = string | number | boolean;
 export declare type TableColumn = TextColumn | NumberColumn | FlagColumn | ChoiceColumn;
 
 /**
- * Names which way a column sorts.
+ * Names which way a column sorts. A column nobody has sorted carries no term at all.
  *
  * @remarks
- * A column nobody has sorted has no {@link TableOrder} at all, so there is no third member
- * standing for unsorted.
+ * No member of this union stands for unsorted; that state is the missing {@link TableOrder}.
  */
 export declare type TableDirection = 'ascending' | 'descending';
 
-/** Represents an error raised by the table domain. */
+/**
+ * Represents an error raised by the table domain — a machine-readable `code` and optional
+ * structured `context`.
+ */
 export declare class TableError extends Error {
     /** Holds the machine-readable reason for this failure. */
     readonly code: TableErrorCode;
@@ -943,7 +1014,7 @@ export declare class TableError extends Error {
 }
 
 /**
- * Names the machine-readable code a table error carries.
+ * Names the reason a {@link TableError} carries — the machine-readable code a `catch` branches on.
  *
  * @remarks
  * `SCHEMA` rejects a malformed schema, including a `key` naming no declared column. `COLUMN`
@@ -954,7 +1025,7 @@ export declare class TableError extends Error {
 export declare type TableErrorCode = 'SCHEMA' | 'COLUMN' | 'KEY' | 'CELL' | 'DESTROYED';
 
 /**
- * Lists everything a table announces.
+ * Lists everything a table announces, mapping each event to the payload its listeners receive.
  *
  * @remarks
  * Every event fires after the state it reports is committed, and only when something actually
@@ -984,11 +1055,11 @@ export declare type TableEventMap = {
 };
 
 /**
- * Represents any filter a table can hold.
+ * Represents any filter a table can hold — the union discriminated on `operator`.
  *
  * @remarks
- * The union discriminates on `operator`, so each operator carries only the operands it uses and a
- * `between` missing a bound cannot be written down.
+ * Each operator carries only the operands it uses, so a `between` missing a bound cannot be
+ * written down.
  *
  * A table holds at most one filter per column and keeps every row all of them accept. There is no
  * either-or composition in this version.
@@ -1049,31 +1120,32 @@ export declare interface TableInterface {
     /** Reports whether the table has been torn down. */
     readonly destroyed: boolean;
     /**
-     * Puts the table back the way it opened, holding nothing.
+     * Puts the table back the way it opened, holding nothing. Rows, sort, filter, selection,
+     * expansion, and the page all reset.
      *
      * @remarks
-     * Every row goes, and sort, filter, selection, expansion, and the page all reset. The table
-     * emits `clear` and nothing else, so a reset of ten thousand rows is one announcement.
+     * The table emits `clear` and nothing else, so a reset of ten thousand rows is one
+     * announcement.
      */
     clear(): void;
     /**
-     * Tears the table down.
+     * Tears the table down. Idempotent; afterwards every write raises `DESTROYED` and every getter
+     * still answers.
      *
      * @remarks
-     * Calling it twice does what calling it once did. Afterwards every write throws a
-     * {@link TableError} coded `DESTROYED`, while every getter still answers what the table last
-     * held, so a host can read its way out of teardown without catching anything.
+     * The write throws a {@link TableError} carrying that code, and what a getter answers is what
+     * the table last held, so a host can read its way out of teardown without catching anything.
      */
     destroy(): void;
 }
 
 /**
- * Represents a row's identity.
+ * Represents a row's identity — a `string`, carried in the cell the schema's `key` names.
  *
  * @remarks
- * Every row carries its own identity in the cell named by {@link TableSchema.key}, as a non-empty
- * string. A column's own identifier is a plain `string`; this names a row. Selection and expansion
- * hold these keys and nothing else, so a row keeps its selection through a re-sort.
+ * The identity must be non-empty. A column's own identifier is a plain `string`; this names a row.
+ * Selection and expansion hold these keys and nothing else, so a row keeps its selection through a
+ * re-sort.
  *
  * @example
  * ```ts
@@ -1083,7 +1155,9 @@ export declare interface TableInterface {
 export declare type TableKey = string;
 
 /**
- * Describes how to open a table.
+ * Describes how to open a table — the listeners wired at construction and where a throw from one
+ * goes, the rows seeded into it, the per-column comparison and test replacements, and the page
+ * size.
  *
  * @remarks
  * `on` wires listeners at construction and `error` receives any throw from one of them.
@@ -1117,11 +1191,12 @@ export declare interface TableOptions {
 }
 
 /**
- * Represents one column's place in the sort.
+ * Represents one column's place in the sort — the `column` and its `direction`. The list is read
+ * left to right.
  *
  * @remarks
- * The order list is read left to right: the first term decides, and each later term breaks the
- * tie the terms before it left. Rows no term separates keep the order the table holds them in.
+ * The first term decides, and each later term breaks the tie the terms before it left. Rows no
+ * term separates keep the order the table holds them in.
  *
  * @example
  * ```ts
@@ -1134,12 +1209,11 @@ export declare interface TableOrder {
 }
 
 /**
- * Represents one row, keyed by column.
+ * Represents one row, keyed by column. A column nobody has filled has no key here.
  *
  * @remarks
- * A row declares a cell for the columns it carries and omits the rest. It carries no key the
- * schema does not declare, and the table clones and freezes it at admission, so nothing a caller
- * holds afterwards can move a stored row.
+ * A row carries no key the schema does not declare, and the table clones and freezes it at
+ * admission, so nothing a caller holds afterwards can move a stored row.
  *
  * @example
  * ```ts
@@ -1149,7 +1223,8 @@ export declare interface TableOrder {
 export declare type TableRow = Readonly<Record<string, TableCell>>;
 
 /**
- * Holds everything a table declares about itself.
+ * Holds everything a table declares about itself — how the table is described, which column
+ * carries row identity, and the columns it declares, in the order it declares them.
  *
  * @remarks
  * The schema is data. It carries no function, so all of it crosses a wire and nothing is dropped
@@ -1185,22 +1260,27 @@ export declare interface TableSchema {
 }
 
 /**
- * Represents one entry of a lens list, held against one declared column.
+ * Represents one entry of a lens list — the `column` it names. A sort term and a filter each hold
+ * one, which is why the two share a list engine.
  *
  * @remarks
  * A table holds at most one sort term and at most one filter per column, so `column` is what
  * places an entry in either list. {@link mergeTerms}, {@link removeTerms}, and
- * {@link matchesTerms} work over this shape alone, which is how sorting and filtering share one
- * list engine while keeping their own operands.
+ * {@link matchesTerms} work over this shape alone, so each list keeps its own operands.
  */
 export declare interface TableTerm {
     readonly column: string;
 }
 
-/** 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.
+ */
 export declare const TEXT_LIMIT = 1048576;
 
-/** Represents a column of text, compared lexically. */
+/**
+ * Represents a column of text, compared lexically. Carries a date, a time, and a timestamp as ISO
+ * strings.
+ */
 export declare interface TextColumn extends ColumnBase {
     readonly cell: 'text';
 }