feat(@tanstack/query-core)!: add skipToken support and queryOptions override

Generated queryOptions and infiniteQueryOptions now accept skipToken;
generated useQuery hooks accept a queryOptions override and default to
enabled for react-query and preact-query.

BREAKING CHANGE: useQuery defaults to enabled for @tanstack/react-query and @tanstack/preact-query.

Author: nmokkenstorm

.changeset/skiptoken-query-options-override.md

@@ -0,0 +1,9 @@
+---
+"@hey-api/openapi-ts": minor
+---
+
+**plugin(@tanstack/react-query, @tanstack/preact-query)**: add `skipToken` support and `queryOptions` override to generated `useQuery` hooks; enable `useQuery` generation by default.
+
+- Generated `queryOptions` and `infiniteQueryOptions` factories now accept `Options<T> | typeof skipToken`, following TanStack Query's idiomatic pattern for conditionally disabling queries.
+- Generated `useQuery` hooks now accept an optional `queryOptions` property (typed as `Partial<Omit<ReturnType<typeof ...Options>, 'queryKey' | 'queryFn'>>`) that is spread over the computed options, allowing callers to override `staleTime`, `gcTime`, `enabled`, etc. without losing type safety.
+- The `useQuery` config flag now defaults to `true` for `@tanstack/react-query` and `@tanstack/preact-query`. Existing users who do not want generated `useQuery` hooks must explicitly set `useQuery: false`.

examples/openapi-ts-tanstack-angular-query-experimental/src/client/@tanstack/angular-query-experimental.gen.ts

@@ -4,6 +4,7 @@ import {
   type DefaultError,
   type MutationOptions,
   queryOptions,
+  skipToken,
 } from '@tanstack/angular-query-experimental';
 
 import { client } from '../client.gen';
@@ -150,6 +151,9 @@ const createQueryKey = <TOptions extends Options>(
   return [params];
 };
 
+const unwrapSkipToken = <T>(options: T | typeof skipToken): T | undefined =>
+  options !== skipToken ? options : undefined;
+
 export const findPetsByStatusQueryKey = (options: Options<FindPetsByStatusData>) =>
   createQueryKey('findPetsByStatus', options);
 
@@ -158,23 +162,28 @@ export const findPetsByStatusQueryKey = (options: Options<FindPetsByStatusData>)
  *
  * Multiple status values can be provided with comma separated strings.
  */
