@gusnips/react 0.5.3 → 0.6.0

package/README.md

@@ -156,15 +156,29 @@ hurry cannot skip.
 which control to offer, and the request id to print under it:
 
 ```ts
-const { cause, hint, recover, reference } = describeError(error);
+const { cause, fix, recover, reference } = describeError(error);
 // recover: "retry" | "signin" | "wait" | "none"
 ```
 
+The field is `fix`, the same word as the prop above. It was `hint` until 0.6.0, which left every
+adopter writing `fix={hint}` at every error surface.
+
 `recover` is derived from `shouldRetry` — the same rule react-query retries on — so the button a
 reader sees and the retry that actually happens cannot disagree. Give it the same
 `durableLimitCodes` list you give `queryDefaults`, and a spent quota offers no button instead of
 one that cannot work.
 
+You also say how a stated wait becomes words:
+
+```ts
+formatWait: (secs) => humanizeWait(t, secs, "errors."); // three ICU plural keys
+formatWait: (secs) => formatIn(secs, locale); // or your own Intl formatter
+```
+
+It is required because the default hid its price: `humanizeWait` reads `waitSeconds`,
+`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.
+
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,

package/dist/describe-error.d.ts

@@ -8,11 +8,17 @@ import { ApiError } from "./api-error.ts";
  * "Monthly quota spent, upgrade or buy a pack" is right in a JSON body and wrong under a button
  * that could just say what to do next.
  *
- * `cause` is what happened. `hint` is what to do about it. **A surface that shows only the first
+ * `cause` is what happened. `fix` is what to do about it. **A surface that shows only the first
  * half is the dead end this exists to prevent** — which is why the type has two fields and not
- * one, and why `hint` being absent should be a deliberate choice at each call site rather than
+ * one, and why `fix` being absent should be a deliberate choice at each call site rather than
  * the default nobody noticed.
  *
+ * `fix`, and not the `hint` this returned until 0.6.0. `ErrorStateProps` — the contract this same
+ * package ships for the component that renders this — has always called it `fix`, so every
+ * adopter wrote `fix={hint}` at every error surface: a rename adapter, which is the shape of an
+ * API we got wrong. It also clears a collision, because in at least one adopter a form field's
+ * `hint` is the requirement text under the input, which is a different thing entirely.
+ *
  * The per-code switch stays in the product: two donors' switches shared their SHAPE and almost
  * no arms, because the arms are that API's vocabulary. What ships is the scaffolding around it,
  * which is the part that was written twice and got subtly different both times.
@@ -42,7 +48,7 @@ export interface ErrorCopy {
     /** What happened, in the reader's words. */
     cause: string;
     /** What to do about it. Its absence should be a decision, not an oversight. */
-    hint?: string;
+    fix?: string;
     /** Override the derived kind — a 429 whose code means a spent quota is `"none"`, not `"wait"`. */
     recover?: RecoveryKind;
     /** Override the request id. Rarely wanted; the envelope's is used by default. */
@@ -65,8 +71,16 @@ export interface DescribedError extends ErrorCopy {
 export type Translate<Key extends string = string> = (key: Key, params?: Record<string, unknown>) => string;
 /** The three names {@link humanizeWait} looks up, under whatever prefix you pass it. */
 type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
-/** Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them. */
-type CopyName = WaitName | "network" | "networkHint" | "unexpected" | "retrySoon";
+/**
+ * Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them.
+ *
+ * The three wait names are deliberately NOT here, which is the other half of 0.6.0. This module
+ * used to humanize a stated wait itself, so `waitSeconds`/`waitMinutes`/`waitHours` — each with
+ * an ICU plural — landed in the key union of every adopter's `t` whether or not a wait was ever
+ * rendered. An app that formats waits with `Intl.RelativeTimeFormat` needs none of them and was
+ * left adding six entries per language to satisfy a compiler. `formatWait` owns that now.
+ */
+type CopyName = "network" | "networkHint" | "unexpected" | "retrySoon";
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *
@@ -74,6 +88,11 @@ type CopyName = WaitName | "network" | "networkHint" | "unexpected" | "retrySoon
  * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
  * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
+ *
+ * This is what you pass as `formatWait` when your catalog carries those three:
+ * `formatWait: (secs) => humanizeWait(t, secs, "errors.")`. An app that formats a wait with
+ * `Intl.RelativeTimeFormat` passes its own one-liner instead and needs no wait keys at all —
+ * which also gets it correct plurals in languages with more than two forms, for free.
  */
 export declare function humanizeWait<Prefix extends string>(t: Translate<`${Prefix}${WaitName}`>, secs: number, prefix: Prefix): string;
 export interface ErrorContext {
@@ -95,6 +114,16 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
     t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
     /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
     copyPrefix: Prefix;
+    /**
+     * How a stated wait becomes words, for the `wait` an arm reads off its context.
+     *
+     * Required rather than defaulted, because there is no answer that is right for everyone and a
+     * default hid the cost: {@link humanizeWait} reads three ICU plural keys out of your catalog,
+     * and an app that already formats relative time with `Intl` would have had to add them to
+     * compile. Say which you want — `(secs) => humanizeWait(t, secs, "errors.")`, or your own
+     * `(secs) => formatIn(secs, locale)` — and the catalog you need is the one you can see.
+     */
+    formatWait: (secs: number) => string;
     /**
      * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
      * ignored — the server names a sentence, it does not get to name any key in the app.
@@ -138,6 +167,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, 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, codes, 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

@@ -7,6 +7,11 @@ import { shouldRetry } from "./query.js";
  * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
  * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
+ *
+ * This is what you pass as `formatWait` when your catalog carries those three:
+ * `formatWait: (secs) => humanizeWait(t, secs, "errors.")`. An app that formats a wait with
+ * `Intl.RelativeTimeFormat` passes its own one-liner instead and needs no wait keys at all —
+ * which also gets it correct plurals in languages with more than two forms, for free.
  */
 export function humanizeWait(t, secs, prefix) {
     if (secs < 90)
@@ -16,7 +21,7 @@ export function humanizeWait(t, secs, prefix) {
     return t(`${prefix}waitHours`, { count: Math.round(secs / 3600) });
 }
 /** Build the describer. */
-export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, codes = {}, durableLimitCodes = [], maxRetryWaitSecs, }) {
+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
@@ -63,7 +68,9 @@ export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMes
             // so these two agree here without either being told about the other.
             return {
                 cause: t(`${copyPrefix}network`),
-                hint: t(`${copyPrefix}networkHint`),
+                // The catalog KEY keeps its name while the field becomes `fix`: renaming it would cost
+                // every adopter a JSON edit in every language, for a string no caller ever types.
+                fix: t(`${copyPrefix}networkHint`),
                 recover: "retry",
             };
         }
@@ -71,7 +78,7 @@ export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMes
         const ctx = {
             error,
             says: serverSentence(error),
-            wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
+            wait: waitSecs === null ? null : formatWait(waitSecs),
             waitSecs,
             recover: recoveryFor(error, waitSecs),
         };
@@ -90,7 +97,7 @@ export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMes
             : {
                 cause: ctx.says ??
                     ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
-                hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+                fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
             };
         // 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/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.5.3",
+  "version": "0.6.0",
   "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

@@ -23,25 +23,68 @@ describe("humanizeWait", () => {
   });
 });
 
+/**
+ * The seam 0.6.0 added, and why it is required rather than defaulted: this module used to
+ * humanize the wait itself, which put `waitSeconds`/`waitMinutes`/`waitHours` into the key union
+ * of every adopter's `t` — six ICU entries per language — even for an app that formats relative
+ * time with `Intl` and would never render one of them.
+ */
+describe("formatWait", () => {
+  const describeError = createErrorDescriber({
+    t,
+    copyPrefix: "errors.",
+    // What an adopter on `Intl.RelativeTimeFormat` passes. Its catalog has no wait keys at all,
+    // and it gets correct plurals in every language without writing one.
+    formatWait: (secs) =>
+      new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(
+        Math.round(secs / 60),
+        "minute",
+      ),
+    messageKeyPrefix: "serverErrors.",
+    knownMessageKeys: {},
+    codes: {
+      RATE_LIMIT_EXCEEDED: ({ wait }) => ({
+        cause: "errors.rateLimit",
+        fix: `wait:${String(wait)}`,
+      }),
+    },
+  });
+
+  it("hands an arm the wait in the app's own words, not the package's", () => {
+    const error = new ApiError(
+      429,
+      { code: "RATE_LIMIT_EXCEEDED", message: "slow down" },
+      { retryAfterSecs: 120 },
+    );
+    expect(describeError(error).fix).toBe("wait:in 2 minutes");
+  });
+
+  it("leaves the wait null when the refusal never stated one", () => {
+    const error = new ApiError(429, { code: "RATE_LIMIT_EXCEEDED", message: "slow down" });
+    expect(describeError(error).fix).toBe("wait:null");
+  });
+});
+
 describe("createErrorDescriber", () => {
   const describeError = createErrorDescriber({
     t,
     copyPrefix: "errors.",
+    formatWait: (secs) => humanizeWait(t, secs, "errors."),
     messageKeyPrefix: "serverErrors.",
     knownMessageKeys: { quotaDay: "", suspended: "" },
     codes: {
       QUOTA_EXCEEDED: ({ says, wait }) => ({
         cause: says ?? "errors.quota",
-        hint: wait ? `errors.retryIn(${wait})` : undefined,
+        fix: wait ? `errors.retryIn(${wait})` : undefined,
       }),
     },
   });
 
   it("reads a thrown non-response as the network, with a way forward", () => {
-    const { cause, hint } = describeError(new TypeError("Failed to fetch"));
+    const { cause, fix } = describeError(new TypeError("Failed to fetch"));
     expect(cause).toBe("errors.network");
-    // The hint is the point. A cause with no hint is the dead end this module exists to stop.
-    expect(hint).toBe("errors.networkHint");
+    // The fix is the point. A cause with no fix is the dead end this module exists to stop.
+    expect(fix).toBe("errors.networkHint");
   });
 
   it("resolves a messageKey this build carries, with its params", () => {
@@ -82,16 +125,16 @@ describe("createErrorDescriber", () => {
   it("offers a retry on a 5xx and withholds it on a 4xx", () => {
     // A 5xx genuinely clears on its own. A 4xx does not, and saying so would cost the reader
     // another attempt for nothing.
-    expect(describeError(new ApiError(503, null)).hint).toBe("errors.retrySoon");
-    expect(describeError(new ApiError(403, null)).hint).toBeUndefined();
+    expect(describeError(new ApiError(503, null)).fix).toBe("errors.retrySoon");
+    expect(describeError(new ApiError(403, null)).fix).toBeUndefined();
   });
 
   it("never puts the client's own log line on screen", () => {
     // A gateway answers with HTML, so there is no envelope and `message` is the client's
     // `Request failed (502)` — English, and written for a log.
-    const { cause, hint } = describeError(new ApiError(502, null));
+    const { cause, fix } = describeError(new ApiError(502, null));
     expect(cause).toBe("errors.unexpected");
-    expect(hint).toBe("errors.retrySoon");
+    expect(fix).toBe("errors.retrySoon");
   });
 });
 
@@ -107,6 +150,7 @@ describe("the recovery kind", () => {
     messageKeyPrefix: "serverErrors.",
     knownMessageKeys: { quotaDay: "" },
     durableLimitCodes: ["QUOTA_EXCEEDED"],
+    formatWait: (secs) => humanizeWait(t, secs, "errors."),
   });
 
   it("sends a 401 to sign-in and leaves a 403 alone", () => {
@@ -159,6 +203,7 @@ describe("the recovery kind", () => {
     const describe503 = createErrorDescriber({
       t,
       copyPrefix: "errors.",
+      formatWait: (secs) => humanizeWait(t, secs, "errors."),
       messageKeyPrefix: "serverErrors.",
       knownMessageKeys: {},
       codes: {
@@ -185,6 +230,7 @@ describe("createErrorDescriber, when the code names the sentence", () => {
   const describeError = createErrorDescriber({
     t,
     copyPrefix: "errors.",
+    formatWait: (secs) => humanizeWait(t, secs, "errors."),
     messageKeyPrefix: "errors.",
     knownMessageKeys: { FORECAST_NOT_FOUND: "", network: "" },
   });

package/src/describe-error.ts

@@ -10,11 +10,17 @@ import { shouldRetry } from "./query.ts";
  * "Monthly quota spent, upgrade or buy a pack" is right in a JSON body and wrong under a button
  * that could just say what to do next.
  *
- * `cause` is what happened. `hint` is what to do about it. **A surface that shows only the first
+ * `cause` is what happened. `fix` is what to do about it. **A surface that shows only the first
  * half is the dead end this exists to prevent** — which is why the type has two fields and not
- * one, and why `hint` being absent should be a deliberate choice at each call site rather than
+ * one, and why `fix` being absent should be a deliberate choice at each call site rather than
  * the default nobody noticed.
  *
+ * `fix`, and not the `hint` this returned until 0.6.0. `ErrorStateProps` — the contract this same
+ * package ships for the component that renders this — has always called it `fix`, so every
+ * adopter wrote `fix={hint}` at every error surface: a rename adapter, which is the shape of an
+ * API we got wrong. It also clears a collision, because in at least one adopter a form field's
+ * `hint` is the requirement text under the input, which is a different thing entirely.
+ *
  * The per-code switch stays in the product: two donors' switches shared their SHAPE and almost
  * no arms, because the arms are that API's vocabulary. What ships is the scaffolding around it,
  * which is the part that was written twice and got subtly different both times.
@@ -46,7 +52,7 @@ export interface ErrorCopy {
   /** What happened, in the reader's words. */
   cause: string;
   /** What to do about it. Its absence should be a decision, not an oversight. */
-  hint?: string;
+  fix?: string;
   /** Override the derived kind — a 429 whose code means a spent quota is `"none"`, not `"wait"`. */
   recover?: RecoveryKind;
   /** Override the request id. Rarely wanted; the envelope's is used by default. */
@@ -76,8 +82,16 @@ export type Translate<Key extends string = string> = (
 /** The three names {@link humanizeWait} looks up, under whatever prefix you pass it. */
 type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
 
-/** Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them. */
-type CopyName = WaitName | "network" | "networkHint" | "unexpected" | "retrySoon";
+/**
+ * Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them.
+ *
+ * The three wait names are deliberately NOT here, which is the other half of 0.6.0. This module
+ * used to humanize a stated wait itself, so `waitSeconds`/`waitMinutes`/`waitHours` — each with
+ * an ICU plural — landed in the key union of every adopter's `t` whether or not a wait was ever
+ * rendered. An app that formats waits with `Intl.RelativeTimeFormat` needs none of them and was
+ * left adding six entries per language to satisfy a compiler. `formatWait` owns that now.
+ */
+type CopyName = "network" | "networkHint" | "unexpected" | "retrySoon";
 
 /**
  * The paragraph above, pinned so it cannot quietly stop being true.
@@ -94,9 +108,6 @@ type ClosedCatalog = (
     | "errors.networkHint"
     | "errors.unexpected"
     | "errors.retrySoon"
-    | "errors.waitSeconds"
-    | "errors.waitMinutes"
-    | "errors.waitHours"
     | "serverErrors.quotaDay"
     | "billing.plan",
   params?: Record<string, unknown>,
@@ -114,6 +125,11 @@ type _TypedCatalogNeedsNoCast = Satisfied<
  * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
  * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
+ *
+ * This is what you pass as `formatWait` when your catalog carries those three:
+ * `formatWait: (secs) => humanizeWait(t, secs, "errors.")`. An app that formats a wait with
+ * `Intl.RelativeTimeFormat` passes its own one-liner instead and needs no wait keys at all —
+ * which also gets it correct plurals in languages with more than two forms, for free.
  */
 export function humanizeWait<Prefix extends string>(
   t: Translate<`${Prefix}${WaitName}`>,
@@ -149,6 +165,16 @@ export interface ErrorDescriberOptions<
   t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
   /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
   copyPrefix: Prefix;
+  /**
+   * How a stated wait becomes words, for the `wait` an arm reads off its context.
+   *
+   * Required rather than defaulted, because there is no answer that is right for everyone and a
+   * default hid the cost: {@link humanizeWait} reads three ICU plural keys out of your catalog,
+   * and an app that already formats relative time with `Intl` would have had to add them to
+   * compile. Say which you want — `(secs) => humanizeWait(t, secs, "errors.")`, or your own
+   * `(secs) => formatIn(secs, locale)` — and the catalog you need is the one you can see.
+   */
+  formatWait: (secs: number) => string;
   /**
    * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
    * ignored — the server names a sentence, it does not get to name any key in the app.
@@ -201,6 +227,7 @@ export function createErrorDescriber<
 >({
   t,
   copyPrefix,
+  formatWait,
   messageKeyPrefix,
   knownMessageKeys,
   codes = {},
@@ -255,7 +282,9 @@ export function createErrorDescriber<
       // so these two agree here without either being told about the other.
       return {
         cause: t(`${copyPrefix}network`),
-        hint: t(`${copyPrefix}networkHint`),
+        // The catalog KEY keeps its name while the field becomes `fix`: renaming it would cost
+        // every adopter a JSON edit in every language, for a string no caller ever types.
+        fix: t(`${copyPrefix}networkHint`),
         recover: "retry",
       };
     }
@@ -264,7 +293,7 @@ export function createErrorDescriber<
     const ctx: ErrorContext = {
       error,
       says: serverSentence(error),
-      wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
+      wait: waitSecs === null ? null : formatWait(waitSecs),
       waitSecs,
       recover: recoveryFor(error, waitSecs),
     };
@@ -285,7 +314,7 @@ export function createErrorDescriber<
           cause:
             ctx.says ??
             ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
-          hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+          fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
         };
 
     // The arm wins where it spoke, the rule fills the rest. `requestId` is the one thing every