@adecore/database 0.0.1 → 0.16.0-beta.0

package/src/table/command-field.ts

@@ -0,0 +1,285 @@
+import type { Engine, ValueKind } from '../protocol/index.ts';
+import {
+    equalsCondition,
+    findColumn,
+    notEqualsCondition,
+    orderByClause,
+    parseOrderByLoose,
+    quoteIdentifier,
+    sqlLiteral,
+    type ColumnSort,
+    type LiteralValue,
+    type SortDirection
+} from '../sql.ts';
+
+/* A condition of the WHERE: `text` is what the chip shows and what editing it starts from, `sql` what goes to the server. */
+export interface FilterChip {
+    readonly kind: 'filter';
+    readonly text: string;
+    readonly sql: string;
+}
+
+export interface SortChip {
+    readonly kind: 'sort';
+    readonly column: string;
+    readonly direction: SortDirection;
+}
+
+/* An ORDER BY that is more than a list of columns, such as one with `NULLS LAST`, kept as it was written. */
+export interface OrderChip {
+    readonly kind: 'order';
+    readonly text: string;
+}
+
+export type Chip = FilterChip | SortChip | OrderChip;
+
+export type StoredFilter = Pick<FilterChip, 'text' | 'sql'>;
+
+export interface CommandColumn {
+    readonly name: string;
+    readonly type: string;
+}
+
+export type Suggestion =
+    | { readonly kind: 'condition'; readonly chip: FilterChip }
+    | { readonly kind: 'filter' | 'sort' | 'jump'; readonly column: CommandColumn }
+    | { readonly kind: 'sql'; readonly chip: FilterChip };
+
+/* 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): string => (chip.kind === 'sort' ? `sort:${chip.column}` : `${chip.kind}:${chip.kind === 'filter' ? chip.sql : chip.text}`);
+
+const isFilter = (chip: Chip): chip is FilterChip => chip.kind === 'filter';
+
+const isSort = (chip: Chip): chip is SortChip => 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: string): string => (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: readonly Chip[]): string => {
+    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: Engine, chips: readonly Chip[]): string =>
+    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: readonly Chip[]): ColumnSort[] => 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: readonly Chip[], sorts: readonly ColumnSort[]): Chip[] => [
+    ...chips.filter(isFilter),
+    ...sorts.map((sort): Chip => ({ 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: readonly Chip[], column: string): Chip[] => {
+    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: readonly Chip[], chip: Chip): Chip[] =>
+    chips.some((other) => chipKey(other) === chipKey(chip)) ? [...chips] : [...chips, chip];
+
+export const removeChipAt = (chips: readonly Chip[], index: number): Chip[] => 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: readonly Chip[], index: number, chip: Chip): 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: string): FilterChip => ({ 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: string, remembered: readonly StoredFilter[] = []): Chip[] => {
+    const text = where.trim();
+    if (text === '') {
+        return [];
+    }
+    const kept = remembered.map((filter): FilterChip => ({ 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: Engine, orderBy: string): Chip[] => {
+    const text = orderBy.trim();
+    if (text === '') {
+        return [];
+    }
+    const sorts = parseOrderByLoose(engine, text);
+    return sorts === null ? [{ kind: 'order', text }] : sorts.map((sort): Chip => ({ kind: 'sort', column: sort.column, direction: sort.direction }));
+};
+
+export interface ChipSource {
+    readonly where: string;
+    readonly orderBy: string;
+    readonly remembered?: readonly StoredFilter[];
+}
+
+export const chipsFromQuery = (engine: Engine, { where, orderBy, remembered }: ChipSource): Chip[] => [
+    ...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: string): boolean => {
+    let quote: string | null = 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: string): string => 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: string): string | null => {
+    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: Engine, text: string, columns: readonly string[]): FilterChip | null => {
+    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: Engine, column: string, value: LiteralValue, kind: ValueKind | undefined, exclude: boolean): FilterChip => {
+    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: string, limit: number): string => (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: string, token: string): number | null => {
+    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: readonly CommandColumn[], typed: string, limit = SUGGESTED_COLUMNS): CommandColumn[] => {
+    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 is { column: CommandColumn; order: number; rank: number } => 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: Engine, text: string, columns: readonly CommandColumn[], limit = SUGGESTED_COLUMNS): Suggestion[] => {
+    const typed = text.trim();
+    if (typed === '') {
+        return [];
+    }
+    const suggestions: Suggestion[] = [];
+    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: CommandColumn): string => `${identifierText(column.name)} `;

package/src/table/grid-rows.ts

@@ -0,0 +1,80 @@
+import { shownOfEdit, type Shown } from '../grid/display.ts';
+import { wholeValueOf } from '../grid/focused-value.ts';
+import { gridColumnOf, type GridColumn, type GridRow } from '../grid/types.ts';
+import type { EditValue, RowsResult, TableStructure } from '../protocol/index.ts';
+import { rowKeyOf, type PendingChanges } from './pending.ts';
+
+export type RowRef = { readonly kind: 'loaded'; readonly index: number } | { readonly kind: 'inserted'; readonly id: number };
+
+export const loadedRowKey = (index: number): string => `row:${index}`;
+
+export const insertedRowKey = (id: number): string => `new:${id}`;
+
+export const parseRowKey = (key: string): RowRef =>
+    key.startsWith('new:') ? { kind: 'inserted', id: Number(key.slice(4)) } : { kind: 'loaded', index: Number(key.slice(4)) };
+
+export const buildGridColumns = (loaded: Pick<RowsResult, 'columns'>, structure: TableStructure | null): GridColumn[] =>
+    loaded.columns.map((column) =>
+        gridColumnOf(
+            column,
+            structure?.columns.find((info) => info.name === column.name),
+            structure?.primaryKey ?? []
+        )
+    );
+
+export interface GridRowsInput {
+    readonly structure: TableStructure | null;
+    readonly loaded: Pick<RowsResult, 'columns' | 'rows'>;
+    readonly pending: PendingChanges;
+    /* Rows before this page, so the gutter counts from the first row of the table. */
+    readonly offset: number;
+}
+
+/* The loaded rows with their pending edits laid over them, then the rows waiting to be inserted. */
+export const buildGridRows = ({ structure, loaded, pending, offset }: GridRowsInput): GridRow[] => {
+    const rows = loaded.rows.map((cells, index): GridRow => {
+        const edits = pending.edits[index];
+        const edited = new Set<number>();
+        const shown = cells.map((cell, column): Shown => {
+            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): GridRow => ({
+        key: insertedRowKey(row.id),
+        number: null,
+        cells: loaded.columns.map((column): Shown => {
+            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: readonly GridColumn[], cells: readonly Shown[]): Record<string, EditValue> => {
+    const values: Record<string, EditValue> = {};
+    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/src/table/import-mapping.ts

@@ -0,0 +1,37 @@
+import type { ColumnInfo } from '../protocol/index.ts';
+
+export type ImportFormat = 'csv' | 'tsv';
+
+/* The columns an import can fill: a generated column is computed by the server. */
+export const importableColumns = (columns: readonly ColumnInfo[]): ColumnInfo[] => columns.filter((column) => !column.generated);
+
+/* CSV or TSV by the extension of the path; CSV when it says neither. */
+export const formatOfPath = (path: string): ImportFormat => (/\.(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: readonly string[], tableColumns: readonly string[], header: boolean): (string | null)[] => {
+    if (!header) {
+        return fileColumns.map((_, index) => tableColumns[index] ?? null);
+    }
+    const taken = new Set<string>();
+    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: readonly (string | null)[]): boolean => 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: readonly (string | null)[], fileColumn: number, tableColumn: string | null): (string | null)[] =>
+    mapping.map((current, index) => (index === fileColumn ? tableColumn : tableColumn !== null && current === tableColumn ? null : current));

package/src/table/layout-store.ts

@@ -0,0 +1,62 @@
+import type { GridLayout } from '../grid/column-layout.ts';
+import type { StoredFilter } from './command-field.ts';
+import { PAGE_SIZES } from './paging.ts';
+
+/* 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;
+
+/* What is remembered of one table's view between visits. */
+export interface StoredLayout extends GridLayout {
+    readonly pageSize: number | null;
+    readonly where: string;
+    readonly orderBy: string;
+    /* The filter chips as typed, which `where` alone would only give back as one raw condition. */
+    readonly filters: readonly StoredFilter[];
+}
+
+export const EMPTY_LAYOUT: StoredLayout = { widths: {}, hidden: [], pinned: [], pageSize: null, where: '', orderBy: '', filters: [] };
+
+export const layoutStorageKey = (connectionId: string, schema: string, table: string): string => `database:table:${connectionId}:${schema}.${table}`;
+
+const isStringList = (value: unknown): value is string[] => Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+const isStoredFilter = (value: unknown): value is StoredFilter =>
+    isRecord(value) && typeof value.text === 'string' && typeof value.sql === 'string' && value.sql.trim() !== '';
+
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+export const serializeLayout = (layout: StoredLayout): string => 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: string | null): StoredLayout | null => {
+    if (text === null) {
+        return null;
+    }
+    let data: unknown;
+    try {
+        data = JSON.parse(text);
+    } catch {
+        return null;
+    }
+    if (!isRecord(data) || data.version !== LAYOUT_VERSION) {
+        return null;
+    }
+    const widths: Record<string, number> = {};
+    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/src/table/paging.ts

@@ -0,0 +1,33 @@
+export const PAGE_SIZES = [100, 500, 1000] as const;
+export const DEFAULT_PAGE_SIZE = 500;
+
+export interface PageBounds {
+    /* One-based number of the first and last row on the page; both 0 on an empty page. */
+    readonly from: number;
+    readonly to: number;
+    /* The number of rows in the table when known, else the least it can be (`exact` is then false). */
+    readonly total: number;
+    readonly exact: boolean;
+    readonly hasPrevious: boolean;
+    readonly hasNext: boolean;
+}
+
+/*
+ * 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: number, rowCount: number, hasMore: boolean, counted: number | null): PageBounds => {
+    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: number, pageSize: number): number => (total <= 0 ? 0 : Math.floor((total - 1) / pageSize) * pageSize);

package/src/table/pending.ts

@@ -0,0 +1,143 @@
+import { valueOfCell, type Cell, type EditValue, type RowChange, type RowKey, type RowsResult, type TableStructure, type Value } from '../protocol/index.ts';
+
+export interface InsertedRow {
+    /* Unique among the inserted rows; the grid keys the row by it. */
+    readonly id: number;
+    /* The columns a person filled in; the others take their default. */
+    readonly values: Readonly<Record<string, EditValue>>;
+}
+
+/*
+ * What a person changed on one page of a table and has not submitted yet. Rows are named by their
+ * index in the page as loaded, so a pending set belongs to that page and is dropped with it.
+ */
+export interface PendingChanges {
+    readonly edits: Readonly<Record<number, Readonly<Record<string, EditValue>>>>;
+    readonly inserts: readonly InsertedRow[];
+    readonly deletes: ReadonlySet<number>;
+}
+
+export const emptyPending: PendingChanges = { edits: {}, inserts: [], deletes: new Set() };
+
+export const isPendingEmpty = (pending: PendingChanges): boolean =>
+    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: PendingChanges): number =>
+    Object.keys(pending.edits).filter((row) => !pending.deletes.has(Number(row))).length + pending.inserts.length + pending.deletes.size;
+
+export const valuesEqual = (left: EditValue | undefined, right: EditValue | undefined): boolean => {
+    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: PendingChanges, row: number, column: string, value: EditValue, original: Cell): PendingChanges => {
+    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: PendingChanges, values: Readonly<Record<string, EditValue>>): PendingChanges => ({
+    ...pending,
+    inserts: [...pending.inserts, { id: pending.inserts.reduce((highest, row) => Math.max(highest, row.id), 0) + 1, values }]
+});
+
+export const addInsert = (pending: PendingChanges): PendingChanges => addInsertWith(pending, {});
+
+export const setInsertValue = (pending: PendingChanges, id: number, column: string, value: EditValue): PendingChanges => ({
+    ...pending,
+    inserts: pending.inserts.map((row) => (row.id === id ? { ...row, values: { ...row.values, [column]: value } } : row))
+});
+
+export const removeInsert = (pending: PendingChanges, id: number): PendingChanges => ({ ...pending, inserts: pending.inserts.filter((row) => row.id !== id) });
+
+export const markDeleted = (pending: PendingChanges, rows: readonly number[]): PendingChanges => ({
+    ...pending,
+    deletes: new Set([...pending.deletes, ...rows])
+});
+
+/* Takes back every change to one loaded row: its edits and its deletion. */
+export const revertRow = (pending: PendingChanges, row: number): PendingChanges => {
+    const { [row]: _dropped, ...edits } = pending.edits;
+    const deletes = new Set(pending.deletes);
+    deletes.delete(row);
+    return { ...pending, edits, deletes };
+};
+
+/* Rows of a page, by the index of the loaded ones and the id of the inserted ones. */
+export interface RowSelectionRefs {
+    readonly loaded: readonly number[];
+    readonly inserted: readonly number[];
+}
+
+/* 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: PendingChanges, rows: RowSelectionRefs): PendingChanges => {
+    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: PendingChanges, rows: RowSelectionRefs): boolean =>
+    rows.loaded.some((row) => pending.edits[row] !== undefined || pending.deletes.has(row)) || pending.inserts.some((row) => rows.inserted.includes(row.id));
+
+type LoadedRows = Pick<RowsResult, 'columns' | 'rows'>;
+
+/*
+ * 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: TableStructure, loaded: LoadedRows, row: number): RowKey | null => {
+    const cells = loaded.rows[row];
+    if (structure.rowKey === null || cells === undefined) {
+        return null;
+    }
+    const key: Record<string, Value> = {};
+    for (const name of structure.rowKey) {
+        const index = loaded.columns.findIndex((column) => column.name === name);
+        const value = index < 0 ? undefined : valueOfCell(cells[index] as Cell);
+        if (value === undefined) {
+            return null;
+        }
+        key[name] = value;
+    }
+    return key;
+};
+
+const numeric = (text: string): number => 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: TableStructure, loaded: LoadedRows, pending: PendingChanges): RowChange[] => {
+    const keyOf = (row: number): RowKey => {
+        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): RowChange => ({ kind: 'update', key: keyOf(row), values: pending.edits[row]! }));
+    const deletes = [...pending.deletes].sort((left, right) => left - right).map((row): RowChange => ({ kind: 'delete', key: keyOf(row) }));
+    const inserts = pending.inserts.map((row): RowChange => ({ 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: RowKey): string =>
+    Object.entries(key)
+        .map(
+            ([column, value]) =>
+                `${column} = ${value === null ? 'NULL' : typeof value === 'object' ? `0x${value.hex}` : typeof value === 'string' ? `'${value}'` : String(value)}`
+        )
+        .join(', ');