feat: add more utils

Author: liaoxuan

README-zh_CN.md

@@ -36,9 +36,12 @@
 - [安装](#installation)
 - [例子](#examples)
 - 使用
-  - [createQuery](#createQuery)
-  - [createInfiniteQuery](#createInfiniteQuery)
-  - [createMutation](#createMutation)
+  - [createQuery](#createquery)
+  - [createInfiniteQuery](#createinfinitequery)
+  - [createMutation](#createmutation)
+  - [createImmutableQuery](#createimmutablequery)
+  - [createSuspenseQuery](#createsuspensequery)
+  - [createSuspenseInfiniteQuery](#createsuspenseinfinitequery)
   - [类型推导](#类型推导)
   - [注意事项](#注意事项)
 - [问题](#issues)
@@ -282,6 +285,68 @@ Returns
 - `setData: (updater: Updater<TData>, options?: SetDataOptions) => TData | undefined`
   - 它的参数与 `queryClient.setQueryData` 类似，但不需要传入 `queryKey`
 
+## createImmutableQuery
+
+如果资源是不可变的，即使我们再怎么重新请求也永远不会发生任何改变，那么我们可以禁用它的所有的自动重新请求。
+ReactQueryKit 提供了一个辅助函数 `createImmutableQuery` 来标记资源为不可变的：
+
+```ts
+import { createImmutableQuery } from 'react-query-kit'
+
+createImmutableQuery({
+  ...options,
+})
+
+// 相当于
+createQuery({
+  ...options,
+  refetchInterval: false,
+  refetchOnMount: false,
+  refetchOnReconnect: false,
+  refetchOnWindowFocus: false,
+  staleTime: Infinity,
+  gcTime: Infinity,
+})
+```
+
+## createSuspenseQuery
+
+这与在查询配置中将 suspense 选项设置为 true 具有相同的效果，但在 TypeScript 中效果更好，因为 data 是有定义的（因为错误和加载状态由 Suspense 和 ErrorBoundaries 处理）。
+
+```ts
+import { createSuspenseQuery } from 'react-query-kit'
+
+createSuspenseQuery({
+  ...options,
+})
+
+// 相当于
+createQuery({
+  ...options,
+  enabled: true,
+  suspense: true,
+  throwOnError: true,
+})
+```
+
+## createSuspenseInfiniteQuery
+
+```ts
+import { createSuspenseInfiniteQuery } from 'react-query-kit'
+
+createSuspenseInfiniteQuery({
+  ...options,
+})
+
+// 相当于
+createInfiniteQuery({
+  ...options,
+  enabled: true,
+  suspense: true,
+  throwOnError: true,
+})
+```
+
 ## createMutation
 
 ### Usage

README.md

@@ -36,11 +36,15 @@ English | [简体中文](./README-zh_CN.md)
 - [Installation](#installation)
 - [Examples](#examples)
 - Usage
-  - [createQuery](#createQuery)
-  - [createInfiniteQuery](#createInfiniteQuery)
-  - [createMutation](#createMutation)
-  - [Type inference](#Type-inference)
-  - [Caution](#Caution)
+  - [createQuery](#createquery)
+  - [createInfiniteQuery](#createinfinitequery)
+  - [createMutation](#createmutation)
+  - [createImmutableQuery](#createimmutablequery)
+  - [createSuspenseQuery](#createsuspensequery)
+  - [createSuspenseInfiniteQuery](#createsuspenseinfinitequery)
+  - [createMutation](#createmutation)
+  - [Type inference](#type-inference)
+  - [Caution](#caution)
 - [Issues](#issues)
   - [🐛 Bugs](#-bugs)
   - [💡 Feature Requests](#-feature-requests)
@@ -295,6 +299,68 @@ Returns
 - `setData: (updater: Updater<InfiniteData<TFnData>>, options?: SetDataOptions) => TData | undefined`
   - it's args similar with `queryClient.setQueryData` but without `queryKey`
 
+## createImmutableQuery
+
+If the resource is immutable, no matter how many times we request it again, it will never change. In this case, we can disable all automatic re-requests for it.
+ReactQueryKit provides a helper function `createImmutableQuery` to mark a resource as immutable.
+
+```ts
+import { createImmutableQuery } from 'react-query-kit'
+
+createImmutableQuery({
+  ...options,
+})
+
+// equals to
+createQuery({
+  ...options,
+  refetchInterval: false,
+  refetchOnMount: false,
+  refetchOnReconnect: false,
+  refetchOnWindowFocus: false,
+  staleTime: Infinity,
+  gcTime: Infinity,
+})
+```
+
+## createSuspenseQuery
+
+This has the same effect as setting the `suspense` option to `true` in the query config, but it works better in TypeScript, because `data` is guaranteed to be defined (as errors and loading states are handled by Suspense- and ErrorBoundaries).
+
+```ts
+import { createSuspenseQuery } from 'react-query-kit'
+
+createSuspenseQuery({
+  ...options,
+})
+
+// equals to
+createQuery({
+  ...options,
+  enabled: true,
+  suspense: true,
+  throwOnError: true,
+})
+```
+
+## createSuspenseInfiniteQuery
+
+```ts
+import { createSuspenseInfiniteQuery } from 'react-query-kit'
+
+createSuspenseInfiniteQuery({
+  ...options,
+})
+
+// equals to
+createInfiniteQuery({
+  ...options,
+  enabled: true,
+  suspense: true,
+  throwOnError: true,
+})
+```
+
 ## createMutation
 
 ### Usage

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.0.0-alpha.19",
+    "@tanstack/react-query": "^5.0.0-beta.9",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^14.0.0",
     "@types/jest": "^28.1.6",

src/createBaseQuery.ts

@@ -19,17 +19,18 @@ type QueryBaseHookOptions = Omit<
   AdditionalQueryHookOptions<any, any> & { context?: any }
 
 export function createBaseQuery(
-  options: any,
+  initialOptions: any,
   useRQHook: (options: any, queryClient?: any) => any,
-  queryClient?: any
+  queryClient?: any,
+  overrideOptions?: QueryBaseHookOptions
 ): any {
   const {
     primaryKey,
     queryFn,
     queryKeyHashFn,
     useDefaultOptions,
     ...defaultOptions
-  } = options as CreateQueryOptions
+  } = initialOptions as CreateQueryOptions
 
   const getPrimaryKey = () => primaryKey
 
@@ -41,6 +42,7 @@ export function createBaseQuery(
       ...defaultOptions,
       ...useDefaultOptions?.(),
       ...options,
+      ...overrideOptions,
     } as QueryBaseHookOptions
 
     const queryKey = getKey(variables)
@@ -50,18 +52,21 @@ export function createBaseQuery(
       mergedOptions.context ? { context: mergedOptions.context } : queryClient
     )
 
-    const queryOptions = {
-      ...mergedOptions,
-      enabled:
-        typeof enabled === 'function'
-          ? enabled(client.getQueryData(queryKey), variables)
-          : enabled,
-      queryKeyHashFn,
-      queryFn,
-      queryKey,
-    }
+    const result = useRQHook(
+      {
+        ...mergedOptions,
+        enabled:
+          typeof enabled === 'function'
+            ? enabled(client.getQueryData(queryKey), variables)
+            : enabled,
+        queryKeyHashFn,
+        queryFn,
+        queryKey,
+      },
+      client
+    )
 
-    return Object.assign(useRQHook(queryOptions, client), {
+    return Object.assign(result, {
       queryKey,
       variables,
       setData: (updater: Updater<any, any>, setDataOptions?: SetDataOptions) =>

src/createImmutableQuery.tsx

@@ -0,0 +1,82 @@
+import type { QueryClient, UseQueryOptions } from '@tanstack/react-query'
+import { useQuery } from '@tanstack/react-query'
+import { createBaseQuery } from './createBaseQuery'
+import type {
+  AdditionalCreateOptions,
+  CompatibleWithV4,
+  ImmutableQueryHook,
+  ImmutableQueryHookOptions,
+  inferQueryKey,
+} from './types'
+
+export interface CreateImmutableQueryOptions<
+  TFnData,
+  TVariables = any,
+  Error = unknown
+> extends Omit<
+      UseQueryOptions<TFnData, Error, TFnData, inferQueryKey<TVariables>>,
+      | 'queryKey'
+      | 'queryFn'
+      | 'enabled'
+      | 'select'
+      | 'refetchInterval'
+      | 'refetchIntervalInBackground'
+      | 'refetchOnMount'
+      | 'refetchOnReconnect'
+      | 'refetchOnWindowFocus'
+      | 'staleTime'
+      | 'gcTime'
+      | 'cacheTime'
+    >,
+    AdditionalCreateOptions<TFnData, TVariables> {}
+
+export function createImmutableQuery<
+  TFnData,
+  TVariables = any,
+  Error = unknown
+>(
+  options: CreateImmutableQueryOptions<TFnData, TVariables, Error> & {
+    useDefaultOptions: () => Omit<
+      ImmutableQueryHookOptions<TFnData, Error, TFnData, TVariables>,
+      'select'
+    > & { variables: TVariables }
+  },
+  queryClient?: CompatibleWithV4<QueryClient, void>
+): ImmutableQueryHook<TFnData, TVariables, Error, TVariables | void>
+
+export function createImmutableQuery<
+  TFnData,
+  TVariables = any,
+  Error = unknown
+>(
+  options: CreateImmutableQueryOptions<TFnData, TVariables, Error> & {
+    useDefaultOptions: () => Omit<
+      ImmutableQueryHookOptions<TFnData, Error, TFnData, TVariables>,
+      'select' | 'variables'
+    >
+  },
+  queryClient?: CompatibleWithV4<QueryClient, void>
+): ImmutableQueryHook<TFnData, TVariables, Error, TVariables>
+
+export function createImmutableQuery<
+  TFnData,
+  TVariables = any,
+  Error = unknown
+>(
+  options: CreateImmutableQueryOptions<TFnData, TVariables, Error>,
+  queryClient?: CompatibleWithV4<QueryClient, void>
+): ImmutableQueryHook<TFnData, TVariables, Error, TVariables>
+
+export function createImmutableQuery(options: any, queryClient?: any) {
+  return createBaseQuery(options, useQuery, queryClient, {
+    refetchInterval: false,
+    refetchOnMount: false,
+    refetchOnReconnect: false,
+    refetchOnWindowFocus: false,
+    staleTime: Infinity,
+    gcTime: Infinity,
+    // compatible with ReactQuery v4
+    // @ts-ignore
+    cacheTime: Infinity,
+  })
+}