@firtoz/router-toolkit 1.3.1 → 2.0.1

package/README.md

@@ -392,6 +392,228 @@ export default function NotificationForm() {
 - `idle` → `loading`: Data fetching started (with `useDynamicFetcher`)
 - `loading` → `idle`: Data fetching completed
 
+## Form Action Utilities
+
+### `formAction`
+
+Type-safe form action wrapper that provides Zod validation and structured error handling for React Router actions. This utility integrates seamlessly with `useDynamicSubmitter` and the `formSchema` export pattern.
+
+#### Features
+
+- ✅ **Automatic form data validation** using Zod schemas
+- 🛡️ **Type-safe error handling** with structured error types
+- 🔄 **MaybeError integration** for consistent error patterns
+- 🚀 **React Router compatibility** preserves redirects and responses
+- 📝 **Full TypeScript support** with inferred types from schemas
+
+#### Basic Usage
+
+```tsx
+// app/routes/register.tsx
+import { z } from "zod/v4";
+import { formAction, type RoutePath } from "@firtoz/router-toolkit";
+import { success, fail } from "@firtoz/maybe-error";
+
+// Export the schema for useDynamicSubmitter integration
+export const formSchema = z.object({
+  email: z.string().email("Invalid email format"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+  confirmPassword: z.string(),
+}).refine(data => data.password === data.confirmPassword, {
+  message: "Passwords don't match",
+  path: ["confirmPassword"],
+});
+
+export const action = formAction({
+  schema: formSchema,
+  handler: async (args, data) => {
+    // data is fully typed based on the schema
+    try {
+      const user = await createUser({
+        email: data.email,
+        password: data.password,
+      });
+      
+      return success({
+        message: "Registration successful!",
+        userId: user.id,
+      });
+    } catch (error) {
+      return fail("Email already exists");
+    }
+  },
+});
+
+export const route: RoutePath<"/register"> = "/register";
+```
+
+#### Using with useDynamicSubmitter
+
+The `formAction` utility works seamlessly with `useDynamicSubmitter` when you export a `formSchema`:
+
+```tsx
+// app/routes/register.tsx (component)
+import { useDynamicSubmitter } from "@firtoz/router-toolkit";
+
+export default function Register() {
+  const submitter = useDynamicSubmitter<typeof import("./register")>("/register");
+
+  return (
+    <submitter.Form method="post">
+      <input name="email" type="email" required />
+      <input name="password" type="password" required />
+      <input name="confirmPassword" type="password" required />
+      <button type="submit" disabled={submitter.state === "submitting"}>
+        {submitter.state === "submitting" ? "Registering..." : "Register"}
+      </button>
+    </submitter.Form>
+  );
+}
+```
+
+#### Error Handling
+
+The `formAction` utility returns structured errors that you can handle in your components:
+
+```tsx
+export default function Register() {
+  const submitter = useDynamicSubmitter<typeof import("./register")>("/register");
+
+  if (submitter.data && !submitter.data.success) {
+    const error = submitter.data.error;
+    
+    switch (error.type) {
+      case "validation":
+        // Handle Zod validation errors
+        console.log("Validation errors:", error.error);
+        break;
+      case "handler":
+        // Handle business logic errors
+        console.log("Handler error:", error.error);
+        break;
+      case "unknown":
+        // Handle unexpected errors
+        console.log("Unknown error occurred");
+        break;
+    }
+  }
+
+  // Rest of component...
+}
+```
+
+#### Error Types
+
+The `formAction` utility returns three types of errors:
+
+1. **Validation Errors** (`type: "validation"`)
+   - Occurs when form data doesn't match the Zod schema
+   - Contains detailed field-level validation errors from Zod
+   - The `error.error` field contains the result of `z.treeifyError()`
+
+2. **Handler Errors** (`type: "handler"`)
+   - Occurs when your handler function returns a `fail()` result
+   - Contains the custom error you provided to `fail()`
+   - The `error.error` field contains your custom error value
+
+3. **Unknown Errors** (`type: "unknown"`)
+   - Occurs when an unexpected exception is thrown
+   - Logs the error to console for debugging
+   - Does not expose the raw error to avoid information leakage
+
+#### Advanced Features
+
+**File Uploads**
+
+```tsx
+const uploadSchema = z.object({
+  title: z.string().min(1),
+  file: z.instanceof(File),
+  description: z.string().optional(),
+});
+
+export const action = formAction({
+  schema: uploadSchema,
+  handler: async (args, data) => {
+    const uploadResult = await uploadFile(data.file, {
+      title: data.title,
+      description: data.description,
+    });
+    
+    return success({ fileId: uploadResult.id });
+  },
+});
+```
+
+**Complex Validation**
+
+```tsx
+const complexSchema = z.object({
+  user: z.object({
+    name: z.string().min(2),
+    age: z.coerce.number().min(18),
+  }),
+  preferences: z.object({
+    newsletter: z.boolean().default(false),
+    theme: z.enum(["light", "dark"]).default("light"),
+  }),
+  terms: z.literal("on", { 
+    errorMap: () => ({ message: "You must accept the terms" }) 
+  }),
+});
+```
+
+**Redirects and Responses**
+
+React Router `Response` objects (like redirects) are automatically preserved:
+
+```tsx
+export const action = formAction({
+  schema: loginSchema,
+  handler: async (args, data) => {
+    const user = await authenticateUser(data.email, data.password);
+    
+    if (user) {
+      // This redirect will be properly handled by React Router
+      throw redirect("/dashboard");
+    }
+    
+    return fail("Invalid credentials");
+  },
+});
+```
+
+#### Type Safety
+
+The `formAction` utility provides full type safety:
+
+- **Schema inference**: Form data is typed based on your Zod schema
+- **Handler types**: Handler parameters are properly typed
+- **Error types**: Error handling is type-safe with discriminated unions
+- **Integration**: Works seamlessly with `useDynamicSubmitter` type inference
+
+#### API Reference
+
+```tsx
+function formAction<
+  TSchema extends z.ZodTypeAny,
+  TResult = undefined,
+  TError = string,
+  ActionArgs extends ActionFunctionArgs = ActionFunctionArgs,
+>(config: {
+  schema: TSchema;
+  handler: (
+    args: ActionArgs, 
+    data: z.infer<TSchema>
+  ) => Promise<MaybeError<TResult, TError>>;
+}): (args: ActionArgs) => Promise<MaybeError<TResult, FormActionError<TError>>>;
+
+type FormActionError<TError> =
+  | { type: "validation"; error: ReturnType<typeof z.treeifyError> }
+  | { type: "handler"; error: TError }
+  | { type: "unknown" };
+```
+
 ## Type Utilities
 
 ### `RoutePath<T>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firtoz/router-toolkit",
-  "version": "1.3.1",
+  "version": "2.0.1",
   "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",
@@ -59,5 +59,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "zod-form-data": "^3.0.0"
   }
 }

