@firtoz/router-toolkit 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firtoz/router-toolkit",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "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",
@@ -11,7 +11,10 @@
       "import": "./src/index.ts",
       "require": "./src/index.ts"
     },
-    "./*": ["./src/*.ts", "./src/*.tsx"]
+    "./*": [
+      "./src/*.ts",
+      "./src/*.tsx"
+    ]
   },
   "files": [
     "src/**/*",
@@ -20,8 +23,12 @@
   "scripts": {
     "build": "echo 'No build step - using TypeScript source directly'",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
-    "test": "echo 'No tests yet'"
+    "lint": "biome check src",
+    "format": "biome format src --write",
+    "test": "echo 'No tests yet'",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
   },
   "keywords": [
     "react-router",
@@ -49,6 +56,8 @@
     "zod": "^3.25.69"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.0.6",
+    "@changesets/cli": "^2.29.5",
     "@types/react": "^19.1.8",
     "react": "^19.1.0",
     "react-router": "^7.6.3",

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./types/index";
+export * from "./useCachedFetch";
+export * from "./useDynamicSubmitter";
+export * from "./useDynamicSubmitter";
+export * from "./useFetcherStateChanged";

package/src/types/Func.ts

@@ -1,2 +1,2 @@
 // biome-ignore lint/suspicious/noExplicitAny: We really want to use any here
-export type Func = (...args: any[]) => unknown; 
+export type Func = (...args: any[]) => unknown;

package/src/types/HrefArgs.ts

@@ -1,17 +1,8 @@
-import type { href, Register } from "react-router";
-
-type AnyParams = Record<string, string | undefined>;
-type AnyPages = Record<string, {
-	params: AnyParams;
-}>;
-
-export type RegisterPages = Register extends {
-	pages: infer Registered extends AnyPages;
-} ? Registered : AnyPages;
-
-export type HrefArgs<T extends keyof RegisterPages> = Parameters<typeof href<T>> extends [
-	string,
-	...infer Rest,
-] ? Rest : [];
-
-export type RoutePath<TPath extends keyof RegisterPages> = TPath;
+import type { href } from "react-router";
+import type { RegisterPages } from "./RegisterPages";
+
+export type HrefArgs<T extends keyof RegisterPages> = Parameters<
+	typeof href<T>
+> extends [string, ...infer Rest]
+	? Rest
+	: [];

package/src/types/MaybeError.ts

@@ -0,0 +1,45 @@
+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,
+	};
+};

package/src/types/RegisterPages.ts

@@ -0,0 +1,15 @@
+import type { Register } from "react-router";
+
+type AnyParams = Record<string, string | undefined>;
+type AnyPages = Record<
+	string,
+	{
+		params: AnyParams;
+	}
+>;
+
+export type RegisterPages = Register extends {
+	pages: infer Registered extends AnyPages;
+}
+	? Registered
+	: AnyPages;

package/src/types/RoutePath.ts

@@ -0,0 +1,3 @@
+import type { RegisterPages } from "./RegisterPages";
+
+export type RoutePath<TPath extends keyof RegisterPages> = TPath;

package/src/types/RouteWithLoaderModule.ts

@@ -0,0 +1,7 @@
+import type { Func } from "./Func";
+import type { RegisterPages } from "./RegisterPages";
+
+export type RouteWithLoaderModule = {
+	file: keyof RegisterPages;
+	loader: Func;
+};

package/src/types/index.ts

@@ -1,2 +1,3 @@
-export type { Func } from "./Func";
-export type { HrefArgs,RoutePath } from "./HrefArgs";
+export * from "./HrefArgs";
+export * from "./MaybeError";
+export * from "./RoutePath";

package/src/useCachedFetch.ts

