feat: support skipToken

Author: liaoxuan

README-zh_CN.md

@@ -14,7 +14,6 @@
 <p align="center">
   <a href="https://github.com/liaoliao666/react-query-kit/actions/workflows/tests.yml"><img src="https://github.com/liaoliao666/react-query-kit/actions/workflows/tests.yml/badge.svg?branch=main" alt="Latest build" target="\_parent"></a>
   <a href="https://www.npmjs.com/package/react-query-kit"><img src="https://badgen.net/npm/v/react-query-kit" alt="Latest published version" target="\_parent"></a>
-  <a href="https://unpkg.com/browse/react-query-kit@latest/build/zip/zip.esm.js" rel="nofollow"><img src="https://img.badgesize.io/https:/unpkg.com/react-query-kit@latest/build/zip/zip.esm.js?label=gzip%20size&compression=gzip" alt="gzip size"></a>
   <a href="https://github.com/liaoliao666/react-query-kit"><img src="https://badgen.net/npm/types/react-query-kit" alt="Types included" target="\_parent"></a>
   <a href="https://www.npmjs.com/package/react-query-kit"><img src="https://badgen.net/npm/license/react-query-kit" alt="License" target="\_parent"></a>
   <a href="https://www.npmjs.com/package/react-query-kit"><img src="https://badgen.net/npm/dt/react-query-kit" alt="Number of downloads" target="\_parent"></a>
@@ -28,7 +27,7 @@
 
 - 以类型安全的方式管理 `queryKey`
 - 让 `queryClient` 的操作更清楚地关联到哪个自定义 hook
-- 可以从任何自定义 ReactQuery 挂钩中提取的 TypeScript 类型
+- 可以从任何自定义 ReactQuery hook 中提取的 TypeScript 类型
 - 中间件
 
 [English](./README.md) | 简体中文