package/src/formAction.ts

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Type-safe form action utility for React Router 7
+ *
+ * This module provides a wrapper for React Router actions that handles form data validation
+ * using Zod schemas and provides structured error handling with MaybeError.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod/v4";
+ * import { formAction } from "@firtoz/router-toolkit";
+ * import { success } from "@firtoz/maybe-error";
+ *
+ * const schema = z.object({
+ *   email: z.string().email(),
+ *   password: z.string().min(8),
+ * });
+ *
+ * export const action = formAction({
+ *   schema,
+ *   handler: async (args, data) => {
+ *     // data is fully typed based on the schema
+ *     const user = await authenticateUser(data.email, data.password);
+ *     return success(user);
+ *   },
+ * });
+ * ```
+ */
+
+import { fail, type MaybeError } from "@firtoz/maybe-error";
+import type { ActionFunctionArgs } from "react-router";
+import { z } from "zod/v4";
+import { zfd } from "zod-form-data";
+
+/**
+ * Error types that can be returned by formAction
+ */
+export type FormActionError<TError> =
+	| {
+			type: "validation";
+			error: ReturnType<typeof z.treeifyError<z.ZodTypeAny>>;
+	  }
+	| {
+			type: "handler";
+			error: TError;
+	  }
+	| {
+			type: "unknown";
+	  };
+
+/**
+ * Configuration object for formAction
+ *
+ * @template TSchema - The Zod schema type for form validation
+ * @template TResult - The success result type from the handler
+ * @template TError - The error type that the handler can return
+ * @template ActionArgs - The action function arguments type (defaults to ActionFunctionArgs)
+ */
+export interface FormActionConfig<
+	TSchema extends z.ZodTypeAny,
+	TResult = undefined,
+	TError = string,
+	ActionArgs extends ActionFunctionArgs = ActionFunctionArgs,
+> {
+	/**
+	 * Zod schema to validate the form data against
+	 */
+	schema: TSchema;
+	/**
+	 * Handler function that processes the validated form data
+	 *
+	 * @param args - The original action function arguments
+	 * @param data - The validated form data (typed according to the schema)
+	 * @returns A promise that resolves to a MaybeError with the result or error
+	 */
+	handler: (
+		args: ActionArgs,
+		data: z.infer<TSchema>,
+	) => Promise<MaybeError<TResult, TError>>;
+}
+
+/**
+ * Creates a type-safe form action handler that validates form data and provides structured error handling.
+ *
+ * This function wraps a React Router action to:
+ * 1. Parse and validate form data using a Zod schema
+ * 2. Call the provided handler with validated data
+ * 3. Return structured errors for validation failures, handler errors, or unknown errors
+ * 4. Preserve React Router Response objects (redirects, etc.) by re-throwing them
+ *
+ * @template TSchema - The Zod schema type for form validation
+ * @template TResult - The success result type from the handler (defaults to undefined)
+ * @template TError - The error type that the handler can return (defaults to string)
+ * @template ActionArgs - The action function arguments type (defaults to ActionFunctionArgs)
+ *
+ * @param config - Configuration object containing schema and handler
+ * @returns An action function that can be used with React Router
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod/v4";
+ * import { formAction } from "@firtoz/router-toolkit";
+ * import { success, fail } from "@firtoz/maybe-error";
+ *
+ * const loginSchema = z.object({
+ *   email: z.string().email("Invalid email format"),
+ *   password: z.string().min(8, "Password must be at least 8 characters"),
+ * });
+ *
+ * export const action = formAction({
+ *   schema: loginSchema,
+ *   handler: async (args, data) => {
+ *     try {
+ *       const user = await authenticateUser(data.email, data.password);
+ *       return success(user);
+ *     } catch (error) {
+ *       return fail("Invalid credentials");
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In your component, handle the different error types:
+ * const actionData = useActionData<typeof action>();
+ *
+ * if (actionData && !actionData.success) {
+ *   switch (actionData.error.type) {
+ *     case "validation":
+ *       // Handle validation errors - actionData.error.error contains field-specific errors
+ *       break;
+ *     case "handler":
+ *       // Handle business logic errors - actionData.error.error contains your custom error
+ *       break;
+ *     case "unknown":
+ *       // Handle unexpected errors
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export const formAction = <
+	TSchema extends z.ZodTypeAny,
+	TResult = undefined,
+	TError = string,
+	ActionArgs extends ActionFunctionArgs = ActionFunctionArgs,
+>({
+	schema,
+	handler,
+}: FormActionConfig<TSchema, TResult, TError, ActionArgs>) => {
+	return async (
+		args: ActionArgs,
+	): Promise<MaybeError<TResult, FormActionError<TError>>> => {
+		try {
+			const rawFormData = await args.request.formData();
+			const formData = await zfd.formData(schema).safeParseAsync(rawFormData);
+
+			if (!formData.success) {
+				return fail({
+					type: "validation" as const,
+					error: z.treeifyError<TSchema>(
+						formData.error as z.core.$ZodError<TSchema>,
+					),
+				});
+			}
+
+			const handlerResult = await handler(args, formData.data);
+			if (!handlerResult.success) {
+				return fail({
+					type: "handler" as const,
+					error: handlerResult.error,
+				});
+			}
+
+			return handlerResult;
+		} catch (error) {
+			// Re-throw Response objects (redirects, etc.) to preserve React Router behavior
+			if (error instanceof Response) {
+				throw error;
+			}
+
+			console.error("Unexpected error in formAction:", error);
+			return fail({
+				type: "unknown" as const,
+			});
+		}
+	};
+};

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./formAction";
 export * from "./types/index";
 export * from "./useCachedFetch";
 export * from "./useDynamicFetcher";

package/src/useDynamicSubmitter.tsx

@@ -1,4 +1,5 @@
-import { useCallback, useMemo } from "react";
+// biome-ignore lint/style/useImportType: We need to import React here.
+import React, { useCallback, useMemo } from "react";
 import {
 	type FetcherFormProps,
 	href,