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

package/dist/query-api.d.ts

@@ -0,0 +1,114 @@
+import type { ApiClient, FetchResponse, HttpMethod, MaybeOptionalInit, MediaType, PathsWithMethod, RequiredKeysOf } from '@r0hitsharma/http-client-core';
+import type { DataTag, QueryClient, QueryFilters, QueryKey, SkipToken, UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
+import { HttpRequestError } from './errors.js';
+import { type QueryApiMiddleware } from './middleware.js';
+import { type QueryApiKey } from './query-key.js';
+/**
+ * The shape an `openapi-typescript`-generated `paths` type has: every path maps
+ * to an object carrying the HTTP methods that endpoint implements, plus the
+ * path-level `parameters`. This is the constraint on `createQueryApi` and on
+ * every option type below, and it is what makes `TPaths[TPath][TMethod]` legal.
+ *
+ * Every method is *optional* and typed `any` for two reasons that come straight
+ * from the generated output. `openapi-typescript` emits absent operations as
+ * `put?: never`, so a required key rejects real generated paths; and the
+ * operation payload has to widen to `any`, because narrowing it makes
+ * TypeScript resolve `TPaths[TPath][TMethod]` to `<payload> | undefined`, which
+ * then fails `FetchResponse`'s own `Record<string | number, any>` constraint.
+ * Nothing is lost by that: the operation types the api actually reports are
+ * read back off the caller's own `TPaths`, never off this shape.
+ *
+ * What it therefore does *not* do is reject a badly typed client. If the paths
+ * type behind `client` is not a paths map, inference finds no candidate for
+ * `TPaths` and falls back to this constraint, so `createQueryApi` still returns
+ * — as `QueryApi<QueryApiPaths>`, on which no `queryOptions` call typechecks.
+ * The rejection lands on the calls rather than on the construction.
+ */
+export type QueryApiPaths = Record<string, {
+    [TMethod in HttpMethod]?: any;
+} & {
+    parameters?: any;
+}>;
+/**
+ * Methods `queryOptions` accepts: the safe, bodyless, cacheable ones. A
+ * POST-backed read (`POST /search`) is deliberately out of v1 — see DESIGN.md.
+ */
+export type QueryApiQueryMethod = Extract<HttpMethod, 'get' | 'head'>;
+/** Methods `mutationOptions` accepts. */
+export type QueryApiMutationMethod = Extract<HttpMethod, 'post' | 'put' | 'patch' | 'delete'>;
+/**
+ * What a failed query or mutation rejects with. A request that reached the
+ * server rejects with {@link HttpRequestError} (status plus parsed error body);
+ * a transport failure or a middleware — response validation, for instance —
+ * rejects with whatever it threw. Narrow with `isHttpRequestError` before
+ * reading `status`.
+ */
+export type QueryApiError<TErrorBody> = HttpRequestError<TErrorBody> | Error;
+type InitWithUnknowns<TInit> = TInit & {
+    [key: string]: unknown;
+};
+type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => infer TSelected ? TSelected : TData;
+/** Per-call options for `queryOptions`: react-query's, plus cache tags. */
+export type QueryApiCallOptions<TQueryFnData, TError, TData, TKey extends QueryKey, TTag extends string> = Omit<UseQueryOptions<TQueryFnData, TError, TData, TKey>, 'queryKey' | 'queryFn'> & {
+    /** Tags this endpoint belongs to, for mutation-driven invalidation. */
+    tags?: readonly TTag[];
+    /** Middleware appended to the instance chain for this call only. */
+    middleware?: readonly QueryApiMiddleware[];
+};
+/**
+ * A tag to invalidate on mutation success, either fixed or derived from the
+ * mutation's own result and variables.
+ */
+export type MutationInvalidation<TTag extends string, TData, TVariables> = TTag | ((data: TData, variables: TVariables) => TTag | readonly TTag[]);
+/** Per-call options for `mutationOptions`: react-query's, plus `invalidates`. */
+export type QueryApiMutationCallOptions<TData, TError, TVariables, TOnMutateResult, TTag extends string> = Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey' | 'mutationFn'> & {
+    invalidates?: readonly MutationInvalidation<TTag, TData, TVariables>[];
+    /** Middleware appended to the instance chain for this call only. */
+    middleware?: readonly QueryApiMiddleware[];
+};
+export type QueryApiKeyFn<TPaths extends QueryApiPaths, TMedia extends MediaType> = <TMethod extends QueryApiQueryMethod, TPath extends PathsWithMethod<TPaths, TMethod>, TInit extends MaybeOptionalInit<TPaths[TPath], TMethod>, TResponse extends Required<FetchResponse<TPaths[TPath][TMethod], TInit, TMedia>>>(method: TMethod, path: TPath, ...[init]: RequiredKeysOf<TInit> extends never ? [init?: InitWithUnknowns<TInit>] : [init: InitWithUnknowns<TInit>]) => NoInfer<DataTag<QueryApiKey<TMethod, TPath>, TResponse['data'], QueryApiError<TResponse['error']>>>;
+export type QueryApiQueryOptionsFn<TPaths extends QueryApiPaths, TTag extends string, TMedia extends MediaType> = <TMethod extends QueryApiQueryMethod, TPath extends PathsWithMethod<TPaths, TMethod>, TInit extends MaybeOptionalInit<TPaths[TPath], TMethod>, TResponse extends Required<FetchResponse<TPaths[TPath][TMethod], TInit, TMedia>>, TOptions extends QueryApiCallOptions<TResponse['data'], QueryApiError<TResponse['error']>, InferSelectReturnType<TResponse['data'], TOptions['select']>, QueryApiKey<TMethod, TPath>, TTag>>(method: TMethod, path: TPath, ...[init, options]: RequiredKeysOf<TInit> extends never ? [init?: InitWithUnknowns<TInit>, options?: TOptions] : [init: InitWithUnknowns<TInit>, options?: TOptions]) => NoInfer<Omit<UseQueryOptions<TResponse['data'], QueryApiError<TResponse['error']>, InferSelectReturnType<TResponse['data'], TOptions['select']>, QueryApiKey<TMethod, TPath>>, 'queryKey' | 'queryFn'> & {
+    queryKey: DataTag<QueryApiKey<TMethod, TPath>, TResponse['data'], QueryApiError<TResponse['error']>>;
+    queryFn: Exclude<UseQueryOptions<TResponse['data'], QueryApiError<TResponse['error']>, InferSelectReturnType<TResponse['data'], TOptions['select']>, QueryApiKey<TMethod, TPath>>['queryFn'], SkipToken | undefined>;
+}>;
+export type QueryApiMutationOptionsFn<TPaths extends QueryApiPaths, TTag extends string, TMedia extends MediaType> = <TMethod extends QueryApiMutationMethod, TPath extends PathsWithMethod<TPaths, TMethod>, TInit extends MaybeOptionalInit<TPaths[TPath], TMethod>, TResponse extends Required<FetchResponse<TPaths[TPath][TMethod], TInit, TMedia>>, TOnMutateResult = unknown>(method: TMethod, path: TPath, options?: QueryApiMutationCallOptions<TResponse['data'], QueryApiError<TResponse['error']>, InitWithUnknowns<TInit>, TOnMutateResult, TTag>) => NoInfer<Omit<UseMutationOptions<TResponse['data'], QueryApiError<TResponse['error']>, InitWithUnknowns<TInit>, TOnMutateResult>, 'mutationKey' | 'mutationFn'> & {
+    mutationKey: readonly [method: TMethod, path: TPath];
+    mutationFn: NonNullable<UseMutationOptions<TResponse['data'], QueryApiError<TResponse['error']>, InitWithUnknowns<TInit>, TOnMutateResult>['mutationFn']>;
+}>;
+/** Instance-level configuration for {@link createQueryApi}. */
+export type QueryApiOptions<TTag extends string> = {
+    /**
+     * The tag vocabulary. Passing it both infers `TTag` (so `tags` and
+     * `invalidates` are checked against a closed set) and makes an unknown tag
+     * throw at runtime, which is what catches typos from untyped call sites.
+     */
+    tags?: readonly TTag[];
+    /** Middleware applied to every request from this instance, outermost first. */
+    middleware?: readonly QueryApiMiddleware[];
+};
+export type QueryApi<TPaths extends QueryApiPaths, TTag extends string = string, TMedia extends MediaType = MediaType> = {
+    /**
+     * The derived key for an operation, for targeting `getQueryData`,
+     * `setQueryData`, or `invalidateQueries` without a hand-built key factory.
+     * Slice it to `[method, path]` to target every cached variant of an endpoint.
+     */
+    queryKey: QueryApiKeyFn<TPaths, TMedia>;
+    queryOptions: QueryApiQueryOptionsFn<TPaths, TTag, TMedia>;
+    mutationOptions: QueryApiMutationOptionsFn<TPaths, TTag, TMedia>;
+    /** A react-query filter matching every query registered under `tag`. */
+    tagFilter: (tag: TTag) => QueryFilters;
+    invalidateTags: (client: QueryClient, tags: readonly TTag[]) => Promise<void>;
+    /** The `${method} ${path}` tokens currently registered under `tag`. */
+    taggedEndpoints: (tag: TTag) => readonly string[];
+};
+/**
+ * Binds a TanStack Query surface to an `openapi-fetch` client.
+ *
+ * The generated `TPaths` type is the only endpoint definition: methods, paths,
+ * params, request bodies, and response types are all read off it, and both
+ * `TPaths` and the tag vocabulary are inferred from the arguments — prefer
+ * `createQueryApi(client, { tags: [...] })` over passing type arguments
+ * explicitly, since naming one disables inference for the rest.
+ */
+export declare function createQueryApi<TPaths extends QueryApiPaths, TTag extends string = string, TMedia extends MediaType = MediaType>(client: ApiClient<TPaths, TMedia>, options?: QueryApiOptions<TTag>): QueryApi<TPaths, TTag, TMedia>;
+export {};

