@adecore/database 0.0.1 → 0.16.0-beta.0

package/dist/table/command-field.js

@@ -0,0 +1,203 @@
+import { equalsCondition, findColumn, notEqualsCondition, orderByClause, parseOrderByLoose, quoteIdentifier, sqlLiteral } from '../sql.js';
+/* How many columns the suggestions list for what is typed. */
+export const SUGGESTED_COLUMNS = 4;
+const OR = /\bor\b/i;
+const BARE_NAME = /^[A-Za-z_][\w$]*$/;
+const WORD = /^(`(?:[^`]|``)+`|"(?:[^"]|"")+"|[A-Za-z_][\w$]*)\s*([\s\S]*)$/;
+const COMPARE = /^(==|=|<>|!=|<=|>=|<|>)\s*([\s\S]+)$/;
+const PATTERN = /^((?:NOT\s+)?(?:LIKE|ILIKE|GLOB|REGEXP|RLIKE))\s+([\s\S]+)$/i;
+const MEMBER = /^((?:NOT\s+)?IN)\s*(\([\s\S]+\))$/i;
+const BETWEEN = /^((?:NOT\s+)?BETWEEN)\s+([\s\S]+?)\s+AND\s+([\s\S]+)$/i;
+const IS_TEST = /^IS\s+(?:NOT\s+)?(?:NULL|TRUE|FALSE)$/i;
+/* A name being typed, or one that opened a quote. Whitespace after it means an operator is coming. */
+const NAME_BEING_TYPED = /^\s*(?:[\w$]*|[`"][^`"]*[`"]?)$/;
+export const chipKey = (chip) => (chip.kind === 'sort' ? `sort:${chip.column}` : `${chip.kind}:${chip.kind === 'filter' ? chip.sql : chip.text}`);
+const isFilter = (chip) => chip.kind === 'filter';
+const isSort = (chip) => chip.kind === 'sort';
+/* A name as typed in SQL: bare when it can be, else in double quotes. The quotes are only for the text of a chip; `sql` quotes per engine. */
+export const identifierText = (name) => (BARE_NAME.test(name) ? name : `"${name.replaceAll('"', '""')}"`);
+/* The conditions AND-ed together, each in parentheses when it holds an OR and there is more than one. */
+export const chipsToWhere = (chips) => {
+    const conditions = chips
+        .filter(isFilter)
+        .map((chip) => chip.sql.trim())
+        .filter((sql) => sql !== '');
+    if (conditions.length < 2) {
+        return conditions[0] ?? '';
+    }
+    return conditions.map((sql) => (OR.test(sql) ? `(${sql})` : sql)).join(' AND ');
+};
+/* The sort chips in order, each quoted for the engine; a raw ORDER BY keeps its place among them. */
+export const chipsToOrderBy = (engine, chips) => chips
+    .flatMap((chip) => {
+    if (chip.kind === 'sort') {
+        return [orderByClause(engine, [chip])];
+    }
+    return chip.kind === 'order' ? [chip.text.trim()] : [];
+})
+    .filter((part) => part !== '')
+    .join(', ');
+export const sortsOf = (chips) => chips.filter(isSort).map(({ column, direction }) => ({ column, direction }));
+/* The sorts of a header menu replace every sort and raw ORDER BY, keeping the filters where they are. */
+export const withSorts = (chips, sorts) => [
+    ...chips.filter(isFilter),
+    ...sorts.map((sort) => ({ kind: 'sort', column: sort.column, direction: sort.direction }))
+];
+/* A column that is not sorted joins as ascending; one that is flips its direction where it stands. */
+export const toggleSort = (chips, column) => {
+    if (!chips.some((chip) => isSort(chip) && chip.column === column)) {
+        return [...chips, { kind: 'sort', column, direction: 'asc' }];
+    }
+    return chips.map((chip) => (isSort(chip) && chip.column === column ? { ...chip, direction: chip.direction === 'asc' ? 'desc' : 'asc' } : chip));
+};
+/* The same list when the chip is already in it. */
+export const addChip = (chips, chip) => chips.some((other) => chipKey(other) === chipKey(chip)) ? [...chips] : [...chips, chip];
+export const removeChipAt = (chips, index) => chips.filter((_, at) => at !== index);
+/* Puts the chip where another stood, dropping it if an equal one is already elsewhere in the list. */
+export const replaceChipAt = (chips, index, chip) => {
+    const duplicate = chips.some((other, at) => at !== index && chipKey(other) === chipKey(chip));
+    return duplicate ? removeChipAt(chips, index) : chips.map((other, at) => (at === index ? chip : other));
+};
+const rawFilter = (text) => ({ kind: 'filter', text, sql: text });
+/* The WHERE of a layout or of a jump as chips: the remembered ones when they still say that text, else the text as one raw chip. */
+export const filterChipsOf = (where, remembered = []) => {
+    const text = where.trim();
+    if (text === '') {
+        return [];
+    }
+    const kept = remembered.map((filter) => ({ kind: 'filter', text: filter.text, sql: filter.sql }));
+    return chipsToWhere(kept) === text ? kept : [rawFilter(text)];
+};
+/* A plain list of columns becomes sort chips; anything else is one chip that keeps the text. */
+export const sortChipsOf = (engine, orderBy) => {
+    const text = orderBy.trim();
+    if (text === '') {
+        return [];
+    }
+    const sorts = parseOrderByLoose(engine, text);
+    return sorts === null ? [{ kind: 'order', text }] : sorts.map((sort) => ({ kind: 'sort', column: sort.column, direction: sort.direction }));
+};
+export const chipsFromQuery = (engine, { where, orderBy, remembered }) => [
+    ...filterChipsOf(where, remembered),
+    ...sortChipsOf(engine, orderBy)
+];
+/* Whether quotes and parentheses close, outside of which an operand would swallow the rest of the text. */
+const isClosed = (operand) => {
+    let quote = null;
+    let depth = 0;
+    for (const character of operand) {
+        if (quote !== null) {
+            quote = character === quote ? null : quote;
+        }
+        else if (character === "'" || character === '"' || character === '`') {
+            quote = character;
+        }
+        else if (character === '(') {
+            depth++;
+        }
+        else if (character === ')') {
+            depth--;
+            if (depth < 0) {
+                return false;
+            }
+        }
+    }
+    return quote === null && depth === 0;
+};
+const upper = (keyword) => keyword.replace(/\s+/g, ' ').toUpperCase();
+/* The operator and operands of a condition in the form the chip shows, or `null` when the text does not read as one. */
+const readOperation = (rest) => {
+    const compare = COMPARE.exec(rest);
+    if (compare !== null) {
+        const operator = compare[1] === '==' ? '=' : compare[1] === '!=' ? '<>' : compare[1];
+        return isClosed(compare[2]) ? `${operator} ${compare[2]}` : null;
+    }
+    const pattern = PATTERN.exec(rest);
+    if (pattern !== null) {
+        return isClosed(pattern[2]) ? `${upper(pattern[1])} ${pattern[2]}` : null;
+    }
+    const member = MEMBER.exec(rest);
+    if (member !== null) {
+        return isClosed(member[2]) ? `${upper(member[1])} ${member[2]}` : null;
+    }
+    const between = BETWEEN.exec(rest);
+    if (between !== null) {
+        return isClosed(between[2]) && isClosed(between[3]) ? `${upper(between[1])} ${between[2]} AND ${between[3]}` : null;
+    }
+    return IS_TEST.test(rest) ? upper(rest) : null;
+};
+/*
+ * The chip a typed text makes when it already reads as a condition: a column of the table, an
+ * operator and what it needs after it. A text that is anything else stays for the person to finish or to hand over as SQL.
+ */
+export const parseCondition = (engine, text, columns) => {
+    const match = WORD.exec(text.trim());
+    if (match === null) {
+        return null;
+    }
+    const column = findColumn(engine, match[1], columns);
+    const operation = column === undefined ? null : readOperation(match[2].trim());
+    if (column === undefined || operation === null) {
+        return null;
+    }
+    return { kind: 'filter', text: `${match[1]} ${operation}`, sql: `${quoteIdentifier(engine, column)} ${operation}` };
+};
+/* `column = value` or `column <> value` for the cell a menu was opened on; NULL reads as IS NULL and IS NOT NULL. */
+export const cellChip = (engine, column, value, kind, exclude) => {
+    const name = identifierText(column);
+    const text = value === null ? `${name} IS ${exclude ? 'NOT ' : ''}NULL` : `${name} ${exclude ? '<>' : '='} ${sqlLiteral(engine, value, kind)}`;
+    return { kind: 'filter', text, sql: exclude ? notEqualsCondition(engine, column, value, kind) : equalsCondition(engine, column, value, kind) };
+};
+/* Cuts a long text for a label, ending in an ellipsis. */
+export const shorten = (text, limit) => (text.length > limit ? `${text.slice(0, limit - 1)}…` : text);
+/* How well a name matches what is typed: 0 is the name itself, then its start, a word of it, anywhere in it; `null` is no match. */
+const rankOf = (name, token) => {
+    const lower = name.toLowerCase();
+    if (lower === token) {
+        return 0;
+    }
+    if (lower.startsWith(token)) {
+        return 1;
+    }
+    if (lower.split(/[\s_.-]+/).some((word) => word.startsWith(token))) {
+        return 2;
+    }
+    return lower.includes(token) ? 3 : null;
+};
+/* The columns that match a typed name, the closest first and in table order among equals. */
+export const matchColumns = (columns, typed, limit = SUGGESTED_COLUMNS) => {
+    const token = typed.trim().replace(/^[`"]/, '').replace(/[`"]$/, '').toLowerCase();
+    if (token === '') {
+        return [];
+    }
+    return columns
+        .map((column, order) => ({ column, order, rank: rankOf(column.name, token) }))
+        .filter((entry) => entry.rank !== null)
+        .sort((left, right) => left.rank - right.rank || left.order - right.order)
+        .slice(0, limit)
+        .map((entry) => entry.column);
+};
+/*
+ * What the popup under the field offers for the text: the condition it already is, then for each
+ * matching column to filter, sort or jump to it, and last the text as plain SQL. Empty text offers nothing.
+ */
+export const suggest = (engine, text, columns, limit = SUGGESTED_COLUMNS) => {
+    const typed = text.trim();
+    if (typed === '') {
+        return [];
+    }
+    const suggestions = [];
+    const condition = parseCondition(engine, typed, columns.map((column) => column.name));
+    if (condition !== null) {
+        suggestions.push({ kind: 'condition', chip: condition });
+    }
+    if (NAME_BEING_TYPED.test(text)) {
+        for (const column of matchColumns(columns, typed, limit)) {
+            suggestions.push({ kind: 'filter', column }, { kind: 'sort', column }, { kind: 'jump', column });
+        }
+    }
+    suggestions.push({ kind: 'sql', chip: rawFilter(typed) });
+    return suggestions;
+};
+/* What the input holds after "Filter on <column>" is picked, ready for an operator and a value. */
+export const filterStartText = (column) => `${identifierText(column.name)} `;

package/dist/table/grid-rows.d.ts

@@ -0,0 +1,23 @@
+import { type Shown } from '../grid/display.ts';
+import { type GridColumn, type GridRow } from '../grid/types.ts';
+import type { EditValue, RowsResult, TableStructure } from '../protocol/index.ts';
+import { type PendingChanges } from './pending.ts';
+export type RowRef = {
+    readonly kind: 'loaded';
+    readonly index: number;
+} | {
+    readonly kind: 'inserted';
+    readonly id: number;
+};
+export declare const loadedRowKey: (index: number) => string;
+export declare const insertedRowKey: (id: number) => string;
+export declare const parseRowKey: (key: string) => RowRef;
+export declare const buildGridColumns: (loaded: Pick<RowsResult, 'columns'>, structure: TableStructure | null) => GridColumn[];
+export interface GridRowsInput {
+    readonly structure: TableStructure | null;
+    readonly loaded: Pick<RowsResult, 'columns' | 'rows'>;
+    readonly pending: PendingChanges;
+    readonly offset: number;
+}
+export declare const buildGridRows: ({ structure, loaded, pending, offset }: GridRowsInput) => GridRow[];
+export declare const cloneValues: (columns: readonly GridColumn[], cells: readonly Shown[]) => Record<string, EditValue>;

package/dist/table/grid-rows.js

@@ -0,0 +1,55 @@
+import { shownOfEdit } from '../grid/display.js';
+import { wholeValueOf } from '../grid/focused-value.js';
+import { gridColumnOf } from '../grid/types.js';
+import { rowKeyOf } from './pending.js';
+export const loadedRowKey = (index) => `row:${index}`;
+export const insertedRowKey = (id) => `new:${id}`;
+export const parseRowKey = (key) => key.startsWith('new:') ? { kind: 'inserted', id: Number(key.slice(4)) } : { kind: 'loaded', index: Number(key.slice(4)) };
+export const buildGridColumns = (loaded, structure) => loaded.columns.map((column) => gridColumnOf(column, structure?.columns.find((info) => info.name === column.name), structure?.primaryKey ?? []));
+/* The loaded rows with their pending edits laid over them, then the rows waiting to be inserted. */
+export const buildGridRows = ({ structure, loaded, pending, offset }) => {
+    const rows = loaded.rows.map((cells, index) => {
+        const edits = pending.edits[index];
+        const edited = new Set();
+        const shown = cells.map((cell, column) => {
+            const edit = edits?.[loaded.columns[column].name];
+            if (edit === undefined) {
+                return cell;
+            }
+            edited.add(column);
+            return shownOfEdit(edit);
+        });
+        return {
+            key: loadedRowKey(index),
+            number: offset + index + 1,
+            cells: shown,
+            state: pending.deletes.has(index) ? 'deleted' : undefined,
+            edited,
+            locked: structure === null || rowKeyOf(structure, loaded, index) === null
+        };
+    });
+    const inserted = pending.inserts.map((row) => ({
+        key: insertedRowKey(row.id),
+        number: null,
+        cells: loaded.columns.map((column) => {
+            const value = row.values[column.name];
+            return value === undefined ? { kind: 'default' } : shownOfEdit(value);
+        }),
+        state: 'inserted'
+    }));
+    return [...rows, ...inserted];
+};
+/*
+ * The values a copy of a row starts from: what the row shows, except the columns the server fills in
+ * (an auto-increment key, a generated column) and the cells that are only a preview or a DEFAULT.
+ */
+export const cloneValues = (columns, cells) => {
+    const values = {};
+    columns.forEach((column, index) => {
+        const value = column.autoIncrement === true || column.readOnly === true ? undefined : wholeValueOf(cells[index] ?? null);
+        if (value !== undefined) {
+            values[column.name] = value;
+        }
+    });
+    return values;
+};

package/dist/table/import-mapping.d.ts

@@ -0,0 +1,7 @@
+import type { ColumnInfo } from '../protocol/index.ts';
+export type ImportFormat = 'csv' | 'tsv';
+export declare const importableColumns: (columns: readonly ColumnInfo[]) => ColumnInfo[];
+export declare const formatOfPath: (path: string) => ImportFormat;
+export declare const matchColumns: (fileColumns: readonly string[], tableColumns: readonly string[], header: boolean) => (string | null)[];
+export declare const hasMapping: (mapping: readonly (string | null)[]) => boolean;
+export declare const mapColumn: (mapping: readonly (string | null)[], fileColumn: number, tableColumn: string | null) => (string | null)[];

package/dist/table/import-mapping.js

@@ -0,0 +1,28 @@
+/* The columns an import can fill: a generated column is computed by the server. */
+export const importableColumns = (columns) => columns.filter((column) => !column.generated);
+/* CSV or TSV by the extension of the path; CSV when it says neither. */
+export const formatOfPath = (path) => (/\.(tsv|tab)$/i.test(path) ? 'tsv' : 'csv');
+/*
+ * The table column each file column goes to, as a name, or `null` for none. Names match without regard
+ * to case and a table column takes at most one file column. A file without a header has no names to
+ * match, so its columns go to the table's columns in order.
+ */
+export const matchColumns = (fileColumns, tableColumns, header) => {
+    if (!header) {
+        return fileColumns.map((_, index) => tableColumns[index] ?? null);
+    }
+    const taken = new Set();
+    return fileColumns.map((name) => {
+        const wanted = name.trim().toLowerCase();
+        const match = tableColumns.find((column) => !taken.has(column) && column.toLowerCase() === wanted);
+        if (match === undefined) {
+            return null;
+        }
+        taken.add(match);
+        return match;
+    });
+};
+/* Whether anything is mapped, since an import of nothing is no import. */
+export const hasMapping = (mapping) => mapping.some((column) => column !== null);
+/* Maps a file column to a table column, taking the table column from any other file column that had it. */
+export const mapColumn = (mapping, fileColumn, tableColumn) => mapping.map((current, index) => (index === fileColumn ? tableColumn : tableColumn !== null && current === tableColumn ? null : current));

package/dist/table/layout-store.d.ts

@@ -0,0 +1,13 @@
+import type { GridLayout } from '../grid/column-layout.ts';
+import type { StoredFilter } from './command-field.ts';
+export declare const LAYOUT_VERSION = 1;
+export interface StoredLayout extends GridLayout {
+    readonly pageSize: number | null;
+    readonly where: string;
+    readonly orderBy: string;
+    readonly filters: readonly StoredFilter[];
+}
+export declare const EMPTY_LAYOUT: StoredLayout;
+export declare const layoutStorageKey: (connectionId: string, schema: string, table: string) => string;
+export declare const serializeLayout: (layout: StoredLayout) => string;
+export declare const parseStoredLayout: (text: string | null) => StoredLayout | null;

package/dist/table/layout-store.js

@@ -0,0 +1,43 @@
+import { PAGE_SIZES } from './paging.js';
+/* Bump when the shape changes; a stored value of another version is ignored rather than migrated. `filters` was added alongside `where`, which still says the same thing for a value without it. */
+export const LAYOUT_VERSION = 1;
+export const EMPTY_LAYOUT = { widths: {}, hidden: [], pinned: [], pageSize: null, where: '', orderBy: '', filters: [] };
+export const layoutStorageKey = (connectionId, schema, table) => `database:table:${connectionId}:${schema}.${table}`;
+const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+const isStoredFilter = (value) => isRecord(value) && typeof value.text === 'string' && typeof value.sql === 'string' && value.sql.trim() !== '';
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export const serializeLayout = (layout) => JSON.stringify({ version: LAYOUT_VERSION, ...layout });
+/* The layout a stored text holds, or `null` when it is missing, broken or from another version. A field that is off is dropped alone. */
+export const parseStoredLayout = (text) => {
+    if (text === null) {
+        return null;
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(data) || data.version !== LAYOUT_VERSION) {
+        return null;
+    }
+    const widths = {};
+    if (isRecord(data.widths)) {
+        for (const [name, width] of Object.entries(data.widths)) {
+            if (typeof width === 'number' && Number.isFinite(width) && width > 0) {
+                widths[name] = width;
+            }
+        }
+    }
+    const pageSize = PAGE_SIZES.find((size) => size === data.pageSize) ?? null;
+    return {
+        widths,
+        hidden: isStringList(data.hidden) ? data.hidden : [],
+        pinned: isStringList(data.pinned) ? data.pinned : [],
+        pageSize,
+        where: typeof data.where === 'string' ? data.where : '',
+        orderBy: typeof data.orderBy === 'string' ? data.orderBy : '',
+        filters: Array.isArray(data.filters) ? data.filters.filter(isStoredFilter).map((filter) => ({ text: filter.text, sql: filter.sql })) : []
+    };
+};

package/dist/table/paging.d.ts

@@ -0,0 +1,12 @@
+export declare const PAGE_SIZES: readonly [100, 500, 1000];
+export declare const DEFAULT_PAGE_SIZE = 500;
+export interface PageBounds {
+    readonly from: number;
+    readonly to: number;
+    readonly total: number;
+    readonly exact: boolean;
+    readonly hasPrevious: boolean;
+    readonly hasNext: boolean;
+}
+export declare const pageBounds: (offset: number, rowCount: number, hasMore: boolean, counted: number | null) => PageBounds;
+export declare const lastPageOffset: (total: number, pageSize: number) => number;

package/dist/table/paging.js

@@ -0,0 +1,20 @@
+export const PAGE_SIZES = [100, 500, 1000];
+export const DEFAULT_PAGE_SIZE = 500;
+/*
+ * Where a page sits. Without a count, a page that `hasMore` says only that one row exists past it, so
+ * the total is that many and the footer writes it as `501+`.
+ */
+export const pageBounds = (offset, rowCount, hasMore, counted) => {
+    const exact = counted !== null || !hasMore;
+    const total = counted ?? (hasMore ? offset + rowCount + 1 : offset + rowCount);
+    return {
+        from: rowCount === 0 ? 0 : offset + 1,
+        to: offset + rowCount,
+        total,
+        exact,
+        hasPrevious: offset > 0,
+        hasNext: counted === null ? hasMore : offset + rowCount < counted
+    };
+};
+/* Where the last page starts, given how many rows the table has. */
+export const lastPageOffset = (total, pageSize) => (total <= 0 ? 0 : Math.floor((total - 1) / pageSize) * pageSize);

package/dist/table/pending.d.ts

@@ -0,0 +1,32 @@
+import { type Cell, type EditValue, type RowChange, type RowKey, type RowsResult, type TableStructure } from '../protocol/index.ts';
+export interface InsertedRow {
+    readonly id: number;
+    readonly values: Readonly<Record<string, EditValue>>;
+}
+export interface PendingChanges {
+    readonly edits: Readonly<Record<number, Readonly<Record<string, EditValue>>>>;
+    readonly inserts: readonly InsertedRow[];
+    readonly deletes: ReadonlySet<number>;
+}
+export declare const emptyPending: PendingChanges;
+export declare const isPendingEmpty: (pending: PendingChanges) => boolean;
+export declare const pendingCount: (pending: PendingChanges) => number;
+export declare const valuesEqual: (left: EditValue | undefined, right: EditValue | undefined) => boolean;
+export declare const setEdit: (pending: PendingChanges, row: number, column: string, value: EditValue, original: Cell) => PendingChanges;
+export declare const addInsertWith: (pending: PendingChanges, values: Readonly<Record<string, EditValue>>) => PendingChanges;
+export declare const addInsert: (pending: PendingChanges) => PendingChanges;
+export declare const setInsertValue: (pending: PendingChanges, id: number, column: string, value: EditValue) => PendingChanges;
+export declare const removeInsert: (pending: PendingChanges, id: number) => PendingChanges;
+export declare const markDeleted: (pending: PendingChanges, rows: readonly number[]) => PendingChanges;
+export declare const revertRow: (pending: PendingChanges, row: number) => PendingChanges;
+export interface RowSelectionRefs {
+    readonly loaded: readonly number[];
+    readonly inserted: readonly number[];
+}
+export declare const revertRows: (pending: PendingChanges, rows: RowSelectionRefs) => PendingChanges;
+export declare const hasRowChanges: (pending: PendingChanges, rows: RowSelectionRefs) => boolean;
+type LoadedRows = Pick<RowsResult, 'columns' | 'rows'>;
+export declare const rowKeyOf: (structure: TableStructure, loaded: LoadedRows, row: number) => RowKey | null;
+export declare const toRowChanges: (structure: TableStructure, loaded: LoadedRows, pending: PendingChanges) => RowChange[];
+export declare const describeKey: (key: RowKey) => string;
+export {};

package/dist/table/pending.js

@@ -0,0 +1,94 @@
+import { valueOfCell } from '../protocol/index.js';
+export const emptyPending = { edits: {}, inserts: [], deletes: new Set() };
+export const isPendingEmpty = (pending) => Object.keys(pending.edits).length === 0 && pending.inserts.length === 0 && pending.deletes.size === 0;
+/* How many row changes a submit sends: an edited row that is also deleted counts once, as the delete. */
+export const pendingCount = (pending) => Object.keys(pending.edits).filter((row) => !pending.deletes.has(Number(row))).length + pending.inserts.length + pending.deletes.size;
+export const valuesEqual = (left, right) => {
+    if (left === undefined || right === undefined) {
+        return false;
+    }
+    if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object') {
+        return left === right;
+    }
+    return left.kind === right.kind && (left.kind !== 'binary' || (right.kind === 'binary' && left.hex === right.hex));
+};
+/* Sets a cell of a loaded row; setting it back to what the row held removes the edit. */
+export const setEdit = (pending, row, column, value, original) => {
+    const { [row]: current = {}, ...others } = pending.edits;
+    const { [column]: _replaced, ...kept } = current;
+    const next = valuesEqual(value, valueOfCell(original)) ? kept : { ...kept, [column]: value };
+    return { ...pending, edits: Object.keys(next).length === 0 ? others : { ...others, [row]: next } };
+};
+/* A new row to insert, filled in with `values`. */
+export const addInsertWith = (pending, values) => ({
+    ...pending,
+    inserts: [...pending.inserts, { id: pending.inserts.reduce((highest, row) => Math.max(highest, row.id), 0) + 1, values }]
+});
+export const addInsert = (pending) => addInsertWith(pending, {});
+export const setInsertValue = (pending, id, column, value) => ({
+    ...pending,
+    inserts: pending.inserts.map((row) => (row.id === id ? { ...row, values: { ...row.values, [column]: value } } : row))
+});
+export const removeInsert = (pending, id) => ({ ...pending, inserts: pending.inserts.filter((row) => row.id !== id) });
+export const markDeleted = (pending, rows) => ({
+    ...pending,
+    deletes: new Set([...pending.deletes, ...rows])
+});
+/* Takes back every change to one loaded row: its edits and its deletion. */
+export const revertRow = (pending, row) => {
+    const { [row]: _dropped, ...edits } = pending.edits;
+    const deletes = new Set(pending.deletes);
+    deletes.delete(row);
+    return { ...pending, edits, deletes };
+};
+/* Takes back every change to the given rows: the edits and deletion marks of the loaded ones, and the inserted ones altogether. */
+export const revertRows = (pending, rows) => {
+    const reverted = rows.loaded.reduce(revertRow, pending);
+    return { ...reverted, inserts: reverted.inserts.filter((row) => !rows.inserted.includes(row.id)) };
+};
+/* Whether any of the given rows has something to take back. */
+export const hasRowChanges = (pending, rows) => rows.loaded.some((row) => pending.edits[row] !== undefined || pending.deletes.has(row)) || pending.inserts.some((row) => rows.inserted.includes(row.id));
+/*
+ * The key that picks out one loaded row, from its own values in the columns of the structure's row
+ * key. `null` when the table has no row key, or a key cell is only a preview, in which case the row
+ * cannot be told apart safely and stays read only.
+ */
+export const rowKeyOf = (structure, loaded, row) => {
+    const cells = loaded.rows[row];
+    if (structure.rowKey === null || cells === undefined) {
+        return null;
+    }
+    const key = {};
+    for (const name of structure.rowKey) {
+        const index = loaded.columns.findIndex((column) => column.name === name);
+        const value = index < 0 ? undefined : valueOfCell(cells[index]);
+        if (value === undefined) {
+            return null;
+        }
+        key[name] = value;
+    }
+    return key;
+};
+const numeric = (text) => Number(text);
+/* Updates, then deletes, then inserts, all computed against the page as loaded. Throws for a change on a row without a usable key, which the grid never lets a person make. */
+export const toRowChanges = (structure, loaded, pending) => {
+    const keyOf = (row) => {
+        const key = rowKeyOf(structure, loaded, row);
+        if (key === null) {
+            throw new Error(`Row ${row + 1} of ${structure.name} has no usable key.`);
+        }
+        return key;
+    };
+    const updates = Object.keys(pending.edits)
+        .map(numeric)
+        .filter((row) => !pending.deletes.has(row))
+        .sort((left, right) => left - right)
+        .map((row) => ({ kind: 'update', key: keyOf(row), values: pending.edits[row] }));
+    const deletes = [...pending.deletes].sort((left, right) => left - right).map((row) => ({ kind: 'delete', key: keyOf(row) }));
+    const inserts = pending.inserts.map((row) => ({ kind: 'insert', values: row.values }));
+    return [...updates, ...deletes, ...inserts];
+};
+/* A key as a person would write it in a WHERE: `id = 5, tenant = 'a'`. */
+export const describeKey = (key) => Object.entries(key)
+    .map(([column, value]) => `${column} = ${value === null ? 'NULL' : typeof value === 'object' ? `0x${value.hex}` : typeof value === 'string' ? `'${value}'` : String(value)}`)
+    .join(', ');

package/dist/table/references.d.ts

@@ -0,0 +1,12 @@
+import type { Shown } from '../grid/display.ts';
+import type { Engine, ForeignKeyInfo, ValueKind } from '../protocol/index.ts';
+export interface Reference {
+    readonly schema: string;
+    readonly table: string;
+    readonly where: string;
+}
+export declare const foreignKeyOf: (foreignKeys: readonly ForeignKeyInfo[], column: string) => ForeignKeyInfo | undefined;
+export declare const referenceOf: (engine: Engine, key: ForeignKeyInfo, columns: readonly {
+    readonly name: string;
+    readonly kind: ValueKind;
+}[], cells: readonly Shown[]) => Reference | null;

package/dist/table/references.js

@@ -0,0 +1,21 @@
+import { wholeValueOf } from '../grid/focused-value.js';
+import { matchCondition } from '../sql.js';
+/* The foreign key a column is part of; the first one when a column sits in several. */
+export const foreignKeyOf = (foreignKeys, column) => foreignKeys.find((key) => key.columns.includes(column));
+/*
+ * The row a foreign key points to, from the cells of the referencing row. `null` when any column of
+ * the key is NULL (it references nothing), is only a preview, or is not among the columns.
+ */
+export const referenceOf = (engine, key, columns, cells) => {
+    const matches = [];
+    for (const [position, name] of key.columns.entries()) {
+        const referenced = key.referencedColumns[position];
+        const index = columns.findIndex((column) => column.name === name);
+        const value = index < 0 ? undefined : wholeValueOf(cells[index] ?? null);
+        if (referenced === undefined || value === undefined || value === null) {
+            return null;
+        }
+        matches.push({ column: referenced, value, kind: columns[index].kind });
+    }
+    return matches.length === 0 ? null : { schema: key.referencedSchema, table: key.referencedTable, where: matchCondition(engine, matches) };
+};

package/dist/table/useLoaded.d.ts

@@ -0,0 +1,7 @@
+export interface Loaded<T> {
+    value: T | null;
+    loading: boolean;
+    error: string | null;
+    reload(): void;
+}
+export declare function useLoaded<T>(load: (signal: AbortSignal) => Promise<T>, key: string): Loaded<T>;

package/dist/table/useLoaded.js

@@ -0,0 +1,36 @@
+import { useEffect, useRef, useState } from 'react';
+import { messageOf } from '@adecore/ui';
+/*
+ * Runs `load` when `key` changes or `reload` is called, and aborts the run that is still going.
+ * `key` has to name everything `load` reads, since `load` itself is a new function on every render.
+ * A value belongs to the hook's owner, which is remounted for a different subject, so it outlives a key change.
+ */
+export function useLoaded(load, key) {
+    const loader = useRef(load);
+    const [version, setVersion] = useState(0);
+    // Loading is not a state of its own: it is that the last answer is not for this key and this version.
+    const [state, setState] = useState({ key: '', version: -1, value: null, error: null });
+    useEffect(() => {
+        loader.current = load;
+    });
+    useEffect(() => {
+        const controller = new AbortController();
+        loader.current(controller.signal).then((value) => {
+            if (!controller.signal.aborted) {
+                setState({ key, version, value, error: null });
+            }
+        }, (error) => {
+            if (!controller.signal.aborted) {
+                setState((now) => ({ key, version, value: now.value, error: messageOf(error) }));
+            }
+        });
+        return () => controller.abort();
+    }, [key, version]);
+    const answered = state.key === key && state.version === version;
+    return {
+        value: state.value,
+        loading: !answered,
+        error: answered ? state.error : null,
+        reload: () => setVersion((now) => now + 1)
+    };
+}

package/dist/table/useStoredLayout.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseStorage } from '../actions.ts';
+import { type StoredLayout } from './layout-store.ts';
+export declare const STORE_DELAY_MS = 500;
+export interface StoredLayoutHandle {
+    readonly stored: StoredLayout | null;
+    remember(change: Partial<StoredLayout>): void;
+}
+export declare function useStoredLayout(storage: DatabaseStorage | undefined, key: string): StoredLayoutHandle;