nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/CrudBackend.js

@@ -0,0 +1,214 @@
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export class CrudBackend {
+    /** Reads a whole list: an array, or the rows of a page. */
+    readList(result) {
+        if (Array.isArray(result))
+            return result;
+        return [...this.readPage(result).rows];
+    }
+    /**
+     * Changes an action's answer makes to rows, by key: a mass flag that answers each record's new status. Rows without
+     * an entry take the change the action stands for (a toggled flag). Default: none.
+     */
+    answeredChanges(result, rowKey) {
+        void result;
+        void rowKey;
+        return new Map();
+    }
+    /**
+     * The keys of the records an action changed, when its answer lists them: a mass trash where some records could not
+     * move. `null` when the answer does not say, and every record sent counts as changed. Default `null`.
+     */
+    answeredKeys(result, rowKey) {
+        void result;
+        void rowKey;
+        return null;
+    }
+    /**
+     * What an answer says about the one record an action wrote: the record itself, or only the fields that changed.
+     * `null` when it says nothing about it - a bare key, an empty body - and then the caller keeps what it has.
+     *
+     * **This is what spares a page its reload.** A save or a mark whose answer carries the record is written into the
+     * table, the pinned band and every list kept in the cache, and nothing is loaded again. Only answers of actions on
+     * **one** record are read here; a mass answer goes through `answeredChanges`, record by record.
+     */
+    answeredRow(result) {
+        void result;
+        return null;
+    }
+    /**
+     * The key an answer gives in place of the record: `Create` answering the new record's id. `null` when the answer
+     * is the record itself, or says nothing. With a key the new record goes straight into the list, and where there is
+     * a `details` endpoint it is read back on its own - one small request, never the whole list again.
+     */
+    answeredKey(result) {
+        void result;
+        return null;
+    }
+    /**
+     * Whether a record belongs in a list, read from the record itself. It is what lets one answer be written into the
+     * lists that are **not** on screen: a flagged record joins the flagged list, a trashed one leaves the active list
+     * and joins the trash, in the cache as well as in the table.
+     *
+     * `undefined` when the record does not say, and a list it cannot answer for is dropped from the cache and loads
+     * again when it is shown. Default: nothing is known, which is how every list behaved before.
+     */
+    listMembership(row, mode) {
+        void row;
+        void mode;
+        return undefined;
+    }
+}
+/*
+ * The Nexus record statuses, as the backend's `ERecordStatus` numbers them. A record's status is a number in a band,
+ * and the bands the owner settled on 2026-09-25 are:
+ *
+ *   0–39   active        (anything under 40 is a live record)
+ *     0–29 active account
+ *       25–29 flag
+ *     30–39 pending, unverified, in review, approval required
+ *   40–59  trash
+ *   60+    delete
+ *
+ * The flag is a **range**, 25–29, and this file checks a single value: the seeded `ERecordStatus.Flagged` is 25, and
+ * nothing yet defines what 26–29 would mean. A range-aware check belongs with the per-project bands being built on
+ * `/v2/core-config`, so it is deliberately not here — and this note is here so the single value is not mistaken for
+ * the final answer.
+ */
+/** The Nexus record status of a flagged record (`ERecordStatus.Flagged`), the bottom of the 25–29 flag band. */
+export const NEXUS_FLAGGED_STATUS = 25;
+/** The Nexus record status of an active record (`ERecordStatus.Active`), the bottom of the 0–39 active band. */
+export const NEXUS_ACTIVE_STATUS = 0;
+/** The Nexus record status of a record in the trash (`ERecordStatus.Trash`), the bottom of the 40–59 trash band. */
+export const NEXUS_TRASH_STATUS = 40;
+/** The Nexus record status of a deleted record (`ERecordStatus.PermanentDeleted`), the bottom of the 60+ delete band. */
+export const NEXUS_DELETED_STATUS = 60;
+/** Just past the flag band: a flagged record is 25–29, so 30 and up is live but not flagged. */
+const NEXUS_FLAG_BAND_END = 30;
+/**
+ * The Nexus backend: pages as `{ searchKeyword, skipCount, maxCount, sorting, sortType }` answered with
+ * `{ results, totalCount, filterCount }`, newest first unless a column is sorted; mass actions send the ids
+ * (`{ description, accountIds }` for descriptions); a flagged record has `recordStatus` 25, a pinned one `isPinned`.
+ */
+export class NexusCrudBackend extends CrudBackend {
+    pageRequest(query, sortKey) {
+        return {
+            searchKeyword: query.search,
+            skipCount: (query.page - 1) * query.pageSize,
+            maxCount: query.pageSize,
+            sorting: query.sort ? (sortKey ?? query.sort.key) : "creationTime",
+            sortType: query.sort ? query.sort.direction : "desc",
+        };
+    }
+    readPage(result) {
+        if (Array.isArray(result))
+            return { rows: result };
+        if (!isRecord(result))
+            return { rows: [] };
+        const rows = (Array.isArray(result.results) ? result.results : []);
+        const total = Number(result.totalCount);
+        const matches = Number(result.filterCount);
+        return {
+            rows,
+            total: Number.isFinite(total) ? total : rows.length,
+            matches: Number.isFinite(matches) ? matches : Number.isFinite(total) ? total : rows.length,
+        };
+    }
+    massRequest(action, keys, values) {
+        return action === "description" ? { description: values?.description ?? null, accountIds: keys } : keys;
+    }
+    isFlagged(row) {
+        return Number(row.recordStatus) === NEXUS_FLAGGED_STATUS;
+    }
+    withFlag(row, on) {
+        return { ...row, recordStatus: on ? NEXUS_FLAGGED_STATUS : NEXUS_ACTIVE_STATUS };
+    }
+    isPinned(row) {
+        return row.isPinned === true;
+    }
+    withPin(row, on) {
+        return { ...row, isPinned: on };
+    }
+    /** Mass answers list the records they changed, with their new `recordStatus` and `isPinned`. */
+    answeredChanges(result, rowKey) {
+        const changes = new Map();
+        const items = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.results) ? result.results : [];
+        for (const item of items) {
+            if (!isRecord(item))
+                continue;
+            const key = item[rowKey];
+            if (key === undefined || key === null)
+                continue;
+            const change = {};
+            if ("recordStatus" in item)
+                change.recordStatus = item.recordStatus;
+            if ("isPinned" in item)
+                change.isPinned = item.isPinned;
+            if (Object.keys(change).length)
+                changes.set(String(key), change);
+        }
+        return changes;
+    }
+    /**
+     * A write answers the record it wrote, or a value that is not one. `Create` and `Update` answer the new record's
+     * **id token**, which says nothing the caller does not already hold, so it is read as nothing; a mark answers the
+     * record's new **`ERecordStatus`**, which is the one field that changed and is what puts the record in the right
+     * list without loading one. A backend that answers the whole record is read as that record.
+     */
+    answeredRow(result) {
+        if (isRecord(result))
+            return result;
+        // A token is text and a status is a number, so the two can never be read for each other.
+        if (typeof result === "number" && Number.isInteger(result) && result >= 0)
+            return { recordStatus: result };
+        return null;
+    }
+    /** `Create` and `Update` answer the record's id: a token when ids are encrypted, the number as text when not. */
+    answeredKey(result) {
+        return typeof result === "string" && result !== "" ? result : null;
+    }
+    /**
+     * The bands the owner settled on: under 40 is live, 25–29 of that is flagged, 40–59 is the trash, and 60 and up is
+     * deleted. A row without a `recordStatus` says nothing, and the lists it cannot answer for load again.
+     */
+    listMembership(row, mode) {
+        const status = row.recordStatus;
+        if (typeof status !== "number" || !Number.isFinite(status))
+            return undefined;
+        switch (mode) {
+            case "normal":
+                return status < NEXUS_TRASH_STATUS;
+            case "flag":
+                return status >= NEXUS_FLAGGED_STATUS && status < NEXUS_FLAG_BAND_END;
+            case "trash":
+                return status >= NEXUS_TRASH_STATUS && status < NEXUS_DELETED_STATUS;
+            case "deleted":
+                return status >= NEXUS_DELETED_STATUS;
+            default:
+                return undefined;
+        }
+    }
+    /** Mass answers list the records they changed (as records, or as ids); other answers say nothing. */
+    answeredKeys(result, rowKey) {
+        const items = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.results) ? result.results : null;
+        if (!items)
+            return null;
+        const keys = new Set();
+        for (const item of items) {
+            const key = isRecord(item) ? item[rowKey] : item;
+            if (typeof key === "string" || typeof key === "number")
+                keys.add(String(key));
+        }
+        return keys;
+    }
+}
+let current = null;
+/** Registers the app's backend conventions, once, beside its API modules. */
+export function defineCrudBackend(backend) {
+    current = backend;
+    return backend;
+}
+/** The registered backend conventions, or the Nexus ones. */
+export function getCrudBackend() {
+    return (current ??= new NexusCrudBackend());
+}

