nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/ApiModules.d.ts

@@ -0,0 +1,131 @@
+import { NexusModule, type ApiEndpoint, type ApiModuleInfo, type ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+import { apiEndpoint, type ApiEndpointExtras, type ApiUrlParts } from "./ApiRoutes.ts";
+/** Where the proxy route sits in an app: `app/api/app/[module]/[...path]/route.ts`. */
+export declare const DEFAULT_PROXY_PATH = "/api/app";
+/** An environment variable, read when it is needed (never inlined at build time), so one build serves every environment. */
+export declare function readEnvironment(name: string | undefined): string | undefined;
+export interface ApiModulesOptions<TModule extends ApiModuleValue> {
+    /** Browser calls go through the app's proxy route, which adds the user's token on the server. Default true. */
+    useProxy?: boolean;
+    /** Where the proxy route is. Default `/api/app`. */
+    proxyPath?: string;
+    /** Root URLs the browser calls when a module does not go through the proxy. Public: the browser sees them. */
+    browserRoots?: Partial<Record<TModule, string>>;
+    /** Root URLs the server calls, by module. They win over `serverRoot`. May be relative to the app's origin. */
+    serverRoots?: Partial<Record<TModule, string>>;
+}
+/**
+ * The API modules of an app. Extend it with the app's own module enum:
+ *
+ * - `modules`: every module, with its key for proxy URLs and its label for messages.
+ * - `serverRoot(module)`: the module's root URL for server calls and the proxy (from the environment, a settings
+ *   service, anything; may be async).
+ *
+ * Then, if the defaults do not suit: `useProxy` to call modules straight from the browser, `browserRoot(module)` for
+ * those roots, and `proxies(module)` to send only some modules through the proxy.
+ *
+ * @example
+ * enum HrModule { Staff = "staff", Payroll = "payroll" }
+ *
+ * class HrApiModules extends ApiModules<HrModule> {
+ *   readonly modules = [
+ *     { module: HrModule.Staff, key: "staff", label: "Staff", env: "STAFF_API_URL" },
+ *     { module: HrModule.Payroll, key: "payroll", label: "Payroll", env: "PAYROLL_API_URL" },
+ *   ];
+ *   serverRoot(module: HrModule) {
+ *     return this.readEnv(this.info(module)?.env);
+ *   }
+ * }
+ *
+ * export const MODULES = defineApiModules(new HrApiModules());
+ * export const EMPLOYEES = MODULES.controller(HrModule.Staff, "Employee", "employee");
+ */
+export declare abstract class ApiModules<TModule extends ApiModuleValue = ApiModuleValue> {
+    /** Every module the app calls. */
+    abstract readonly modules: readonly ApiModuleInfo<TModule>[];
+    /** A module's root URL for server calls and the proxy: absolute, or relative to the app's origin. `undefined` when it is not set. */
+    abstract serverRoot(module: TModule): string | undefined | Promise<string | undefined>;
+    /** Browser calls go through the proxy route. Change it here, in the options, or in a subclass. */
+    useProxy: boolean;
+    /** Where the proxy route is. */
+    proxyPath: string;
+    protected readonly options: ApiModulesOptions<TModule>;
+    constructor(options?: ApiModulesOptions<TModule>);
+    /** A module's root URL for browser calls that skip the proxy. Default: `browserRoots` from the options. */
+    browserRoot(module: TModule): string | undefined;
+    /** Whether the browser calls a module through the proxy. Default: `useProxy`, for every module. */
+    proxies(_module: TModule): boolean;
+    /** A module by its value, its key (any case), or its value as text ("2048", as older proxy URLs have it). */
+    info(module: TModule | string): ApiModuleInfo<TModule> | undefined;
+    /** The root the browser calls for a module: the proxy's path for it, or its own root. Throws when neither is set. */
+    browserUrl(module: TModule): string;
+    /** A module's root for server calls, as set: `serverRoots`, else `serverRoot`. Throws when it is not set. May be relative. */
+    serverUrl(module: TModule): Promise<string>;
+    /** The URL the browser calls for an endpoint, for links, images, and downloads: `/api/app/reservation/Room/Detail/5`. */
+    browserApiUrl(endpoint: ApiEndpoint<TModule>, parts?: ApiUrlParts): string;
+    /** An environment variable, read at call time; for `serverRoot`. */
+    protected readEnv(name: string | undefined): string | undefined;
+    /** Endpoints typed to this app's modules: `MODULES.endpoint.get(HrModule.Staff, "Employee/Birthdays")`. */
+    readonly endpoint: Record<keyof typeof apiEndpoint, (module: TModule, path: string, extras?: ApiEndpointExtras) => ApiEndpoint<TModule>>;
+    /** A controller's standard endpoints, typed to this app's modules. See `apiController`. */
+    controller(module: TModule, controller: string, subject?: string): {
+        module: TModule;
+        controller: string;
+        listing: ApiEndpoint<TModule>;
+        activeListing: ApiEndpoint<TModule>;
+        findListing: ApiEndpoint<TModule>;
+        pagination: ApiEndpoint<TModule>;
+        lists: Record<import("../Shared.Index.ts").CrudMode, ApiEndpoint<TModule>>;
+        pages: Record<import("../Shared.Index.ts").CrudMode, ApiEndpoint<TModule>>;
+        pins: ApiEndpoint<TModule>;
+        details: ApiEndpoint<TModule>;
+        create: ApiEndpoint<TModule>;
+        update: ApiEndpoint<TModule>;
+        delete: ApiEndpoint<TModule>;
+        trash: ApiEndpoint<TModule>;
+        trashFromDelete: ApiEndpoint<TModule>;
+        recover: ApiEndpoint<TModule>;
+        flag: ApiEndpoint<TModule>;
+        pin: ApiEndpoint<TModule>;
+        audit: ApiEndpoint<TModule>;
+        accessActions: ApiEndpoint<TModule>;
+        mass: {
+            description: ApiEndpoint<TModule>;
+            trash: ApiEndpoint<TModule>;
+            trashFromDelete: ApiEndpoint<TModule>;
+            flag: ApiEndpoint<TModule>;
+            pin: ApiEndpoint<TModule>;
+            delete: ApiEndpoint<TModule>;
+            recover: ApiEndpoint<TModule>;
+        };
+        action: (method: import("../Shared.Index.ts").HttpMethod, action: string, extras?: Partial<Omit<ApiEndpoint<number>, "path" | "method" | "module">> | undefined) => ApiEndpoint<TModule>;
+    };
+}
+/** The Nexus modules, their names in proxy URLs, and the environment variables with their roots (as in the previous project). */
+export declare const NEXUS_MODULES: readonly ApiModuleInfo<NexusModule>[];
+/**
+ * The Nexus modules: each module's root from its environment variable on the server (`API_RESERVATION=…/App/Api`),
+ * browser calls through the proxy, and `NexusModule.None` for the app's own routes at `/api/…`. Extend it to change one
+ * thing, such as a module's root.
+ */
+export declare class NexusApiModules extends ApiModules<NexusModule> {
+    readonly modules: readonly ApiModuleInfo<number>[];
+    serverRoot(module: NexusModule): string | undefined;
+    browserRoot(module: NexusModule): string | undefined;
+    proxies(module: NexusModule): boolean;
+}
+/**
+ * Makes an app's modules the ones every call uses, and returns them. Define endpoints through what it returns, so any
+ * file that calls an endpoint has registered the modules first, on the server and in the browser alike.
+ *
+ * @example
+ * export const MODULES = defineApiModules(new NexusApiModules({ useProxy: process.env.NEXT_PUBLIC_API_PROXY !== "false" }));
+ * export const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");
+ */
+export declare function defineApiModules<T extends ApiModules<any>>(modules: T): T;
+/** The app's modules: the ones given to `defineApiModules`, else `NexusApiModules`. */
+export declare function getApiModules(): ApiModules<any>;
+/** The URL the browser calls for an endpoint, through the app's modules. See `ApiModules.browserApiUrl`. */
+export declare function browserApiUrl(endpoint: ApiEndpoint, parts?: ApiUrlParts): string;
+/** Names a call for logs and messages: "reservation/Room/NormalListing". */
+export declare function describeEndpoint(endpoint: ApiEndpoint): string;

package/dist/Helpers/ApiModules.js

@@ -0,0 +1,195 @@
+import { NexusModule } from "../Interfaces/ApiInterfaces.js";
+import { apiController, apiEndpoint, appendQuery, fillApiPath, joinUrl } from "./ApiRoutes.js";
+import { notConfiguredMessage } from "./MessageBuilder.js";
+/*
+ * An app's API modules: which modules it calls and where each one's root URL is. The package does not decide either.
+ * An app describes its own in a class that extends `ApiModules` (its module enum, its list, and how it finds a root)
+ * and registers it once with `defineApiModules`; the browser's `api`, the server's `serverApi`, and the proxy route all
+ * ask it. Nexus apps use `NexusApiModules`, which is also what runs when nothing is registered.
+ */
+/** Where the proxy route sits in an app: `app/api/app/[module]/[...path]/route.ts`. */
+export const DEFAULT_PROXY_PATH = "/api/app";
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** An environment variable, read when it is needed (never inlined at build time), so one build serves every environment. */
+export function readEnvironment(name) {
+    if (!name)
+        return undefined;
+    const env = globalThis.process?.env;
+    return env?.[name]?.trim() || undefined;
+}
+/**
+ * The API modules of an app. Extend it with the app's own module enum:
+ *
+ * - `modules`: every module, with its key for proxy URLs and its label for messages.
+ * - `serverRoot(module)`: the module's root URL for server calls and the proxy (from the environment, a settings
+ *   service, anything; may be async).
+ *
+ * Then, if the defaults do not suit: `useProxy` to call modules straight from the browser, `browserRoot(module)` for
+ * those roots, and `proxies(module)` to send only some modules through the proxy.
+ *
+ * @example
+ * enum HrModule { Staff = "staff", Payroll = "payroll" }
+ *
+ * class HrApiModules extends ApiModules<HrModule> {
+ *   readonly modules = [
+ *     { module: HrModule.Staff, key: "staff", label: "Staff", env: "STAFF_API_URL" },
+ *     { module: HrModule.Payroll, key: "payroll", label: "Payroll", env: "PAYROLL_API_URL" },
+ *   ];
+ *   serverRoot(module: HrModule) {
+ *     return this.readEnv(this.info(module)?.env);
+ *   }
+ * }
+ *
+ * export const MODULES = defineApiModules(new HrApiModules());
+ * export const EMPLOYEES = MODULES.controller(HrModule.Staff, "Employee", "employee");
+ */
+export class ApiModules {
+    /** Browser calls go through the proxy route. Change it here, in the options, or in a subclass. */
+    useProxy;
+    /** Where the proxy route is. */
+    proxyPath;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        this.useProxy = options.useProxy ?? true;
+        this.proxyPath = options.proxyPath ?? DEFAULT_PROXY_PATH;
+    }
+    /** A module's root URL for browser calls that skip the proxy. Default: `browserRoots` from the options. */
+    browserRoot(module) {
+        return this.options.browserRoots?.[module];
+    }
+    /** Whether the browser calls a module through the proxy. Default: `useProxy`, for every module. */
+    proxies(_module) {
+        return this.useProxy;
+    }
+    /** A module by its value, its key (any case), or its value as text ("2048", as older proxy URLs have it). */
+    info(module) {
+        const list = this.modules;
+        const exact = list.find(info => info.module === module);
+        if (exact || typeof module !== "string")
+            return exact;
+        const key = module.toLowerCase();
+        return list.find(info => info.key.toLowerCase() === key || String(info.module).toLowerCase() === key);
+    }
+    /** The root the browser calls for a module: the proxy's path for it, or its own root. Throws when neither is set. */
+    browserUrl(module) {
+        const info = this.info(module);
+        if (!info)
+            throw new Error(`"${String(module)}" is not one of the app's API modules.`);
+        if (this.proxies(module))
+            return joinUrl(this.proxyPath, info.key);
+        const root = this.browserRoot(module);
+        if (!root)
+            throw new Error(notConfiguredMessage(info.label, "browserRoot"));
+        return root;
+    }
+    /** A module's root for server calls, as set: `serverRoots`, else `serverRoot`. Throws when it is not set. May be relative. */
+    async serverUrl(module) {
+        const info = this.info(module);
+        if (!info)
+            throw new Error(`"${String(module)}" is not one of the app's API modules.`);
+        const root = this.options.serverRoots?.[module] ?? (await this.serverRoot(module));
+        if (!root)
+            throw new Error(notConfiguredMessage(info.label, info.env ?? "serverRoot"));
+        return root;
+    }
+    /** The URL the browser calls for an endpoint, for links, images, and downloads: `/api/app/reservation/Room/Detail/5`. */
+    browserApiUrl(endpoint, parts = {}) {
+        return appendQuery(joinUrl(this.browserUrl(endpoint.module), fillApiPath(endpoint.path, parts.params, parts.body)), endpoint.query, parts.query);
+    }
+    /** An environment variable, read at call time; for `serverRoot`. */
+    readEnv(name) {
+        return readEnvironment(name);
+    }
+    /** Endpoints typed to this app's modules: `MODULES.endpoint.get(HrModule.Staff, "Employee/Birthdays")`. */
+    endpoint = apiEndpoint;
+    /** A controller's standard endpoints, typed to this app's modules. See `apiController`. */
+    controller(module, controller, subject) {
+        return apiController(module, controller, subject);
+    }
+}
+/** The Nexus modules, their names in proxy URLs, and the environment variables with their roots (as in the previous project). */
+export const NEXUS_MODULES = [
+    { module: NexusModule.Configuration, key: "configuration", label: "Configuration", env: "API_CONFIGURATION" },
+    { module: NexusModule.Identity, key: "identity", label: "Identity", env: "API_IDENTITY" },
+    { module: NexusModule.Enterprise, key: "enterprise", label: "Enterprise", env: "API_ENTERPRISE" },
+    { module: NexusModule.Drive, key: "drive", label: "Drive", env: "API_DRIVE" },
+    { module: NexusModule.Message, key: "message", label: "Message", env: "API_MESSAGE" },
+    { module: NexusModule.Chat, key: "chat", label: "Chat", env: "API_CHAT" },
+    { module: NexusModule.Accounting, key: "accounting", label: "Accounting", env: "API_ACCOUNTING" },
+    { module: NexusModule.Report, key: "report", label: "Report", env: "API_REPORT" },
+    { module: NexusModule.Requisition, key: "requisition", label: "Requisition", env: "API_REQUISITION" },
+    { module: NexusModule.Tenant, key: "tenant", label: "Tenant", env: "API_TENANT" },
+    { module: NexusModule.Subscription, key: "subscription", label: "Subscription", env: "API_SUBSCRIPTION" },
+    { module: NexusModule.Reservation, key: "reservation", label: "Reservation", env: "API_RESERVATION" },
+    { module: NexusModule.School, key: "school", label: "School", env: "API_SCHOOL" },
+    { module: NexusModule.Pharmacy, key: "pharmacy", label: "Pharmacy", env: "API_PHARMACY" },
+    { module: NexusModule.Staffing, key: "staffing", label: "Staffing", env: "API_STAFFING" },
+    { module: NexusModule.Portfolio, key: "portfolio", label: "Portfolio", env: "API_PORTFOLIO" },
+    // The app's own API routes (/api/...), never through the proxy.
+    { module: NexusModule.None, key: "app", label: "App" },
+];
+/**
+ * The Nexus modules: each module's root from its environment variable on the server (`API_RESERVATION=…/App/Api`),
+ * browser calls through the proxy, and `NexusModule.None` for the app's own routes at `/api/…`. Extend it to change one
+ * thing, such as a module's root.
+ */
+export class NexusApiModules extends ApiModules {
+    modules = NEXUS_MODULES;
+    serverRoot(module) {
+        if (module === NexusModule.None)
+            return "/api";
+        return this.readEnv(this.info(module)?.env);
+    }
+    browserRoot(module) {
+        return module === NexusModule.None ? "/api" : super.browserRoot(module);
+    }
+    proxies(module) {
+        return module !== NexusModule.None && super.proxies(module);
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let registered;
+/** Checks a modules class: every module once, keys that fit in a URL. Throws on the first problem. */
+function checkModules(modules) {
+    const keys = new Set();
+    const values = new Set();
+    for (const info of modules.modules) {
+        if (!KEY_PATTERN.test(info.key))
+            throw new Error(`API module key "${info.key}" can hold letters, digits, dots, dashes, and underscores only.`);
+        const key = info.key.toLowerCase();
+        if (keys.has(key))
+            throw new Error(`Two API modules have the key "${info.key}".`);
+        if (values.has(info.module))
+            throw new Error(`Two API modules have the value ${String(info.module)}.`);
+        keys.add(key);
+        values.add(info.module);
+    }
+}
+/**
+ * Makes an app's modules the ones every call uses, and returns them. Define endpoints through what it returns, so any
+ * file that calls an endpoint has registered the modules first, on the server and in the browser alike.
+ *
+ * @example
+ * export const MODULES = defineApiModules(new NexusApiModules({ useProxy: process.env.NEXT_PUBLIC_API_PROXY !== "false" }));
+ * export const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function defineApiModules(modules) {
+    checkModules(modules);
+    registered = modules;
+    return modules;
+}
+/** The app's modules: the ones given to `defineApiModules`, else `NexusApiModules`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getApiModules() {
+    return (registered ??= new NexusApiModules());
+}
+/** The URL the browser calls for an endpoint, through the app's modules. See `ApiModules.browserApiUrl`. */
+export function browserApiUrl(endpoint, parts) {
+    return getApiModules().browserApiUrl(endpoint, parts);
+}
+/** Names a call for logs and messages: "reservation/Room/NormalListing". */
+export function describeEndpoint(endpoint) {
+    return `${getApiModules().info(endpoint.module)?.key ?? String(endpoint.module)}/${endpoint.path}`;
+}

package/dist/Helpers/ApiResponses.d.ts

@@ -0,0 +1,51 @@
+import type { ApiErrorMessage, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { MessageAction, MessageContext } from "../Interfaces/MessageInterfaces.ts";
+/** Shown when nothing reached the server (the default wording; `messages.reason({ network: true })` follows `configureMessages`). */
+export declare const NETWORK_ERROR_MESSAGE: string;
+/** 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 declare function apiStatusMessage(status: number | undefined, action?: MessageAction): string;
+/**
+ * Every problem a body lists, in its order, however it listed them: `errorMessages` as a list or as one message object,
+ * `errorMessage` either way, or an `errors` list (an `errors` map by field name is read by `readErrorMap` instead).
+ * Plain sentences count. Empty for a body that lists nothing; `fallback` is then read as the one problem, which is how
+ * the message and codes at the top level of a Nexus answer are read.
+ */
+export declare function readErrorMessages(body: unknown, fallback?: unknown): ApiErrorMessage[];
+/**
+ * Reads a server's answer as success or failure:
+ * - Nexus API responses, `{ isSuccess, code, errorMessages: [{ message, messageCode, errorCode, inputName }], result }`:
+ *   every problem is kept, in the server's order, and `inputName` names the inputs a message is about (several with "|").
+ *   `errorMessages` may be one message object instead of a list, and an older answer carries its one message and codes at
+ *   the top level (`{ isSuccess, message, messageCode, errorCode, inputName }`); all of them are read the same way.
+ * - ASP.NET Core problem details and validation errors, `{ title, detail, errors: { Email: ["…"] } }`.
+ * - Anything else by its HTTP status; the body is the result.
+ *
+ * The server's own words are the message whenever it sent any. Only a failure that explains nothing gets a message by
+ * status, worded for what the call did (`context`, default: a save).
+ */
+export declare function readApiResponse(body: unknown, status?: number, context?: MessageContext): ApiResult;
+/** Reads a `fetch` response: its JSON (or text) through `read`. */
+export declare function readFetchResponse(response: Response, read?: (body: unknown, status: number | undefined) => ApiResult): Promise<ApiResult>;
+/** Whether an error is a request stopped on purpose (the form closed), which shows nothing. */
+export declare function isAbortError(error: unknown): boolean;
+/** A thrown error as a message: its own, or the network message for a failed `fetch`. */
+export declare function errorMessage(error: unknown, fallback?: string): string;
+/** Values as form fields: lists of plain values repeat their name, objects and lists of objects go as JSON text. */
+export declare function toFormData(values: unknown): FormData;
+/** Whether a value is already a read answer (`{ ok, … }`), not a server's body. */
+export declare function isApiResult(value: unknown): value is ApiResult;
+/** A failed answer as an error, for code that throws: a server component's error boundary, a form's `loadValue`. */
+export declare class ApiError extends Error {
+    readonly response: ApiResult;
+    constructor(response: ApiResult);
+    get status(): number | undefined;
+}
+/**
+ * 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 declare function unwrapApiResult<T>(response: ApiResult<T>): T;

package/dist/Helpers/ApiResponses.js

@@ -0,0 +1,250 @@
+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.
+ *
+ * What the server says always wins: a body that explains its refusal is shown in the server's own words, however it
+ * carried them (a list, one message object, or the message at the top level), and the messages built from the HTTP
+ * status are only the fallback for an answer that explains nothing.
+ */
+/** 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;
+}
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 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;
+}
+/** The backend's defaults say nothing about what went wrong, so they are left out. */
+const EMPTY_CODES = ["SUCCESS", "GENERIC_ERROR"];
+/** A code worth keeping: not one of the backend's defaults. */
+function codeOf(value) {
+    const code = text(value);
+    return code && !EMPTY_CODES.includes(code) ? code : undefined;
+}
+/**
+ * One problem from any shape a backend sends it in: `{ message, messageCode, errorCode, inputName }`, a plain sentence,
+ * or a wording of the same fields (`errorMessage`, `code`, `field`, `propertyName`). Nothing without words to show.
+ */
+function readErrorMessage(value) {
+    if (typeof value === "string") {
+        const sentence = text(value);
+        return sentence ? { message: sentence } : undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const message = text(value.message) ?? text(value.errorMessage) ?? text(value.detail) ?? text(value.title);
+    if (!message)
+        return undefined;
+    const messageCode = codeOf(value.messageCode) ?? codeOf(value.code);
+    const errorCode = count(value.errorCode);
+    const inputName = text(value.inputName) ?? text(value.field) ?? text(value.propertyName);
+    return {
+        message,
+        ...(messageCode ? { messageCode } : {}),
+        ...(errorCode ? { errorCode } : {}),
+        ...(inputName ? { inputName } : {}),
+    };
+}
+/**
+ * Every problem a body lists, in its order, however it listed them: `errorMessages` as a list or as one message object,
+ * `errorMessage` either way, or an `errors` list (an `errors` map by field name is read by `readErrorMap` instead).
+ * Plain sentences count. Empty for a body that lists nothing; `fallback` is then read as the one problem, which is how
+ * the message and codes at the top level of a Nexus answer are read.
+ */
+export function readErrorMessages(body, fallback) {
+    const list = (values) => values.map(readErrorMessage).filter((problem) => Boolean(problem));
+    if (Array.isArray(body))
+        return list(body);
+    if (isRecord(body)) {
+        for (const key of ["errorMessages", "errorMessage", "errors"]) {
+            const value = body[key];
+            if (value === undefined || value === null)
+                continue;
+            // `errors` is a list of problems only when it is a list; as an object it names fields.
+            if (key === "errors" && !Array.isArray(value))
+                continue;
+            const problems = list(Array.isArray(value) ? value : [value]);
+            if (problems.length)
+                return problems;
+        }
+    }
+    if (fallback === undefined)
+        return [];
+    const own = readErrorMessage(fallback);
+    return own ? [own] : [];
+}
+/** The problems that name an input, as one message per name: several on one name joined, `"floor|rate"` naming both. */
+function fieldErrors(problems) {
+    const errors = {};
+    for (const { message, inputName } of problems) {
+        if (!inputName)
+            continue;
+        for (const part of inputName.split("|")) {
+            const name = part.trim();
+            if (!name)
+                continue;
+            errors[name] = errors[name] && errors[name] !== message ? `${errors[name]} ${message}` : message;
+        }
+    }
+    return Object.keys(errors).length ? errors : undefined;
+}
+/**
+ * Reads a server's answer as success or failure:
+ * - Nexus API responses, `{ isSuccess, code, errorMessages: [{ message, messageCode, errorCode, inputName }], result }`:
+ *   every problem is kept, in the server's order, and `inputName` names the inputs a message is about (several with "|").
+ *   `errorMessages` may be one message object instead of a list, and an older answer carries its one message and codes at
+ *   the top level (`{ isSuccess, message, messageCode, errorCode, inputName }`); all of them are read the same way.
+ * - ASP.NET Core problem details and validation errors, `{ title, detail, errors: { Email: ["…"] } }`.
+ * - Anything else by its HTTP status; the body is the result.
+ *
+ * The server's own words are the message whenever it sent any. Only a failure that explains nothing gets a message 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;
+            // A failure's problems: its list, else the message and codes at the top level as the one problem.
+            const problems = ok ? [] : readErrorMessages(body, body);
+            const said = problems.map(problem => problem.message).join(" ") || text(body.message);
+            const messageCode = problems[0]?.messageCode ?? codeOf(body.messageCode);
+            const errorCode = problems[0]?.errorCode ?? count(body.errorCode);
+            return {
+                ok,
+                // An answer read without its HTTP status (an app's own send function) still carries it as `code`.
+                status: status ?? count(body.code),
+                result: body.result,
+                message: said ?? (ok ? undefined : fallback()),
+                errors: fieldErrors(problems),
+                ...(problems.length ? { errorMessages: problems } : {}),
+                ...(messageCode ? { messageCode } : {}),
+                ...(errorCode ? { errorCode } : {}),
+            };
+        }
+        // Another backend's envelope: its problems if it lists any, ASP.NET Core's field map, or its status.
+        const problems = readErrorMessages(body);
+        const errors = readErrorMap(body.errors) ?? fieldErrors(problems);
+        if (problems.length || errors || !statusOk) {
+            const said = problems.map(problem => problem.message).join(" ") || (text(body.message) ?? (errors ? undefined : (text(body.detail) ?? text(body.title))));
+            const messageCode = problems[0]?.messageCode;
+            const errorCode = problems[0]?.errorCode;
+            return {
+                ok: false,
+                status,
+                result: body,
+                message: said ?? (errors ? undefined : fallback()),
+                errors,
+                ...(problems.length ? { errorMessages: problems } : {}),
+                ...(messageCode ? { messageCode } : {}),
+                ...(errorCode ? { errorCode } : {}),
+            };
+        }
+        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", "errorMessages", "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;
+}