@faasjs/react 8.0.0-beta.20 → 8.0.0-beta.22

package/dist/index.mjs

@@ -4,13 +4,15 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * Generate a random identifier with an optional prefix.
 *
-* @param prefix - Prefix prepended to the generated identifier.
-* @param length - Length of the generated identifier excluding `prefix`. Must be between `8` and `18`.
-* @returns Generated identifier string.
+* @param {string} [prefix] - Prefix prepended to the generated identifier.
+* @param {number} [length] - Length of the generated identifier excluding `prefix`. Must be between `8` and `18`.
+* @returns {string} Generated identifier string.
 * @throws {Error} When `length` is outside the supported `8` to `18` range.
 *
 * @example
 * ```ts
+* import { generateId } from '@faasjs/react'
+*
 * const id = generateId('prefix-')
 *
 * id.startsWith('prefix-') // true
@@ -133,9 +135,9 @@ function generateId(prefix = "", length = 18) {
 * })
 * ```
 *
-* @see ResponseProps for response property type
-* @see ResponseError for error response handling
-* @see FaasBrowserClient.action for method returning Response
+* @see {@link ResponseProps} for response property type.
+* @see {@link ResponseError} for error response handling.
+* @see {@link FaasBrowserClient.action} for method returning Response.
 */
 var Response = class {
 	/**
@@ -157,12 +159,12 @@ var Response = class {
 	/**
 	* Create a wrapped response object.
 	*
-	* @param props - Response properties including status, headers, body, and data.
-	* @param props.status - HTTP status code. Defaults to `200` when `data` or `body` exists, otherwise `204`.
-	* @param props.headers - Response headers keyed by header name.
-	* @param props.body - Raw response body to expose without additional parsing.
-	* @param props.data - Parsed response payload to expose on `response.data`.
-	* @returns Wrapped response instance.
+	* @param {ResponseProps<T>} [props] - Response properties including status, headers, body, and data.
+	* @param {number} [props.status] - HTTP status code. Defaults to `200` when `data` or `body` exists, otherwise `204`.
+	* @param {ResponseHeaders} [props.headers] - Response headers keyed by header name.
+	* @param {any} [props.body] - Raw response body to expose without additional parsing.
+	* @param {T} [props.data] - Parsed response payload to expose on `response.data`.
+	* @returns {Response<T>} Wrapped response instance.
 	*/
 	constructor(props = {}) {
 		this.status = props.status || (props.data || props.body ? 200 : 204);
@@ -264,9 +266,9 @@ var Response = class {
 * - Use instanceof ResponseError to distinguish FaasJS errors from other JavaScript errors
 * - The body property can contain structured error information from the server response
 *
-* @see FaasBrowserClient.action for how ResponseError is thrown in requests
-* @see ResponseProps for the structure of response data
-* @see setMock for mocking errors in tests
+* @see {@link FaasBrowserClient.action} for how ResponseError is thrown in requests.
+* @see {@link ResponseProps} for the structure of response data.
+* @see {@link setMock} for mocking errors in tests.
 */
 var ResponseError = class extends Error {
 	/**
@@ -308,7 +310,7 @@ let mock = null;
 /**
 * Set the global mock handler used by all {@link FaasBrowserClient} instances.
 *
-* @param handler - Mock handler, can be:
+* @param {MockHandler | ResponseProps | Response | null | undefined} handler - Mock handler, can be:
 *   - MockHandler function: receives (action, params, options) and returns response data
 *   - ResponseProps object: static response data
 *   - Response instance: pre-configured Response object
@@ -466,8 +468,8 @@ function setMock(handler) {
 *
 * @throws {Error} When baseUrl does not end with '/'
 *
-* @see setMock for testing support
-* @see ResponseError for error handling
+* @see {@link setMock} for testing support.
+* @see {@link ResponseError} for error handling.
 */
 var FaasBrowserClient = class {
 	/**
@@ -485,8 +487,8 @@ var FaasBrowserClient = class {
 	/**
 	* Creates a new FaasBrowserClient instance.
 	*
-	* @param baseUrl - Base URL for all API requests. Must end with `/`. Defaults to `/` for relative requests.
-	* @param options - Default request options such as headers, hooks, request override, or stream mode.
+	* @param {BaseUrl} [baseUrl] - Base URL for all API requests. Must end with `/`. Defaults to `/` for relative requests.
+	* @param {Options} [options] - Default request options such as headers, hooks, request override, or stream mode.
 	* See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
 	* `request`, `baseUrl`, and `stream`.
 	*
@@ -552,16 +554,16 @@ var FaasBrowserClient = class {
 	* Makes a request to a FaasJS function.
 	*
 	* @template PathOrData - The function path or data type for type safety
-	* @param action - The function path to call. Converted to lowercase when constructing the URL.
+	* @param {FaasAction<PathOrData>} action - The function path to call. Converted to lowercase when constructing the URL.
 	*   Must be a non-empty string.
-	* @param params - The parameters to send to the function. Will be serialized as JSON.
+	* @param {FaasParams<PathOrData>} [params] - The parameters to send to the function. Will be serialized as JSON.
 	*   Optional if the function accepts no parameters.
-	* @param options - Optional request options that override client defaults.
+	* @param {Options} [options] - Optional request options that override client defaults.
 	*   Supports headers, beforeRequest hook, custom request function, baseUrl override, and streaming mode.
 	*   See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
 	*   `request`, `baseUrl`, and `stream`.
 	*
-	* @returns A promise resolving to the wrapped FaasJS response. When `options.stream`
+	* @returns {Promise<Response<FaasData<PathOrData>>>} A promise resolving to the wrapped FaasJS response. When `options.stream`
 	*   is `true`, the runtime returns the native fetch response so callers can read the stream.
 	*
 	* @throws {Error} When action is not provided or is empty
@@ -745,12 +747,12 @@ var FaasBrowserClient = class {
 *
 * @template PathOrData - Action path or response data type used for inference.
 *
-* @param action - Action path to invoke.
-* @param params - Parameters sent to the action.
-* @param options - Optional per-request overrides such as headers or base URL.
-* See the request `Options` type for supported fields such as `headers`, `beforeRequest`,
+* @param {FaasAction<PathOrData>} action - Action path to invoke.
+* @param {FaasParams<PathOrData>} params - Parameters sent to the action.
+* @param {Options} [options] - Optional per-request overrides such as headers or base URL.
+* See the browser-client `Options` type for supported fields such as `headers`, `beforeRequest`,
 * `request`, `baseUrl`, and `stream`.
-* @returns Response returned by the active browser client.
+* @returns {Promise<Response<FaasData<PathOrData>>>} Response returned by the active browser client.
 * @throws {ResponseError} When the request fails and the active client does not recover inside `onError`.
 *
 * @example
@@ -781,9 +783,9 @@ const AsyncFunction = (async () => {}).constructor;
 * It handles various data types including primitives, arrays, dates, regular expressions, functions,
 * maps, sets, and promises.
 *
-* @param a - The first value to compare.
-* @param b - The second value to compare.
-* @returns `true` if the values are deeply equal, `false` otherwise.
+* @param {any} a - The first value to compare.
+* @param {any} b - The second value to compare.
+* @returns {boolean} `true` if the values are deeply equal, `false` otherwise.
 *
 * @example
 * ```ts
@@ -824,8 +826,8 @@ function equal(a, b) {
 /**
 * Custom hook that memoizes a value using deep equality comparison.
 *
-* @param value - The value to be memoized.
-* @returns The memoized value.
+* @param {any} value - The value to be memoized.
+* @returns {any} The memoized value.
 *
 * @example
 * ```tsx
@@ -855,9 +857,9 @@ function useEqualSignal(value) {
 /**
 * Custom hook that works like `useEffect` but uses deep comparison on dependencies.
 *
-* @param callback - The effect callback function to run.
-* @param dependencies - The list of dependencies for the effect.
-* @returns The result of the `useEffect` hook with memoized dependencies.
+* @param {React.EffectCallback} callback - The effect callback function to run.
+* @param {any[]} dependencies - The list of dependencies for the effect.
+* @returns {void} The result of the `useEffect` hook with memoized dependencies.
 *
 * @example
 * ```tsx
@@ -880,9 +882,9 @@ function useEqualEffect(callback, dependencies) {
 *
 * @template T - Memoized value type returned by the callback.
 *
-* @param callback - The callback function to run.
-* @param dependencies - The list of dependencies.
-* @returns The result of the `useMemo` hook with memoized dependencies.
+* @param {() => T} callback - The callback function to run.
+* @param {any[]} dependencies - The list of dependencies.
+* @returns {T} The result of the `useMemo` hook with memoized dependencies.
 *
 * @example
 * ```tsx
@@ -908,9 +910,9 @@ function useEqualMemo(callback, dependencies) {
 *
 * @template T - Callback signature to memoize.
 *
-* @param callback - The callback function to run.
-* @param dependencies - The list of dependencies.
-* @returns The result of the `useCallback` hook with memoized dependencies.
+* @param {T} callback - The callback function to run.
+* @param {any[]} dependencies - The list of dependencies.
+* @returns {T} The result of the `useCallback` hook with memoized dependencies.
 *
 * @example
 * ```tsx
@@ -934,16 +936,16 @@ function useEqualCallback(callback, dependencies) {
 * The wrapper defers rendering `children` or `render` until the first request
 * completes, then keeps passing the latest request state to the rendered output.
 *
-* @param props - Wrapper props controlling the request and rendered fallback.
-* @param props.render - Render prop that receives the resolved Faas request state.
-* @param props.children - Child element cloned with injected Faas request state.
-* @param props.fallback - Element rendered before the first successful load.
-* @param props.action - Action path to request.
-* @param props.params - Params sent to the action.
-* @param props.onDataChange - Callback invoked when the resolved data value changes.
-* @param props.data - Controlled data value used instead of internal state.
-* @param props.setData - Controlled setter used instead of internal state.
-* @param props.baseUrl - Base URL override used for this wrapper instance.
+* @param {FaasDataWrapperProps<PathOrData>} props - Wrapper props controlling the request and rendered fallback.
+* @param {(args: FaasDataInjection<PathOrData>) => JSX.Element | JSX.Element[]} [props.render] - Render prop that receives the resolved Faas request state.
+* @param {React.ReactElement<Partial<FaasDataInjection<PathOrData>>>} [props.children] - Child element cloned with injected Faas request state.
+* @param {JSX.Element | false} [props.fallback] - Element rendered before the first successful load.
+* @param {FaasAction<PathOrData>} props.action - Action path to request.
+* @param {FaasParams<PathOrData>} [props.params] - Params sent to the action.
+* @param {(args: FaasDataInjection<PathOrData>) => void} [props.onDataChange] - Callback invoked when the resolved data value changes.
+* @param {FaasData<PathOrData>} [props.data] - Controlled data value used instead of internal state.
+* @param {React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>} [props.setData] - Controlled setter used instead of internal state.
+* @param {BaseUrl} [props.baseUrl] - Base URL override used for this wrapper instance.
 *
 * @example
 * ```tsx
@@ -1052,9 +1054,9 @@ Object.assign(FaasDataWrapper, { displayName: "FaasDataWrapper" });
 *
 * @template PathOrData - Action path or response data type used for inference.
 * @template TComponentProps - Component props including injected Faas data fields.
-* @param Component - Component that consumes injected Faas data props.
-* @param faasProps - Request configuration forwarded to `FaasDataWrapper`.
-* @returns Component that accepts the original props minus the injected Faas data fields.
+* @param {React.FC<TComponentProps>} Component - Component that consumes injected Faas data props.
+* @param {FaasDataWrapperProps<PathOrData>} faasProps - Request configuration forwarded to `FaasDataWrapper`.
+* @returns {React.FC<Omit<TComponentProps, keyof FaasDataInjection<PathOrData>> & Record<string, any>>} Component that accepts the original props minus the injected Faas data fields.
 *
 * @example
 * ```tsx
@@ -1083,71 +1085,59 @@ function withFaasData(Component, faasProps) {
 	});
 }
 //#endregion
-//#region src/useFaas.tsx
+//#region src/useFaasRequest.ts
 /**
-* Request FaasJS data and keep request state in React state.
-*
-* `useFaas` is the default hook for standard FaasJS request-response flows in React.
-* It sends an initial request unless `skip` is enabled, and returns request state
-* plus helpers for reloading, updating data, and handling errors.
-*
-* @template PathOrData - Action path or response data type used for inference.
-*
-* @param action - Action path to invoke.
-* @param defaultParams - Params used for the initial request and future reloads.
-* @param options - Optional hook configuration such as controlled data, debounce, and skip logic.
-* @param options.params - Request params override used without mutating the hook's stored params state.
-* @param options.data - Controlled data value used instead of the hook's internal state.
-* @param options.setData - Controlled setter used instead of the hook's internal `setData`.
-* @param options.skip - Boolean or predicate that suppresses the automatic request until `reload()` runs.
-* @param options.debounce - Milliseconds to wait before sending the latest request.
-* @param options.baseUrl - Base URL override used for this hook instance.
-* @returns Request state and helper methods described by {@link FaasDataInjection}.
-*
+* Run the shared request lifecycle used by the higher-level FaasJS React hooks.
+*
+* It manages loading state, abort signals, debounce timing, retry-on-fetch-failure,
+* and queued reload promises while delegating the actual transport to `send`.
+*
+* @template Params - Request params type tracked by the lifecycle.
+* @template Result - Successful response payload type.
+* @template RequestPromise - Promise type exposed through `promiseRef`.
+* @param {UseFaasRequestArgs<Params, Result, RequestPromise>} args - Request lifecycle configuration.
+* @param {string} args.action - Action path or request key used to trigger the lifecycle.
+* @param {Params} args.defaultParams - Initial params value stored by the lifecycle.
+* @param {Pick<SharedUseFaasOptions<Params, Result>, 'params' | 'skip' | 'debounce' | 'baseUrl'>} args.options - Shared request options used by the lifecycle.
+* @param {() => void} [args.beforeSend] - Optional callback invoked immediately before a request starts.
+* @param {(result: Result) => void} [args.onSuccess] - Optional callback invoked after a successful response.
+* @param {UseFaasRequestArgs<Params, Result, RequestPromise>['send']} args.send - Transport function responsible for creating and resolving the request.
+* @returns Shared request state, reload helpers, and refs used by `useFaas` and `useFaasStream`.
 * @example
-* ```tsx
-* import { useFaas } from '@faasjs/react'
-*
-* function Profile({ id }: { id: number }) {
-*   const { data, error, loading, reload } = useFaas('/pages/users/get', { id })
-*
-*   if (loading) return <div>Loading...</div>
+* ```ts
+* function useUserRequest(id: number) {
+*   return useFaasRequest({
+*     action: '/pages/users/get',
+*     defaultParams: { id },
+*     options: {},
+*     send: async ({ action, params, signal, client, setPromise }) => {
+*       const promise = client.faas(action, params, { signal })
 *
-*   if (error) {
-*     return (
-*       <div>
-*         <div>Load failed: {error.message}</div>
-*         <button type="button" onClick={() => reload()}>
-*           Retry
-*         </button>
-*       </div>
-*     )
-*   }
+*       setPromise(promise)
 *
-*   return (
-*     <div>
-*       <span>{data.name}</span>
-*       <button type="button" onClick={() => reload()}>
-*         Refresh
-*       </button>
-*     </div>
-*   )
+*       return (await promise).data as { name: string }
+*     },
+*   })
 * }
 * ```
 */
-function useFaas(action, defaultParams, options = {}) {
+function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess, send }) {
 	const [loading, setLoading] = useState(true);
-	const [data, setData] = useState();
 	const [error, setError] = useState();
 	const [params, setParams] = useState(defaultParams);
 	const [reloadTimes, setReloadTimes] = useState(0);
-	const [fails, setFails] = useState(0);
 	const [skip, setSkip] = useState(typeof options.skip === "function" ? options.skip(defaultParams) : options.skip);
 	const promiseRef = useRef(null);
 	const controllerRef = useRef(null);
-	const localSetData = setData;
+	const failedOnceRef = useRef(false);
 	const pendingReloadsRef = useRef(/* @__PURE__ */ new Map());
 	const reloadCounterRef = useRef(0);
+	const beforeSendRef = useRef(beforeSend);
+	const onSuccessRef = useRef(onSuccess);
+	const sendRef = useRef(send);
+	beforeSendRef.current = beforeSend;
+	onSuccessRef.current = onSuccess;
+	sendRef.current = send;
 	useEqualEffect(() => {
 		setSkip(typeof options.skip === "function" ? options.skip(params) : options.skip);
 	}, [typeof options.skip === "function" ? params : options.skip]);
@@ -1160,50 +1150,63 @@ function useFaas(action, defaultParams, options = {}) {
 			return;
 		}
 		setLoading(true);
+		beforeSendRef.current?.();
+		failedOnceRef.current = false;
 		const controller = new AbortController();
 		controllerRef.current = controller;
 		const client = getClient(options.baseUrl);
-		const requestParams = options.params ?? params;
-		function send() {
-			const request = client.faas(action, requestParams, { signal: controller.signal });
-			promiseRef.current = request;
-			request.then((r) => {
-				const nextData = r.data;
-				setFails(0);
+		const requestParams = options.params || params;
+		const rejectPending = (reason) => {
+			for (const { reject } of pendingReloadsRef.current.values()) reject(reason);
+			pendingReloadsRef.current.clear();
+		};
+		const resolvePending = (value) => {
+			for (const { resolve } of pendingReloadsRef.current.values()) resolve(value);
+			pendingReloadsRef.current.clear();
+		};
+		const run = () => {
+			sendRef.current({
+				action,
+				params: requestParams,
+				signal: controller.signal,
+				client,
+				setPromise: (promise) => {
+					promiseRef.current = promise;
+				}
+			}).then((result) => {
+				failedOnceRef.current = false;
 				setError(null);
-				if (options.setData) options.setData(nextData);
-				else localSetData(nextData);
+				onSuccessRef.current?.(result);
 				setLoading(false);
-				for (const { resolve } of pendingReloadsRef.current.values()) resolve(nextData);
-				pendingReloadsRef.current.clear();
+				resolvePending(result);
 			}).catch(async (e) => {
-				if (typeof e?.message === "string" && e.message.toLowerCase().indexOf("aborted") >= 0) return;
-				if (!fails && typeof e?.message === "string" && e.message.indexOf("Failed to fetch") >= 0) {
+				if (typeof e?.message === "string" && e.message.toLowerCase().includes("aborted")) return;
+				if (!failedOnceRef.current && typeof e?.message === "string" && e.message.includes("Failed to fetch")) {
+					failedOnceRef.current = true;
 					console.warn(`FaasReactClient: ${e.message} retry...`);
-					setFails(1);
-					return send();
+					run();
+					return;
 				}
-				let error = e;
+				let nextError = e;
 				if (client.onError) try {
-					await client.onError(action, requestParams)(e);
+					await client.onError(action, requestParams || Object.create(null))(e);
 				} catch (newError) {
-					error = newError;
+					nextError = newError;
 				}
-				setError(error);
+				setError(nextError);
 				setLoading(false);
-				for (const { reject } of pendingReloadsRef.current.values()) reject(error);
-				pendingReloadsRef.current.clear();
+				rejectPending(nextError);
 			});
-		}
+		};
 		if (options.debounce) {
-			const timeout = setTimeout(send, options.debounce);
+			const timeout = setTimeout(run, options.debounce);
 			return () => {
 				clearTimeout(timeout);
 				controllerRef.current?.abort();
 				setLoading(false);
 			};
 		}
-		send();
+		run();
 		return () => {
 			controllerRef.current?.abort();
 			setLoading(false);
@@ -1214,35 +1217,111 @@ function useFaas(action, defaultParams, options = {}) {
 		reloadTimes,
 		skip
 	]);
-	const reload = useEqualCallback((params) => {
-		if (skip) setSkip(false);
-		if (params) setParams(params);
-		const reloadCounter = ++reloadCounterRef.current;
-		return new Promise((resolve, reject) => {
-			pendingReloadsRef.current.set(reloadCounter, {
-				resolve,
-				reject
+	return {
+		loading,
+		error,
+		params,
+		reloadTimes,
+		reload: useEqualCallback((nextParams) => {
+			if (skip) setSkip(false);
+			if (nextParams) setParams(nextParams);
+			const reloadCounter = ++reloadCounterRef.current;
+			return new Promise((resolve, reject) => {
+				pendingReloadsRef.current.set(reloadCounter, {
+					resolve,
+					reject
+				});
+				setReloadTimes((prev) => prev + 1);
 			});
-			setReloadTimes((prev) => prev + 1);
-		});
-	}, [params, skip]);
+		}, [skip]),
+		promiseRef,
+		setError,
+		setLoading
+	};
+}
+//#endregion
+//#region src/useFaas.tsx
+/**
+* Request FaasJS data and keep request state in React state.
+*
+* `useFaas` is the default hook for standard FaasJS request-response flows in React.
+* It sends an initial request unless `skip` is enabled, and returns request state
+* plus helpers for reloading, updating data, and handling errors.
+*
+* @template PathOrData - Action path or response data type used for inference.
+*
+* @param {FaasAction<PathOrData>} action - Action path to invoke.
+* @param {FaasParams<PathOrData>} defaultParams - Params used for the initial request and future reloads.
+* @param {useFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, and base URL overrides.
+* See the `useFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+* @returns {FaasDataInjection<PathOrData>} Request state and helper methods described by {@link FaasDataInjection}.
+*
+* @example
+* ```tsx
+* import { useFaas } from '@faasjs/react'
+*
+* function Profile({ id }: { id: number }) {
+*   const { data, error, loading, reload } = useFaas('/pages/users/get', { id })
+*
+*   if (loading) return <div>Loading...</div>
+*
+*   if (error) {
+*     return (
+*       <div>
+*         <div>Load failed: {error.message}</div>
+*         <button type="button" onClick={() => reload()}>
+*           Retry
+*         </button>
+*       </div>
+*     )
+*   }
+*
+*   return (
+*     <div>
+*       <span>{data.name}</span>
+*       <button type="button" onClick={() => reload()}>
+*         Refresh
+*       </button>
+*     </div>
+*   )
+* }
+* ```
+*/
+function useFaas(action, defaultParams, options = {}) {
+	const [data, setData] = useState();
+	const localSetData = setData;
+	const request = useFaasRequest({
+		action,
+		defaultParams,
+		options,
+		onSuccess: (nextData) => {
+			if (options.setData) options.setData(nextData);
+			else localSetData(nextData);
+		},
+		send: ({ action, params, signal, client, setPromise }) => {
+			const promise = client.faas(action, params, { signal });
+			setPromise(promise);
+			return promise.then((response) => response.data);
+		}
+	});
 	const currentData = options.data ?? data;
-	const currentPromise = promiseRef.current ?? Promise.resolve({});
+	const currentPromise = request.promiseRef.current ?? Promise.resolve({});
+	const updateData = options.setData ?? localSetData;
 	return {
 		action,
-		params,
-		loading,
+		params: request.params,
+		loading: request.loading,
 		data: currentData,
-		reloadTimes,
-		error,
+		reloadTimes: request.reloadTimes,
+		error: request.error,
 		promise: currentPromise,
-		reload,
-		setData: options.setData ?? localSetData,
-		setLoading,
+		reload: request.reload,
+		setData: updateData,
+		setLoading: request.setLoading,
 		setPromise: (newPromise) => {
-			promiseRef.current = typeof newPromise === "function" ? newPromise(currentPromise) : newPromise;
+			request.promiseRef.current = typeof newPromise === "function" ? newPromise(currentPromise) : newPromise;
 		},
-		setError
+		setError: request.setError
 	};
 }
 //#endregion
@@ -1254,13 +1333,13 @@ const clients = {};
 * The returned client is stored by `baseUrl` and becomes the default client
 * used by helpers such as {@link faas} and {@link useFaas}.
 *
-* @param options - Client configuration including base URL, default request options, and error hooks.
-* @param options.baseUrl - Base URL used to register and route the client instance.
-* @param options.options - Default browser-client request options forwarded to `FaasBrowserClient`.
-* @param options.onError - Hook factory used to handle failed `faas` and `useFaas` requests.
+* @param {FaasReactClientOptions} [options] - Client configuration including base URL, default request options, and error hooks.
+* @param {BaseUrl} [options.baseUrl] - Base URL used to register and route the client instance.
+* @param {Options} [options.options] - Default browser-client request options forwarded to `FaasBrowserClient`.
+* @param {OnError} [options.onError] - Hook factory used to handle failed `faas` and `useFaas` requests.
 * See {@link Options} for supported browser-client request fields such as `headers`,
 * `beforeRequest`, `request`, `baseUrl`, and `stream`.
-* @returns Registered FaasReactClient instance.
+* @returns {FaasReactClientInstance} Registered FaasReactClient instance.
 *
 * @example
 * ```ts
@@ -1313,8 +1392,8 @@ function FaasReactClient(options = { baseUrl: "/" }) {
 * different base URLs. In normal single-client app code, prefer the default
 * `faas`, `useFaas`, or `FaasReactClient` setup directly.
 *
-* @param host - Registered base URL to look up. Omit it to use the default client.
-* @returns Registered or newly created FaasReactClient instance.
+* @param {string} [host] - Registered base URL to look up. Omit it to use the default client.
+* @returns {FaasReactClientInstance} Registered or newly created FaasReactClient instance.
 *
 * @example
 * ```ts
@@ -1347,7 +1426,8 @@ function getClient(host) {
 * Returns a constant value that is created by the given function.
 *
 * @template T - Constant value type returned by the initializer.
-* @param fn - Initializer that runs only once for the current component instance.
+* @param {() => T} fn - Initializer that runs only once for the current component instance.
+* @returns {T} Stable value returned by the initializer.
 *
 * @example
 * ```tsx
@@ -1395,10 +1475,10 @@ var ErrorBoundary = class extends Component {
 	/**
 	* Create an error boundary with empty error state.
 	*
-	* @param props - Boundary props.
-	* @param props.children - Descendant elements protected by the boundary.
-	* @param props.onError - Callback invoked after a render error is captured.
-	* @param props.errorChildren - Custom fallback element that receives error details.
+	* @param {ErrorBoundaryProps} props - Boundary props.
+	* @param {ReactNode} [props.children] - Descendant elements protected by the boundary.
+	* @param {(error: Error | null, info: any) => void} [props.onError] - Callback invoked after a render error is captured.
+	* @param {ReactElement<ErrorChildrenProps>} [props.errorChildren] - Custom fallback element that receives error details.
 	*/
 	constructor(props) {
 		super(props);
@@ -1410,8 +1490,8 @@ var ErrorBoundary = class extends Component {
 	/**
 	* Capture rendering errors from descendant components.
 	*
-	* @param error - Caught render error.
-	* @param info - React component stack metadata.
+	* @param {Error} error - Caught render error.
+	* @param {ErrorInfo} info - React component stack metadata.
 	*/
 	componentDidCatch(error, info) {
 		this.setState({
@@ -1444,12 +1524,12 @@ var ErrorBoundary = class extends Component {
 /**
 * Conditionally wrap children with another component.
 *
-* @param props - Wrapper condition, wrapper component, and child content.
-* @param props.condition - When `true`, wrap children with `Wrapper`.
-* @param props.Wrapper - Component used as the wrapper when the condition passes.
-* @param props.wrapperProps - Props forwarded to the wrapper component.
-* @param props.children - Content rendered directly or inside the wrapper.
-* @returns Wrapped children or the original children when `condition` is false.
+* @param {OptionalWrapperProps} props - Wrapper condition, wrapper component, and child content.
+* @param {boolean} props.condition - When `true`, wrap children with `Wrapper`.
+* @param {OptionalWrapperProps['Wrapper']} props.Wrapper - Component used as the wrapper when the condition passes.
+* @param {OptionalWrapperProps['wrapperProps']} [props.wrapperProps] - Props forwarded to the wrapper component.
+* @param {ReactNode} props.children - Content rendered directly or inside the wrapper.
+* @returns {ReactNode} Wrapped children or the original children when `condition` is false.
 *
 * @example
 * ```tsx
@@ -1481,8 +1561,8 @@ OptionalWrapper.displayName = "OptionalWrapper";
 * Create local state entries and matching setters for each key in an object.
 *
 * @template T - A generic type that extends a record with string keys and any values.
-* @param initialStates - Object whose keys become state values and `setXxx` setters.
-* @returns Object containing the original keys plus generated setter functions.
+* @param {T} initialStates - Object whose keys become state values and `setXxx` setters.
+* @returns {StatesWithSetters<T>} Object containing the original keys plus generated setter functions.
 *
 * @example
 * ```tsx
@@ -1514,8 +1594,8 @@ function useSplittingState(initialStates) {
 * subscribe to the values they access.
 *
 * @template T - Context value shape exposed by the provider and hook.
-* @param defaultValue - Default value map or key list used to create split contexts.
-* @returns Provider and hook helpers for the split context.
+* @param {Record<string, any> | (keyof T)[]} defaultValue - Default value map or key list used to create split contexts.
+* @returns {{ Provider<NewT extends T = T>(this: void, props: { value?: Partial<NewT>; children: ReactNode; memo?: true | any[]; initializeStates?: Partial<NewT> }): ReactNode; use<NewT extends T = T>(this: void): Readonly<NewT> }} Provider and hook helpers for the split context.
 *
 * @example
 * ```tsx
@@ -1601,16 +1681,11 @@ function createSplittingContext(defaultValue) {
 * It sends a streaming request, appends decoded text chunks to `data`, and
 * exposes reload helpers for retrying the same action.
 *
-* @param action - Action path to invoke.
-* @param defaultParams - Params used for the initial request and future reloads.
-* @param options - Optional hook configuration such as controlled data, debounce, and skip logic.
-* @param options.params - Request params override used without mutating the hook's stored params state.
-* @param options.data - Controlled stream text used instead of the hook's internal state.
-* @param options.setData - Controlled setter used instead of the hook's internal `setData`.
-* @param options.skip - Boolean or predicate that suppresses the automatic request until `reload()` runs.
-* @param options.debounce - Milliseconds to wait before sending the latest request.
-* @param options.baseUrl - Base URL override used for this hook instance.
-* @returns Streaming request state and helper methods described by {@link UseFaasStreamResult}.
+* @param {string} action - Action path to invoke.
+* @param {Record<string, any>} defaultParams - Params used for the initial request and future reloads.
+* @param {UseFaasStreamOptions} [options] - Optional hook configuration such as controlled stream text, skip logic, debounce timing, and base URL overrides.
+* See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+* @returns {UseFaasStreamResult} Streaming request state and helper methods described by {@link UseFaasStreamResult}.
 *
 * @example
 * ```tsx
@@ -1637,123 +1712,46 @@ function createSplittingContext(defaultValue) {
 * ```
 */
 function useFaasStream(action, defaultParams, options = {}) {
-	const [loading, setLoading] = useState(true);
 	const [data, setData] = useState(options.data || "");
-	const [error, setError] = useState();
-	const [params, setParams] = useState(defaultParams);
-	const [reloadTimes, setReloadTimes] = useState(0);
-	const [fails, setFails] = useState(0);
-	const [skip, setSkip] = useState(typeof options.skip === "function" ? options.skip(defaultParams) : options.skip);
-	const controllerRef = useRef(null);
-	const pendingReloadsRef = useRef(/* @__PURE__ */ new Map());
-	const reloadCounterRef = useRef(0);
-	useEqualEffect(() => {
-		setSkip(typeof options.skip === "function" ? options.skip(params) : options.skip);
-	}, [typeof options.skip === "function" ? params : options.skip]);
-	useEqualEffect(() => {
-		if (!equal(defaultParams, params)) setParams(defaultParams);
-	}, [defaultParams]);
-	useEqualEffect(() => {
-		if (!action || skip) {
-			setLoading(false);
-			return;
-		}
-		setLoading(true);
-		setData("");
-		const controller = new AbortController();
-		controllerRef.current = controller;
-		const client = getClient(options.baseUrl);
-		const requestParams = options.params ?? params;
-		function send() {
-			client.browserClient.action(action, requestParams, {
-				signal: controller.signal,
+	const request = useFaasRequest({
+		action,
+		defaultParams,
+		options,
+		beforeSend: () => setData(""),
+		send: async ({ action, params, signal, client }) => {
+			const response = await client.browserClient.action(action, params, {
+				signal,
 				stream: true
-			}).then(async (response) => {
-				if (!response.body) {
-					setError(/* @__PURE__ */ new Error("Response body is null"));
-					setLoading(false);
-					return;
-				}
-				const reader = response.body.getReader();
-				const decoder = new TextDecoder();
-				let accumulatedText = "";
-				try {
-					while (true) {
-						const { done, value } = await reader.read();
-						if (done) break;
-						accumulatedText += decoder.decode(value, { stream: true });
-						setData(accumulatedText);
-					}
-					setFails(0);
-					setError(null);
-					setLoading(false);
-					for (const { resolve } of pendingReloadsRef.current.values()) resolve(accumulatedText);
-					pendingReloadsRef.current.clear();
-				} catch (readError) {
-					reader.releaseLock();
-					throw readError;
-				}
-			}).catch(async (e) => {
-				if (typeof e?.message === "string" && e.message.toLowerCase().indexOf("aborted") >= 0) return;
-				if (!fails && typeof e?.message === "string" && e.message.indexOf("Failed to fetch") >= 0) {
-					console.warn(`FaasReactClient: ${e.message} retry...`);
-					setFails(1);
-					return send();
-				}
-				let error = e;
-				if (client.onError) try {
-					await client.onError(action, requestParams)(e);
-				} catch (newError) {
-					error = newError;
-				}
-				setError(error);
-				setLoading(false);
-				for (const { reject } of pendingReloadsRef.current.values()) reject(error);
-				pendingReloadsRef.current.clear();
 			});
+			if (!response.body) throw new Error("Response body is null");
+			const reader = response.body.getReader();
+			const decoder = new TextDecoder();
+			let accumulatedText = "";
+			try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					accumulatedText += decoder.decode(value, { stream: true });
+					setData(accumulatedText);
+				}
+				return accumulatedText;
+			} catch (error) {
+				reader.releaseLock();
+				throw error;
+			}
 		}
-		if (options.debounce) {
-			const timeout = setTimeout(send, options.debounce);
-			return () => {
-				clearTimeout(timeout);
-				controllerRef.current?.abort();
-				setLoading(false);
-			};
-		}
-		send();
-		return () => {
-			controllerRef.current?.abort();
-			setLoading(false);
-		};
-	}, [
-		action,
-		options.params || params,
-		reloadTimes,
-		skip
-	]);
-	const reload = useEqualCallback((params) => {
-		if (skip) setSkip(false);
-		if (params) setParams(params);
-		const reloadCounter = ++reloadCounterRef.current;
-		return new Promise((resolve, reject) => {
-			pendingReloadsRef.current.set(reloadCounter, {
-				resolve,
-				reject
-			});
-			setReloadTimes((prev) => prev + 1);
-		});
-	}, [params, skip]);
+	});
 	return {
 		action,
-		params,
-		loading,
+		params: request.params,
+		loading: request.loading,
+		reloadTimes: request.reloadTimes,
 		data: options.data || data,
-		reloadTimes,
-		error,
-		reload,
+		error: request.error,
+		reload: request.reload,
 		setData: options.setData || setData,
-		setLoading,
-		setError
+		setLoading: request.setLoading,
+		setError: request.setError
 	};
 }
 //#endregion
@@ -1762,8 +1760,8 @@ function useFaasStream(action, defaultParams, options = {}) {
 * Hook to store the previous value of a state or prop.
 *
 * @template T - The type of the value.
-* @param value - The current value to track.
-* @returns Previous value from the prior render, or `undefined` on the first render.
+* @param {T} value - The current value to track.
+* @returns {T | undefined} Previous value from the prior render, or `undefined` on the first render.
 *
 * @example
 * ```tsx
@@ -1789,8 +1787,8 @@ function usePrevious(value) {
 * Custom hook that returns a stateful value and a ref to that value.
 *
 * @template T - The type of the value.
-* @param initialValue - Initial state value. When omitted, state starts as `null`.
-* @returns Tuple containing the current state, the state setter, and a ref that always points at the latest state.
+* @param {T} [initialValue] - Initial state value. When omitted, state starts as `null`.
+* @returns {[T | null, Dispatch<SetStateAction<T | null>>, RefObject<T | null>]} Tuple containing the current state, the state setter, and a ref that always points at the latest state.
 *
 * @example
 * ```tsx