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

package/src/query-api.types.test.ts

@@ -0,0 +1,225 @@
+import { type ApiClient, createApiClient } from '@r0hitsharma/http-client-core';
+import { useQuery } from '@tanstack/react-query';
+import type { DataTag, QueryClient } from '@tanstack/react-query';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { type HttpRequestError, isHttpRequestError } from './errors.js';
+import { createQueryApi } from './query-api.js';
+import type { QueryApi, QueryApiPaths } from './query-api.js';
+import type { ApiFault, TestPaths, User } from './test-fixtures.js';
+
+/**
+ * Type-level coverage of the inference the whole design rests on: methods,
+ * paths, params, request bodies, and response types all come off the generated
+ * `TPaths` type, and the single cast inside `createQueryApi` still lines up with
+ * the generic surface it claims.
+ *
+ * `expectTypeOf` and `@ts-expect-error` are checked by `npm run type:check`, so
+ * the assertions live in functions that are never called — several of them would
+ * throw or issue requests if they ran, and one calls `useQuery` outside a React
+ * render purely to borrow its overload resolution.
+ */
+
+const client = createApiClient<TestPaths>('https://api.test');
+const api = createQueryApi(client, { tags: ['users', 'user'] });
+
+/**
+ * Stands in for `useQuery`, reading the data and error types back out of the
+ * branded query key so both can be asserted without rendering a hook.
+ */
+declare function readTags<TData, TError>(options: {
+  queryKey: DataTag<readonly unknown[], TData, TError>;
+}): { data: TData; error: TError };
+
+type ResolvedQueryFn<
+  TOptions extends { queryFn: (...args: never[]) => unknown },
+> = Awaited<ReturnType<TOptions['queryFn']>>;
+
+describe('createQueryApi — inference', () => {
+  // A real assertion rather than a placeholder: the file's whole premise is
+  // that this api instance was constructed, and everything asserted below is
+  // about the options it builds.
+  it('builds options whose key is the operation', () => {
+    expect(api.queryOptions('get', '/users').queryKey).toEqual([
+      'get',
+      '/users',
+      {},
+    ]);
+  });
+});
+
+export function typeAssertions(): void {
+  // The tag vocabulary narrows `TTag` — no explicit type argument needed.
+  expectTypeOf(api.tagFilter).parameter(0).toEqualTypeOf<'users' | 'user'>();
+  expectTypeOf(api.taggedEndpoints)
+    .parameter(0)
+    .toEqualTypeOf<'users' | 'user'>();
+
+  // Response data comes from the operation's 2xx response.
+  const listOptions = api.queryOptions('get', '/users', {
+    params: { query: { limit: 10 } },
+  });
+  expectTypeOf<ResolvedQueryFn<typeof listOptions>>().toEqualTypeOf<User[]>();
+
+  const listResult = readTags(listOptions);
+  expectTypeOf(listResult.data).toEqualTypeOf<User[]>();
+  expectTypeOf(listResult.error).toEqualTypeOf<
+    HttpRequestError<ApiFault> | Error
+  >();
+
+  // The derived key is `[method, path, sanitized(init)]`.
+  expectTypeOf(listOptions.queryKey).toExtend<
+    readonly ['get', '/users', { query?: Record<string, unknown> }]
+  >();
+
+  const detailOptions = api.queryOptions('get', '/users/{id}', {
+    params: { path: { id: 'u1' } },
+  });
+  expectTypeOf<ResolvedQueryFn<typeof detailOptions>>().toEqualTypeOf<User>();
+  expectTypeOf(readTags(detailOptions).error).toEqualTypeOf<
+    HttpRequestError<ApiFault> | Error
+  >();
+
+  // Narrowing needs no body type parameter: the guard filters the declared
+  // union, so the operation's own error body survives it — and stays optional,
+  // because a failure need not carry a body at all.
+  const failure = readTags(detailOptions).error;
+  if (isHttpRequestError(failure)) {
+    expectTypeOf(failure.body).toEqualTypeOf<ApiFault | undefined>();
+  }
+
+  // A `catch` binding declares nothing, so the body stays `unknown` — the guard
+  // has no type parameter with which to claim otherwise.
+  const caught = failure as unknown;
+  if (isHttpRequestError(caught)) {
+    expectTypeOf(caught.status).toEqualTypeOf<number>();
+    expectTypeOf(caught.body).toEqualTypeOf<unknown>();
+  }
+
+  // `select` retypes what a component reads without losing the fetched type.
+  const selectedOptions = api.queryOptions('get', '/users', undefined, {
+    select: (users) => users.length,
+  });
+  expectTypeOf(selectedOptions.select).parameter(0).toEqualTypeOf<User[]>();
+
+  // The assertion that matters: the options' `TData` is the *selected* type, so
+  // this is what a component reads. Asserted through the real `useQuery` rather
+  // than a stand-in, since matching its overload resolution is the point.
+  // This function never runs, so these two are type-level calls only — they
+  // borrow `useQuery`'s overload resolution rather than invoking a hook.
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  expectTypeOf(useQuery(selectedOptions).data).toEqualTypeOf<
+    number | undefined
+  >();
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  expectTypeOf(useQuery(listOptions).data).toEqualTypeOf<User[] | undefined>();
+
+  // And the key's brand still carries the *fetched* type, not the selected one:
+  // `getQueryData` on this key hands back what the endpoint returned.
+  expectTypeOf(readTags(selectedOptions).data).toEqualTypeOf<User[]>();
+
+  // HEAD is in the query method union, so a declared HEAD operation has to be
+  // reachable through it — and only on the path that declares one.
+  const headOptions = api.queryOptions('head', '/users', {
+    params: { query: { search: 'ada' } },
+  });
+  expectTypeOf(headOptions.queryKey).toExtend<
+    readonly ['head', '/users', { query?: Record<string, unknown> }]
+  >();
+
+  // @ts-expect-error — /users/{id} declares no HEAD operation
+  api.queryOptions('head', '/users/{id}', { params: { path: { id: 'u1' } } });
+
+  // @ts-expect-error — `params.path.id` is required by the operation
+  api.queryOptions('get', '/users/{id}');
+
+  // @ts-expect-error — `id` must be a string
+  api.queryOptions('get', '/users/{id}', { params: { path: { id: 7 } } });
+
+  // @ts-expect-error — the path is not in TestPaths
+  api.queryOptions('get', '/unknown');
+
+  // @ts-expect-error — /users has no DELETE operation
+  api.queryOptions('delete', '/users');
+
+  // @ts-expect-error — mutating methods do not belong on queryOptions
+  api.queryOptions('post', '/users');
+
+  // @ts-expect-error — 'orders' is not in the declared tag vocabulary
+  api.queryOptions('get', '/users', undefined, { tags: ['orders'] });
+
+  // Mutations: variables are the operation's init, data is the 2xx body.
+  const createOptions = api.mutationOptions('post', '/users', {
+    invalidates: ['users'],
+  });
+  expectTypeOf(createOptions.mutationFn)
+    .parameter(0)
+    .toExtend<{ body: { name: string } }>();
+  expectTypeOf<
+    Awaited<ReturnType<typeof createOptions.mutationFn>>
+  >().toEqualTypeOf<User>();
+  expectTypeOf(createOptions.mutationKey).toEqualTypeOf<
+    readonly ['post', '/users']
+  >();
+
+  // A tag-producing callback sees the mutation's own result.
+  api.mutationOptions('post', '/users', {
+    invalidates: [
+      (created) => {
+        expectTypeOf(created).toEqualTypeOf<User>();
+        return ['user', 'users'];
+      },
+    ],
+  });
+
+  // @ts-expect-error — 'orders' is not in the declared tag vocabulary
+  api.mutationOptions('post', '/users', { invalidates: ['orders'] });
+
+  // @ts-expect-error — read methods do not belong on mutationOptions
+  api.mutationOptions('get', '/users');
+
+  const deleteOptions = api.mutationOptions('delete', '/users/{id}');
+  expectTypeOf(deleteOptions.mutationFn)
+    .parameter(0)
+    .toExtend<{ params: { path: { id: string } } }>();
+
+  // The query key helper is branded with the same data and error types.
+  expectTypeOf(
+    readTags({ queryKey: api.queryKey('get', '/users') }).data,
+  ).toEqualTypeOf<User[]>();
+
+  // `QueryApiPaths` constrains `createQueryApi` itself, not just the option
+  // types it returns, so a paths type that is not a map of path → operations is
+  // rejected at the api's own signature.
+  const notPathsClient = {} as ApiClient<{ '/users': string }>;
+  // @ts-expect-error — `string` is not a map of HTTP method to operation
+  createQueryApi<{ '/users': string }>(notPathsClient);
+
+  // Inferring the same bad paths type off the client is the case the constraint
+  // cannot reject: inference finds no candidate and falls back to the
+  // constraint, so the api is typed `QueryApi<QueryApiPaths>` and it is the
+  // calls on it that fail, not the construction.
+  expectTypeOf(createQueryApi(notPathsClient)).toEqualTypeOf<
+    QueryApi<QueryApiPaths>
+  >();
+}
+
+/**
+ * An operation whose init is entirely optional must be callable with two
+ * arguments — including in a contextually typed position, which is where the
+ * `NoInfer` wrappers on the return types earn their keep.
+ */
+export function optionalInitArity(queryClient: QueryClient): void {
+  api.queryKey('get', '/users');
+  api.queryOptions('get', '/users');
+  api.mutationOptions('post', '/users');
+
+  const key: readonly unknown[] = api.queryKey('get', '/users');
+  void key;
+
+  void queryClient.invalidateQueries({
+    queryKey: api.queryKey('get', '/users'),
+  });
+  void queryClient.getQueryState(api.queryKey('get', '/users'));
+  void queryClient.fetchQuery(api.queryOptions('get', '/users'));
+}