package/dist/query-api.js

@@ -0,0 +1,128 @@
+import { HttpRequestError } from './errors.js';
+import { composeMiddleware, } from './middleware.js';
+import { buildQueryApiKey } from './query-key.js';
+import { createTagRegistry } from './tags.js';
+/**
+ * Binds a TanStack Query surface to an `openapi-fetch` client.
+ *
+ * The generated `TPaths` type is the only endpoint definition: methods, paths,
+ * params, request bodies, and response types are all read off it, and both
+ * `TPaths` and the tag vocabulary are inferred from the arguments — prefer
+ * `createQueryApi(client, { tags: [...] })` over passing type arguments
+ * explicitly, since naming one disables inference for the rest.
+ */
+export function createQueryApi(client, options = {}) {
+    const registry = createTagRegistry(options.tags);
+    const instanceMiddleware = options.middleware ?? [];
+    const methods = client;
+    const send = async (ctx) => {
+        const method = ctx.method.toUpperCase();
+        const call = methods[method];
+        if (!call) {
+            throw new Error(`http-client-react: client has no ${method} method`);
+        }
+        const { data, error, response } = await call(ctx.path, ctx.init);
+        if (!response.ok || error !== undefined) {
+            throw new HttpRequestError({
+                method: ctx.method,
+                path: ctx.path,
+                body: error,
+                response,
+            });
+        }
+        // A HEAD response has no body by definition, so `openapi-fetch` resolves
+        // `data: undefined` whatever the status and whatever `Content-Length`
+        // claims — and it claims the size the matching GET would have returned, so
+        // the emptiness checks below do not catch it. react-query rejects
+        // `undefined` as query data.
+        if (method === 'HEAD')
+            return data ?? null;
+        // Same conversion for the other two ways a 2xx legitimately has no body.
+        if (response.status === 204 ||
+            response.headers.get('Content-Length') === '0') {
+            return data ?? null;
+        }
+        return data;
+    };
+    const request = (operationType, method, path, init, callMiddleware) => {
+        const chain = callMiddleware?.length
+            ? [...instanceMiddleware, ...callMiddleware]
+            : instanceMiddleware;
+        return composeMiddleware(chain, send)({
+            method,
+            path,
+            operationType,
+            init,
+        });
+    };
+    const tagFilter = (tag) => {
+        registry.assertKnown(tag);
+        return { predicate: (query) => registry.matches(tag, query.queryKey) };
+    };
+    const invalidateTags = async (client_, tags) => {
+        await Promise.all(tags.map((tag) => client_.invalidateQueries(tagFilter(tag))));
+    };
+    /**
+     * Runs after the mutation has already succeeded, which is what makes the
+     * asymmetry below the right one: a literal tag was checked when
+     * `mutationOptions` was called, so it can still throw; a tag a callback
+     * derives from the result can only be checked here, and throwing here would
+     * turn a successful mutation into a failed one and skip the caller's own
+     * `onSuccess`. So an unknown derived tag is warned about and dropped.
+     */
+    const resolveInvalidations = (invalidates, data, variables) => {
+        const resolved = new Set();
+        for (const entry of invalidates) {
+            if (typeof entry !== 'function') {
+                resolved.add(entry);
+                continue;
+            }
+            const produced = entry(data, variables);
+            for (const tag of typeof produced === 'string' ? [produced] : produced) {
+                if (registry.acceptOrWarn(tag))
+                    resolved.add(tag);
+            }
+        }
+        return [...resolved];
+    };
+    /**
+     * The public surface is the generic type above; the implementation is written
+     * against loose types and cast once, here. `query-api.types.test.ts` is what
+     * holds the two in agreement.
+     */
+    const api = {
+        queryKey: (method, path, init) => buildQueryApiKey(method, path, init),
+        queryOptions: (method, path, init, callOptions) => {
+            const { tags, middleware, ...queryRest } = callOptions ?? {};
+            for (const tag of tags ?? [])
+                registry.register(tag, method, path);
+            return {
+                ...queryRest,
+                queryKey: buildQueryApiKey(method, path, init),
+                queryFn: ({ signal }) => request('query', method, path, { ...init, signal }, middleware),
+            };
+        },
+        mutationOptions: (method, path, callOptions) => {
+            const { invalidates, middleware, onSuccess, ...mutationRest } = callOptions ?? {};
+            for (const entry of invalidates ?? []) {
+                if (typeof entry === 'string')
+                    registry.assertKnown(entry);
+            }
+            return {
+                ...mutationRest,
+                mutationKey: [method, path],
+                mutationFn: (variables) => request('mutation', method, path, variables, middleware),
+                onSuccess: async (data, variables, onMutateResult, context) => {
+                    if (invalidates?.length) {
+                        await invalidateTags(context.client, resolveInvalidations(invalidates, data, variables));
+                    }
+                    return await onSuccess?.(data, variables, onMutateResult, context);
+                },
+            };
+        },
+        tagFilter,
+        invalidateTags,
+        taggedEndpoints: registry.endpoints,
+    };
+    return api;
+}