package/dist/Helpers/CrudHelpers.d.ts

@@ -0,0 +1,111 @@
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { CrudActionName, CrudEndpoints, CrudMassActionName, CrudMode, CrudRowActionName } from "../Interfaces/CrudInterfaces.ts";
+import type { MessageActionName } from "../Interfaces/MessageInterfaces.ts";
+import type { TablePage, TablePaging, TableRow } from "../Interfaces/TableInterfaces.ts";
+/** Every list, in the order the CRUD shows them. */
+export declare const CRUD_MODES: readonly CrudMode[];
+/** The built-in actions on one record, per list, in their menu order. */
+export declare const CRUD_ROW_ACTIONS: Readonly<Record<CrudMode, readonly CrudRowActionName[]>>;
+/** The built-in actions on selected records, per list. */
+export declare const CRUD_MASS_ACTIONS: Readonly<Record<CrudMode, readonly CrudMassActionName[]>>;
+/**
+ * The built-in actions a list offers, in menu order, of those `allowed`. A controller without a trash (`trashless`: no
+ * trash endpoint, or trash not asked for) offers Delete where Move to trash would be. A trash the user may not use never
+ * turns into Delete.
+ */
+export declare function crudRowActions(mode: CrudMode, allowed: (action: CrudRowActionName) => boolean, trashless?: boolean): CrudRowActionName[];
+/** The built-in actions on selected records a list offers, with the same Delete for a controller without a trash. */
+export declare function crudMassActions(mode: CrudMode, allowed: (action: CrudMassActionName) => boolean, trashless?: boolean): CrudMassActionName[];
+/** The endpoint of a list: its full list for tables that page in the browser, its pages for server tables. */
+export declare function crudListEndpoint(api: CrudEndpoints, mode: CrudMode, paging: TablePaging): ApiEndpoint | undefined;
+/** The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one). */
+export declare function crudRowEndpoint(api: CrudEndpoints, action: CrudRowActionName): ApiEndpoint | undefined;
+/** The lists a CRUD can offer: asked for, with an endpoint, and allowed. */
+export declare function availableModes(api: CrudEndpoints, paging: TablePaging, wanted: readonly CrudMode[], can: (endpoint: ApiEndpoint) => boolean): CrudMode[];
+/**
+ * Whether a built-in action can run: asked for, with an endpoint, and allowed. View also works without a `details`
+ * endpoint (it shows the row), but a `details` endpoint the user may not call hides it, as in the old CRUD.
+ */
+export declare function actionAllowed(action: CrudActionName, api: CrudEndpoints, wanted: readonly CrudActionName[], can: (endpoint: ApiEndpoint) => boolean): boolean;
+/** Whether a mass action can run: its row action is wanted, and its mass endpoint exists and is allowed. */
+export declare function massActionAllowed(action: CrudMassActionName, api: CrudEndpoints, wanted: readonly CrudActionName[], can: (endpoint: ApiEndpoint) => boolean): boolean;
+/**
+ * Whether a record leaves the list shown after an action. Trash, recover, delete, and moving back to the trash take it
+ * to another list, and unflagging leaves the flagged list. Pinning and unpinning never do: a pinned
+ * record stays in the list it is in. `markOn` is the record's new flag.
+ */
+export declare function leavesList(action: CrudRowActionName | CrudMassActionName, mode: CrudMode, markOn?: boolean): boolean;
+/** The message builder's action for a built-in action: "Guest recovered.", "Unpin 3 guests?" */
+export declare function crudMessageAction(action: CrudRowActionName | CrudMassActionName, markOn?: boolean): MessageActionName;
+/** What every CRUD follows, whatever module it shows. `configureCrud` changes it once, for the whole app. */
+export interface CrudSettings {
+    /**
+     * Most records a user may pin. Default 100. Lowering it never unpins anything: a user over the new limit keeps their
+     * pins and can unpin, and may pin again once they are under it.
+     */
+    maxPins: number;
+}
+/**
+ * Changes what every CRUD follows, once, where the app registers its API modules: `configureCrud({ maxPins: 50 })`.
+ * Values left out keep what they had.
+ */
+export declare function configureCrud(changes: Partial<CrudSettings>): CrudSettings;
+/** The settings every CRUD follows. */
+export declare function getCrudSettings(): CrudSettings;
+/**
+ * How many more records may be pinned: the limit less the records pinned, never below zero. `pinned` is `undefined`
+ * when nothing counts the pins (no `pins` endpoint), and then there is no limit to keep.
+ */
+export declare function pinRoom(pinned: number | undefined, max?: number): number;
+/** Default time a CRUD keeps a list: 5 minutes. */
+export declare const CRUD_CACHE_LIFETIME: number;
+/** Lists kept while a page is open, by key, each for a lifetime. Plain values; nothing is written to storage. */
+export declare class CrudCache<T = unknown> {
+    private entries;
+    readonly lifetime: number;
+    private now;
+    constructor(lifetime?: number, now?: () => number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    /** Replaces a value, keeping its age, so a changed list does not live longer than the list it came from. */
+    update(key: string, value: T): void;
+    /**
+     * Writes a change through every entry, each keeping its age: this is how a record that was saved or marked reaches
+     * the lists that are not on screen without a request. Returning `null` drops that entry, and its list loads again
+     * the next time it is shown.
+     */
+    map(change: (key: string, value: T) => T | null): void;
+    /** Drops every entry whose key passes the test. */
+    drop(test: (key: string) => boolean): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * A record a change touched, as the lists kept in the cache are patched from it: how it is now, how it was, and
+ * whether it is in any list at all any more.
+ */
+export interface CrudRowChange<TRow extends TableRow = TableRow> {
+    /** The record's key, as the table reads it. */
+    key: string;
+    /** The record as it is now. */
+    row: TRow;
+    /** The record as it was, when the page had it. Without it, a list that holds the record counts as having held it. */
+    before: TRow | undefined;
+    /** The record is in no list any more, whatever it says: it is taken out of every list kept. */
+    gone?: boolean;
+}
+/** The list a cache entry belongs to: the key itself for a whole list, its first part for one page of one. */
+export declare function crudCacheMode(key: string): CrudMode;
+/**
+ * One list kept in the cache, after a change: the records that belong in it are written in, the ones that no longer
+ * belong are taken out, and the entry is returned as it should now be. `null` means the list cannot be worked out
+ * and has to be loaded again.
+ *
+ * `member` is the backend's rule for which list a record belongs in (`CrudBackend.listMembership`). A record it
+ * cannot answer for drops the entry, which is what every list did before this.
+ *
+ * **A whole list** is patched: a record that joined it goes on top, where the table also shows a record just added.
+ * **One page of a list** is not: its order, its last row and its counts are the server's, so as soon as a record
+ * joined it or left it the page is dropped; a record that stayed is written in place, which costs nothing.
+ */
+export declare function patchCachedList<TRow extends TableRow>(value: TablePage<TRow> | TRow[], mode: CrudMode, changes: readonly CrudRowChange<TRow>[], keyOf: (row: TRow) => string, member: (row: TRow, mode: CrudMode) => boolean | undefined): TablePage<TRow> | TRow[] | null;

package/dist/Helpers/CrudHelpers.js

@@ -0,0 +1,267 @@
+/*
+ * The rules of the CRUD component, with no React: which lists and actions a controller offers, which actions each list
+ * shows, which records leave a list after an action, the settings every CRUD follows (how many records may be pinned),
+ * and the cache of lists kept while the page is open - including how a change is written into the lists kept, so that
+ * a record saved or marked costs no request on any list.
+ */
+/** Every list, in the order the CRUD shows them. */
+export const CRUD_MODES = ["normal", "flag", "trash", "deleted"];
+const ACTIVE_ROW_ACTIONS = ["view", "edit", "flag", "pin", "trash"];
+const ACTIVE_MASS_ACTIONS = ["flag", "pin", "description", "trash"];
+/** The built-in actions on one record, per list, in their menu order. */
+export const CRUD_ROW_ACTIONS = {
+    normal: ACTIVE_ROW_ACTIONS,
+    flag: ACTIVE_ROW_ACTIONS,
+    trash: ["view", "recover", "delete"],
+    deleted: ["view", "trashFromDelete"],
+};
+/** The built-in actions on selected records, per list. */
+export const CRUD_MASS_ACTIONS = {
+    normal: ACTIVE_MASS_ACTIONS,
+    flag: ACTIVE_MASS_ACTIONS,
+    trash: ["recover", "description", "delete"],
+    deleted: ["trashFromDelete"],
+};
+/**
+ * The built-in actions a list offers, in menu order, of those `allowed`. A controller without a trash (`trashless`: no
+ * trash endpoint, or trash not asked for) offers Delete where Move to trash would be. A trash the user may not use never
+ * turns into Delete.
+ */
+export function crudRowActions(mode, allowed, trashless = false) {
+    const list = [];
+    for (const action of CRUD_ROW_ACTIONS[mode]) {
+        if (action === "trash" && trashless) {
+            if (allowed("delete"))
+                list.push("delete");
+        }
+        else if (allowed(action))
+            list.push(action);
+    }
+    return list;
+}
+/** The built-in actions on selected records a list offers, with the same Delete for a controller without a trash. */
+export function crudMassActions(mode, allowed, trashless = false) {
+    const list = [];
+    for (const action of CRUD_MASS_ACTIONS[mode]) {
+        if (action === "trash" && trashless) {
+            if (allowed("delete"))
+                list.push("delete");
+        }
+        else if (allowed(action))
+            list.push(action);
+    }
+    return list;
+}
+/** The endpoint of a list: its full list for tables that page in the browser, its pages for server tables. */
+export function crudListEndpoint(api, mode, paging) {
+    return paging === "server" ? api.pages?.[mode] : api.lists?.[mode];
+}
+/** The endpoint of a row action. `view` needs none of its own: it shows the row (and calls `details` when there is one). */
+export function crudRowEndpoint(api, action) {
+    if (action === "view")
+        return api.details;
+    if (action === "edit")
+        return api.update;
+    return api[action];
+}
+/** The lists a CRUD can offer: asked for, with an endpoint, and allowed. */
+export function availableModes(api, paging, wanted, can) {
+    return CRUD_MODES.filter(mode => wanted.includes(mode)).filter(mode => {
+        const endpoint = crudListEndpoint(api, mode, paging);
+        return Boolean(endpoint) && can(endpoint);
+    });
+}
+/**
+ * Whether a built-in action can run: asked for, with an endpoint, and allowed. View also works without a `details`
+ * endpoint (it shows the row), but a `details` endpoint the user may not call hides it, as in the old CRUD.
+ */
+export function actionAllowed(action, api, wanted, can) {
+    if (!wanted.includes(action))
+        return false;
+    if (action === "create")
+        return Boolean(api.create) && can(api.create);
+    if (action === "description")
+        return Boolean(api.mass?.description) && can(api.mass.description);
+    if (action === "view")
+        return !api.details || can(api.details);
+    const endpoint = crudRowEndpoint(api, action);
+    return Boolean(endpoint) && can(endpoint);
+}
+/** Whether a mass action can run: its row action is wanted, and its mass endpoint exists and is allowed. */
+export function massActionAllowed(action, api, wanted, can) {
+    if (!wanted.includes(action))
+        return false;
+    const endpoint = api.mass?.[action];
+    return Boolean(endpoint) && can(endpoint);
+}
+/**
+ * Whether a record leaves the list shown after an action. Trash, recover, delete, and moving back to the trash take it
+ * to another list, and unflagging leaves the flagged list. Pinning and unpinning never do: a pinned
+ * record stays in the list it is in. `markOn` is the record's new flag.
+ */
+export function leavesList(action, mode, markOn) {
+    switch (action) {
+        case "trash":
+        case "recover":
+        case "delete":
+        case "trashFromDelete":
+            return true;
+        case "flag":
+            return mode === "flag" && markOn === false;
+        default:
+            return false;
+    }
+}
+/** The message builder's action for a built-in action: "Guest recovered.", "Unpin 3 guests?" */
+export function crudMessageAction(action, markOn) {
+    switch (action) {
+        case "flag":
+            return markOn === false ? "unflag" : "flag";
+        case "pin":
+            return markOn === false ? "unpin" : "pin";
+        case "trashFromDelete":
+            return "trash";
+        case "description":
+            return "update";
+        case "edit":
+        case "view":
+            return "save";
+        default:
+            return action;
+    }
+}
+const DEFAULT_CRUD_SETTINGS = { maxPins: 100 };
+let crudSettings = DEFAULT_CRUD_SETTINGS;
+/**
+ * Changes what every CRUD follows, once, where the app registers its API modules: `configureCrud({ maxPins: 50 })`.
+ * Values left out keep what they had.
+ */
+export function configureCrud(changes) {
+    crudSettings = { ...crudSettings, ...changes };
+    return crudSettings;
+}
+/** The settings every CRUD follows. */
+export function getCrudSettings() {
+    return crudSettings;
+}
+/**
+ * How many more records may be pinned: the limit less the records pinned, never below zero. `pinned` is `undefined`
+ * when nothing counts the pins (no `pins` endpoint), and then there is no limit to keep.
+ */
+export function pinRoom(pinned, max = getCrudSettings().maxPins) {
+    if (pinned === undefined)
+        return Number.POSITIVE_INFINITY;
+    return Math.max(0, max - pinned);
+}
+/** Default time a CRUD keeps a list: 5 minutes. */
+export const CRUD_CACHE_LIFETIME = 5 * 60 * 1000;
+/** Lists kept while a page is open, by key, each for a lifetime. Plain values; nothing is written to storage. */
+export class CrudCache {
+    entries = new Map();
+    lifetime;
+    now;
+    constructor(lifetime = CRUD_CACHE_LIFETIME, now = Date.now) {
+        this.lifetime = lifetime;
+        this.now = now;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (this.now() - entry.at > this.lifetime) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        if (this.lifetime > 0)
+            this.entries.set(key, { value, at: this.now() });
+    }
+    /** Replaces a value, keeping its age, so a changed list does not live longer than the list it came from. */
+    update(key, value) {
+        const entry = this.entries.get(key);
+        if (entry)
+            entry.value = value;
+    }
+    /**
+     * Writes a change through every entry, each keeping its age: this is how a record that was saved or marked reaches
+     * the lists that are not on screen without a request. Returning `null` drops that entry, and its list loads again
+     * the next time it is shown.
+     */
+    map(change) {
+        for (const [key, entry] of [...this.entries]) {
+            const next = change(key, entry.value);
+            if (next === null)
+                this.entries.delete(key);
+            else
+                entry.value = next;
+        }
+    }
+    /** Drops every entry whose key passes the test. */
+    drop(test) {
+        for (const key of [...this.entries.keys()])
+            if (test(key))
+                this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+}
+/** The list a cache entry belongs to: the key itself for a whole list, its first part for one page of one. */
+export function crudCacheMode(key) {
+    const bar = key.indexOf("|");
+    return (bar === -1 ? key : key.slice(0, bar));
+}
+/**
+ * One list kept in the cache, after a change: the records that belong in it are written in, the ones that no longer
+ * belong are taken out, and the entry is returned as it should now be. `null` means the list cannot be worked out
+ * and has to be loaded again.
+ *
+ * `member` is the backend's rule for which list a record belongs in (`CrudBackend.listMembership`). A record it
+ * cannot answer for drops the entry, which is what every list did before this.
+ *
+ * **A whole list** is patched: a record that joined it goes on top, where the table also shows a record just added.
+ * **One page of a list** is not: its order, its last row and its counts are the server's, so as soon as a record
+ * joined it or left it the page is dropped; a record that stayed is written in place, which costs nothing.
+ */
+export function patchCachedList(value, mode, changes, keyOf, member) {
+    const paged = !Array.isArray(value);
+    const rows = paged ? [...value.rows] : [...value];
+    let touched = false;
+    for (const change of changes) {
+        const now = change.gone ? false : member(change.row, mode);
+        if (now === undefined)
+            return null;
+        const at = rows.findIndex(row => keyOf(row) === change.key);
+        const was = change.before ? member(change.before, mode) : at !== -1;
+        if (was === undefined)
+            return null;
+        if (paged) {
+            if (was !== now)
+                return null;
+            if (at !== -1) {
+                rows[at] = change.row;
+                touched = true;
+            }
+            continue;
+        }
+        if (now) {
+            if (at === -1)
+                rows.unshift(change.row);
+            else
+                rows[at] = change.row;
+            touched = true;
+        }
+        else if (at !== -1) {
+            rows.splice(at, 1);
+            touched = true;
+        }
+    }
+    if (!touched)
+        return value;
+    return paged ? { ...value, rows } : rows;
+}