@firtoz/router-toolkit 8.0.0 → 9.0.0

package/src/useDynamicFetcher.ts

@@ -97,28 +97,33 @@
  *
  * ```tsx
  * import { useDynamicFetcher, useDynamicSubmitter } from "@firtoz/router-toolkit";
+ * import { useEffect, useState } from "react";
  *
  * function PostEditor({ postId }: { postId: string }) {
- *   // Fetch post data
  *   const fetcher = useDynamicFetcher<typeof import("./api.posts.$postId")>(
  *     "/api/posts/:postId",
  *     { postId }
  *   );
  *
- *   // Submit updates
  *   const submitter = useDynamicSubmitter<typeof import("./api.posts.$postId")>(
  *     "/api/posts/:postId",
  *     { postId }
  *   );
  *
+ *   const [saving, setSaving] = useState(false);
+ *
  *   useEffect(() => {
  *     fetcher.load();
  *   }, [fetcher.load]);
  *
  *   const handleSave = async (title: string, content: string) => {
- *     await submitter.submitJson({ title, content }, { method: "PUT" });
- *     // Reload after save
- *     fetcher.load();
+ *     setSaving(true);
+ *     try {
+ *       await submitter.submitJson({ title, content }, { method: "PUT" });
+ *       fetcher.load();
+ *     } finally {
+ *       setSaving(false);
+ *     }
  *   };
  *
  *   if (!fetcher.data) return <div>Loading...</div>;
@@ -127,17 +132,22 @@
  *     <form onSubmit={(e) => {
  *       e.preventDefault();
  *       const form = new FormData(e.currentTarget);
- *       handleSave(form.get("title") as string, form.get("content") as string);
+ *       void handleSave(form.get("title") as string, form.get("content") as string);
  *     }}>
  *       <input name="title" defaultValue={fetcher.data.post.title} />
  *       <textarea name="content" defaultValue={fetcher.data.post.content} />
- *       <button disabled={submitter.state !== "idle"}>
- *         {submitter.state === "submitting" ? "Saving..." : "Save"}
+ *       <button type="submit" disabled={saving}>
+ *         {saving ? "Saving..." : "Save"}
  *       </button>
  *     </form>
  *   );
  * }
  * ```
+ *
+ * **Submitter UX:** Local `saving` around `await submitter.submitJson` fits a promise-first save +
+ * reload flow. For declarative `fetcher.state` / `fetcher.data` in JSX (e.g. with `submitter.Form`),
+ * use {@link useDynamicSubmitterFetcher} instead. The package README documents trade-offs under
+ * **useDynamicSubmitter** (heading “Local useState vs useDynamicSubmitterFetcher”).
  */
 
 import { useCallback, useMemo } from "react";

package/src/useDynamicSubmitter.tsx

@@ -4,6 +4,30 @@
  * This module provides a hook that creates a type-safe fetcher for submitting forms
  * to dynamic routes with full TypeScript inference for the form schema and route params.
  *
+ * **Awaiting results:** `submit` and `submitJson` return a `Promise` that resolves with the
+ * action payload after the submission completes (fetcher leaves `submitting` / `loading` for
+ * `idle`). The hook does **not** expose `data` or `state`—use the promise result (and local
+ * React state) for outcomes and loading UX. For declarative UI tied to the same fetcher, use
+ * {@link useDynamicSubmitterFetcher} (or {@link dynamicSubmitterFetcherKey} with `useFetcher`).
+ * Use **one awaited submit at
+ * a time** per hook instance; React Router’s
+ * single fetcher replaces an in-flight request when you submit again. If you call `submit` or
+ * `submitJson` again before the previous promise settles, the previous promise is **rejected**
+ * with {@link SubmitterSupersededError}. That applies **per React Router fetcher key** (same
+ * resolved URL and {@link UseDynamicSubmitterOptions.keySuffix}): two hook instances that share
+ * the same key also supersede one another’s in-flight promise. Use distinct `keySuffix` values
+ * when you need independent overlapping submissions to the same route. For many overlapping
+ * operations, use `ConcurrentSubmitterProvider` / `useConcurrentSubmitter` instead.
+ *
+ * **Unmount:** If the component unmounts while a returned promise is still pending, that
+ * promise is **rejected** with {@link SubmitterUnmountedError}.
+ *
+ * **Local `useState` vs {@link useDynamicSubmitterFetcher}:** For programmatic
+ * `await submitter.submitJson`, a local pending flag and `try` / `finally` is often enough for
+ * disabled buttons and matches the promise-first API. Use {@link useDynamicSubmitterFetcher} when
+ * you want declarative `fetcher.state` / `fetcher.data` in JSX (especially with `submitter.Form`
+ * or inline errors). The package README documents trade-offs in more detail.
+ *
  * @example
  * ### Route Setup (`app/routes/admin.posts.$id.tsx`)
  *
@@ -51,17 +75,24 @@
  *     { id: postId }
  *   );
  *
- *   // submitter.data is the typed response from the action
- *   // submitter.state is "idle" | "loading" | "submitting"
+ *   const [pending, setPending] = useState(false);
  *
  *   // Option 1: Submit as JSON (recommended for programmatic submissions)
  *   // Defaults to POST if no options provided
  *   const handleSubmitJson = async () => {
- *     await submitter.submitJson({
- *       title: "My Post",
- *       content: "Post content here",
- *       published: true,
- *     });
+ *     setPending(true);
+ *     try {
+ *       const data = await submitter.submitJson({
+ *         title: "My Post",
+ *         content: "Post content here",
+ *         published: true,
+ *       });
+ *       if (data?.success) {
+ *         console.log("Saved");
+ *       }
+ *     } finally {
+ *       setPending(false);
+ *     }
  *   };
  *
  *   // Option 2: Submit with FormData or SubmitTarget
@@ -69,43 +100,12 @@
  *     await submitter.submit(formData, { method: "POST" });
  *   };
  *
