@gusnips/react 0.9.0 → 0.9.1

package/README.md

@@ -87,6 +87,13 @@ limit both arrive as 429, but one clears by waiting and the other clears by buyi
 second burns another request against the limiter to hear the same thing three times, so you name
 those codes and they are never retried.
 
+You only need that list where your API stays quiet. If it answers `Retry-After: 2`, the wait is
+sat out; past `maxRetryWaitSecs` (10 seconds by default) the wait is the answer and the screen
+says so instead of holding a spinner. And if it sends `details.retryAfterSecs: null`, it is
+saying waiting will never fix this — a cap that frees only when somebody deletes something, a
+slot that frees when another job ends. That `null` is read as the claim it is, not as a field
+somebody forgot, so the code never reaches your list.
+
 ## Survives your deploys
 
 An app with `lazy()` routes serves chunks by hashed filename. Deploy while someone has a tab

package/dist/api-error.d.ts

@@ -51,8 +51,34 @@ export declare class ApiError extends Error {
  * The header first, because it is the standard one and it is what a limiter emits without being
  * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
  * caller asking "how long" should not have to know which server it is talking to.
+ *
+ * It deliberately does not answer whether waiting helps at all. `null` here means "no countdown
+ * to show", which is the right answer both for a refusal that said nothing and for one that said
+ * waiting will never fix it — and the adopters' countdown UIs read it for exactly that. Telling
+ * those two apart is {@link waitingNeverHelps}.
  */
 export declare function retryAfterSecs(error: ApiError): number | null;
+/**
+ * Did the answer say, in so many words, that waiting will never fix this?
+ *
+ * The server half of this fleet sends `details.retryAfterSecs: null` on a refusal no amount of
+ * time clears — a cap that frees only when somebody deletes something, a concurrency slot that
+ * frees when another job ends. An explicit `null` is a claim somebody has to read; an omitted key
+ * is invisible. That is the whole reason the two must not collapse into one answer: this is the
+ * server naming what `durableLimitCodes` otherwise makes every app name by hand, one code at a
+ * time, and keep in step with a backend it does not own.
+ *
+ * Present-and-`null` is the entire test. An absent key reads as `undefined`, so `=== null`
+ * already separates the claim from the silence and an `in` check would only widen it to every
+ * stated wait. Body-only by design: `Retry-After` has no spelling for "never".
+ *
+ * Not exported from the package, and that is the point: it is not "is this refusal durable?". It
+ * says nothing about a durable CODE or a wait too long to hold, so an error surface branching on
+ * it would answer differently from the retry rule for every limit the app names itself. The one
+ * question worth asking out loud is `shouldRetry`, and `describeError` already derives the
+ * control it offers from exactly that — invariant 8, one rule and two consumers.
+ */
+export declare function waitingNeverHelps(error: ApiError): boolean;
 /**
  * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;gBAGzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,EAClC,IAAI,GAAE;QACJ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;KACpB;CAaT;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAM7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAepF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD"}
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;gBAGzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,EAClC,IAAI,GAAE;QACJ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;KACpB;CAaT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAM7D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAI1D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAepF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD"}

package/dist/api-error.js

@@ -56,6 +56,11 @@ export class ApiError extends Error {
  * The header first, because it is the standard one and it is what a limiter emits without being
  * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
  * caller asking "how long" should not have to know which server it is talking to.
+ *
+ * It deliberately does not answer whether waiting helps at all. `null` here means "no countdown
+ * to show", which is the right answer both for a refusal that said nothing and for one that said
+ * waiting will never fix it — and the adopters' countdown UIs read it for exactly that. Telling
+ * those two apart is {@link waitingNeverHelps}.
  */
 export function retryAfterSecs(error) {
     if (error.retryAfterSecs !== undefined)
@@ -66,6 +71,32 @@ export function retryAfterSecs(error) {
     const value = details.retryAfterSecs;
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+/**
+ * Did the answer say, in so many words, that waiting will never fix this?
+ *
+ * The server half of this fleet sends `details.retryAfterSecs: null` on a refusal no amount of
+ * time clears — a cap that frees only when somebody deletes something, a concurrency slot that
+ * frees when another job ends. An explicit `null` is a claim somebody has to read; an omitted key
+ * is invisible. That is the whole reason the two must not collapse into one answer: this is the
+ * server naming what `durableLimitCodes` otherwise makes every app name by hand, one code at a
+ * time, and keep in step with a backend it does not own.
+ *
+ * Present-and-`null` is the entire test. An absent key reads as `undefined`, so `=== null`
+ * already separates the claim from the silence and an `in` check would only widen it to every
+ * stated wait. Body-only by design: `Retry-After` has no spelling for "never".
+ *
+ * Not exported from the package, and that is the point: it is not "is this refusal durable?". It
+ * says nothing about a durable CODE or a wait too long to hold, so an error surface branching on
+ * it would answer differently from the retry rule for every limit the app names itself. The one
+ * question worth asking out loud is `shouldRetry`, and `describeError` already derives the
+ * control it offers from exactly that — invariant 8, one rule and two consumers.
+ */
+export function waitingNeverHelps(error) {
+    const details = error.details;
+    if (typeof details !== "object" || details === null)
+        return false;
+    return details.retryAfterSecs === null;
+}
 /**
  * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
  *

package/dist/api-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAS;IACf,IAAI,CAAqB;IACzB,UAAU,CAAqB;IAC/B,MAAM,CAA8C;IACpD,OAAO,CAAU;IACjB,SAAS,CAAqB;IACvC;;;;;;;;;OASG;IACM,cAAc,CAAqB;IAE5C;;;;;;;;OAQG;IACM,QAAQ,CAAU;IAE3B,YACE,MAAc,EACd,IAAkC,EAClC,OAKI,EAAE;QAEN,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,IAAI,mBAAmB,MAAM,GAAG,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,IAAI,EAAE,UAAU,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,cAAc,CAAC;IACpE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,KAAK,GAAI,OAAwC,CAAC,cAAc,CAAC;IACvE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC;IAC9D,MAAM,GAAG,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IAC1B,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,6FAA6F;IAC7F,yFAAyF;IACzF,uDAAuD;IACvD,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AACtE,CAAC"}
+{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"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"}

package/dist/query.d.ts

@@ -4,6 +4,10 @@ export interface QueryDefaultsOptions {
      * Error codes that mean "this limit does not clear by waiting" — a spent monthly quota, a
      * balance that needs topping up. They usually arrive as 402 or 429; the status alone cannot
      * tell them apart from a burst limit, which is why the caller names them.
+     *
+     * Only needed where the server does not say so itself. One that sends
+     * `details.retryAfterSecs: null` has already made the claim and `shouldRetry` reads it, which
+     * is one entry fewer to keep in step with a backend this app does not own.
      */
     durableLimitCodes?: readonly string[];
     /** How many times to retry a transient failure. Two donors used 2, one used 1. */

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA+B5D,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,iBAAiB,GAAE,SAAS,MAAM,EAAO,EACzC,gBAAgB,SAA8B,GAC7C,OAAO,CAcT;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKzE;AAED,wBAAgB,aAAa,CAAC,EAC5B,iBAAsB,EACtB,UAAc,EACd,gBAA8C,EAC9C,SAAyB,EACzB,MAAuB,EACvB,oBAA4B,GAC7B,GAAE,oBAAyB,GAAG,cAAc,CAe5C"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoC5D,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,iBAAiB,GAAE,SAAS,MAAM,EAAO,EACzC,gBAAgB,SAA8B,GAC7C,OAAO,CAqBT;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKzE;AAED,wBAAgB,aAAa,CAAC,EAC5B,iBAAsB,EACtB,UAAc,EACd,gBAA8C,EAC9C,SAAyB,EACzB,MAAuB,EACvB,oBAA4B,GAC7B,GAAE,oBAAyB,GAAG,cAAc,CAe5C"}

package/dist/query.js

@@ -1,4 +1,4 @@
-import { ApiError, retryAfterSecs } from "./api-error.js";
+import { ApiError, retryAfterSecs, waitingNeverHelps } from "./api-error.js";
 /**
  * react-query defaults — the merge of three repos that each got part of this right.
  *
@@ -19,6 +19,11 @@ import { ApiError, retryAfterSecs } from "./api-error.js";
  * 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.
  *
+ * The fifth rule came from the server half of this fleet rather than from a donor: a refusal can
+ * state that waiting will never fix it at all, by sending `details.retryAfterSecs: null`. Read as
+ * "did not say how long" — which is what every version before this one did — that 429 is retried
+ * against a limit no amount of time moves.
+ *
  * This is invariant 8.
  */
 /** 4xx statuses a second attempt can fix. Everything else in the 4xx family is an answer. */
@@ -37,6 +42,13 @@ export function shouldRetry(error, durableLimitCodes = [], maxRetryWaitSecs = DE
         return true;
     if (error.code !== undefined && durableLimitCodes.includes(error.code))
         return false;
+    // The same judgement, made by the server instead of by a list the app maintains: an explicit
+    // `details.retryAfterSecs: null` means waiting will never fix this. Checked before the stated
+    // wait because the two can contradict each other, and the `null` is written by whoever raised
+    // this particular refusal where a number can come from a limiter that attaches one to every
+    // 429 it emits.
+    if (waitingNeverHelps(error))
+        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);

package/dist/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,6FAA6F;AAC7F,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEpD,MAAM,2BAA2B,GAAG,EAAE,CAAC;AA8BvC;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc,EACd,oBAAuC,EAAE,EACzC,gBAAgB,GAAG,2BAA2B;IAE9C,wFAAwF;IACxF,wEAAwE;IACxE,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAErF,4FAA4F;IAC5F,4FAA4F;IAC5F,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,gBAAgB;QAAE,OAAO,KAAK,CAAC;IAE3D,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,YAAoB,EAAE,KAAc;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,YAAY,EAAE,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC;IACjD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAC5B,iBAAiB,GAAG,EAAE,EACtB,UAAU,GAAG,CAAC,EACd,gBAAgB,GAAG,2BAA2B,EAC9C,SAAS,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,EACzB,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EACvB,oBAAoB,GAAG,KAAK,MACJ,EAAE;IAC1B,OAAO;QACL,OAAO,EAAE;YACP,SAAS;YACT,MAAM;YACN,KAAK,EAAE,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,CAC7B,YAAY,GAAG,UAAU,IAAI,WAAW,CAAC,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,CAAC;YACtF,UAAU,EAAE,YAAY;YACxB,oBAAoB;YACpB,kBAAkB,EAAE,IAAI;SACzB;QACD,2FAA2F;QAC3F,yFAAyF;QACzF,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,6FAA6F;AAC7F,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEpD,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAkCvC;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc,EACd,oBAAuC,EAAE,EACzC,gBAAgB,GAAG,2BAA2B;IAE9C,wFAAwF;IACxF,wEAAwE;IACxE,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAErF,6FAA6F;IAC7F,8FAA8F;IAC9F,8FAA8F;IAC9F,4FAA4F;IAC5F,gBAAgB;IAChB,IAAI,iBAAiB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3C,4FAA4F;IAC5F,4FAA4F;IAC5F,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,gBAAgB;QAAE,OAAO,KAAK,CAAC;IAE3D,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,YAAoB,EAAE,KAAc;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,YAAY,EAAE,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC;IACjD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAC5B,iBAAiB,GAAG,EAAE,EACtB,UAAU,GAAG,CAAC,EACd,gBAAgB,GAAG,2BAA2B,EAC9C,SAAS,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,EACzB,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EACvB,oBAAoB,GAAG,KAAK,MACJ,EAAE;IAC1B,OAAO;QACL,OAAO,EAAE;YACP,SAAS;YACT,MAAM;YACN,KAAK,EAAE,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,CAC7B,YAAY,GAAG,UAAU,IAAI,WAAW,CAAC,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,CAAC;YACtF,UAAU,EAAE,YAAY;YACxB,oBAAoB;YACpB,kBAAkB,EAAE,IAAI;SACzB;QACD,2FAA2F;QAC3F,yFAAyF;QACzF,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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/api-error.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { ApiError, parseRetryAfter, retryAfterSecs } from "./api-error.ts";
+import { ApiError, parseRetryAfter, retryAfterSecs, waitingNeverHelps } from "./api-error.ts";
 
 /**
  * Two APIs, two places for the same fact: one states the wait in the `Retry-After` header (the
@@ -38,6 +38,51 @@ describe("retryAfterSecs", () => {
     expect(retryAfterSecs(new ApiError(429, { code: "X", message: "", details: null }))).toBeNull();
     expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
   });
+
+  // And it keeps answering `null` for a stated never, which is what its callers want: there is
+  // no countdown to show. The claim is a separate question, asked separately.
+  it("answers null for a stated never, same as for silence", () => {
+    const stated = new ApiError(429, {
+      code: "X",
+      message: "",
+      details: { retryAfterSecs: null },
+    });
+    expect(retryAfterSecs(stated)).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
+  });
+});
+
+/**
+ * The claim `retryAfterSecs` cannot carry: an explicit `null` in the body, meaning waiting will
+ * never fix this. It has to be told apart from an absent key, which is silence.
+ */
+describe("waitingNeverHelps", () => {
+  const withDetails = (details: unknown) => new ApiError(429, { code: "X", message: "", details });
+
+  it("reads a present null as the claim", () => {
+    expect(waitingNeverHelps(withDetails({ retryAfterSecs: null }))).toBe(true);
+  });
+
+  it("reads silence as no claim", () => {
+    expect(waitingNeverHelps(withDetails({ scope: "account" }))).toBe(false);
+    expect(waitingNeverHelps(withDetails({}))).toBe(false);
+    expect(waitingNeverHelps(new ApiError(429, null))).toBe(false);
+  });
+
+  it("reads a stated wait as no claim", () => {
+    expect(waitingNeverHelps(withDetails({ retryAfterSecs: 30 }))).toBe(false);
+    // The header is not a channel for this — there is no `Retry-After` that says "never".
+    expect(waitingNeverHelps(new ApiError(429, null, { retryAfterSecs: 30 }))).toBe(false);
+  });
+
+  // `details` is whatever the server put there, so the shape is a trust boundary. A JSON `null`
+  // is the one that bites: `typeof null` is `"object"`, so a missing guard reads a property off
+  // it and throws inside a retry rule.
+  it("survives a details that is not an object", () => {
+    expect(waitingNeverHelps(withDetails(null))).toBe(false);
+    expect(waitingNeverHelps(withDetails("nope"))).toBe(false);
+    expect(waitingNeverHelps(withDetails(7))).toBe(false);
+  });
 });
 
 /**

package/src/api-error.ts

@@ -70,6 +70,11 @@ export class ApiError extends Error {
  * The header first, because it is the standard one and it is what a limiter emits without being
  * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
  * caller asking "how long" should not have to know which server it is talking to.
+ *
+ * It deliberately does not answer whether waiting helps at all. `null` here means "no countdown
+ * to show", which is the right answer both for a refusal that said nothing and for one that said
+ * waiting will never fix it — and the adopters' countdown UIs read it for exactly that. Telling
+ * those two apart is {@link waitingNeverHelps}.
  */
 export function retryAfterSecs(error: ApiError): number | null {
   if (error.retryAfterSecs !== undefined) return error.retryAfterSecs;
@@ -79,6 +84,32 @@ export function retryAfterSecs(error: ApiError): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+/**
+ * Did the answer say, in so many words, that waiting will never fix this?
+ *
+ * The server half of this fleet sends `details.retryAfterSecs: null` on a refusal no amount of
+ * time clears — a cap that frees only when somebody deletes something, a concurrency slot that
+ * frees when another job ends. An explicit `null` is a claim somebody has to read; an omitted key
+ * is invisible. That is the whole reason the two must not collapse into one answer: this is the
+ * server naming what `durableLimitCodes` otherwise makes every app name by hand, one code at a
+ * time, and keep in step with a backend it does not own.
+ *
+ * Present-and-`null` is the entire test. An absent key reads as `undefined`, so `=== null`
+ * already separates the claim from the silence and an `in` check would only widen it to every
+ * stated wait. Body-only by design: `Retry-After` has no spelling for "never".
+ *
+ * Not exported from the package, and that is the point: it is not "is this refusal durable?". It
+ * says nothing about a durable CODE or a wait too long to hold, so an error surface branching on
+ * it would answer differently from the retry rule for every limit the app names itself. The one
+ * question worth asking out loud is `shouldRetry`, and `describeError` already derives the
+ * control it offers from exactly that — invariant 8, one rule and two consumers.
+ */
+export function waitingNeverHelps(error: ApiError): boolean {
+  const details = error.details;
+  if (typeof details !== "object" || details === null) return false;
+  return (details as { retryAfterSecs?: unknown }).retryAfterSecs === null;
+}
+
 /**
  * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
  *

package/src/query.test.ts

@@ -9,6 +9,14 @@ const refusal = (status: number, code?: string) =>
 const waited = (status: number, secs: number) =>
   new ApiError(status, null, { retryAfterSecs: secs });
 
+/** A refusal whose body says, in so many words, that waiting will never clear it. */
+const never = (status: number) =>
+  new ApiError(status, { code: "LIMIT_REACHED", message: "", details: { retryAfterSecs: null } });
+
+/** The same body with no such key: details, but no claim either way. */
+const silent = (status: number) =>
+  new ApiError(status, { code: "LIMIT_REACHED", message: "", details: { scope: "account" } });
+
 // 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", () => {
@@ -56,6 +64,38 @@ describe("shouldRetry", () => {
     expect(shouldRetry(refusal(503, "QUOTA_EXCEEDED"), ["QUOTA_EXCEEDED"])).toBe(false);
   });
 
+  // The same judgement with the server doing the naming. The server half of this fleet sends
+  // `details.retryAfterSecs: null` on a refusal no amount of time clears — a cap that frees only
+  // when somebody deletes something, a slot that frees when another job ends. Read as "nothing
+  // said how long", which is how every version before this one read it, that 429 gets retried
+  // against a limit that cannot move, and the app has to keep a `durableLimitCodes` entry for a
+  // claim the answer already carries.
+  it("does not retry a refusal whose body says waiting never helps", () => {
+    expect(shouldRetry(never(429))).toBe(false);
+    // And it outranks the status, exactly as a durable code does.
+    expect(shouldRetry(never(503))).toBe(false);
+  });
+
+  // The distinction the rule above rests on: an absent key is silence, not a claim, and silence
+  // has always meant "retry a transient failure". Only a key that is present and `null` is the
+  // claim — which is why this reads `=== null` and not `in`.
+  it("still retries when the body carries details but no stated wait", () => {
+    expect(shouldRetry(silent(500))).toBe(true);
+    expect(shouldRetry(silent(429))).toBe(true);
+  });
+
+  // A header wait and a body `null` contradict each other. The `null` is written by whoever
+  // raised this particular refusal; the number can come from a limiter that attaches one to
+  // every 429 it emits, so the hand-written claim is the more specific one.
+  it("takes an explicit never over a stated wait", () => {
+    const both = new ApiError(
+      429,
+      { code: "LIMIT_REACHED", message: "", details: { retryAfterSecs: null } },
+      { retryAfterSecs: 2 },
+    );
+    expect(shouldRetry(both)).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", () => {

package/src/query.ts

@@ -1,5 +1,5 @@
 import type { DefaultOptions } from "@tanstack/react-query";
-import { ApiError, retryAfterSecs } from "./api-error.ts";
+import { ApiError, retryAfterSecs, waitingNeverHelps } from "./api-error.ts";
 
 /**
  * react-query defaults — the merge of three repos that each got part of this right.
@@ -21,6 +21,11 @@ import { ApiError, retryAfterSecs } from "./api-error.ts";
  * 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.
  *
+ * The fifth rule came from the server half of this fleet rather than from a donor: a refusal can
+ * state that waiting will never fix it at all, by sending `details.retryAfterSecs: null`. Read as
+ * "did not say how long" — which is what every version before this one did — that 429 is retried
+ * against a limit no amount of time moves.
+ *
  * This is invariant 8.
  */
 
@@ -34,6 +39,10 @@ export interface QueryDefaultsOptions {
    * Error codes that mean "this limit does not clear by waiting" — a spent monthly quota, a
    * balance that needs topping up. They usually arrive as 402 or 429; the status alone cannot
    * tell them apart from a burst limit, which is why the caller names them.
+   *
+   * Only needed where the server does not say so itself. One that sends
+   * `details.retryAfterSecs: null` has already made the claim and `shouldRetry` reads it, which
+   * is one entry fewer to keep in step with a backend this app does not own.
    */
   durableLimitCodes?: readonly string[];
   /** How many times to retry a transient failure. Two donors used 2, one used 1. */
@@ -74,6 +83,13 @@ export function shouldRetry(
 
   if (error.code !== undefined && durableLimitCodes.includes(error.code)) return false;
 
+  // The same judgement, made by the server instead of by a list the app maintains: an explicit
+  // `details.retryAfterSecs: null` means waiting will never fix this. Checked before the stated
+  // wait because the two can contradict each other, and the `null` is written by whoever raised
+  // this particular refusal where a number can come from a limiter that attaches one to every
+  // 429 it emits.
+  if (waitingNeverHelps(error)) 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);