@gusnips/react 0.2.0 → 0.3.0

package/dist/describe-error.d.ts

@@ -23,8 +23,21 @@ export interface DescribedError {
     /** What to do about it. Its absence should be a decision, not an oversight. */
     hint?: string;
 }
-/** The subset of i18next's `t` this module needs — typed here so `i18next` stays optional. */
-export type Translate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * The subset of i18next's `t` this module needs — typed here so `i18next` stays optional.
+ *
+ * `Key` is a parameter and not plain `string` for a reason the first migration found. Every app
+ * on this stack declares `CustomTypeOptions.resources`, which types `t` to accept ONLY the keys
+ * its catalog has — so a `t` is not assignable to anything asking for `(key: string) => string`,
+ * and the adopter is left with a cast. Naming the keys instead turns that around: each function
+ * below asks for exactly the keys it looks up, a typed `t` accepts a superset of them and goes
+ * in directly, and a catalog missing one is a compile error rather than a raw key on screen.
+ */
+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";
 /** Seconds until a refusal clears, when the envelope carries them. */
 export declare function retryAfterSecs(error: ApiError): number | null;
 /**
@@ -32,31 +45,10 @@ export declare function retryAfterSecs(error: ApiError): number | null;
  *
  * The thresholds are deliberately not round: 90 seconds rather than 60, so "in 75 seconds" does
  * 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` in the catalog, each with a
+ * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
  */