package/dist/query-client.d.ts

@@ -0,0 +1,84 @@
+import { QueryClient, type QueryClientConfig } from '@tanstack/react-query';
+/**
+ * Whether a response status is worth asking for again.
+ *
+ * 5xx and the three transient 4xx statuses are; every other 4xx is not, and
+ * neither is anything below 400 — a 304 reaching the error path is a caching
+ * problem, not a flaky one.
+ */
+export declare function isRetryableHttpStatus(status: number): boolean;
+/**
+ * Whether a rejected query or mutation is worth retrying.
+ *
+ * A rejection carrying no status is retried by default: a DNS failure, a
+ * dropped connection, a CORS refusal, an abort, or a middleware that threw
+ * leaves no evidence beyond the request not completing, and treating an
+ * unrecognised rejection as fatal would make a single dropped socket a visible
+ * error.
+ *
+ * `ZodResponseValidationError` is the exception, and the reason this is not a
+ * bare `isHttpRequestError` check. It carries no status because
+ * `createZodResponseMiddleware` rejects *after* a 2xx arrived and parsed — the
+ * request completed, and the body it returned does not match the schema. That
+ * verdict is a property of the deployed server, so asking again produces the
+ * same mismatch two round trips later: exactly the cost this module's `retry`
+ * exists to avoid on a 422.
+ *
+ * Both checks narrow on `name` rather than `instanceof`, so they still hold
+ * when a consumer's module graph contains two copies of this package.
+ *
+ * Exported so a consumer can keep this status policy while changing how many
+ * times it asks again: `retry: (count, error) => count < 5 &&
+ * isRetryableError(error)` is five retries, so six attempts.
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * The retry predicate {@link createQueryClient} installs, in react-query's own
+ * `(failureCount, error)` shape. `failureCount` is the number of failures
+ * *before* this attempt, so it is 0 on the first rejection.
+ *
+ * Exported so a consumer can wrap it rather than restate it — dropping an
+ * application-specific error out of the policy, say:
+ *
+ * ```ts
+ * retry: (count, error) =>
+ *   isSessionExpired(error) ? false : shouldRetryRequest(count, error)
+ * ```
+ */
+export declare function shouldRetryRequest(failureCount: number, error: unknown): boolean;
+/**
+ * A `QueryClient` with defaults suited to a data-dense application, in place of
+ * react-query's, which are tuned for a document-shaped app:
+ *
+ * - **`refetchOnWindowFocus: false`.** Alt-tabbing back to a dashboard should
+ *   not reload every panel under the cursor. Freshness is the business of
+ *   `staleTime` and explicit invalidation, both of which the app controls.
+ * - **A status-aware `retry`** — see {@link shouldRetryRequest}. React-query
+ *   retries every rejection three times, so a 422 costs four round trips to
+ *   report a validation error the server already decided on the first.
+ *
+ * Mutations are deliberately left un-retried — react-query's default, and the
+ * right one, because a POST that reached the server may well have applied
+ * before the failure and this package cannot tell which.
+ *
+ * Everything else is left at react-query's default deliberately, `staleTime`
+ * most of all: how long a given screen may show a stale number is a product
+ * decision, and a package-level guess would be wrong quietly.
+ *
+ * `config` is react-query's own `QueryClientConfig` and every field of it wins.
+ * The merge is per-option rather than wholesale, so overriding one default
+ * keeps the others:
+ *
+ * ```ts
+ * // Keeps `refetchOnWindowFocus: false`; replaces only the retry policy.
+ * const queryClient = createQueryClient({
+ *   defaultOptions: { queries: { retry: 5 } },
+ * });
+ * ```
+ *
+ * A `queries` key present with the value `undefined` is *not* an override: it
+ * is dropped before the merge, so the else-branch of
+ * `retry: cond ? false : undefined` leaves the shipped policy standing rather
+ * than reverting it to react-query's `retry ?? 3`.
+ */
+export declare function createQueryClient(config?: QueryClientConfig): QueryClient;

