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

package/README.md

@@ -0,0 +1,427 @@
+# @r0hitsharma/http-client-react
+
+TanStack Query bindings for `@r0hitsharma/http-client-core`.
+
+The generated OpenAPI `paths` type **is** the endpoint definition. Methods,
+paths, params, request bodies, response types, and error bodies are all read off
+it, so there is no second registry of endpoints to keep in step with the API.
+See [DESIGN.md](./DESIGN.md) for the contract and its deliberate limits.
+
+## Installation
+
+```bash
+npm install @r0hitsharma/http-client-react @r0hitsharma/http-client-core '@tanstack/react-query@^5.89.0' react react-dom
+```
+
+`@tanstack/react-query` is a **peer** dependency, so the app owns the version and
+the `QueryClient` this package's hooks and options talk to is the same instance
+the app's own `useQuery` calls use. See [peer
+dependencies](#peer-dependencies) for why the range starts at 5.89.0.
+
+## Usage
+
+### 1. Generate types and create the api
+
+```bash
+npx uikit-openapi-generate --schema openapi.json --output src/api.types.ts
+```
+
+```ts
+// src/api.ts
+import { createApiClient, createQueryApi } from '@r0hitsharma/http-client-react';
+
+import type { paths } from './api.types';
+
+const client = createApiClient<paths>('/api');
+
+// Both the paths type and the tag vocabulary are inferred from the arguments.
+// Do not pass type arguments explicitly: naming one turns inference off for the
+// rest, and `TTag` silently widens to `string`.
+export const api = createQueryApi(client, {
+  tags: ['positions', 'position', 'alerts'],
+});
+```
+
+### 2. Provide a QueryClient
+
+```tsx
+import { createQueryClient, HttpProvider } from '@r0hitsharma/http-client-react';
+
+const queryClient = createQueryClient();
+
+export function App() {
+  return (
+    <HttpProvider client={queryClient}>
+      <Dashboard />
+    </HttpProvider>
+  );
+}
+```
+
+`createQueryClient()` is a `QueryClient` with two defaults changed from
+react-query's, both because react-query's are tuned for a document-shaped app
+rather than a data-dense one:
+
+| Default | Value | Why |
+| --- | --- | --- |
+| `refetchOnWindowFocus` | `false` | Alt-tabbing back to a dashboard should not reload every panel. Freshness is `staleTime` and explicit invalidation, which the app controls. |
+| `retry` | status-aware | React-query retries every rejection three times, so a 422 costs four round trips to report a validation error the server decided on the first. |
+
+The retry policy, exactly:
+
+- **5xx** — retried. The request was well formed; the server was not well.
+- **408, 425, 429** — retried. Request timeout, TLS early-data refusal, and rate
+  limiting are all transient conditions rather than bad requests.
+- **every other 4xx** — not retried. A 401, a 404, a 422: repeating the request
+  unchanged produces the same answer more slowly.
+- **anything below 400** — not retried. A 304 on the error path is a caching
+  problem, not a flaky one.
+- **a rejection with no status at all** — retried. A dropped connection, a CORS
+  refusal, an abort, or a middleware that threw leaves no evidence except that
+  the request did not complete, and treating that as fatal makes one dropped
+  socket a visible error.
+- **a `ZodResponseValidationError`** — not retried, the one exception to the line
+  above. `createZodResponseMiddleware` rejects after a 2xx arrived and parsed, so
+  the request *did* complete and the body will be the same on the next attempt.
+
+Two retries, so with react-query's exponential `retryDelay` an error reaches the
+screen about three seconds after the first failure. Mutations are not retried at
+all — a `POST` that reached the server may have applied before the failure, and
+this package cannot tell which.
+
+With focus refetching off, **the app owns error recovery**. A query that has
+exhausted its retries will not try again on its own while the tab stays open and
+the connection stays up, and react-query keeps serving the last successful `data`
+next to `status: 'error'` — so an expired session reads as current numbers unless
+the screen says otherwise. Render the error and offer a refetch.
+
+Nothing else is set. `staleTime` most of all: how long a screen may show a stale
+number is a product decision, and a package-level guess would be wrong quietly.
+
+#### Changing the defaults
+
+`createQueryClient` takes react-query's own `QueryClientConfig` and every field
+of it wins. The merge is per-option, so replacing one default keeps the rest:
+
+```ts
+// Keeps `refetchOnWindowFocus: false`; replaces only the retry policy.
+const queryClient = createQueryClient({
+  defaultOptions: { queries: { retry: 5, staleTime: 30_000 } },
+});
+```
+
+A `queries` key present with the value `undefined` is **not** an override — it
+is dropped before the merge, and the default stands. So the else-branch of a
+conditional override leaves the shipped policy in place rather than reverting it
+to react-query's `retry ?? 3`:
+
+```ts
+// `retry` is the package predicate whenever `cond` is false.
+createQueryClient({
+  defaultOptions: { queries: { retry: cond ? false : undefined } },
+});
+```
+
+To keep the status policy and change only how many times it asks again, or to
+drop one error out of it, compose the exported predicates rather than restating
+them:
+
+```ts
+import {
+  createQueryClient,
+  isRetryableError,
+  shouldRetryRequest,
+} from '@r0hitsharma/http-client-react';
+
+createQueryClient({
+  defaultOptions: {
+    queries: {
+      // Same statuses, five retries — six attempts. `failureCount` is the
+      // number of failures *before* this attempt, so it is 0 on the first.
+      retry: (failureCount, error) => failureCount < 5 && isRetryableError(error),
+      // Or: the shipped policy, minus one application-specific error.
+      // retry: (count, error) =>
+      //   isSessionExpired(error) ? false : shouldRetryRequest(count, error),
+    },
+  },
+});
+```
+
+`isRetryableHttpStatus(status)` is exported too, for a predicate built from
+something other than an `HttpRequestError`.
+
+#### Reporting errors once, centrally
+
+Not shipped, deliberately: a `QueryCache.onError` that turns a failed query into
+a toast. The wiring is three lines, but the useful half of it is the sink — your
+notification system — and the `meta` field it reads has to be typed by
+augmenting react-query's `Register` interface, which is a *global* declaration
+an app can only make once. A package that made it would collide with the app's
+own. So this stays a recipe rather than an export:
+
+```ts
+// src/query-client.ts
+declare module '@tanstack/react-query' {
+  interface Register {
+    queryMeta: { errorMessage?: string };
+  }
+}
+
+export const queryClient = createQueryClient({
+  queryCache: new QueryCache({
+    onError: (error, query) => {
+      // Only queries that opted in by declaring the message.
+      const message = query.meta?.errorMessage;
+      if (message) toast.error(message, { description: error.message });
+    },
+  }),
+});
+```
+
+`meta` rides through on the per-call options: `api.queryOptions('get',
+'/positions', undefined, { meta: { errorMessage: 'Could not load positions' } })`.
+
+### 3. Query in a component
+
+```tsx
+import { isHttpRequestError } from '@r0hitsharma/http-client-react';
+import { useQuery } from '@tanstack/react-query';
+
+import { api } from './api';
+
+function PositionPanel({ id }: { id: string }) {
+  const { data, isPending, error } = useQuery(
+    api.queryOptions(
+      'get',
+      '/positions/{id}',
+      { params: { path: { id }, query: { expand: 'collateral' } } },
+      { tags: ['position'], staleTime: 30_000 },
+    ),
+  );
+
+  if (isPending) return <LoadingIndicator />;
+  if (error) {
+    // `status` and the parsed error body are only on HTTP failures; a transport
+    // error or a validation middleware rejects with a plain Error.
+    return (
+      <ErrorState
+        message={isHttpRequestError(error) ? `HTTP ${error.status}` : error.message}
+      />
+    );
+  }
+
+  return <PositionSummary position={data} />;
+}
+```
+
+`data` is typed from the operation's 2xx response, the `params` object is typed
+from its parameters, and the query key is derived — `['get', '/positions/{id}',
+{ path: { id }, query: { expand: 'collateral' } }]` — so two components asking
+for the same thing share one cache entry regardless of how they spell the init.
+
+### 4. Mutate, and invalidate by tag
+
+```tsx
+import { useMutation } from '@tanstack/react-query';
+
+import { api } from './api';
+
+function ClosePositionButton({ id }: { id: string }) {
+  const { mutate, isPending } = useMutation(
+    api.mutationOptions('post', '/positions/{id}/close', {
+      // A tag, or a callback that derives tags from the mutation's own result.
+      invalidates: ['position', (closed) => (closed.liquidated ? 'alerts' : [])],
+    }),
+  );
+
+  return (
+    <Button
+      disabled={isPending}
+      onClick={() => mutate({ params: { path: { id } } })}
+    >
+      Close
+    </Button>
+  );
+}
+```
+
+The mutation variables are the operation's init, so the body and params are
+typed. On success, every query registered under an invalidated tag is
+invalidated through the `QueryClient` react-query passes to the mutation — no
+`useQueryClient` call and no key factory at the call site.
+
+### 5. Middleware, including response validation
+
+```ts
+import {
+  createApiClient,
+  createQueryApi,
+  createZodResponseMiddleware,
+  type QueryApiMiddleware,
+} from '@r0hitsharma/http-client-react';
+
+import openApiDocument from '../openapi.json';
+import type { paths } from './api.types';
+
+const logSlowRequests: QueryApiMiddleware = async (ctx, next) => {
+  const startedAt = performance.now();
+  try {
+    return await next();
+  } finally {
+    const elapsed = performance.now() - startedAt;
+    if (elapsed > 1_000) {
+      console.warn(`slow ${ctx.method} ${ctx.path}: ${Math.round(elapsed)}ms`);
+    }
+  }
+};
+
+export const api = createQueryApi(createApiClient<paths>('/api'), {
+  tags: ['positions', 'position', 'alerts'],
+  middleware: [
+    logSlowRequests,
+    createZodResponseMiddleware({
+      document: openApiDocument,
+      schemas: { 'get /positions/{id}': 'Position' },
+      // Report drift instead of breaking the screen. Omit to reject instead.
+      onInvalid: (error) => console.warn(error.message, error.issues),
+    }),
+  ],
+});
+```
+
+Middleware is onion-style over the *parsed result*: `[a, b]` means `a` runs
+before `b` on the way in and after it on the way out. A per-call
+`middleware: [...]` on `queryOptions`/`mutationOptions` is appended innermost,
+which is how you opt one query into response validation rather than all of them.
+For middleware that needs the raw `Request`/`Response`, use `openapi-fetch`'s own
+`client.use()`.
+
+### Targeting the cache directly
+
+```ts
+// Exactly one query.
+queryClient.getQueryData(api.queryKey('get', '/positions/{id}', { params: { path: { id } } }));
+
+// Every cached variant of an endpoint — the key's first two elements are the
+// operation, and react-query prefix-matches.
+await queryClient.invalidateQueries({ queryKey: ['get', '/positions'] });
+
+// Everything under a tag.
+await api.invalidateTags(queryClient, ['positions']);
+```
+
+`sanitizeQueryInit` and `buildQueryApiKey` are exported for anything that needs
+to derive a key outside an api instance.
+
+### Prefetching: pass `queryOptions`, never `queryKey`
+
+`api.queryKey(…)` targets an entry that already exists. `api.queryOptions(…)`
+*describes* one. Prefetching creates an entry, so it takes the options:
+
+```ts
+// Right: one argument, and it is the whole options object.
+await queryClient.prefetchQuery(
+  api.queryOptions(
+    'get',
+    '/positions/{id}',
+    { params: { path: { id } } },
+    { tags: ['position'], staleTime: 30_000 },
+  ),
+);
+```
+
+```ts
+// Wrong, and it typechecks, and it warms the cache, and it still costs you.
+await queryClient.prefetchQuery({
+  queryKey: api.queryKey('get', '/positions/{id}', { params: { path: { id } } }),
+  queryFn: () => fetch(`/api/positions/${id}`).then((r) => r.json()),
+});
+```
+
+The key is identical in both, so the entry lands where the component will look
+for it and the prefetch appears to work. What the second form drops is
+everything else the options carry:
+
+- **`staleTime`.** Absent, it falls back to react-query's `0`, so the entry is
+  stale the instant it is written. The component mounts, reads it, and refetches
+  immediately — you paid for the request and saved nothing. This is the failure
+  that looks most like success: data does appear, just after a second round
+  trip.
+- **The middleware chain.** A hand-written `queryFn` bypasses the api instance
+  entirely, so response validation, auth headers, and every other middleware do
+  not run. The cached data was never checked, and the component that reads it
+  cannot tell.
+- **`tags`.** Registration is a side effect of building the options, so an entry
+  prefetched around them belongs to no tag and `invalidateTags` skips it
+  silently — see [the registry's boundary](./DESIGN.md#the-registrys-boundary).
+- **The error type.** `api.queryOptions` rejects with `HttpRequestError`; a raw
+  `fetch` resolves a 404 into whatever `r.json()` makes of the error body, and
+  the entry caches that as *data*.
+
+The same rule holds for `fetchQuery` and `ensureQueryData`, and for a router
+loader that warms the cache before a route renders. If you find yourself writing
+a `queryFn` next to an `api.queryKey(…)` call, the options object you want
+already exists.
+
+One caveat on the last line: `invalidateTags` reaches only the endpoints some
+`api.queryOptions(…, { tags })` call has registered. An entry written straight
+through `setQueryData`, or restored by SSR/persisted-cache hydration, is cached
+under a perfectly good key that the tag has never heard of, and the invalidation
+skips it silently. Register the endpoint once at module scope, or invalidate by
+key prefix — see [the registry's
+boundary](./DESIGN.md#the-registrys-boundary).
+
+## API surface
+
+| Export | What it does |
+| --- | --- |
+| `createQueryApi(client, options?)` | Binds a TanStack Query surface to an `openapi-fetch` client |
+| `api.queryOptions(method, path, init?, options?)` | `queryOptions` for a GET/HEAD operation, with a derived key |
+| `api.mutationOptions(method, path, options?)` | `mutationOptions` for a POST/PUT/PATCH/DELETE operation |
+| `api.queryKey(method, path, init?)` | The derived, branded query key for an operation |
+| `api.tagFilter(tag)` | A react-query filter matching every query under a tag |
+| `api.invalidateTags(queryClient, tags)` | Invalidates every query under the given tags |
+| `api.taggedEndpoints(tag)` | The `${method} ${path}` tokens registered under a tag |
+| `createZodResponseMiddleware(options)` | Validates responses against the OpenAPI document |
+| `ZodResponseValidationError` / `isZodResponseValidationError` | The validation failure that middleware raises, and its guard |
+| `HttpRequestError` / `isHttpRequestError` | The typed failure carrying `status` and the parsed error body |
+| `sanitizeQueryInit` / `buildQueryApiKey` / `canonicalizeQueryKeyValue` | The key-derivation primitives |
+| `composeMiddleware` | The middleware combinator, for composing chains outside an api |
+| `createQueryClient(config?)` | A `QueryClient` with dashboard defaults; `config` overrides per option |
+| `shouldRetryRequest(failureCount, error)` | The default retry predicate, for wrapping |
+| `isRetryableError(error)` / `isRetryableHttpStatus(status)` | The retry policy's two halves, for building a custom predicate |
+| `HttpProvider` | `QueryClientProvider` wrapper, defaulting to an internal client |
+| `createQueryOptions` | **Deprecated.** Hand-written key + fn shim; use `api.queryOptions` |
+
+## Not in v1
+
+Optimistic updates, cache updaters, cross-tab cache sync, infinite queries, and
+`POST`-backed reads are deliberately out of scope — see
+[DESIGN.md](./DESIGN.md#deliberately-out-of-v1). The mock layer is a separate
+package: [http-client-msw](../http-client-msw) keys its handlers off the same
+`paths` type, so a fixture and the request it stands in for are described by one
+source.
+
+## Peer dependencies
+
+- `react`, `react-dom` — `^19.0.0`
+- `@tanstack/react-query` — `^5.89.0`
+
+The react-query floor is not arbitrary. `mutationOptions` invalidates tags
+through the `QueryClient` react-query hands to the mutation callback, which means
+it needs the four-argument `onSuccess(data, variables, onMutateResult, context)`
+signature and `context.client`. Both arrived in **5.89.0**; the release before it
+(5.87.4) passes three arguments and no client, so the package does not typecheck
+against it. Anything from 5.89.0 up works — the package is developed against the
+latest 5.x.
+
+Keeping react-query a peer rather than a dependency is what guarantees one
+`QueryClient` and one cache: two copies in the module graph would give the
+`HttpProvider` and the app's own hooks separate caches.
+
+## See also
+
+- [http-client-core](../http-client-core) for the client factory and the
+  OpenAPI/zod helpers
+- [http-client-msw](../http-client-msw) for the mock layer keyed off the same
+  `paths` type

package/dist/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `openapi-fetch` resolves both outcomes of a request into `{ data, error }`,
+ * so a 404 is a fulfilled promise. TanStack Query only treats a *rejected*
+ * query function as a failure, so the query layer has to convert one into the
+ * other. This is the carrier for that conversion: it keeps the HTTP status and
+ * the parsed error body instead of flattening the failure to a message string.
+ */
+export declare class HttpRequestError<TBody = unknown> extends Error {
+    readonly name = "HttpRequestError";
+    /** Lowercase OpenAPI method (`get`, `post`, …) that failed. */
+    readonly method: string;
+    /** The OpenAPI path template, braces intact (`/users/{id}`). */
+    readonly path: string;
+    readonly status: number;
+    readonly statusText: string;
+    /**
+     * The response body parsed by `openapi-fetch`, typed from the operation's
+     * error responses — and `| undefined`, because a failure need not have one: a
+     * 5xx from a proxy, or any non-2xx with an empty body, leaves nothing to
+     * parse. Declaring it as `TBody` alone would let a consumer read through to a
+     * property of a body that is not there.
+     */
+    readonly body: TBody | undefined;
+    readonly response: Response;
+    constructor(init: {
+        method: string;
+        path: string;
+        body: TBody | undefined;
+        response: Response;
+    });
+}
+/**
+ * What {@link isHttpRequestError} narrows `TValue` to: the `HttpRequestError`
+ * member `TValue` already declares, so the body type the operation described
+ * survives the guard, and a bare `HttpRequestError` when `TValue` declares none
+ * — a `catch` binding, where no body type is knowable.
+ */
+type NarrowedHttpRequestError<TValue> = [
+    Extract<TValue, HttpRequestError<unknown>>
+] extends [never] ? HttpRequestError<unknown> : Extract<TValue, HttpRequestError<unknown>>;
+/**
+ * Narrows a caught value to {@link HttpRequestError}.
+ *
+ * Matches on `name` rather than `instanceof` so the guard still holds when a
+ * consumer ends up with two copies of this package in its module graph (a
+ * bundled app plus a linked workspace build, for instance).
+ *
+ * The body type is *derived* from the argument rather than taken as a type
+ * parameter. A runtime check on `name` can say nothing about the body's shape,
+ * so a `TBody` parameter would have let a call site name any type it liked and
+ * get it back unchecked; deriving it means narrowing a
+ * `QueryApiError<TErrorBody>` yields that operation's own error body, and
+ * narrowing an `unknown` yields `unknown` — which is the truth in both cases.
+ */
+export declare function isHttpRequestError<TValue>(value: TValue): value is TValue & NarrowedHttpRequestError<TValue>;
+export {};

package/dist/errors.js

@@ -0,0 +1,51 @@
+/**
+ * `openapi-fetch` resolves both outcomes of a request into `{ data, error }`,
+ * so a 404 is a fulfilled promise. TanStack Query only treats a *rejected*
+ * query function as a failure, so the query layer has to convert one into the
+ * other. This is the carrier for that conversion: it keeps the HTTP status and
+ * the parsed error body instead of flattening the failure to a message string.
+ */
+export class HttpRequestError extends Error {
+    name = 'HttpRequestError';
+    /** Lowercase OpenAPI method (`get`, `post`, …) that failed. */
+    method;
+    /** The OpenAPI path template, braces intact (`/users/{id}`). */
+    path;
+    status;
+    statusText;
+    /**
+     * The response body parsed by `openapi-fetch`, typed from the operation's
+     * error responses — and `| undefined`, because a failure need not have one: a
+     * 5xx from a proxy, or any non-2xx with an empty body, leaves nothing to
+     * parse. Declaring it as `TBody` alone would let a consumer read through to a
+     * property of a body that is not there.
+     */
+    body;
+    response;
+    constructor(init) {
+        super(`${init.method.toUpperCase()} ${init.path} failed with status ${init.response.status}`);
+        this.method = init.method;
+        this.path = init.path;
+        this.status = init.response.status;
+        this.statusText = init.response.statusText;
+        this.body = init.body;
+        this.response = init.response;
+    }
+}
+/**
+ * Narrows a caught value to {@link HttpRequestError}.
+ *
+ * Matches on `name` rather than `instanceof` so the guard still holds when a
+ * consumer ends up with two copies of this package in its module graph (a
+ * bundled app plus a linked workspace build, for instance).
+ *
+ * The body type is *derived* from the argument rather than taken as a type
+ * parameter. A runtime check on `name` can say nothing about the body's shape,
+ * so a `TBody` parameter would have let a call site name any type it liked and
+ * get it back unchecked; deriving it means narrowing a
+ * `QueryApiError<TErrorBody>` yields that operation's own error body, and
+ * narrowing an `unknown` yields `unknown` — which is the truth in both cases.
+ */
+export function isHttpRequestError(value) {
+    return value instanceof Error && value.name === 'HttpRequestError';
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { type QueryClient } from '@tanstack/react-query';
+import type { PropsWithChildren } from 'react';
+export { createApiClient } from '@r0hitsharma/http-client-core';
+export type { ApiClient, ApiClientOptions, JsonSchema, } from '@r0hitsharma/http-client-core';
+export { createQueryApi } from './query-api.js';
+export type { MutationInvalidation, QueryApi, QueryApiCallOptions, QueryApiError, QueryApiKeyFn, QueryApiMutationCallOptions, QueryApiMutationMethod, QueryApiMutationOptionsFn, QueryApiOptions, QueryApiPaths, QueryApiQueryMethod, QueryApiQueryOptionsFn, } from './query-api.js';
+export { HttpRequestError, isHttpRequestError } from './errors.js';
+export { composeMiddleware } from './middleware.js';
+export type { QueryApiMiddleware, QueryApiNext, QueryApiOperationType, QueryApiRequestContext, } from './middleware.js';
+export { buildQueryApiKey, canonicalizeQueryKeyValue, operationToken, sanitizeQueryInit, } from './query-key.js';
+export type { QueryApiKey, SanitizedQueryInit } from './query-key.js';
+export { createQueryClient, isRetryableError, isRetryableHttpStatus, shouldRetryRequest, } from './query-client.js';
+export { createZodResponseMiddleware, isZodResponseValidationError, ZodResponseValidationError, } from './zod-response.js';
+export type { ResponseSchemaSource, ResponseValidationIssue, ZodResponseMiddlewareOptions, } from './zod-response.js';
+export type HttpProviderProps = PropsWithChildren<{
+    client?: QueryClient;
+}>;
+export declare function HttpProvider({ client, children }: HttpProviderProps): import("react").JSX.Element;
+/**
+ * @deprecated Use `createQueryApi(client).queryOptions(method, path, init)`
+ * instead: it derives the query key from the operation, types the result from
+ * the OpenAPI response, and rejects with a typed error. This shim keeps working
+ * for the hand-written query keys that predate it.
+ */
+export declare function createQueryOptions<TData>(queryKey: readonly unknown[], queryFn: () => Promise<TData>): import("@tanstack/query-core").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<TData, Error, TData, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/query-core").QueryFunction<TData, readonly unknown[], never> | undefined;
+} & import("@tanstack/query-core").QueryKeyWithDataTag<readonly unknown[], TData, Error>;

package/dist/index.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { queryOptions, QueryClientProvider, } from '@tanstack/react-query';
+import { createQueryClient } from './query-client.js';
+export { createApiClient } from '@r0hitsharma/http-client-core';
+export { createQueryApi } from './query-api.js';
+export { HttpRequestError, isHttpRequestError } from './errors.js';
+export { composeMiddleware } from './middleware.js';
+export { buildQueryApiKey, canonicalizeQueryKeyValue, operationToken, sanitizeQueryInit, } from './query-key.js';
+export { createQueryClient, isRetryableError, isRetryableHttpStatus, shouldRetryRequest, } from './query-client.js';
+export { createZodResponseMiddleware, isZodResponseValidationError, ZodResponseValidationError, } from './zod-response.js';
+/**
+ * The client `HttpProvider` falls back to when the app does not pass one. A
+ * single module-scoped instance, so every consumer of the fallback shares one
+ * cache — but prefer creating it in the app: the fallback cannot be reset
+ * between tests and cannot be reached for `setQueryData` before render.
+ */
+const defaultQueryClient = createQueryClient();
+export function HttpProvider({ client, children }) {
+    return (_jsx(QueryClientProvider, { client: client ?? defaultQueryClient, children: children }));
+}
+/**
+ * @deprecated Use `createQueryApi(client).queryOptions(method, path, init)`
+ * instead: it derives the query key from the operation, types the result from
+ * the OpenAPI response, and rejects with a typed error. This shim keeps working
+ * for the hand-written query keys that predate it.
+ */
+export function createQueryOptions(queryKey, queryFn) {
+    return queryOptions({ queryKey, queryFn });
+}

package/dist/middleware.d.ts

@@ -0,0 +1,45 @@
+/** Which half of the API a request came from. */
+export type QueryApiOperationType = 'query' | 'mutation';
+/**
+ * What a middleware sees. `init` is the init as it will be handed to
+ * `openapi-fetch` — the caller's init plus the abort `signal` react-query
+ * supplies — not the sanitized cache-key form.
+ */
+export type QueryApiRequestContext = {
+    /** Lowercase OpenAPI method (`get`, `post`, …). */
+    readonly method: string;
+    /** The OpenAPI path template, braces intact (`/users/{id}`). */
+    readonly path: string;
+    readonly operationType: QueryApiOperationType;
+    readonly init: Record<string, unknown> | undefined;
+};
+/**
+ * Invokes the rest of the chain. Called with no argument to pass the context
+ * through unchanged, or with a replacement to rewrite the request downstream.
+ */
+export type QueryApiNext = (ctx?: QueryApiRequestContext) => Promise<unknown>;
+/**
+ * Onion-style middleware over the *parsed result* of a request, not over
+ * `Request`/`Response`. That is the altitude for response validation, logging
+ * and timing, rewriting the request on the way in (`next(ctx)`), reshaping the
+ * result on the way out, and short-circuiting with a substitute result by never
+ * calling `next` at all.
+ *
+ * **Not retries.** `next` is single-use per invocation — a second call rejects —
+ * so a middleware cannot re-issue the request it is wrapping. Retrying belongs
+ * either to react-query, whose `retry`/`retryDelay` re-invoke the whole chain
+ * from the top, or to the `fetch` implementation handed to `createApiClient`,
+ * which owns the actual HTTP call. `openapi-fetch`'s own `use()` middleware
+ * remains available on the client for anything that needs the raw HTTP objects.
+ */
+export type QueryApiMiddleware = (ctx: QueryApiRequestContext, next: QueryApiNext) => Promise<unknown>;
+type TerminalHandler = (ctx: QueryApiRequestContext) => Promise<unknown>;
+/**
+ * Folds `middleware` around `terminal`, outermost first: given `[a, b]`, `a`
+ * runs before `b` on the way in and after `b` on the way out.
+ *
+ * Each composed handler is single-use per invocation — calling `next()` twice
+ * from one middleware rejects rather than issuing the request twice.
+ */
+export declare function composeMiddleware(middleware: readonly QueryApiMiddleware[], terminal: TerminalHandler): TerminalHandler;
+export {};

package/dist/middleware.js

@@ -0,0 +1,25 @@
+/**
+ * Folds `middleware` around `terminal`, outermost first: given `[a, b]`, `a`
+ * runs before `b` on the way in and after `b` on the way out.
+ *
+ * Each composed handler is single-use per invocation — calling `next()` twice
+ * from one middleware rejects rather than issuing the request twice.
+ */
+export function composeMiddleware(middleware, terminal) {
+    if (middleware.length === 0)
+        return terminal;
+    return (ctx) => {
+        let called = -1;
+        const dispatch = (index, current) => {
+            if (index <= called) {
+                return Promise.reject(new Error('http-client-react: middleware called next() more than once'));
+            }
+            called = index;
+            const handler = middleware[index];
+            if (!handler)
+                return terminal(current);
+            return handler(current, (nextCtx) => dispatch(index + 1, nextCtx ?? current));
+        };
+        return dispatch(0, ctx);
+    };
+}