@orkestrel/table 0.0.1

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

@@ -0,0 +1,1353 @@
+import { Emitter } from '@orkestrel/emitter';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { JSONRecord } from '@orkestrel/contract';
+
+/**
+ * Check whether one column admits a filter and all its operands.
+ *
+ * @param column - The column that fixes the accepted operators and cell shapes.
+ * @param filter - The filter to inspect.
+ * @returns Whether the filter belongs to the column and the column can apply it.
+ */
+export declare function admitsFilter(column: TableColumn, filter: TableFilter): boolean;
+
+/**
+ * Audit a structurally valid schema for domain and budget faults.
+ *
+ * @param schema - The table schema to audit.
+ * @returns Frozen human-readable diagnostics, or an empty list when the schema is sound.
+ */
+export declare function auditTable(schema: TableSchema): readonly string[];
+
+/**
+ * Keep the rows whose cell falls between these bounds, both included.
+ *
+ * @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.
+ */
+export declare interface BetweenFilter {
+    readonly column: string;
+    readonly operator: 'between';
+    readonly minimum: string | number;
+    readonly maximum: string | number;
+}
+
+/**
+ * Compare two cells of one column.
+ *
+ * @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.
+ *
+ * @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.
+ * @returns A negative number when `left` sorts first, a positive number when `right` does, and
+ *   zero when neither does.
+ * @example
+ * ```ts
+ * const natural: CellComparator = (left, right) => String(left).localeCompare(String(right))
+ * ```
+ */
+export declare type CellComparator = (left: TableCell | undefined, right: TableCell | undefined) => number;
+
+/**
+ * Test one column's cell against a filter.
+ *
+ * @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.
+ *
+ * @param cell - The row's cell, or `undefined` when it carries none.
+ * @param filter - The filter the table is applying.
+ * @returns `true` to keep the row.
+ * @example
+ * ```ts
+ * const loose: CellMatcher = (cell, filter) =>
+ * 	filter.operator === 'contains' && String(cell).toLowerCase().includes(filter.text.toLowerCase())
+ * ```
+ */
+export declare type CellMatcher = (cell: TableCell | undefined, filter: TableFilter) => boolean;
+
+/** The maximum number of choices one `choice` column may offer. */
+export declare const CHOICE_LIMIT = 1024;
+
+/**
+ * A column drawn from a declared list, compared by the order that list declares.
+ *
+ * @remarks
+ * A cell holding a value the list does not offer is refused at admission.
+ */
+export declare interface ChoiceColumn extends ColumnBase {
+    readonly cell: 'choice';
+    readonly choices: readonly ColumnChoice[];
+}
+
+/**
+ * Clone one row into an owned frozen snapshot.
+ *
+ * @param row - The row to own.
+ * @returns A frozen copy of the row's cells.
+ */
+export declare function cloneRow(row: TableRow): TableRow;
+
+/**
+ * Clone a table schema into an owned frozen snapshot.
+ *
+ * @param schema - The schema to own.
+ * @returns A frozen schema with every nested column, choice, list, and metadata record owned.
+ */
+export declare function cloneSchema(schema: TableSchema): TableSchema;
+
+/** Every column cell, in the order declared by the public contract. */
+export declare const COLUMN_CELLS: readonly ColumnCell[];
+
+/** The maximum number of columns one schema may declare. */
+export declare const COLUMN_LIMIT = 256;
+
+/**
+ * What every column carries, whatever its cells hold.
+ *
+ * @remarks
+ * `key` names the column, and it is the name a row uses for that column's cell. `label` is the
+ * heading a reader sees and `help` explains the column.
+ *
+ * `hidden` declares the column out of the presentation. It is still sorted, still filtered, and
+ * still serialized, because hiding is what a host draws rather than what the table holds.
+ *
+ * There is no `sortable` and no `filterable`. Every declared column sorts and filters; whether a
+ * heading offers either is the host's decision.
+ *
+ * `meta` is a bounded JSON carrier for whatever the schema declines to model. The table never
+ * reads it, no comparison sees it, and it round-trips verbatim. This package defines no key in
+ * it, so every key belongs to the host: an alignment, a format, a pixel width.
+ */
+export declare interface ColumnBase {
+    readonly key: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly hidden?: boolean;
+    readonly meta?: JSONRecord;
+}
+
+/**
+ * What a column's cells hold.
+ *
+ * @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.
+ *
+ * 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
+ * midnight spelling such as `00:00:00Z` instead of `24:00:00Z`. There is no temporal cell.
+ *
+ * @example
+ * ```ts
+ * const cell: ColumnCell = 'choice'
+ * ```
+ */
+export declare type ColumnCell = 'text' | 'number' | 'flag' | 'choice';
+
+/**
+ * One value a `choice` column offers.
+ *
+ * @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.
+ */
+export declare interface ColumnChoice {
+    readonly value: string;
+    readonly label: string;
+    readonly help?: string;
+}
+
+/**
+ * Compare two cells in ascending order according to one column.
+ *
+ * @param column - The column that fixes the comparison.
+ * @param left - The first cell, or absence.
+ * @param right - The second cell, or absence.
+ * @returns A negative number, positive number, or zero in sort-comparator form.
+ */
+export declare function compareCells(column: TableColumn, left: TableCell | undefined, right: TableCell | undefined): number;
+
+/**
+ * Compute one atomic 0/1/N membership change over known keys.
+ *
+ * @param known - Every key the caller may change.
+ * @param current - The current key set.
+ * @param input - Every known key, one key, or a key list.
+ * @param include - Decide the next membership from each key's membership at that step.
+ * @returns `undefined` when any requested key is unknown, the current set for a no-op, or the next
+ *   set when membership changes.
+ */
+export declare function computeKeys(known: readonly TableKey[], current: ReadonlySet<TableKey>, input: TableKey | readonly TableKey[] | undefined, include: (included: boolean) => boolean): ReadonlySet<TableKey> | undefined;
+
+/** Keep the rows whose cell holds this text somewhere inside it. */
+export declare interface ContainsFilter {
+    readonly column: string;
+    readonly operator: 'contains';
+    readonly text: string;
+}
+
+/**
+ * Open a table against a schema.
+ *
+ * @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
+ * ```ts
+ * const table = createTable({ key: 'id', columns: [{ cell: 'text', key: 'id' }] })
+ * table.rows.add({ id: '1' })
+ * ```
+ */
+export declare function createTable(schema: TableSchema, options?: TableOptions): TableInterface;
+
+/** Keep the rows whose cell holds exactly this value. */
+export declare interface EqualsFilter {
+    readonly column: string;
+    readonly operator: 'equals';
+    readonly value: TableCell;
+}
+
+/** The keys of the rows somebody has opened. */
+export declare class ExpansionManager implements ExpansionManagerInterface {
+    #private;
+    /**
+     * Create an expansion manager over one table's private stores.
+     *
+     * @param emitter - The table's event emitter.
+     * @param gate - The table lifecycle gate.
+     * @param rows - A read of every row key.
+     * @param read - A read of the expanded keys.
+     * @param write - The expanded-key commit boundary.
+     */
+    constructor(emitter: Emitter<TableEventMap>, gate: () => void, rows: () => readonly TableKey[], read: () => ReadonlySet<TableKey>, write: (keys: ReadonlySet<TableKey>) => void);
+    /** The keys of the rows opened right now. */
+    get keys(): ReadonlySet<TableKey>;
+    /** Open every row the table holds. */
+    expand(): void;
+    /** Open one row. */
+    expand(key: TableKey): boolean;
+    /** Open several rows. */
+    expand(keys: readonly TableKey[]): boolean;
+    /** Close every row. */
+    clear(): void;
+    /** Close one row. */
+    clear(key: TableKey): boolean;
+    /** Close several rows. */
+    clear(keys: readonly TableKey[]): boolean;
+    /** Open one row or close it when already open. */
+    toggle(key: TableKey): boolean;
+    /** Turn several rows around independently. */
+    toggle(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * The rows somebody has opened up.
+ *
+ * @remarks
+ * Expansion holds keys exactly as selection does, and what an opened row shows beside it is the
+ * host's to draw.
+ *
+ * @example
+ * ```ts
+ * table.expansion.toggle('7')
+ * table.expansion.keys.has('7') // true
+ * ```
+ */
+export declare interface ExpansionManagerInterface {
+    /** The keys of the rows opened right now. */
+    readonly keys: ReadonlySet<TableKey>;
+    /** Open every row the table holds. */
+    expand(): void;
+    /**
+     * Open one row.
+     *
+     * @param key - The row's key.
+     * @returns `true` when the key named a row the table holds.
+     */
+    expand(key: TableKey): boolean;
+    /**
+     * Open several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns `true` when every key named a row the table holds. Every key is checked before any
+     *   row opens.
+     */
+    expand(keys: readonly TableKey[]): boolean;
+    /** Close every row. */
+    clear(): void;
+    /**
+     * Close one row.
+     *
+     * @param key - The row's key.
+     * @returns `true` when the key named a row the table holds, whether or not it was open.
+     */
+    clear(key: TableKey): boolean;
+    /**
+     * Close several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns `true` when every key named a row the table holds. Every key is checked before any
+     *   row closes.
+     */
+    clear(keys: readonly TableKey[]): boolean;
+    /**
+     * Open one row, or close it when it is already open.
+     *
+     * @param key - The row's key.
+     * @returns `true` when the key named a row the table holds.
+     */
+    toggle(key: TableKey): boolean;
+    /**
+     * Turn several rows around, each on its own.
+     *
+     * @param keys - The rows' keys.
+     * @returns `true` when every key named a row the table holds. Every key is checked before any
+     *   row turns.
+     */
+    toggle(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * Find one column by key.
+ *
+ * @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.
+ */
+export declare function extractColumn(schema: TableSchema, key: string): TableColumn | undefined;
+
+/**
+ * Read one row's declared identity.
+ *
+ * @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.
+ */
+export declare function extractKey(schema: TableSchema, row: TableRow): TableKey | undefined;
+
+/** The filters one table applies with and-only composition. */
+export declare class FilterManager implements FilterManagerInterface {
+    #private;
+    /**
+     * Create a filter manager over one table's private filter store.
+     *
+     * @param schema - The table schema.
+     * @param emitter - The table's event emitter.
+     * @param gate - The table lifecycle gate.
+     * @param read - A read of the current filters.
+     * @param write - The filter commit boundary.
+     * @param clamp - The pagination clamp commit after a filter commit.
+     */
+    constructor(schema: TableSchema, emitter: Emitter<TableEventMap>, gate: () => void, read: () => readonly TableFilter[], write: (filters: readonly TableFilter[]) => void, clamp: () => number | undefined);
+    /** Find one column's filter. */
+    filter(column: string): TableFilter | undefined;
+    /** Read every filter as an owned frozen snapshot. */
+    filters(): readonly TableFilter[];
+    /** Filter several columns. */
+    set(filters: readonly TableFilter[]): void;
+    /** Filter one column. */
+    set(filter: TableFilter): void;
+    /** Stop filtering by every column. */
+    remove(): void;
+    /** Stop filtering by one column. */
+    remove(column: string): boolean;
+    /** Stop filtering by several columns. */
+    remove(columns: readonly string[]): boolean;
+}
+
+/**
+ * Which rows a table keeps.
+ *
+ * @remarks
+ * The table holds at most one filter per column and keeps the rows every filter accepts.
+ *
+ * @example
+ * ```ts
+ * table.filter.set({ column: 'name', operator: 'contains', text: 'ad' })
+ * table.count // how many rows are left
+ * ```
+ */
+export declare interface FilterManagerInterface {
+    /**
+     * Find one column's filter.
+     *
+     * @param column - The column's key.
+     * @returns The filter, or `undefined` when nothing filters that column.
+     */
+    filter(column: string): TableFilter | undefined;
+    /**
+     * Every filter the table keeps rows by.
+     *
+     * @returns The filters, in the order they were set.
+     */
+    filters(): readonly TableFilter[];
+    /**
+     * Filter several columns.
+     *
+     * @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.
+     * @throws A {@link TableError} coded `COLUMN` when a filter names a column the schema does not
+     *   declare, and `CELL` when an operand is one the column cannot hold. Every filter is checked
+     *   before any is set.
+     */
+    set(filters: readonly TableFilter[]): void;
+    /**
+     * Filter one column.
+     *
+     * @param filter - The filter to set.
+     * @throws A {@link TableError} coded `COLUMN` when the filter names a column the schema does
+     *   not declare, and `CELL` when an operand is one the column cannot hold.
+     */
+    set(filter: TableFilter): void;
+    /** Stop filtering by anything. */
+    remove(): void;
+    /**
+     * Stop filtering one column.
+     *
+     * @param column - The column's key.
+     * @returns `true` when the schema declares that column.
+     */
+    remove(column: string): boolean;
+    /**
+     * Stop filtering several columns.
+     *
+     * @param columns - The columns' keys.
+     * @returns `true` when the schema declares every one of them. Every key is checked before any
+     *   filter goes.
+     */
+    remove(columns: readonly string[]): boolean;
+}
+
+/**
+ * How a filter tests a cell.
+ *
+ * @remarks
+ * `contains` looks for text inside a `text` or `choice` cell. `between` accepts a cell inside a
+ * pair of bounds, comparing the way the column compares. `equals` accepts a cell holding exactly
+ * one value, which is what a `flag` or a `choice` asks for.
+ *
+ * A column needing anything else takes a {@link CellMatcher} through
+ * {@link TableOptions.matchers}, so the operator set stays small and the schema stays data.
+ */
+export declare type FilterOperator = 'contains' | 'between' | 'equals';
+
+/**
+ * Keep the rows accepted by every filter.
+ *
+ * @param schema - The schema that declares the filtered columns.
+ * @param rows - The rows to filter.
+ * @param filters - The filters to apply with and-only composition.
+ * @param matchers - Optional per-column replacements for the default matcher.
+ * @returns A frozen copy of the accepted rows in their original order.
+ */
+export declare function filterRows(schema: TableSchema, rows: readonly TableRow[], filters: readonly TableFilter[], matchers?: Readonly<Record<string, CellMatcher>>): readonly TableRow[];
+
+/** A column of yes-or-no answers, compared false before true. */
+export declare interface FlagColumn extends ColumnBase {
+    readonly cell: 'flag';
+}
+
+/**
+ * Determine whether an unknown value is a declared column cell.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is one of the four column cells.
+ */
+export declare function isColumnCell(input: unknown): input is ColumnCell;
+
+/**
+ * Determine whether an unknown value is one exact column choice record.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a column choice.
+ */
+export declare function isColumnChoice(input: unknown): input is ColumnChoice;
+
+/**
+ * Determine whether an unknown value has one exact structural table-schema shape.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value has the exact structure of a table schema.
+ */
+export declare function isStructuralTableSchema(input: unknown): input is TableSchema;
+
+/**
+ * Determine whether an unknown value has a table cell shape.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a string, finite number, or boolean.
+ */
+export declare function isTableCell(input: unknown): input is TableCell;
+
+/**
+ * Determine whether an unknown value is one exact discriminated table column.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a structurally valid table column.
+ */
+export declare function isTableColumn(input: unknown): input is TableColumn;
+
+/**
+ * Determine whether an unknown value is a table error.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a {@link TableError} instance.
+ */
+export declare function isTableError(input: unknown): input is TableError;
+
+/**
+ * Determine whether an unknown value is a record of table cells.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether every own key is a string and every value is a table cell.
+ */
+export declare function isTableRow(input: unknown): input is TableRow;
+
+/**
+ * Determine whether an unknown value is one semantically sound table schema.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value has valid structure, domain relationships, and budgets.
+ */
+export declare function isTableSchema(input: unknown): input is TableSchema;
+
+/**
+ * Check whether a value has the shape required by one column cell.
+ *
+ * @param column - The column that owns the cell.
+ * @param value - The unknown value to inspect.
+ * @returns Whether the column can hold the value.
+ */
+export declare function matchesCell(column: TableColumn, value: unknown): value is TableCell;
+
+/**
+ * Test one cell against a filter according to its column.
+ *
+ * @param column - The column that fixes the accepted operators.
+ * @param cell - The cell to test, or absence.
+ * @param filter - The filter to apply.
+ * @returns Whether the filter accepts the cell.
+ */
+export declare function matchesFilter(column: TableColumn, cell: TableCell | undefined, filter: TableFilter): boolean;
+
+/** The maximum length, in UTF-16 code units, of a schema name or column key. */
+export declare const NAME_LIMIT = 128;
+
+/** The maximum total number of records, arrays, and leaves one schema retains. */
+export declare const NODE_LIMIT = 16384;
+
+/** A column of numbers, compared by magnitude. */
+export declare interface NumberColumn extends ColumnBase {
+    readonly cell: 'number';
+}
+
+/** The page arithmetic over one table's filtered rows. */
+export declare class PaginationManager implements PaginationManagerInterface {
+    #private;
+    /**
+     * Create a pagination manager over one table's private stores.
+     *
+     * @param emitter - The table's event emitter.
+     * @param gate - The table lifecycle gate.
+     * @param rows - A read of the filtered row count.
+     * @param readPage - A read of the current page.
+     * @param writePage - The page commit boundary.
+     * @param readLimit - A read of the current page size.
+     * @param writeLimit - The page-size commit boundary.
+     */
+    constructor(emitter: Emitter<TableEventMap>, gate: () => void, rows: () => number, readPage: () => number, writePage: (page: number) => void, readLimit: () => number | undefined, writeLimit: (limit: number | undefined) => void);
+    /** The page shown, counted from one. */
+    get page(): number;
+    /** The number of rows one page holds. */
+    get limit(): number | undefined;
+    /** The number of filtered rows skipped before this page. */
+    get offset(): number;
+    /** The number of pages filled by the filtered rows. */
+    get count(): number;
+    /** Show another page, clamped to the pages that exist. */
+    move(page: number): void;
+    /** Change the page size while keeping the first row previously shown. */
+    resize(limit?: number): void;
+}
+
+/**
+ * Which stretch of the filtered rows the view shows.
+ *
+ * @remarks
+ * `page` is the state, counted from one. `offset` and `count` are worked out from it and from the
+ * rows the filter admits, so nothing here can drift out of step with what the table holds. A page
+ * beyond the last one clamps to the last one.
+ *
+ * `offset` counts the rows skipped, from zero, which is what a database query asks for.
+ *
+ * @example
+ * ```ts
+ * table.pagination.resize(10)
+ * table.pagination.move(3)
+ * table.pagination.offset // 20
+ * ```
+ */
+export declare interface PaginationManagerInterface {
+    /** The page the view shows, counted from one, and `1` when the table is not paged. */
+    readonly page: number;
+    /** How many rows a page holds, or `undefined` when the table is not paged. */
+    readonly limit: number | undefined;
+    /** How many rows the view skips before the page it shows, counted from zero. */
+    readonly offset: number;
+    /** How many pages the rows admitted by the filter fill, and `1` when the table is not paged. */
+    readonly count: number;
+    /**
+     * Show another page.
+     *
+     * @param page - The page to show, counted from one and clamped to the pages that exist.
+     */
+    move(page: number): void;
+    /**
+     * Say how many rows a page holds.
+     *
+     * @remarks
+     * The view keeps showing the first of the rows it was showing, so the page moves to wherever
+     * that 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.
+     */
+    resize(limit?: number): void;
+}
+
+/**
+ * Parse unknown wire rows against one table schema.
+ *
+ * @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.
+ */
+export declare function parseRows(schema: TableSchema, input: unknown): readonly TableRow[] | undefined;
+
+/**
+ * Parse unknown wire data into an owned, semantically sound table schema.
+ *
+ * @param input - The unknown schema value to parse.
+ * @returns An owned table schema, or `undefined` on refusal.
+ */
+export declare function parseTable(input: unknown): TableSchema | undefined;
+
+/** The rows one table holds in its own order. */
+export declare class RowManager implements RowManagerInterface {
+    #private;
+    /**
+     * Create a row manager over one table's private row store.
+     *
+     * @param schema - The table schema.
+     * @param emitter - The table's event emitter.
+     * @param gate - The table lifecycle gate.
+     * @param read - A read of the current rows.
+     * @param write - The row commit boundary.
+     * @param settle - Commit dependent state, then order row and dependent announcements.
+     * @param rows - Rows to seed without announcements.
+     */
+    constructor(schema: TableSchema, emitter: Emitter<TableEventMap>, gate: () => void, read: () => readonly TableRow[], write: (rows: readonly TableRow[]) => void, settle: (removed: readonly TableKey[], announce: () => void) => void, rows?: readonly TableRow[]);
+    /** Find one row by key as an owned frozen snapshot. */
+    row(key: TableKey): TableRow | undefined;
+    /** Read every row as owned frozen snapshots in table order. */
+    rows(): readonly TableRow[];
+    /** Append several rows. */
+    add(rows: readonly TableRow[]): void;
+    /** Append one row. */
+    add(row: TableRow): void;
+    /** Merge several rows into the rows their keys name. */
+    update(rows: readonly TableRow[]): boolean;
+    /** Merge one row into the row its key names. */
+    update(row: TableRow): boolean;
+    /** Move one row to a clamped index in table order. */
+    move(key: TableKey, index: number): boolean;
+    /** Remove every row. */
+    remove(): void;
+    /** Remove one row. */
+    remove(key: TableKey): boolean;
+    /** Remove several rows. */
+    remove(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * The rows a table holds, in the order it holds them.
+ *
+ * @remarks
+ * This order is the table's own, and it is what the view shows when no sort term separates two
+ * rows. Sorting reads it and never rewrites it.
+ *
+ * @example
+ * ```ts
+ * table.rows.add({ id: '7', name: 'Ada', age: 36 })
+ * table.rows.update({ id: '7', age: 37 })
+ * ```
+ */
+export declare interface RowManagerInterface {
+    /**
+     * Find one row by key.
+     *
+     * @param key - The row's key.
+     * @returns The row, or `undefined` when the table holds no such key.
+     */
+    row(key: TableKey): TableRow | undefined;
+    /**
+     * Every row the table holds, in its own order.
+     *
+     * @returns The rows, unfiltered, unsorted, and unpaged.
+     */
+    rows(): readonly TableRow[];
+    /**
+     * Take in several rows, appending them in the order given.
+     *
+     * @param rows - The rows to admit.
+     * @throws A {@link TableError} coded `KEY` when a row's key is missing, unusable, already
+     *   taken, or repeated inside the batch, and `CELL` when a cell is one its column cannot hold.
+     *   Every row is checked before any is admitted, so one refusal admits none of them.
+     */
+    add(rows: readonly TableRow[]): void;
+    /**
+     * Take in one row, appending it.
+     *
+     * @param row - The row to admit.
+     * @throws A {@link TableError} coded `KEY` when the row's key is missing, unusable, or already
+     *   taken, and `CELL` when a cell is one its column cannot hold.
+     */
+    add(row: TableRow): void;
+    /**
+     * Write over several rows, each found by the key it carries.
+     *
+     * @param rows - The rows to write, each carrying the key of the row it writes over.
+     * @returns `true` when every key named a row the table holds.
+     * @throws A {@link TableError} coded `CELL` when a cell is one its column cannot hold. Every
+     *   row is checked before any is written, so one refusal writes none of them.
+     */
+    update(rows: readonly TableRow[]): boolean;
+    /**
+     * Write over one row, found by the key it carries.
+     *
+     * @remarks
+     * The cells given replace the cells held; the cells left out stay as they are. A row's key
+     * therefore cannot move, because a different key names a different row.
+     *
+     * @param row - The cells to write, carrying the key of the row they belong to.
+     * @returns `true` when the key named a row the table holds.
+     * @throws A {@link TableError} coded `CELL` when a cell is one its column cannot hold.
+     */
+    update(row: TableRow): boolean;
+    /**
+     * Move one row to another place in the table's own order.
+     *
+     * @param key - The row's key.
+     * @param index - Where to put it, counted from zero and clamped to the rows that exist.
+     * @returns `true` when the key named a row the table holds.
+     */
+    move(key: TableKey, index: number): boolean;
+    /**
+     * Take out every row.
+     *
+     * @remarks
+     * Selection and expansion drop the keys they held, because those rows are gone.
+     */
+    remove(): void;
+    /**
+     * Take out one row.
+     *
+     * @param key - The row's key.
+     * @returns `true` when the key named a row the table holds.
+     */
+    remove(key: TableKey): boolean;
+    /**
+     * Take out several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns `true` when every key named a row the table holds. Every key is checked before any
+     *   row goes, so one unknown key leaves the whole call undone.
+     */
+    remove(keys: readonly TableKey[]): boolean;
+}
+
+/** The keys of the rows somebody has picked. */
+export declare class SelectionManager implements SelectionManagerInterface {
+    #private;
+    /**
+     * Create a selection manager over one table's private stores.
+     *
+     * @param emitter - The table's event emitter.
+     * @param gate - The table lifecycle gate.
+     * @param rows - A read of every row key.
+     * @param read - A read of the selected keys.
+     * @param write - The selected-key commit boundary.
+     */
+    constructor(emitter: Emitter<TableEventMap>, gate: () => void, rows: () => readonly TableKey[], read: () => ReadonlySet<TableKey>, write: (keys: ReadonlySet<TableKey>) => void);
+    /** The keys of the rows picked right now. */
+    get keys(): ReadonlySet<TableKey>;
+    /** Pick every row the table holds. */
+    select(): void;
+    /** Pick one row. */
+    select(key: TableKey): boolean;
+    /** Pick several rows. */
+    select(keys: readonly TableKey[]): boolean;
+    /** Drop every pick. */
+    clear(): void;
+    /** Drop one pick. */
+    clear(key: TableKey): boolean;
+    /** Drop several picks. */
+    clear(keys: readonly TableKey[]): boolean;
+    /** Pick one row or drop it when already picked. */
+    toggle(key: TableKey): boolean;
+    /** Turn several rows around independently. */
+    toggle(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * The rows somebody has picked.
+ *
+ * @remarks
+ * Selection holds keys, never rows or positions, so a pick survives a sort, a filter, and a page
+ * turn. A row that leaves the table takes its key out of the selection with it.
+ *
+ * @example
+ * ```ts
+ * table.selection.toggle('7')
+ * table.selection.keys.has('7') // true
+ * ```
+ */
+export declare interface SelectionManagerInterface {
+    /** The keys of the rows picked right now. */
+    readonly keys: ReadonlySet<TableKey>;
+    /**
+     * Pick every row the table holds.
+     *
+     * @remarks
+     * Every row, not every visible one. A host picking one page hands that page's keys over
+     * instead.
+     */
+    select(): void;
+    /**
+     * Pick one row.
+     *
+     * @param key - The row's key.
+     * @returns `true` when the key named a row the table holds.
+     */
+    select(key: TableKey): boolean;
+    /**
+     * Pick several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns `true` when every key named a row the table holds. Every key is checked before any
+     *   row is picked.
+     */
+    select(keys: readonly TableKey[]): boolean;
+    /** Drop every pick. */
+    clear(): void;
+    /**
+     * Drop one pick.
+     *
+     * @param key - The row's key.
+     * @returns `true` when the key named a row the table holds, whether or not it was picked.
+     */
+    clear(key: TableKey): boolean;
+    /**
+     * Drop several picks.
+     *
+     * @param keys - The rows' keys.
+     * @returns `true` when every key named a row the table holds. Every key is checked before any
+     *   pick is dropped.
+     */
+    clear(keys: readonly TableKey[]): boolean;
+    /**
+     * Pick one row, or drop it when it is already picked.
+     *
+     * @param key - The row's key.
+     * @returns `true` when the key named a row the table holds.
+     */
+    toggle(key: TableKey): boolean;
+    /**
+     * Turn several rows around, each on its own.
+     *
+     * @param keys - The rows' keys.
+     * @returns `true` when every key named a row the table holds. Every key is checked before any
+     *   row turns.
+     */
+    toggle(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * Project rows into schema-column-ordered JSON.
+ *
+ * @param schema - The schema that fixes cell order.
+ * @param rows - The rows to project.
+ * @returns A frozen list of owned JSON records with absent cells omitted.
+ */
+export declare function serializeRows(schema: TableSchema, rows: readonly TableRow[]): readonly JSONRecord[];
+
+/**
+ * Project a schema into declaration-ordered JSON.
+ *
+ * @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.
+ */
+export declare function serializeTable(schema: TableSchema): JSONRecord;
+
+/** The ordered sort terms of one table. */
+export declare class SortManager implements SortManagerInterface {
+    #private;
+    /**
+     * Create a sort manager over one table's private term store.
+     *
+     * @param schema - The table schema.
+     * @param emitter - The table's event emitter.
+     * @param gate - The table lifecycle gate.
+     * @param read - A read of the current terms.
+     * @param write - The term commit boundary.
+     */
+    constructor(schema: TableSchema, emitter: Emitter<TableEventMap>, gate: () => void, read: () => readonly TableOrder[], write: (orders: readonly TableOrder[]) => void);
+    /** Find one column's sort term. */
+    order(column: string): TableOrder | undefined;
+    /** Read every sort term as an owned frozen snapshot. */
+    orders(): readonly TableOrder[];
+    /** Sort by several columns. */
+    set(orders: readonly TableOrder[]): void;
+    /** Sort by one column. */
+    set(order: TableOrder): void;
+    /** Stop sorting by every column. */
+    remove(): void;
+    /** Stop sorting by one column. */
+    remove(column: string): boolean;
+    /** Stop sorting by several columns. */
+    remove(columns: readonly string[]): boolean;
+}
+
+/**
+ * The order a table reads its rows in.
+ *
+ * @remarks
+ * The table holds one term per column and applies them in the order they were set. Which
+ * direction a heading offers next is the host's decision, so there is no cycling verb here: read
+ * the column's term, decide, then set or remove it.
+ *
+ * @example
+ * ```ts
+ * table.sort.set({ column: 'age', direction: 'descending' })
+ * table.sort.orders() // [{ column: 'age', direction: 'descending' }]
+ * ```
+ */
+export declare interface SortManagerInterface {
+    /**
+     * Find one column's term.
+     *
+     * @param column - The column's key.
+     * @returns The term, or `undefined` when nothing sorts that column.
+     */
+    order(column: string): TableOrder | undefined;
+    /**
+     * Every term the table sorts by.
+     *
+     * @returns The terms, first to last, in the order they decide.
+     */
+    orders(): readonly TableOrder[];
+    /**
+     * Sort by several columns.
+     *
+     * @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.
+     * @throws A {@link TableError} coded `COLUMN` when a term names a column the schema does not
+     *   declare. Every term is checked before any is set.
+     */
+    set(orders: readonly TableOrder[]): void;
+    /**
+     * Sort by one column.
+     *
+     * @param order - The term to set.
+     * @throws A {@link TableError} coded `COLUMN` when the term names a column the schema does not
+     *   declare.
+     */
+    set(order: TableOrder): void;
+    /** Stop sorting by anything. */
+    remove(): void;
+    /**
+     * Stop sorting by one column.
+     *
+     * @param column - The column's key.
+     * @returns `true` when the schema declares that column.
+     */
+    remove(column: string): boolean;
+    /**
+     * Stop sorting by several columns.
+     *
+     * @param columns - The columns' keys.
+     * @returns `true` when the schema declares every one of them. Every key is checked before any
+     *   term goes.
+     */
+    remove(columns: readonly string[]): boolean;
+}
+
+/**
+ * Order rows stably by a sequence of terms.
+ *
+ * @param schema - The schema that declares the sorted columns.
+ * @param rows - The rows to order.
+ * @param orders - The ordered sort terms.
+ * @param comparators - Optional per-column replacements for the default comparator.
+ * @returns A frozen sorted copy that leaves the input untouched.
+ */
+export declare function sortRows(schema: TableSchema, rows: readonly TableRow[], orders: readonly TableOrder[], comparators?: Readonly<Record<string, CellComparator>>): readonly TableRow[];
+
+/** The maximum length, in UTF-16 code units, of any single retained string. */
+export declare const STRING_LIMIT = 65536;
+
+/** A schema, its rows, and the lens through which they are read. */
+export declare class Table implements TableInterface {
+    #private;
+    /**
+     * Open a table against a schema.
+     *
+     * @param schema - The table declaration to own.
+     * @param options - Initial rows, lens overrides, pagination, and emitter wiring.
+     * @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.
+     */
+    constructor(schema: TableSchema, options?: TableOptions);
+    /** The table's event emitter. */
+    get emitter(): EmitterInterface<TableEventMap>;
+    /** The owned frozen schema. */
+    get schema(): TableSchema;
+    /** The rows the table holds. */
+    get rows(): RowManagerInterface;
+    /** The ordered sort terms. */
+    get sort(): SortManagerInterface;
+    /** The filters applied with and-only composition. */
+    get filter(): FilterManagerInterface;
+    /** The selected row keys. */
+    get selection(): SelectionManagerInterface;
+    /** The expanded row keys. */
+    get expansion(): ExpansionManagerInterface;
+    /** The page arithmetic. */
+    get pagination(): PaginationManagerInterface;
+    /** The filtered, sorted, and paged rows as owned frozen snapshots. */
+    get view(): readonly TableRow[];
+    /** The number of rows admitted by the filters. */
+    get count(): number;
+    /** Whether the table has been torn down. */
+    get destroyed(): boolean;
+    /** Reset every moving axis to its opening state. */
+    clear(): void;
+    /** Tear the table down while leaving every getter readable. */
+    destroy(): void;
+}
+
+/**
+ * Every value a cell can hold.
+ *
+ * @remarks
+ * The variant follows the column: `text` and `choice` hold a `string`, `number` holds a `number`,
+ * and `flag` holds a `boolean`. A cell nobody has filled has no key in its row, so absence is
+ * `undefined` and never `null` or an empty string.
+ */
+export declare type TableCell = string | number | boolean;
+
+/**
+ * Any column a schema can declare.
+ *
+ * @remarks
+ * The union discriminates on `cell`, so narrowing on that member reaches each variant's own
+ * members.
+ *
+ * @example
+ * ```ts
+ * function choices(column: TableColumn): readonly ColumnChoice[] {
+ * 	return column.cell === 'choice' ? column.choices : []
+ * }
+ * ```
+ */
+export declare type TableColumn = TextColumn | NumberColumn | FlagColumn | ChoiceColumn;
+
+/**
+ * Which way a column sorts.
+ *
+ * @remarks
+ * A column nobody has sorted has no {@link TableOrder} at all, so there is no third member
+ * standing for unsorted.
+ */
+export declare type TableDirection = 'ascending' | 'descending';
+
+/** An error raised by the table domain. */
+export declare class TableError extends Error {
+    /** The machine-readable reason for this failure. */
+    readonly code: TableErrorCode;
+    /** Structured values that locate or explain this failure. */
+    readonly context?: JSONRecord;
+    /**
+     * Create a table error.
+     *
+     * @param code - The machine-readable reason.
+     * @param message - The human-readable failure text.
+     * @param context - Optional structured failure details.
+     */
+    constructor(code: TableErrorCode, message: string, context?: JSONRecord);
+}
+
+/**
+ * The machine-readable code a table error carries.
+ *
+ * @remarks
+ * `SCHEMA` rejects a malformed schema, including a `key` naming no declared column. `COLUMN`
+ * names a column the schema does not declare. `KEY` reports a row identity that is missing,
+ * unusable, or already taken. `CELL` reports a value the column's cell cannot hold. `DESTROYED`
+ * refuses a write to a table that has been torn down.
+ */
+export declare type TableErrorCode = 'SCHEMA' | 'COLUMN' | 'KEY' | 'CELL' | 'DESTROYED';
+
+/**
+ * Everything a table announces.
+ *
+ * @remarks
+ * Every event fires after the state it reports is committed, and only when something actually
+ * moved: a write that changes nothing announces nothing.
+ *
+ * `write` and `remove` carry one key and fire once per row, in the order the table wrote or
+ * removed them. A listener that wants the row reads it back.
+ *
+ * `sort` and `filter` carry the whole axis as it now stands, and `select` and `expand` carry the
+ * whole key set. Each payload is owned by the listener, so nothing it holds moves underneath it.
+ *
+ * `paginate` carries the page the table now shows, and fires whenever the paged window moves,
+ * including a clamp and a change of page size.
+ *
+ * `clear` is a signal, and it is the whole announcement of that reset: a clear emits no `remove`,
+ * no `select`, and no `paginate` beside it.
+ */
+export declare type TableEventMap = {
+    readonly write: readonly [key: TableKey];
+    readonly remove: readonly [key: TableKey];
+    readonly sort: readonly [orders: readonly TableOrder[]];
+    readonly filter: readonly [filters: readonly TableFilter[]];
+    readonly select: readonly [keys: ReadonlySet<TableKey>];
+    readonly expand: readonly [keys: ReadonlySet<TableKey>];
+    readonly paginate: readonly [page: number];
+    readonly clear: readonly [];
+};
+
+/**
+ * Any filter a table can hold.
+ *
+ * @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.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const filter: TableFilter = { column: 'age', operator: 'between', minimum: 30, maximum: 40 }
+ * ```
+ */
+export declare type TableFilter = ContainsFilter | BetweenFilter | EqualsFilter;
+
+/**
+ * A table: what it declares, the rows it holds, and the lens it reads them through.
+ *
+ * @remarks
+ * The table owns values, not pixels. It renders nothing, reads no document, and names no host
+ * type, so one table serves a browser, a terminal, a report, and an export equally.
+ *
+ * Six managers hold everything that moves, one per axis: `rows`, `sort`, `filter`, `selection`,
+ * `expansion`, and `pagination`. Nothing else is stored. `view` and `count` are worked out when
+ * they are read, so no second copy of the answer can go stale.
+ *
+ * A write validates all of itself before any of it lands, and announces itself once it has.
+ *
+ * @example
+ * ```ts
+ * table.filter.set({ column: 'name', operator: 'contains', text: 'ad' })
+ * table.sort.set({ column: 'age', direction: 'descending' })
+ * table.view // the rows to draw now: filtered, sorted, paged
+ * ```
+ */
+export declare interface TableInterface {
+    /** The table's event emitter. */
+    readonly emitter: EmitterInterface<TableEventMap>;
+    /** What this table declares. */
+    readonly schema: TableSchema;
+    /** The rows the table holds. */
+    readonly rows: RowManagerInterface;
+    /** The order the table reads them in. */
+    readonly sort: SortManagerInterface;
+    /** Which of them the table keeps. */
+    readonly filter: FilterManagerInterface;
+    /** The ones somebody has picked. */
+    readonly selection: SelectionManagerInterface;
+    /** The ones somebody has opened up. */
+    readonly expansion: ExpansionManagerInterface;
+    /** Which stretch of them the view shows. */
+    readonly pagination: PaginationManagerInterface;
+    /**
+     * The rows to draw right now: filtered, then sorted, then paged.
+     *
+     * @remarks
+     * It is worked out on every read and never stored, so it is right the instant anything moves.
+     */
+    readonly view: readonly TableRow[];
+    /** How many rows the filter admits, before the page narrows them. */
+    readonly count: number;
+    /** Whether the table has been torn down. */
+    readonly destroyed: boolean;
+    /**
+     * Put the table back the way it opened, holding nothing.
+     *
+     * @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.
+     */
+    clear(): void;
+    /**
+     * Tear the table down.
+     *
+     * @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.
+     */
+    destroy(): void;
+}
+
+/**
+ * A row's identity.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * const key: TableKey = '7'
+ * ```
+ */
+export declare type TableKey = string;
+
+/**
+ * How to open a table.
+ *
+ * @param options - The table's settings.
+ * @remarks
+ * `on` wires listeners at construction and `error` receives any throw from one of them.
+ *
+ * `rows` seeds the rows. Seeding announces nothing, so a table opens quietly and every later
+ * write is heard.
+ *
+ * `comparators` and `matchers` are keyed by column key. Each entry replaces, for that column
+ * alone, the comparison or the test the column's {@link ColumnCell} fixes. They are the reason no
+ * function belongs in the schema: behavior is supplied where the table is opened, and the schema
+ * stays data that crosses a wire whole.
+ *
+ * `limit` is how many rows a page holds. Leave it out and the table is not paged.
+ *
+ * @example
+ * ```ts
+ * const options: TableOptions = {
+ * 	rows: [{ id: '7', name: 'Ada', age: 36 }],
+ * 	limit: 25,
+ * 	on: { select: (keys) => highlight(keys) },
+ * }
+ * ```
+ */
+export declare interface TableOptions {
+    readonly on?: EmitterHooks<TableEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly rows?: readonly TableRow[];
+    readonly comparators?: Readonly<Record<string, CellComparator>>;
+    readonly matchers?: Readonly<Record<string, CellMatcher>>;
+    readonly limit?: number;
+}
+
+/**
+ * One column's place in the sort.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * const order: TableOrder = { column: 'age', direction: 'descending' }
+ * ```
+ */
+export declare interface TableOrder {
+    readonly column: string;
+    readonly direction: TableDirection;
+}
+
+/**
+ * One row, keyed by column.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * const row: TableRow = { id: '7', name: 'Ada', age: 36, active: true }
+ * ```
+ */
+export declare type TableRow = Readonly<Record<string, TableCell>>;
+
+/**
+ * Everything a table declares about itself.
+ *
+ * @remarks
+ * The schema is data. It carries no function, so all of it crosses a wire and nothing is dropped
+ * on the way.
+ *
+ * `columns` is the schema's column list, and the order it declares is the order a host presents.
+ * `key` names the column whose cells carry row identity; it is required, it must name a declared
+ * column, and the table refuses a row whose cell there is missing, empty, or not a string. There
+ * is no default column, no positional fallback, and no key generation: an index is a position,
+ * and a position is not an identity.
+ *
+ * `name`, `label`, and `help` describe the table itself.
+ *
+ * @example
+ * ```ts
+ * const schema: TableSchema = {
+ * 	label: 'People',
+ * 	key: 'id',
+ * 	columns: [
+ * 		{ cell: 'text', key: 'id', label: 'Reference' },
+ * 		{ cell: 'text', key: 'name', label: 'Name' },
+ * 		{ cell: 'number', key: 'age', label: 'Age' },
+ * 	],
+ * }
+ * ```
+ */
+export declare interface TableSchema {
+    readonly name?: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly key: string;
+    readonly columns: readonly TableColumn[];
+}
+
+/** The maximum total length, in UTF-16 code units, of every string one schema retains. */
+export declare const TEXT_LIMIT = 1048576;
+
+/** A column of text, compared lexically. */
+export declare interface TextColumn extends ColumnBase {
+    readonly cell: 'text';
+}
+
+export { }