-export declare function humanizeWait(t: Translate, secs: number, prefix?: string): string;
-export interface ErrorDescriberOptions<Code extends string> {
-    t: Translate;
-    /**
-     * 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.
-     */
-    messageKeyPrefix?: string;
-    /**
-     * The keys this build actually carries, usually `Object.keys(en.serverErrors)`.
-     *
-     * Membership is checked with `hasOwnProperty` and not `in`, which would accept `"toString"`.
-     * A key that is absent falls back to the server's English `message`, because a deploy can land
-     * ahead of the bundle a tab is still running and a missing translation must degrade to
-     * readable rather than render the key itself at somebody.
-     */
-    knownMessageKeys?: readonly string[] | Record<string, unknown>;
-    /** Catalog namespace for this module's own copy. Defaults to `"errors."`. */
-    copyPrefix?: string;
-    /** Per-code copy. Everything not listed falls through to the default arm below. */
-    codes?: Partial<Record<Code, (ctx: ErrorContext) => DescribedError>>;
-}
+export declare function humanizeWait<Prefix extends string>(t: Translate<`${Prefix}${WaitName}`>, secs: number, prefix: Prefix): string;
 export interface ErrorContext {
     error: ApiError;
     /** The server's own localized sentence, when `messageKey` named one this build carries. */
@@ -64,11 +56,40 @@ export interface ErrorContext {
     /** Seconds until it clears, already humanized. Null when the envelope did not say. */
     wait: string | null;
     waitSecs: number | null;
-    t: Translate;
 }
-/**
- * Build the describer. Needs `network`, `networkHint`, `unexpected`, `retrySoon`,
- * `waitSeconds`, `waitMinutes` and `waitHours` under `copyPrefix` in every locale.
- */
-export declare function createErrorDescriber<Code extends string>({ t, messageKeyPrefix, knownMessageKeys, copyPrefix, codes, }: ErrorDescriberOptions<Code>): (error: unknown) => DescribedError;
+export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix extends string, ServerName extends string> {
+    t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
+    /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
+    copyPrefix: Prefix;
+    /**
+     * 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.
+     */
+    messageKeyPrefix: ServerPrefix;
+    /**
+     * The keys this build actually carries, usually the `serverErrors` object out of the English
+     * catalog. Passing the catalog itself is both the membership test and the proof the compiler
+     * wants: a name that is in it IS a key, so the lookup below needs no cast.
+     *
+     * It is required because leaving it out is not a smaller version of this — it is the bug the
+     * 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.
+     */
+    knownMessageKeys: Record<ServerName, unknown>;
+    /**
+     * Per-code copy. Everything not listed falls through to the default arm.
+     *
+     * The arms look up the app's own keys, so they close over the app's `t` rather than being
+     * handed one — this module has no names for that copy and no business typing it.
+     *
+     * Annotate your object `Partial<Record<YourErrorCode, ErrorArm>>` where you write it, and a
+     * code that does not exist is a compile error at the arm rather than a branch that never runs.
+     */
+    codes?: Partial<Record<string, ErrorArm>>;
+}
+export type ErrorArm = (ctx: ErrorContext) => DescribedError;
+/** Build the describer. */
+export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, codes, }: 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":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;AAElF,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAK5E;AAED,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,MAAM;IACxD,CAAC,EAAE,SAAS,CAAC;IACb;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/D,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,cAAc,CAAC,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,CAAC,EAAE,SAAS,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,SAAS,MAAM,EAAE,EACxD,CAAC,EACD,gBAAkC,EAClC,gBAAgB,EAChB,UAAsB,EACtB,KAAU,GACX,EAAE,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CA2ClE"}
+{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,IAAI,CACnD,GAAG,EAAE,GAAG,EACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ,wFAAwF;AACxF,KAAK,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,WAAW,CAAC;AAE5D,iGAAiG;AACjG,KAAK,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,GAAG,WAAW,CAAC;AA8BlF,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,MAAM,EAChD,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAIR;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB,CACpC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM;IAEzB,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,GAAG,GAAG,YAAY,GAAG,UAAU,EAAE,CAAC,CAAC;IACtE,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,gBAAgB,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,cAAc,CAAC;AAE7D,2BAA2B;AAC3B,wBAAgB,oBAAoB,CAClC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM,EACzB,EACA,CAAC,EACD,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,KAAU,GACX,EAAE,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CA0C9F"}

package/dist/describe-error.js

@@ -12,39 +12,35 @@ export function retryAfterSecs(error) {
  *
  * The thresholds are deliberately not round: 90 seconds rather than 60, so "in 75 seconds" does
  * 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` in the catalog, each with a
+ * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
  */
-export function humanizeWait(t, secs, prefix = "") {
-    const key = (name) => `${prefix}${name}`;
+export function humanizeWait(t, secs, prefix) {
     if (secs < 90)
-        return t(key("waitSeconds"), { count: Math.max(1, Math.round(secs)) });
+        return t(`${prefix}waitSeconds`, { count: Math.max(1, Math.round(secs)) });
     if (secs < 90 * 60)
-        return t(key("waitMinutes"), { count: Math.round(secs / 60) });
-    return t(key("waitHours"), { count: Math.round(secs / 3600) });
+        return t(`${prefix}waitMinutes`, { count: Math.round(secs / 60) });
+    return t(`${prefix}waitHours`, { count: Math.round(secs / 3600) });
 }
-/**
- * Build the describer. Needs `network`, `networkHint`, `unexpected`, `retrySoon`,
- * `waitSeconds`, `waitMinutes` and `waitHours` under `copyPrefix` in every locale.
- */
-export function createErrorDescriber({ t, messageKeyPrefix = "serverErrors.", knownMessageKeys, copyPrefix = "errors.", codes = {}, }) {
-    const known = Array.isArray(knownMessageKeys)
-        ? new Set(knownMessageKeys)
-        : new Set(Object.keys(knownMessageKeys ?? {}));
-    const has = (name) => known.size === 0 || known.has(name);
-    const key = (name) => `${copyPrefix}${name}`;
+/** Build the describer. */
+export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, codes = {}, }) {
+    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".
+    const has = (name) => known.has(name);
     function serverSentence(error) {
         const messageKey = error.messageKey;
         if (messageKey === undefined || !messageKey.startsWith(messageKeyPrefix))
             return null;
         const name = messageKey.slice(messageKeyPrefix.length);
-        return has(name) ? t(messageKey, error.params) : null;
+        return has(name) ? t(`${messageKeyPrefix}${name}`, error.params) : null;
     }
     return function describeError(error) {
         if (!(error instanceof ApiError)) {
             // Not a response at all — the request never landed. Almost always the network, and almost
             // never worth showing a stack trace for.
-            return { cause: t(key("network")), hint: t(key("networkHint")) };
+            return { cause: t(`${copyPrefix}network`), hint: t(`${copyPrefix}networkHint`) };
         }
         const waitSecs = retryAfterSecs(error);
         const ctx = {
@@ -52,7 +48,6 @@ export function createErrorDescriber({ t, messageKeyPrefix = "serverErrors.", kn
             says: serverSentence(error),
             wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
             waitSecs,
-            t,
         };
         const arm = error.code === undefined ? undefined : codes[error.code];
         if (arm)
@@ -62,8 +57,8 @@ export function createErrorDescriber({ t, messageKeyPrefix = "serverErrors.", kn
         // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
         // the reader another attempt.
         return {
-            cause: ctx.says ?? (error.message || t(key("unexpected"))),
-            hint: error.status >= 500 ? t(key("retrySoon")) : undefined,
+            cause: ctx.says ?? (error.message || t(`${copyPrefix}unexpected`)),
+            hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
         };
     };
 }

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/dist/index.d.ts

@@ -4,7 +4,7 @@ export { createApiClient, type ApiClient, type ApiClientOptions, type RefreshRes
 export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
 export { queryDefaults, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, } from "./error-boundary.tsx";
-export { createErrorDescriber, humanizeWait, retryAfterSecs, type DescribedError, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
+export { createErrorDescriber, humanizeWait, retryAfterSecs, type DescribedError, type ErrorArm, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
 export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError, } from "./chunk-reload.ts";
 export { hydrateOrMount, PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./hydrate.ts";
 export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,EAAE;AACF,iGAAiG;AACjG,6FAA6F;AAC7F,iGAAiG;AACjG,+FAA+F;AAC/F,0FAA0F;AAC1F,qFAAqF;AAErF,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,GAKf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,EAAE;AACF,iGAAiG;AACjG,6FAA6F;AAC7F,iGAAiG;AACjG,+FAA+F;AAC/F,0FAA0F;AAC1F,qFAAqF;AAErF,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,GAMf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.2.0",
+  "version": "0.3.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, chunk-reload recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",

package/src/describe-error.test.ts

@@ -42,7 +42,9 @@ describe("retryAfterSecs", () => {
 describe("createErrorDescriber", () => {
   const describeError = createErrorDescriber({
     t,
-    knownMessageKeys: ["quotaDay", "suspended"],
+    copyPrefix: "errors.",
+    messageKeyPrefix: "serverErrors.",
+    knownMessageKeys: { quotaDay: "", suspended: "" },
     codes: {
       QUOTA_EXCEEDED: ({ says, wait }) => ({
         cause: says ?? "errors.quota",

package/src/describe-error.ts

@@ -26,8 +26,54 @@ export interface DescribedError {
   hint?: string;
 }
 
-/** The subset of i18next's `t` this module needs — typed here so `i18next` stays optional. */
-export type Translate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * The subset of i18next's `t` this module needs — typed here so `i18next` stays optional.
+ *
+ * `Key` is a parameter and not plain `string` for a reason the first migration found. Every app
+ * on this stack declares `CustomTypeOptions.resources`, which types `t` to accept ONLY the keys
+ * its catalog has — so a `t` is not assignable to anything asking for `(key: string) => string`,
+ * and the adopter is left with a cast. Naming the keys instead turns that around: each function
+ * below asks for exactly the keys it looks up, a typed `t` accepts a superset of them and goes
+ * in directly, and a catalog missing one is a compile error rather than a raw key on screen.
+ */
+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";
+
+/**
+ * The paragraph above, pinned so it cannot quietly stop being true.
+ *
+ * `ClosedCatalog` is what an app's `t` looks like once it declares `CustomTypeOptions.resources`:
+ * a closed union, nothing else accepted. It must go straight into the options below. Widen `Key`
+ * back to `string` and this stops compiling HERE, rather than at the eleventh adopter reaching
+ * for the cast the house rules forbid.
+ */
+type Satisfied<T extends true> = T;
+type ClosedCatalog = (
+  key:
+    | "errors.network"
+    | "errors.networkHint"
+    | "errors.unexpected"
+    | "errors.retrySoon"
+    | "errors.waitSeconds"
+    | "errors.waitMinutes"
+    | "errors.waitHours"
+    | "serverErrors.quotaDay"
+    | "billing.plan",
+  params?: Record<string, unknown>,
+) => string;
+type _TypedCatalogNeedsNoCast = Satisfied<
+  ClosedCatalog extends ErrorDescriberOptions<"errors.", "serverErrors.", "quotaDay">["t"]
+    ? true
+    : false
+>;
 
 /** Seconds until a refusal clears, when the envelope carries them. */
 export function retryAfterSecs(error: ApiError): number | null {
@@ -42,78 +88,97 @@ export function retryAfterSecs(error: ApiError): number | null {
  *
  * The thresholds are deliberately not round: 90 seconds rather than 60, so "in 75 seconds" does
  * 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` in the catalog, each with a
+ * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
  */
-export function humanizeWait(t: Translate, secs: number, prefix = ""): string {
-  const key = (name: string): string => `${prefix}${name}`;
-  if (secs < 90) return t(key("waitSeconds"), { count: Math.max(1, Math.round(secs)) });
-  if (secs < 90 * 60) return t(key("waitMinutes"), { count: Math.round(secs / 60) });
-  return t(key("waitHours"), { count: Math.round(secs / 3600) });
+export function humanizeWait<Prefix extends string>(
+  t: Translate<`${Prefix}${WaitName}`>,
+  secs: number,
+  prefix: Prefix,
+): string {
+  if (secs < 90) return t(`${prefix}waitSeconds`, { count: Math.max(1, Math.round(secs)) });
+  if (secs < 90 * 60) return t(`${prefix}waitMinutes`, { count: Math.round(secs / 60) });
+  return t(`${prefix}waitHours`, { count: Math.round(secs / 3600) });
+}
+
+export interface ErrorContext {
+  error: ApiError;
+  /** The server's own localized sentence, when `messageKey` named one this build carries. */
+  says: string | null;
+  /** Seconds until it clears, already humanized. Null when the envelope did not say. */
+  wait: string | null;
+  waitSecs: number | null;
 }
 
-export interface ErrorDescriberOptions<Code extends string> {
-  t: Translate;
+export interface ErrorDescriberOptions<
+  Prefix extends string,
+  ServerPrefix extends string,
+  ServerName extends string,
+> {
+  t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
+  /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
+  copyPrefix: Prefix;
   /**
    * 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.
    */
-  messageKeyPrefix?: string;
+  messageKeyPrefix: ServerPrefix;
+  /**
+   * The keys this build actually carries, usually the `serverErrors` object out of the English
+   * catalog. Passing the catalog itself is both the membership test and the proof the compiler
+   * wants: a name that is in it IS a key, so the lookup below needs no cast.
+   *
+   * It is required because leaving it out is not a smaller version of this — it is the bug the
+   * 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.
+   */
+  knownMessageKeys: Record<ServerName, unknown>;
   /**
-   * The keys this build actually carries, usually `Object.keys(en.serverErrors)`.
+   * Per-code copy. Everything not listed falls through to the default arm.
+   *
+   * The arms look up the app's own keys, so they close over the app's `t` rather than being
+   * handed one — this module has no names for that copy and no business typing it.
    *
-   * Membership is checked with `hasOwnProperty` and not `in`, which would accept `"toString"`.
-   * A key that is absent falls back to the server's English `message`, because a deploy can land
-   * ahead of the bundle a tab is still running and a missing translation must degrade to
-   * readable rather than render the key itself at somebody.
+   * Annotate your object `Partial<Record<YourErrorCode, ErrorArm>>` where you write it, and a
+   * code that does not exist is a compile error at the arm rather than a branch that never runs.
    */
-  knownMessageKeys?: readonly string[] | Record<string, unknown>;
-  /** Catalog namespace for this module's own copy. Defaults to `"errors."`. */
-  copyPrefix?: string;
-  /** Per-code copy. Everything not listed falls through to the default arm below. */
-  codes?: Partial<Record<Code, (ctx: ErrorContext) => DescribedError>>;
+  codes?: Partial<Record<string, ErrorArm>>;
 }
 
-export interface ErrorContext {
-  error: ApiError;
-  /** The server's own localized sentence, when `messageKey` named one this build carries. */
-  says: string | null;
-  /** Seconds until it clears, already humanized. Null when the envelope did not say. */
-  wait: string | null;
-  waitSecs: number | null;
-  t: Translate;
-}
+export type ErrorArm = (ctx: ErrorContext) => DescribedError;
 
-/**
- * Build the describer. Needs `network`, `networkHint`, `unexpected`, `retrySoon`,
- * `waitSeconds`, `waitMinutes` and `waitHours` under `copyPrefix` in every locale.
- */
-export function createErrorDescriber<Code extends string>({
+/** Build the describer. */
+export function createErrorDescriber<
+  Prefix extends string,
+  ServerPrefix extends string,
+  ServerName extends string,
+>({
   t,
-  messageKeyPrefix = "serverErrors.",
+  copyPrefix,
+  messageKeyPrefix,
   knownMessageKeys,
-  copyPrefix = "errors.",
   codes = {},
-}: ErrorDescriberOptions<Code>): (error: unknown) => DescribedError {
-  const known = Array.isArray(knownMessageKeys)
-    ? new Set<string>(knownMessageKeys)
-    : new Set(Object.keys(knownMessageKeys ?? {}));
+}: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError {
+  const known = new Set<string>(Object.keys(knownMessageKeys));
 
-  const has = (name: string): boolean => known.size === 0 || known.has(name);
-  const key = (name: string): string => `${copyPrefix}${name}`;
+  // 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);
 
   function serverSentence(error: ApiError): string | null {
     const messageKey = error.messageKey;
     if (messageKey === undefined || !messageKey.startsWith(messageKeyPrefix)) return null;
     const name = messageKey.slice(messageKeyPrefix.length);
-    return has(name) ? t(messageKey, error.params) : null;
+    return has(name) ? t(`${messageKeyPrefix}${name}`, error.params) : null;
   }
 
   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
       // never worth showing a stack trace for.
-      return { cause: t(key("network")), hint: t(key("networkHint")) };
+      return { cause: t(`${copyPrefix}network`), hint: t(`${copyPrefix}networkHint`) };
     }
 
     const waitSecs = retryAfterSecs(error);
@@ -122,10 +187,9 @@ export function createErrorDescriber<Code extends string>({
       says: serverSentence(error),
       wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
       waitSecs,
-      t,
     };
 
-    const arm = error.code === undefined ? undefined : codes[error.code as Code];
+    const arm = error.code === undefined ? undefined : codes[error.code];
     if (arm) return arm(ctx);
 
     // Anything unmapped: the server's own sentence is still the most specific thing we have,
@@ -133,8 +197,8 @@ export function createErrorDescriber<Code extends string>({
     // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
     // the reader another attempt.
     return {
-      cause: ctx.says ?? (error.message || t(key("unexpected"))),
-      hint: error.status >= 500 ? t(key("retrySoon")) : undefined,
+      cause: ctx.says ?? (error.message || t(`${copyPrefix}unexpected`)),
+      hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
     };
   };
 }

package/src/index.ts

@@ -44,6 +44,7 @@ export {
   humanizeWait,
   retryAfterSecs,
   type DescribedError,
+  type ErrorArm,
   type ErrorContext,
   type ErrorDescriberOptions,
   type Translate,