- *   // Option 3: Use the Form component (defaults to POST)
+ *   // Option 3: Use the Form component (defaults to POST); pair with useDynamicSubmitterFetcher(submitter) if you need reactive state
  *   return (
  *     <submitter.Form>
  *       <input name="title" />
  *       <textarea name="content" />
- *       <button type="submit">Save</button>
- *     </submitter.Form>
- *   );
- * }
- * ```
- *
- * @example
- * ### Handling responses
- *
- * ```tsx
- * function LoginForm() {
- *   const submitter = useDynamicSubmitter<typeof import("./auth.login")>("/auth/login");
- *
- *   useEffect(() => {
- *     if (submitter.data?.success) {
- *       // Handle success
- *       console.log("Logged in as:", submitter.data.value.user.email);
- *     } else if (submitter.data && !submitter.data.success) {
- *       // Handle error
- *       if (submitter.data.error.type === "validation") {
- *         console.log("Validation errors:", submitter.data.error.error);
- *       }
- *     }
- *   }, [submitter.data]);
- *
- *   return (
- *     <submitter.Form>
- *       <input name="email" type="email" />
- *       <input name="password" type="password" />
- *       <button disabled={submitter.state !== "idle"}>
- *         {submitter.state === "submitting" ? "Logging in..." : "Login"}
- *       </button>
+ *       <button type="submit" disabled={pending}>Save</button>
  *     </submitter.Form>
  *   );
  * }
@@ -113,9 +113,10 @@
  */
 
 // biome-ignore lint/style/useImportType: We need to import React here.
