@gusnips/react 0.6.0 → 0.6.2

package/README.md

@@ -179,6 +179,20 @@ It is required because the default hid its price: `humanizeWait` reads `waitSeco
 `waitMinutes` and `waitHours` out of your catalog, so an app that already formats relative time
 with `Intl` had to add six entries per language before it would compile.
 
+An error your `codes` map does not name falls back to the server's own `message`. Pass `fallback`
+when that message is written for a log rather than for a person:
+
+```ts
+fallback: ({ says, wait }) => ({
+  cause: says ?? t("errors.invalid"),
+  fix: wait ? t("errors.retryIn", { when: wait }) : undefined,
+});
+```
+
+Some APIs write `message` for whoever reads the screen. Some write it for whoever reads the log —
+in English, in an app that ships three languages. Your arm also gets the stated wait, which the
+default has nowhere to put.
+
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,

package/dist/describe-error.d.ts

@@ -81,6 +81,19 @@ type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
  * left adding six entries per language to satisfy a compiler. `formatWait` owns that now.
  */
 type CopyName = "network" | "networkHint" | "unexpected" | "retrySoon";
+/**
+ * A plural is stored under suffixed names and named by its base, and the gate has to know both.
+ *
+ * i18next keeps `seatLimitReached_one` and `seatLimitReached_other`; the server sends
+ * `serverErrors.seatLimitReached`, because that is the key a person resolves with a `count`. So
+ * `Object.keys` on a catalog does NOT contain the name the server actually sends, and a gate
+ * built from it alone rejects a sentence the app is carrying — falling back to the server's
+ * English for the one refusal that had a written answer. Measured in the seventh migration: two
+ * of that API's 112 keys, both of them plan limits, both of them the exact screen where a
+ * specific sentence earns its keep.
+ */
+type PluralSuffix = "zero" | "one" | "two" | "few" | "many" | "other";
+type PluralBase<N extends string> = N extends `${infer Base}_${PluralSuffix}` ? Base : N;
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *
@@ -111,7 +124,7 @@ export interface ErrorContext {
     recover: RecoveryKind;
 }
 export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix extends string, ServerName extends string> {
-    t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
+    t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName | PluralBase<ServerName>}`>;
     /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
     copyPrefix: Prefix;
     /**
@@ -144,8 +157,25 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
      * option exists to prevent. i18next answers a key it does not have with the key itself, so a
      * deploy landing ahead of the bundle a tab is still running would render `serverErrors.foo` at
      * somebody. A name that is absent falls back to the server's English `message` instead.
+     *
+     * Hand it over as it is. A plural sits in the catalog under suffixed names while the server
+     * names the base, so the base is admitted too — see {@link PluralBase}.
      */
     knownMessageKeys: Record<ServerName, unknown>;
+    /**
+     * Transform `params` before they fill the server's sentence.
+     *
+     * The envelope carries what the SERVER knows, which is not always a word anyone should read: a
+     * role id (`admin`), an action verb (`approve_content`). The sentence needs whatever the app's
+     * own screens call those things, and the substitution happens here — inside the one lookup that
+     * reads `params` — so there is nowhere else an adopter could intervene. Without this seam the
+     * choice is to ship the raw id into `{{role}}`, or to stop using the server's sentence at all
+     * and re-resolve every key by hand, which is how i18n ended up inside a transport once already.
+     *
+     * Optional, and identity by default: an API whose params are already words passes nothing. It
+     * deliberately takes only the params — an arm that needs the error has `ctx` for that.
+     */
+    localizeParams?: (params: Record<string, string | number> | undefined) => Record<string, unknown> | undefined;
     /**
      * Per-code copy. Everything not listed falls through to the default arm.
      *
@@ -156,6 +186,21 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
      * code that does not exist is a compile error at the arm rather than a branch that never runs.
      */
     codes?: Partial<Record<string, ErrorArm>>;
