@gusnips/react 0.3.0 → 0.4.1

package/src/index.ts

@@ -11,17 +11,25 @@
 //   @gusnips/react/ui       the Base UI wrappers   → @base-ui/react
 //   @gusnips/react/store    createAuthStore        → zustand
 //   @gusnips/react/guards   the route guards       → react-router-dom
+//   @gusnips/react/hydrate  hydrateOrMount         → react-dom
 //
-// So what is left here imports `react`, `react-dom` and `@gusnips/http` and nothing else, and an
-// app on TanStack Router or on Redux takes the fetch client without installing a router or a
-// store it will never call. `@tanstack/react-query`, `i18next` and `react-i18next` stay optional
-// AND stay here, because `query.ts`, `i18n.ts` and `states.ts` import only their TYPES — which
-// erase, so the built barrel does not reference them at runtime. Check that claim against
-// `dist/`, never against this file: a type-only re-export looks identical in source.
+// `react-dom` is the one the second migration added, and it is the sharpest case yet: olhary
+// ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to give.
+// A required peer nobody can satisfy is not a strict contract, it is a closed door — the whole
+// package was unusable there, for one function no phone would ever call. The rule did not need
+// changing to catch it; `react-dom` simply had to stop being required.
+//
+// So what is left here imports `react` and `@gusnips/http` and nothing else, and an app on
+// TanStack Router, on Redux, or on a phone takes the fetch client without installing a router, a
+// store or a DOM renderer it will never call. `@tanstack/react-query`, `i18next` and
+// `react-i18next` stay optional AND stay here, because `query.ts`, `i18n.ts` and `states.ts`
+// import only their TYPES — which erase, so the built barrel does not reference them at runtime.
+// Check that claim against `dist/`, never against this file: a type-only re-export looks
+// identical in source.
 
 export { cn } from "./cn.ts";
 
