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

package/src/query-client.ts

@@ -0,0 +1,173 @@
+import { QueryClient, type QueryClientConfig } 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: ReadonlySet<number> = 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: number): boolean {
+  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: unknown): boolean {
+  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: number,
+  error: unknown,
+): boolean {
+  return failureCount < DEFAULT_MAX_RETRIES && isRetryableError(error);
+}
+
+/** The `queries` half of react-query's `DefaultOptions`, with no `undefined`. */
+type DefaultQueryOptions = NonNullable<
+  NonNullable<QueryClientConfig['defaultOptions']>['queries']
+>;
+
+/**
+ * `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: DefaultQueryOptions | undefined,
+): Partial<DefaultQueryOptions> {
+  if (!queries) return {};
+
+  return Object.fromEntries(
+    Object.entries(queries).filter(([, value]) => value !== undefined),
+  ) as Partial<DefaultQueryOptions>;
+}
+
+/**
+ * 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: QueryClientConfig = {}): QueryClient {
+  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/src/query-key.test.ts

@@ -0,0 +1,121 @@
+import { hashKey } from '@tanstack/react-query';
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildQueryApiKey,
+  canonicalizeQueryKeyValue,
+  sanitizeQueryInit,
+} from './query-key.js';
+
+describe('sanitizeQueryInit', () => {
+  it('is insensitive to param key order', () => {
+    const a = sanitizeQueryInit({ params: { query: { limit: 10, q: 'ada' } } });
+    const b = sanitizeQueryInit({ params: { query: { q: 'ada', limit: 10 } } });
+
+    expect(a).toEqual(b);
+    // Deep equality is not the point — the *serialized* form has to match, or
+    // partial-match invalidation and devtools output diverge.
+    expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+  });
+
+  it('sorts nested object keys, at every depth', () => {
+    const sanitized = sanitizeQueryInit({
+      body: { z: 1, a: { d: 4, b: 2 } },
+    });
+
+    expect(JSON.stringify(sanitized)).toBe(
+      '{"body":{"a":{"b":2,"d":4},"z":1}}',
+    );
+  });
+
+  it('strips undefined-valued properties', () => {
+    expect(
+      sanitizeQueryInit({
+        params: { query: { limit: 10, search: undefined } },
+      }),
+    ).toEqual({ query: { limit: 10 } });
+  });
+
+  it('collapses absent, empty, and all-undefined params to the same value', () => {
+    const forms = [
+      undefined,
+      {},
+      { params: {} },
+      { params: { query: {} } },
+      { params: { query: { limit: undefined } } },
+    ];
+
+    for (const form of forms) {
+      expect(sanitizeQueryInit(form)).toEqual({});
+    }
+  });
+
+  it('keeps array order and canonicalizes array members', () => {
+    const sanitized = sanitizeQueryInit({
+      params: { query: { ids: ['b', 'a'] } },
+      body: [{ y: 2, x: 1 }],
+    });
+
+    expect(JSON.stringify(sanitized)).toBe(
+      '{"query":{"ids":["b","a"]},"body":[{"x":1,"y":2}]}',
+    );
+  });
+
+  it('keeps path params, query params, and the body — and nothing else', () => {
+    const sanitized = sanitizeQueryInit({
+      params: {
+        path: { id: 'u1' },
+        query: { expand: 'roles' },
+        header: { authorization: 'Bearer secret' },
+        cookie: { session: 'secret' },
+      },
+      body: { name: 'Ada' },
+      signal: new AbortController().signal,
+      headers: { authorization: 'Bearer secret' },
+      baseUrl: 'https://other.test',
+      parseAs: 'text',
+      fetch: () => Promise.resolve(new Response()),
+    });
+
+    expect(sanitized).toEqual({
+      path: { id: 'u1' },
+      query: { expand: 'roles' },
+      body: { name: 'Ada' },
+    });
+  });
+
+  it('preserves a falsy body', () => {
+    expect(sanitizeQueryInit({ body: 0 })).toEqual({ body: 0 });
+    expect(sanitizeQueryInit({ body: null })).toEqual({ body: null });
+  });
+
+  it('leaves non-plain objects by reference', () => {
+    const date = new Date(0);
+    expect(canonicalizeQueryKeyValue(date)).toBe(date);
+  });
+});
+
+describe('buildQueryApiKey', () => {
+  it('derives [method, path, sanitized(init)]', () => {
+    expect(
+      buildQueryApiKey('get', '/users/{id}', {
+        params: { path: { id: 'u1' } },
+      }),
+    ).toEqual(['get', '/users/{id}', { path: { id: 'u1' } }]);
+  });
+
+  it('always emits three elements, so [method, path] prefix-matches', () => {
+    expect(buildQueryApiKey('get', '/users')).toEqual(['get', '/users', {}]);
+  });
+
+  it('hashes two orderings of the same request to one cache entry', () => {
+    const a = buildQueryApiKey('get', '/users', {
+      params: { query: { limit: 10, search: 'ada' } },
+    });
+    const b = buildQueryApiKey('get', '/users', {
+      params: { query: { search: 'ada', limit: 10 } },
+    });
+
+    expect(hashKey(a)).toBe(hashKey(b));
+  });
+});

package/src/query-key.ts

@@ -0,0 +1,113 @@
+/**
+ * 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]`.
+ */
+// `TPath` is deliberately unconstrained: `PathsWithMethod` resolves to
+// `keyof TPaths`, which TypeScript widens to `string | number | symbol` even
+// though a generated `paths` type only ever has string keys.
+export type QueryApiKey<TMethod = string, TPath = string> = readonly [
+  method: TMethod,
+  path: TPath,
+  init: SanitizedQueryInit,
+];
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto: unknown = 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: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(canonicalizeQueryKeyValue);
+  }
+
+  if (isPlainObject(value)) {
+    const canonical: Record<string, unknown> = {};
+
+    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: unknown,
+): Record<string, unknown> | undefined {
+  if (!isPlainObject(value)) return undefined;
+  const canonical = canonicalizeQueryKeyValue(value) as Record<string, unknown>;
+  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: unknown): SanitizedQueryInit {
+  if (!isPlainObject(init)) return {};
+
+  const params = isPlainObject(init.params) ? init.params : undefined;
+  const sanitized: SanitizedQueryInit = {};
+
+  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<TMethod extends string, TPath extends string>(
+  method: TMethod,
+  path: TPath,
+  init?: unknown,
+): QueryApiKey<TMethod, TPath> {
+  return [method, path, sanitizeQueryInit(init)];
+}
+
+/** The `${method} ${path}` token an endpoint is registered and matched under. */
+export function operationToken(method: string, path: string): string {
+  return `${method} ${path}`;
+}

package/src/tags.ts

@@ -0,0 +1,100 @@
+import { operationToken } from './query-key.js';
+
+// Ambient, package-local declaration — this package's `tsconfig.json` has no
+// `"types": ["node"]` reference, so `process` isn't otherwise a known global.
+// Declaring it as possibly `undefined` keeps the `typeof process` guard below
+// meaningful to the type checker without pulling in `@types/node`.
+declare const process: { env?: { NODE_ENV?: string } } | undefined;
+
+/**
+ * Bundlers statically replace `process.env.NODE_ENV`, so a production build
+ * collapses this to `false` and drops the warning call; the `typeof` guard
+ * keeps it safe to evaluate where no global `process` exists at all.
+ */
+const IS_DEV =
+  typeof process !== 'undefined' && process?.env?.NODE_ENV !== 'production';
+
+/**
+ * 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 function createTagRegistry<TTag extends string>(
+  vocabulary?: readonly TTag[],
+): TagRegistry<TTag> {
+  const known = vocabulary ? new Set<string>(vocabulary) : undefined;
+  const endpointsByTag = new Map<string, Set<string>>();
+  const warned = new Set<string>();
+
+  /** Names the vocabulary, for a message that has to report a tag outside it. */
+  const describeVocabulary = (declared: Set<string>): string =>
+    `Declared tags: ${[...declared].join(', ') || '(none)'}`;
+
+  // Both checks below read `known` directly rather than through a shared
+  // predicate: with no vocabulary there is no closed set, so no tag is unknown
+  // and neither branch is reachable.
+  const assertKnown = (tag: TTag): void => {
+    if (known && !known.has(tag)) {
+      throw new Error(
+        `http-client-react: unknown tag "${tag}". ${describeVocabulary(known)}`,
+      );
+    }
+  };
+
+  const acceptOrWarn = (tag: TTag): boolean => {
+    if (!known || known.has(tag)) return true;
+
+    if (IS_DEV && !warned.has(tag)) {
+      warned.add(tag);
+      console.warn(
+        `http-client-react: skipping unknown tag "${tag}" produced by an ` +
+          `invalidates callback — nothing was invalidated for it. ` +
+          describeVocabulary(known),
+      );
+    }
+
+    return false;
+  };
+
+  return {
+    assertKnown,
+    acceptOrWarn,
+    register: (tag, method, path) => {
+      assertKnown(tag);
+      const tokens = endpointsByTag.get(tag) ?? new Set<string>();
+      tokens.add(operationToken(method, path));
+      endpointsByTag.set(tag, tokens);
+    },
+    matches: (tag, queryKey) => {
+      const tokens = endpointsByTag.get(tag);
+      if (!tokens) return false;
+      const [method, path] = queryKey;
+      if (typeof method !== 'string' || typeof path !== 'string') return false;
+      return tokens.has(operationToken(method, path));
+    },
+    endpoints: (tag) => [...(endpointsByTag.get(tag) ?? [])],
+  };
+}