add tag operations to query client

Author: KurtGokhan

examples/vite/src/App.tsx

@@ -2,7 +2,7 @@ import './mocks';
 import { useRef, useState } from 'react';
 import { CommentData, PostData, baseUrl } from './mocks';
 import './App.css';
-import { HttpQueryBuilder, useOperateOnTags } from 'react-query-builder';
+import { HttpQueryBuilder } from 'react-query-builder';
 import { queryClient } from './client';
 
 const baseQuery = new HttpQueryBuilder({
@@ -92,13 +92,13 @@ function App() {
 
   const deleteErrors = deletePostMutation.useMutationState(undefined, { status: 'error' }, (x) => x.state.variables?.params.id);
 
-  const [refresh] = useOperateOnTags({ tags: 'refreshable' });
+  const refresh = () => baseQuery.client.operateTags({ tags: 'refreshable', operation: 'reset' });
 
   if (postId) return <PostPage postId={postId} onBack={() => setPostId(null)} />;
 
   return (
     <>
-      <button onClick={() => refresh()} disabled={posts.isFetching}>
+      <button onClick={refresh} disabled={posts.isFetching}>
         Refresh
       </button>
 

src/builder/QueryBuilder.ts

@@ -89,7 +89,7 @@ export class QueryBuilder<TVars, TData, TError, TKey extends unknown[], TTags ex
     return this as any;
   }
 
-  freeze(): QueryBuilderFrozen<TVars, TData, TError, TKey> {
+  freeze(): QueryBuilderFrozen<TVars, TData, TError, TKey, TTags> {
     return this;
   }
 

src/builder/QueryBuilderClient.ts

@@ -1,9 +1,20 @@
 import type { CancelOptions, InvalidateOptions, QueryFilters, RefetchOptions, ResetOptions, SetDataOptions } from '@tanstack/react-query';
+import { operateOnTags } from '../tags/operateOnTags';
+import { QueryTagContext, QueryUpdateTag, TagOperationOptions } from '../tags/types';
+import { updateTags } from '../tags/updateTags';
+import { WithOptional } from '../type-utils';
 import { QueryBuilderConfig, QueryBuilderFrozen } from './QueryBuilderFrozen';
 
-export class QueryBuilderClient<TVars, TData, TError, TKey extends unknown[], TFilters = QueryFilters<TData, TError, TData, TKey>> {
+export class QueryBuilderClient<
+  TVars,
+  TData,
+  TError,
+  TKey extends unknown[],
+  TTags extends Record<string, unknown>,
+  TFilters = QueryFilters<TData, TError, TData, TKey>,
+> {
   private declare _options: QueryBuilderConfig<TVars, TData, TError, TKey>['options'];
-  constructor(private builder: QueryBuilderFrozen<TVars, TData, TError, TKey>) {}
+  constructor(private builder: QueryBuilderFrozen<TVars, TData, TError, TKey, TTags>) {}
 
   readonly ensureData = (vars: TVars, opts?: typeof this._options) =>
     this.builder.config.queryClient?.ensureQueryData(this.builder.getQueryOptions(vars, opts));
@@ -47,6 +58,22 @@ export class QueryBuilderClient<TVars, TData, TError, TKey extends unknown[], TF
     this.builder.config.queryClient?.setQueryData<TData>(this.builder.getQueryKey(vars), updater, opts);
 
   readonly getState = (vars: TVars) => this.builder.config.queryClient?.getQueryState<TData, TError>(this.builder.getQueryKey(vars));
+
+  readonly operateTags = ({ tags = [], operation = 'invalidate', filters, options }: TagOperationOptions<TTags>) =>
+    operateOnTags({ queryClient: this.builder.config.queryClient!, tags, operation }, filters, options);
+
+  /**
+   * This function can be used to operate on queries based on tags.
+   */
+  readonly updateTags = ({
+    tags = [],
+    ctx: { client = this.builder.config.queryClient, ...ctx },
+    optimistic = false,
+  }: {
+    tags: readonly QueryUpdateTag<TVars, TData, TError, TTags>[];
+    ctx: WithOptional<QueryTagContext<TVars, TData, TError>, 'client'>;
+    optimistic?: boolean;
+  }) => updateTags({ tags, queryClient: client!, ctx: { client: client!, ...ctx }, optimistic });
 }
 
 type SetDataUpdater<T> = T | undefined | ((oldData: T | undefined) => T | undefined);

src/builder/QueryBuilderFrozen.ts

@@ -2,6 +2,7 @@ import {
   DataTag,
   InfiniteData,
   InfiniteQueryPageParamsOptions,
+  MutationFunction,
   QueryFilters,
   QueryFunction,
   UseInfiniteQueryOptions,
@@ -10,14 +11,18 @@ import {
   UseSuspenseInfiniteQueryResult,
   useInfiniteQuery,
   useIsFetching,
+  useMutation,
   usePrefetchInfiniteQuery,
   usePrefetchQuery,
   useQueries,
   useQuery,
+  useQueryClient,
   useSuspenseInfiniteQuery,
   useSuspenseQueries,
   useSuspenseQuery,
 } from '@tanstack/react-query';
+import { operateOnTags } from '../tags/operateOnTags';
+import { TagOperationOptions } from '../tags/types';
 import { FunctionType, TODO } from '../type-utils';
 import { QueryBuilderClient } from './QueryBuilderClient';
 import { BuilderConfig, BuilderQueriesResult } from './types';
@@ -174,7 +179,24 @@ export class QueryBuilderFrozen<
     return useSuspenseInfiniteQuery(this.getInfiniteQueryOptions(vars, opts), this.config.queryClient);
   };
 
-  private _client?: QueryBuilderClient<TVars, TData, TError, TKey>;
+  /**
+   * This hook returns a function that can be used to operate on queries based on tags.
+   * It also returns the mutation object that can be used to track the state of the operation.
+   * See `operateOnTags` for more information.
+   */
+  useTagOperation(opts?: TagOperationOptions<TTags> | void) {
+    const queryClient = useQueryClient();
+    const mutationFn: MutationFunction<unknown, TagOperationOptions<TTags> | void> = (
+      { tags = [], operation = 'invalidate', filters, options } = opts || {},
+    ) => operateOnTags({ queryClient, tags, operation }, filters, options);
+
+    const mutation = useMutation({ mutationFn });
+    const operate = mutation.mutateAsync;
+
+    return [operate, mutation] as const;
+  }
+
+  private _client?: QueryBuilderClient<TVars, TData, TError, TKey, TTags>;
   get client() {
     return (this._client ??= new QueryBuilderClient(this));
   }

src/index.ts

@@ -4,4 +4,3 @@ export * from './builder/MutationBuilder';
 export * from './builder/HttpMutationBuilder';
 export type { MiddlewareFn, MiddlewareContext, MiddlewareNextFn } from './builder/createMiddlewareFunction';
 export * from './http/request';
-export * from './tags/useOperateOnTags';

src/tags/types.ts

@@ -1,5 +1,6 @@
-import type { QueryClient } from '@tanstack/react-query';
+import type { InvalidateOptions, InvalidateQueryFilters, QueryClient } from '@tanstack/react-query';
 import { KeysOfValue, StringLiteral } from '../type-utils';
+import { OperateOnTagsOperation } from './operateOnTags';
 
 export type TagMap = Record<string, unknown>;
 
@@ -23,7 +24,7 @@ export type QueryTagCallback<TVars = void, TData = unknown, TErr = unknown, TTag
   ctx: QueryTagContext<TVars, TData, TErr>,
 ) => TTag | readonly TTag[];
 
-export type QueryTagStaticOption<TTag extends QueryTagObject = QueryTagObject> = '*' | QueryTag<TTag> | readonly QueryTag<TTag>[];
+export type QueryTagStaticOption<TTag extends QueryTagObject<any> = QueryTagObject<any>> = '*' | QueryTag<TTag> | readonly QueryTag<TTag>[];
 
 export type QueryTagOption<TVars = unknown, TData = unknown, TErr = unknown, TTag extends QueryTagObject<any> = QueryTagObject<any>> =
   | QueryTagStaticOption<TTag>
@@ -81,3 +82,10 @@ export type QueryUpdateTag<TVars = unknown, TData = unknown, TErr = unknown, TMa
 >;
 
 export type QueryTagCache = Record<string | number, Record<string, QueryTagObject[]>>;
+
+export type TagOperationOptions<TMap extends TagMap = TagMap> = {
+  tags?: QueryTagStaticOption<QueryTagObject<TMap>>;
+  operation?: OperateOnTagsOperation;
+  filters?: InvalidateQueryFilters;
+  options?: InvalidateOptions;
+};

src/tags/updateTags.ts

@@ -1,6 +1,4 @@
-import { type InfiniteData, InfiniteQueryObserver, type QueryClient, type QueryState, useQueryClient } from '@tanstack/react-query';
-import { useStableCallback } from '../hooks/useStableCallback';
-import type { WithOptional } from '../type-utils';
+import { type InfiniteData, InfiniteQueryObserver, type QueryClient, type QueryState } from '@tanstack/react-query';
 import { queryMatchesTag } from './operateOnTags';
 import type { QueryTagContext, QueryUpdateTag } from './types';
 import { getUpdater } from './updaters';
@@ -93,28 +91,3 @@ function setDataToExistingQuery(
   query?.setData(newData);
   if (state || meta) query?.setState(state || {}, { meta });
 }
-
-/**
- * This hook returns a function that can be used to operate on queries based on tags.
- * It also returns the mutation object that can be used to track the state of the operation.
- * See `operateOnTags` for more information.
- */
-export function useUpdateTags(base?: {
-  tags?: readonly QueryUpdateTag<any, any, any, any>[];
-  ctx?: QueryTagContext<unknown>;
-  optimistic?: boolean;
-}) {
-  const queryClient = useQueryClient();
-  const update = useStableCallback(
-    ({
-      tags = base?.tags || [],
-      ctx = base?.ctx || { client: queryClient, vars: undefined, data: undefined },
-      optimistic = base?.optimistic,
-    }: {
-      tags: readonly QueryUpdateTag<any, any, any, any>[];
-      ctx: WithOptional<QueryTagContext<unknown>, 'client'>;
-      optimistic?: boolean;
-    }) => updateTags({ tags, queryClient, ctx: { client: queryClient, ...ctx }, optimistic }),
-  );
-  return update;
-}