@tpzdsp/next-toolkit 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A reusable React component library for Next.js applications",
   "packageManager": "pnpm@11.5.3",
   "engines": {

package/src/http/query.ts

@@ -9,9 +9,12 @@ import {
   type BetterFetchOption,
 } from '@better-fetch/fetch';
 import {
+  useMutation,
   useQuery,
   useSuspenseQuery,
   type QueryKey,
+  type UseMutationOptions,
+  type UseMutationResult,
   type UseQueryOptions,
   type UseQueryResult,
   type UseSuspenseQueryOptions,
@@ -84,8 +87,8 @@ type SchemaRoutesOf<Option extends CreateFetchOption> = Option extends {
   ? Routes
   : undefined;
 
-// We provide the `queryFn` and `queryKeys` automatically, so no need to let the user provide them.
-type OmitReactQueryKeys = 'queryKey' | 'queryFn';
+// We provide these keys automatically, so no need to let the user provide them.
+type OmitReactQueryKeys = 'queryKey' | 'queryFn' | 'mutationFn' | 'mutationKey';
 
 /**
  * A higher-order type that creates React Query hooks (`useBetterQuerySafe` and `useBetterSuspenseQuery`)
@@ -183,6 +186,75 @@ type ReactQueryBetterFetch = <
       OmitReactQueryKeys
     >,
   ): UseSuspenseQueryResult<Output>;
+
+  // Mutation query (error thrown)
+
+  // Overload that uses schema output (`RoutesWithOutput`)
+  useBetterMutation<
+    Error = ApiError,
+    Route extends RoutesWithOutput<Routes> = RoutesWithOutput<Routes>,
+  >(
+    route: Route,
+    // If the route requires an input, then expect options that provide that input, otherwise just expect options without inputs.
+    fetchOptions?: OptionsNoInputOutput,
+    queryOptions?: Omit<
+      UseMutationOptions<SchemaRouteOutput<Routes, Route>, Error, unknown, unknown>,
+      OmitReactQueryKeys
+    >,
+  ): UseMutationResult<
+    SchemaRouteOutput<Routes, Route>,
+    Error,
+    Route extends RoutesWithInput<Routes> ? OptionsWithInput<Routes, Route> : void
+  >;
+
+  // Overload that allows manual output type instead of schema (`RoutesWithoutOutput`)
+  useBetterMutation<
+    Output,
+    Error = ApiError,
+    Route extends RoutesWithoutOutput<Routes> = RoutesWithoutOutput<Routes>,
+  >(
+    route: Route,
+    fetchOptions?: OptionsNoInputOutput,
+    queryOptions?: Omit<UseMutationOptions<Output, Error, unknown, unknown>, OmitReactQueryKeys>,
+  ): UseMutationResult<
+    Output,
+    Error,
+    Route extends RoutesWithInput<Routes> ? OptionsWithInput<Routes, Route> : void
+  >;
+
+  // Safe mutation (error NOT thrown)
+
+  // Overload that uses schema output (`RoutesWithOutput`)
+  useBetterMutationSafe<
+    Error = ApiError,
+    Route extends RoutesWithOutput<Routes> = RoutesWithOutput<Routes>,
+  >(
+    route: Route,
+    fetchOptions?: OptionsNoInputOutput,
+    queryOptions?: Omit<
+      UseMutationOptions<SchemaRouteOutput<Routes, Route>, Error, unknown, unknown>,
+      OmitReactQueryKeys
+    >,
+  ): UseMutationResult<
+    SchemaRouteOutput<Routes, Route>,
+    Error,
+    Route extends RoutesWithInput<Routes> ? OptionsWithInput<Routes, Route> : void
+  >;
+
+  // Overload that allows manual output type instead of schema (`RoutesWithoutOutput`)
+  useBetterMutationSafe<
+    Output,
+    Error = ApiError,
+    Route extends RoutesWithoutOutput<Routes> = RoutesWithoutOutput<Routes>,
+  >(
+    route: Route,
+    fetchOptions?: OptionsNoInputOutput,
+    queryOptions?: Omit<UseMutationOptions<Output, Error, unknown, unknown>, OmitReactQueryKeys>,
+  ): UseMutationResult<
+    Output,
+    Error,
+    Route extends RoutesWithInput<Routes> ? OptionsWithInput<Routes, Route> : void
+  >;
 };
 
 /**
@@ -283,5 +355,50 @@ export const reactQueryBetterFetch: ReactQueryBetterFetch = <
     });
   };
 
-  return { useBetterQuerySafe, useBetterSuspenseQuery };
+  const useBetterMutation = <Route extends keyof Routes>(
+    route: Route,
+    fetchOptions?: InferOptions<FetchSchema, ''>,
+    queryOptions?: Omit<
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      UseMutationOptions<any, any, any, unknown>,
+      OmitReactQueryKeys | 'throwOnError'
+    >,
+  ) => {
+    return useMutation({
+      ...queryOptions,
+      mutationKey: [
+        route,
+        fetchOptions?.body,
+        fetchOptions?.params,
+        fetchOptions?.query,
+        fetchOptions?.headers,
+      ],
+      mutationFn: (inputs) => anyInstance(route, { ...fetchOptions, ...inputs }),
+      throwOnError: true,
+    });
+  };
+
+  const useBetterMutationSafe = <Route extends keyof Routes>(
+    route: Route,
+    fetchOptions?: InferOptions<FetchSchema, ''>,
+    queryOptions?: Omit<
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      UseMutationOptions<any, any, any, unknown>,
+      OmitReactQueryKeys | 'throwOnError'
+    >,
+  ) => {
+    return useMutation({
+      ...queryOptions,
+      mutationKey: [
+        route,
+        fetchOptions?.body,
+        fetchOptions?.params,
+        fetchOptions?.query,
+        fetchOptions?.headers,
+      ],
+      mutationFn: (inputs) => anyInstance(route, { ...fetchOptions, ...inputs }),
+    });
+  };
+
+  return { useBetterQuerySafe, useBetterMutationSafe, useBetterMutation, useBetterSuspenseQuery };
 };