-import React, { useCallback, useMemo } from "react";
+import React, { useCallback, useEffect, useMemo, useRef } from "react";
 import {
 	type FetcherFormProps,
+	type HTMLFormMethod,
 	href,
 	type SubmitOptions,
 	type SubmitTarget,
@@ -125,6 +126,127 @@ import type { z } from "zod";
 import type { HrefArgs } from "./types/HrefArgs";
 import type { RouteWithActionModule } from "./types/RouteWithActionModule";
 
+/**
+ * Thrown when a new `submit` or `submitJson` runs before a prior returned promise has settled.
+ * The new submission proceeds; catch this error if overlapping calls are expected.
+ */
+export class SubmitterSupersededError extends Error {
+	override readonly name = "SubmitterSupersededError";
+	constructor(
+		message = "This submission was superseded by a newer submit before it completed.",
+	) {
+		super(message);
+	}
+}
+
+/**
+ * Thrown when the component that owns the submitter unmounts before a `submit` /
+ * `submitJson` promise has settled.
+ */
+export class SubmitterUnmountedError extends Error {
+	override readonly name = "SubmitterUnmountedError";
+	constructor(
+		message = "The submitter was unmounted before this submission completed.",
+	) {
+		super(message);
+	}
+}
+
+/**
+ * Action payload type resolved by `submit` / `submitJson` (same shape React Router puts on `fetcher.data` after the action runs).
+ */
+export type DynamicSubmitterData<TInfo extends RouteWithActionModule> =
+	ReturnType<typeof useFetcher<TInfo["action"]>>["data"];
+
+/**
+ * Options for {@link useDynamicSubmitter}.
+ */
+export type UseDynamicSubmitterOptions = {
+	/**
+	 * Appended to the default fetcher key so multiple submitters can target the same resolved URL
+	 * without sharing React Router fetcher state. Omit to use the default key for that URL.
+	 */
+	keySuffix?: string;
+};
+
+/**
+ * React Router `useFetcher` key used by {@link useDynamicSubmitter} for a resolved href.
+ * Pass the same string as {@link UseDynamicSubmitterResult.fetcherKey} (or call with the same
+ * `resolvedHref` and `keySuffix` as the submitter) so a parallel `useFetcher({ key })` observes
+ * the same submission lifecycle.
+ *
+ * When `keySuffix` is set, it is encoded and joined with a fixed delimiter so arbitrary strings
+ * are safe in the key.
+ */
+export function dynamicSubmitterFetcherKey(
+	resolvedHref: string,
+	keySuffix?: string,
+): string {
+	const base = `submitter-${resolvedHref}`;
+	if (keySuffix === undefined || keySuffix === "") {
+		return base;
+	}
+	return `${base}::${encodeURIComponent(keySuffix)}`;
+}
+
+function isSubmitterOptions(x: unknown): x is UseDynamicSubmitterOptions {
+	if (x === null || typeof x !== "object") return false;
+	const keys = Object.keys(x as object);
+	if (keys.length === 0) return false;
+	return keys.every((k) => k === "keySuffix");
+}
+
+function parseUseDynamicSubmitterRestArgs(args: readonly unknown[]): {
+	hrefArgs: unknown[];
+	options: UseDynamicSubmitterOptions;
+} {
+	if (args.length === 0) {
+		return { hrefArgs: [], options: {} };
+	}
+	const last = args[args.length - 1];
+	if (args.length >= 2 && isSubmitterOptions(last)) {
+		return { hrefArgs: [...args.slice(0, -1)], options: last };
+	}
+	if (args.length === 1 && isSubmitterOptions(args[0])) {
+		return { hrefArgs: [], options: args[0] };
+	}
+	return { hrefArgs: [...args], options: {} };
+}
+
+type UseDynamicSubmitterRest<R extends RouteWithActionModule["route"]> =
+	HrefArgs<R> extends readonly []
+		? [options?: UseDynamicSubmitterOptions]
+		: [...hrefArgs: HrefArgs<R>, options?: UseDynamicSubmitterOptions];
+
+type PendingAwait = {
+	gen: number;
+	ownerId: number;
+	reject: (reason: unknown) => void;
+	/** Called when the shared fetcher reaches `idle` for this submission generation. */
+	finishIdle: (data: unknown, error: unknown | undefined) => void;
+};
+
+type SubmitterKeyBucket = {
+	submitGen: number;
+	pending: PendingAwait | null;
+};
+
+const submitterKeyBuckets = new Map<string, SubmitterKeyBucket>();
+
+function getSubmitterKeyBucket(key: string): SubmitterKeyBucket {
+	let b = submitterKeyBuckets.get(key);
+	if (!b) {
+		b = { submitGen: 0, pending: null };
+		submitterKeyBuckets.set(key, b);
+	}
+	return b;
+}
+
+let nextSubmitterOwnerId = 1;
+function allocateSubmitterOwnerId(): number {
+	return nextSubmitterOwnerId++;
+}
+
 /**
  * Function type for submitting form data with a SubmitTarget.
  *
@@ -145,7 +267,7 @@ type SubmitFunc<TModule extends RouteWithActionModule> = (
 	options: Omit<SubmitOptions, "action" | "method" | "encType"> & {
 		method: Exclude<SubmitOptions["method"], "GET">;
 	},
-) => Promise<void>;
+) => Promise<DynamicSubmitterData<TModule>>;
 
 /**
  * Options for submitJson function.
@@ -183,7 +305,7 @@ type SubmitJsonOptions = Omit<
 type SubmitJsonFunc<TModule extends RouteWithActionModule> = (
 	data: z.infer<TModule["formSchema"]>,
 	options?: SubmitJsonOptions,
-) => Promise<void>;
+) => Promise<DynamicSubmitterData<TModule>>;
 
 /**
  * Form component type with pre-bound action URL.
@@ -214,6 +336,19 @@ type SubmitForm = (
 	},
 ) => React.ReactElement;
 
+/**
+ * Stable object returned by {@link useDynamicSubmitter}: `submit`, `submitJson`, `Form`, and
+ * `fetcherKey`. The reference is memoized and does not change when the internal fetcher’s
+ * `state` / `data` update.
+ */
+export type UseDynamicSubmitterResult<TInfo extends RouteWithActionModule> = {
+	submit: SubmitFunc<TInfo>;
+	submitJson: SubmitJsonFunc<TInfo>;
+	Form: SubmitForm;
+	/** Pass to {@link useDynamicSubmitterFetcher} or `useFetcher({ key })` for reactive `state` / `data`. */
+	fetcherKey: string;
+};
+
 /**
  * Creates a type-safe fetcher for submitting forms to dynamic routes.
  *
@@ -225,15 +360,13 @@ type SubmitForm = (
  * @template TInfo - The route module type (use `typeof import("./route-file")`)
  *
  * @param path - The route path (must match the route's `route` export)
- * @param args - Route parameters (if the route has dynamic segments like `:id`)
+ * @param rest - Route parameters (if any), then optional {@link UseDynamicSubmitterOptions}. For
+ * static routes, you may pass only options as the second argument (e.g. `{ keySuffix: "a" }`).
+ * Options are recognized only when the object contains exclusively the `keySuffix` key (do not use
+ * a route param object whose only field is named `keySuffix` unless it is meant as options).
  *
- * @returns An extended fetcher object with:
- * - `submit` - Submit with FormData/SubmitTarget (includes schema type)
- * - `submitJson` - Submit a plain object as JSON (schema type only)
- * - `Form` - Pre-bound form component
- * - `data` - Response data from the action (typed)
- * - `state` - Fetcher state ("idle" | "loading" | "submitting")
- * - All other useFetcher properties
+ * @returns Stable `{ submit, submitJson, Form, fetcherKey }`. Await the promises for action results;
+ * use {@link useDynamicSubmitterFetcher} or local state for reactive loading/data.
  *
  * @example
  * ### Basic usage with route parameters
@@ -254,86 +387,164 @@ type SubmitForm = (
  *   { userId: "123" }
  * );
  *
- * // Submit using submitJson (type-safe, no FormData needed, defaults to POST)
- * await submitter.submitJson({
+ * const data = await submitter.submitJson({
  *   displayName: "John Doe",
  *   email: "john@example.com",
  *   notifications: true,
  * });
  *
- * // Check the response
- * if (submitter.data?.success) {
+ * if (data?.success) {
  *   console.log("Settings updated!");
  * }
  * ```
  */
-export const useDynamicSubmitter = <TInfo extends RouteWithActionModule>(
+export function useDynamicSubmitter<TInfo extends RouteWithActionModule>(
 	path: TInfo["route"],
-	...args: TInfo["route"] extends "undefined"
-		? HrefArgs<"/">
-		: HrefArgs<TInfo["route"]>
-): Omit<
-	ReturnType<typeof useFetcher<TInfo["action"]>>,
-	"load" | "submit" | "Form"
-> & {
-	/** Submit with FormData or SubmitTarget (schema type & SubmitTarget) */
-	submit: SubmitFunc<TInfo>;
-	/** Submit a plain object as JSON (schema type only, defaults to POST) */
-	submitJson: SubmitJsonFunc<TInfo>;
-	/** Pre-bound Form component with action URL already set (defaults to POST) */
-	Form: SubmitForm;
-} => {
+	...rest: UseDynamicSubmitterRest<TInfo["route"]>
+): UseDynamicSubmitterResult<TInfo> {
+	const { hrefArgs, options } = parseUseDynamicSubmitterRestArgs(rest);
+	const keySuffix = options.keySuffix;
+
 	const url = useMemo(() => {
 		// biome-ignore lint/suspicious/noExplicitAny: Intentional
-		return href(path, ...(args as any));
-	}, [path, args]);
+		return href(path, ...(hrefArgs as any));
+	}, [path, keySuffix, ...(hrefArgs as unknown[])]);
+
+	const fetcherKey = useMemo(
+		() => dynamicSubmitterFetcherKey(url, keySuffix),
+		[url, keySuffix],
+	);
 
 	const fetcher = useFetcher<TInfo["action"]>({
-		key: `submitter-${url}`,
+		key: fetcherKey,
 	});
 
+	const fetcherRef = useRef(fetcher);
+	fetcherRef.current = fetcher;
+
+	const ownerIdRef = useRef(allocateSubmitterOwnerId());
+	const prevStateRef = useRef(fetcher.state);
+
+	const beginSubmit = useCallback(
+		(runSubmit: () => void) => {
+			return new Promise<DynamicSubmitterData<TInfo>>((resolve, reject) => {
+				const bucket = getSubmitterKeyBucket(fetcherKey);
+				const prevPending = bucket.pending;
+				if (prevPending) {
+					prevPending.reject(new SubmitterSupersededError());
+				}
+				bucket.submitGen += 1;
+				const gen = bucket.submitGen;
+				bucket.pending = {
+					gen,
+					ownerId: ownerIdRef.current,
+					reject,
+					finishIdle: (data, error) => {
+						if (data !== undefined) {
+							resolve(data as DynamicSubmitterData<TInfo>);
+						} else {
+							reject(error ?? new Error("Submission failed"));
+						}
+					},
+				};
+				runSubmit();
+			});
+		},
+		[fetcherKey],
+	);
+
+	useEffect(() => {
+		return () => {
+			const bucket = getSubmitterKeyBucket(fetcherKey);
+			const pending = bucket.pending;
+			if (pending && pending.ownerId === ownerIdRef.current) {
+				bucket.pending = null;
+				pending.reject(new SubmitterUnmountedError());
+			}
+		};
+	}, [fetcherKey]);
+
+	const fetcherError = (fetcher as { error?: unknown }).error;
+
+	useEffect(() => {
+		const prev = prevStateRef.current;
+		prevStateRef.current = fetcher.state;
+		const wasWorking = prev === "submitting" || prev === "loading";
+		if (!wasWorking || fetcher.state !== "idle") {
+			return;
+		}
+		const bucket = getSubmitterKeyBucket(fetcherKey);
+		const p = bucket.pending;
+		if (!p || p.gen !== bucket.submitGen) {
+			return;
+		}
+		bucket.pending = null;
+		p.finishIdle(fetcher.data, fetcherError);
+	}, [fetcherKey, fetcher.state, fetcher.data, fetcherError]);
+
 	const submit: SubmitFunc<TInfo> = useCallback(
 		(target, options) => {
-			return fetcher.submit(target, {
-				...options,
-				method: (options?.method ??
-					"POST") as import("react-router").HTMLFormMethod,
-				action: url,
-				encType: "multipart/form-data",
-			} as Parameters<typeof fetcher.submit>[1]);
+			return beginSubmit(() => {
+				const f = fetcherRef.current;
+				void f.submit(target, {
+					...options,
+					method: (options?.method ?? "POST") as HTMLFormMethod,
+					action: url,
+					encType: "multipart/form-data",
+				} as Parameters<typeof f.submit>[1]);
+			});
 		},
-		[fetcher.submit, url],
+		[beginSubmit, url],
 	);
 
 	const submitJson: SubmitJsonFunc<TInfo> = useCallback(
 		(data, options = {}) => {
-			return fetcher.submit(
-				data as SubmitTarget,
-				{
-					...options,
-					method: (options.method ??
-						"POST") as import("react-router").HTMLFormMethod,
-					action: url,
-					encType: "application/json",
-				} as Parameters<typeof fetcher.submit>[1],
-			);
+			return beginSubmit(() => {
+				const f = fetcherRef.current;
+				void f.submit(
+					data as SubmitTarget,
+					{
+						...options,
+						method: (options.method ?? "POST") as HTMLFormMethod,
+						action: url,
+						encType: "application/json",
+					} as Parameters<typeof f.submit>[1],
+				);
+			});
 		},
-		[fetcher.submit, url],
+		[beginSubmit, url],
 	);
 
-	const OriginalForm = fetcher.Form;
+	const fetcherFormRef = useRef(fetcher.Form);
+	fetcherFormRef.current = fetcher.Form;
 
 	const Form: SubmitForm = useCallback(
 		({ method = "POST", ...props }) => {
+			const OriginalForm = fetcherFormRef.current;
 			return <OriginalForm action={url} method={method} {...props} />;
 		},
-		[url, OriginalForm],
+		[url],
 	);
 
-	return {
-		...fetcher,
-		submit,
-		submitJson,
-		Form,
-	};
-};
+	return useMemo(
+		() => ({
+			submit,
+			submitJson,
+			Form,
+			fetcherKey,
+		}),
+		[submit, submitJson, Form, fetcherKey],
+	);
+}
+
+/**
+ * React Router `useFetcher` bound to the same key as {@link useDynamicSubmitter}, so `state` /
+ * `data` reflect the same submissions as `submitter.submit` / `submitter.Form`.
+ *
+ * Call at component top level next to `useDynamicSubmitter`.
+ */
+export function useDynamicSubmitterFetcher<TInfo extends RouteWithActionModule>(
+	submitter: UseDynamicSubmitterResult<TInfo>,
+) {
+	return useFetcher<TInfo["action"]>({ key: submitter.fetcherKey });
+}