+    /**
+     * What to say when nothing in `codes` matches: a code this build has no arm for, or an answer
+     * with no envelope at all.
+     *
+     * The built-in arm hands the reader the server's own `message`, and for one API in the fleet
+     * that is right — its message IS the sentence a person should read. For another it is exactly
+     * wrong: that repo's own i18n rules say `message` is "the English fallback for logs", and it
+     * ships three languages, so the built-in would put developer English in front of a reader who
+     * does not speak it. One default cannot be right for both, and the one baked in here was
+     * simply the first adopter's convention, mistaken for a fact.
+     *
+     * An arm here is also handed the stated wait, which the built-in spends on nothing: a refusal
+     * with no arm of its own could state its expiry and have that go unsaid.
+     */
+    fallback?: ErrorArm;
     /**
      * The codes that mean "this limit does not clear by waiting" — **the same list you hand
      * `queryDefaults`**, because it answers the same question and a second copy is a second
@@ -167,6 +212,6 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
 }
 export type ErrorArm = (ctx: ErrorContext) => ErrorCopy;
 /** Build the describer. */
-export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, codes, durableLimitCodes, maxRetryWaitSecs, }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError;
+export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, localizeParams, codes, fallback, durableLimitCodes, maxRetryWaitSecs, }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError;
 export {};
 //# sourceMappingURL=describe-error.d.ts.map

package/dist/describe-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}

package/dist/describe-error.js

@@ -1,5 +1,6 @@
 import { ApiError, retryAfterSecs } from "./api-error.js";
 import { shouldRetry } from "./query.js";
+const PLURAL_SUFFIX = /_(zero|one|two|few|many|other)$/;
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *
@@ -21,18 +22,23 @@ export function humanizeWait(t, secs, prefix) {
     return t(`${prefix}waitHours`, { count: Math.round(secs / 3600) });
 }
 /** Build the describer. */