package/dist/query-client.js

@@ -0,0 +1,152 @@
+import { QueryClient } from '@tanstack/react-query';
+import { isHttpRequestError } from './errors.js';
+import { isZodResponseValidationError } from './zod-response.js';
+/**
+ * The 4xx statuses that describe a *transient* condition rather than a bad
+ * request. Everything else in the 4xx range says the request itself is wrong —
+ * a 401, a 404, a 422 — and repeating it unchanged produces the same answer
+ * more slowly.
+ *
+ * - **408 Request Timeout** — the server gave up waiting for the request.
+ * - **425 Too Early** — a replay-risk refusal on an early-data TLS connection;
+ *   the retry goes out on the completed handshake.
+ * - **429 Too Many Requests** — rate limited, which is by definition temporary.
+ */
+const RETRYABLE_CLIENT_STATUSES = new Set([408, 425, 429]);
+/**
+ * Retries before a query is reported as failed. With react-query's default
+ * exponential `retryDelay` (1s, then 2s) this puts an error on screen about
+ * three seconds after the first failure — react-query's own default of 3 takes
+ * roughly seven, which is a long time for a panel to sit in a pending state
+ * over a fault that is not going to clear.
+ */
+const DEFAULT_MAX_RETRIES = 2;
+/**
+ * Whether a response status is worth asking for again.
+ *
+ * 5xx and the three transient 4xx statuses are; every other 4xx is not, and
+ * neither is anything below 400 — a 304 reaching the error path is a caching
+ * problem, not a flaky one.
+ */
+export function isRetryableHttpStatus(status) {
+    return status >= 500 || RETRYABLE_CLIENT_STATUSES.has(status);
+}
+/**
+ * Whether a rejected query or mutation is worth retrying.
+ *
+ * A rejection carrying no status is retried by default: a DNS failure, a
+ * dropped connection, a CORS refusal, an abort, or a middleware that threw
+ * leaves no evidence beyond the request not completing, and treating an
+ * unrecognised rejection as fatal would make a single dropped socket a visible
+ * error.
+ *
+ * `ZodResponseValidationError` is the exception, and the reason this is not a
+ * bare `isHttpRequestError` check. It carries no status because
+ * `createZodResponseMiddleware` rejects *after* a 2xx arrived and parsed — the
+ * request completed, and the body it returned does not match the schema. That
+ * verdict is a property of the deployed server, so asking again produces the
+ * same mismatch two round trips later: exactly the cost this module's `retry`
+ * exists to avoid on a 422.
+ *
+ * Both checks narrow on `name` rather than `instanceof`, so they still hold
+ * when a consumer's module graph contains two copies of this package.
+ *
+ * Exported so a consumer can keep this status policy while changing how many
+ * times it asks again: `retry: (count, error) => count < 5 &&
+ * isRetryableError(error)` is five retries, so six attempts.
+ */
+export function isRetryableError(error) {
+    if (isHttpRequestError(error))
+        return isRetryableHttpStatus(error.status);
+    return !isZodResponseValidationError(error);
+}
+/**
+ * The retry predicate {@link createQueryClient} installs, in react-query's own
+ * `(failureCount, error)` shape. `failureCount` is the number of failures
+ * *before* this attempt, so it is 0 on the first rejection.
+ *
+ * Exported so a consumer can wrap it rather than restate it — dropping an
+ * application-specific error out of the policy, say:
+ *
+ * ```ts
+ * retry: (count, error) =>
+ *   isSessionExpired(error) ? false : shouldRetryRequest(count, error)
+ * ```
+ */
+export function shouldRetryRequest(failureCount, error) {
+    return failureCount < DEFAULT_MAX_RETRIES && isRetryableError(error);
+}
+/**
+ * `queries` with its explicitly-`undefined` keys dropped, so that spreading it
+ * over the defaults cannot replace one with nothing.
+ *
+ * A spread does not distinguish an absent key from one present with the value
+ * `undefined`, and the second shape is ordinary in conditional config:
+ * `{ retry: cond ? false : undefined }`. Spread raw, that copies
+ * `retry: undefined` over {@link shouldRetryRequest}, react-query reads it as
+ * `retry ?? 3`, and the policy silently becomes retry-everything — while
+ * `refetchOnWindowFocus: false` survives the same spread, so the client still
+ * looks configured.
+ *
+ * Dropping the key instead is lossless: react-query resolves every one of these
+ * options with `?? <default>` or an `=== undefined` check, so a key that is
+ * absent and a key that is `undefined` already mean the same thing to it. There
+ * is no option for which "present but undefined" says something an explicit
+ * value could not say more clearly.
+ */
+function definedQueryOptions(queries) {
+    if (!queries)
+        return {};
+    return Object.fromEntries(Object.entries(queries).filter(([, value]) => value !== undefined));
+}
+/**
+ * A `QueryClient` with defaults suited to a data-dense application, in place of
+ * react-query's, which are tuned for a document-shaped app:
+ *
+ * - **`refetchOnWindowFocus: false`.** Alt-tabbing back to a dashboard should
+ *   not reload every panel under the cursor. Freshness is the business of
+ *   `staleTime` and explicit invalidation, both of which the app controls.
+ * - **A status-aware `retry`** — see {@link shouldRetryRequest}. React-query
+ *   retries every rejection three times, so a 422 costs four round trips to
+ *   report a validation error the server already decided on the first.
+ *
+ * Mutations are deliberately left un-retried — react-query's default, and the
+ * right one, because a POST that reached the server may well have applied
+ * before the failure and this package cannot tell which.
+ *
+ * Everything else is left at react-query's default deliberately, `staleTime`
+ * most of all: how long a given screen may show a stale number is a product
+ * decision, and a package-level guess would be wrong quietly.
+ *
+ * `config` is react-query's own `QueryClientConfig` and every field of it wins.
+ * The merge is per-option rather than wholesale, so overriding one default
+ * keeps the others:
+ *
+ * ```ts
+ * // Keeps `refetchOnWindowFocus: false`; replaces only the retry policy.
+ * const queryClient = createQueryClient({
+ *   defaultOptions: { queries: { retry: 5 } },
+ * });
+ * ```
+ *
+ * A `queries` key present with the value `undefined` is *not* an override: it
+ * is dropped before the merge, so the else-branch of
+ * `retry: cond ? false : undefined` leaves the shipped policy standing rather
+ * than reverting it to react-query's `retry ?? 3`.
+ */
+export function createQueryClient(config = {}) {
+    const { defaultOptions, ...rest } = config;
+    return new QueryClient({
+        ...rest,
+        defaultOptions: {
+            ...defaultOptions,
+            queries: {
+                refetchOnWindowFocus: false,
+                retry: shouldRetryRequest,
+                // Spread last: each `queries` option the caller actually gave a value
+                // replaces the default of the same name and leaves the rest standing.
+                ...definedQueryOptions(defaultOptions?.queries),
+            },
+        },
+    });
+}