package/dist/chunk-2RLEUOSR.js

@@ -1,3 +0,0 @@
-export * from '@firtoz/maybe-error';
-//# sourceMappingURL=chunk-2RLEUOSR.js.map
-//# sourceMappingURL=chunk-2RLEUOSR.js.map

package/dist/chunk-5MOCOBGV.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/formAction.ts"],"names":[],"mappings":";;;;;AA6SO,IAAM,aAAa,CAKxB;AAAA,EACD,MAAA;AAAA,EACA;AACD,CAAA,KAA8D;AAC7D,EAAA,OAAO,OACN,IAAA,KACoE;AACpE,IAAA,IAAI;AACH,MAAA,MAAM,WAAA,GAAc,IAAA,CAAK,OAAA,CAAQ,OAAA,CAAQ,IAAI,cAAc,CAAA;AAC3D,MAAA,MAAM,MAAA,GAAS,WAAA,EAAa,QAAA,CAAS,kBAAkB,CAAA,IAAK,KAAA;AAE5D,MAAA,MAAM,WAAA,GAAc,SACjB,MAAM,MAAA,CAAO,eAAe,MAAM,IAAA,CAAK,QAAQ,IAAA,EAAM,IACrD,MAAM,GAAA,CACL,SAAS,MAAM,CAAA,CACf,eAAe,MAAM,IAAA,CAAK,OAAA,CAAQ,QAAA,EAAU,CAAA;AAEhD,MAAA,IAAI,CAAC,YAAY,OAAA,EAAS;AACzB,QAAA,OAAO,IAAA,CAAK;AAAA,UACX,IAAA,EAAM,YAAA;AAAA,UACN,OAAO,CAAA,CAAE,YAAA;AAAA,YACR,WAAA,CAAY;AAAA;AACb,SACA,CAAA;AAAA,MACF;AAEA,MAAA,MAAM,aAAA,GAAgB,MAAM,OAAA,CAAQ,IAAA,EAAM,YAAY,IAAI,CAAA;AAC1D,MAAA,IAAI,CAAC,cAAc,OAAA,EAAS;AAC3B,QAAA,OAAO,IAAA,CAAK;AAAA,UACX,IAAA,EAAM,SAAA;AAAA,UACN,OAAO,aAAA,CAAc;AAAA,SACrB,CAAA;AAAA,MACF;AAEA,MAAA,OAAO,aAAA;AAAA,IACR,SAAS,KAAA,EAAO;AAEf,MAAA,IAAI,iBAAiB,QAAA,EAAU;AAC9B,QAAA,MAAM,KAAA;AAAA,MACP;AAEA,MAAA,OAAA,CAAQ,KAAA,CAAM,mCAAmC,KAAK,CAAA;AACtD,MAAA,OAAO,IAAA,CAAK;AAAA,QACX,IAAA,EAAM;AAAA,OACN,CAAA;AAAA,IACF;AAAA,EACD,CAAA;AACD","file":"chunk-5MOCOBGV.js","sourcesContent":["/**\n * @fileoverview Type-safe form action utility for React Router 7\n *\n * This module provides a wrapper for React Router actions that handles form data and JSON\n * validation using Zod schemas and provides structured error handling with MaybeError.\n *\n * Supports both:\n * - **JSON requests** (`Content-Type: application/json`) - parsed with `request.json()` and validated directly\n * - **FormData requests** (`multipart/form-data` or `application/x-www-form-urlencoded`) - parsed with `request.formData()` and validated with zod-form-data\n *\n * ## Overview\n *\n * `formAction` is designed to work seamlessly with `useDynamicSubmitter` and `useDynamicFetcher`\n * to provide end-to-end type safety for your React Router forms.\n *\n * @example\n * ### Basic Route Setup (`app/routes/auth.login.tsx`)\n *\n * ```typescript\n * import { z } from \"zod\";\n * import { formAction, type RoutePath } from \"@firtoz/router-toolkit\";\n * import { success, fail } from \"@firtoz/maybe-error\";\n *\n * // 1. Export the route path for type inference\n * export const route: RoutePath<\"/auth/login\"> = \"/auth/login\";\n *\n * // 2. Define your form schema with Zod\n * export const formSchema = z.object({\n *   email: z.string().email(\"Please enter a valid email\"),\n *   password: z.string().min(8, \"Password must be at least 8 characters\"),\n *   rememberMe: z.boolean().optional().default(false),\n * });\n *\n * // 3. Create the action with formAction\n * export const action = formAction({\n *   schema: formSchema,\n *   handler: async ({ request }, data) => {\n *     // data is fully typed: { email: string, password: string, rememberMe: boolean }\n *     try {\n *       const user = await authenticateUser(data.email, data.password);\n *       if (data.rememberMe) {\n *         await createPersistentSession(user.id);\n *       }\n *       return success({ user });\n *     } catch (error) {\n *       return fail(\"Invalid email or password\");\n *     }\n *   },\n * });\n * ```\n *\n * @example\n * ### Using with useDynamicSubmitter\n *\n * The route above can be used with `useDynamicSubmitter` for type-safe form submissions:\n *\n * ```tsx\n * import { useDynamicSubmitter } from \"@firtoz/router-toolkit\";\n *\n * function LoginForm() {\n *   const submitter = useDynamicSubmitter<typeof import(\"./auth.login\")>(\"/auth/login\");\n *\n *   // Option 1: Submit as JSON (defaults to POST)\n *   const handleLoginJson = async () => {\n *     await submitter.submitJson({\n *       email: \"user@example.com\",\n *       password: \"secret123\",\n *       rememberMe: true,\n *     });\n *   };\n *\n *   // Option 2: Use the Form component (defaults to POST)\n *   return (\n *     <submitter.Form>\n *       <input name=\"email\" type=\"email\" placeholder=\"Email\" />\n *       <input name=\"password\" type=\"password\" placeholder=\"Password\" />\n *       <label>\n *         <input name=\"rememberMe\" type=\"checkbox\" /> Remember me\n *       </label>\n *       <button disabled={submitter.state !== \"idle\"}>\n *         {submitter.state === \"submitting\" ? \"Logging in...\" : \"Login\"}\n *       </button>\n *\n *       {submitter.data && !submitter.data.success && (\n *         <div className=\"error\">\n *           {submitter.data.error.type === \"validation\"\n *             ? \"Please check your inputs\"\n *             : submitter.data.error.type === \"handler\"\n *               ? submitter.data.error.error // \"Invalid email or password\"\n *               : \"An unexpected error occurred\"}\n *         </div>\n *       )}\n *     </submitter.Form>\n *   );\n * }\n * ```\n *\n * @example\n * ### Combined loader + action route (`app/routes/admin.posts.$id.tsx`)\n *\n * You can combine `formAction` with a loader for full CRUD operations:\n *\n * ```typescript\n * import { z } from \"zod\";\n * import { formAction, type RoutePath } from \"@firtoz/router-toolkit\";\n * import { success, fail } from \"@firtoz/maybe-error\";\n * import type { LoaderFunctionArgs } from \"react-router\";\n *\n * export const route: RoutePath<\"/admin/posts/:id\"> = \"/admin/posts/:id\";\n *\n * // Loader for fetching data (used with useDynamicFetcher)\n * export const loader = async ({ params }: LoaderFunctionArgs) => {\n *   const post = await db.posts.findUnique({ where: { id: params.id } });\n *   return { post };\n * };\n *\n * // Form schema for updates\n * export const formSchema = z.object({\n *   title: z.string().min(1, \"Title is required\"),\n *   content: z.string().min(10, \"Content must be at least 10 characters\"),\n *   published: z.boolean().optional().default(false),\n * });\n *\n * // Action for handling form submissions (used with useDynamicSubmitter)\n * export const action = formAction({\n *   schema: formSchema,\n *   handler: async ({ params }, data) => {\n *     const updated = await db.posts.update({\n *       where: { id: params.id },\n *       data,\n *     });\n *     return success({ post: updated });\n *   },\n * });\n * ```\n *\n * @example\n * ### Full CRUD component using both hooks\n *\n * ```tsx\n * import { useDynamicFetcher, useDynamicSubmitter } from \"@firtoz/router-toolkit\";\n * import { useEffect } from \"react\";\n *\n * function PostEditor({ postId }: { postId: string }) {\n *   // Fetch post data\n *   const fetcher = useDynamicFetcher<typeof import(\"./admin.posts.$id\")>(\n *     \"/admin/posts/:id\",\n *     { id: postId }\n *   );\n *\n *   // Submit updates\n *   const submitter = useDynamicSubmitter<typeof import(\"./admin.posts.$id\")>(\n *     \"/admin/posts/:id\",\n *     { id: postId }\n *   );\n *\n *   useEffect(() => {\n *     fetcher.load();\n *   }, [fetcher.load]);\n *\n *   if (fetcher.state === \"loading\" && !fetcher.data) {\n *     return <div>Loading...</div>;\n *   }\n *\n *   const post = fetcher.data?.post;\n *\n *   return (\n *     <submitter.Form method=\"PUT\">\n *       <input name=\"title\" defaultValue={post?.title} />\n *       <textarea name=\"content\" defaultValue={post?.content} />\n *       <label>\n *         <input name=\"published\" type=\"checkbox\" defaultChecked={post?.published} />\n *         Published\n *       </label>\n *       <button disabled={submitter.state !== \"idle\"}>\n *         {submitter.state === \"submitting\" ? \"Saving...\" : \"Save\"}\n *       </button>\n *     </submitter.Form>\n *   );\n * }\n * ```\n */\n\nimport { fail, type MaybeError } from \"@firtoz/maybe-error\";\nimport type { ActionFunctionArgs } from \"react-router\";\nimport { z } from \"zod\";\nimport { zfd } from \"zod-form-data\";\n\n/**\n * Error types that can be returned by formAction\n */\nexport type FormActionError<TError, TSchema extends z.ZodTypeAny> =\n\t| {\n\t\t\ttype: \"validation\";\n\t\t\terror: ReturnType<typeof z.treeifyError<z.infer<TSchema>>>;\n\t  }\n\t| {\n\t\t\ttype: \"handler\";\n\t\t\terror: TError;\n\t  }\n\t| {\n\t\t\ttype: \"unknown\";\n\t  };\n\n/**\n * Configuration object for formAction\n *\n * @template TSchema - The Zod schema type for form validation\n * @template TResult - The success result type from the handler\n * @template TError - The error type that the handler can return\n * @template ActionArgs - The action function arguments type (defaults to ActionFunctionArgs)\n */\nexport interface FormActionConfig<\n\tTSchema extends z.ZodTypeAny,\n\tTResult = undefined,\n\tTError = string,\n\tActionArgs extends ActionFunctionArgs = ActionFunctionArgs,\n> {\n\t/**\n\t * Zod schema to validate the form data against\n\t */\n\tschema: TSchema;\n\t/**\n\t * Handler function that processes the validated form data\n\t *\n\t * @param args - The original action function arguments\n\t * @param data - The validated form data (typed according to the schema)\n\t * @returns A promise that resolves to a MaybeError with the result or error\n\t */\n\thandler: (\n\t\targs: ActionArgs,\n\t\tdata: z.infer<TSchema>,\n\t) => Promise<MaybeError<TResult, TError>>;\n}\n\n/**\n * Creates a type-safe form action handler that validates form data or JSON and provides structured error handling.\n *\n * This function wraps a React Router action to:\n * 1. Detect content type (JSON vs FormData) from the request headers\n * 2. Parse and validate the request body using a Zod schema\n * 3. Call the provided handler with validated data\n * 4. Return structured errors for validation failures, handler errors, or unknown errors\n * 5. Preserve React Router Response objects (redirects, etc.) by re-throwing them\n *\n * **Content-Type handling:**\n * - `application/json`: Uses `request.json()` and validates directly with the schema\n * - `multipart/form-data` or `application/x-www-form-urlencoded`: Uses `request.formData()` and validates with zod-form-data\n *\n * @template TSchema - The Zod schema type for form validation\n * @template TResult - The success result type from the handler (defaults to undefined)\n * @template TError - The error type that the handler can return (defaults to string)\n * @template ActionArgs - The action function arguments type (defaults to ActionFunctionArgs)\n *\n * @param config - Configuration object containing schema and handler\n * @returns An action function that can be used with React Router\n *\n * @example\n * ```typescript\n * import { z } from \"zod\";\n * import { formAction } from \"@firtoz/router-toolkit\";\n * import { success, fail } from \"@firtoz/maybe-error\";\n *\n * const loginSchema = z.object({\n *   email: z.string().email(\"Invalid email format\"),\n *   password: z.string().min(8, \"Password must be at least 8 characters\"),\n * });\n *\n * export const action = formAction({\n *   schema: loginSchema,\n *   handler: async (args, data) => {\n *     try {\n *       const user = await authenticateUser(data.email, data.password);\n *       return success(user);\n *     } catch (error) {\n *       return fail(\"Invalid credentials\");\n *     }\n *   },\n * });\n * ```\n *\n * @example\n * ```typescript\n * // In your component, handle the different error types:\n * const actionData = useActionData<typeof action>();\n *\n * if (actionData && !actionData.success) {\n *   switch (actionData.error.type) {\n *     case \"validation\":\n *       // Handle validation errors - actionData.error.error contains field-specific errors\n *       break;\n *     case \"handler\":\n *       // Handle business logic errors - actionData.error.error contains your custom error\n *       break;\n *     case \"unknown\":\n *       // Handle unexpected errors\n *       break;\n *   }\n * }\n * ```\n */\nexport const formAction = <\n\tTSchema extends z.ZodTypeAny,\n\tTResult = undefined,\n\tTError = string,\n\tActionArgs extends ActionFunctionArgs = ActionFunctionArgs,\n>({\n\tschema,\n\thandler,\n}: FormActionConfig<TSchema, TResult, TError, ActionArgs>) => {\n\treturn async (\n\t\targs: ActionArgs,\n\t): Promise<MaybeError<TResult, FormActionError<TError, TSchema>>> => {\n\t\ttry {\n\t\t\tconst contentType = args.request.headers.get(\"Content-Type\");\n\t\t\tconst isJson = contentType?.includes(\"application/json\") ?? false;\n\n\t\t\tconst parseResult = isJson\n\t\t\t\t? await schema.safeParseAsync(await args.request.json())\n\t\t\t\t: await zfd\n\t\t\t\t\t\t.formData(schema)\n\t\t\t\t\t\t.safeParseAsync(await args.request.formData());\n\n\t\t\tif (!parseResult.success) {\n\t\t\t\treturn fail({\n\t\t\t\t\ttype: \"validation\" as const,\n\t\t\t\t\terror: z.treeifyError<z.infer<TSchema>>(\n\t\t\t\t\t\tparseResult.error as z.core.$ZodError<z.infer<TSchema>>,\n\t\t\t\t\t),\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst handlerResult = await handler(args, parseResult.data);\n\t\t\tif (!handlerResult.success) {\n\t\t\t\treturn fail({\n\t\t\t\t\ttype: \"handler\" as const,\n\t\t\t\t\terror: handlerResult.error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\treturn handlerResult;\n\t\t} catch (error) {\n\t\t\t// Re-throw Response objects (redirects, etc.) to preserve React Router behavior\n\t\t\tif (error instanceof Response) {\n\t\t\t\tthrow error;\n\t\t\t}\n\n\t\t\tconsole.error(\"Unexpected error in formAction:\", error);\n\t\t\treturn fail({\n\t\t\t\ttype: \"unknown\" as const,\n\t\t\t});\n\t\t}\n\t};\n};\n"]}

