@alxia/react-router 0.10.0 → 0.11.0

package/README.md

@@ -95,7 +95,7 @@ client's files and the app's middlewares. So does React Router's prerendering.
 optional peer, for `/vite`; `react` 19 is an optional peer, for `/pwa/react`. The six `workbox-*`
 packages (`workbox-core`, `workbox-expiration`, `workbox-navigation-preload`,
 `workbox-precaching`, `workbox-routing`, `workbox-strategies`) are optional
-peers too, for `/pwa/worker` (the [PWA section](#installable-and-offline-pwa) has the install line). The package declares no dependency.
+peers too, for `/pwa/worker` (the [PWA section](#installable-and-offline-pwa) has the install line). `/errors` imports `react-router`, a required peer that is already installed. The package declares no dependency.
 
 Its `typescript` peer is 6 or 7. The template's TypeScript 5.9 typechecks,
 but `bun add` warns about it; `bun add -d typescript@^6` silences the
@@ -621,6 +621,155 @@ The [PWA guide](https://github.com/softistx/alxia/blob/develop/packages/react-ro
 has the worker's options, the offline page, the manifest route, the update
 banner and the rest.
 
+## An API's refusals, worded for the page
+
+`@alxia/react-router/errors` has no UI; its one runtime import is `react-router`, never `@alxia/core`. It
+holds the shape of a GraphQL API's refusal, declared structurally (no `@nxgt/graphql-client` at
+runtime), the request id an API echoes, the page a request is for, the
+catalogue of the API's messages an app keeps, the words of a form's checks,
+the provider that fills the catalogue in the browser, the wording of a refusal, the loaders and actions that answer with it, the JSON actions (CSRF check) with their fetcher hook, and what a failed call to the API becomes (`apiCallFailure`):
+
+```ts
+import { isApiErrorLike, nextOf, requestIdOf } from '@alxia/react-router/errors';
+
+export function describe(error: unknown, request: Request) {
+	return isApiErrorLike(error)
+		? { code: error.code, status: error.status, next: nextOf(request.url) }
+		: undefined;
+}
+
+export const idOf = (response: Response) => requestIdOf(response);
+```
+
+The catalogue is an instance made with the app's ICU formatter. A form's checks
+read it through `apiCodeResolver`, and the provider fills it from the root's data:
+
+```ts
+import {
+	ApiMessagesProvider,
+	apiCodeResolver,
+	createApiMessages,
+} from '@alxia/react-router/errors';
+
+type Language = 'en' | 'fr';
+
+export const apiMessages = createApiMessages<Language>({
+	format: (message) => message, // the app's ICU formatter goes here
+});
+
+export const resolver = apiCodeResolver(apiMessages, {
+	translate: (key) => key,
+	language: () => 'en',
+});
+
+// In the root: <ApiMessagesProvider messages={apiMessages} value={data.catalogue}>…
+export const provider = ApiMessagesProvider({
+	messages: apiMessages,
+	value: { en: {}, fr: {} },
+	children: null,
+});
+```
+
+A failed call is worded in the page's language by `createApiErrors`:
+
+```ts
+import { createApiErrors } from '@alxia/react-router/errors';
+import { apiMessages } from './api-messages';
+
+export const apiErrors = createApiErrors<'en' | 'fr'>({
+	messages: apiMessages,
+	unavailable: (language) => (language === 'en' ? 'Unavailable' : 'Indisponible'),
+});
+
+// In an action's catch: { message, status }, or undefined (rethrow it).
+export const refusal = (error: unknown) => apiErrors.apiRefusal(error, 'en');
+```
+
+A loader throws the API's error as a route error, with the call's request id
+for the error page; an action answers a refusal as data:
+
+```ts
+import { errorRequestId, routeError } from '@alxia/react-router/errors';
+import { apiErrors } from './api-errors';
+
+// In a loader's catch: a 401, 403, 404 or 503 ApiError becomes a route error.
+export const thrown = (error: unknown) => routeError(error);
+
+// In the root's ErrorBoundary: the reference the user can quote.
+export const reference = (error: unknown) => errorRequestId(error);
+
+// A fetcher's action: { ok: true, …value }, or { ok: false, error } with a status.
+export const rename = (run: () => Promise<{ title: string }>) =>
+	apiErrors.fetcherResult('en', { intent: 'rename' }, run);
+
+// A form's action: { ok: true, value }, or the form's errors with a status.
+export const create = (run: () => Promise<{ id: string }>) =>
+	apiErrors.submitForm('en', run, (path) =>
+		path === 'todo.title' ? 'title' : undefined,
+	);
+```
+
+JSON actions refuse a post from another site, and read a Standard Schema's input:
+
+```ts
+import { jsonActions, useJsonFetcher } from '@alxia/react-router/errors';
+import { z } from 'zod';
+
+// Behind a TLS proxy named with createServer({ proxy }), nothing to set; else: origin: () => process.env.APP_ORIGIN
+export const { readInput } = jsonActions();
+
+const schema = z.object({ title: z.string().min(1) });
+
+export async function action({ request }: { request: Request }) {
+	return readInput(request, schema); // 400 when the input is refused
+}
+
+// In the component: const { post, busy } = useJsonFetcher<typeof action>();
+```
+
+A call that failed is turned into what a loader throws, and logged with the API's request id, by `apiCallFailure(error, { api, operation: operationName(document), requestId })`
+(your own `execute` calls it in its `catch`):
+
+```ts
+import { apiCallFailure, operationName } from '@alxia/react-router/errors';
+import type { DocumentNode } from 'graphql';
+
+export function failed(error: unknown, document: DocumentNode, requestId?: string, signal?: AbortSignal) {
+	return apiCallFailure(error, { api: 'my-api', operation: operationName(document), requestId, signal });
+}
+// In execute(): catch (error) { throw failed(error, document, requestId, signal); }
+```
+
+The API's catalogue is read and kept fresh by `createErrorCatalogue`; the root's
+middleware awaits `freshAll()`, its loader returns `clientMessages()` and
+`server.ts` calls `warm()`:
+
+```ts
+import { createErrorCatalogue } from '@alxia/react-router/errors';
+import { apiMessages } from './api-messages';
+
+export const catalogue = createErrorCatalogue<'en' | 'fr'>({
+	messages: apiMessages,
+	languages: ['en', 'fr'],
+	read: async (language) => fetchCatalogue(language), // { version, messages }
+	versions: async () => fetchVersions(), // { en: '…', fr: '…' }
+	ttlMs: () => Number(process.env.CATALOGUE_TTL_MS ?? 60_000),
+	clientCodes: ['validation.errors.required'],
+});
+
+declare function fetchCatalogue(
+	language: string,
+): Promise<{ version: string; messages: { code: string; message: string; params: { name: string; kind: 'TEXT' }[] }[] }>;
+declare function fetchVersions(): Promise<{ en: string; fr: string }>;
+
+// The root's middleware: await catalogue.freshAll();
+// The root's loader: return { messages: catalogue.clientMessages() };
+// server.ts, at startup: catalogue.warm();
+```
+
+The [errors guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/errors.md)
+has the rest.
+
 ## Traps
 
 - **A context key made in `app/` reaches the loaders only through the
@@ -736,6 +885,31 @@ From `@alxia/react-router/pwa/build` (Bun; Node's built-ins its only imports):
 | `BuildWorkerOptions` | `file` (required), `root`, `client`, `contract`, `offline`, `precacheAssets`, `minify` |
 | `WorkerBuild` | `{ file, precache, precacheBytes, bytes }` |
 
+From `@alxia/react-router/errors` (`react-router` is its only package import, and never `@alxia/core`):
+
+| export | |
+| --- | --- |
+| `isApiErrorLike(error)` | whether `error` is an `@nxgt/graphql-client` `ApiError`, like the client's `isApiError`, plus a numeric `status`, which `ApiErrorLike` promises; it holds across two copies of the client |
+| `ApiErrorLike`, `ApiErrorEntryLike`, `ApiErrorExtensionsLike`, `ApiErrorParamsLike`, `ApiFieldErrorLike` | the shape of the refusal: `errors`, `code`, `status`, `requestId?`, and each error's `extensions` (`code`, `params`, `fields`, `field`, `minutes`, `retryAfter`) |
+| `waitMinutes(extensions)` | the minutes of a throttle's wait: `minutes` (at least one), else `retryAfter` rounded up |
+| `REQUEST_ID_HEADER`, `requestIdOf(response)` | `x-request-id`, and the id a response carries, if the API sent one |
+| `nextOf(url)` | the path and search of the page a request is for, without React Router's `.data`, `/_.data`, `_routes` and empty `index`; it never starts with two slashes, but an app still validates `next` before redirecting to it |
+| `FormErrors` | what a form action answers when the API refused the input: `fieldErrors` by field and a `formError` (`undefined` when every message sits under a field), already translated; `submitForm` answers it |
+| `routeError(error, { statuses? }?)`, `RouteErrorOptions` | what a loader throws for the API's error: an `ApiError` of 401, 403, 404 or 503, or such a `Response` carrying a request id, becomes a route error of that status with the `code`, `message` and `requestId`; any other `ApiError` with an id becomes a 500 carrying the id; anything else is returned as it is |
+| `errorRequestId(error)`, `RouteErrorData` | the support reference an error page shows: the `requestId` a route error carries, else `undefined`; `RouteErrorData` is the data `routeError` carries (`code?`, `message?`, `requestId?`) |
+| `createApiMessages({ format })`, `ApiMessages`, `ApiMessagesOptions` | the catalogue store of an app, an instance (`set`, `add`, `clear` (for tests), `messageOf`, `format`, `apiMessage(code, values, language)`); `format` is the app's ICU formatter, such as `@nxgt/material`'s `formatMessage` |
+| `CatalogueMessage`, `CatalogueMessages`, `ParamKind`, `MessageFormat`, `MessageValues` | one API message with the kind of each argument (`TEXT`, `NUMBER`, `DATE`, `PLURAL`, `SELECT`), a language's messages by code, and the formatter's type |
+| `apiCodeResolver(messages, { translate, language, codeOf?, isApiCode? })`, `ApiCodeResolver`, `ApiCodeResolverOptions`, `CodeIssueLike` | the `{ translate, codeOf }` a form's `useCodeResolver(schema, resolver)` takes: a check's API code is worded as the API words it, any other key by the app's translator; `CodeIssueLike` is the issue a custom `codeOf` receives |
+| `ApiMessagesProvider({ messages, value, children })`, `ApiMessagesProviderProps` | `messages` is the store and `value` the root loader's data; fills the store in the browser from the root's data before the children render; a server render writes nothing. A function with no JSX, so no React import |
+| `createApiErrors({ messages, unavailable, refused?, byCode?, isApiCode? })`, `ApiErrors`, `ApiErrorsOptions` | what a page says of a refusal, in a language: `apiErrorMessage(error, language)` (the catalogue's text of the code, else the API's message; `refused` replaces it for an error with no API code and `byCode` words given codes, such as a query's limits), `fieldErrors(error, language)` by input path, `translateCode(code, fallback, language, values?)`, `unavailableMessage(language)` and `apiRefusal(error, language)`; for an action, `fetcherResult(language, about, run, route?)` (`{ ok: true, …about, …value }`, or `{ ok: false, …about, error }` with the refusal's status), `fetcherRefusal(error, language, route?)` (the refusal, or the thrown route error) and `submitForm(language, run, fieldOf, route?)` (`{ ok: true, value }`, or a `FormErrors` with the refusal's status); `route` is the `RouteErrorOptions` of the `routeError` they throw through |
+| `apiCallFailure(error, { api, operation?, requestId?, signal?, passedThrough?, log? })`, `CallFailureOptions` | what a failed call to the API becomes, for a loader or an action to throw, logged with the request id: an `ApiError` as it is (with `requestId`), a `Response` of its own status for a 401, 403 or 404 without a GraphQL body, a 503 `Response` with no body for an unreachable, slow, garbled or aborted call (the reason is in the log), any other error as it is; the log lines start with `api`, and a `log` that throws never replaces the outcome. It recognises `@nxgt/graphql-client`'s errors by `name`, not `instanceof` |
+| `operationName(document)`, `DocumentLike` | the name of the operation a document holds, for the log (else `query`, `mutation` or `subscription`); a structural `{ definitions }`, so `graphql`'s `DocumentNode` fits |
+| `createErrorCatalogue({ messages, languages, read, versions, ttlMs, clientCodes, retryMs?, firstReadWaitMs?, log? })`, `ErrorCatalogue`, `ErrorCatalogueOptions`, `CatalogueReply` | keeps the API's error catalogue in the store: `fresh(language, now?)` and `freshAll(now?)` (a cold language is awaited for `firstReadWaitMs`, 1500 by default, and read once however many requests ask; a held one is served, and its version checked in the background once per `ttlMs`, a number or a getter; only a language whose version moved is read again; a failure is retried after `retryMs`, 5000 by default), `warm()` for startup, `clientMessages()` (the `clientCodes` the browser words itself, by language, for the root's loader), and, for tests, `reset()`, `heldVersion(language)`, `settled()` and the `now` parameters. `read` and `versions` are the app's calls to its API |
+| `ApiRefusal` | `{ message, status }`: a failed call as a page says it; what `apiRefusal` returns for an API refusal (its status) or an unreachable API (503), else `undefined` |
+| `jsonActions({ origin? })`, `JsonActions`, `JsonActionsOptions` | the JSON helpers of the actions, bound to the app's origin (a string, or a getter read at each request; the request's own by default): `readJson(request)` (403 `Cross-site request refused` for another origin or a cross-site fetch, 415 `Expected a JSON body`, 400 `Malformed JSON body`), `requireJsonPost(request)` (a native post goes back to its page) and `readInput(request, schema)` (the body's `input` through a Standard Schema, async allowed; 400 `The form sent an input the API would refuse`) |
+| `useJsonFetcher(key?, action?)`, `JsonBody` | a fetcher that posts JSON: `{ fetcher, post(body, to?), busy }`; `to` is the action of one call |
+| `StandardSchemaV1` | the Standard Schema v1 type `readInput` takes, declared in `/errors` (type only, so no `@alxia/core`; `readInput`'s output is inferred from the schema's `~standard.types`); a Zod 4, Valibot or ArkType schema fits |
+
 The `alxia-react-router` bin, run with `bunx`:
 
 | command | |
@@ -751,6 +925,7 @@ The `alxia-react-router` bin, run with `bunx`:
 - [Typing the loaders](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/typing-the-loaders.md): `Register`, and the app's own context keys.
 - [A CSP nonce](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/csp-nonce.md), [Beside the pages](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/beside-the-pages.md) (middlewares, routes, WebSockets, the client's files), [OpenAPI](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/openapi.md), [Testing](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/testing.md) and [Deploying](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/deploying.md), with Docker.
 - [Installable and offline](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/pwa.md): what the subpaths hold, the worker's contract, the worker, what it caches, the offline page, building the worker with `alxia()` or `buildWorker`, the hooks in React, registering the worker and offering an update, serving the worker's script, the web app manifest, and clearing at sign-out.
+- [An API's refusals](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide/errors.md): what `/errors` holds, recognising an API error, the request id, the page a request is for, the catalogue store, the form checks in the API's words, the provider, wording a refusal, loaders and the error page, actions, JSON actions and CSRF, and keeping the catalogue fresh.
 - [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/troubleshooting.md): each message, and the traps that print none.
 - [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/roadmap.md): what is coming, and what is not planned.
 - [Example](https://github.com/softistx/alxia/tree/develop/examples/react-router): the official template, these four changes, then an `app/server.ts` with a session, an `/api`, secure headers with a nonce and a streamed page.

package/dist/errors/api-error.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The shape of an API's refusal, as `@nxgt/graphql-client`'s `ApiError`
+ * carries it, declared structurally: `/errors` never imports the client, so
+ * an app needs it only if it calls the API through it. `api-error.spec.ts`
+ * holds the two in step.
+ */
+/** One refused input field: `extensions.fields` of a validation refusal. */
+export interface ApiFieldErrorLike {
+    readonly path: string;
+    readonly code: string;
+    readonly message: string;
+    /** The values the field's message interpolates. */
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+/** The values a message interpolates; a throttle's wait is `minutes` or `retryAfter`. */
+export interface ApiErrorParamsLike {
+    readonly minutes?: unknown;
+    readonly retryAfter?: unknown;
+    readonly [key: string]: unknown;
+}
+/**
+ * One GraphQL error's `extensions`. `code` is the API's own
+ * `<module>.errors.<slug>`; the rest is what its messages name.
+ */
+export interface ApiErrorExtensionsLike {
+    readonly code?: string;
+    /** The values the message interpolates, when the API sends them. */
+    readonly params?: ApiErrorParamsLike;
+    /** A validation refusal: every field at fault, by input path. */
+    readonly fields?: readonly ApiFieldErrorLike[];
+    /** Any other refusal about one input field, by its path. */
+    readonly field?: string;
+    /** A throttle's wait, in minutes (`waitMinutes` coerces a string). */
+    readonly minutes?: unknown;
+    /** A throttle's wait, in seconds. */
+    readonly retryAfter?: unknown;
+    readonly [key: string]: unknown;
+}
+/** One error of a response's `errors`. */
+export interface ApiErrorEntryLike {
+    readonly message: string;
+    readonly extensions?: ApiErrorExtensionsLike;
+}
+/** A refusal read from a GraphQL API: what `ApiError` has, and the request id. */
+export interface ApiErrorLike extends Error {
+    readonly errors: readonly ApiErrorEntryLike[];
+    /** The first error's `extensions.code`. */
+    readonly code: string | undefined;
+    /** The HTTP status to answer with. */
+    readonly status: number;
+    /** The id the API logged the request under, when the caller kept it. */
+    readonly requestId?: string;
+}
+/** Whether `error` is an `Error` of this `name`: the client's errors are told by it, never `instanceof`. */
+export declare const isNamed: (error: unknown, name: string) => error is Error;
+/**
+ * Whether `error` is an `ApiError` of `@nxgt/graphql-client`, by the test
+ * that client's `isApiError` makes (an `Error` named `ApiError` with an
+ * `errors` array), plus a numeric `status`, which `ApiErrorLike` promises.
+ * It holds across two copies of the client.
+ */
+export declare function isApiErrorLike(error: unknown): error is ApiErrorLike;
+/**
+ * The minutes a wait lasts, as the API words it: `minutes` (at least one, in
+ * `extensions.params` or beside it), else the `retryAfter` seconds rounded
+ * up, else one.
+ */
+export declare function waitMinutes(extensions: ApiErrorExtensionsLike | undefined): number;
+/**
+ * The values a message names: `extensions.params` over the extensions
+ * themselves, where older errors and the extras of a few sit.
+ */
+export declare function valuesOf(extensions: ApiErrorExtensionsLike | undefined): Record<string, unknown> | undefined;
+/** `@nxgt/graphql-client`'s `ApiStatusError`, as far as the failure reads it. */
+export interface StatusErrorLike extends Error {
+    status: number;
+    statusText?: string | undefined;
+    body?: unknown;
+}
+/** `@nxgt/graphql-client`'s `ApiUnavailableError`, as far as the failure reads it. */
+export interface UnavailableErrorLike extends Error {
+    reason: string;
+}
+export declare const isStatusError: (error: unknown) => error is StatusErrorLike;
+export declare const isUnavailableError: (error: unknown) => error is UnavailableErrorLike;
+//# sourceMappingURL=api-error.d.ts.map

package/dist/errors/api-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../src/errors/api-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD;AAED,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;IACrC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,sBAAsB,CAAC;CAC7C;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAa,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,4GAA4G;AAC5G,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,EAAE,MAAM,MAAM,KAAG,KAAK,IAAI,KAClB,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,UAAU,EAAE,sBAAsB,GAAG,SAAS,GAC5C,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACvB,UAAU,EAAE,sBAAsB,GAAG,SAAS,GAC5C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAKrC;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAgB,SAAQ,KAAK;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,sFAAsF;AACtF,MAAM,WAAW,oBAAqB,SAAQ,KAAK;IAClD,MAAM,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAEG,CAAC;AAE5D,eAAO,MAAM,kBAAkB,GAC9B,OAAO,OAAO,KACZ,KAAK,IAAI,oBAE+C,CAAC"}

package/dist/errors/api-errors.d.ts

@@ -0,0 +1,96 @@
+import type { data } from 'react-router';
+import type { ApiErrorLike } from './api-error';
+import type { FormErrors } from './form-errors';
+import type { ApiMessages } from './messages';
+import type { RouteErrorOptions } from './route-error';
+/** A refused call, as a page says it: the message, and the HTTP status to answer. */
+export type ApiRefusal = {
+    message: string;
+    status: number;
+};
+export interface ApiErrorsOptions<L extends string> {
+    /** The catalogue the API's codes are worded from. */
+    messages: ApiMessages<L>;
+    /**
+     * The app's own word for an API it cannot reach (a 503 `Response`): not
+     * an API error, so never one of the catalogue's codes.
+     */
+    unavailable(language: L): string;
+    /**
+     * The app's generic refusal, said for an error with no API code (a raw
+     * `BAD_USER_INPUT` before the API's validation layer), never the raw
+     * message. Without it, such an error says the message the API sent.
+     */
+    refused?(language: L): string;
+    /**
+     * An app's own wording for given codes, such as the API's request limits
+     * (depth, cost, introspection), whose params differ and name no field.
+     * Checked after `refused`, before the catalogue.
+     */
+    byCode?: Readonly<Record<string, (error: ApiErrorLike, language: L) => string>>;
+    /** Whether a code is an API code; `<module>.errors.<slug>` by default. */
+    isApiCode?(code: string): boolean;
+}
+/** What a page says of an API's refusals, in a language. */
+export interface ApiErrors<L extends string> {
+    /**
+     * The catalogue's text of an API code in `language`, else `fallback` (the
+     * message the API already worded). `values` are the message's arguments
+     * (`extensions.params`).
+     */
+    translateCode(code: string | undefined, fallback: string, language: L, values?: Readonly<Record<string, unknown>>): string;
+    /**
+     * What to show for an API error: `refused` for an error with no API code,
+     * when given; else `byCode`'s wording of its code; else the catalogue's
+     * text; else the message the API already worded.
+     */
+    apiErrorMessage(error: ApiErrorLike, language: L): string;
+    /**
+     * The message of each refused field, by input path, ready for a form: the
+     * entries of `extensions.fields`, else the one field `extensions.field`
+     * names, with the error's own message. Empty for neither.
+     */
+    fieldErrors(error: ApiErrorLike, language: L): Record<string, string>;
+    /** `unavailable`, in `language`. */
+    unavailableMessage(language: L): string;
+    /**
+     * What a failed call says to the user: an API refusal's message and its
+     * status, or an API it cannot reach (a 503 `Response`: the unavailable
+     * word). Undefined for anything else, which the caller rethrows.
+     */
+    apiRefusal(error: unknown, language: L): ApiRefusal | undefined;
+    /**
+     * A fetcher's refusal: `apiRefusal`'s, so the page stays where it was. A
+     * 401 (the session caller redirects first) or any other failure is
+     * thrown, through `routeError`, for the error page.
+     */
+    fetcherRefusal(error: unknown, language: L, route?: RouteErrorOptions): ApiRefusal;
+    /**
+     * Runs the mutation of an action a fetcher posted to: `{ ok: true }` with
+     * `about` and the mutation's value, or `{ ok: false, error }` with `about`
+     * and the refusal's message, answered with its HTTP status.
+     */
+    fetcherResult<About extends object, Value extends object = Record<never, never>>(language: L, about: About, run: () => Promise<Value>, route?: RouteErrorOptions): Promise<({
+        ok: true;
+    } & About & Value) | ReturnType<typeof data<{
+        ok: false;
+        error: string;
+    } & About>>>;
+    /**
+     * Runs a form's mutation: `{ ok: true, value }`, or the form's errors
+     * (`fieldErrors` under the form field `fieldOf` names an input path by,
+     * and a `formError` for the rest) with the refusal's status. A 404 about
+     * none of the form's fields, a 401 and other failures are thrown for the
+     * error page, through `routeError` (with `route`).
+     */
+    submitForm<T>(language: L, run: () => Promise<T>, fieldOf: (path: string) => string | undefined, route?: RouteErrorOptions): Promise<{
+        ok: true;
+        value: T;
+    } | ReturnType<typeof data<FormErrors>>>;
+}
+/**
+ * The wording of an API's refusals for the languages `L`, from the
+ * catalogue `messages` holds. Make one per app, beside its `createApiMessages`.
+ */
+export declare function createApiErrors<L extends string>(options: ApiErrorsOptions<L>): ApiErrors<L>;
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/errors/api-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-errors.d.ts","sourceRoot":"","sources":["../../src/errors/api-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,qFAAqF;AACrF,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM;IACjD,qDAAqD;IACrD,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC;IAC9B;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAChB,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,MAAM,CAAC,CAC5D,CAAC;IACF,0EAA0E;IAC1E,SAAS,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM;IAC1C;;;;OAIG;IACH,aAAa,CACZ,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,CAAC,EACX,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAAC;IACV;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC;IAC1D;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtE,oCAAoC;IACpC,kBAAkB,CAAC,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,UAAU,GAAG,SAAS,CAAC;IAChE;;;;OAIG;IACH,cAAc,CACb,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,EACX,KAAK,CAAC,EAAE,iBAAiB,GACvB,UAAU,CAAC;IACd;;;;OAIG;IACH,aAAa,CACZ,KAAK,SAAS,MAAM,EACpB,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE3C,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,EACzB,KAAK,CAAC,EAAE,iBAAiB,GACvB,OAAO,CACP,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,KAAK,GAAG,KAAK,CAAC,GAC9B,UAAU,CAAC,OAAO,IAAI,CAAC;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC,CAAC,CAC/D,CAAC;IACF;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,EACX,QAAQ,EAAE,CAAC,EACX,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CACzE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC/C,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC1B,SAAS,CAAC,CAAC,CAAC,CAEd"}

package/dist/errors/call-failure.d.ts

@@ -0,0 +1,45 @@
+export interface CallFailureOptions {
+    /** What a log line names the API by, such as `my-api https://api.example.com/graphql`. */
+    api: string;
+    /** The operation's name, for the log (`operationName(document)`). */
+    operation?: string;
+    /** The `x-request-id` the API answered, when it did (`requestIdOf(response)`). */
+    requestId?: string;
+    /** The incoming request's signal: an aborted call is answered 503. */
+    signal?: AbortSignal;
+    /** The statuses without a GraphQL body that become a `Response` of their own; 401, 403 and 404 by default. */
+    passedThrough?: ReadonlySet<number>;
+    /** Where the lines go; `console` by default. */
+    log?: Pick<Console, 'warn' | 'error'>;
+}
+/**
+ * What a call became once it failed, for a loader or an action to throw: the
+ * `ApiError` as it is (carrying `requestId`), a `Response` of the API's own
+ * status for a 401, 403 or 404 without a GraphQL body, a 503 `Response` (with no body; the reason is in the log) for an
+ * unreachable, slow, garbled or aborted API, and any other error as it is.
+ * Every case it recognises is logged with the request id, when the API gave one, and never
+ * the headers, the variables nor a token; the id rides on the `ApiError` as
+ * `requestId` and on a `Response` as `x-request-id`, where `routeError` reads
+ * it.
+ *
+ * It recognises `@nxgt/graphql-client`'s errors by their `name`, never with
+ * `instanceof`, so it needs no import of the client and holds across two
+ * copies of it.
+ */
+export declare function apiCallFailure(error: unknown, { api, operation, requestId, signal, passedThrough, log: appLog, }: CallFailureOptions): unknown;
+/** A document, as far as `operationName` reads it: `graphql`'s `DocumentNode` fits. */
+export interface DocumentLike {
+    readonly definitions: readonly {
+        readonly kind: string;
+        readonly operation?: string | undefined;
+        readonly name?: {
+            readonly value: string;
+        } | undefined;
+    }[];
+}
+/**
+ * The name of the operation a document holds, for a log line: its name, else
+ * its kind (`query`, `mutation`, `subscription`), else `operation`.
+ */
+export declare function operationName(document: DocumentLike): string;
+//# sourceMappingURL=call-failure.d.ts.map

package/dist/errors/call-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-failure.d.ts","sourceRoot":"","sources":["../../src/errors/call-failure.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,kBAAkB;IAClC,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8GAA8G;IAC9G,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,gDAAgD;IAChD,GAAG,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,OAAO,EACd,EACC,GAAG,EACH,SAAuB,EACvB,SAAS,EACT,MAAM,EACN,aAA8B,EAC9B,GAAG,EAAE,MAAgB,GACrB,EAAE,kBAAkB,GACnB,OAAO,CAyCT;AAED,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS;QAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACxC,QAAQ,CAAC,IAAI,CAAC,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC;KACvD,EAAE,CAAC;CACJ;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAO5D"}

package/dist/errors/catalogue-check.d.ts

@@ -0,0 +1,24 @@
+import type { Held } from './catalogue-read';
+/** What the TTL check needs: the reader's state and the app's own calls. */
+export interface CheckContext<L extends string> {
+    reader: {
+        held: Map<L, Held>;
+        load(language: L, now: number): Promise<void>;
+    };
+    versions(): Promise<Partial<Record<L, string>>>;
+    ttl(): number;
+    retryMs: number;
+    log: Pick<Console, 'error'>;
+}
+/**
+ * Asks the versions in one call and reads again the messages of each
+ * language that moved. An API that cannot be reached keeps the messages
+ * held (stale, still worded) and is asked again after `retryMs`.
+ */
+export declare function checkVersions<L extends string>({ reader, versions, ttl, retryMs, log }: CheckContext<L>, now: number): Promise<void>;
+/**
+ * The TTL, whose getter is the app's: one that throws, or that is not a
+ * finite number of at least 0, is logged and `fallback` is used.
+ */
+export declare function safeTtl(ttlMs: number | (() => number), fallback: number, log: Pick<Console, 'error'>): () => number;
+//# sourceMappingURL=catalogue-check.d.ts.map

package/dist/errors/catalogue-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue-check.d.ts","sourceRoot":"","sources":["../../src/errors/catalogue-check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,4EAA4E;AAC5E,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM;IAC7C,MAAM,EAAE;QACP,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACnB,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9C,CAAC;IACF,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAChD,GAAG,IAAI,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,EACnD,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC,EACxD,GAAG,EAAE,MAAM,iBAoBX;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACtB,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,gBAc3B"}

package/dist/errors/catalogue-read.d.ts

@@ -0,0 +1,33 @@
+import type { ApiMessages, CatalogueMessage } from './messages';
+/** What the API answers for one language: its version and every message. */
+export type CatalogueReply = {
+    version: string;
+    messages: ReadonlyArray<CatalogueMessage & {
+        readonly code: string;
+    }>;
+};
+/** A language's catalogue as held, and when its version was last confirmed. */
+export type Held = {
+    version: string;
+    checkedAt: number;
+};
+export interface CatalogueReaderOptions<L extends string> {
+    messages: ApiMessages<L>;
+    read(language: L): Promise<CatalogueReply>;
+    retryMs: number;
+    firstReadWaitMs: number;
+    log: Pick<Console, 'error'>;
+}
+/**
+ * The reading half of the catalogue: the first read of each language (one in
+ * flight, a bounded wait, a retry delay after a failure) and the version
+ * each one holds. `createErrorCatalogue` adds the TTL check on top.
+ */
+export declare function createCatalogueReader<L extends string>({ messages, read, retryMs, firstReadWaitMs, log, }: CatalogueReaderOptions<L>): {
+    held: Map<L, Held>;
+    load: (language: L, now: number) => Promise<void>;
+    /** Reads a language that is not held yet, unless a failure is still fresh. */
+    first(language: L, now: number): Promise<void>;
+    reset(): void;
+};
+//# sourceMappingURL=catalogue-read.d.ts.map

package/dist/errors/catalogue-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue-read.d.ts","sourceRoot":"","sources":["../../src/errors/catalogue-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhE,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC,gBAAgB,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,MAAM;IACvD,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CAC5B;AAqBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,EACvD,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,eAAe,EACf,GAAG,GACH,EAAE,sBAAsB,CAAC,CAAC,CAAC;;qBAMG,CAAC,OAAO,MAAM;IAwC3C,8EAA8E;oBACxD,CAAC,OAAO,MAAM;;EAYrC"}

package/dist/errors/catalogue.d.ts

@@ -0,0 +1,59 @@
+import { type CatalogueReply } from './catalogue-read';
+import type { ApiMessages, CatalogueMessages } from './messages';
+export type { CatalogueReply } from './catalogue-read';
+export interface ErrorCatalogueOptions<L extends string> {
+    /** The store the page words refusals from (`createApiMessages`). */
+    messages: ApiMessages<L>;
+    /** The languages to hold, each read once and kept fresh. */
+    languages: readonly L[];
+    /** Reads one language's catalogue from the API. */
+    read(language: L): Promise<CatalogueReply>;
+    /** Asks the API for the version of every language, in one call. */
+    versions(): Promise<Partial<Record<L, string>>>;
+    /** How long a held catalogue is served before its version is checked. */
+    ttlMs: number | (() => number);
+    /** How soon a check or a first read that failed is tried again. Default 5000. */
+    retryMs?: number;
+    /**
+     * How long a request waits for a language's first read; past it the
+     * request goes on and the read carries on in the background. Default 1500.
+     */
+    firstReadWaitMs?: number;
+    /** The codes the browser words itself (`clientMessages`). */
+    clientCodes: readonly string[];
+    /** Where failures are reported. Default `console`. */
+    log?: Pick<Console, 'error'>;
+}
+/** The API's error catalogue, kept fresh for the server. */
+export interface ErrorCatalogue<L extends string> {
+    /**
+     * The catalogue of `language`, ready to word a refusal. Only a language
+     * with no catalogue yet is awaited, for at most `firstReadWaitMs`. A held
+     * one is served as it is, and once older than the TTL its version is
+     * checked in the background, one check at a time.
+     */
+    fresh(language: L, now?: number): Promise<void>;
+    /** Every language, fresh: what the root middleware awaits. */
+    freshAll(now?: number): Promise<void>;
+    /** At startup: reads every language without holding the boot back. */
+    warm(): void;
+    /** The messages the browser words itself, by language, for the root's loader. */
+    clientMessages(): Record<L, CatalogueMessages>;
+    /**
+     * Forgets everything held and in flight. For use between tests, with
+     * nothing in flight: a read or check still running when it is called
+     * finishes and holds its result again.
+     */
+    reset(): void;
+    /** The version held for a language, if any. */
+    heldVersion(language: L): string | undefined;
+    /** Waits for the check in flight, if any (tests). */
+    settled(): Promise<void>;
+}
+/**
+ * Keeps the API's error catalogue in `messages`: read on first use, checked
+ * against the API's versions once per TTL, and re-read only for the
+ * languages whose version moved. It is an instance, not module state.
+ */
+export declare function createErrorCatalogue<L extends string>({ messages, languages, read, versions, ttlMs, retryMs, firstReadWaitMs, clientCodes, log: appLog, }: ErrorCatalogueOptions<L>): ErrorCatalogue<L>;
+//# sourceMappingURL=catalogue.d.ts.map

package/dist/errors/catalogue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.d.ts","sourceRoot":"","sources":["../../src/errors/catalogue.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,kBAAkB,CAAC;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEjE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,MAAM;IACtD,oEAAoE;IACpE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB,4DAA4D;IAC5D,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;IACxB,mDAAmD;IACnD,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,mEAAmE;IACnE,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAChD,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IAC/B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,sDAAsD;IACtD,GAAG,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CAC7B;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM;IAC/C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,sEAAsE;IACtE,IAAI,IAAI,IAAI,CAAC;IACb,iFAAiF;IACjF,cAAc,IAAI,MAAM,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC/C;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;IACd,+CAA+C;IAC/C,WAAW,CAAC,QAAQ,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,qDAAqD;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAqBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,EACtD,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,OAAe,EACf,eAAuB,EACvB,WAAW,EACX,GAAG,EAAE,MAAgB,GACrB,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAoD9C"}

package/dist/errors/code-resolver.d.ts

@@ -0,0 +1,44 @@
+import type { ApiMessages } from './messages';
+/** The part of a zod issue a code reads, by shape (`@nxgt/material-core`'s `CodeIssue`). */
+export type CodeIssueLike = {
+    readonly code: string;
+    /** A custom issue's params: `.refine(…, { params: { code } })`. */
+    readonly params?: Record<string, unknown> | undefined;
+    readonly input?: unknown;
+    readonly origin?: string | undefined;
+    readonly minimum?: unknown;
+    readonly maximum?: unknown;
+    readonly expected?: unknown;
+    readonly message?: string | undefined;
+};
+/** An API error code (`<module>.errors.<slug>`), as opposed to a GraphQL one (`BAD_USER_INPUT`). */
+export declare const API_CODE: RegExp;
+export interface ApiCodeResolverOptions<L extends string> {
+    /**
+     * The app's translator, for every key that is not an API code. Method
+     * syntax: the app's own `Translate<LocaleKey>` is accepted.
+     */
+    translate(key: string, context?: Readonly<Record<string, unknown>>, language?: L | (() => L)): string;
+    /** The page's language, when a call names none. */
+    language(): L;
+    /** Which code an issue carries; the issue's `params.code` by default. */
+    codeOf?(issue: CodeIssueLike): string | undefined;
+    /** Whether a key is an API code; `<module>.errors.<slug>` by default. */
+    isApiCode?(key: string): boolean;
+}
+/** What `@nxgt/material`'s `useCodeResolver(schema, resolver)` takes. */
+export interface ApiCodeResolver<L extends string> {
+    translate: (key: string, context?: Readonly<Record<string, unknown>>, language?: L | (() => L)) => string;
+    codeOf: (issue: CodeIssueLike) => string | undefined;
+}
+/**
+ * The words of what a form's checks ask for: a refinement carrying an API
+ * code in `params.code` reads exactly as the API words it (from the
+ * catalogue `messages` holds), any other key takes the app's translator, and
+ * a code the catalogue lacks comes back as it is, so the form library words
+ * the issue with its own locale instead. Both functions are stable: a
+ * resolver is made once per schema and language, so build this once, at
+ * module scope.
+ */
+export declare function apiCodeResolver<L extends string>(messages: ApiMessages<L>, options: ApiCodeResolverOptions<L>): ApiCodeResolver<L>;
+//# sourceMappingURL=code-resolver.d.ts.map

package/dist/errors/code-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-resolver.d.ts","sourceRoot":"","sources":["../../src/errors/code-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC,CAAC;AAEF,oGAAoG;AACpG,eAAO,MAAM,QAAQ,QAAkC,CAAC;AAExD,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,MAAM;IACvD;;;OAGG;IACH,SAAS,CACR,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC3C,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GACtB,MAAM,CAAC;IACV,mDAAmD;IACnD,QAAQ,IAAI,CAAC,CAAC;IACd,yEAAyE;IACzE,MAAM,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;IAClD,yEAAyE;IACzE,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM;IAChD,SAAS,EAAE,CACV,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC3C,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KACpB,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,CAAC;CACrD;AAOD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC/C,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,EACxB,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAChC,eAAe,CAAC,CAAC,CAAC,CAiBpB"}