package/src/query-client.test.ts

@@ -0,0 +1,315 @@
+import {
+  environmentManager,
+  QueryCache,
+  QueryClient,
+  type QueryClientConfig,
+  QueryObserver,
+} from '@tanstack/react-query';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { HttpRequestError } from './errors.js';
+import {
+  createQueryClient,
+  isRetryableError,
+  isRetryableHttpStatus,
+  shouldRetryRequest,
+} from './query-client.js';
+import { ZodResponseValidationError } from './zod-response.js';
+
+/** An `HttpRequestError` as `createQueryApi` would build it for `status`. */
+function httpError(status: number): HttpRequestError {
+  return new HttpRequestError({
+    method: 'get',
+    path: '/users',
+    body: undefined,
+    response: new Response(null, { status }),
+  });
+}
+
+/** A `ZodResponseValidationError` as the zod middleware would build it. */
+function validationError(): ZodResponseValidationError {
+  return new ZodResponseValidationError({
+    method: 'get',
+    path: '/users/{id}',
+    schemaName: 'User',
+    issues: [{ path: 'name', message: 'expected string, received undefined' }],
+  });
+}
+
+describe('isRetryableHttpStatus', () => {
+  // The four names below are the whole policy; the table specs under
+  // `shouldRetryRequest` exercise it through the exported predicate.
+  it.for([408, 425, 429])('retries the transient 4xx %i', (status) => {
+    expect(isRetryableHttpStatus(status)).toBe(true);
+  });
+
+  it.for([400, 401, 403, 404, 409, 410, 418, 422, 451, 499])(
+    'does not retry the client fault %i',
+    (status) => {
+      expect(isRetryableHttpStatus(status)).toBe(false);
+    },
+  );
+
+  it.for([500, 502, 503, 504, 599])('retries the server fault %i', (status) => {
+    expect(isRetryableHttpStatus(status)).toBe(true);
+  });
+
+  it.for([200, 204, 301, 304])(
+    'does not retry the sub-400 status %i',
+    (status) => {
+      expect(isRetryableHttpStatus(status)).toBe(false);
+    },
+  );
+});
+
+describe('isRetryableError', () => {
+  it('reads the status off an HttpRequestError', () => {
+    expect(isRetryableError(httpError(429))).toBe(true);
+    expect(isRetryableError(httpError(422))).toBe(false);
+  });
+
+  it('retries a rejection that never reached a status', () => {
+    // A dropped connection, a CORS refusal, or a middleware that threw: the
+    // only evidence is that the request did not complete.
+    expect(isRetryableError(new TypeError('Failed to fetch'))).toBe(true);
+    expect(isRetryableError(new Error('response validation failed'))).toBe(
+      true,
+    );
+    expect(isRetryableError('not an error at all')).toBe(true);
+  });
+
+  it('narrows on `name`, not `instanceof`', () => {
+    // Two copies of this package in one module graph produce an error that is
+    // not `instanceof` the class this predicate closed over.
+    const foreign = Object.assign(new Error('HTTP 404'), {
+      name: 'HttpRequestError',
+      status: 404,
+    });
+
+    expect(isRetryableError(foreign)).toBe(false);
+  });
+
+  it('does not retry a body that failed response validation', () => {
+    // The one rejection without a status that still means the request
+    // completed: the middleware rejects after a 2xx arrived and parsed.
+    expect(isRetryableError(validationError())).toBe(false);
+  });
+
+  it('narrows the validation error on `name` too', () => {
+    const foreign = Object.assign(new Error('User validation failed'), {
+      name: 'ZodResponseValidationError',
+    });
+
+    expect(isRetryableError(foreign)).toBe(false);
+  });
+});
+
+describe('shouldRetryRequest', () => {
+  it('allows two retries, then stops', () => {
+    // `failureCount` is the number of failures *before* this attempt, so the
+    // first rejection arrives as 0. Two `true`s means three attempts total.
+    expect(shouldRetryRequest(0, httpError(503))).toBe(true);
+    expect(shouldRetryRequest(1, httpError(503))).toBe(true);
+    expect(shouldRetryRequest(2, httpError(503))).toBe(false);
+  });
+
+  it('stops on a client fault at the first failure', () => {
+    expect(shouldRetryRequest(0, httpError(404))).toBe(false);
+  });
+});
+
+describe('createQueryClient', () => {
+  it('installs the dashboard defaults', () => {
+    const queries = createQueryClient().getDefaultOptions().queries;
+
+    expect(queries?.refetchOnWindowFocus).toBe(false);
+    expect(queries?.retry).toBe(shouldRetryRequest);
+  });
+
+  it('leaves mutations un-retried', () => {
+    expect(
+      createQueryClient().getDefaultOptions().mutations?.retry,
+    ).toBeUndefined();
+  });
+
+  it('replaces one default without dropping the others', () => {
+    const queries = createQueryClient({
+      defaultOptions: { queries: { retry: 5 } },
+    }).getDefaultOptions().queries;
+
+    expect(queries?.retry).toBe(5);
+    expect(queries?.refetchOnWindowFocus).toBe(false);
+  });
+
+  it('does not read a present-but-undefined key as an override', () => {
+    // How conditional config is ordinarily written. A raw spread would copy
+    // `retry: undefined` over the predicate, and react-query resolves that as
+    // `retry ?? 3` — the retry-everything default this module exists to
+    // replace, reinstated by a branch that meant to change nothing.
+    const alwaysFail = false as boolean;
+
+    const queries = createQueryClient({
+      defaultOptions: {
+        queries: {
+          retry: alwaysFail ? false : undefined,
+          refetchOnWindowFocus: undefined,
+        },
+      },
+    }).getDefaultOptions().queries;
+
+    expect(queries?.retry).toBe(shouldRetryRequest);
+    expect(queries?.refetchOnWindowFocus).toBe(false);
+  });
+
+  it('keeps the defined keys of a partly-undefined override', () => {
+    const queries = createQueryClient({
+      defaultOptions: { queries: { retry: undefined, staleTime: 30_000 } },
+    }).getDefaultOptions().queries;
+
+    expect(queries?.retry).toBe(shouldRetryRequest);
+    expect(queries?.staleTime).toBe(30_000);
+  });
+
+  it('passes the rest of QueryClientConfig through untouched', () => {
+    const queryCache = new QueryCache();
+
+    const client = createQueryClient({
+      queryCache,
+      defaultOptions: { mutations: { retry: 1 }, dehydrate: {} },
+    });
+
+    expect(client.getQueryCache()).toBe(queryCache);
+    expect(client.getDefaultOptions().mutations?.retry).toBe(1);
+    expect(client.getDefaultOptions().dehydrate).toEqual({});
+    expect(client.getDefaultOptions().queries?.refetchOnWindowFocus).toBe(
+      false,
+    );
+  });
+
+  it('returns a distinct client per call', () => {
+    expect(createQueryClient()).not.toBe(createQueryClient());
+  });
+
+  it('is a real QueryClient', () => {
+    expect(createQueryClient()).toBeInstanceOf(QueryClient);
+  });
+});
+
+describe('the retry policy a real client applies', () => {
+  /**
+   * How many times a query rejecting with `error` is attempted under the
+   * package defaults. Only `retryDelay` is overridden — `retry` is the default
+   * under test — so the exponential backoff does not make the spec wait out
+   * the three seconds a real screen would.
+   */
+  async function countAttempts(error: unknown): Promise<number> {
+    let attempts = 0;
+
+    await createQueryClient({ defaultOptions: { queries: { retryDelay: 0 } } })
+      .fetchQuery({
+        queryKey: ['attempts'],
+        queryFn: () => {
+          attempts += 1;
+          return Promise.reject(error);
+        },
+      })
+      .catch(() => undefined);
+
+    return attempts;
+  }
+
+  it('asks once when the response body drifted', async () => {
+    // Before the validation carve-out this was 3, and with the default
+    // backoff the error reached the screen three seconds late.
+    await expect(countAttempts(validationError())).resolves.toBe(1);
+  });
+
+  it('asks once on a client fault', async () => {
+    await expect(countAttempts(httpError(422))).resolves.toBe(1);
+  });
+
+  // The rest of the statusless branch is unchanged: no status and no verdict
+  // from the server means the only reading available is that the request did
+  // not complete.
+  it.for([
+    ['a dropped connection', new TypeError('Failed to fetch')],
+    ['an abort', new DOMException('The operation was aborted.', 'AbortError')],
+    [
+      'a middleware that threw',
+      new Error('http-client-react: middleware called next() more than once'),
+    ],
+  ] as const)('still retries %s twice', async ([, error]) => {
+    await expect(countAttempts(error)).resolves.toBe(3);
+  });
+
+  it('retries a server fault twice', async () => {
+    await expect(countAttempts(httpError(503))).resolves.toBe(3);
+  });
+});
+
+describe('the retry policy a mounted query applies', () => {
+  // `fetchQuery` rewrites an `undefined` retry to `false`, so `countAttempts`
+  // above reads 1 whether the predicate is installed or missing — it cannot
+  // see a retry default that went away. A subscribed observer is the
+  // `useQuery` path, where react-query falls back to `retry ?? 3` instead, and
+  // the only place a lost predicate costs visible round trips.
+  const serverByDefault = environmentManager.isServer();
+
+  // That fallback is `?? 0` on the server, and these specs run under `node`.
+  beforeAll(() => environmentManager.setIsServer(() => false));
+  afterAll(() => environmentManager.setIsServer(() => serverByDefault));
+
+  /** How many times a *mounted* query rejecting with `error` is attempted. */
+  async function countMountedAttempts(
+    config: QueryClientConfig,
+    error: unknown,
+  ): Promise<number> {
+    let attempts = 0;
+
+    const observer = new QueryObserver(createQueryClient(config), {
+      queryKey: ['mounted-attempts'],
+      queryFn: () => {
+        attempts += 1;
+        return Promise.reject(error);
+      },
+      retryDelay: 0,
+    });
+
+    await new Promise<void>((resolve) => {
+      const unsubscribe = observer.subscribe((result) => {
+        if (result.status === 'error') {
+          unsubscribe();
+          resolve();
+        }
+      });
+    });
+
+    return attempts;
+  }
+
+  it('asks once on a client fault', async () => {
+    await expect(countMountedAttempts({}, httpError(422))).resolves.toBe(1);
+  });
+
+  it('asks once when an override names `retry` as undefined', async () => {
+    // The shape a conditional override is ordinarily written in. Before the
+    // merge dropped undefined-valued keys this was 4 — react-query's own
+    // `retry ?? 3`, reinstated by a branch that meant to change nothing.
+    const alwaysFail = false as boolean;
+
+    await expect(
+      countMountedAttempts(
+        {
+          defaultOptions: {
+            queries: { retry: alwaysFail ? false : undefined },
+          },
+        },
+        httpError(422),
+      ),
+    ).resolves.toBe(1);
+  });
+
+  it('retries a server fault twice', async () => {
+    await expect(countMountedAttempts({}, httpError(503))).resolves.toBe(3);
+  });
+});