feat: refetch return Promise<Void>

.prettierignore

@@ -1,2 +1,4 @@
 node_modules
 build
+CHANGELOG.md
+

src/react-query/hooks/__tests__/useQueryData.refetch.test.ts

@@ -0,0 +1,189 @@
+import {QueryClient, useInfiniteQuery, useQuery} from '@tanstack/react-query';
+import {renderHook} from '@testing-library/react';
+
+import {idle} from '../../../core';
+import type {AnyInfiniteQueryDataSource} from '../../impl/infinite/types';
+import type {AnyPlainQueryDataSource} from '../../impl/plain/types';
+import {warnDisabledRefetch} from '../../utils/warnDisabledRefetch';
+import {useQueryContext} from '../useQueryContext';
+import {useQueryData} from '../useQueryData';
+
+jest.mock('@tanstack/react-query', () => ({
+    ...jest.requireActual('@tanstack/react-query'),
+    useQuery: jest.fn(),
+    useInfiniteQuery: jest.fn(),
+}));
+
+jest.mock('../useQueryContext');
+jest.mock('../../utils/warnDisabledRefetch');
+
+const mockUseQuery = useQuery as jest.MockedFunction<typeof useQuery>;
+const mockUseInfiniteQuery = useInfiniteQuery as jest.MockedFunction<typeof useInfiniteQuery>;
+const mockWarnDisabledRefetch = warnDisabledRefetch as jest.MockedFunction<
+    typeof warnDisabledRefetch
+>;
+
+describe('useQueryData refetch behavior', () => {
+    const mockQueryClient = new QueryClient();
+    const mockContext = {queryClient: mockQueryClient};
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        (useQueryContext as jest.Mock).mockReturnValue(mockContext);
+    });
+
+    const createMockQueryResult = (refetch = jest.fn()) => ({
+        data: 'test-data',
+        error: null,
+        status: 'success' as const,
+        fetchStatus: 'idle' as const,
+        isLoading: false,
+        isError: false,
+        isSuccess: true,
+        isPending: false,
+        refetch,
+        dataUpdatedAt: Date.now(),
+        errorUpdatedAt: 0,
+        failureCount: 0,
+        failureReason: null,
+        isFetched: true,
+        isFetchedAfterMount: true,
+        isFetching: false,
+        isInitialLoading: false,
+        isLoadingError: false,
+        isPaused: false,
+        isPlaceholderData: false,
+        isPreviousData: false,
+        isRefetchError: false,
+        isRefetching: false,
+        isStale: false,
+        promise: Promise.resolve('test-data'),
+    });
+
+    const createMockInfiniteResult = (refetch = jest.fn()) => ({
+        data: {pages: [['item1'], ['item2']], pageParams: [undefined, 'next-page']},
+        error: null,
+        status: 'success' as const,
+        fetchStatus: 'idle' as const,
+        isLoading: false,
+        isError: false,
+        isSuccess: true,
+        isPending: false,
+        refetch,
+        hasNextPage: false,
+        hasPreviousPage: false,
+        fetchNextPage: jest.fn(),
+        fetchPreviousPage: jest.fn(),
+        isFetchingNextPage: false,
+        isFetchingPreviousPage: false,
+        dataUpdatedAt: Date.now(),
+        errorUpdatedAt: 0,
+        failureCount: 0,
+        failureReason: null,
+        isFetched: true,
+        isFetchedAfterMount: true,
+        isFetching: false,
+        isInitialLoading: false,
+        isLoadingError: false,
+        isPaused: false,
+        isPlaceholderData: false,
+        isPreviousData: false,
+        isRefetchError: false,
+        isRefetching: false,
+        isStale: false,
+        promise: Promise.resolve({
+            pages: [['item1'], ['item2']],
+            pageParams: [undefined, 'next-page'],
+        }),
+    });
+
+    describe('plain data source', () => {
+        const plainDataSource: AnyPlainQueryDataSource = {
+            type: 'plain',
+            name: 'test-plain',
+            fetch: jest.fn().mockResolvedValue({data: 'test-data'}),
+        };
+
+        it('should wrap refetch when no enabled option', async () => {
+            const originalRefetch = jest.fn().mockResolvedValue({data: 'test', status: 'success'});
+            mockUseQuery.mockReturnValue(createMockQueryResult(originalRefetch) as any);
+
+            const {result} = renderHook(() => useQueryData(plainDataSource, {id: 1}));
+
+            expect(result.current.refetch).not.toBe(originalRefetch);
+            expect(result.current.refetch).not.toBe(mockWarnDisabledRefetch);
+
+            await result.current.refetch();
+            expect(originalRefetch).toHaveBeenCalledTimes(1);
+        });
+
+        it('should use warnDisabledRefetch when enabled: false', () => {
+            const originalRefetch = jest.fn();
+            mockUseQuery.mockReturnValue(createMockQueryResult(originalRefetch) as any);
+
+            const {result} = renderHook(() =>
+                useQueryData(plainDataSource, {id: 1}, {enabled: false}),
+            );
+
+            expect(result.current.refetch).toBe(mockWarnDisabledRefetch);
+            expect(result.current.refetch).not.toBe(originalRefetch);
+        });
+
+        it('should use warnDisabledRefetch when params is idle', () => {
+            const originalRefetch = jest.fn();
+            mockUseQuery.mockReturnValue(createMockQueryResult(originalRefetch) as any);
+
+            const {result} = renderHook(() => useQueryData(plainDataSource, idle));
+
+            expect(result.current.refetch).toBe(mockWarnDisabledRefetch);
+            expect(result.current.refetch).not.toBe(originalRefetch);
+        });
+    });
+
+    describe('infinite data source', () => {
+        const infiniteDataSource: AnyInfiniteQueryDataSource = {
+            type: 'infinite',
+            name: 'test-infinite',
+            fetch: jest.fn().mockResolvedValue({data: ['item1', 'item2']}),
+            next: jest.fn(),
+        };
+
+        it('should wrap refetch when no enabled option', async () => {
+            const originalRefetch = jest.fn().mockResolvedValue({
+                data: {pages: [], pageParams: []},
+                status: 'success',
+            });
+            mockUseInfiniteQuery.mockReturnValue(createMockInfiniteResult(originalRefetch) as any);
+
+            const {result} = renderHook(() => useQueryData(infiniteDataSource, {id: 1}));
+
+            expect(result.current.refetch).not.toBe(originalRefetch);
+            expect(result.current.refetch).not.toBe(mockWarnDisabledRefetch);
+
+            await result.current.refetch();
+            expect(originalRefetch).toHaveBeenCalledTimes(1);
+        });
+
+        it('should use warnDisabledRefetch when enabled: false', () => {
+            const originalRefetch = jest.fn();
+            mockUseInfiniteQuery.mockReturnValue(createMockInfiniteResult(originalRefetch) as any);
+
+            const {result} = renderHook(() =>
+                useQueryData(infiniteDataSource, {id: 1}, {enabled: false}),
+            );
+
+            expect(result.current.refetch).toBe(mockWarnDisabledRefetch);
+            expect(result.current.refetch).not.toBe(originalRefetch);
+        });
+
+        it('should use warnDisabledRefetch when params is idle', () => {
+            const originalRefetch = jest.fn();
+            mockUseInfiniteQuery.mockReturnValue(createMockInfiniteResult(originalRefetch) as any);
+
+            const {result} = renderHook(() => useQueryData(infiniteDataSource, idle));
+
+            expect(result.current.refetch).toBe(mockWarnDisabledRefetch);
+            expect(result.current.refetch).not.toBe(originalRefetch);
+        });
+    });
+});

