@tpzdsp/next-toolkit 2.1.0 → 2.3.0

package/README.md

@@ -559,10 +559,32 @@ import '@your-org/nextjs-library/src/assets/styles/globals.css';
 4. Add tests for your changes (`src/test/YourComponent.test.tsx`)
 5. Run the test suite (`pnpm test`)
 6. Test with yalc in a real Next.js app
-7. Commit your changes (`git commit -m 'Add some amazing feature'`)
+7. Commit your changes following the [Angular commit message guidelines](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md) — the `commit-msg` hook enforces this via commitlint
 8. Push to the branch (`git push origin feature/amazing-feature`)
 9. Open a Pull Request
 
+### Commit Convention
+
+We follow the [Angular commit message guidelines](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md). Commits are validated by [commitlint](https://commitlint.io/) on every `git commit`. Allowed types come from `@commitlint/config-conventional`. Allowed scopes are defined in `commitlint.config.ts` — edit that file to add or remove scopes.
+
+#### Smoke-testing the commit hook
+
+Run these directly in the terminal to verify the hook is working after any changes to `commitlint.config.ts`:
+
+```bash
+# Should be rejected — wrong type
+printf 'feature(map): bad type\n\nBody text here explaining the change.' | pnpm commitlint
+
+# Should be rejected — unknown scope
+printf 'feat(unknown): bad scope\n\nBody text here explaining the change.' | pnpm commitlint
+
+# Should be rejected — missing body
+printf 'feat(map): missing body\n' | pnpm commitlint
+
+# Should pass
+printf 'feat(map): valid message\n\nThis explains what changed and why.' | pnpm commitlint
+```
+
 ### Code Style
 
 - Use TypeScript for all files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "A reusable React component library for Next.js applications",
   "packageManager": "pnpm@11.5.3",
   "engines": {
@@ -9,17 +9,17 @@
   },
   "type": "module",
   "private": false,
-  "homepage": "https://github.com/DSP3-apps/next-toolkit#readme",
+  "homepage": "https://github.com/agrimetrics/next-toolkit#readme",
   "author": "Mark Small",
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/DSP3-apps/next-toolkit.git"
+    "url": "git+https://github.com/agrimetrics/next-toolkit.git"
   },
   "bugs": {
-    "url": "https://github.com/DSP3-apps/next-toolkit/issues"
+    "url": "https://github.com/agrimetrics/next-toolkit/issues"
   },
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -127,6 +127,9 @@
   },
   "devDependencies": {
     "@better-fetch/fetch": "^1.1.21",
+    "@commitlint/cli": "^21.1.0",
+    "@commitlint/config-conventional": "^21.1.0",
+    "@commitlint/types": "^21.1.0",
     "@floating-ui/react": "^0.27.17",
     "@storybook/addon-docs": "10.3.5",
     "@storybook/addon-links": "10.3.5",

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 };
 };