@@ -0,0 +1,75 @@
+import { useEffect, useMemo, useState } from "react";
+import { href, type useLoaderData } from "react-router";
+import type { HrefArgs } from "./types/HrefArgs";
+import type { RouteWithLoaderModule } from "./types/RouteWithLoaderModule";
+
+// Cache for the useCachedFetch hook (regular fetch, not useFetcher)
+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"
+		? HrefArgs<"/">
+		: HrefArgs<TInfo["file"]>
+): {
+	data: ReturnType<typeof useLoaderData<TInfo["loader"]>> | undefined;
+	isLoading: boolean;
+	error: Error | undefined;
+} => {
+	// Generate URL using href, same as useDynamicFetcher
+	const url = useMemo(() => {
+		return href<typeof path>(path, ...args);
+	}, [path, args]);
+
+	// Use the generated URL as the cache key
+	const cacheKey = url;
+
+	// Local state
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState<Error | undefined>(undefined);
+	const [data, setData] = useState<
+		ReturnType<typeof useLoaderData<TInfo["loader"]>> | undefined
+	>(() =>
+		fetchCache.has(cacheKey)
+			? (fetchCache.get(cacheKey) as ReturnType<
+					typeof useLoaderData<TInfo["loader"]>
+				>)
+			: undefined,
+	);
+
+	// Auto-fetch on mount or when URL changes, if not in cache
+	useEffect(() => {
+		const fetchData = async () => {
+			// Skip fetch if data is already cached
+			if (fetchCache.has(cacheKey)) {
+				return;
+			}
+
+			setIsLoading(true);
+			setError(undefined);
+
+			try {
+				const response = await fetch(url);
+
+				if (!response.ok) {
+					throw new Error(`HTTP error! Status: ${response.status}`);
+				}
+
+				const result = await response.json();
+
+				// Update cache and state
+				fetchCache.set(cacheKey, result);
+				setData(result as ReturnType<typeof useLoaderData<TInfo["loader"]>>);
+			} catch (err) {
+				setError(err instanceof Error ? err : new Error(String(err)));
+			} finally {
+				setIsLoading(false);
+			}
+		};
+
+		fetchData();
+	}, [url, cacheKey]);
+
+	return { data, isLoading, error };
+};

package/src/useDynamicFetcher.ts

@@ -1,16 +1,13 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
-import { href, useFetcher, type useLoaderData } from "react-router";
-import type { Func } from "./types/Func";
-import type { HrefArgs, RegisterPages } from "./types/HrefArgs";
+import { useCallback, useMemo } from "react";
+import { href, useFetcher } from "react-router";
+import type { HrefArgs } from "./types/HrefArgs";
+import type { RouteWithLoaderModule } from "./types/RouteWithLoaderModule";
 
