nexus-shared 2.0.0 → 3.1.0

package/dist/Helpers/ExcelBackend.js

@@ -0,0 +1,296 @@
+import { readApiResponse } from "./ApiResponses.js";
+import { ExcelRowKind } from "../Interfaces/ExcelInterfaces.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value) => {
+    if (value === undefined || value === null)
+        return null;
+    const written = String(value).trim();
+    return written.length ? written : null;
+};
+const count = (value, fallback = 0) => {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : fallback;
+};
+/** The actions of a Nexus Excel controller, as the backend names them (`NexusExcelController`). */
+export const EXCEL_ACTIONS = {
+    settings: "Excel/Settings",
+    template: "Excel/Template",
+    verify: "Excel/Verify",
+    import: "Excel/Import",
+    /** The model's own action, which the two controller bases leave to it. */
+    export: "Excel/Export",
+};
+const at = (controller, action) => `${controller}/${action}`;
+/**
+ * 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 function excelEndpoints(controller, options = {}) {
+    const { module, controller: name } = controller;
+    const subject = options.subject;
+    const endpoint = (method, action, extras) => ({ module, path: at(name, action), method, ...(subject && { subject }), ...extras });
+    const [exportMethod, exportAction] = Array.isArray(options.exportAction) ? options.exportAction : ["POST", options.exportAction ?? EXCEL_ACTIONS.export];
+    return {
+        settings: endpoint("GET", EXCEL_ACTIONS.settings, { action: "load" }),
+        template: endpoint("GET", EXCEL_ACTIONS.template, { action: "download" }),
+        verify: endpoint("POST", EXCEL_ACTIONS.verify, { action: "upload", bodyType: "form-data" }),
+        import: endpoint("POST", EXCEL_ACTIONS.import, { action: "import" }),
+        ...(options.exportable === false ? {} : { export: endpoint(exportMethod, exportAction, { action: "export" }) }),
+    };
+}
+export class ExcelBackend {
+}
+/**
+ * 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 class NexusExcelBackend extends ExcelBackend {
+    get uploadField() {
+        return "file";
+    }
+    importRequest(rows, recordStatus) {
+        return recordStatus === undefined ? { rows } : { rows, recordStatus };
+    }
+    /**
+     * 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) {
+        return {
+            ...query.filters,
+            searchKeyword: text(query.search) ?? undefined,
+            sorting: text(query.sort) ?? "creationTime",
+            sortType: query.direction ?? (query.sort ? "asc" : "desc"),
+        };
+    }
+    readSettings(result) {
+        const answer = isRecord(result) ? result : {};
+        return {
+            subject: text(answer.subject) ?? "row",
+            templateFileName: text(answer.templateFileName) ?? undefined,
+            sheetRows: answer.sheetRows === undefined ? undefined : count(answer.sheetRows),
+            maxExportRows: count(answer.maxExportRows, DEFAULT_MAX_EXPORT_ROWS),
+            maxImportRows: count(answer.maxImportRows, DEFAULT_MAX_IMPORT_ROWS),
+            columns: readColumns(answer.columns),
+            inputs: Array.isArray(answer.inputs) ? answer.inputs : [],
+            recordStatuses: Array.isArray(answer.recordStatuses)
+                ? answer.recordStatuses.filter(isRecord).flatMap(status => (typeof status.value === "number" && typeof status.label === "string" ? [{ value: status.value, label: status.label }] : []))
+                : [],
+            defaultRecordStatus: typeof answer.defaultRecordStatus === "number" ? answer.defaultRecordStatus : undefined,
+        };
+    }
+    readVerify(result) {
+        const answer = isRecord(result) ? result : {};
+        const rows = readRows(answer.rows);
+        const kinds = (kind) => rows.filter(row => row.kind === kind).length;
+        const read = count(answer.read, rows.length);
+        const fresh = answer.new === undefined ? kinds(ExcelRowKind.New) : count(answer.new);
+        const invalid = answer.invalid === undefined ? kinds(ExcelRowKind.Invalid) : count(answer.invalid);
+        return {
+            subject: text(answer.subject) ?? "row",
+            read,
+            new: fresh,
+            duplicates: answer.duplicates === undefined ? kinds(ExcelRowKind.Duplicate) : count(answer.duplicates),
+            invalid,
+            isReady: typeof answer.isReady === "boolean" ? answer.isReady : invalid === 0 && fresh > 0,
+            note: text(answer.note) ?? "",
+            columns: readColumns(answer.columns),
+            rows,
+            inputs: Array.isArray(answer.inputs) ? answer.inputs : [],
+        };
+    }
+    readImport(result) {
+        const answer = isRecord(result) ? result : {};
+        return {
+            sent: count(answer.sent),
+            created: count(answer.created),
+            duplicates: count(answer.duplicates),
+            invalid: count(answer.invalid),
+            refused: readRows(answer.refused),
+            note: text(answer.note) ?? "",
+        };
+    }
+    get downloadHeaders() {
+        return NEXUS_DOWNLOAD_HEADERS;
+    }
+}
+/** The most rows one export writes when the backend does not say (`Nexus:Excel:MaxExportRows`). */
+export const DEFAULT_MAX_EXPORT_ROWS = 5000;
+/** The most rows one import takes when the backend does not say (`Nexus:Excel:MaxImportRows`). */
+export 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 const NEXUS_DOWNLOAD_HEADERS = {
+    rows: "X-Nexus-Export-Rows",
+    skipped: "X-Nexus-Export-Skipped",
+    limit: "X-Nexus-Export-Limit",
+    note: "X-Nexus-Export-Note",
+};
+function readColumns(value) {
+    if (!Array.isArray(value))
+        return [];
+    const columns = [];
+    for (const item of value) {
+        if (!isRecord(item))
+            continue;
+        const field = text(item.field);
+        if (!field)
+            continue;
+        columns.push({
+            field,
+            header: text(item.header) ?? field,
+            dataType: count(item.dataType),
+            isRequired: item.isRequired === true,
+            isReadOnly: item.isReadOnly === true,
+            isReference: item.isReference === true,
+            list: text(item.list),
+            minLength: count(item.minLength),
+            maxLength: count(item.maxLength),
+            minimum: item.minimum === undefined || item.minimum === null ? null : count(item.minimum),
+            maximum: item.maximum === undefined || item.maximum === null ? null : count(item.maximum),
+            note: text(item.note),
+        });
+    }
+    return columns;
+}
+/** A dictionary of texts: every value as text, so nothing read out of an answer can be sent back as a number or an id. */
+function readValues(value) {
+    const values = {};
+    if (!isRecord(value))
+        return values;
+    for (const [key, item] of Object.entries(value))
+        values[key] = text(item);
+    return values;
+}
+function readProblems(value) {
+    if (!Array.isArray(value))
+        return [];
+    const problems = [];
+    for (const item of value) {
+        if (!isRecord(item))
+            continue;
+        problems.push({
+            row: count(item.row),
+            column: count(item.column),
+            cell: text(item.cell) ?? "",
+            header: text(item.header) ?? "",
+            field: text(item.field) ?? "",
+            message: text(item.message) ?? "",
+            messageCode: text(item.messageCode) ?? undefined,
+            errorCode: item.errorCode === undefined ? undefined : count(item.errorCode),
+        });
+    }
+    return problems;
+}
+function readRows(value) {
+    if (!Array.isArray(value))
+        return [];
+    const rows = [];
+    for (const [index, item] of value.entries()) {
+        if (!isRecord(item))
+            continue;
+        const problems = readProblems(item.problems);
+        const kind = item.kind === undefined ? (problems.length ? ExcelRowKind.Invalid : ExcelRowKind.New) : count(item.kind);
+        rows.push({
+            number: count(item.number, index + 1),
+            kind,
+            values: readValues(item.values),
+            labels: readValues(item.labels),
+            problems,
+            duplicate: text(item.duplicate),
+        });
+    }
+    return rows;
+}
+/**
+ * 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 function readExcelResponse(body, status) {
+    if (isRecord(body) && body.isSuccess !== true) {
+        const list = Array.isArray(body.errorMessages) ? body.errorMessages : isRecord(body.errorMessages) ? [body.errorMessages] : [];
+        const problems = list.filter(isRecord);
+        if (problems.length) {
+            const first = problems[0];
+            const errors = {};
+            for (const problem of problems) {
+                const input = text(problem.inputName);
+                const message = text(problem.message);
+                if (input && message && !(input in errors))
+                    errors[input] = message;
+            }
+            return {
+                ok: false,
+                status: status ?? (typeof body.code === "number" ? body.code : undefined),
+                message: text(first.message) ?? undefined,
+                messageCode: text(first.messageCode) ?? undefined,
+                errorCode: first.errorCode === undefined ? undefined : count(first.errorCode),
+                ...(Object.keys(errors).length ? { errors } : {}),
+                // An import that wrote nothing still says, row by row, what it refused and why (XLS_X044): keep that report.
+                ...(isRecord(body.result) ? { result: body.result } : {}),
+            };
+        }
+    }
+    return readApiResponse(body, status);
+}
+let current = null;
+/** Registers the app's spreadsheet conventions, once, beside its API modules. */
+export function defineExcelBackend(backend) {
+    current = backend;
+    return backend;
+}
+/** The registered spreadsheet conventions, or the Nexus ones. */
+export function getExcelBackend() {
+    return (current ??= new NexusExcelBackend());
+}
+/** The file name out of a `Content-Disposition`, `filename*` first (it carries the encoding) and `filename` after. */
+export function readFileName(disposition) {
+    if (!disposition)
+        return undefined;
+    const encoded = /filename\*\s*=\s*([^;]+)/i.exec(disposition)?.[1]?.trim();
+    if (encoded) {
+        const parts = encoded.split("'");
+        const value = (parts.length >= 3 ? parts.slice(2).join("'") : encoded).trim();
+        try {
+            const name = decodeURIComponent(value.replace(/^"|"$/g, ""));
+            if (name)
+                return name;
+        }
+        catch {
+            // A name that is not valid percent-encoding: fall through to the plain one.
+        }
+    }
+    const plain = /filename\s*=\s*("([^"]*)"|[^;]+)/i.exec(disposition);
+    const name = (plain?.[2] ?? plain?.[1] ?? "").trim();
+    return name.length ? name : undefined;
+}
+/** What a download answered, as its own headers tell it. */
+export function readDownloadHeaders(headers, blob, fallbackName) {
+    const names = getExcelBackend().downloadHeaders;
+    const number = (name) => {
+        const value = headers.get(name);
+        if (value === null)
+            return undefined;
+        const read = Number(value);
+        return Number.isFinite(read) ? read : undefined;
+    };
+    return {
+        blob,
+        fileName: readFileName(headers.get("Content-Disposition")) ?? fallbackName,
+        rows: number(names.rows),
+        skipped: number(names.skipped),
+        limit: number(names.limit),
+        note: text(headers.get(names.note)) ?? undefined,
+    };
+}

