feat(react-query): add skipToken functionality (#683)

Author: Gabrola

.changeset/gorgeous-games-sell.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/react-query': minor
+---
+
+Add ability to pass `skipToken` to `queryData` similar to how you can pass it to `queryFn` in plain React Query

libs/ts-rest/core/src/lib/type-utils.ts

@@ -102,12 +102,22 @@ type OptionalKeys<T> = T extends unknown
     }[keyof T]
   : never;
 
+// TODO: Replace all usages of this with IfAllPropertiesOptional
 export type AreAllPropertiesOptional<T> = T extends Record<string, unknown>
   ? Exclude<keyof T, OptionalKeys<T>> extends never
     ? true
     : false
   : false;
 
+export type IfAllPropertiesOptional<T, TIf, TElse> = T extends Record<
+  string,
+  unknown
+>
+  ? Exclude<keyof T, OptionalKeys<T>> extends never
+    ? TIf
+    : TElse
+  : TElse;
+
 export type OptionalIfAllOptional<
   T,
   Select extends keyof T = keyof T,

libs/ts-rest/react-query-v5/src/v5/internal/create-hooks.ts

@@ -12,6 +12,7 @@ import {
   usePrefetchQuery,
   usePrefetchInfiniteQuery,
   QueryOptions,
+  skipToken,
 } from '@tanstack/react-query';
 import {
   AppRoute,
@@ -70,20 +71,25 @@ function createBaseQueryOptions<
   TClientArgs extends ClientArgs,
   TOptions extends QueryOptions<any, any>,
 >(route: TAppRoute, clientArgs: TClientArgs, options: TOptions): TOptions {
-  const { queryData, ...rqOptions } = options as unknown as TOptions &
-    (
-      | TsRestQueryOptions<TAppRoute, TClientArgs>
-      | TsRestInfiniteQueryOptions<TAppRoute, TClientArgs>
-    );
+  const { queryData: queryDataOrFunction, ...rqOptions } =
+    options as unknown as TOptions &
+      (
+        | TsRestQueryOptions<TAppRoute, TClientArgs>
+        | TsRestInfiniteQueryOptions<TAppRoute, TClientArgs>
+      );
   return {
     ...rqOptions,
-    queryFn: (context?: QueryFunctionContext<QueryKey, unknown>) => {
-      return apiFetcher(
-        route,
-        clientArgs,
-        context?.signal,
-      )(typeof queryData === 'function' ? queryData(context!) : queryData);
-    },
+    queryFn:
+      queryDataOrFunction === skipToken
+        ? skipToken
+        : (context?: QueryFunctionContext<QueryKey, unknown>) => {
+            const requestData =
+              typeof queryDataOrFunction === 'function'
+                ? queryDataOrFunction(context!)
+                : queryDataOrFunction;
+
+            return apiFetcher(route, clientArgs, context?.signal)(requestData);
+          },
   } as unknown as TOptions;
 }
 

libs/ts-rest/react-query-v5/src/v5/react-query.spec.tsx

@@ -1,5 +1,9 @@
 import '@testing-library/jest-dom';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  QueryClient,
+  QueryClientProvider,
+  skipToken,
+} from '@tanstack/react-query';
 import {
   waitFor,
   renderHook,
@@ -235,6 +239,27 @@ describe('react-query', () => {
     expect(result.current.data).toStrictEqual(SUCCESS_RESPONSE);
   });
 
+  it('useQuery should handle skipToken', async () => {
+    const { result } = renderHook(
+      () => {
+        return tsr.health.useQuery({
+          queryKey: ['health'],
+          queryData: skipToken,
+        });
+      },
+      {
+        wrapper: ReactQueryProvider,
+      },
+    );
+
+    await waitFor(() => {
+      expect(result.current.isPending).toStrictEqual(true);
+    });
+
+    expect(result.current.data).toStrictEqual(undefined);
+    expect(api).toHaveBeenCalledTimes(0);
+  });
+
   it('useQuery should handle error response', async () => {
     api.mockResolvedValue({
       status: 404,
@@ -799,6 +824,19 @@ describe('react-query', () => {
     });
   });
 
+  it('useSuspenseQuery should not allow skipToken', async () => {
+    renderHook(
+      () => {
+        return tsr.health.useSuspenseQuery({
+          queryKey: ['health'],
+          // @ts-expect-error - skipToken is not allowed in suspense
+          queryData: skipToken,
+        });
+      },
+      { wrapper: ReactQueryProvider },
+    );
+  });
+
   it('should handle mutation', async () => {
     api.mockResolvedValue(SUCCESS_RESPONSE);
 
@@ -937,6 +975,65 @@ describe('react-query', () => {
     expect(result.current[1].data).toStrictEqual(SUCCESS_RESPONSE);
   });
 
+  it('useQueries should handle skipToken', async () => {
+    api.mockResolvedValue(SUCCESS_RESPONSE);
+
+    const { result } = renderHook(
+      () => {
+        return tsr.posts.getPost.useQueries({
+          queries: [
+            {
+              queryKey: ['posts', '1'],
+              queryData: {
+                params: {
+                  id: '1',
+                },
+              },
+            },
+            {
+              queryKey: ['posts', '2'],
+              queryData: skipToken,
+            },
+          ],
+        });
+      },
+      {
+        wrapper: ReactQueryProvider,
+      },
+    );
+
+    expect(result.current[0].data).toStrictEqual(undefined);
+    expect(result.current[0].isPending).toStrictEqual(true);
+
+    expect(result.current[1].data).toStrictEqual(undefined);
+    expect(result.current[1].isPending).toStrictEqual(true);
+
+    await waitFor(() => {
+      expect(result.current[0].isPending).toStrictEqual(false);
+      expect(result.current[1].isPending).toStrictEqual(true);
+    });
+
+    expect(result.current[0].data).toStrictEqual(SUCCESS_RESPONSE);
+
+    expect(result.current[1].data).toStrictEqual(undefined);
+
+    expect(api).toHaveBeenCalledWith({
+      method: 'GET',
+      path: 'https://api.com/posts/1',
+      body: undefined,
+      headers: {
+        'x-test': 'test',
+      },
+      route: contract.posts.getPost,
+      signal: expect.any(AbortSignal),
+      fetchOptions: {
+        signal: expect.any(AbortSignal),
+      },
+    });
+
+    expect(api).toHaveBeenCalledTimes(1);
+  });
+
   it('useQueries should handle `select`', async () => {
     api.mockResolvedValue(SUCCESS_RESPONSE);
 

libs/ts-rest/react-query-v5/src/v5/types/hooks-options.ts

@@ -7,8 +7,9 @@ import {
   UseQueryOptions as TanStackUseQueryOptions,
   UseSuspenseInfiniteQueryOptions as TanStackUseSuspenseInfiniteQueryOptions,
   UseSuspenseQueryOptions as TanStackUseSuspenseQueryOptions,
+  SkipToken,
 } from '@tanstack/react-query';
-import { AppRoute, AreAllPropertiesOptional, ClientArgs } from '@ts-rest/core';
+import { AppRoute, ClientArgs, IfAllPropertiesOptional } from '@ts-rest/core';
 import { QueriesOptions, QueriesResults } from '../internal/queries-options';
 import {
   SuspenseQueriesOptions,
@@ -20,14 +21,38 @@ export type TsRestQueryOptions<
   TAppRoute extends AppRoute,
   TClientArgs extends ClientArgs,
   TQueryData = RequestData<TAppRoute, TClientArgs>,
-> = AreAllPropertiesOptional<TQueryData> extends true
-  ? { queryData?: TQueryData }
-  : { queryData: TQueryData };
+> = IfAllPropertiesOptional<
+  TQueryData,
+  { queryData?: TQueryData | SkipToken },
+  { queryData: TQueryData | SkipToken }
+>;
+
+export type TsRestSuspenseQueryOptions<
+  TAppRoute extends AppRoute,
+  TClientArgs extends ClientArgs,
+  TQueryData = RequestData<TAppRoute, TClientArgs>,
+> = IfAllPropertiesOptional<
+  TQueryData,
+  { queryData?: TQueryData },
+  { queryData: TQueryData }
+>;
 
 export type TsRestInfiniteQueryOptions<
   TAppRoute extends AppRoute,
   TClientArgs extends ClientArgs,
   TPageParam = unknown,
+> = {
+  queryData:
+    | ((
+        context: QueryFunctionContext<QueryKey, TPageParam>,
+      ) => RequestData<TAppRoute, TClientArgs>)
+    | SkipToken;
+};
+
+export type TsRestSuspenseInfiniteQueryOptions<
+  TAppRoute extends AppRoute,
+  TClientArgs extends ClientArgs,
+  TPageParam = unknown,
 > = {
   queryData: (
     context: QueryFunctionContext<QueryKey, TPageParam>,
@@ -96,7 +121,7 @@ export type UseSuspenseQueryOptions<
   >,
   'queryFn'
 > &
-  TsRestQueryOptions<TAppRoute, TClientArgs>;
+  TsRestSuspenseQueryOptions<TAppRoute, TClientArgs>;
 
 export type UseInfiniteQueryOptions<
   TAppRoute extends AppRoute,
@@ -152,7 +177,7 @@ export type UseSuspenseInfiniteQueryOptions<
   >,
   'queryFn'
 > &
-  TsRestInfiniteQueryOptions<TAppRoute, TClientArgs, TPageParam>;
+  TsRestSuspenseInfiniteQueryOptions<TAppRoute, TClientArgs, TPageParam>;
 
 export type UseMutationOptions<
   TAppRoute extends AppRoute,