-type RouteModule = {
-	file: keyof RegisterPages;
-	loader: Func;
-};
-
-export const useDynamicFetcher = <TInfo extends RouteModule>(
+export const useDynamicFetcher = <TInfo extends RouteWithLoaderModule>(
 	path: TInfo["file"],
-	...args: TInfo["file"] extends "undefined" ? HrefArgs<"/"> : HrefArgs<TInfo["file"]>
+	...args: TInfo["file"] extends "undefined"
+		? HrefArgs<"/">
+		: HrefArgs<TInfo["file"]>
 ): Omit<ReturnType<typeof useFetcher<TInfo["loader"]>>, "load" | "submit"> & {
 	load: (queryParams?: Record<string, string>) => Promise<void>;
 } => {
@@ -44,84 +41,3 @@ export const useDynamicFetcher = <TInfo extends RouteModule>(
 		load,
 	};
 };
-
-// Cache for the useCachedFetch hook (regular fetch, not useFetcher)
-const fetchCache = new Map<string, unknown>();
-
-// Hook that uses regular fetch instead of useFetcher to avoid route invalidation
-export const useCachedFetch = <
-	TInfo extends {
-		file: string;
-		module: RouteModule;
-	},
->(
-	path: TInfo["file"] extends "undefined"
-		? "/"
-		: `/${TInfo["file"]}` extends keyof RegisterPages
-		? `/${TInfo["file"]}`
-		: never,
-	...args: TInfo["file"] extends "undefined"
-		? HrefArgs<"/">
-		: `/${TInfo["file"]}` extends keyof RegisterPages
-		? HrefArgs<`/${TInfo["file"]}`>
-		: never
-): {
-	data: ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>> | undefined;
-	isLoading: boolean;
-	error: Error | undefined;
-} => {
-	// Generate URL using href, same as useDynamicFetcher
-	const url = useMemo(() => {
-		// biome-ignore lint/suspicious/noExplicitAny: Complex conditional typing prevents TypeScript from inferring args when spreading
-		return href<typeof path>(path, ...(args as any));
-	}, [path, args]);
-
-	// Use the generated URL as the cache key
-	const cacheKey = url;
-
-	// Local state
-	const [isLoading, setIsLoading] = useState(false);
-	const [error, setError] = useState<Error | undefined>(undefined);
-	const [data, setData] = useState<
-		ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>> | undefined
-	>(() =>
-		fetchCache.has(cacheKey)
-			? (fetchCache.get(cacheKey) as ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>>)
-			: undefined,
-	);
-
-	// Auto-fetch on mount or when URL changes, if not in cache
-	useEffect(() => {
-		const fetchData = async () => {
-			// Skip fetch if data is already cached
-			if (fetchCache.has(cacheKey)) {
-				return;
-			}
-
-			setIsLoading(true);
-			setError(undefined);
-
-			try {
-				const response = await fetch(url);
-
-				if (!response.ok) {
-					throw new Error(`HTTP error! Status: ${response.status}`);
-				}
-
-				const result = await response.json();
-
-				// Update cache and state
-				fetchCache.set(cacheKey, result);
-				setData(result as ReturnType<typeof useLoaderData<TInfo["module"]["loader"]>>);
-			} catch (err) {
-				setError(err instanceof Error ? err : new Error(String(err)));
-			} finally {
-				setIsLoading(false);
-			}
-		};
-
-		fetchData();
-	}, [url, cacheKey]);
-
-	return { data, isLoading, error };
-}; 

package/src/useDynamicSubmitter.tsx

@@ -7,8 +7,9 @@ import {
 	useFetcher,
 } from "react-router";
 import type { z } from "zod/v4";
-import { HrefArgs, RegisterPages } from "./types/HrefArgs";
-import { Func } from "./types";
+import type { Func } from "./types/Func";
+import type { HrefArgs } from "./types/HrefArgs";
+import type { RegisterPages } from "./types/RegisterPages";
 
 type RouteModule = {
 	file: keyof RegisterPages;
@@ -24,21 +25,28 @@ type SubmitFunc<TModule extends RouteModule> = (
 ) => Promise<void>;
 
 type SubmitForm = (
-	props: Omit<FetcherFormProps & React.RefAttributes<HTMLFormElement>, "action" | "method"> & {
+	props: Omit<
+		FetcherFormProps & React.RefAttributes<HTMLFormElement>,
+		"action" | "method"
+	> & {
 		method: Exclude<SubmitOptions["method"], "GET">;
 	},
 ) => React.ReactElement;
 
 export const useDynamicSubmitter = <TInfo extends RouteModule>(
 	path: TInfo["file"],
-	...args: TInfo["file"] extends "undefined" ? HrefArgs<"/"> : HrefArgs<TInfo["file"]>
-): Omit<ReturnType<typeof useFetcher<TInfo["action"]>>, "load" | "submit" | "Form"> & {
+	...args: TInfo["file"] extends "undefined"
+		? HrefArgs<"/">
+		: HrefArgs<TInfo["file"]>
+): Omit<
+	ReturnType<typeof useFetcher<TInfo["action"]>>,
+	"load" | "submit" | "Form"
+> & {
 	submit: SubmitFunc<TInfo>;
 	Form: SubmitForm;
 } => {
 	const url = useMemo(() => {
-		// biome-ignore lint/suspicious/noExplicitAny: We are sure the args are correct
-		return href<typeof path>(path, ...(args as any));
+		return href<typeof path>(path, ...args);
 	}, [path, args]);
 
 	const fetcher = useFetcher<TInfo["action"]>({

package/src/useFetcherStateChanged.ts

@@ -8,7 +8,10 @@ import type { useFetcher } from "react-router";
  */
 export const useFetcherStateChanged = (
 	fetcher: Pick<ReturnType<typeof useFetcher>, "state">,
-	onChange: (lastState: typeof fetcher.state | undefined, newState: typeof fetcher.state) => void,
+	onChange: (
+		lastState: typeof fetcher.state | undefined,
+		newState: typeof fetcher.state,
+	) => void,
 ) => {
 	const lastStateRef = useRef<typeof fetcher.state>(fetcher.state);
 
@@ -18,4 +21,4 @@ export const useFetcherStateChanged = (
 			lastStateRef.current = fetcher.state;
 		}
 	}, [fetcher.state, onChange]);
-}; 
+};