package/dist/Helpers/ExcelHelpers.d.ts

@@ -0,0 +1,126 @@
+import type { InputParams } from "../Interfaces/FormInterfaces.ts";
+import type { ExcelCellProblem, ExcelColumnInfo, ExcelDownload, ExcelReviewRow, ExcelSheetRow } from "../Interfaces/ExcelInterfaces.ts";
+/** What a spreadsheet file is called in a file picker. */
+export declare const EXCEL_FILE_ACCEPT = ".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+/** The field of an editor row that holds the sheet row it came from. Not a column, so no input is drawn for it. */
+export declare const EXCEL_ROW_NUMBER = "__excelRow";
+/** The field of an editor row that holds each reference column's key, which the person never sees or types. */
+export declare const EXCEL_ROW_KEYS = "__excelKeys";
+/** The field of an editor row that holds what the verify answered for it, so an edit can be told from an untouched row. */
+export declare const EXCEL_ROW_SENT = "__excelSent";
+/**
+ * One row of a review editor: a value per column, plus the three fields the editor carries for itself. A row added in
+ * the browser - by Add, Insert or Duplicate, or every row of a bulk insert - has none of the three, or only some.
+ */
+export interface ExcelEditorRow {
+    [EXCEL_ROW_NUMBER]?: number;
+    [EXCEL_ROW_KEYS]?: Record<string, string | null>;
+    [EXCEL_ROW_SENT]?: Record<string, string | null>;
+    [field: string]: unknown;
+}
+declare const DEFAULT_TEXT: {
+    readonly template: "Download template";
+    readonly templateHint: "The file to fill in: every list is a dropdown, and the ids beside a choice fill themselves.";
+    readonly choose: "Choose file";
+    readonly change: "Choose another file";
+    readonly checking: "Checking";
+    readonly nothingPicked: "No file picked yet.";
+    readonly verifyFailed: "The file could not be read.";
+    readonly newRows: "New rows";
+    readonly duplicates: "Already there";
+    readonly duplicateHint: "Already records: these are skipped, and nothing here is updated.";
+    readonly failedHead: "Not written";
+    readonly skippedHead: "Skipped: already there";
+    readonly importAgain: "To import another file, start over.";
+    readonly addAgain: "To add more, start over.";
+    readonly bulkUnavailable: "The sheet's columns could not be read, so there is nothing to type the rows into.";
+    readonly discardTitle: "Discard what you typed?";
+    readonly discardLabel: "Discard";
+    readonly keepEditing: "Keep editing";
+    readonly toFix: "What needs fixing";
+    readonly whyDuplicate: "Why these are already there";
+    readonly referenceLocked: "Picked in the spreadsheet: this list belongs to the server.";
+    readonly generated: "The file fills this in.";
+    readonly importLabel: "Import";
+    readonly importNothing: "There is no row to import.";
+    readonly importedNone: "Nothing was written.";
+    readonly refused: "Not written";
+    readonly exportWarning: "Export is cut short";
+    readonly close: "Close";
+    readonly startOver: "Start over";
+};
+export type ExcelTextKey = keyof typeof DEFAULT_TEXT;
+/** Rewords or translates the spreadsheet side's own texts. Names only what changes. */
+export declare function configureExcelText(changes: Partial<Record<ExcelTextKey, string>>): void;
+/** One of the spreadsheet side's texts. */
+export declare function excelText(key: ExcelTextKey): string;
+/**
+ * One column of a sheet as an input of the review editors. The rules are the ones the sheet told the person about and
+ * no others, so a fix made here is checked the way the file was.
+ *
+ * Three columns are read-only on purpose:
+ * - a **reference**, because its list is the backend's and is picked in the spreadsheet; the cell shows the words the
+ *   person picked and the key travels back untouched (a key read out of an answer is never typed, and never an id);
+ * - a column the **file** fills;
+ * - and a **date and time** is a text box rather than a picker, because the sheet's moment is a zone-less wall clock
+ *   while the picker's value is a UTC moment: a picker here would shift every value by the person's own offset.
+ */
+export declare function excelColumnInput(column: ExcelColumnInfo): InputParams;
+/** Every column of a sheet as the inputs of one editor row, in the order they read. */
+export declare function excelColumnInputs(columns: readonly ExcelColumnInfo[]): InputParams[];
+/** Whether the person edits this column's cell at all, or only reads it. */
+export declare function isExcelColumnEditable(column: ExcelColumnInfo): boolean;
+/**
+ * A verify's rows as the editors' rows: a value per column, the sheet's row number, and - held beside them, never
+ * drawn - each reference column's key and the values the verify answered with.
+ *
+ * A reference cell shows the **words** the person picked, because its key is not something anybody reads or types.
+ */
+export declare function excelEditorRows(rows: readonly ExcelReviewRow[], columns: readonly ExcelColumnInfo[]): ExcelEditorRow[];
+/** The sheet row a row came from, or 0 for a row added in the browser. */
+export declare function excelRowNumber(row: ExcelEditorRow): number;
+/**
+ * The editors' rows as rows to send: every value as text, every reference as the key it came with, and the sheet's own
+ * row number kept so a problem can still name where it is.
+ *
+ * A cell the person did not touch goes back **exactly** as it came, which is what makes the round trip faithful: the
+ * backend reads its own text again, not a number an input rewrote on the way through.
+ *
+ * A row added in the browser has no sheet row, so it is numbered after the last one the sheet had: no two rows share a
+ * number, and a problem still names the row it is about. `after` is that last row - the file's, rows already there and
+ * rows taken out of the review included, which are not among the rows sent. A bulk insert, with no sheet at all,
+ * numbers its rows 1, 2, 3.
+ */
+export declare function excelSheetRows(rows: readonly ExcelEditorRow[], columns: readonly ExcelColumnInfo[], after?: number): ExcelSheetRow[];
+/** Whether the person changed anything in a row since the verify answered it. */
+export declare function isExcelRowEdited(row: ExcelEditorRow, columns: readonly ExcelColumnInfo[]): boolean;
+/** Whether a row has anything in a cell the person types in. A row added and left empty has not, and is not sent. */
+export declare function hasExcelValues(row: ExcelEditorRow, columns: readonly ExcelColumnInfo[]): boolean;
+/**
+ * Whether a row holds something only this screen has, which closing it would lose: a sheet's row the person edited, or
+ * a row added here with anything in it.
+ */
+export declare function isExcelRowTyped(row: ExcelEditorRow, columns: readonly ExcelColumnInfo[]): boolean;
+/**
+ * Where a problem is, as the person reads it: the cell, a middle dot, and the column's heading ("B7 - City name"). Rows
+ * typed in the browser have no sheet, so `byRow` names the row instead ("Row 3 - City name").
+ */
+export declare function excelProblemPlace(problem: ExcelCellProblem, byRow?: boolean): string;
+/** Every problem of these rows, in the order the rows read. */
+export declare function excelProblems(rows: readonly ExcelReviewRow[]): ExcelCellProblem[];
+/** The rows of one kind. */
+export declare function excelRowsOfKind(rows: readonly ExcelReviewRow[], ...kinds: readonly number[]): ExcelReviewRow[];
+/** The rows an import would try to write: the new ones, and the ones still waiting on a fix. */
+export declare function excelWritableRows(rows: readonly ExcelReviewRow[]): ExcelReviewRow[];
+/** More than one of the subject: "cities", "boxes", "rows". An English ending, which a text change can replace. */
+export declare function excelPlural(subject: string, plural?: string): string;
+/** A count said in the subject's own words: "1 city", "12 cities". */
+export declare function excelCount(rows: number, subject: string, plural?: string): string;
+/**
+ * What to tell the person before an export that will be cut short, as the owner asked: what is on screen, what will be
+ * written, and that filtering is how they get the rest.
+ */
+export declare function excelExportWarning(rows: number, limit: number, subject: string): string;
+/** Hands the person a file to save, under the name the answer gave it. */
+export declare function saveExcelFile(download: ExcelDownload): void;
+export {};