src/react-query/impl/infinite/hooks.ts

@@ -1,6 +1,6 @@
 import {useMemo} from 'react';
 
-import {useInfiniteQuery} from '@tanstack/react-query';
+import {skipToken, useInfiniteQuery} from '@tanstack/react-query';
 import type {InfiniteData, InfiniteQueryObserverOptions} from '@tanstack/react-query';
 
 import type {
@@ -16,6 +16,8 @@ import type {
 } from '../../../core';
 import {useRefetchInterval} from '../../hooks/useRefetchInterval';
 import {normalizeStatus} from '../../utils/normalizeStatus';
+import {warnDisabledRefetch} from '../../utils/warnDisabledRefetch';
+import {wrapRefetch} from '../../utils/wrapRefetch';
 
 import type {AnyInfiniteQueryDataSource, InfiniteQueryObserverExtendedOptions} from './types';
 import {composeOptions} from './utils';
@@ -63,11 +65,14 @@ export const useInfiniteQueryData = <TDataSource extends AnyInfiniteQueryDataSou
         [state.data],
     );
 
+    const isDisabled = composedOptions.enabled === false || composedOptions.queryFn === skipToken;
+
     return {
         ...state,
         status: normalizeStatus(state.status, state.fetchStatus),
         data: transformedData,
         originalStatus: state.status,
         originalData: state.data,
+        refetch: isDisabled ? warnDisabledRefetch : wrapRefetch(state.refetch),
     } as DataSourceState<TDataSource>;
 };