package/dist/query-key.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The identity-bearing subset of an `openapi-fetch` request init, canonicalized
+ * so that two structurally equivalent requests produce one cache entry.
+ *
+ * Only path params, query params, and the request body identify a resource.
+ * Per-call transport concerns (`signal`, `fetch`, serializers, `headers`,
+ * `baseUrl`, `parseAs`) are deliberately excluded: they are either
+ * non-serializable, or — in the case of headers — carry credentials that have
+ * no business being visible in a cache key or in devtools.
+ */
+export type SanitizedQueryInit = {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+};
+/**
+ * The derived key shape: `[method, path, sanitized(init)]`. The first two
+ * elements are the operation itself, so react-query's default prefix matching
+ * invalidates every cached variant of an endpoint via `[method, path]`.
+ */
+export type QueryApiKey<TMethod = string, TPath = string> = readonly [
+    method: TMethod,
+    path: TPath,
+    init: SanitizedQueryInit
+];
+/**
+ * Recursively rewrites plain objects with their keys in sorted order and their
+ * `undefined`-valued properties removed. Arrays keep their order (query-array
+ * order is significant on the wire) and every other value is passed through by
+ * reference.
+ *
+ * react-query's own `hashKey` already sorts object keys before hashing, so this
+ * is not what makes two orderings hit the same cache entry. What it buys is
+ * everything that compares keys *structurally* rather than by hash: partial
+ * `invalidateQueries` matching (`partialDeepEqual` is order- and
+ * `undefined`-sensitive), `exact` filters, and reading a key in devtools.
+ */
+export declare function canonicalizeQueryKeyValue(value: unknown): unknown;
+/**
+ * Reduces an `openapi-fetch` init to its canonical, identity-bearing form.
+ *
+ * Empty and all-`undefined` param records collapse to absent, so
+ * `undefined`, `{}`, and `{ params: { query: { after: undefined } } }` all
+ * sanitize to the same value and therefore share a cache entry.
+ */
+export declare function sanitizeQueryInit(init: unknown): SanitizedQueryInit;
+/** Builds the untyped `[method, path, sanitized(init)]` key. */
+export declare function buildQueryApiKey<TMethod extends string, TPath extends string>(method: TMethod, path: TPath, init?: unknown): QueryApiKey<TMethod, TPath>;
+/** The `${method} ${path}` token an endpoint is registered and matched under. */
+export declare function operationToken(method: string, path: string): string;

