@firtoz/router-toolkit 1.0.0 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @firtoz/router-toolkit
 
-Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management.
+Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management for React Router 7 framework mode.
 
 ## Features
 
@@ -31,7 +31,7 @@ This package requires the following peer dependencies:
 {
   "react": "^18.0.0 || ^19.0.0",
   "react-router": "^7.0.0",
-  "zod": "^4.0.0"
+  "zod": "^4.0.5"
 }
 ```
 
@@ -86,21 +86,37 @@ function CachedComponent() {
 
 Type-safe form submission with Zod validation and enhanced submit functionality.
 
+**Basic Usage Pattern:**
+
 ```tsx
-import { useDynamicSubmitter } from '@firtoz/router-toolkit';
+// app/routes/contact.tsx
+import { useDynamicSubmitter, type RoutePath } from '@firtoz/router-toolkit';
 import { z } from 'zod/v4';
 
-const formSchema = z.object({
+// 1. Define your form schema
+export const formSchema = z.object({
   name: z.string(),
   email: z.string().email(),
 });
 
-function ContactForm() {
-  const submitter = useDynamicSubmitter('/api/contact');
+// 2. Export route constant
+export const route: RoutePath<"contact"> = "contact";
 
-  const handleSubmit = (formData: z.infer<typeof formSchema>) => {
-    submitter.submit(formData, { method: 'POST' });
-  };
+// 3. Define your action
+export const action = async ({ request }) => {
+  const formData = await request.formData();
+  // Handle submission
+  return { success: true };
+};
+
+// 4. Use the hook (requires full route module setup)
+export default function ContactForm() {
+  // Note: This requires proper route module registration
+  const submitter = useDynamicSubmitter<{
+    file: "contact";
+    action: typeof action;
+    formSchema: typeof formSchema;
+  }>("contact");
 
   return (
     <submitter.Form method="POST">
@@ -112,6 +128,8 @@ function ContactForm() {
 }
 ```
 
+**Note:** `useDynamicSubmitter` requires advanced setup with route module registration and Zod schemas. For simpler use cases, you may prefer React Router's built-in `useFetcher`.
+
 ### `useFetcherStateChanged`
 
 Track changes in fetcher state and react to them.
@@ -171,7 +189,44 @@ type ProfileArgs = HrefArgs<'/profile/:id'>;
 
 ## Usage with React Router 7 Framework Mode
 
-This toolkit is specifically designed for React Router 7's framework mode. Make sure your routes are properly typed in your `react-router.config.ts`:
+This toolkit is specifically designed for React Router 7's framework mode. Here's the recommended pattern for setting up routes with router-toolkit:
+
+### Route Setup Pattern
+
+For each route file, follow this pattern to enable full type safety:
+
+```tsx
+// app/routes/users.tsx
+import { useDynamicFetcher, type RoutePath } from '@firtoz/router-toolkit';
+
+// 1. Export your route constant with proper typing
+export const route: RoutePath<"users"> = "users";
+
+// 2. Define your loader/action as usual
+export const loader = async () => {
+  return { users: [] }; // Your data
+};
+
+// 3. Use the hook with typeof import for full type inference
+export default function UsersPage() {
+  const fetcher = useDynamicFetcher<typeof import("./users")>("users");
+
+  const handleRefresh = () => {
+    fetcher.load(); // No need to specify URL - it's inferred
+  };
+
+  return (
+    <div>
+      <button onClick={handleRefresh}>Refresh</button>
+      {fetcher.data && <div>{JSON.stringify(fetcher.data)}</div>}
+    </div>
+  );
+}
+```
+
+### Configuration
+
+Make sure your routes are properly typed in your `react-router.config.ts`:
 
 ```tsx
 // react-router.config.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firtoz/router-toolkit",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "description": "Type-safe React Router 7 framework mode helpers with enhanced fetching, form submission, and state management",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -25,9 +25,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check src",
     "format": "biome format src --write",
-    "test": "echo 'No tests yet'",
-    "semantic-release": "semantic-release",
-    "prepare": "husky"
+    "test": "echo 'No tests yet'"
   },
   "keywords": [
     "react-router",
@@ -44,31 +42,17 @@
   "homepage": "https://github.com/firtoz/router-toolkit#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/firtoz/router-toolkit.git"
+    "url": "https://github.com/firtoz/router-toolkit.git",
+    "directory": "packages/router-toolkit"
   },
   "bugs": {
     "url": "https://github.com/firtoz/router-toolkit/issues"
   },
   "peerDependencies": {
+    "@firtoz/maybe-error": "^1.2.1",
     "react": "^19.1.0",
     "react-router": "^7.6.3",
-    "zod": "^3.25.69"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.0.6",
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^11.0.3",
-    "@semantic-release/npm": "^12.0.2",
-    "@types/react": "^19.1.8",
-    "husky": "^9.1.7",
-    "react": "^19.1.0",
-    "react-router": "^7.6.3",
-    "semantic-release": "^24.2.7",
-    "typescript": "^5.8.3",
-    "zod": "^3.25.74"
+    "zod": "^4.0.5"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./useCachedFetch";
 export * from "./useDynamicFetcher";
 export * from "./useDynamicSubmitter";
 export * from "./useFetcherStateChanged";
+// Test comment to trigger release

package/src/types/RouteWithLoaderModule.ts

@@ -2,6 +2,6 @@ import type { Func } from "./Func";
 import type { RegisterPages } from "./RegisterPages";
 
 export type RouteWithLoaderModule = {
-	file: keyof RegisterPages;
+	route: keyof RegisterPages;
 	loader: Func;
 };

package/src/types/index.ts

@@ -1,3 +1,6 @@
+export * from "@firtoz/maybe-error";
+export * from "./Func";
 export * from "./HrefArgs";
-export * from "./MaybeError";
+export * from "./RegisterPages";
 export * from "./RoutePath";
+export * from "./RouteWithLoaderModule";

package/src/useCachedFetch.ts

@@ -8,10 +8,10 @@ const fetchCache = new Map<string, unknown>();
 
 // Hook that uses regular fetch instead of useFetcher to avoid route invalidation
 export const useCachedFetch = <TInfo extends RouteWithLoaderModule>(
-	path: TInfo["file"],
-	...args: TInfo["file"] extends "undefined"
+	path: TInfo["route"],
+	...args: TInfo["route"] extends "undefined"
 		? HrefArgs<"/">
-		: HrefArgs<TInfo["file"]>
+		: HrefArgs<TInfo["route"]>
 ): {
 	data: ReturnType<typeof useLoaderData<TInfo["loader"]>> | undefined;
 	isLoading: boolean;
@@ -19,7 +19,8 @@ export const useCachedFetch = <TInfo extends RouteWithLoaderModule>(
 } => {
 	// Generate URL using href, same as useDynamicFetcher
 	const url = useMemo(() => {
-		return href<typeof path>(path, ...args);
+		// biome-ignore lint/suspicious/noExplicitAny: Typechecks complain about this so we need to cast to any
+		return (href as any)(path, ...args);
 	}, [path, args]);
 
 	// Use the generated URL as the cache key

package/src/useDynamicFetcher.ts

@@ -4,15 +4,16 @@ import type { HrefArgs } from "./types/HrefArgs";
 import type { RouteWithLoaderModule } from "./types/RouteWithLoaderModule";
 
 export const useDynamicFetcher = <TInfo extends RouteWithLoaderModule>(
-	path: TInfo["file"],
-	...args: TInfo["file"] extends "undefined"
+	path: TInfo["route"],
+	...args: TInfo["route"] extends "undefined"
 		? HrefArgs<"/">
-		: HrefArgs<TInfo["file"]>
+		: HrefArgs<TInfo["route"]>
 ): Omit<ReturnType<typeof useFetcher<TInfo["loader"]>>, "load" | "submit"> & {
 	load: (queryParams?: Record<string, string>) => Promise<void>;
 } => {
 	const url = useMemo(() => {
-		return href<typeof path>(path, ...args);
+		// biome-ignore lint/suspicious/noExplicitAny: Typechecks complain about this so we need to cast to any
+		return (href as any)(path, ...args);
 	}, [path, args]);
 
 	const fetcher = useFetcher<TInfo["loader"]>({

package/src/useDynamicSubmitter.tsx

@@ -12,9 +12,9 @@ import type { HrefArgs } from "./types/HrefArgs";
 import type { RegisterPages } from "./types/RegisterPages";
 
 type RouteModule = {
-	file: keyof RegisterPages;
+	route: keyof RegisterPages;
 	action: Func;
-	formSchema: z.ZodTypeAny;
+	formSchema: z.ZodType;
 };
 
 type SubmitFunc<TModule extends RouteModule> = (
@@ -34,10 +34,10 @@ type SubmitForm = (
 ) => React.ReactElement;
 
 export const useDynamicSubmitter = <TInfo extends RouteModule>(
-	path: TInfo["file"],
-	...args: TInfo["file"] extends "undefined"
+	path: TInfo["route"],
+	...args: TInfo["route"] extends "undefined"
 		? HrefArgs<"/">
-		: HrefArgs<TInfo["file"]>
+		: HrefArgs<TInfo["route"]>
 ): Omit<
 	ReturnType<typeof useFetcher<TInfo["action"]>>,
 	"load" | "submit" | "Form"
@@ -46,7 +46,8 @@ export const useDynamicSubmitter = <TInfo extends RouteModule>(
 	Form: SubmitForm;
 } => {
 	const url = useMemo(() => {
-		return href<typeof path>(path, ...args);
+		// biome-ignore lint/suspicious/noExplicitAny: Typechecks complain about this so we need to cast to any
+		return (href as any)(path, ...args);
 	}, [path, args]);
 
 	const fetcher = useFetcher<TInfo["action"]>({

package/src/types/MaybeError.ts

@@ -1,45 +0,0 @@
-export type DefiniteError<TError = string> = {
-	success: false;
-	error: TError;
-};
-
-export type DefiniteSuccess<T = undefined> = {
-	success: true;
-} & (T extends undefined
-	? {
-			result?: T;
-		}
-	: {
-			result: T;
-		});
-
-export type MaybeError<T = undefined, TError = string> =
-	| DefiniteSuccess<T>
-	| DefiniteError<TError>;
-
-export type AssumeSuccess<T extends MaybeError<unknown>> = Exclude<
-	T,
-	undefined
-> extends MaybeError<infer U>
-	? U
-	: never;
-
-export const success = <T = undefined>(
-	...params: T extends undefined ? [] : [T]
-): DefiniteSuccess<T> => {
-	if (params.length === 0) {
-		return { success: true } as unknown as DefiniteSuccess<T>;
-	}
-
-	return {
-		success: true,
-		result: params[0],
-	} as unknown as DefiniteSuccess<T>;
-};
-
-export const fail = <TError = string>(error: TError): DefiniteError<TError> => {
-	return {
-		success: false,
-		error,
-	};
-};