-export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, codes = {}, durableLimitCodes = [], maxRetryWaitSecs, }) {
-    const known = new Set(Object.keys(knownMessageKeys));
-    // Sound, and the reason nothing here needs a cast: the set was built from the keys of
-    // `knownMessageKeys`, so membership really does establish the claim. `Object.keys` and not
-    // `in`, which would have accepted "toString".
+export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, localizeParams = (params) => params, codes = {}, fallback, durableLimitCodes = [], maxRetryWaitSecs, }) {
+    // Both spellings of every name: the one the catalog stores, and — for a plural — the one the
+    // server sends. `Object.keys` and not `in`, which would have accepted "toString".
+    const known = new Set();
+    for (const name of Object.keys(knownMessageKeys)) {
+        known.add(name);
+        known.add(name.replace(PLURAL_SUFFIX, ""));
+    }
+    // Still sound, and still the reason nothing here needs a cast: the set holds exactly the raw
+    // keys and their plural bases, which is exactly what the predicate claims.
     const has = (name) => known.has(name);
     function serverSentence(error) {
         const lookup = (named) => {
             if (named === undefined || !named.startsWith(messageKeyPrefix))
                 return null;
             const name = named.slice(messageKeyPrefix.length);
-            return has(name) ? t(`${messageKeyPrefix}${name}`, error.params) : null;
+            return has(name) ? t(`${messageKeyPrefix}${name}`, localizeParams(error.params)) : null;
         };
         // `messageKey` first: an API that sends both means the key, and the code is what the UI
         // switches on. The code is only consulted when there is no key to prefer, and it is spelled
@@ -61,6 +67,25 @@ export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPref
             return "wait";
         return shouldRetry(error, durableLimitCodes, maxRetryWaitSecs) ? "retry" : "none";
     }
+    /**
+     * Anything `codes` does not name. The server's own sentence is still the most specific thing
+     * we have, and support can act on it. A 5xx additionally gets "try again shortly", because that
+     * one genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
+     * the reader another attempt.
+     *
+     * No `code` means no envelope, and then `message` is not the server's: it is the client's own
+     * `Request failed (502)`, written for a log. A gateway answering with HTML while the API
+     * restarts is exactly when that happens, so it reached screens — until the second migration,
+     * whose three apps each guarded against that one string by hand.
+     *
+     * Replaceable, because reaching for `message` is a convention rather than a fact — see
+     * `fallback`.
+     */
+    const unmapped = fallback ??
+        (({ error, says }) => ({
+            cause: says ?? ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
+            fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+        }));
     return function describeError(error) {
         if (!(error instanceof ApiError)) {
             // Not a response at all — the request never landed. Almost always the network, and almost
@@ -82,23 +107,8 @@ export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPref
             waitSecs,
             recover: recoveryFor(error, waitSecs),
         };
-        // Anything unmapped: the server's own sentence is still the most specific thing we have,
-        // and support can act on it. A 5xx additionally gets "try again shortly", because that one
-        // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
-        // the reader another attempt.
-        //
-        // No `code` means no envelope, and then `message` is not the server's: it is the client's
-        // own `Request failed (502)`, written for a log. A gateway answering with HTML while the API
-        // restarts is exactly when that happens, so it reached screens — until the second migration,
-        // whose three apps each guarded against that one string by hand.
-        const arm = error.code === undefined ? undefined : codes[error.code];
-        const copy = arm
-            ? arm(ctx)
-            : {
-                cause: ctx.says ??
-                    ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
-                fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
-            };
+        const arm = (error.code === undefined ? undefined : codes[error.code]) ?? unmapped;
+        const copy = arm(ctx);
         // The arm wins where it spoke, the rule fills the rest. `requestId` is the one thing every
         // error surface asks for and nothing was producing — `ErrorStateProps` has reserved a
         // `reference` slot for it since the contract was written.

package/dist/describe-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"describe-error.js","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"describe-error.js","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",

package/src/describe-error.test.ts

@@ -113,6 +113,27 @@ describe("createErrorDescriber", () => {
   // The server names a SENTENCE, not any key in the app. A messageKey outside the namespace
   // is ignored rather than resolved — otherwise a compromised or careless server could point
   // the client at arbitrary copy.
+  // i18next stores a plural suffixed and the server names the base, so `Object.keys` alone does
+  // not contain the key the server sends. Before this, the two plan limits in the seventh
+  // migration's API — a seat limit and a profile limit — read as keys the build did not have,
+  // and each fell back to English on the one screen where the written sentence earns its keep.
+  it("admits the base name of a plural the catalog stores suffixed", () => {
+    const describePlural = createErrorDescriber({
+      t,
+      copyPrefix: "errors.",
+      formatWait: (secs) => humanizeWait(t, secs, "errors."),
+      messageKeyPrefix: "serverErrors.",
+      knownMessageKeys: { seatLimitReached_one: "", seatLimitReached_other: "" },
+    });
+    const error = new ApiError(402, {
+      code: "PAYMENT_REQUIRED",
+      message: "seat limit reached",
+      messageKey: "serverErrors.seatLimitReached",
+      params: { count: 3 },
+    });
+    expect(describePlural(error).cause).toBe('serverErrors.seatLimitReached({"count":3})');
+  });
+
   it("ignores a messageKey outside the server namespace", () => {
     const error = new ApiError(500, {
       code: "UNKNOWN",
@@ -220,6 +241,107 @@ describe("the recovery kind", () => {
   });
 });
 
+/**
+ * The seventh migration's seam. The server names what IT knows — a role id, an action verb — and
+ * the sentence needs whatever the app's own screens call those. The substitution can only happen
+ * inside the lookup that reads `params`, which is why an arm cannot do it: by the time an arm
+ * runs, `ctx.says` is already resolved.
+ */
+describe("localizeParams", () => {
+  const options = {
+    t,
+    copyPrefix: "errors." as const,
+    formatWait: (secs: number) => humanizeWait(t, secs, "errors."),
+    messageKeyPrefix: "serverErrors." as const,
+    knownMessageKeys: { roleRequired: "" },
+  };
+  const refusal = new ApiError(403, {
+    code: "FORBIDDEN",
+    message: "Needs admin",
+    messageKey: "serverErrors.roleRequired",
+    params: { role: "admin" },
+  });
+
+  it("translates a param before it fills the sentence", () => {
+    const describeError = createErrorDescriber({
+      ...options,
+      localizeParams: (params) => ({
+        ...params,
+        ...(typeof params?.role === "string" && { role: t(`roles.${params.role}`) }),
+      }),
+    });
+    expect(describeError(refusal).cause).toBe('serverErrors.roleRequired({"role":"roles.admin"})');
+  });
+
+  it("is identity by default, so params already in words pass straight through", () => {
+    const describeError = createErrorDescriber(options);
+    expect(describeError(refusal).cause).toBe('serverErrors.roleRequired({"role":"admin"})');
+  });
+});
+
+/**
+ * The seventh migration's second seam, and the same lesson as the first: a default that was one
+ * adopter's convention, shipped as if it were a fact.
+ *
+ * The built-in arm hands an unmapped code the server's `message`. That is right for the API whose
+ * message IS the reader's sentence. It is wrong for the one whose own i18n rules call `message`
+ * "the English fallback for logs" while the app ships three languages — there the built-in puts
+ * developer English on screen, which is the single thing that repo's rules forbid.
+ */
+describe("fallback", () => {
+  const options = {
+    t,
+    copyPrefix: "errors." as const,
+    formatWait: (secs: number) => humanizeWait(t, secs, "errors."),
+    messageKeyPrefix: "serverErrors." as const,
+    knownMessageKeys: { quotaDay: "" },
+  };
+  const describeError = createErrorDescriber({
+    ...options,
+    fallback: ({ error, says, wait }) => ({
+      cause:
+        says ??
+        (error.code !== undefined && error.status < 500 ? "errors.invalid" : "errors.unexpected"),
+      fix: wait ? `errors.retryIn(${wait})` : undefined,
+    }),
+  });
+
+  it("keeps the server's English log line off the screen", () => {
+    const error = new ApiError(422, {
+      code: "SLIDE_TOO_LONG",
+      message: "slide 3 exceeds 2200 chars",
+    });
+    expect(describeError(error).cause).toBe("errors.invalid");
+    // What the built-in would have said, which is the whole reason the seam exists.
+    expect(createErrorDescriber(options)(error).cause).toBe("slide 3 exceeds 2200 chars");
+  });
+
+  it("still resolves a sentence this build carries", () => {
+    // The arm only runs for what `codes` left unnamed; it does not take over the key lookup.
+    const error = new ApiError(429, {
+      code: "SOMETHING_NEW",
+      message: "log line",
+      messageKey: "serverErrors.quotaDay",
+    });
+    expect(describeError(error).cause).toBe("serverErrors.quotaDay");
+  });
+
+  it("hands the arm a stated wait the built-in spends on nothing", () => {
+    const error = new ApiError(
+      503,
+      { code: "SOMETHING_NEW", message: "log line" },
+      { retryAfterSecs: 120 },
+    );
+    expect(describeError(error).fix).toBe('errors.retryIn(errors.waitMinutes({"count":2}))');
+    expect(createErrorDescriber(options)(error).fix).toBe("errors.retrySoon");
+  });
+
+  it("leaves the derived recovery kind alone unless the arm narrows it", () => {
+    const error = new ApiError(503, { code: "SOMETHING_NEW", message: "log line" });
+    expect(describeError(error).recover).toBe("retry");
+  });
+});
+
 /**
  * The second convention in the fleet: an API with no `messageKey` field at all, whose CODE
  * names the sentence. One repo has 98 of them — `errors.FORECAST_NOT_FOUND` and its siblings —

package/src/describe-error.ts

@@ -93,6 +93,21 @@ type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
  */
 type CopyName = "network" | "networkHint" | "unexpected" | "retrySoon";
 
+/**
+ * A plural is stored under suffixed names and named by its base, and the gate has to know both.
+ *
+ * i18next keeps `seatLimitReached_one` and `seatLimitReached_other`; the server sends
+ * `serverErrors.seatLimitReached`, because that is the key a person resolves with a `count`. So
+ * `Object.keys` on a catalog does NOT contain the name the server actually sends, and a gate
+ * built from it alone rejects a sentence the app is carrying — falling back to the server's
+ * English for the one refusal that had a written answer. Measured in the seventh migration: two
+ * of that API's 112 keys, both of them plan limits, both of them the exact screen where a
+ * specific sentence earns its keep.
+ */
+type PluralSuffix = "zero" | "one" | "two" | "few" | "many" | "other";
+type PluralBase<N extends string> = N extends `${infer Base}_${PluralSuffix}` ? Base : N;
+const PLURAL_SUFFIX = /_(zero|one|two|few|many|other)$/;
+
 /**
  * The paragraph above, pinned so it cannot quietly stop being true.
  *
@@ -162,7 +177,7 @@ export interface ErrorDescriberOptions<
   ServerPrefix extends string,
   ServerName extends string,
 > {
-  t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
+  t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName | PluralBase<ServerName>}`>;
   /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
   copyPrefix: Prefix;
   /**
@@ -195,8 +210,27 @@ export interface ErrorDescriberOptions<
    * option exists to prevent. i18next answers a key it does not have with the key itself, so a
    * deploy landing ahead of the bundle a tab is still running would render `serverErrors.foo` at
    * somebody. A name that is absent falls back to the server's English `message` instead.
+   *
+   * Hand it over as it is. A plural sits in the catalog under suffixed names while the server
+   * names the base, so the base is admitted too — see {@link PluralBase}.
    */
   knownMessageKeys: Record<ServerName, unknown>;
+  /**
+   * Transform `params` before they fill the server's sentence.
+   *
+   * The envelope carries what the SERVER knows, which is not always a word anyone should read: a
+   * role id (`admin`), an action verb (`approve_content`). The sentence needs whatever the app's
+   * own screens call those things, and the substitution happens here — inside the one lookup that
+   * reads `params` — so there is nowhere else an adopter could intervene. Without this seam the
+   * choice is to ship the raw id into `{{role}}`, or to stop using the server's sentence at all
+   * and re-resolve every key by hand, which is how i18n ended up inside a transport once already.
+   *
+   * Optional, and identity by default: an API whose params are already words passes nothing. It
+   * deliberately takes only the params — an arm that needs the error has `ctx` for that.
+   */
+  localizeParams?: (
+    params: Record<string, string | number> | undefined,
+  ) => Record<string, unknown> | undefined;
   /**
    * Per-code copy. Everything not listed falls through to the default arm.
    *
@@ -207,6 +241,21 @@ export interface ErrorDescriberOptions<
    * code that does not exist is a compile error at the arm rather than a branch that never runs.
    */
   codes?: Partial<Record<string, ErrorArm>>;
+  /**
+   * What to say when nothing in `codes` matches: a code this build has no arm for, or an answer
+   * with no envelope at all.
+   *
+   * The built-in arm hands the reader the server's own `message`, and for one API in the fleet
+   * that is right — its message IS the sentence a person should read. For another it is exactly
+   * wrong: that repo's own i18n rules say `message` is "the English fallback for logs", and it
+   * ships three languages, so the built-in would put developer English in front of a reader who
+   * does not speak it. One default cannot be right for both, and the one baked in here was
+   * simply the first adopter's convention, mistaken for a fact.
+   *
+   * An arm here is also handed the stated wait, which the built-in spends on nothing: a refusal
+   * with no arm of its own could state its expiry and have that go unsaid.
+   */
+  fallback?: ErrorArm;
   /**
    * The codes that mean "this limit does not clear by waiting" — **the same list you hand
    * `queryDefaults`**, because it answers the same question and a second copy is a second
@@ -230,22 +279,29 @@ export function createErrorDescriber<
   formatWait,
   messageKeyPrefix,
   knownMessageKeys,
+  localizeParams = (params) => params,
   codes = {},
+  fallback,
   durableLimitCodes = [],
   maxRetryWaitSecs,
 }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError {
-  const known = new Set<string>(Object.keys(knownMessageKeys));
+  // Both spellings of every name: the one the catalog stores, and — for a plural — the one the
+  // server sends. `Object.keys` and not `in`, which would have accepted "toString".
+  const known = new Set<string>();
+  for (const name of Object.keys(knownMessageKeys)) {
+    known.add(name);
+    known.add(name.replace(PLURAL_SUFFIX, ""));
+  }
 
-  // Sound, and the reason nothing here needs a cast: the set was built from the keys of
-  // `knownMessageKeys`, so membership really does establish the claim. `Object.keys` and not
-  // `in`, which would have accepted "toString".
-  const has = (name: string): name is ServerName => known.has(name);
+  // Still sound, and still the reason nothing here needs a cast: the set holds exactly the raw
+  // keys and their plural bases, which is exactly what the predicate claims.
+  const has = (name: string): name is ServerName | PluralBase<ServerName> => known.has(name);
 
   function serverSentence(error: ApiError): string | null {
     const lookup = (named: string | undefined): string | null => {
       if (named === undefined || !named.startsWith(messageKeyPrefix)) return null;
       const name = named.slice(messageKeyPrefix.length);
-      return has(name) ? t(`${messageKeyPrefix}${name}`, error.params) : null;
+      return has(name) ? t(`${messageKeyPrefix}${name}`, localizeParams(error.params)) : null;
     };
     // `messageKey` first: an API that sends both means the key, and the code is what the UI
     // switches on. The code is only consulted when there is no key to prefer, and it is spelled
@@ -275,6 +331,28 @@ export function createErrorDescriber<
     return shouldRetry(error, durableLimitCodes, maxRetryWaitSecs) ? "retry" : "none";
   }
 
+  /**
+   * Anything `codes` does not name. The server's own sentence is still the most specific thing
+   * we have, and support can act on it. A 5xx additionally gets "try again shortly", because that
+   * one genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
+   * the reader another attempt.
+   *
+   * No `code` means no envelope, and then `message` is not the server's: it is the client's own
+   * `Request failed (502)`, written for a log. A gateway answering with HTML while the API
+   * restarts is exactly when that happens, so it reached screens — until the second migration,
+   * whose three apps each guarded against that one string by hand.
+   *
+   * Replaceable, because reaching for `message` is a convention rather than a fact — see
+   * `fallback`.
+   */
+  const unmapped: ErrorArm =
+    fallback ??
+    (({ error, says }) => ({
+      cause:
+        says ?? ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
+      fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+    }));
+
   return function describeError(error: unknown): DescribedError {
     if (!(error instanceof ApiError)) {
       // Not a response at all — the request never landed. Almost always the network, and almost
@@ -298,24 +376,8 @@ export function createErrorDescriber<
       recover: recoveryFor(error, waitSecs),
     };
 
-    // Anything unmapped: the server's own sentence is still the most specific thing we have,
-    // and support can act on it. A 5xx additionally gets "try again shortly", because that one
-    // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
-    // the reader another attempt.
-    //
-    // No `code` means no envelope, and then `message` is not the server's: it is the client's
-    // own `Request failed (502)`, written for a log. A gateway answering with HTML while the API
-    // restarts is exactly when that happens, so it reached screens — until the second migration,
-    // whose three apps each guarded against that one string by hand.
-    const arm = error.code === undefined ? undefined : codes[error.code];
-    const copy: ErrorCopy = arm
-      ? arm(ctx)
-      : {
-          cause:
-            ctx.says ??
-            ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
-          fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
-        };
+    const arm = (error.code === undefined ? undefined : codes[error.code]) ?? unmapped;
+    const copy: ErrorCopy = arm(ctx);
 
     // The arm wins where it spoke, the rule fills the rest. `requestId` is the one thing every
     // error surface asks for and nothing was producing — `ErrorStateProps` has reserved a

package/src/guards.test.ts

@@ -0,0 +1,129 @@
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  createRequireAnonymous,
+  createRequireAuth,
+  createRequireProfile,
+  type MeQuery,
+} from "./guards.tsx";
+
+// `react-router-dom` is mocked rather than wrapped in a real router. Every question here is only
+// WHICH branch a guard picked, and a redirect is the one branch with no children to read — so
+// `Navigate` never has to run, it only has to be identifiable as an element type. That is what
+// lets the redirect cases assert a destination without rendering anything.
+const router = vi.hoisted(() => ({
+  Navigate: vi.fn(),
+  useLocation: vi.fn(() => ({ pathname: "/posts", search: "?page=2" })),
+}));
+vi.mock("react-router-dom", () => router);
+
+/**
+ * One render, as plain data.
+ *
+ * A function component IS a function, so calling it returns the element it would have rendered —
+ * no DOM, no renderer, nothing mounted, and no test-only dependency to install. The cast is this
+ * file admitting it reads two fields off that element and nothing else.
+ */
+type Rendered = { type: unknown; props: Record<string, unknown> };
+const render = (Guard: (p: { children: ReactNode }) => ReactNode): Rendered =>
+  Guard({ children: "CONTENT" }) as unknown as Rendered;
+
+/** Which branch came back: a redirect names its destination, every other branch names its child. */
+const branch = (r: Rendered): unknown =>
+  r.type === router.Navigate ? { to: r.props.to, state: r.props.state } : r.props.children;
+
+const session =
+  (isAuthenticated: boolean, isLoading = false) =>
+  () => ({
+    isAuthenticated,
+    isLoading,
+  });
+
+const profile = (me: MeQuery<{ suspended: boolean }>) =>
+  createRequireProfile(() => me, { loading: "LOADING" })(
+    (m) => !m.suspended,
+    "DENIED",
+    (error) => `FAILED:${String(error)}`,
+  );
+
+describe("createRequireProfile", () => {
+  it("waits while the profile is still being asked for", () => {
+    expect(branch(render(profile({ status: "pending" })))).toBe("LOADING");
+  });
+
+  // Invariant 4, and the reason this module exists rather than being written a ninth time.
+  // `!me?.isStaff` reads an undefined profile as a real "no", so an outage on /auth/me becomes a
+  // refusal — the wrong cause, no retry, and no request id to quote. Three repos shipped that, and
+  // in two of them the sibling guard failed the other way for the same reason: `me?.suspended` read
+  // a failure as "not suspended" and let a suspended account straight through. One mistake, closed
+  // on one screen and OPEN on the next, which is why a failure must reach neither answer.
+  it("does not read a failed query as a refusal", () => {
+    const failed = branch(render(profile({ status: "error", error: "boom" })));
+    expect(failed).toBe("FAILED:boom");
+    expect(failed).not.toBe("DENIED");
+    expect(failed).not.toBe("CONTENT");
+  });
+
+  it("refuses only on a real no", () => {
+    expect(branch(render(profile({ status: "success", data: { suspended: true } })))).toBe(
+      "DENIED",
+    );
+  });
+
+  it("lets an allowed profile through", () => {
+    expect(branch(render(profile({ status: "success", data: { suspended: false } })))).toBe(
+      "CONTENT",
+    );
+  });
+
+  it("takes a refusal as a function, for one built only when it is used", () => {
+    const Guard = createRequireProfile(() => ({ status: "success" as const, data: 1 }), {
+      loading: "LOADING",
+    })(
+      () => false,
+      () => "DENIED-LAZY",
+      () => "FAILED",
+    );
+    expect(branch(render(Guard))).toBe("DENIED-LAZY");
+  });
+});
+
+describe("createRequireAuth", () => {
+  const guard = (isAuthenticated: boolean, isLoading = false) =>
+    createRequireAuth(session(isAuthenticated, isLoading), "/login", { loading: "LOADING" });
+
+  it("waits while the session is still resolving", () => {
+    expect(branch(render(guard(false, true)))).toBe("LOADING");
+  });
+
+  // The redirect carries where they were headed, query string included: an adopter's sign-in screen
+  // reads `location.state.from` to land them on the page they actually wanted rather than the home
+  // screen. One donor hardcoded this in four places, which is what made it a factory.
+  it("remembers the address it turned away", () => {
+    expect(branch(render(guard(false)))).toEqual({
+      to: "/login",
+      state: { from: "/posts?page=2" },
+    });
+  });
+
+  it("lets a signed-in visitor through", () => {
+    expect(branch(render(guard(true)))).toBe("CONTENT");
+  });
+});
+
+describe("createRequireAnonymous", () => {
+  const guard = (isAuthenticated: boolean, isLoading = false) =>
+    createRequireAnonymous(session(isAuthenticated, isLoading), "/", { loading: "LOADING" });
+
+  it("waits while the session is still resolving", () => {
+    expect(branch(render(guard(true, true)))).toBe("LOADING");
+  });
+
+  it("sends a signed-in visitor home", () => {
+    expect(branch(render(guard(true)))).toEqual({ to: "/", state: undefined });
+  });
+
+  it("lets an anonymous visitor through", () => {
+    expect(branch(render(guard(false)))).toBe("CONTENT");
+  });
+});