nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/ApiResponses.js

@@ -0,0 +1,159 @@
+import { buildMessage, describeResult } from "./MessageBuilder.js";
+/*
+ * Reading a server's answer as success or failure, the same way for every call: Nexus API responses, ASP.NET Core problem
+ * details, or any JSON by its status. Pure, so it works in tests, in the browser, and on a server.
+ */
+/** Shown when nothing reached the server (the default wording; `messages.reason({ network: true })` follows `configureMessages`). */
+export const NETWORK_ERROR_MESSAGE = buildMessage("reason", { network: true });
+/** A message for a failed request that came without one of its own, by HTTP status and what the request did. Default action `save`. */
+export function apiStatusMessage(status, action = "save") {
+    return buildMessage("reason", { action, status });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/** Messages by field from `{ errors: { Email: ["…"], "Addresses[0].City": "…" } }`. */
+function readErrorMap(errors) {
+    if (!isRecord(errors))
+        return undefined;
+    const result = {};
+    for (const [key, value] of Object.entries(errors)) {
+        const message = Array.isArray(value) ? value.map(text).filter(Boolean).join(" ") : text(value);
+        if (message)
+            result[key] = message;
+    }
+    return Object.keys(result).length ? result : undefined;
+}
+/**
+ * Reads a server's answer as success or failure:
+ * - Nexus API responses, `{ isSuccess, message, messageCode, errorCode, inputName, result }`: `inputName` names the
+ *   inputs the message is about, several joined with "|".
+ * - ASP.NET Core problem details and validation errors, `{ title, detail, errors: { Email: ["…"] } }`.
+ * - Anything else by its HTTP status; the body is the result.
+ *
+ * A failure without a message of its own gets one by status, worded for what the call did (`context`, default: a save).
+ */
+export function readApiResponse(body, status, context) {
+    const fallback = () => buildMessage("reason", { action: "save", ...context, status });
+    const statusOk = status === undefined || (status >= 200 && status < 300);
+    if (isRecord(body)) {
+        if (typeof body.isSuccess === "boolean") {
+            const ok = body.isSuccess && statusOk;
+            const message = text(body.message);
+            let errors;
+            const names = text(body.inputName);
+            if (!ok && names && message) {
+                errors = {};
+                for (const name of names.split("|"))
+                    if (name.trim())
+                        errors[name.trim()] = message;
+            }
+            // The backend's defaults ("SUCCESS", "GENERIC_ERROR", error 0) say nothing, so they are left out.
+            const code = text(body.messageCode);
+            const messageCode = code && code !== (ok ? "SUCCESS" : "GENERIC_ERROR") ? code : undefined;
+            const errorCode = typeof body.errorCode === "number" && body.errorCode !== 0 ? body.errorCode : undefined;
+            return {
+                ok,
+                status,
+                result: body.result,
+                message: message ?? (ok ? undefined : fallback()),
+                errors,
+                ...(messageCode ? { messageCode } : {}),
+                ...(errorCode !== undefined ? { errorCode } : {}),
+            };
+        }
+        const errors = readErrorMap(body.errors);
+        if (errors || !statusOk) {
+            const message = text(body.message) ?? (errors ? undefined : (text(body.detail) ?? text(body.title)));
+            return { ok: false, status, result: body, message: message ?? (errors ? undefined : fallback()), errors };
+        }
+        return { ok: true, status, result: body, message: text(body.message) };
+    }
+    if (!statusOk) {
+        // A short text answer is the message; an HTML error page is not.
+        const plain = text(body);
+        const message = plain && plain.length <= 300 && !plain.startsWith("<") ? plain : fallback();
+        return { ok: false, status, message };
+    }
+    return { ok: true, status, result: body === "" ? undefined : body };
+}
+/** Reads a `fetch` response: its JSON (or text) through `read`. */
+export async function readFetchResponse(response, read = readApiResponse) {
+    const type = response.headers.get("content-type") ?? "";
+    let body = null;
+    try {
+        body = type.includes("json") ? await response.json() : await response.text();
+    }
+    catch {
+        body = null;
+    }
+    return read(body, response.status);
+}
+/** Whether an error is a request stopped on purpose (the form closed), which shows nothing. */
+export function isAbortError(error) {
+    return error?.name === "AbortError";
+}
+/** A thrown error as a message: its own, or the network message for a failed `fetch`. */
+export function errorMessage(error, fallback = "Could not save the changes.") {
+    if (error instanceof TypeError)
+        return buildMessage("reason", { network: true });
+    return text(error?.message) ?? (typeof error === "string" && error ? error : fallback);
+}
+/** Values as form fields: lists of plain values repeat their name, objects and lists of objects go as JSON text. */
+export function toFormData(values) {
+    if (typeof FormData !== "undefined" && values instanceof FormData)
+        return values;
+    const data = new FormData();
+    if (!isRecord(values))
+        return data;
+    for (const [key, value] of Object.entries(values)) {
+        if (value === undefined)
+            continue;
+        if (value instanceof Blob)
+            data.append(key, value);
+        else if (Array.isArray(value) && value.every(item => item === null || typeof item !== "object" || item instanceof Blob))
+            for (const item of value)
+                data.append(key, item instanceof Blob ? item : item === null ? "" : String(item));
+        else if (value !== null && typeof value === "object")
+            data.append(key, JSON.stringify(value));
+        else
+            data.append(key, value === null ? "" : String(value));
+    }
+    return data;
+}
+const RESULT_KEYS = ["result", "message", "errors", "status", "network", "timeout", "aborted", "messageCode", "errorCode"];
+/** Whether a value is already a read answer (`{ ok, … }`), not a server's body. */
+export function isApiResult(value) {
+    if (!isRecord(value) || typeof value.ok !== "boolean" || "isSuccess" in value)
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 || keys.some(key => RESULT_KEYS.includes(key));
+}
+/** A failed answer as an error, for code that throws: a server component's error boundary, a form's `loadValue`. */
+export class ApiError extends Error {
+    response;
+    constructor(response) {
+        super(describeResult(response)?.message ?? response.message ?? "The request failed.");
+        this.name = response.aborted ? "AbortError" : "ApiError";
+        this.response = response;
+    }
+    get status() {
+        return this.response.status;
+    }
+}
+/**
+ * What the server sent back, or an `ApiError` thrown for a failure (an `AbortError` for an aborted call, which forms and
+ * loaders ignore).
+ *
+ * @example
+ * const rooms = unwrapApiResult(await serverApi.get<Room[]>(ROOMS.listing));
+ * <ApiForm loadValue={signal => api.get(ROOMS.details, { params: { id }, signal }).then(unwrapApiResult)} … />
+ */
+export function unwrapApiResult(response) {
+    if (!response.ok)
+        throw new ApiError(response);
+    return response.result;
+}

package/dist/Helpers/ApiRoutes.d.ts

@@ -0,0 +1,150 @@
+import type { ApiEndpoint, ApiModuleValue, ApiQuery, HttpMethod } from "../Interfaces/ApiInterfaces.ts";
+import type { CrudMode } from "../Interfaces/CrudInterfaces.ts";
+/**
+ * The standard actions of a Nexus controller, as the backend names them. `apiController` builds its endpoints from
+ * these; use them for an endpoint of your own too: `apiEndpoint.get(module, "Room/" + API_ACTIONS.activeListing)`.
+ */
+export declare const API_ACTIONS: {
+    readonly details: "Detail";
+    /** Every active record: the `normal` list. */
+    readonly listing: "NormalListing";
+    readonly activeListing: "ActiveListing";
+    readonly findListing: "FindListing";
+    /** One page of the `normal` list. */
+    readonly pagination: "NormalPagination";
+    /** Every record of each list a CRUD shows. */
+    readonly listings: {
+        readonly normal: "NormalListing";
+        readonly flag: "FlagListing";
+        readonly archive: "ArchiveListing";
+        readonly trash: "TrashListing";
+        readonly deleted: "DeleteListing";
+    };
+    /** One page of each list a CRUD shows. */
+    readonly paginations: {
+        readonly normal: "NormalPagination";
+        readonly flag: "FlagPagination";
+        readonly archive: "ArchivePagination";
+        readonly trash: "TrashPagination";
+        readonly deleted: "DeletePagination";
+    };
+    /** The records the user pinned, which a CRUD shows above its list. */
+    readonly pinListing: "PinListing";
+    readonly create: "Create";
+    readonly update: "Update";
+    readonly delete: "Delete";
+    readonly trash: "Trash";
+    readonly trashFromDelete: "TrashFromDelete";
+    readonly archive: "Archive";
+    readonly recover: "Recover";
+    readonly restore: "Restore";
+    readonly flag: "Flag";
+    readonly pin: "Pin";
+    readonly audit: "AuditListing";
+    readonly accessActions: "AccessActions";
+    readonly massDescription: "MassDescription";
+    readonly massArchive: "MassArchive";
+    readonly massTrash: "MassTrash";
+    readonly massFlag: "MassFlag";
+    readonly massPin: "MassPin";
+    readonly massDelete: "MassDelete";
+    readonly massRecover: "MassRecover";
+    readonly massRestore: "MassRestore";
+    readonly massTrashFromDelete: "MassTrashFromDelete";
+};
+/** An endpoint's optional parts: `bodyType`, `query`, `action`, `subject`. */
+export type ApiEndpointExtras = Partial<Omit<ApiEndpoint, "module" | "path" | "method">>;
+type EndpointExtras = ApiEndpointExtras;
+/**
+ * Builds an endpoint: `apiEndpoint.get(NexusModule.Message, "EmailProvider/ActiveListing")`. The path is under the
+ * module's root; `{name}` in it is filled from the call's `params`, then its body.
+ */
+export declare const apiEndpoint: {
+    get: <TModule extends ApiModuleValue>(module: TModule, path: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
+    post: <TModule extends ApiModuleValue>(module: TModule, path: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
+    put: <TModule extends ApiModuleValue>(module: TModule, path: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
+    patch: <TModule extends ApiModuleValue>(module: TModule, path: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
+    delete: <TModule extends ApiModuleValue>(module: TModule, path: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
+};
+/**
+ * The endpoints of a Nexus controller, named as the backend names them. `subject` is what the controller keeps, for
+ * messages ("room" → "Room saved.", "3 rooms deleted."); a call can name the record instead (`subject: "Room 204"`).
+ *
+ * @example
+ * export const ROOMS = apiController(NexusModule.Reservation, "Room", "room");
+ * api.get(ROOMS.details, { params: { id: 5 } });      // GET  /api/app/reservation/Room/Detail/5
+ * api.put(ROOMS.update, values);                      // PUT  /api/app/reservation/Room/Update   → "Room saved."
+ * api.delete(ROOMS.delete, { params: { id: 5 } });    // DELETE .../Room/Delete/5               → "Room deleted."
+ */
+export declare function apiController<TModule extends ApiModuleValue>(module: TModule, controller: string, subject?: string): {
+    module: TModule;
+    controller: string;
+    /** Every active row: GET `Room/NormalListing`. */
+    listing: ApiEndpoint<TModule>;
+    /** Active rows for dropdowns: GET `Room/ActiveListing`. */
+    activeListing: ApiEndpoint<TModule>;
+    /** Rows by id, for saved values a list no longer shows: POST `Room/FindListing` with the ids. */
+    findListing: ApiEndpoint<TModule>;
+    /** One page of active rows: POST `Room/NormalPagination` with `{ searchKeyword, skipCount, maxCount, sorting, sortType }`. */
+    pagination: ApiEndpoint<TModule>;
+    /** Every row of each list, for a CRUD that pages in the browser: GET `Room/NormalListing`, `Room/TrashListing`, … */
+    lists: Record<CrudMode, ApiEndpoint<TModule>>;
+    /** One page of each list, for a CRUD that pages on the server: POST `Room/NormalPagination`, `Room/TrashPagination`, … */
+    pages: Record<CrudMode, ApiEndpoint<TModule>>;
+    /** The records the user pinned, shown above the list: GET `Room/PinListing`. */
+    pins: ApiEndpoint<TModule>;
+    /** One record: GET `Room/Detail/{id}`. */
+    details: ApiEndpoint<TModule>;
+    create: ApiEndpoint<TModule>;
+    update: ApiEndpoint<TModule>;
+    delete: ApiEndpoint<TModule>;
+    trash: ApiEndpoint<TModule>;
+    trashFromDelete: ApiEndpoint<TModule>;
+    archive: ApiEndpoint<TModule>;
+    restore: ApiEndpoint<TModule>;
+    recover: ApiEndpoint<TModule>;
+    flag: ApiEndpoint<TModule>;
+    pin: ApiEndpoint<TModule>;
+    /** A record's history: GET `Room/AuditListing/{ownerId}/{skipCount}`. */
+    audit: ApiEndpoint<TModule>;
+    /** What the user may do here: GET `Room/AccessActions`. */
+    accessActions: ApiEndpoint<TModule>;
+    /** Actions on many rows at once: POST `Room/MassDelete` and the rest, with the ids. */
+    mass: {
+        description: ApiEndpoint<TModule>;
+        archive: ApiEndpoint<TModule>;
+        trash: ApiEndpoint<TModule>;
+        trashFromDelete: ApiEndpoint<TModule>;
+        flag: ApiEndpoint<TModule>;
+        pin: ApiEndpoint<TModule>;
+        delete: ApiEndpoint<TModule>;
+        recover: ApiEndpoint<TModule>;
+        restore: ApiEndpoint<TModule>;
+    };
+    /** Any other action of the controller: `ROOMS.action("PUT", "Block/{id}", { action: "update" })`. */
+    action: (method: HttpMethod, action: string, extras?: EndpointExtras) => ApiEndpoint<TModule>;
+};
+export type ApiControllerEndpoints = ReturnType<typeof apiController>;
+/** Whether a value is an endpoint (not a URL or a request of another shape). */
+export declare function isApiEndpoint(value: unknown): value is ApiEndpoint;
+/** Thrown when a path names a value the call did not give, so a request never goes to ".../Detail/undefined". */
+export declare class ApiPathError extends Error {
+    readonly path: string;
+    readonly missing: string;
+    constructor(path: string, missing: string);
+}
+/**
+ * Fills `{name}` in a path from `params`, then from the body's fields (names without case), and encodes each value.
+ * Leading and trailing slashes go.
+ */
+export declare function fillApiPath(path: string, params?: Record<string, unknown> | null, body?: unknown): string;
+/** Adds query values to a URL: lists repeat their name, dates go as ISO text, `null` and `undefined` are left out. */
+export declare function appendQuery(url: string, ...queries: (ApiQuery | null | undefined)[]): string;
+/** Joins a root URL and a path with one slash between them. */
+export declare function joinUrl(root: string, path: string): string;
+export interface ApiUrlParts {
+    params?: Record<string, unknown> | null;
+    query?: ApiQuery;
+    body?: unknown;
+}
+export {};

package/dist/Helpers/ApiRoutes.js

@@ -0,0 +1,191 @@
+/*
+ * Endpoints and their URLs. An endpoint is a path under a module's root; which roots exist, and where, is the app's
+ * `ApiModules` class (ApiModules.ts). Define endpoints once, with `apiEndpoint` or `apiController` (or the same
+ * methods of the app's modules), and call them from anywhere.
+ */
+/**
+ * The standard actions of a Nexus controller, as the backend names them. `apiController` builds its endpoints from
+ * these; use them for an endpoint of your own too: `apiEndpoint.get(module, "Room/" + API_ACTIONS.activeListing)`.
+ */
+export const API_ACTIONS = {
+    details: "Detail",
+    /** Every active record: the `normal` list. */
+    listing: "NormalListing",
+    activeListing: "ActiveListing",
+    findListing: "FindListing",
+    /** One page of the `normal` list. */
+    pagination: "NormalPagination",
+    /** Every record of each list a CRUD shows. */
+    listings: { normal: "NormalListing", flag: "FlagListing", archive: "ArchiveListing", trash: "TrashListing", deleted: "DeleteListing" },
+    /** One page of each list a CRUD shows. */
+    paginations: { normal: "NormalPagination", flag: "FlagPagination", archive: "ArchivePagination", trash: "TrashPagination", deleted: "DeletePagination" },
+    /** The records the user pinned, which a CRUD shows above its list. */
+    pinListing: "PinListing",
+    create: "Create",
+    update: "Update",
+    delete: "Delete",
+    trash: "Trash",
+    trashFromDelete: "TrashFromDelete",
+    archive: "Archive",
+    recover: "Recover",
+    restore: "Restore",
+    flag: "Flag",
+    pin: "Pin",
+    audit: "AuditListing",
+    accessActions: "AccessActions",
+    massDescription: "MassDescription",
+    massArchive: "MassArchive",
+    massTrash: "MassTrash",
+    massFlag: "MassFlag",
+    massPin: "MassPin",
+    massDelete: "MassDelete",
+    massRecover: "MassRecover",
+    massRestore: "MassRestore",
+    massTrashFromDelete: "MassTrashFromDelete",
+};
+const define = (method) => (module, path, extras) => ({ ...extras, module, path, method });
+/**
+ * Builds an endpoint: `apiEndpoint.get(NexusModule.Message, "EmailProvider/ActiveListing")`. The path is under the
+ * module's root; `{name}` in it is filled from the call's `params`, then its body.
+ */
+export const apiEndpoint = {
+    get: define("GET"),
+    post: define("POST"),
+    put: define("PUT"),
+    patch: define("PATCH"),
+    delete: define("DELETE"),
+};
+/**
+ * The endpoints of a Nexus controller, named as the backend names them. `subject` is what the controller keeps, for
+ * messages ("room" → "Room saved.", "3 rooms deleted."); a call can name the record instead (`subject: "Room 204"`).
+ *
+ * @example
+ * export const ROOMS = apiController(NexusModule.Reservation, "Room", "room");
+ * api.get(ROOMS.details, { params: { id: 5 } });      // GET  /api/app/reservation/Room/Detail/5
+ * api.put(ROOMS.update, values);                      // PUT  /api/app/reservation/Room/Update   → "Room saved."
+ * api.delete(ROOMS.delete, { params: { id: 5 } });    // DELETE .../Room/Delete/5               → "Room deleted."
+ */
+export function apiController(module, controller, subject) {
+    const at = (action) => `${controller}/${action}`;
+    const endpoint = (method, path, extras) => ({ module, path, method, ...(subject && { subject }), ...extras });
+    const A = API_ACTIONS;
+    const modes = Object.keys(A.listings);
+    const byMode = (method, actions) => Object.fromEntries(modes.map(mode => [mode, endpoint(method, at(actions[mode]), { action: "load" })]));
+    return {
+        module,
+        controller,
+        /** Every active row: GET `Room/NormalListing`. */
+        listing: endpoint("GET", at(A.listing), { action: "load" }),
+        /** Active rows for dropdowns: GET `Room/ActiveListing`. */
+        activeListing: endpoint("GET", at(A.activeListing), { action: "load" }),
+        /** Rows by id, for saved values a list no longer shows: POST `Room/FindListing` with the ids. */
+        findListing: endpoint("POST", at(A.findListing), { action: "load" }),
+        /** One page of active rows: POST `Room/NormalPagination` with `{ searchKeyword, skipCount, maxCount, sorting, sortType }`. */
+        pagination: endpoint("POST", at(A.pagination), { action: "load" }),
+        /** Every row of each list, for a CRUD that pages in the browser: GET `Room/NormalListing`, `Room/TrashListing`, … */
+        lists: byMode("GET", A.listings),
+        /** One page of each list, for a CRUD that pages on the server: POST `Room/NormalPagination`, `Room/TrashPagination`, … */
+        pages: byMode("POST", A.paginations),
+        /** The records the user pinned, shown above the list: GET `Room/PinListing`. */
+        pins: endpoint("GET", at(A.pinListing), { action: "load" }),
+        /** One record: GET `Room/Detail/{id}`. */
+        details: endpoint("GET", at(`${A.details}/{id}`), { action: "load" }),
+        create: endpoint("POST", at(A.create), { action: "create" }),
+        update: endpoint("PUT", at(A.update), { action: "save" }),
+        delete: endpoint("DELETE", at(`${A.delete}/{id}`), { action: "delete" }),
+        trash: endpoint("DELETE", at(`${A.trash}/{id}`), { action: "trash" }),
+        trashFromDelete: endpoint("PUT", at(`${A.trashFromDelete}/{id}`), { action: "trash" }),
+        archive: endpoint("PUT", at(`${A.archive}/{id}`), { action: "archive" }),
+        restore: endpoint("PUT", at(`${A.restore}/{id}`), { action: "restore" }),
+        recover: endpoint("PUT", at(`${A.recover}/{id}`), { action: "recover" }),
+        flag: endpoint("PUT", at(`${A.flag}/{id}`), { action: "flag" }),
+        pin: endpoint("PUT", at(`${A.pin}/{id}`), { action: "pin" }),
+        /** A record's history: GET `Room/AuditListing/{ownerId}/{skipCount}`. */
+        audit: endpoint("GET", at(`${A.audit}/{ownerId}/{skipCount}`), { action: "load" }),
+        /** What the user may do here: GET `Room/AccessActions`. */
+        accessActions: endpoint("GET", at(A.accessActions), { action: "load" }),
+        /** Actions on many rows at once: POST `Room/MassDelete` and the rest, with the ids. */
+        mass: {
+            description: endpoint("POST", at(A.massDescription), { action: "update" }),
+            archive: endpoint("POST", at(A.massArchive), { action: "archive" }),
+            trash: endpoint("POST", at(A.massTrash), { action: "trash" }),
+            trashFromDelete: endpoint("POST", at(A.massTrashFromDelete), { action: "trash" }),
+            flag: endpoint("POST", at(A.massFlag), { action: "flag" }),
+            pin: endpoint("POST", at(A.massPin), { action: "pin" }),
+            delete: endpoint("POST", at(A.massDelete), { action: "delete" }),
+            recover: endpoint("POST", at(A.massRecover), { action: "recover" }),
+            restore: endpoint("POST", at(A.massRestore), { action: "restore" }),
+        },
+        /** Any other action of the controller: `ROOMS.action("PUT", "Block/{id}", { action: "update" })`. */
+        action: (method, action, extras) => endpoint(method, at(action), extras),
+    };
+}
+/** Whether a value is an endpoint (not a URL or a request of another shape). */
+export function isApiEndpoint(value) {
+    const endpoint = value;
+    return typeof endpoint === "object" && endpoint !== null && (typeof endpoint.module === "number" || typeof endpoint.module === "string") && typeof endpoint.path === "string" && typeof endpoint.method === "string";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Blob) && !(typeof FormData !== "undefined" && value instanceof FormData);
+}
+/** Thrown when a path names a value the call did not give, so a request never goes to ".../Detail/undefined". */
+export class ApiPathError extends Error {
+    path;
+    missing;
+    constructor(path, missing) {
+        super(`The API path "${path}" needs "${missing}", which the call did not give.`);
+        this.name = "ApiPathError";
+        this.path = path;
+        this.missing = missing;
+    }
+}
+/**
+ * Fills `{name}` in a path from `params`, then from the body's fields (names without case), and encodes each value.
+ * Leading and trailing slashes go.
+ */
+export function fillApiPath(path, params, body) {
+    const fields = isRecord(body) ? body : undefined;
+    const filled = path.replace(/\{(\w+)\}/g, (_whole, name) => {
+        let value = params?.[name];
+        if ((value === undefined || value === null) && fields) {
+            const lower = name.toLowerCase();
+            const key = name in fields ? name : Object.keys(fields).find(candidate => candidate.toLowerCase() === lower);
+            if (key !== undefined)
+                value = fields[key];
+        }
+        if (value === undefined || value === null || value === "")
+            throw new ApiPathError(path, name);
+        return encodeURIComponent(String(value));
+    });
+    return filled.replace(/^\/+|\/+$/g, "");
+}
+function queryText(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+/** Adds query values to a URL: lists repeat their name, dates go as ISO text, `null` and `undefined` are left out. */
+export function appendQuery(url, ...queries) {
+    const search = new URLSearchParams();
+    for (const query of queries) {
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined || value === null)
+                continue;
+            if (Array.isArray(value))
+                for (const item of value)
+                    search.append(key, queryText(item));
+            else
+                search.append(key, queryText(value));
+        }
+    }
+    const text = search.toString();
+    if (!text)
+        return url;
+    const hash = url.indexOf("#");
+    const [base, fragment] = hash === -1 ? [url, ""] : [url.slice(0, hash), url.slice(hash)];
+    return `${base}${base.includes("?") ? "&" : "?"}${text}${fragment}`;
+}
+/** Joins a root URL and a path with one slash between them. */
+export function joinUrl(root, path) {
+    if (!path)
+        return root.replace(/\/+$/, "");
+    return `${root.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}

package/dist/Helpers/ApiToasts.d.ts

@@ -0,0 +1,21 @@
+import type { ApiResult, HttpMethod } from "../Interfaces/ApiInterfaces.ts";
+import type { BuiltMessage, MessageContext } from "../Interfaces/MessageInterfaces.ts";
+/**
+ * Toasts for one call. `true` shows both, `false` none; or each on its own, with `true`, `false`, or a title of its own:
+ * `{ success: "Booking confirmed.", error: false, loading: true }`. `loading` shows a spinner toast while the call runs,
+ * which then turns into the success or error toast (or closes).
+ */
+export type ApiToastOption = boolean | {
+    success?: boolean | string;
+    error?: boolean | string;
+    loading?: boolean | string;
+};
+/** The app's defaults: an error toast for every failed call, a success toast for POST, PUT, PATCH, and DELETE. */
+export interface ApiToastDefaults {
+    success?: boolean;
+    error?: boolean;
+}
+/** The toast for a call's answer, or `null` for none. */
+export declare function planApiToast(result: ApiResult, method: HttpMethod, context: MessageContext, option?: ApiToastOption, defaults?: ApiToastDefaults): BuiltMessage | null;
+/** The loading toast's text for a call, or `null` for none. */
+export declare function planLoadingToast(context: MessageContext, option?: ApiToastOption): string | null;

package/dist/Helpers/ApiToasts.js

@@ -0,0 +1,22 @@
+import { buildMessage, describeResult } from "./MessageBuilder.js";
+/** The toast for a call's answer, or `null` for none. */
+export function planApiToast(result, method, context, option, defaults = {}) {
+    if (result.aborted)
+        return null;
+    const choice = typeof option === "object" ? (result.ok ? option.success : option.error) : option;
+    const wanted = choice ?? (result.ok ? (defaults.success ?? true) && method !== "GET" : (defaults.error ?? true));
+    if (!wanted)
+        return null;
+    const built = describeResult(result, context);
+    if (!built || typeof choice !== "string")
+        return built;
+    // A title of the call's own; a failure keeps the reason under it.
+    return result.ok ? { tone: "success", title: choice } : { ...built, title: choice };
+}
+/** The loading toast's text for a call, or `null` for none. */
+export function planLoadingToast(context, option) {
+    const loading = typeof option === "object" ? option.loading : undefined;
+    if (!loading)
+        return null;
+    return typeof loading === "string" ? loading : buildMessage("loading", context);
+}

package/dist/Helpers/ClassHelpers.d.ts

@@ -0,0 +1,3 @@
+export type ClassValue = string | false | null | undefined | 0;
+/** Joins class names, skipping empty and false values: `cx("nx-btn", active && "is-active")`. */
+export declare function cx(...classes: ClassValue[]): string;

package/dist/Helpers/ClassHelpers.js

@@ -0,0 +1,4 @@
+/** Joins class names, skipping empty and false values: `cx("nx-btn", active && "is-active")`. */
+export function cx(...classes) {
+    return classes.filter(Boolean).join(" ");
+}

package/dist/Helpers/CrudBackend.d.ts

@@ -0,0 +1,56 @@
+import type { CrudMassActionName } from "../Interfaces/CrudInterfaces.ts";
+import type { TableKey, TablePage, TableQuery, TableRow } from "../Interfaces/TableInterfaces.ts";
+type Row = Record<string, unknown>;
+export declare abstract class CrudBackend {
+    /** What a server table sends for one page, from the query. `sortKey` is the sorted column's server name. */
+    abstract pageRequest(query: TableQuery, sortKey: string | undefined): unknown;
+    /** Reads the page a pagination endpoint answered. */
+    abstract readPage<TRow extends TableRow>(result: unknown): TablePage<TRow>;
+    /** Reads a whole list: an array, or the rows of a page. */
+    readList<TRow extends TableRow>(result: unknown): TRow[];
+    /** What a mass action sends: the selected keys, and for `description` the new text. */
+    abstract massRequest(action: CrudMassActionName, keys: TableKey[], values?: Row): unknown;
+    abstract isFlagged(row: TableRow): boolean;
+    /** The row with its flag set or cleared. */
+    abstract withFlag<TRow extends TableRow>(row: TRow, on: boolean): TRow;
+    abstract isPinned(row: TableRow): boolean;
+    /** The row with its pin set or cleared. */
+    abstract withPin<TRow extends TableRow>(row: TRow, on: boolean): TRow;
+    /**
+     * 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: unknown, rowKey: string): Map<string, Row>;
+    /**
+     * 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: unknown, rowKey: string): Set<string> | null;
+}
+/** The Nexus record status of a flagged record (`ERecordStatus.Flagged`). */
+export declare const NEXUS_FLAGGED_STATUS = 15;
+/** The Nexus record status of an active record (`ERecordStatus.Active`). */
+export declare const NEXUS_ACTIVE_STATUS = 0;
+/**
+ * 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`.
+ */
+export declare class NexusCrudBackend extends CrudBackend {
+    pageRequest(query: TableQuery, sortKey: string | undefined): unknown;
+    readPage<TRow extends TableRow>(result: unknown): TablePage<TRow>;
+    massRequest(action: CrudMassActionName, keys: TableKey[], values?: Row): unknown;
+    isFlagged(row: TableRow): boolean;
+    withFlag<TRow extends TableRow>(row: TRow, on: boolean): TRow;
+    isPinned(row: TableRow): boolean;
+    withPin<TRow extends TableRow>(row: TRow, on: boolean): TRow;
+    /** Mass answers list the records they changed, with their new `recordStatus` and `isPinned`. */
+    answeredChanges(result: unknown, rowKey: string): Map<string, Row>;
+    /** Mass answers list the records they changed (as records, or as ids); other answers say nothing. */
+    answeredKeys(result: unknown, rowKey: string): Set<string> | null;
+}
+/** Registers the app's backend conventions, once, beside its API modules. */
+export declare function defineCrudBackend<T extends CrudBackend>(backend: T): T;
+/** The registered backend conventions, or the Nexus ones. */
+export declare function getCrudBackend(): CrudBackend;
+export {};