nexus-shared 3.0.0 → 3.2.0

package/dist/Services/ApiProxyRules.js

@@ -0,0 +1,426 @@
+/*
+ * The rules the API proxy keeps so that the browser never learns where the backend is or what it runs: which request
+ * headers go on, which response headers come back, which redirects the proxy follows itself, and which error answers it
+ * replaces. Plain functions over the standard Headers, URL and streams, so they run in Node, the Edge runtime and the
+ * unit tests alike. `ApiProxy.ts` puts them together.
+ */
+/** The most bytes a request body may have, unless the app says otherwise (`maxBodySize`): 100 MB. */
+export const DEFAULT_PROXY_BODY_LIMIT = 100 * 1024 * 1024;
+/** How many redirects inside a module the proxy follows for one call, unless the app says otherwise (`maxRedirects`). */
+export const DEFAULT_PROXY_REDIRECTS = 3;
+/** The most of an error answer the proxy reads to see what it is. A bigger one is never passed on. */
+export const ERROR_BODY_LIMIT = 1024 * 1024;
+// ---------------------------------------------------------------------------------------------------------------------
+// Request headers
+/** Request headers that never reach the backend. */
+const REQUEST_HEADERS_DROPPED = new Set([
+    // This hop's own, and what `fetch` sets by itself. `expect` would make Node's fetch throw.
+    "host",
+    "connection",
+    "keep-alive",
+    "proxy-connection",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    "expect",
+    "content-length",
+    "accept-encoding",
+    "proxy-authorization",
+    // The app's session stays with the app; the user's token goes instead.
+    "cookie",
+    // Where the request came from, as the browser tells it: anyone can send these, so the proxy writes its own.
+    "forwarded",
+    "via",
+    "x-real-ip",
+    "x-client-ip",
+    "true-client-ip",
+    "cf-connecting-ip",
+    "fastly-client-ip",
+    "x-cluster-client-ip",
+    "x-original-forwarded-for",
+    // Headers some servers obey to change the method or the path after the proxy has checked both.
+    "x-http-method-override",
+    "x-http-method",
+    "x-method-override",
+    "x-original-url",
+    "x-rewrite-url",
+    // Next.js's own.
+    "rsc",
+]);
+/** Prefixes of request headers that never reach the backend: every X-Forwarded-* (the proxy writes its own), and Next.js's. */
+const REQUEST_PREFIXES_DROPPED = ["x-forwarded-", "x-middleware-", "x-invoke-", "x-nextjs-", "next-"];
+/**
+ * The browser's request headers the backend may see: all of them except the ones above, and except any that the
+ * request's own `Connection` header names (those belong to this hop too).
+ */
+export function forwardRequestHeaders(incoming) {
+    const named = (incoming.get("connection") ?? "")
+        .split(",")
+        .map(name => name.trim().toLowerCase())
+        .filter(name => name !== "");
+    const headers = new Headers();
+    incoming.forEach((value, name) => {
+        const lower = name.toLowerCase();
+        if (REQUEST_HEADERS_DROPPED.has(lower) || named.includes(lower))
+            return;
+        if (REQUEST_PREFIXES_DROPPED.some(prefix => lower.startsWith(prefix)))
+            return;
+        headers.set(name, value);
+    });
+    return headers;
+}
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+/** The only characters an IPv6 address is written with: hex digits, colons, and the dots of an IPv4 address at its end. */
+const IPV6_CHARACTERS = /^[0-9a-f:.]+$/i;
+/**
+ * An IP address as text, without the port some proxies add; `undefined` for anything else (a host name, "unknown", an
+ * obfuscated identifier, a zone such as `%eth0`). An IPv6 address is checked by the URL parser, which every runtime has,
+ * once its characters are known to be an address's: without that, text that closes the bracket itself and goes on
+ * (`::1]/,6.6.6.6`) parsed as an address followed by a path.
+ *
+ * @example
+ * readIpAddress(" 203.0.113.7:51000 ")   // "203.0.113.7"
+ * readIpAddress("[2001:db8::1]:443")      // "2001:db8::1"
+ * readIpAddress("unknown")                // undefined
+ * readIpAddress("::1]/,6.6.6.6")          // undefined
+ */
+export function readIpAddress(value) {
+    let text = value?.trim();
+    if (!text)
+        return undefined;
+    const bracketed = /^\[([^\]]+)\](:\d+)?$/.exec(text);
+    if (bracketed)
+        text = bracketed[1];
+    else if (/^[\d.]+:\d+$/.test(text))
+        text = text.slice(0, text.lastIndexOf(":"));
+    if (IPV4.test(text))
+        return text;
+    if (!text.includes(":") || !IPV6_CHARACTERS.test(text))
+        return undefined;
+    try {
+        new URL(`http://[${text}]/`);
+        return text;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * This server's own origin, for a module whose root is a path on the app (a pretend backend): the host and port of the
+ * request URL, over http. Next.js builds that URL from the host and port it listens on, never from the Host header, but
+ * takes its protocol from X-Forwarded-Proto, which anyone can send, so the protocol is not read from it. A server that
+ * listens on every address (`0.0.0.0`, `::`) is called on this machine's own, and the port is always the one Next.js
+ * wrote, even when the URL leaves it out as its protocol's default.
+ *
+ * Never the app's configured origin: an app may build that from a request's Host header, and then a client would choose
+ * which port on this machine the proxy calls, with the user's token.
+ *
+ * @example
+ * ownOrigin(new URL("https://localhost:20016/api/app/drive/File/List"))   // "http://localhost:20016"
+ * ownOrigin(new URL("http://0.0.0.0:3000/api/app/drive/File/List"))       // "http://127.0.0.1:3000"
+ */
+export function ownOrigin(requestUrl) {
+    let host = requestUrl.hostname;
+    if (host === "0.0.0.0")
+        host = "127.0.0.1";
+    else if (host === "[::]")
+        host = "[::1]";
+    let port = requestUrl.port;
+    if (port === "")
+        port = requestUrl.protocol === "https:" ? "443" : "80";
+    return `http://${host}:${port}`;
+}
+/**
+ * The client's address as the app received it: the **last** one in X-Forwarded-For, which is the one Next.js (from the
+ * connection) or the app's own reverse proxy in front of it wrote. The ones before it are what the client claims, and
+ * a client can claim anything. Behind two proxies of the app's own, or a CDN with a header of its own, the app passes
+ * `clientAddress` to the proxy instead. It reads anything with a `get`: a request's headers, or Next.js's `headers()`.
+ *
+ * @example
+ * // A browser sent "X-Forwarded-For: 6.6.6.6"; the app's nginx appended the address it really came from.
+ * lastForwardedAddress(new Headers({ "x-forwarded-for": "6.6.6.6, 203.0.113.7" }))   // "203.0.113.7"
+ */
+export function lastForwardedAddress(headers) {
+    const list = headers.get("x-forwarded-for");
+    if (!list)
+        return undefined;
+    const parts = list.split(",");
+    return readIpAddress(parts[parts.length - 1]);
+}
+/**
+ * Whether a browser sent this request from a page of another site, other than by following a link. Every current
+ * browser says where a request comes from in `Sec-Fetch-Site` and `Sec-Fetch-Mode`. The proxy turns the app's own
+ * session into the user's token, so a page on another site must not be able to call the backend through it (cross-site
+ * request forgery). A link followed from another site (an email, a chat) is a GET navigation and passes; a request
+ * without these headers (an older browser, a server, a tool) is no browser's cross-site call and passes too.
+ */
+export function isCrossSiteCall(headers, method) {
+    if (headers.get("sec-fetch-site") !== "cross-site")
+        return false;
+    const followedLink = headers.get("sec-fetch-mode") === "navigate" && (method === "GET" || method === "HEAD");
+    return !followedLink;
+}
+/** A path segment the proxy refuses: one that climbs (`.`, `..`, nothing but dots and spaces), or one holding a slash. */
+export function isUnsafeSegment(segment) {
+    return /^[\s.]*$/.test(segment) || /[\\/]/.test(segment);
+}
+/** Reads a body whole, up to `limit` bytes. `null` when it is longer: the rest is not read. */
+export async function readBody(stream, limit) {
+    if (!stream)
+        return new Uint8Array(0);
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > limit) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    const whole = new Uint8Array(size);
+    let at = 0;
+    for (const chunk of chunks) {
+        whole.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return whole;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// Response headers
+/** The backend's response headers that come back to the browser, and the only ones unless an app names more. */
+export const DEFAULT_PROXY_RESPONSE_HEADERS = [
+    "content-type",
+    "content-disposition",
+    "content-language",
+    "content-range",
+    "accept-ranges",
+    "cache-control",
+    "expires",
+    "etag",
+    "last-modified",
+    "vary",
+    "retry-after",
+];
+/** Prefixes that come back too: the Nexus backend's own headers for the client, such as a download's X-Nexus-Export-Rows. */
+const RESPONSE_PREFIXES_KEPT = ["x-nexus-"];
+/**
+ * Response headers that never come back, even when an app names them. They name the backend or its software, point at
+ * it (Location, Link, Refresh), carry its own policies for its own origin, or belong to this hop. CORS headers are here
+ * because on the app's origin they would let another site read a user's data through the proxy, with the user's token.
+ */
+const RESPONSE_HEADERS_NEVER = new Set([
+    "server",
+    "x-sourcefiles",
+    "via",
+    "alt-svc",
+    "strict-transport-security",
+    "report-to",
+    "reporting-endpoints",
+    "nel",
+    "expect-ct",
+    "public-key-pins",
+    "public-key-pins-report-only",
+    "location",
+    "content-location",
+    "link",
+    "refresh",
+    "www-authenticate",
+    "timing-allow-origin",
+    "connection",
+    "keep-alive",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    // `fetch` has already decoded the body, so its encoding and length no longer describe what the browser gets.
+    "content-encoding",
+    "content-length",
+    // Only with `passCookies`, and then read on its own (see below).
+    "set-cookie",
+]);
+/** Prefixes of response headers that never come back: X-AspNet-Version, X-AspNetMvc-Version, X-Powered-By*, CORS, Proxy-*. */
+const RESPONSE_PREFIXES_NEVER = ["x-aspnet", "x-powered-by", "access-control-", "proxy-"];
+/** Whether a response header (its lower-case name) may reach the browser. */
+function mayPass(name, allowed) {
+    if (RESPONSE_HEADERS_NEVER.has(name))
+        return false;
+    if (RESPONSE_PREFIXES_NEVER.some(prefix => name.startsWith(prefix)))
+        return false;
+    return allowed.has(name) || RESPONSE_PREFIXES_KEPT.some(prefix => name.startsWith(prefix));
+}
+/** The backend's response headers the browser may see: the allowlist and the app's own names, never one of the above. */
+export function filterResponseHeaders(answer, rules = {}) {
+    const allowed = new Set([...DEFAULT_PROXY_RESPONSE_HEADERS, ...(rules.extra ?? [])].map(name => name.toLowerCase()));
+    const headers = new Headers();
+    answer.forEach((value, name) => {
+        const lower = name.toLowerCase();
+        if (mayPass(lower, allowed))
+            headers.append(lower, value);
+    });
+    // Several cookies cannot be joined into one line, so they are read one by one.
+    if (rules.passCookies)
+        for (const cookie of answer.getSetCookie())
+            headers.append("set-cookie", cookie);
+    return headers;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// Redirects
+/** The statuses `fetch` follows as redirects. The proxy follows each one itself or refuses it; none reaches the browser. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+export function isRedirect(status) {
+    return REDIRECT_STATUSES.has(status);
+}
+/**
+ * Where a backend's redirect leads, when it stays inside the module: on the root's own origin, or on the root's own
+ * host moved from http to https (a backend's HTTPS redirection, which picks its own https port), and under the root's
+ * path, whose casing may differ ("/App/Api" and "/app/api"). Anything else - another host or port, a move from https
+ * to http, a path outside the root, a URL with a user name in it - is `undefined`, and the proxy refuses it: following
+ * it would carry the user's token somewhere the app never named.
+ *
+ * @example
+ * // The module's root is http://localhost:10040/App/Api, and the proxy asked for .../App/Api/Region/ActiveListing:
+ * redirectInsideModule("https://localhost:10041/App/Api/Region/ActiveListing", asked, root) // followed: the https upgrade
+ * redirectInsideModule("/App/Api/Region/ActiveListing/", asked, root)                       // followed: a trailing slash
+ * redirectInsideModule("https://sso.example.com/login?next=/App/Api", asked, root)          // undefined: another host
+ */
+export function redirectInsideModule(location, from, root) {
+    let target;
+    try {
+        target = new URL(location, from);
+    }
+    catch {
+        return undefined;
+    }
+    if (target.username !== "" || target.password !== "")
+        return undefined;
+    const sameOrigin = target.origin === root.origin;
+    const upgraded = root.protocol === "http:" && target.protocol === "https:" && target.hostname === root.hostname;
+    if (!sameOrigin && !upgraded)
+        return undefined;
+    const base = root.pathname.replace(/\/+$/, "").toLowerCase();
+    const path = target.pathname.toLowerCase();
+    if (base !== "" && path !== base && !path.startsWith(`${base}/`))
+        return undefined;
+    target.hash = "";
+    return target;
+}
+/**
+ * The method of the request after a redirect, as the Fetch standard follows one: a 303 asks for a GET (a HEAD stays a
+ * HEAD), a 301 or 302 turns a POST into a GET, and a 307 or 308 keeps the method and the body.
+ */
+export function methodAfterRedirect(status, method) {
+    if (status === 303 && method !== "GET" && method !== "HEAD")
+        return "GET";
+    if ((status === 301 || status === 302) && method === "POST")
+        return "GET";
+    return method;
+}
+/** Headers that describe a request's body: they go with the body when a redirect turns the request into a GET. */
+export const BODY_HEADERS = ["content-type", "content-language", "content-encoding", "content-location"];
+// ---------------------------------------------------------------------------------------------------------------------
+// Error answers
+/** Top-level keys of a JSON answer that is a stack trace: ASP.NET Core's developer exception page, a serialized exception. */
+const TRACE_KEYS = new Set(["exception", "innerexception", "stacktrace", "stacktracestring", "stack"]);
+/**
+ * Why an error answer cannot reach the browser as it came, or `undefined` when it can. An empty answer passes (there is
+ * nothing in it), and so does JSON - the backend's envelope, or problem details - unless it is a stack trace or repeats
+ * the user's token (a page that lists the request's headers). Anything else (an HTML page, text, XML) is the backend
+ * talking about itself.
+ */
+export function whyHidden(contentType, text, token) {
+    if (text.trim() === "")
+        return undefined;
+    if (token && text.includes(token))
+        return "it repeated the user's token";
+    if (!contentType.toLowerCase().includes("json"))
+        return `it was ${contentType.split(";")[0].trim() || "a body with no type"}, not JSON`;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return "it said it was JSON and was not";
+    }
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        if (Object.keys(parsed).some(key => TRACE_KEYS.has(key.toLowerCase())))
+            return "it was a stack trace";
+    }
+    return undefined;
+}
+/**
+ * A short, one-line piece of an error answer for the server's log: the user's token, styles, scripts and tags taken
+ * out, spaces collapsed.
+ */
+export function logSnippet(text, token, length = 300) {
+    let plain = token ? text.split(token).join("[token]") : text;
+    plain = plain
+        .replace(/<(style|script)\b[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<[^>]*>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return plain.length > length ? `${plain.slice(0, length)}...` : plain;
+}
+/** A URL for the server's log: its origin and path, never its query (it may hold what a user searched for, or a key). */
+export function logUrl(url) {
+    return `${url.origin}${url.pathname}`;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// The proxy's own answers
+/**
+ * The proxy's own refusals: each code is answered from one place in `ApiProxy.ts`, with its HTTP status and its kind
+ * as the Nexus backend numbers kinds (`EErrorCodes`, where a kind's category is its number divided by 20).
+ */
+export const PROXY_REFUSALS = {
+    /** A method other than GET, HEAD, POST, PUT, PATCH and DELETE. RequestInvalid. */
+    METHOD_NOT_ALLOWED: { status: 405, errorCode: 29 },
+    /** A call from a page of another site. AccessDenied. */
+    CROSS_SITE_REFUSED: { status: 403, errorCode: 60 },
+    /** A module the app does not have. RequestInvalid. */
+    MODULE_NOT_FOUND: { status: 404, errorCode: 29 },
+    /** A module the browser calls directly, not through the proxy. RequestInvalid. */
+    MODULE_NOT_PROXIED: { status: 404, errorCode: 29 },
+    /** A path that climbs out of its module. RequestInvalid. */
+    INVALID_PATH: { status: 400, errorCode: 29 },
+    /** A body over the limit. TooLong. */
+    REQUEST_TOO_LARGE: { status: 413, errorCode: 22 },
+    /** A body that could not be read (the client left while sending it). RequestInvalid. */
+    REQUEST_UNREADABLE: { status: 400, errorCode: 29 },
+    /** A module without a usable root URL on this server. SettingMissing. */
+    MODULE_NOT_CONFIGURED: { status: 500, errorCode: 120 },
+    /** A backend that cannot be reached: down, refused, or a certificate this server does not trust. ServiceUnavailable. */
+    BACKEND_UNREACHABLE: { status: 502, errorCode: 160 },
+    /** A backend that did not start answering in time. ServiceTimeout. */
+    BACKEND_TIMEOUT: { status: 504, errorCode: 161 },
+    /** A redirect out of the module, or one with no usable Location. ServiceAnswerInvalid. */
+    BACKEND_REDIRECT_REFUSED: { status: 502, errorCode: 163 },
+    /** More redirects inside the module than the limit. ServiceAnswerInvalid. */
+    BACKEND_REDIRECT_LIMIT: { status: 502, errorCode: 163 },
+    /** An error page that cannot be passed on, answered with the backend's own status. ServiceRefused. */
+    BACKEND_ERROR_PAGE: { status: 502, errorCode: 162 },
+};
+/**
+ * A refusal as the Nexus backend answers one: `{ isSuccess: false, code, errorMessages: [{ message, messageCode,
+ * errorCode }] }`, with the one problem at the top level too, for readers of the older shape.
+ */
+export function nexusFailure(failure) {
+    const { status, message, messageCode, errorCode } = failure;
+    const problem = { message, messageCode, errorCode };
+    return Response.json({ isSuccess: false, code: status, ...problem, errorMessages: [problem] }, { status });
+}
+/**
+ * Every answer the proxy gives: never sniffed into another type, and kept out of every cache unless the backend said
+ * how to cache it - the answer was fetched with the user's token, so a shared cache must never keep it for another user.
+ */
+export function harden(response) {
+    const headers = new Headers(response.headers);
+    headers.set("X-Content-Type-Options", "nosniff");
+    if (!headers.has("cache-control"))
+        headers.set("Cache-Control", "private, no-store");
+    return new Response(response.body, { status: response.status, headers });
+}

package/dist/Services/ExcelApi.d.ts

@@ -43,4 +43,6 @@ export declare function verifyExcelFile(endpoints: ExcelEndpoints, file: File, o
  * they made on screen would be lost. Every check runs again on the way in: what the browser sends is a row, not a
  * decision.
  */
-export declare function importExcelRows(endpoints: ExcelEndpoints, rows: readonly ExcelSheetRow[], options?: ExcelCallOptions): Promise<ApiResult<ExcelImportAnswer>>;
+export declare function importExcelRows(endpoints: ExcelEndpoints, rows: readonly ExcelSheetRow[], options?: ExcelCallOptions & {
+    recordStatus?: number;
+}): Promise<ApiResult<ExcelImportAnswer>>;

package/dist/Services/ExcelApi.js

@@ -104,7 +104,7 @@ export async function verifyExcelFile(endpoints, file, options = {}) {
  */
 export async function importExcelRows(endpoints, rows, options = {}) {
     const backend = getExcelBackend();
-    const answer = await api.post(endpoints.import, backend.importRequest(rows), { ...call(options), count: rows.length, toast: options.toast === false ? false : { success: false } });
+    const answer = await api.post(endpoints.import, backend.importRequest(rows, options.recordStatus), { ...call(options), count: rows.length, toast: options.toast === false ? false : { success: false } });
     // An import that wrote nothing at all is the one failure; it still answers with what it refused, where it says so.
     return { ...answer, result: answer.result === undefined ? undefined : backend.readImport(answer.result) };
 }

package/dist/Services/JoinSources.d.ts

@@ -0,0 +1,48 @@
+import { type CrudBackend } from "../Helpers/CrudBackend.ts";
+import type { ApiEndpoint } from "../Interfaces/ApiInterfaces.ts";
+import type { DropdownPage, DropdownPageRequest, OptionValue } from "../Interfaces/InputInterfaces.ts";
+import type { TableJoinSource, TableJoinedRecord } from "../Interfaces/TableInterfaces.ts";
+/**
+ * A join's source as the table calls it. An endpoint becomes one that POSTs the keys to it as an array and reads the
+ * records it answers - a Nexus controller's `findListing` - made once per endpoint, so every table and picker naming it
+ * shares one source and so one cache. A source of the page's own is used as it is.
+ */
+export declare function joinSource(source: ApiEndpoint | TableJoinSource, backend?: CrudBackend): TableJoinSource;
+/** The controller a picker offers records from: any with an `activeListing` and a `findListing` (`MODULES.controller(...)`). */
+export interface PickerController {
+    activeListing: ApiEndpoint;
+    findListing: ApiEndpoint;
+}
+/** What `crudPicker` needs to know of the records: the field a person reads, and the one under it. */
+export interface CrudPickerOptions {
+    /** The field shown as the option: `"regionName"`. */
+    labelKey: string;
+    /** A field shown under it, such as the parent's name: `"regionName"` under a sub-region. */
+    descriptionKey?: string;
+    /** The field that holds the key. Default `id`. */
+    valueKey?: string;
+    backend?: CrudBackend;
+}
+/** The dropdown params `crudPicker` gives: spread them into a dropdown's input. */
+export interface CrudPickerParams {
+    loadOptions: (request: DropdownPageRequest) => Promise<DropdownPage<TableJoinedRecord>>;
+    resolveOptions: (values: OptionValue[]) => Promise<readonly TableJoinedRecord[]>;
+    valueKey: string;
+    labelKey: string;
+    descriptionKey?: string;
+    isOptionInactive: (item: TableJoinedRecord) => boolean;
+}
+/**
+ * A dropdown of a controller's usable records, for picking a parent in a form: the `activeListing` read once and kept
+ * for every form on the page (the owner's caching rule: a second dropdown, or an Add row, never asks again), searched
+ * and paged in the browser. A value the form already holds that the list does not offer - a parent since trashed - is
+ * found through `findListing`, sharing the calls and answers of the tables' joins, and shows tagged, never offered again.
+ *
+ * @example { type: "dropdown", name: "regionId", label: "Region", required: true, ...crudPicker(REGIONS, { labelKey: "regionName" }) }
+ */
+export declare function crudPicker(controller: PickerController, { labelKey, descriptionKey, valueKey, backend }: CrudPickerOptions): CrudPickerParams;
+/**
+ * Marks what the page looked up from a controller as old, after a write there may have changed it: the records its
+ * `findListing` named, and the list its picker offers. Drawn as they are until the next ask brings the new ones.
+ */
+export declare function expireLookups(controller: Partial<PickerController>): void;

package/dist/Services/JoinSources.js

@@ -0,0 +1,74 @@
+import { isApiEndpoint } from "../Helpers/ApiRoutes.js";
+import { getCrudBackend } from "../Helpers/CrudBackend.js";
+import { filterItems } from "../Helpers/DropdownHelpers.js";
+import { joinSourceName, tableJoins } from "../Helpers/TableJoins.js";
+import { api } from "./BrowserApi.js";
+/*
+ * The browser's half of a join: the call that looks records up, and a picker that shares what it looked up. The cache
+ * itself (`tableJoins`) knows nothing of the API; this is where an endpoint becomes a source it can call.
+ */
+const made = new Map();
+/**
+ * A join's source as the table calls it. An endpoint becomes one that POSTs the keys to it as an array and reads the
+ * records it answers - a Nexus controller's `findListing` - made once per endpoint, so every table and picker naming it
+ * shares one source and so one cache. A source of the page's own is used as it is.
+ */
+export function joinSource(source, backend = getCrudBackend()) {
+    if (!isApiEndpoint(source))
+        return source;
+    const name = joinSourceName(source);
+    let found = made.get(name);
+    if (!found) {
+        found = {
+            name,
+            async load(keys, signal) {
+                const answer = await api.send(source, { body: keys, signal, toast: false });
+                if (!answer.ok)
+                    throw new Error(answer.message ?? "The records could not be looked up.");
+                return backend.readList(answer.result);
+            },
+        };
+        made.set(name, found);
+    }
+    return found;
+}
+/**
+ * A dropdown of a controller's usable records, for picking a parent in a form: the `activeListing` read once and kept
+ * for every form on the page (the owner's caching rule: a second dropdown, or an Add row, never asks again), searched
+ * and paged in the browser. A value the form already holds that the list does not offer - a parent since trashed - is
+ * found through `findListing`, sharing the calls and answers of the tables' joins, and shows tagged, never offered again.
+ *
+ * @example { type: "dropdown", name: "regionId", label: "Region", required: true, ...crudPicker(REGIONS, { labelKey: "regionName" }) }
+ */
+export function crudPicker(controller, { labelKey, descriptionKey, valueKey = "id", backend = getCrudBackend() }) {
+    const listName = joinSourceName(controller.activeListing);
+    // The words a person reads, not the key: a Nexus key is an encrypted token, and a search would find letters in it.
+    const searchKeys = descriptionKey ? [labelKey, descriptionKey] : [labelKey];
+    const loadList = (signal) => api.send(controller.activeListing, { signal, toast: false }).then(answer => {
+        if (!answer.ok)
+            throw new Error(answer.message ?? "The list could not be loaded.");
+        return backend.readList(answer.result);
+    });
+    return {
+        async loadOptions({ search, skip, pageSize }) {
+            const all = await tableJoins.list(listName, loadList);
+            const matches = search ? filterItems(all, search, searchKeys) : all;
+            return { items: matches.slice(skip, skip + pageSize), total: matches.length, hasMore: skip + pageSize < matches.length };
+        },
+        resolveOptions: values => tableJoins.records(joinSource(controller.findListing, backend), values.map(String)),
+        valueKey,
+        labelKey,
+        ...(descriptionKey && { descriptionKey }),
+        isOptionInactive: item => !backend.isPickable(item),
+    };
+}
+/**
+ * Marks what the page looked up from a controller as old, after a write there may have changed it: the records its
+ * `findListing` named, and the list its picker offers. Drawn as they are until the next ask brings the new ones.
+ */
+export function expireLookups(controller) {
+    if (controller.findListing)
+        tableJoins.expire(joinSourceName(controller.findListing));
+    if (controller.activeListing)
+        tableJoins.expireList(joinSourceName(controller.activeListing));
+}

package/dist/Services/ServerApi.d.ts

@@ -11,7 +11,12 @@ export interface ServerApiOptions {
 }
 /** How server calls behave. Where they go (each module's root) is the app's `ApiModules`. */
 export interface ServerApiConfig {
-    /** The app's own address, for relative roots and URLs such as `/api/…`. Default: `URL_CURRENT` from the environment. */
+    /**
+     * The app's own address, for `serverApi`'s relative roots and URLs such as `/api/…`, and for the X-Forwarded-Host and
+     * -Proto the proxy sends. Default: `URL_CURRENT` from the environment. Never a request's Host header as it came: a
+     * client can name any address in it, and `serverApi` would call that address. (The proxy calls a relative root at
+     * this server's own host and port, whatever this says.)
+     */
     origin?: string | (() => string | undefined | Promise<string | undefined>);
     /** The user's token for every call, such as from the session cookie. */
     token?: () => string | null | undefined | Promise<string | null | undefined>;
@@ -35,9 +40,15 @@ export interface ServerApiConfig {
  * configureServerApi({ token: async () => (await cookies()).get("access_token")?.value });
  */
 export declare function configureServerApi(config: ServerApiConfig): void;
+/**
+ * The app's own address, as `configureServerApi({ origin })` or `URL_CURRENT` gives it; `undefined` when neither does.
+ * The proxy tells the backend it in X-Forwarded-Host and X-Forwarded-Proto.
+ */
+export declare function serverAppOrigin(): Promise<string | undefined>;
 /**
  * A module's absolute root URL on the server, from the app's `ApiModules`. Throws "The Reservation API address is not
- * set (API_RESERVATION)." when it is missing. `origin` resolves a relative root, such as the proxy's request origin.
+ * set (API_RESERVATION)." when it is missing. `origin` resolves a relative root (the proxy passes this server's own);
+ * without it, the app's (`serverAppOrigin`).
  */
 export declare function serverModuleRoot(module: ApiModuleValue, origin?: string): Promise<string>;
 /**

package/dist/Services/ServerApi.js

@@ -12,21 +12,26 @@ let settings = {};
 export function configureServerApi(config) {
     settings = { ...settings, ...config };
 }
-async function appOrigin() {
+/**
+ * The app's own address, as `configureServerApi({ origin })` or `URL_CURRENT` gives it; `undefined` when neither does.
+ * The proxy tells the backend it in X-Forwarded-Host and X-Forwarded-Proto.
+ */
+export async function serverAppOrigin() {
     const value = typeof settings.origin === "function" ? await settings.origin() : settings.origin;
     return value || readEnvironment("URL_CURRENT");
 }
 async function absolute(url, fallbackOrigin) {
     if (/^https?:\/\//i.test(url))
         return url;
-    const origin = fallbackOrigin ?? (await appOrigin());
+    const origin = fallbackOrigin ?? (await serverAppOrigin());
     if (!origin)
         throw new Error(`"${url}" is relative, and the app's address is not set (URL_CURRENT).`);
     return new URL(url.startsWith("/") ? url : `/${url}`, origin).toString();
 }
 /**
  * A module's absolute root URL on the server, from the app's `ApiModules`. Throws "The Reservation API address is not
- * set (API_RESERVATION)." when it is missing. `origin` resolves a relative root, such as the proxy's request origin.
+ * set (API_RESERVATION)." when it is missing. `origin` resolves a relative root (the proxy passes this server's own);
+ * without it, the app's (`serverAppOrigin`).
  */
 export async function serverModuleRoot(module, origin) {
     return absolute(await getApiModules().serverUrl(module), origin);