@@ -50,6 +49,7 @@
   - [中间件](#中间件)
   - [TypeScript](#typescript)
   - [类型推导](#类型推导)
+  - [禁用查询](#禁用查询)
 - [常见问题](#常见问题)
 - [迁移](#迁移)
 - [Issues](#issues)
@@ -649,6 +649,24 @@ inferError<typeof useProjects> // Error
 inferOptions<typeof useProjects> // InfiniteQueryHookOptions<...>
 ```
 
+## 禁用查询
+
+要禁用查询，您可以将 `skipToken` 作为选项 `variables` 传递给您的自定义查询。这将阻止查询被执行。
+
+```ts
+import { skipToken } from '@tanstack/react-query'
+
+const [name, setName] = useState<string | undefined>()
+const result = usePost({
+  variables: id ? { id: id } : skipToken,
+})
+
+// 以及用于 useQueries 的示例
+const queries = useQueries({
+  queries: [usePost.getOptions(id ? { id: id } : skipToken)],
+})
+```
+
 ## 常见问题
 
 ### `getFetchOptions` 和 `getOptions` 有什么不同

README.md

@@ -14,7 +14,6 @@
 <p align="center">
   <a href="https://github.com/liaoliao666/react-query-kit/actions/workflows/tests.yml"><img src="https://github.com/liaoliao666/react-query-kit/actions/workflows/tests.yml/badge.svg?branch=main" alt="Latest build" target="\_parent"></a>
   <a href="https://www.npmjs.com/package/react-query-kit"><img src="https://badgen.net/npm/v/react-query-kit" alt="Latest published version" target="\_parent"></a>
-  <a href="https://unpkg.com/browse/react-query-kit@latest/build/zip/zip.esm.js" rel="nofollow"><img src="https://img.badgesize.io/https:/unpkg.com/react-query-kit@latest/build/zip/zip.esm.js?label=gzip%20size&compression=gzip" alt="gzip size"></a>
   <a href="https://github.com/liaoliao666/react-query-kit"><img src="https://badgen.net/npm/types/react-query-kit" alt="Types included" target="\_parent"></a>
   <a href="https://github.com/liaoliao666/react-query-kit/blob/main/LICENSE"><img src="https://badgen.net/npm/license/react-query-kit" alt="License" target="\_parent"></a>
   <a href="https://www.npmjs.com/package/react-query-kit"><img src="https://badgen.net/npm/dt/react-query-kit" alt="Number of downloads" target="\_parent"></a>
@@ -50,6 +49,7 @@ English | [简体中文](./README-zh_CN.md)
   - [Middleware](#middleware)
   - [TypeScript](#typescript)
   - [Type inference](#type-inference)
+  - [Disabling Queries](#disabling-queries)
 - [FAQ](#faq)
 - [Migration](#migration)
 - [Issues](#issues)
@@ -649,6 +649,24 @@ inferError<typeof useProjects> // Error
 inferOptions<typeof useProjects> // InfiniteQueryHookOptions<...>
 ```
 
+## Disabling Queries
+
+To disable queries, you can pass `skipToken` as the option `variables` to your custom query. This will prevent the query from being executed.
+
+```ts
+import { skipToken } from '@tanstack/react-query'
+
+const [name, setName] = useState<string | undefined>()
+const result = usePost({
+  variables: id ? { id: id } : skipToken,
+})
+
+// and for useQueries example
+const queries = useQueries({
+  queries: [usePost.getOptions(id ? { id: id } : skipToken)],
+})
+```
+
 ## FAQ
 
 ### What is the difference between `getFetchOptions` and `getOptions`?

package.json

@@ -27,7 +27,7 @@
     "@rollup/plugin-commonjs": "^22.0.2",
     "@rollup/plugin-node-resolve": "^13.2.1",
     "@rollup/plugin-replace": "^4.0.0",
-    "@tanstack/react-query": "^5.28.6",
+    "@tanstack/react-query": "^5.35.1",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^14.0.0",
     "@trivago/prettier-plugin-sort-imports": "^4.2.0",

rollup.config.js

@@ -35,7 +35,6 @@ export default function rollup() {
     cjs(options),
     umdDev(options),
     umdProd(options),
-    esmZip(options),
   ]
 }
 
@@ -121,29 +120,6 @@ function umdProd({ input, external, globals, jsName }) {
       name: jsName,
       globals,
     },
-    plugins: [
-      babelPlugin,
-      commonJS(),
-      nodeResolve({ extensions }),
-      replaceDevPlugin('production'),
-      terser({
-        mangle: true,
-        compress: true,
-      }),
-    ],
-  }
-}
-
-function esmZip({ input, external, globals, jsName }) {
-  return {
-    external,
-    input,
-    output: {
-      format: 'esm',
-      file: `build/zip/zip.esm.js`,
-      name: jsName,
-      globals,
-    },
     plugins: [
       babelPlugin,
       commonJS(),

src/createBaseQuery.ts

@@ -1,11 +1,11 @@
-import type {
-  QueryClient,
-  QueryFunctionContext,
-  UseBaseQueryOptions,
-  UseInfiniteQueryOptions,
+import {
+  type QueryClient,
+  type QueryFunctionContext,
+  type UseBaseQueryOptions,
+  type UseInfiniteQueryOptions,
 } from '@tanstack/react-query'
 
-import { getKey as getFullKey, withMiddleware } from './utils'
+import { ReactQuery, getKey as getFullKey, withMiddleware } from './utils'
 
 type QueryBaseHookOptions = Omit<
   UseBaseQueryOptions,
@@ -38,7 +38,10 @@ export const createBaseQuery = (
 
   const getQueryOptions = (fetcherFn: any, variables: any) => {
     return {
-      queryFn: (context: QueryFunctionContext) => fetcherFn(variables, context),
+      queryFn:
+        variables && variables === ReactQuery.skipToken
+          ? ReactQuery.skipToken
+          : (context: QueryFunctionContext) => fetcherFn(variables, context),
       queryKey: getFullKey(defaultOptions.queryKey, variables),
     }
   }

src/types.ts

@@ -13,6 +13,7 @@ import type {
   QueryKey,
   QueryKeyHashFunction,
   QueryObserverSuccessResult,
+  SkipToken,
   UseInfiniteQueryOptions,
   UseInfiniteQueryResult,
   UseMutationOptions,
@@ -100,7 +101,9 @@ export type ExposeMethods<TFnData, TVariables, TError, TPageParam = never> = {
     QueryKey
   >
   getFetchOptions: (
-    variables: TVariables extends void ? TVariables | void : TVariables
+    variables: TVariables extends void
+      ? CompatibleWithV4<TVariables | SkipToken, TVariables> | void
+      : CompatibleWithV4<TVariables | SkipToken, TVariables>
   ) => Pick<
     ReturnType<
       ExposeMethods<TFnData, TVariables, TError, TPageParam>['getOptions']
@@ -117,7 +120,9 @@ export type ExposeMethods<TFnData, TVariables, TError, TPageParam = never> = {
           | 'initialPageParam'
   >
   getOptions: (
-    variables: TVariables extends void ? TVariables | void : TVariables
+    variables: TVariables extends void
+      ? CompatibleWithV4<TVariables | SkipToken, TVariables> | void
+      : CompatibleWithV4<TVariables | SkipToken, TVariables>
   ) => [TPageParam] extends [never]
     ? CompatibleWithV4<
         UseQueryOptions<TFnData, TError, TFnData, QueryKey> & {
@@ -169,7 +174,7 @@ export interface QueryHookOptions<TFnData, TError, TData, TVariables>
     'queryKey' | 'queryFn' | 'queryKeyHashFn'
   > {
   use?: Middleware<QueryHook<TFnData, TVariables, TError>>[]
-  variables?: TVariables
+  variables?: CompatibleWithV4<TVariables | SkipToken, TVariables>
 }
 
 export interface DefinedQueryHookOptions<TFnData, TError, TData, TVariables>
@@ -242,7 +247,7 @@ export interface SuspenseQueryHookOptions<TFnData, TError, TData, TVariables>
     | 'useErrorBoundary'
   > {
   use?: Middleware<SuspenseQueryHook<TFnData, TVariables, TVariables>>[]
-  variables?: TVariables
+  variables?: CompatibleWithV4<TVariables | SkipToken, TVariables>
 }
 
 export type SuspenseQueryHookResult<TData, TError> = Omit<
@@ -301,7 +306,7 @@ export interface InfiniteQueryHookOptions<
     | 'getNextPageParam'
   > {
   use?: Middleware<InfiniteQueryHook<TFnData, TVariables, TError, TPageParam>>[]
-  variables?: TVariables
+  variables?: CompatibleWithV4<TVariables | SkipToken, TVariables>
 }
 
 export interface DefinedInfiniteQueryHookOptions<
@@ -411,7 +416,7 @@ export interface SuspenseInfiniteQueryHookOptions<
     | 'useErrorBoundary'
   > {
   use?: Middleware<SuspenseInfiniteQueryHook<TFnData, TVariables, TVariables>>[]
-  variables?: TVariables
+  variables?: CompatibleWithV4<TVariables | SkipToken, TVariables>
 }
 
 export type SuspenseInfiniteQueryHookResult<TData, TError> = Omit<

tests/createQuery.test.tsx

@@ -1,12 +1,12 @@
-import { QueryClient } from '@tanstack/react-query'
+import { QueryClient, skipToken } from '@tanstack/react-query'
 import '@testing-library/jest-dom'
-import { waitFor } from '@testing-library/react'
+import { fireEvent, waitFor } from '@testing-library/react'
 import * as React from 'react'
 
 import { createQuery } from '../src'
 import type { QueryHookResult } from '../src'
 import { Middleware } from '../src/types'
-import { omit, renderWithClient, uniqueKey } from './utils'
+import { omit, renderWithClient, sleep, uniqueKey } from './utils'
 
 describe('createQuery', () => {
   const queryClient = new QueryClient()
@@ -138,4 +138,50 @@ describe('createQuery', () => {
 
     await waitFor(() => rendered.getByText('selectedData'))
   })
+
+  it('should respect skipToken and refetch when skipToken is taken away', async () => {
+    const useGeneratedQuery = createQuery<string>({
+      queryKey: uniqueKey(),
+      fetcher: async () => {
+        await sleep(10)
+        return Promise.resolve('data')
+      },
+    })
+
+    function Page({ enabled }: { enabled: boolean }) {
+      const { data, status } = useGeneratedQuery({
+        variables: enabled ? undefined : skipToken,
+        retry: false,
+        retryOnMount: false,
+        refetchOnMount: false,
+        refetchOnWindowFocus: false,
+      })
+
+      return (
+        <div>
+          <div>status: {status}</div>
+          <div>data: {String(data)}</div>
+        </div>
+      )
+    }
+
+    function App() {
+      const [enabled, toggle] = React.useReducer(x => !x, false)
+
+      return (
+        <div>
+          <Page enabled={enabled} />
+          <button onClick={toggle}>enable</button>
+        </div>
+      )
+    }
+
+    const rendered = renderWithClient(queryClient, <App />)
+
+    await waitFor(() => rendered.getByText('status: pending'))
+
+    fireEvent.click(rendered.getByRole('button', { name: 'enable' }))
+    await waitFor(() => rendered.getByText('status: success'))
+    await waitFor(() => rendered.getByText('data: data'))
+  })
 })

tests/utils.tsx

@@ -32,3 +32,9 @@ export function omit<T extends object, K extends string[]>(
     Object.entries(object || {}).filter(([key]) => !paths.includes(key))
   ) as Pick<T, Exclude<keyof T, K[number]>>
 }
+
+export function sleep(timeout: number): Promise<void> {
+  return new Promise((resolve, _reject) => {
+    setTimeout(resolve, timeout)
+  })
+}

yarn.lock

@@ -1676,17 +1676,17 @@
   dependencies:
     "@sinonjs/commons" "^3.0.0"
 
-"@tanstack/query-core@5.28.6":
-  version "5.28.6"
-  resolved "https://registry.yarnpkg.com/@tanstack/query-core/-/query-core-5.28.6.tgz#a3bdb108f9f8d4e2ba3163068dbe6ff55b905a81"
-  integrity sha512-hnhotV+DnQtvtR3jPvbQMPNMW4KEK0J4k7c609zJ8muiNknm+yoDyMHmxTWM5ZnlZpsz0zOxYFr+mzRJNHWJsA==
+"@tanstack/query-core@5.35.1":
+  version "5.35.1"
+  resolved "https://registry.yarnpkg.com/@tanstack/query-core/-/query-core-5.35.1.tgz#a7e6cbf0f252475da19ba9cba6567e8fe683b2ee"
+  integrity sha512-0Dnpybqb8+ps6WgqBnqFEC+1F/xLvUosRAq+wiGisTgolOZzqZfkE2995dEXmhuzINiTM7/a6xSGznU0NIvBkw==
 
-"@tanstack/react-query@^5.28.6":
-  version "5.28.6"
-  resolved "https://registry.yarnpkg.com/@tanstack/react-query/-/react-query-5.28.6.tgz#0d52b0a98a1d842debf9c65496e20a9981a23bc4"
-  integrity sha512-/DdYuDBSsA21Qbcder1R8Cr/3Nx0ZnA2lgtqKsLMvov8wL4+g0HBz/gWYZPlIsof7iyfQafyhg4wUVUsS3vWZw==
+"@tanstack/react-query@^5.35.1":
+  version "5.35.1"
+  resolved "https://registry.yarnpkg.com/@tanstack/react-query/-/react-query-5.35.1.tgz#3b7c710bb32c6c71e0cbe64029dded9b0cbd9a0f"
+  integrity sha512-i2T7m2ffQdNqlX3pO+uMsnQ0H4a59Ens2GxtlMsRiOvdSB4SfYmHb27MnvFV8rGmtWRaa4gPli0/rpDoSS5LbQ==
   dependencies:
-    "@tanstack/query-core" "5.28.6"
+    "@tanstack/query-core" "5.35.1"
 
 "@testing-library/dom@^9.0.0":
   version "9.3.0"