-export const findPetsByStatusOptions = (options: Options<FindPetsByStatusData>) =>
+export const findPetsByStatusOptions = (
+  options: Options<FindPetsByStatusData> | typeof skipToken,
+) =>
   queryOptions<
     FindPetsByStatusResponse,
     DefaultError,
     FindPetsByStatusResponse,
     ReturnType<typeof findPetsByStatusQueryKey>
   >({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await findPetsByStatus({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: findPetsByStatusQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await findPetsByStatus({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: findPetsByStatusQueryKey(unwrapSkipToken(options) as Options<FindPetsByStatusData>),
   });
 
 export const findPetsByTagsQueryKey = (options: Options<FindPetsByTagsData>) =>
@@ -185,23 +194,26 @@ export const findPetsByTagsQueryKey = (options: Options<FindPetsByTagsData>) =>
  *
  * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
  */
-export const findPetsByTagsOptions = (options: Options<FindPetsByTagsData>) =>
+export const findPetsByTagsOptions = (options: Options<FindPetsByTagsData> | typeof skipToken) =>
   queryOptions<
     FindPetsByTagsResponse,
     DefaultError,
     FindPetsByTagsResponse,
     ReturnType<typeof findPetsByTagsQueryKey>
   >({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await findPetsByTags({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: findPetsByTagsQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await findPetsByTags({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: findPetsByTagsQueryKey(unwrapSkipToken(options) as Options<FindPetsByTagsData>),
   });
 
 /**
@@ -233,23 +245,26 @@ export const getPetByIdQueryKey = (options: Options<GetPetByIdData>) =>
  *
  * Returns a single pet.
  */
-export const getPetByIdOptions = (options: Options<GetPetByIdData>) =>
+export const getPetByIdOptions = (options: Options<GetPetByIdData> | typeof skipToken) =>
   queryOptions<
     GetPetByIdResponse,
     DefaultError,
     GetPetByIdResponse,
     ReturnType<typeof getPetByIdQueryKey>
   >({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await getPetById({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: getPetByIdQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await getPetById({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: getPetByIdQueryKey(unwrapSkipToken(options) as Options<GetPetByIdData>),
   });
 
 /**
@@ -310,23 +325,26 @@ export const getInventoryQueryKey = (options?: Options<GetInventoryData>) =>
  *
  * Returns a map of status codes to quantities.
  */
-export const getInventoryOptions = (options?: Options<GetInventoryData>) =>
+export const getInventoryOptions = (options?: Options<GetInventoryData> | typeof skipToken) =>
   queryOptions<
     GetInventoryResponse,
     DefaultError,
     GetInventoryResponse,
     ReturnType<typeof getInventoryQueryKey>
   >({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await getInventory({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: getInventoryQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await getInventory({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: getInventoryQueryKey(unwrapSkipToken(options)),
   });
 
 /**
@@ -383,23 +401,26 @@ export const getOrderByIdQueryKey = (options: Options<GetOrderByIdData>) =>
  *
  * For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
  */
-export const getOrderByIdOptions = (options: Options<GetOrderByIdData>) =>
+export const getOrderByIdOptions = (options: Options<GetOrderByIdData> | typeof skipToken) =>
   queryOptions<
     GetOrderByIdResponse,
     DefaultError,
     GetOrderByIdResponse,
     ReturnType<typeof getOrderByIdQueryKey>
   >({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await getOrderById({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: getOrderByIdQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await getOrderById({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: getOrderByIdQueryKey(unwrapSkipToken(options) as Options<GetOrderByIdData>),
   });
 
 /**
@@ -464,23 +485,26 @@ export const loginUserQueryKey = (options?: Options<LoginUserData>) =>
  *
  * Log into the system.
  */
-export const loginUserOptions = (options?: Options<LoginUserData>) =>
+export const loginUserOptions = (options?: Options<LoginUserData> | typeof skipToken) =>
   queryOptions<
     LoginUserResponse,
     DefaultError,
     LoginUserResponse,
     ReturnType<typeof loginUserQueryKey>
   >({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await loginUser({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: loginUserQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await loginUser({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: loginUserQueryKey(unwrapSkipToken(options)),
   });
 
 export const logoutUserQueryKey = (options?: Options<LogoutUserData>) =>
@@ -491,18 +515,21 @@ export const logoutUserQueryKey = (options?: Options<LogoutUserData>) =>
  *
  * Log user out of the system.
  */
-export const logoutUserOptions = (options?: Options<LogoutUserData>) =>
+export const logoutUserOptions = (options?: Options<LogoutUserData> | typeof skipToken) =>
   queryOptions<unknown, DefaultError, unknown, ReturnType<typeof logoutUserQueryKey>>({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await logoutUser({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: logoutUserQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await logoutUser({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: logoutUserQueryKey(unwrapSkipToken(options)),
   });
 
 /**
@@ -534,23 +561,26 @@ export const getUserByNameQueryKey = (options: Options<GetUserByNameData>) =>
  *
  * Get user detail based on username.
  */
-export const getUserByNameOptions = (options: Options<GetUserByNameData>) =>
+export const getUserByNameOptions = (options: Options<GetUserByNameData> | typeof skipToken) =>
   queryOptions<
     GetUserByNameResponse,
     DefaultError,
     GetUserByNameResponse,
     ReturnType<typeof getUserByNameQueryKey>
   >({
-    queryFn: async ({ queryKey, signal }) => {
-      const { data } = await getUserByName({
-        ...options,
-        ...queryKey[0],
-        signal,
-        throwOnError: true,
-      });
-      return data;
-    },
-    queryKey: getUserByNameQueryKey(options),
+    queryFn:
+      options === skipToken
+        ? skipToken
+        : async ({ queryKey, signal }) => {
+            const { data } = await getUserByName({
+              ...unwrapSkipToken(options),
+              ...queryKey[0],
+              signal,
+              throwOnError: true,
+            });
+            return data;
+          },
+    queryKey: getUserByNameQueryKey(unwrapSkipToken(options) as Options<GetUserByNameData>),
   });
 
 /**