nexus-shared 2.0.0 → 3.0.0

package/dist/Helpers/CrudBackend.js

@@ -24,15 +24,71 @@ export class CrudBackend {
         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 status of a flagged record (`ERecordStatus.Flagged`). */
-export const NEXUS_FLAGGED_STATUS = 15;
-/** The Nexus record status of an active record (`ERecordStatus.Active`). */
+/*
+ * 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` 15, a pinned one `isPinned`.
+ * (`{ description, accountIds }` for descriptions); a flagged record has `recordStatus` 25, a pinned one `isPinned`.
  */
 export class NexusCrudBackend extends CrudBackend {
     pageRequest(query, sortKey) {
@@ -93,6 +149,45 @@ export class NexusCrudBackend extends CrudBackend {
         }
         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;

package/dist/Helpers/CrudHelpers.d.ts

@@ -1,7 +1,7 @@
 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 { TablePaging } from "../Interfaces/TableInterfaces.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. */
@@ -30,12 +30,12 @@ export declare function actionAllowed(action: CrudActionName, api: CrudEndpoints
 /** 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. Archive, trash, restore, 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
+ * 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 archived.", "Unpin 3 guests?" */
+/** 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 {
@@ -69,8 +69,43 @@ export declare class CrudCache<T = unknown> {
     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

@@ -1,17 +1,17 @@
 /*
  * 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.
+ * 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", "archive", "trash", "deleted"];
-const ACTIVE_ROW_ACTIONS = ["view", "edit", "flag", "pin", "archive", "trash"];
-const ACTIVE_MASS_ACTIONS = ["flag", "pin", "archive", "description", "trash"];
+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,
-    archive: ["view", "restore", "trash"],
     trash: ["view", "recover", "delete"],
     deleted: ["view", "trashFromDelete"],
 };
@@ -19,7 +19,6 @@ export const CRUD_ROW_ACTIONS = {
 export const CRUD_MASS_ACTIONS = {
     normal: ACTIVE_MASS_ACTIONS,
     flag: ACTIVE_MASS_ACTIONS,
-    archive: ["restore", "description", "trash"],
     trash: ["recover", "description", "delete"],
     deleted: ["trashFromDelete"],
 };
@@ -96,14 +95,12 @@ export function massActionAllowed(action, api, wanted, can) {
     return Boolean(endpoint) && can(endpoint);
 }
 /**
- * Whether a record leaves the list shown after an action. Archive, trash, restore, 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
+ * 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 "archive":
-        case "restore":
         case "trash":
         case "recover":
         case "delete":
@@ -115,7 +112,7 @@ export function leavesList(action, mode, markOn) {
             return false;
     }
 }
-/** The message builder's action for a built-in action: "Guest archived.", "Unpin 3 guests?" */
+/** The message builder's action for a built-in action: "Guest recovered.", "Unpin 3 guests?" */
 export function crudMessageAction(action, markOn) {
     switch (action) {
         case "flag":
@@ -187,6 +184,20 @@ export class CrudCache {
         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()])
@@ -200,3 +211,57 @@ export class CrudCache {
         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;
+}

package/dist/Helpers/ExcelBackend.d.ts

@@ -0,0 +1,106 @@
+import type { ApiModuleValue, ApiResult, HttpMethod } from "../Interfaces/ApiInterfaces.ts";
+import type { ExcelDownload, ExcelEndpoints, ExcelExportQuery, ExcelImportAnswer, ExcelSettings, ExcelSheetRow, ExcelVerifyAnswer } from "../Interfaces/ExcelInterfaces.ts";
+/** The actions of a Nexus Excel controller, as the backend names them (`NexusExcelController`). */
+export declare const EXCEL_ACTIONS: {
+    readonly settings: "Excel/Settings";
+    readonly template: "Excel/Template";
+    readonly verify: "Excel/Verify";
+    readonly import: "Excel/Import";
+    /** The model's own action, which the two controller bases leave to it. */
+    readonly export: "Excel/Export";
+};
+/** Which controller a model's spreadsheets sit on. An `apiController(...)` fits as it is. */
+export interface ExcelController<TModule extends ApiModuleValue = ApiModuleValue> {
+    module: TModule;
+    /** The controller's name: "City". */
+    controller: string;
+}
+/** Changes to the endpoints a Nexus controller gets. */
+export interface ExcelEndpointOptions {
+    /** What one row is, for the messages: "city". */
+    subject?: string;
+    /** No export is offered. Default: `Excel/Export` as a POST. */
+    exportable?: false;
+    /** The export action, when the controller named it something else: `"Export"`, or `["GET", "Download"]`. */
+    exportAction?: string | [HttpMethod, string];
+}
+/**
+ * The spreadsheet endpoints of a Nexus controller, named as the backend names them: `Excel/Settings`,
+ * `Excel/Template`, `Excel/Verify`, `Excel/Import`, and the model's own `Excel/Export`.
+ *
+ * @example
+ * export const CITIES = MODULES.controller(NexusModule.Configuration, "City", "city");
+ * export const CITY_SHEET = excelEndpoints(CITIES, { subject: "city" });
+ */
+export declare function excelEndpoints<TModule extends ApiModuleValue>(controller: ExcelController<TModule>, options?: ExcelEndpointOptions): ExcelEndpoints<TModule>;
+/** What a download's own headers are called, so a backend that names them differently still reads. */
+export interface ExcelDownloadHeaders {
+    rows: string;
+    skipped: string;
+    limit: string;
+    note: string;
+}
+export declare abstract class ExcelBackend {
+    /** The form field an upload is sent under. */
+    abstract get uploadField(): string;
+    /** What an import sends: the rows the verify answered with, as the person left them. */
+    abstract importRequest(rows: readonly ExcelSheetRow[]): unknown;
+    /** What an export sends: the search, the sort and the filters the person has on screen. */
+    abstract exportRequest(query: ExcelExportQuery): unknown;
+    /** Reads what the settings endpoint answered. */
+    abstract readSettings(result: unknown): ExcelSettings;
+    /** Reads what a verify answered. */
+    abstract readVerify(result: unknown): ExcelVerifyAnswer;
+    /** Reads what an import answered. */
+    abstract readImport(result: unknown): ExcelImportAnswer;
+    /**
+     * What a download says about itself in its headers. Every one of them has to be named in the backend's CORS policy:
+     * a browser can read only the headers it is told it may, `Content-Disposition` included, so a frontend on another
+     * origin otherwise receives a file it cannot even name.
+     */
+    abstract get downloadHeaders(): ExcelDownloadHeaders;
+}
+/**
+ * The Nexus backend. The four calls sit under one controller; an import sends `{ rows }`; an export sends the list
+ * request a Nexus pagination takes, without its paging, because an export is not a page; a download says what it came
+ * to in `X-Nexus-Export-*` headers.
+ */
+export declare class NexusExcelBackend extends ExcelBackend {
+    get uploadField(): string;
+    importRequest(rows: readonly ExcelSheetRow[]): unknown;
+    /**
+     * The same request a Nexus listing takes, minus `skipCount` and `maxCount`: an export writes every row the search
+     * leaves, up to the backend's own limit, not the page the person happens to be on. With nothing sorted it follows
+     * the list's own order, newest first.
+     */
+    exportRequest(query: ExcelExportQuery): unknown;
+    readSettings(result: unknown): ExcelSettings;
+    readVerify(result: unknown): ExcelVerifyAnswer;
+    readImport(result: unknown): ExcelImportAnswer;
+    get downloadHeaders(): ExcelDownloadHeaders;
+}
+/** The most rows one export writes when the backend does not say (`Nexus:Excel:MaxExportRows`). */
+export declare const DEFAULT_MAX_EXPORT_ROWS = 5000;
+/** The most rows one import takes when the backend does not say (`Nexus:Excel:MaxImportRows`). */
+export declare const DEFAULT_MAX_IMPORT_ROWS = 2000;
+/** What a Nexus download says about itself (`Excels/ExcelHeaders.cs`), all of them exposed by the CORS policy. */
+export declare const NEXUS_DOWNLOAD_HEADERS: ExcelDownloadHeaders;
+/**
+ * Reads an answer whose problems are in `errorMessages`, which is how the backend answers a refusal now: nothing at the
+ * top level, and one entry per wrong field (`{ message, messageCode, errorCode, inputName }`) so every one of them is
+ * told at once. The first entry words the answer, and each entry that names an input lands on that input.
+ *
+ * Anything else - a success, a backend of another shape, problem details, a proxy answering while the service is down -
+ * goes to `readApiResponse`, which is also the default for every call that does not name a reader. It is used here
+ * because a spreadsheet's refusals are the whole point of the review: "no row could be written" has to reach the person
+ * in the backend's own words, not as a generic sentence.
+ */
+export declare function readExcelResponse(body: unknown, status?: number): ApiResult;
+/** Registers the app's spreadsheet conventions, once, beside its API modules. */
+export declare function defineExcelBackend<T extends ExcelBackend>(backend: T): T;
+/** The registered spreadsheet conventions, or the Nexus ones. */
+export declare function getExcelBackend(): ExcelBackend;
+/** The file name out of a `Content-Disposition`, `filename*` first (it carries the encoding) and `filename` after. */
+export declare function readFileName(disposition: string | null | undefined): string | undefined;
+/** What a download answered, as its own headers tell it. */
+export declare function readDownloadHeaders(headers: Headers, blob: Blob, fallbackName: string): ExcelDownload;