add withMethod and withMeta

Author: KurtGokhan

README.md

@@ -16,23 +16,25 @@ It uses the builder pattern, the best pattern that works with complex Typescript
 
 - REST client using fetch API
 - Automaticly created query keys and easy invalidation
+- Customizable with middlewares
 - Tag based invalidation
 - Declarative optimistic updates
-- Ability to strongly type everything, from parameters to tags
+- Ability to strongly type everything
 
 ## Advantages
 
 - 💪 Strong-typed
 - 🧩 Consistently structured
 - 🚀 Features out-of-the-box
-- ⚙️ Customizable
+- ⚙️ Customizable and extendable
 - 🪶 Zero dependencies
 - 🚢 SSR and Router compatible
 
 ## TODO
 
 - Strong typed customizable tags
 - Infinite queries
+- OOTB Query Hash function
 
 ## Examples
 
@@ -48,21 +50,16 @@ const baseMutation = new HttpMutationBuilder().withBaseUrl(baseUrl);
 
 type PostData = { id: number; title: string; body: string; userId: number };
 
-const postsQuery = baseQuery
-  .withConfig({ tags: "refreshable" })
-  .withConfig({ tags: { type: "posts", id: "LIST" } })
-  .withPath("/posts")
-  .withData<PostData[]>();
+const postsQuery = baseQuery.withTags("refreshable", "posts").withPath("/posts").withData<PostData[]>();
 
-const deletePostMutation = baseMutation
-  .withConfig({ invalidates: { type: "posts", id: "LIST" } })
-  .withVars({ method: "delete" })
-  .withPath("/posts/:id");
+const deletePostMutation = baseMutation.withUpdates("posts").withMethod("delete").withPath("/posts/:id");
 
 export function MyApp() {
   const posts = postsQuery.useQuery({});
   const deletePost = deletePostMutation.useMutation();
 
+  const [refresh] = useOperateOnTags({ tags: "refreshable" });
+
   const onDelete = (id: number) => deletePost.mutateAsync({ params: { id } });
 
   if (!posts.isSuccess) return <>Loading...</>;
@@ -79,6 +76,8 @@ export function MyApp() {
           </button>
         </div>
       ))}
+
+      <button onClick={() => refresh()}>Refresh all posts</button>
     </>
   );
 }

examples/vite/src/App.tsx

@@ -40,7 +40,7 @@ const commentsQuery = baseQuery
 
 const editPostMutation = baseMutation
   .withPath('/posts/:id')
-  .withVars({ method: 'put' })
+  .withMethod('put')
   .withBody<Partial<PostData>>()
   .withUpdates<PostData | PostData[]>(
     {
@@ -68,7 +68,7 @@ const editPostMutation = baseMutation
   });
 
 const deletePostMutation = baseMutation
-  .withVars({ method: 'delete' })
+  .withMethod('delete')
   .withPath('/posts/:id')
   .withUpdates<PostData[]>({
     type: 'posts' as any,
@@ -89,7 +89,7 @@ function App() {
     (x) => x.state.variables?.params.id,
   );
 
-  const [refresh] = useOperateOnTags({ tags: ['refreshable'] });
+  const [refresh] = useOperateOnTags({ tags: 'refreshable' });
 
   if (postId) return <PostPage postId={postId} onBack={() => setPostId(null)} />;
 

src/builder/HttpMutationBuilder.ts

@@ -1,4 +1,4 @@
-import { ExtractPathParams } from '../http/types';
+import { ExtractPathParams, HttpMethod } from '../http/types';
 import { WithOptional } from '../types/utils';
 import { HttpQueryBuilder } from './HttpQueryBuilder';
 import { MutationBuilder, MutationBuilderConfig } from './MutationBuilder';
@@ -59,6 +59,11 @@ export class HttpMutationBuilder<
     return this.withVars({ search }) as any;
   }
 
+  withMeta<TMeta>(meta?: TMeta): HttpMutationBuilder<AppendVarsType<T, { meta: TMeta }>> {
+    if (!meta) return this as any;
+    return this.withVars({ meta }) as any;
+  }
+
   withPath<const TPath extends string>(
     path: TPath,
   ): ExtractPathParams<TPath> extends void
@@ -71,6 +76,10 @@ export class HttpMutationBuilder<
     return this.withVars({ baseUrl }) as any;
   }
 