-export { ApiError, isAbortError } from "./api-error.ts";
+export { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";
 export {
   createApiClient,
   type ApiClient,
@@ -32,7 +40,7 @@ export {
 } from "./api-client.ts";
 export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
 
-export { queryDefaults, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
+export { queryDefaults, retryDelayMs, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
 
 export {
   ErrorBoundary,
@@ -42,7 +50,6 @@ export {
 export {
   createErrorDescriber,
   humanizeWait,
-  retryAfterSecs,
   type DescribedError,
   type ErrorArm,
   type ErrorContext,
@@ -57,7 +64,10 @@ export {
   reloadOnceForChunkError,
 } from "./chunk-reload.ts";
 
-export { hydrateOrMount, PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./hydrate.ts";
+// The two constants, but NOT `hydrateOrMount` — that one is at `@gusnips/react/hydrate`, because
+// it is the package's only `react-dom` import. These come from the contract module, which imports
+// nothing at all, so they are free to everyone: a build script, a browser entry, or a phone.
+export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
 
 export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";
 

package/src/query.test.ts

@@ -1,10 +1,14 @@
 import { describe, expect, it } from "vitest";
 import { ApiError } from "./api-error.ts";
-import { shouldRetry } from "./query.ts";
+import { retryDelayMs, shouldRetry } from "./query.ts";
 
 const refusal = (status: number, code?: string) =>
   new ApiError(status, code ? { code, message: code } : null);
 
+/** A refusal that named its own expiry, the way a `Retry-After` header does. */
+const waited = (status: number, secs: number) =>
+  new ApiError(status, null, { retryAfterSecs: secs });
+
 // Invariant 8, and the reason this module exists: three donors wrote three retry rules and
 // each was right about something the other two got wrong. Every case below is one of those.
 describe("shouldRetry", () => {
@@ -51,4 +55,52 @@ describe("shouldRetry", () => {
   it("lets a durable code override the status", () => {
     expect(shouldRetry(refusal(503, "QUOTA_EXCEEDED"), ["QUOTA_EXCEEDED"])).toBe(false);
   });
+
+  // The second migration's rule. Its limiter answers `Retry-After: 60` on a per-minute window,
+  // so retrying at 1s and 2s spends two more requests that cannot possibly succeed.
+  it("does not retry a stated wait longer than we will hold", () => {
+    expect(shouldRetry(waited(429, 60))).toBe(false);
+    expect(shouldRetry(waited(429, 2))).toBe(true);
+    // The boundary is inclusive: exactly the ceiling is still worth waiting out.
+    expect(shouldRetry(waited(429, 10))).toBe(true);
+    expect(shouldRetry(waited(429, 11))).toBe(false);
+  });
+
+  it("takes the ceiling from the caller", () => {
+    expect(shouldRetry(waited(429, 60), [], 90)).toBe(true);
+    expect(shouldRetry(waited(429, 3), [], 1)).toBe(false);
+  });
+
+  // A long wait is an answer whatever the status says — the same judgement `durableLimitCodes`
+  // makes, except here the server named it and the app did not have to.
+  it("lets a stated wait override a 5xx", () => {
+    expect(shouldRetry(waited(503, 300))).toBe(false);
+  });
+
+  it("still retries when nothing said how long", () => {
+    expect(shouldRetry(refusal(429))).toBe(true);
+  });
+});
+
+describe("retryDelayMs", () => {
+  it("backs off exponentially when nothing said how long", () => {
+    expect(retryDelayMs(0, refusal(500))).toBe(1000);
+    expect(retryDelayMs(1, refusal(500))).toBe(2000);
+    // …and caps, so a long-lived query does not schedule a retry for next week.
+    expect(retryDelayMs(20, refusal(500))).toBe(30_000);
+  });
+
+  it("waits what the server asked for", () => {
+    expect(retryDelayMs(0, waited(429, 5))).toBe(5000);
+  });
+
+  // `Retry-After: 0` is a server saying "immediately", which for a client that was just refused
+  // is still too soon — the backoff is the floor.
+  it("never goes below the backoff", () => {
+    expect(retryDelayMs(1, waited(429, 0))).toBe(2000);
+  });
+
+  it("backs off for a failure that is not an API answer at all", () => {
+    expect(retryDelayMs(0, new TypeError("Failed to fetch"))).toBe(1000);
+  });
 });

package/src/query.ts

@@ -1,5 +1,5 @@
 import type { DefaultOptions } from "@tanstack/react-query";
-import { ApiError } from "./api-error.ts";
+import { ApiError, retryAfterSecs } from "./api-error.ts";
 
 /**
  * react-query defaults — the merge of three repos that each got part of this right.
@@ -15,12 +15,20 @@ import { ApiError } from "./api-error.ts";
  * - one set **`refetchOnReconnect`**, which none of the others had, and which is the single
  *   most useful refetch there is: coming back from a tunnel is exactly when the screen is stale.
  *
+ * The second migration added the fourth rule, which no donor had: **when a 429 says how long,
+ * believe it.** Its limiter answers `Retry-After: 60` on a per-minute window, and the default
+ * backoff retries at 1s and 2s — two more requests that cannot succeed, both charged against the
+ * same limiter, and three seconds added before the screen says anything. So a stated wait is
+ * waited out when it is short, and is an ANSWER when it is not.
+ *
  * This is invariant 8.
  */
 
 /** 4xx statuses a second attempt can fix. Everything else in the 4xx family is an answer. */
 const RETRYABLE_CLIENT_STATUS = new Set([408, 429]);
 
+const DEFAULT_MAX_RETRY_WAIT_SECS = 10;
+
 export interface QueryDefaultsOptions {
   /**
    * Error codes that mean "this limit does not clear by waiting" — a spent monthly quota, a
@@ -30,6 +38,15 @@ export interface QueryDefaultsOptions {
   durableLimitCodes?: readonly string[];
   /** How many times to retry a transient failure. Two donors used 2, one used 1. */
   maxRetries?: number;
+  /**
+   * Longest stated wait still worth retrying. Default 10 seconds.
+   *
+   * Only applies when the refusal named its own expiry (`Retry-After`, or `retryAfterSecs` in
+   * the body). A burst limit that clears in two seconds is worth sitting out; a monthly ceiling
+   * that clears in an hour is an answer, and holding a spinner for it helps nobody — show the
+   * wait instead, which is what `humanizeWait` is for.
+   */
+  maxRetryWaitSecs?: number;
   staleTime?: number;
   gcTime?: number;
   /**
@@ -46,19 +63,42 @@ export interface QueryDefaultsOptions {
  * Exported on its own because an app with its own QueryClient config still wants this rule, and
  * because it is the part worth testing.
  */
-export function shouldRetry(error: unknown, durableLimitCodes: readonly string[] = []): boolean {
+export function shouldRetry(
+  error: unknown,
+  durableLimitCodes: readonly string[] = [],
+  maxRetryWaitSecs = DEFAULT_MAX_RETRY_WAIT_SECS,
+): boolean {
   // No response at all — offline, DNS, a dropped connection. The request never landed, so
   // nothing about it is an answer, and a second attempt is exactly right.
   if (!(error instanceof ApiError)) return true;
 
   if (error.code !== undefined && durableLimitCodes.includes(error.code)) return false;
+
+  // It told us when it clears. A wait we are not willing to hold is a refusal, not a hiccup —
+  // and it is the same judgement `durableLimitCodes` makes, except the server did the naming.
+  const wait = retryAfterSecs(error);
+  if (wait !== null && wait > maxRetryWaitSecs) return false;
+
   if (error.status >= 500) return true;
   return RETRYABLE_CLIENT_STATUS.has(error.status);
 }
 
+/**
+ * How long before the next attempt: the server's stated wait when there is one, react-query's
+ * exponential backoff otherwise, and never less than the backoff — a `Retry-After: 0` is a
+ * server saying "immediately", which for a client that just got refused is still too soon.
+ */
+export function retryDelayMs(attemptIndex: number, error: unknown): number {
+  const backoff = Math.min(1000 * 2 ** attemptIndex, 30_000);
+  if (!(error instanceof ApiError)) return backoff;
+  const wait = retryAfterSecs(error);
+  return wait === null ? backoff : Math.max(backoff, wait * 1000);
+}
+
 export function queryDefaults({
   durableLimitCodes = [],
   maxRetries = 2,
+  maxRetryWaitSecs = DEFAULT_MAX_RETRY_WAIT_SECS,
   staleTime = 2 * 60 * 1000,
   gcTime = 10 * 60 * 1000,
   refetchOnWindowFocus = false,
@@ -68,7 +108,8 @@ export function queryDefaults({
       staleTime,
       gcTime,
       retry: (failureCount, error) =>
-        failureCount < maxRetries && shouldRetry(error, durableLimitCodes),
+        failureCount < maxRetries && shouldRetry(error, durableLimitCodes, maxRetryWaitSecs),
+      retryDelay: retryDelayMs,
       refetchOnWindowFocus,
       refetchOnReconnect: true,
     },