package/dist/query-key.js

@@ -0,0 +1,70 @@
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Recursively rewrites plain objects with their keys in sorted order and their
+ * `undefined`-valued properties removed. Arrays keep their order (query-array
+ * order is significant on the wire) and every other value is passed through by
+ * reference.
+ *
+ * react-query's own `hashKey` already sorts object keys before hashing, so this
+ * is not what makes two orderings hit the same cache entry. What it buys is
+ * everything that compares keys *structurally* rather than by hash: partial
+ * `invalidateQueries` matching (`partialDeepEqual` is order- and
+ * `undefined`-sensitive), `exact` filters, and reading a key in devtools.
+ */
+export function canonicalizeQueryKeyValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalizeQueryKeyValue);
+    }
+    if (isPlainObject(value)) {
+        const canonical = {};
+        for (const key of Object.keys(value).sort()) {
+            const entry = canonicalizeQueryKeyValue(value[key]);
+            if (entry !== undefined)
+                canonical[key] = entry;
+        }
+        return canonical;
+    }
+    return value;
+}
+function canonicalizeRecord(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    const canonical = canonicalizeQueryKeyValue(value);
+    return Object.keys(canonical).length > 0 ? canonical : undefined;
+}
+/**
+ * Reduces an `openapi-fetch` init to its canonical, identity-bearing form.
+ *
+ * Empty and all-`undefined` param records collapse to absent, so
+ * `undefined`, `{}`, and `{ params: { query: { after: undefined } } }` all
+ * sanitize to the same value and therefore share a cache entry.
+ */
+export function sanitizeQueryInit(init) {
+    if (!isPlainObject(init))
+        return {};
+    const params = isPlainObject(init.params) ? init.params : undefined;
+    const sanitized = {};
+    const path = canonicalizeRecord(params?.path);
+    if (path)
+        sanitized.path = path;
+    const query = canonicalizeRecord(params?.query);
+    if (query)
+        sanitized.query = query;
+    const body = canonicalizeQueryKeyValue(init.body);
+    if (body !== undefined)
+        sanitized.body = body;
+    return sanitized;
+}
+/** Builds the untyped `[method, path, sanitized(init)]` key. */
+export function buildQueryApiKey(method, path, init) {
+    return [method, path, sanitizeQueryInit(init)];
+}
+/** The `${method} ${path}` token an endpoint is registered and matched under. */
+export function operationToken(method, path) {
+    return `${method} ${path}`;
+}

package/dist/tags.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Maps tags to the endpoints that carry them.
+ *
+ * Membership is recorded where the tag is declared — on the `queryOptions`
+ * call — so the query itself stays the single place an endpoint's cache
+ * behaviour is described. Nothing has to be mirrored into a second registry.
+ *
+ * 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.
+ */
+export type TagRegistry<TTag extends string> = {
+    register: (tag: TTag, method: string, path: string) => void;
+    assertKnown: (tag: TTag) => void;
+    /**
+     * Whether `tag` may be acted on, warning once per unknown tag rather than
+     * throwing. For tags that only materialize *after* a request has already
+     * succeeded — the ones an `invalidates` callback derives from a mutation's
+     * result — where a throw would report the successful mutation as failed.
+     */
+    acceptOrWarn: (tag: TTag) => boolean;
+    /** Whether a `[method, path, …]` query key belongs to `tag`. */
+    matches: (tag: TTag, queryKey: readonly unknown[]) => boolean;
+    /** The `${method} ${path}` tokens currently registered under `tag`. */
+    endpoints: (tag: TTag) => readonly string[];
+};
+export declare function createTagRegistry<TTag extends string>(vocabulary?: readonly TTag[]): TagRegistry<TTag>;