src/react-query/impl/infinite/types.ts

@@ -84,6 +84,7 @@ type ResultWrapper<TResult, TRequest, TResponse, TData, TError> =
               {
                   status: DataLoaderStatus;
                   data: Array<FlatArray<Array<ActualData<TData, TResponse>>, 1>>;
+                  refetch: () => Promise<void>;
               }
           > & {
               originalStatus: TResult['status'];

src/react-query/impl/plain/hooks.ts

@@ -1,4 +1,4 @@
-import {type QueryObserverOptions, useQuery} from '@tanstack/react-query';
+import {type QueryObserverOptions, skipToken, useQuery} from '@tanstack/react-query';
 
 import type {
     DataSourceContext,
@@ -12,6 +12,8 @@ import type {
 } from '../../../core';
 import {useRefetchInterval} from '../../hooks/useRefetchInterval';
 import {normalizeStatus} from '../../utils/normalizeStatus';
+import {warnDisabledRefetch} from '../../utils/warnDisabledRefetch';
+import {wrapRefetch} from '../../utils/wrapRefetch';
 
 import type {AnyPlainQueryDataSource, QueryObserverExtendedOptions} from './types';
 import {composeOptions} from './utils';
@@ -52,9 +54,12 @@ export const usePlainQueryData = <TDataSource extends AnyPlainQueryDataSource>(
     const composedOptions = usePlainQueryDataOptions(extendedOptions);
     const state = useQuery(composedOptions);
 
+    const isDisabled = composedOptions.enabled === false || composedOptions.queryFn === skipToken;
+
     return {
         ...state,
         status: normalizeStatus(state.status, state.fetchStatus),
         originalStatus: state.status,
+        refetch: isDisabled ? warnDisabledRefetch : wrapRefetch(state.refetch),
     } as DataSourceState<TDataSource>;
 };

src/react-query/impl/plain/types.ts

@@ -53,5 +53,11 @@ export type AnyPlainQueryDataSource = PlainQueryDataSource<any, any, any, any, a
 
 type ResultWrapper<TResult, TResponse, TData, TError> =
     TResult extends QueryObserverResult<ActualData<TData, TResponse>, TError>
-        ? Overwrite<TResult, {status: DataLoaderStatus}> & {originalStatus: TResult['status']}
+        ? Overwrite<
+              TResult,
+              {
+                  status: DataLoaderStatus;
+                  refetch: () => Promise<void>;
+              }
+          > & {originalStatus: TResult['status']}
         : never;

src/react-query/types/options.ts

@@ -11,6 +11,11 @@ export interface QueryDataAdditionalOptions<
     TQueryKey extends QueryKey = QueryKey,
 > {
     refetchInterval?: RefetchInterval<TQueryFnData, TError, TQueryData, TQueryKey>;
+    /**
+     * @deprecated The use of the enabled option is deprecated.
+     * It is recommended to use idle as query parameters to control query state.
+     */
+    enabled?: boolean;
     /** Normalization configuration (enable/disable) */
     normalize?: boolean;
     /** Optimistic data update configuration */

src/react-query/utils/warn.ts

@@ -0,0 +1,8 @@
+export function warn(msg: string) {
+    if (!msg || process.env.NODE_ENV === 'production') {
+        return;
+    }
+
+    // eslint-disable-next-line no-console
+    console.warn(msg);
+}

src/react-query/utils/warnDisabledRefetch.ts

@@ -0,0 +1,5 @@
+import {warn} from './warn';
+
+export const warnDisabledRefetch = async (): Promise<void> => {
+    warn('Disabled refetch is called');
+};

src/react-query/utils/wrapRefetch.ts

@@ -0,0 +1,9 @@
+import type {QueryObserverResult, RefetchOptions} from '@tanstack/react-query';
+
+export function wrapRefetch<TData, TError>(
+    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<TData, TError>>,
+): (options?: RefetchOptions) => Promise<void> {
+    return async (options?: RefetchOptions) => {
+        await refetch(options);
+    };
+}