+  withMethod(method: HttpMethod): this {
+    return this.withVars({ method }) as any;
+  }
+
   declare withData: <TData>() => HttpMutationBuilder<SetDataType<T, TData>>;
   declare withError: <TError>() => HttpMutationBuilder<SetErrorType<T, TError>>;
   declare withVars: <TVars = T['vars'], const TReset extends boolean = false>(

src/builder/HttpQueryBuilder.ts

@@ -1,4 +1,4 @@
-import { ExtractPathParams } from '../http/types';
+import { ExtractPathParams, HttpMethod } from '../http/types';
 import { WithOptional } from '../types/utils';
 import { HttpMutationBuilder } from './HttpMutationBuilder';
 import { MutationBuilder } from './MutationBuilder';
@@ -49,6 +49,11 @@ export class HttpQueryBuilder<T extends HttpBuilderTypeTemplate = HttpBuilderTyp
     return this.withVars({ search }) as any;
   }
 
+  withMeta<TMeta>(meta?: TMeta): HttpQueryBuilder<AppendVarsType<T, { meta: TMeta }>> {
+    if (!meta) return this as any;
+    return this.withVars({ meta }) as any;
+  }
+
   withPath<const TPath extends string>(
     path: TPath,
   ): ExtractPathParams<TPath> extends void
@@ -61,6 +66,10 @@ export class HttpQueryBuilder<T extends HttpBuilderTypeTemplate = HttpBuilderTyp
     return this.withVars({ baseUrl }) as any;
   }
 
