nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/ApiClient.js

@@ -0,0 +1,197 @@
+import { isAbortError, readApiResponse, readFetchResponse, toFormData } from "./ApiResponses.js";
+import { appendQuery, fillApiPath, isApiEndpoint } from "./ApiRoutes.js";
+import { buildMessage } from "./MessageBuilder.js";
+export const DEFAULT_API_TIMEOUT = 60_000;
+/** Statuses worth one more try for a GET: the server or a gateway was briefly unavailable. */
+const RETRY_STATUSES = new Set([502, 503, 504]);
+/** What a call does when it names nothing: GET loads, DELETE deletes, the rest save. */
+export function defaultAction(method) {
+    return method === "GET" ? "load" : method === "DELETE" ? "delete" : "save";
+}
+/** What a call does and acts on: its endpoint, its method, and the context its messages are built from. */
+export function apiCallContext(target, options = {}) {
+    const endpoint = isApiEndpoint(target) ? target : undefined;
+    const method = options.method ?? endpoint?.method ?? "GET";
+    const context = { action: options.action ?? endpoint?.action ?? defaultAction(method), subject: options.subject ?? endpoint?.subject };
+    if (options.count !== undefined)
+        context.count = options.count;
+    if (options.plural)
+        context.plural = options.plural;
+    return { endpoint, method, context };
+}
+function isRawBody(body) {
+    return ((typeof Blob !== "undefined" && body instanceof Blob) ||
+        (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
+}
+function pause(ms, signal) {
+    return new Promise(resolve => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
+const aborted = () => ({ ok: false, aborted: true });
+/**
+ * Whether an error is a framework's own signal passing through a call, never a failed request: Next.js throws one from
+ * `headers()`, `cookies()`, or a `no-store` fetch while it prerenders, to learn that a page renders per request (and
+ * for `redirect()` and `notFound()`). Each carries a `digest`, or React's `$typeof`. The engine throws them on.
+ */
+export function isFrameworkError(error) {
+    const value = error;
+    return typeof value === "object" && value !== null && (typeof value.digest === "string" || value.$typeof !== undefined);
+}
+/**
+ * Makes an API client. Apps use the two made here, `api` (browser) and `serverApi` (server); make another for an API
+ * that is not a Nexus module.
+ */
+export function createApiClient(config) {
+    const inflight = new Map();
+    function describe(target, options) {
+        return { target, ...apiCallContext(target, options), url: "", options };
+    }
+    async function resolve(call) {
+        const { endpoint, options } = call;
+        if (endpoint) {
+            const path = fillApiPath(endpoint.path, options.params, options.body);
+            return appendQuery(await config.resolveUrl(endpoint, path, call), endpoint.query, options.query);
+        }
+        const url = call.target;
+        return appendQuery(config.resolveTarget ? await config.resolveTarget(url, call) : url, options.query);
+    }
+    /** Sends the request and reads its answer. */
+    async function request(call) {
+        const { method, options, endpoint } = call;
+        const headers = { Accept: "application/json", ...(await config.headers?.(call)) };
+        const token = await config.token?.(call);
+        if (token)
+            headers.Authorization = /^bearer /i.test(token) ? token : `Bearer ${token}`;
+        let body;
+        if (method !== "GET" && options.body !== undefined) {
+            const bodyType = options.bodyType ?? endpoint?.bodyType ?? (typeof FormData !== "undefined" && options.body instanceof FormData ? "form-data" : "json");
+            if (isRawBody(options.body))
+                body = options.body;
+            else if (bodyType === "form-data")
+                body = toFormData(options.body);
+            else {
+                body = JSON.stringify(options.body);
+                headers["Content-Type"] = "application/json";
+            }
+        }
+        Object.assign(headers, options.headers);
+        const controller = new AbortController();
+        const caller = options.signal;
+        const stop = () => controller.abort();
+        caller?.addEventListener("abort", stop, { once: true });
+        let timedOut = false;
+        const timeout = options.timeout ?? config.timeout ?? DEFAULT_API_TIMEOUT;
+        const timer = timeout > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, timeout)
+            : undefined;
+        const read = options.read ?? ((answer, status) => readApiResponse(answer, status, call.context));
+        const stopped = () => caller?.aborted ? aborted() : timedOut ? { ok: false, timeout: true, message: buildMessage("reason", { ...call.context, timeout: true }) } : undefined;
+        let init = { method, headers, body, credentials: options.credentials ?? config.credentials, signal: controller.signal };
+        if (config.prepare)
+            init = config.prepare(init, call);
+        const send = config.fetch ?? globalThis.fetch;
+        const retries = options.retries ?? (method === "GET" ? 1 : 0);
+        try {
+            for (let attempt = 0;; attempt++) {
+                if (caller?.aborted)
+                    return aborted();
+                let response;
+                try {
+                    response = await send(call.url, init);
+                }
+                catch (error) {
+                    if (isFrameworkError(error))
+                        throw error;
+                    const early = stopped();
+                    if (early)
+                        return early;
+                    // Aborted by a signal the call does not know, such as the page closing: nothing to show either.
+                    if (isAbortError(error))
+                        return aborted();
+                    if (attempt < retries) {
+                        await pause(300 * 2 ** attempt, controller.signal);
+                        continue;
+                    }
+                    return { ok: false, network: true, message: buildMessage("reason", { ...call.context, network: true }) };
+                }
+                if (RETRY_STATUSES.has(response.status) && attempt < retries) {
+                    await response.body?.cancel().catch(() => undefined);
+                    await pause(300 * 2 ** attempt, controller.signal);
+                    continue;
+                }
+                const result = await readFetchResponse(response, read);
+                // A body cut off by an abort or the timeout reads as empty: say what happened instead.
+                return stopped() ?? result;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            caller?.removeEventListener("abort", stop);
+        }
+    }
+    async function send(target, options = {}) {
+        const call = describe(target, options);
+        const done = config.onStart?.(call);
+        let result;
+        try {
+            call.url = await resolve(call);
+        }
+        catch (error) {
+            if (isFrameworkError(error)) {
+                done?.(aborted());
+                throw error;
+            }
+            // A module without a root URL, or a path that names a value the call did not give: nothing is sent.
+            result = { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+        if (!result) {
+            try {
+                result = await run(call);
+            }
+            catch (error) {
+                // A framework's signal (or a throw in the app's own headers or token): a loading toast closes, the error goes on.
+                done?.(aborted());
+                throw error;
+            }
+        }
+        config.onResult?.(result, call);
+        done?.(result);
+        return result;
+    }
+    async function run(call) {
+        if (!config.dedupe || call.method !== "GET" || call.options.signal)
+            return request(call);
+        let shared = inflight.get(call.url);
+        if (!shared) {
+            shared = request(call).finally(() => inflight.delete(call.url));
+            inflight.set(call.url, shared);
+        }
+        // Each caller gets its own copy, so one cannot change another's answer.
+        return { ...(await shared) };
+    }
+    const withBody = (method) => (target, body, options) => send(target, { ...options, body, method });
+    return {
+        send,
+        get: (target, options) => send(target, { ...options, method: "GET" }),
+        post: withBody("POST"),
+        put: withBody("PUT"),
+        patch: withBody("PATCH"),
+        delete: (target, options) => send(target, { ...options, method: "DELETE" }),
+        url: (target, options = {}) => resolve(describe(target, options)),
+    };
+}

package/dist/Helpers/ApiFormHelpers.d.ts

@@ -0,0 +1,26 @@
+import type { ApiCallOptions, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { ApiRequest, FormErrors } from "../Interfaces/FormInterfaces.ts";
+export interface SendApiOptions {
+    signal?: AbortSignal;
+    read?: (body: unknown, status: number | undefined) => ApiResult;
+}
+/** The call options of a form's `{ url, method, headers, bodyType, credentials }` request with its values. */
+export declare function apiRequestOptions(request: ApiRequest, body: unknown, { signal, read }?: SendApiOptions): ApiCallOptions;
+/** An abort as the error `fetch` throws, for code that expects a stopped request to reject. */
+export declare function abortError(): Error;
+/**
+ * Sends a body with `fetch` and reads the answer. Resolves with a failed result for a network error or a timeout;
+ * rejects only when the request is aborted. `ApiForm` sends through the app's `api` instead, with its headers.
+ */
+export declare function sendApiRequest(request: ApiRequest, body: unknown, options?: SendApiOptions): Promise<ApiResult>;
+/** What an `ApiSend` function answered, read the same way: a `Response`, an `ApiResult`, or a body. */
+export declare function toApiResult(answer: unknown, read?: (body: unknown, status: number | undefined) => ApiResult): Promise<ApiResult>;
+/**
+ * Puts a server's messages on the inputs they name. Names match without case, and a path matches its first part that is
+ * an input ("Addresses[1].City" and "$.addresses" go to "addresses"; "dto.Email" to "email"). Messages that match no
+ * input are returned in `others`, for the form's message.
+ */
+export declare function matchFieldErrors(errors: Record<string, string> | undefined, inputNames: readonly string[]): {
+    fields: FormErrors;
+    others: string[];
+};

package/dist/Helpers/ApiFormHelpers.js

@@ -0,0 +1,56 @@
+import { createApiClient } from "./ApiClient.js";
+import { isApiResult, readApiResponse, readFetchResponse } from "./ApiResponses.js";
+/** The call options of a form's `{ url, method, headers, bodyType, credentials }` request with its values. */
+export function apiRequestOptions(request, body, { signal, read = readApiResponse } = {}) {
+    const { method = "POST", headers, bodyType = "json", credentials } = request;
+    return { method, headers, bodyType, credentials, signal, read, body: body ?? {} };
+}
+/** An abort as the error `fetch` throws, for code that expects a stopped request to reject. */
+export function abortError() {
+    return typeof DOMException === "function" ? new DOMException("The request was aborted.", "AbortError") : Object.assign(new Error("The request was aborted."), { name: "AbortError" });
+}
+/** Sends URLs as they are, with none of an app's settings. */
+const plainClient = createApiClient({
+    resolveUrl: () => {
+        throw new Error("sendApiRequest takes a URL; call an endpoint with api or serverApi.");
+    },
+});
+/**
+ * Sends a body with `fetch` and reads the answer. Resolves with a failed result for a network error or a timeout;
+ * rejects only when the request is aborted. `ApiForm` sends through the app's `api` instead, with its headers.
+ */
+export async function sendApiRequest(request, body, options = {}) {
+    const result = await plainClient.send(request.url, apiRequestOptions(request, body, options));
+    if (result.aborted)
+        throw abortError();
+    return result;
+}
+/** What an `ApiSend` function answered, read the same way: a `Response`, an `ApiResult`, or a body. */
+export async function toApiResult(answer, read = readApiResponse) {
+    if (typeof Response !== "undefined" && answer instanceof Response)
+        return readFetchResponse(answer, read);
+    if (isApiResult(answer))
+        return answer;
+    return read(answer, undefined);
+}
+/**
+ * Puts a server's messages on the inputs they name. Names match without case, and a path matches its first part that is
+ * an input ("Addresses[1].City" and "$.addresses" go to "addresses"; "dto.Email" to "email"). Messages that match no
+ * input are returned in `others`, for the form's message.
+ */
+export function matchFieldErrors(errors, inputNames) {
+    const byName = new Map(inputNames.map(name => [name.toLowerCase(), name]));
+    const fields = {};
+    const others = [];
+    for (const [key, message] of Object.entries(errors ?? {})) {
+        if (!message)
+            continue;
+        const parts = key.replace(/^\$\.?/, "").split(/[.[\]]+/).filter(Boolean);
+        const name = parts.slice(0, 2).map(part => byName.get(part.toLowerCase())).find(Boolean);
+        if (name)
+            fields[name] = fields[name] && fields[name] !== message ? `${fields[name]} ${message}` : message;
+        else if (!others.includes(message))
+            others.push(message);
+    }
+    return { fields, others };
+}

package/dist/Helpers/ApiModules.d.ts

@@ -0,0 +1,135 @@
+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>;
+        archive: ApiEndpoint<TModule>;
+        restore: ApiEndpoint<TModule>;
+        recover: ApiEndpoint<TModule>;
+        flag: ApiEndpoint<TModule>;
+        pin: ApiEndpoint<TModule>;
+        audit: ApiEndpoint<TModule>;
+        accessActions: ApiEndpoint<TModule>;
+        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>;
+        };
+        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,194 @@
+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.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,41 @@
+import type { 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;
+/**
+ * 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 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;