@r0hitsharma/http-client-react 0.12.0-rohit-fork-ci.1

package/DESIGN.md

@@ -0,0 +1,378 @@
+# http-client-react — design contract
+
+`@r0hitsharma/http-client-react` binds TanStack Query to an `openapi-fetch`
+client. This document is the authoritative statement of what the layer
+guarantees, what it deliberately refuses to do, and why.
+
+## Premise: the generated `paths` type is the endpoint definition
+
+There is exactly one description of the API in a consuming app: the
+`openapi-typescript` output. `createQueryApi` reads everything off it — which
+methods exist on which paths, what params and body each takes, what its 2xx
+response is, what its error responses are. Nothing is restated in a hand-written
+endpoint registry, a key factory, or a hooks file, because every restatement is
+a thing that can drift from the spec while still compiling.
+
+The consequence worth naming: **a mock layer belongs on the same premise.** The
+sibling `http-client-msw` package derives msw request handlers from the same
+`paths` type, so a fixture that no longer matches the API fails to typecheck
+rather than silently passing a test.
+
+## Verdict on `openapi-react-query`
+
+We considered depending on `openapi-react-query` (the openapi-ts ecosystem's own
+react-query binding) and **hand-rolled instead**, reusing its type *shape* as
+prior art.
+
+`openapi-react-query` implements exactly two things: a query key of
+`[method, path, init]`, and a `queryFn` that calls the client and re-throws
+`error`. Every v1 requirement here replaces one of them:
+
+1. **The key must be canonical.** Its key holds the caller's `init` verbatim, so
+   `{ limit, search }` and `{ search, limit }` are different keys for partial
+   matching, and a `signal` or a `headers` object in the init lands in the key.
+   We cannot fix that by overriding `queryKey`, because its `queryFn` reads the
+   init back *out of the key* — a sanitized key would change the request.
+2. **Failures must carry status and the parsed body.** It rethrows the bare error
+   body, which loses the status code. Its `queryFn` is internal, so this is not
+   overridable.
+3. **Middleware over the parsed result.** It has none, and `openapi-fetch`'s own
+   `use()` middleware works on `Request`/`Response`, which is the wrong altitude
+   for response validation.
+4. **Tags and invalidation.** It has none.
+
+So the dependency would have bought only the generic signature types — and those
+we can get from `openapi-fetch`'s own exported helpers (`MaybeOptionalInit`,
+`FetchResponse`) plus `openapi-typescript-helpers`, both already in the tree.
+Against that, it adds a package whose react-query and `openapi-fetch` peer
+ranges have to stay compatible with our exact pins, for code we override
+entirely. The hand-rolled version is ~250 lines of types and ~120 of runtime.
+
+What we *did* borrow, deliberately, is the generic signature shape:
+`<TMethod, TPath, TInit, TResponse, TOptions>` with the conditional
+`...[init, options]` tuple, the self-referential `TOptions` constraint that makes
+`select` infer, and `NoInfer` on the return type. That shape is well-tested
+upstream and reinventing it would have been strictly worse.
+
+One dependency was added: `openapi-typescript-helpers@0.1.0`, a types-only
+package that `openapi-fetch` already depends on, re-exported from
+http-client-core so both packages type against one pinned copy of the OpenAPI
+helper types.
+
+## Query key contract
+
+A key is always exactly three elements:
+
+```
+[method, path, sanitizeQueryInit(init)]
+```
+
+- `method` is the lowercase OpenAPI method; `path` is the path *template*, braces
+  intact. Together they are the operation, so `['get', '/users']` prefix-matches
+  every cached variant of that endpoint.
+- The third element is the **identity-bearing** part of the init only: path
+  params, query params, and the body, with object keys sorted at every depth and
+  `undefined`-valued properties removed. Arrays keep their order.
+- `undefined`, `{}`, `{ params: {} }`, and
+  `{ params: { query: { after: undefined } } }` all sanitize to `{}` and share a
+  cache entry.
+- Per-call transport concerns — `signal`, `fetch`, `headers`, `baseUrl`,
+  `parseAs`, the serializers — are **excluded**. They are either
+  non-serializable or, in the case of headers, credentials that have no business
+  being visible in a cache key or in devtools.
+
+react-query's own `hashKey` already sorts plain-object keys, so canonicalizing is
+not what makes two orderings hit the same entry. What it buys is everything that
+compares keys *structurally*: partial `invalidateQueries` matching
+(`partialDeepEqual` is order- and `undefined`-sensitive), `exact` filters, and a
+key you can read in devtools.
+
+**Consequence for header-varying responses.** Because headers are not part of
+identity, two requests that differ only by header share a cache entry. If a
+response genuinely varies by header (a tenant selector, say), spread the options
+and override `queryKey` yourself — the `queryFn` closes over the init rather
+than reading it out of the key, so a custom key still issues the right request.
+
+## Error contract
+
+`openapi-fetch` resolves both outcomes into `{ data, error }`; react-query only
+treats a rejection as failure. The `queryFn` converts:
+
+- Non-2xx (or any `error`) rejects with `HttpRequestError`, carrying `status`,
+  `statusText`, the parsed `body` typed from the operation's error responses, the
+  `method`/`path`, and the raw `Response`. `body` is `TBody | undefined`, not
+  `TBody`: a 5xx from something in front of the API, or any non-2xx with
+  `Content-Length: 0`, leaves `openapi-fetch` nothing to parse. Narrowing with
+  `isHttpRequestError` gets you `status` for free but still not a body.
+- A 204, or a response with `Content-Length: 0`, resolves to `null` — react-query
+  rejects `undefined` as query data.
+- A `HEAD` resolves to `null` unconditionally. A HEAD response has no body by
+  definition, so `openapi-fetch` parses none; its `Content-Length` echoes the
+  size the matching `GET` would have returned, so neither check above catches it.
+
+The declared error type is `HttpRequestError<TErrorBody> | Error`, not
+`HttpRequestError` alone. That is honest rather than convenient: a transport
+failure or a middleware (response validation, for instance) rejects with
+something that is not an HTTP error, so `status` is reachable only after
+`isHttpRequestError(error)`. The guard matches on `name` rather than `instanceof`
+so it survives a consumer ending up with two copies of the package.
+
+`createZodResponseMiddleware`'s rejection is the one of those with a guard of its
+own, `isZodResponseValidationError`, because the retry policy has to tell it from
+a transport failure — it is the only statusless rejection this package raises
+after the request completed.
+
+The guard takes **no body type parameter**. A check on `name` cannot say
+anything about the body's shape, so a parameter would only have let a call site
+name a type and get it back unchecked. It derives the body type from what the
+argument already declares instead: narrowing a `QueryApiError<TErrorBody>` keeps
+that operation's error body, and narrowing a `catch` binding keeps `unknown`.
+
+## Middleware contract
+
+`(ctx, next) => Promise<unknown>`, onion order: the instance chain outermost in
+declared order, a per-call chain appended innermost. `ctx` carries `method`,
+`path`, `operationType` (`'query' | 'mutation'`), and `init` — the init as it
+will be handed to `openapi-fetch`, including react-query's abort signal.
+
+Middleware sees the **parsed result**, not `Request`/`Response`. That is the
+altitude response validation, timing, and result shimming want. Anything that
+needs the raw HTTP objects belongs in `openapi-fetch`'s own `client.use()`.
+
+`next()` with no argument passes the context through; `next(ctx)` rewrites it for
+everything downstream. Not calling `next` at all short-circuits the chain with a
+substitute result. Calling it twice rejects rather than issuing the request
+twice — which also means **a middleware cannot retry**: it has no way to re-issue
+the request it is wrapping. Whole-operation retry is react-query's `retry`/
+`retryDelay`, which re-enter the chain from the top; transport-level retry
+belongs in the `fetch` handed to `createApiClient`, which owns the HTTP call.
+
+The one shipped middleware, `createZodResponseMiddleware`, validates bodies
+against the OpenAPI document through http-client-core's
+`getComponentSchemaFromOpenApi`, so the runtime schema and the static types come
+from the same spec. It **passes the body through unmodified** — it never
+substitutes zod's parse output, so the runtime value always matches the
+statically inferred one and no coercion happens behind the caller's back.
+Compiled schemas are memoized per middleware instance, because
+`z.fromJSONSchema` is far too expensive per request.
+
+## Tag contract
+
+Tags are declared in two places and nowhere else:
+
+- the vocabulary, on `createQueryApi(client, { tags })` — which both infers
+  `TTag` (so `tags` and `invalidates` are checked against a closed set) and makes
+  an unknown tag throw at runtime, catching typos from untyped call sites;
+- membership, on the `queryOptions` call that belongs to the tag.
+
+Membership is recorded where the query is described, so the query stays the
+single place its cache behaviour lives. On mutation success, tags resolved from
+`invalidates` are invalidated through the `QueryClient` react-query passes to the
+mutation callback — no `useQueryClient` at the call site, no `QueryClient`
+threaded into the api instance.
+
+**An unknown tag fails where it is written, not where it is used.** A literal in
+`tags` or `invalidates` is checked when the options are built — before anything
+has run — so it throws, which is what catches a typo from an untyped call site.
+A tag an `invalidates` callback derives from the mutation's result can only be
+checked after the mutation has already succeeded, and throwing there would report
+the succeeded mutation as failed and skip the caller's own `onSuccess`. So an
+unknown derived tag is dropped, with one `console.warn` per distinct tag per api
+instance in a non-production build. The mutation's outcome never depends on the
+tag vocabulary.
+
+**Granularity is per `${method} ${path}`, not per key.** Invalidating a tag
+invalidates every cached variant of the endpoints under it, whatever their
+params. That is what "refetch the user list" almost always means, and it keeps
+the registry bounded by endpoint count rather than by cache size. The corollary:
+two queries on one endpoint with different tags cannot be invalidated
+independently — use the key directly for that.
+
+### The registry's boundary
+
+A tag matches only the endpoints some `queryOptions` call has registered on this
+api instance, in this session. Registration happens as a side effect of building
+the options, so the registry is empty until the first call that declares a tag —
+and it is genuinely possible to have a cache entry that no `queryOptions` call
+ever described:
+
+- `queryClient.setQueryData(api.queryKey('get', '/positions'), …)` — a key
+  without options, written directly;
+- `prefetchQuery`/`fetchQuery` against `api.queryKey(…)` rather than against
+  `api.queryOptions(…)` — which drops more than the tag, and is written up in
+  full in [the README](./README.md#prefetching-pass-queryoptions-never-querykey);
+- SSR or persisted-cache **hydration**, which restores entries before any render
+  has run.
+
+Those entries are cached under a `[method, path, …]` key like any other, but the
+tag does not know the endpoint, so `invalidateTags` and `tagFilter` skip them
+silently. This is a real hole, not a theoretical one: the invalidation looks
+correct and simply does nothing.
+
+Two ways out, both explicit:
+
+1. **Register the endpoint once, at module scope.** Building the options is what
+   registers, so the result can be discarded — the call is the registration.
+
+   ```ts
+   // Registers `get /positions` under `positions` at import time, so a later
+   // hydrated or hand-written entry for it is in scope for the tag.
+   void api.queryOptions('get', '/positions', undefined, { tags: ['positions'] });
+   ```
+
+2. **Invalidate by key instead of by tag.** The first two elements of a key are
+   the operation and react-query prefix-matches, so
+   `invalidateQueries({ queryKey: ['get', '/positions'] })` reaches every cached
+   variant whether or not the registry has heard of it.
+
+The registry is deliberately not fixed by scanning the cache for `[method, path]`
+pairs: that would make a tag's membership depend on what happens to be cached at
+the moment of invalidation, which is a worse contract than one that is empty
+until declared.
+
+## QueryClient defaults
+
+`createQueryClient` exists because react-query's defaults are tuned for a
+document-shaped app and this package's consumers are not building one. Two are
+changed; the deliberate part is how few.
+
+**`refetchOnWindowFocus: false`.** The default is `true`, which means returning
+to a tab reissues every active query. On a dashboard that is a visible reload of
+panels the user was reading, triggered by an action that expressed no intent to
+reload. Freshness belongs to `staleTime` and to explicit invalidation, both of
+which the app already controls.
+
+The consequence is that **the app owns error recovery**: a mounted query that has
+exhausted its retries makes no further attempt on its own while the tab stays
+open and the connection stays up, and react-query keeps serving the last
+successful `data` beside `status: 'error'` — so a session that expired under an
+open dashboard reads as current numbers rather than as an empty panel.
+`refetchOnReconnect` and `refetchOnMount` are left at react-query's defaults, so
+a dropped connection returning or a remount still refetches; in between, showing
+the error and offering a refetch is the app's job, not this package's.
+
+**A status-aware `retry`.** The default retries every rejection three times. The
+policy here splits on what the status *says*: a 5xx is a well-formed request
+meeting an unwell server, so ask again; 408, 425, and 429 name transient
+conditions — a server-side request timeout, a TLS early-data refusal, rate
+limiting — so ask again; every other 4xx says the request itself is wrong, and
+repeating it unchanged buys nothing but latency. Below 400 is not retried
+either: a 304 on the error path is a caching bug.
+
+A rejection carrying no status is retried. That covers a dropped connection, a
+CORS refusal, an abort, and a middleware that threw, and it is the deliberately
+optimistic branch — the alternative, treating an unrecognised rejection as fatal,
+turns one dropped socket into an error state. The cost of being wrong is two
+extra requests; the cost of the other default is a screen that fails on a blip.
+
+One statusless rejection is exempt, and it is this package's own.
+`ZodResponseValidationError` has no status because `createZodResponseMiddleware`
+rejects *after* a 2xx arrived and parsed: the request completed, and the body the
+server sent will not have changed by the next attempt. Retrying it costs two more
+round trips to reach the same mismatch three seconds later — precisely the cost
+the status policy above exists to avoid on a 422. `isZodResponseValidationError`
+is what the predicate narrows with, on `name` rather than `instanceof`, for the
+same duplicate-copy reason as `isHttpRequestError`.
+
+Two retries rather than react-query's three, so that with the default
+exponential `retryDelay` an error surfaces in about three seconds instead of
+seven. A panel sitting pending over a fault that will not clear is worse than an
+error state that arrives promptly.
+
+**Mutations get nothing.** react-query already does not retry them, and it is
+right: a `POST` that failed after reaching the server may have applied, and
+nothing at this layer can distinguish that from one that did not.
+
+### What is not in the defaults
+
+**`staleTime`.** How long a screen may show a stale number is a product
+decision. A package-level value would be wrong silently, in whichever direction
+it was wrong.
+
+**A `QueryCache.onError` driven by per-query `meta`.** Every consumer wants one,
+which is an argument for shipping it, and the two reasons not to are both
+concrete. The half with the value in it is the sink — the app's toast or logger
+— which this package has no business owning. And typing the `meta` it reads
+requires augmenting react-query's `Register` interface, a global declaration
+that can be made exactly once in a module graph; making it here would collide
+with the app's own augmentation and leave the consumer worse off than if the
+package had stayed out of it. The README carries it as a recipe instead.
+
+### Overriding
+
+The retry policy has to be replaceable without giving up the rest, so
+`createQueryClient` takes react-query's own `QueryClientConfig` and merges it one
+option deep: a caller's `defaultOptions.queries.retry` replaces the default of
+that name and leaves `refetchOnWindowFocus` standing. Anything outside
+`defaultOptions` — `queryCache`, `mutationCache` — passes straight through.
+
+The `queries` merge drops the caller's explicitly-`undefined` keys first, and
+that step is the difference between a sound override and a silent one. A spread
+cannot tell an absent key from one present with the value `undefined`, and the
+second shape is how conditional config is ordinarily written:
+`{ retry: cond ? false : undefined }`. Spread raw, the else-branch copies
+`retry: undefined` over the predicate, react-query resolves it as `retry ?? 3`,
+and a mounted query asks four times where it should ask once — reinstating the
+retry-everything default this whole section exists to replace. Nothing looks
+wrong from outside, either: `refetchOnWindowFocus: false` survives the same
+spread, so the client still reads as configured. Dropping the key instead is
+lossless, because react-query resolves each of these options with `?? <default>`
+or an `=== undefined` check, so absent and `undefined` already mean the same
+thing to it — there is no option where "present but undefined" says something an
+explicit value could not say more plainly.
+
+For the middle case, where the status policy is right but the shape around it is
+not, the policy is exported in three pieces: `shouldRetryRequest` (the
+react-query-shaped predicate, for wrapping), `isRetryableError` (the error
+policy, for changing how many times a request is repeated), and
+`isRetryableHttpStatus` (the status policy alone). A consumer composes rather
+than restates, so a change to the status table reaches them.
+
+## Type-level guarantees
+
+`createQueryApi`'s implementation is written against loose types and cast once,
+at the return. `src/query-api.types.test.ts` is what holds the cast and the
+declared surface in agreement — it asserts data/error/param/variable inference
+and `@ts-expect-error`s the calls that must not compile. It is checked by
+`npm run type:check`, not by the vitest run.
+
+`TPaths` is constrained by `QueryApiPaths` on `createQueryApi` itself, not only
+inside the option types — the constraint is the same one either side, so there is
+one statement of what a paths type is. Its shape is dictated by the generated
+output: every method **optional**, because `openapi-typescript` emits absent
+operations as `put?: never`, and every operation payload `any`, because
+narrowing it makes `TPaths[TPath][TMethod]` resolve to `<payload> | undefined`,
+which fails `FetchResponse`'s own `Record<string | number, any>` constraint.
+Nothing is lost by the `any`: the types the api reports are read off the
+caller's `TPaths`, never off the constraint.
+
+The limit worth knowing: this rejects a bad *explicit* type argument, not a bad
+*client*. Given a client whose paths type is not a paths map, inference finds no
+candidate for `TPaths` and falls back to the constraint, so `createQueryApi`
+returns `QueryApi<QueryApiPaths>` — an api on which no `queryOptions` call
+typechecks. The error surfaces at the calls rather than at the construction.
+
+Both `queryKey` and `queryOptions` wrap their return in `NoInfer`. Without it, a
+contextual type on the result — the `queryKey` property of an
+`invalidateQueries` filter, say — becomes an inference site that leaves `TInit`
+unresolved and makes TypeScript demand the optional `init` argument.
+
+## Deliberately out of v1
+
+- **Optimistic updates and cache updaters.** No `onMutate` rollback helpers, no
+  string-DSL updaters. They need per-endpoint knowledge of how a mutation's
+  result maps into a query's shape, which is the one thing the OpenAPI document
+  does not describe. Invalidation is correct without that knowledge.
+- **Cross-tab sync.** No `BroadcastChannel`; use react-query's own persistence
+  and broadcast plugins if a consumer needs it.
+- **`POST`-backed reads.** `queryOptions` accepts `get` and `head` only. A
+  `POST /search` used as a read has to go through `mutationOptions` for now.
+- **Infinite queries and suspense wrappers.** Neither has a consumer yet; both
+  are additive.
+- **Header-varying cache identity.** See the query key contract above.
+
+## Deprecated
+
+`createQueryOptions(queryKey, queryFn)` — the pre-`createQueryApi` shim that
+takes a hand-written key and function. Kept working for existing call sites,
+marked `@deprecated`, and not to be used in new code.