@firtoz/router-toolkit 5.3.1 → 5.5.0

package/README.md

@@ -13,6 +13,7 @@ Type-safe React Router 7 framework mode helpers with enhanced fetching, form sub
 - ✅ **Type-safe routing** - Full TypeScript support with React Router 7 framework mode
 - 🚀 **Enhanced fetching** - Dynamic fetchers with caching and query parameter support
 - 📝 **Form submission** - Type-safe form handling with Zod validation
+- 📤 **Concurrent submissions** - Multiple parallel submissions per action with per-operation tracking and optimistic UI (`useConcurrentDynamicSubmitter`)
 - 🔄 **State tracking** - Monitor fetcher state changes with ease
 - 🎯 **Zero configuration** - Works out of the box with React Router 7
 - 📦 **Tree-shakeable** - Import only what you need
@@ -278,6 +279,51 @@ export default function ContactForm() {
 }
 ```
 
+### `useConcurrentDynamicSubmitter`
+
+Run multiple submissions to the same action in parallel, each tracked independently. No single fetcher; each call returns `{ id, promise }` and adds an entry to `operations` with `submittedData` (for optimistic UI) and `data` when done.
+
+- **`submitJson(data)`** — POST JSON; `submittedData` is the payload you send.
+- **`submitFormData(formData, submittedData?)`** — POST multipart/form-data (e.g. file uploads). Optional `submittedData` is a serializable object for the operations list (e.g. `{ type: "upload", label: "photo.jpg" }`); FormData/File are not stored in state.
+
+```tsx
+import { useConcurrentDynamicSubmitter } from '@firtoz/router-toolkit';
+
+function UploadList() {
+  const { operations, submitFormData } = useConcurrentDynamicSubmitter<
+    typeof import("./api.upload")
+  >("/api/upload");
+
+  const handleUpload = (file: File) => {
+    const fd = new FormData();
+    fd.set("file", file);
+    submitFormData(fd, { type: "upload", label: file.name });
+  };
+
+  return (
+    <ul>
+      {Object.values(operations).map((op) => (
+        <li key={op.id}>
+          {op.status === "pending" && (
+            <Skeleton>{(op.submittedData as { label?: string }).label}</Skeleton>
+          )}
+          {op.status === "done" && (
+            <span>Saved: {op.data?.id}</span>
+          )}
+          {op.status === "error" && (
+            <span>Failed: {String(op.error)}</span>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+- **`operations`**: `Record<string, Operation<T>>` — each operation has `id`, `status` (`"pending"` | `"done"` | `"error"`), `submittedData` (payload or display object), and when done `data` (action response).
+- **`submitJson(data)`**: returns `{ id, promise }`.
+- **`submitFormData(formData, submittedData?)`**: returns `{ id, promise }`; `submittedData` defaults to `{}` and is used only for display in the operations list.
+
 ### `useFetcherStateChanged`
 
 Track changes in fetcher state and react to them. Perfect for triggering side effects, showing notifications, or handling state transitions in your application.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/router-toolkit",
-	"version": "5.3.1",
+	"version": "5.5.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",
@@ -72,8 +72,8 @@
 	"devDependencies": {
 		"@testing-library/react": "^16.3.1",
 		"@types/jsdom": "^27.0.0",
-		"@types/react": "^19.2.13",
-		"bun-types": "^1.3.8",
-		"jsdom": "^28.0.0"
+		"@types/react": "^19.2.14",
+		"bun-types": "^1.3.9",
+		"jsdom": "^28.1.0"
 	}
 }

package/src/index.ts

@@ -3,5 +3,6 @@ export * from "./types/index";
 export * from "./useCachedFetch";
 export * from "./useDynamicFetcher";
 export * from "./useDynamicSubmitter";
+export * from "./useConcurrentDynamicSubmitter";
 export * from "./useFetcherStateChanged";
 // Test comment to trigger release

package/src/useConcurrentDynamicSubmitter.tsx

@@ -0,0 +1,257 @@
+/**
+ * @fileoverview Concurrent type-safe form submissions for React Router 7
+ *
+ * Lets you run multiple submissions to the same (or logical) action in parallel,
+ * each tracked independently with pending → done state. No single fetcher;
+ * each submission is a promise and an entry in `operations`.
+ *
+ * @example
+ * ```tsx
+ * const { operations, submitJson } = useConcurrentDynamicSubmitter<typeof import("./api.upload")>("/api/upload");
+ *
+ * const a = submitJson({ fileId: "1", name: "a.pdf" });
+ * const b = submitJson({ fileId: "2", name: "b.pdf" });
+ *
+ * // FormData: pass serializable submittedData for display (no File/FormData in state)
+ * submitFormData(formData, { type: "upload", label: "photo.jpg" });
+ * submitFormData(convertFormData, { type: "convert", label: "anim.gif" });
+ * // Map operations: op.submittedData for labels, op.data when done
+ * {Object.values(operations).map((op) => (
+ *   <div key={op.id}>
+ *     {op.status === "pending" && <Skeleton>{op.submittedData.label}</Skeleton>}
+ *     {op.status === "done" && <Item data={op.data} />}
+ *   </div>
+ * ))}
+ * ```
+ */
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import { href } from "react-router";
+import type { z } from "zod";
+import type { HrefArgs } from "./types/HrefArgs";
+import type { RegisterPages } from "./types/RegisterPages";
+
+type RouteModule = {
+	route: keyof RegisterPages;
+	action: (...args: unknown[]) => unknown;
+	formSchema: z.ZodType;
+};
+
+/** Action result type inferred from the route module's action */
+export type ActionResult<TModule extends RouteModule> = Awaited<
+	ReturnType<TModule["action"]>
+>;
+
+/** Status of a single concurrent submission */
+export type OperationStatus = "pending" | "done" | "error";
+
+/** One tracked submission: pending → done (or error). Includes submitted payload for optimistic UI. */
+export type Operation<TResponse, TFormData = unknown> = {
+	id: string;
+	status: OperationStatus;
+	/** Data that was sent (for optimistic display while pending, or to show what was submitted) */
+	submittedData: TFormData;
+	/** Response from the action when status is "done" */
+	data?: TResponse;
+	error?: unknown;
+};
+
+/** Result of submitJson / submitFormData: id to look up in operations, promise to await */
+export type SubmitJsonResult<T> = {
+	id: string;
+	promise: Promise<T>;
+};
+
+type SubmitJsonOptions = {
+	method?: "POST" | "PUT" | "PATCH" | "DELETE";
+};
+
+/** Optional serializable payload for FormData submissions (for display in operations list; FormData/File are not stored in state). */
+export type FormDataSubmittedData = Record<string, unknown>;
+
+/**
+ * Submits JSON to the action URL via fetch and returns the parsed JSON.
+ */
+async function submitJsonToAction<T>(
+	actionUrl: string,
+	data: unknown,
+	options: SubmitJsonOptions & { fetchFn?: typeof fetch },
+): Promise<T> {
+	const { method = "POST", fetchFn = fetch } = options;
+	const res = await fetchFn(actionUrl, {
+		method,
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(data),
+	});
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`Action failed: ${res.status} ${text}`);
+	}
+	const json = (await res.json()) as T;
+	return json;
+}
+
+/**
+ * Submits FormData to the action URL. No Content-Type header — browser sets multipart/form-data with boundary.
+ */
+async function submitFormDataToAction<T>(
+	actionUrl: string,
+	formData: FormData,
+	options: {
+		method?: "POST" | "PUT" | "PATCH" | "DELETE";
+		fetchFn?: typeof fetch;
+	},
+): Promise<T> {
+	const { method = "POST", fetchFn = fetch } = options;
+	const res = await fetchFn(actionUrl, {
+		method,
+		body: formData,
+	});
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`Action failed: ${res.status} ${text}`);
+	}
+	const json = (await res.json()) as T;
+	return json;
+}
+
+/**
+ * Hook for multiple concurrent submissions to a dynamic route action.
+ * Each submission gets an id and appears in `operations` as pending → done (or error).
+ * Strongly typed: form data from route's formSchema, result from action return type.
+ *
+ * @template TInfo - Route module type (e.g. `typeof import("./api.upload")`)
+ * @param path - Route path
+ * @param args - Route params if path has segments
+ * @returns operations map (id → Operation), submitJson, submitFormData (each returns { id, promise })
+ */
+export function useConcurrentDynamicSubmitter<TInfo extends RouteModule>(
+	path: TInfo["route"],
+	...args: TInfo["route"] extends "undefined"
+		? HrefArgs<"/">
+		: HrefArgs<TInfo["route"]>
+): {
+	operations: Record<
+		string,
+		Operation<
+			ActionResult<TInfo>,
+			z.infer<TInfo["formSchema"]> | FormDataSubmittedData
+		>
+	>;
+	submitJson: (
+		data: z.infer<TInfo["formSchema"]>,
+		options?: SubmitJsonOptions,
+	) => SubmitJsonResult<ActionResult<TInfo>>;
+	submitFormData: (
+		formData: FormData,
+		submittedData?: FormDataSubmittedData,
+	) => SubmitJsonResult<ActionResult<TInfo>>;
+} {
+	const actionUrl = useMemo(() => {
+		// biome-ignore lint/suspicious/noExplicitAny: Intentional
+		return href(path, ...(args as any));
+	}, [path, args]);
+
+	type JsonFormData = z.infer<TInfo["formSchema"]>;
+	type Op = Operation<
+		ActionResult<TInfo>,
+		JsonFormData | FormDataSubmittedData
+	>;
+
+	const nextIdRef = useRef(0);
+	const [operations, setOperations] = useState<Record<string, Op>>({});
+
+	const submitJson = useCallback(
+		(
+			data: JsonFormData,
+			options: SubmitJsonOptions = {},
+		): SubmitJsonResult<ActionResult<TInfo>> => {
+			const id = `op-${++nextIdRef.current}`;
+			setOperations((prev) => ({
+				...prev,
+				[id]: { id, status: "pending", submittedData: data },
+			}));
+
+			const promise = submitJsonToAction<ActionResult<TInfo>>(
+				actionUrl,
+				data,
+				options,
+			)
+				.then((responseData) => {
+					setOperations((prev) => ({
+						...prev,
+						[id]: {
+							id,
+							status: "done",
+							submittedData: data,
+							data: responseData,
+						},
+					}));
+					return responseData;
+				})
+				.catch((error) => {
+					setOperations((prev) => ({
+						...prev,
+						[id]: {
+							id,
+							status: "error",
+							submittedData: data,
+							error,
+						},
+					}));
+					throw error;
+				});
+
+			return { id, promise };
+		},
+		[actionUrl],
+	);
+
+	const submitFormData = useCallback(
+		(
+			formData: FormData,
+			submittedData: FormDataSubmittedData = {},
+		): SubmitJsonResult<ActionResult<TInfo>> => {
+			const id = `op-${++nextIdRef.current}`;
+			setOperations((prev) => ({
+				...prev,
+				[id]: { id, status: "pending", submittedData },
+			}));
+
+			const promise = submitFormDataToAction<ActionResult<TInfo>>(
+				actionUrl,
+				formData,
+				{ method: "POST" },
+			)
+				.then((responseData) => {
+					setOperations((prev) => ({
+						...prev,
+						[id]: {
+							id,
+							status: "done",
+							submittedData,
+							data: responseData,
+						},
+					}));
+					return responseData;
+				})
+				.catch((error) => {
+					setOperations((prev) => ({
+						...prev,
+						[id]: {
+							id,
+							status: "error",
+							submittedData,
+							error,
+						},
+					}));
+					throw error;
+				});
+
+			return { id, promise };
+		},
+		[actionUrl],
+	);
+
+	return { operations, submitJson, submitFormData };
+}