+  withMethod(method: HttpMethod): this {
+    return this.withVars({ method }) as any;
+  }
+
   declare withData: <TData>() => HttpQueryBuilder<SetDataType<T, TData>>;
   declare withError: <TError>() => HttpQueryBuilder<SetErrorType<T, TError>>;
   declare withVars: <TVars = T['vars'], const TReset extends boolean = false>(

src/builder/utils.ts

@@ -80,10 +80,10 @@ export const mergeHttpVars: BuilderMergeVarsFn<HttpBuilderTypeTemplate['vars']>
 export function createHttpQueryFn<T extends HttpBuilderTypeTemplate>(
   mergeVarsFn: BuilderMergeVarsFn<T['vars']>,
 ): BuilderQueryFn<T> {
-  return async ({ queryKey, signal, meta, pageParam }: any) => {
+  return async ({ queryKey, signal, pageParam }) => {
     const [vars] = queryKey || [];
-    const mergedVars = mergeVarsFn(vars, pageParam);
-    return httpRequest<T['data']>({ ...(mergedVars as any), meta, signal });
+    const mergedVars = mergeVarsFn(vars, pageParam as Partial<T['vars']>);
+    return httpRequest<T['data']>({ ...(mergedVars as any), signal });
   };
 }
 

src/http/types.ts

@@ -15,7 +15,7 @@ export type HttpRequestPathParams = {
   [param: string]: PathParam;
 };
 
-export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options';
 
 // biome-ignore lint/suspicious/noEmptyInterface: <explanation>
 export interface HttpRequestMeta {}

src/tags/operateOnTags.ts

@@ -6,7 +6,8 @@ import {
   type QueryFilters,
   hashKey,
 } from '@tanstack/react-query';
-import type { QueryTag } from './types';
+import { resolveTags } from './resolveTags';
+import type { QueryTag, QueryTagStaticOption } from './types';
 
 /**
  * Based on the behavior described in https://redux-toolkit.js.org/rtk-query/usage/automated-refetching#tag-invalidation-behavior
@@ -47,20 +48,22 @@ export function operateOnTags(
     queryClient,
     operation = 'invalidate',
   }: {
-    tags: readonly QueryTag[];
+    tags: QueryTagStaticOption;
     queryClient: QueryClient;
     operation?: OperateOnTagsOperation;
   },
   filters?: InvalidateQueryFilters,
   options?: InvalidateOptions,
 ) {
-  if (!tags?.length) return Promise.resolve();
+  const resolvedTags = resolveTags({ tags, client: queryClient, vars: undefined });
+  if (!resolvedTags?.length) return Promise.resolve();
 
   const filtersObj: QueryFilters = {
     ...(operation === 'refetch' && { type: 'active' }),
     ...filters,
     predicate: (query) =>
-      tags.some((tag) => queryMatchesTag(queryClient, query, tag)) && (!filters?.predicate || filters.predicate(query)),
+      resolvedTags.some((tag) => queryMatchesTag(queryClient, query, tag)) &&
+      (!filters?.predicate || filters.predicate(query)),
   };
 
   if (operation === 'refetch') return queryClient.refetchQueries(filtersObj, options);

src/tags/types.ts

@@ -22,12 +22,17 @@ 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 QueryTagOption<
   TVars = void,
   TData = unknown,
   TErr = unknown,
   TTag extends QueryTagObject = QueryTagObject,
-> = '*' | QueryTag<TTag> | readonly QueryTag<TTag>[] | QueryTagCallback<TVars, TData, TErr, TTag>;
+> = QueryTagStaticOption<TTag> | QueryTagCallback<TVars, TData, TErr, TTag>;
 
 export type QueryUpdaterFn<TVars = unknown, TData = unknown, TErr = unknown, TTarget = unknown> = (
   ctx: QueryTagContext<TVars, TData, TErr>,

src/tags/updaters.ts

@@ -14,6 +14,7 @@ export function getUpdater<TVars = unknown, TData = unknown, TErr = unknown, TTa
     if (updaterKey === 'body') return ctx.vars?.body;
     if (updaterKey === 'params') return ctx.vars?.params;
     if (updaterKey === 'search') return ctx.vars?.search;
+    if (updaterKey === 'meta') return ctx.vars?.meta;
     return undefined;
   };
 
@@ -34,8 +35,8 @@ export function getUpdater<TVars = unknown, TData = unknown, TErr = unknown, TTa
       if (!target) return target;
 
       const data = getFromCtx(ctx);
-      const dataKey = data[byKey];
-      if (!dataKey) return target;
+      const dataKey = data?.[byKey];
+      if (dataKey == null) return target;
 
       if (Array.isArray(target)) {
         const foundIndex = target.findIndex((item) => item[byKey] === dataKey);
@@ -53,8 +54,8 @@ export function getUpdater<TVars = unknown, TData = unknown, TErr = unknown, TTa
       if (!target) return target;
 
       const data = getFromCtx(ctx);
-      const dataKey = data[byKey];
-      if (!dataKey) return target;
+      const dataKey = data?.[byKey];
+      if (dataKey == null) return target;
 
       if (Array.isArray(target)) {
         const foundIndex = target.findIndex((item) => item[byKey] === dataKey);
@@ -71,8 +72,8 @@ export function getUpdater<TVars = unknown, TData = unknown, TErr = unknown, TTa
       if (!target) return target;
 
       const data = getFromCtx(ctx);
-      const dataKey = data[byKey];
-      if (!dataKey) return target;
+      const dataKey = data?.[byKey];
+      if (dataKey == null) return target;
 
       if (Array.isArray(target)) {
         const foundIndex = target.findIndex((item) => item[byKey] === dataKey);
@@ -88,8 +89,8 @@ export function getUpdater<TVars = unknown, TData = unknown, TErr = unknown, TTa
       if (!target || typeof target !== 'object') return target;
 
       const data = getFromCtx(ctx);
-      const dataKey = data[byKey];
-      if (!dataKey) return target;
+      const dataKey = data?.[byKey];
+      if (dataKey == null) return target;
 
       if (Array.isArray(target)) {
         return target.filter((item) => item[byKey] !== dataKey);
@@ -105,8 +106,8 @@ export function getUpdater<TVars = unknown, TData = unknown, TErr = unknown, TTa
       if (!target) return target;
 
       const data = getFromCtx(ctx);
-      const dataKey = data[byKey];
-      if (!dataKey) return target;
+      const dataKey = data?.[byKey];
+      if (dataKey == null) return target;
 
       if (Array.isArray(target)) {
         const foundIndex = target.findIndex((item) => item[byKey] === dataKey);

src/tags/useOperateOnTags.ts

@@ -6,10 +6,10 @@ import {
   useQueryClient,
 } from '@tanstack/react-query';
 import { type OperateOnTagsOperation, operateOnTags } from './operateOnTags';
-import type { QueryTag } from './types';
+import type { QueryTagStaticOption } from './types';
 
 type OperateMutationOpts = {
-  tags?: QueryTag[];
+  tags?: QueryTagStaticOption;
   operation?: OperateOnTagsOperation;
   filters?: InvalidateQueryFilters;
   options?: InvalidateOptions;