package/dist/chunk-HX57TC2S.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/useDynamicFetcher.ts"],"names":[],"mappings":";;;;AAsMO,IAAM,iBAAA,GAAoB,CAChC,IAAA,EAAA,GACG,IAAA,KAoBC;AACJ,EAAA,MAAM,GAAA,GAAM,QAAQ,MAAM;AAEzB,IAAA,OAAO,IAAA,CAAK,IAAA,EAAM,GAAI,IAAY,CAAA;AAAA,EACnC,CAAA,EAAG,CAAC,IAAA,EAAM,IAAI,CAAC,CAAA;AAEf,EAAA,MAAM,UAAU,UAAA,CAA4B;AAAA,IAC3C,GAAA,EAAK,WAAW,GAAG,CAAA;AAAA,GACnB,CAAA;AAED,EAAA,MAAM,IAAA,GAAO,WAAA;AAAA,IACZ,CAAC,WAAA,KAAyC;AACzC,MAAA,IAAI,CAAC,WAAA,IAAe,MAAA,CAAO,KAAK,WAAW,CAAA,CAAE,WAAW,CAAA,EAAG;AAC1D,QAAA,OAAO,OAAA,CAAQ,KAAK,GAAG,CAAA;AAAA,MACxB;AAGA,MAAA,MAAM,SAAS,IAAI,GAAA,CAAI,GAAA,EAAK,MAAA,CAAO,SAAS,MAAM,CAAA;AAClD,MAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,WAAW,CAAA,EAAG;AACvD,QAAA,MAAA,CAAO,YAAA,CAAa,GAAA,CAAI,GAAA,EAAK,KAAK,CAAA;AAAA,MACnC;AAEA,MAAA,OAAO,OAAA,CAAQ,IAAA,CAAK,MAAA,CAAO,QAAA,GAAW,OAAO,MAAM,CAAA;AAAA,IACpD,CAAA;AAAA,IACA,CAAC,OAAA,CAAQ,IAAA,EAAM,GAAG;AAAA,GACnB;AAEA,EAAA,OAAO;AAAA,IACN,GAAG,OAAA;AAAA,IACH;AAAA,GACD;AACD","file":"chunk-HX57TC2S.js","sourcesContent":["/**\n * @fileoverview Type-safe dynamic data fetching hook for React Router 7\n *\n * This module provides a hook that creates a type-safe fetcher for loading data\n * from dynamic routes with full TypeScript inference for the loader response and route params.\n *\n * @example\n * ### Route Setup (`app/routes/api.users.$userId.ts`)\n *\n * First, set up your route with the required exports:\n *\n * ```typescript\n * import type { RoutePath } from \"@firtoz/router-toolkit\";\n *\n * // Export the route path for type inference\n * export const route: RoutePath<\"/api/users/:userId\"> = \"/api/users/:userId\";\n *\n * // Define the loader with a typed return value\n * export const loader = async ({ params }: LoaderFunctionArgs) => {\n *   const user = await db.users.findUnique({ where: { id: params.userId } });\n *   return {\n *     user: {\n *       id: user.id,\n *       email: user.email,\n *       displayName: user.displayName,\n *       createdAt: user.createdAt.toISOString(),\n *     },\n *   };\n * };\n * ```\n *\n * @example\n * ### Using the hook in a component\n *\n * ```tsx\n * import { useDynamicFetcher } from \"@firtoz/router-toolkit\";\n * import { useEffect } from \"react\";\n *\n * function UserProfile({ userId }: { userId: string }) {\n *   // Type-safe fetcher with full inference\n *   const fetcher = useDynamicFetcher<typeof import(\"./api.users.$userId\")>(\n *     \"/api/users/:userId\",\n *     { userId }\n *   );\n *\n *   // Load data on mount\n *   useEffect(() => {\n *     fetcher.load();\n *   }, [fetcher.load]);\n *\n *   // fetcher.data is fully typed: { user: { id, email, displayName, createdAt } } | undefined\n *   if (fetcher.state === \"loading\") {\n *     return <div>Loading...</div>;\n *   }\n *\n *   if (!fetcher.data) {\n *     return <div>No user found</div>;\n *   }\n *\n *   return (\n *     <div>\n *       <h1>{fetcher.data.user.displayName}</h1>\n *       <p>{fetcher.data.user.email}</p>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ### Loading with query parameters\n *\n * ```tsx\n * function SearchResults() {\n *   const fetcher = useDynamicFetcher<typeof import(\"./api.search\")>(\"/api/search\");\n *\n *   const handleSearch = (query: string, page: number) => {\n *     // Pass query params to the load function\n *     fetcher.load({ q: query, page: String(page) });\n *   };\n *\n *   return (\n *     <div>\n *       <input onChange={(e) => handleSearch(e.target.value, 1)} />\n *       {fetcher.data?.results.map((result) => (\n *         <div key={result.id}>{result.title}</div>\n *       ))}\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ### Combining with useDynamicSubmitter for full CRUD\n *\n * You can use `useDynamicFetcher` alongside `useDynamicSubmitter` to create\n * complete CRUD interfaces with type safety:\n *\n * ```tsx\n * import { useDynamicFetcher, useDynamicSubmitter } from \"@firtoz/router-toolkit\";\n *\n * function PostEditor({ postId }: { postId: string }) {\n *   // Fetch post data\n *   const fetcher = useDynamicFetcher<typeof import(\"./api.posts.$postId\")>(\n *     \"/api/posts/:postId\",\n *     { postId }\n *   );\n *\n *   // Submit updates\n *   const submitter = useDynamicSubmitter<typeof import(\"./api.posts.$postId\")>(\n *     \"/api/posts/:postId\",\n *     { postId }\n *   );\n *\n *   useEffect(() => {\n *     fetcher.load();\n *   }, [fetcher.load]);\n *\n *   const handleSave = async (title: string, content: string) => {\n *     await submitter.submitJson({ title, content }, { method: \"PUT\" });\n *     // Reload after save\n *     fetcher.load();\n *   };\n *\n *   if (!fetcher.data) return <div>Loading...</div>;\n *\n *   return (\n *     <form onSubmit={(e) => {\n *       e.preventDefault();\n *       const form = new FormData(e.currentTarget);\n *       handleSave(form.get(\"title\") as string, form.get(\"content\") as string);\n *     }}>\n *       <input name=\"title\" defaultValue={fetcher.data.post.title} />\n *       <textarea name=\"content\" defaultValue={fetcher.data.post.content} />\n *       <button disabled={submitter.state !== \"idle\"}>\n *         {submitter.state === \"submitting\" ? \"Saving...\" : \"Save\"}\n *       </button>\n *     </form>\n *   );\n * }\n * ```\n */\n\nimport { useCallback, useMemo } from \"react\";\nimport { href, useFetcher } from \"react-router\";\nimport type { HrefArgs } from \"./types/HrefArgs\";\nimport type { RouteWithLoaderModule } from \"./types/RouteWithLoaderModule\";\n\n/**\n * Creates a type-safe fetcher for loading data from dynamic routes.\n *\n * This hook provides full TypeScript inference for:\n * - Route parameters (from the route path)\n * - Loader response type (from the route's loader export)\n *\n * @template TInfo - The route module type (use `typeof import(\"./route-file\")`)\n *\n * @param path - The route path (must match the route's `route` export)\n * @param args - Route parameters (if the route has dynamic segments like `:id`)\n *\n * @returns An extended fetcher object with:\n * - `load` - Function to load data, optionally with query parameters\n * - `data` - Response data from the loader (typed)\n * - `state` - Fetcher state (\"idle\" | \"loading\" | \"submitting\")\n * - All other useFetcher properties (except `submit`)\n *\n * @example\n * ### Basic usage\n *\n * ```typescript\n * // In your route file (app/routes/api.products.$productId.ts):\n * export const route: RoutePath<\"/api/products/:productId\"> = \"/api/products/:productId\";\n * export const loader = async ({ params }: LoaderFunctionArgs) => {\n *   return { product: await getProduct(params.productId) };\n * };\n *\n * // In your component:\n * const fetcher = useDynamicFetcher<typeof import(\"./api.products.$productId\")>(\n *   \"/api/products/:productId\",\n *   { productId: \"abc123\" }\n * );\n *\n * useEffect(() => {\n *   fetcher.load();\n * }, [fetcher.load]);\n *\n * // fetcher.data is typed as { product: Product } | undefined\n * ```\n *\n * @example\n * ### With query parameters\n *\n * ```typescript\n * const fetcher = useDynamicFetcher<typeof import(\"./api.search\")>(\"/api/search\");\n *\n * // Load with query params: /api/search?q=hello&limit=10\n * fetcher.load({ q: \"hello\", limit: \"10\" });\n * ```\n */\nexport const useDynamicFetcher = <TInfo extends RouteWithLoaderModule>(\n\tpath: TInfo[\"route\"],\n\t...args: TInfo[\"route\"] extends \"undefined\"\n\t\t? HrefArgs<\"/\">\n\t\t: HrefArgs<TInfo[\"route\"]>\n): Omit<ReturnType<typeof useFetcher<TInfo[\"loader\"]>>, \"load\" | \"submit\"> & {\n\t/**\n\t * Load data from the route's loader.\n\t *\n\t * @param queryParams - Optional query parameters to append to the URL\n\t * @returns A promise that resolves when the load is complete\n\t *\n\t * @example\n\t * ```typescript\n\t * // Load without query params\n\t * fetcher.load();\n\t *\n\t * // Load with query params\n\t * fetcher.load({ page: \"2\", sort: \"name\" });\n\t * ```\n\t */\n\tload: (queryParams?: Record<string, string>) => Promise<void>;\n} => {\n\tconst url = useMemo(() => {\n\t\t// biome-ignore lint/suspicious/noExplicitAny: Intentional\n\t\treturn href(path, ...(args as any));\n\t}, [path, args]);\n\n\tconst fetcher = useFetcher<TInfo[\"loader\"]>({\n\t\tkey: `fetcher-${url}`,\n\t});\n\n\tconst load = useCallback(\n\t\t(queryParams?: Record<string, string>) => {\n\t\t\tif (!queryParams || Object.keys(queryParams).length === 0) {\n\t\t\t\treturn fetcher.load(url);\n\t\t\t}\n\n\t\t\t// Build URL with query parameters\n\t\t\tconst urlObj = new URL(url, window.location.origin);\n\t\t\tfor (const [key, value] of Object.entries(queryParams)) {\n\t\t\t\turlObj.searchParams.set(key, value);\n\t\t\t}\n\n\t\t\treturn fetcher.load(urlObj.pathname + urlObj.search);\n\t\t},\n\t\t[fetcher.load, url],\n\t);\n\n\treturn {\n\t\t...fetcher,\n\t\tload,\n\t};\n};\n"]}