@faasjs/react 8.0.0-beta.3 → 8.0.0-beta.31

package/dist/index.mjs

@@ -1,741 +1,1427 @@
-import { FaasBrowserClient } from '@faasjs/browser';
-import { useState, useImperativeHandle, cloneElement, forwardRef, useEffect, useMemo, createContext, useRef, useCallback, Component, useContext } from 'react';
-import { jsx, jsxs } from 'react/jsx-runtime';
-
-// src/client.tsx
-var AsyncFunction = (async () => {
-}).constructor;
+import { Component, cloneElement, createContext, forwardRef, useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/generate-id/index.ts
+/**
+* Generate a random identifier with an optional prefix.
+*
+* @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
+* ```
+*/
+function generateId(prefix = "", length = 18) {
+	if (length < 8 || length > 18) throw new Error("Length must be 8 ~ 18");
+	return `${prefix}${Date.now().toString(36).padStart(8, "0")}${Math.random().toString(36).substring(2, length - 6).padEnd(length - 8, "0")}`;
+}
+//#endregion
+//#region src/browser/response.ts
+/**
+* Wrapper class for HTTP responses from FaasJS functions.
+*
+* Provides a consistent interface for handling server responses with status code, headers,
+* body, and parsed data. Automatically handles JSON serialization and status code defaults.
+*
+* @template T - The type of the data property for type-safe response handling
+*/
+var Response = class {
+	/**
+	* HTTP status code exposed to callers.
+	*/
+	status;
+	/**
+	* Response headers keyed by header name.
+	*/
+	headers;
+	/**
+	* Raw response body.
+	*/
+	body;
+	/**
+	* Parsed response payload when JSON data is available.
+	*/
+	data;
+	/**
+	* Create a wrapped response object.
+	*/
+	constructor(props = {}) {
+		this.status = props.status || (props.data || props.body ? 200 : 204);
+		this.headers = props.headers || {};
+		this.body = props.body;
+		if (props.data !== void 0) this.data = props.data;
+		if (props.data && !props.body) this.body = JSON.stringify(props.data);
+	}
+};
+/**
+* Custom error class for handling HTTP response errors from FaasJS requests.
+*
+* Extends the built-in Error class to provide additional information about failed requests,
+* including HTTP status code, response headers, response body, and the original error.
+*/
+var ResponseError = class extends Error {
+	/**
+	* HTTP status code reported for the failed request.
+	*/
+	status;
+	/**
+	* Response headers returned with the error.
+	*/
+	headers;
+	/**
+	* Raw error body or fallback error payload.
+	*/
+	body;
+	/**
+	* Original error used to construct this instance, when available.
+	*/
+	originalError;
+	constructor(data, options) {
+		let props;
+		if (typeof data === "string") props = {
+			message: data,
+			...options
+		};
+		else if (data instanceof Error || typeof data === "object" && data !== null && typeof data.constructor?.name === "string" && data.constructor.name.includes("Error")) props = {
+			message: data.message,
+			originalError: data,
+			...options
+		};
+		else props = data;
+		super(props.message);
+		this.status = props.status || 500;
+		this.headers = props.headers || {};
+		this.body = props.body || props.originalError || { error: { message: props.message } };
+		if (props.originalError) this.originalError = props.originalError;
+	}
+};
+//#endregion
+//#region src/browser/mock.ts
+let mock = null;
+/**
+* Set the global mock handler used by all {@link FaasBrowserClient} instances.
+*/
+function setMock(handler) {
+	mock = handler;
+}
+function normalizeMockResponse(response) {
+	if (response instanceof Error) throw new ResponseError(response);
+	if (response instanceof Response) {
+		if (typeof ReadableStream !== "undefined" && response.body instanceof ReadableStream && response.body.locked === false) {
+			const [nextBody, currentBody] = response.body.tee();
+			response.body = nextBody;
+			const clonedResponse = {
+				status: response.status,
+				headers: response.headers,
+				body: currentBody
+			};
+			if (response.data !== void 0) clonedResponse.data = response.data;
+			return new Response({ ...clonedResponse });
+		}
+		return response;
+	}
+	if (response && typeof ReadableStream !== "undefined" && response.body instanceof ReadableStream && response.body.locked === false) {
+		const [nextBody, currentBody] = response.body.tee();
+		response.body = nextBody;
+		return new Response({
+			...response,
+			body: currentBody
+		});
+	}
+	return new Response(response || {});
+}
+async function resolveMockResponse(action, params, options) {
+	if (typeof mock === "function") return normalizeMockResponse(await mock(action, params, options));
+	return normalizeMockResponse(mock);
+}
+//#endregion
+//#region src/browser/helpers.ts
+function buildActionUrl(action, baseUrl, options, requestId) {
+	return `${(options?.baseUrl || baseUrl) + action.toLowerCase()}?_=${requestId}`;
+}
+function buildActionOptions(defaultOptions, options, params, requestId) {
+	const resolvedOptions = {
+		method: "POST",
+		headers: { "Content-Type": "application/json; charset=UTF-8" },
+		mode: "cors",
+		credentials: "include",
+		body: JSON.stringify(params),
+		...defaultOptions,
+		...options || Object.create(null)
+	};
+	if (!resolvedOptions.headers["X-FaasJS-Request-Id"] && !resolvedOptions.headers["x-faasjs-request-id"]) resolvedOptions.headers["X-FaasJS-Request-Id"] = requestId;
+	return resolvedOptions;
+}
+async function runBeforeRequest(action, params, options) {
+	if (!options.beforeRequest) return;
+	await options.beforeRequest({
+		action,
+		params,
+		options,
+		headers: options.headers
+	});
+}
+function toResponseHeaders(headers) {
+	const responseHeaders = {};
+	for (const [key, value] of headers) responseHeaders[key] = value;
+	return responseHeaders;
+}
+function parseSuccessfulResponse(status, headers, text) {
+	if (!text) return new Response({
+		status,
+		headers
+	});
+	const body = JSON.parse(text);
+	if (body.error?.message) throw new ResponseError({
+		message: body.error.message,
+		status,
+		headers,
+		body
+	});
+	return new Response({
+		status,
+		headers,
+		body,
+		data: body.data
+	});
+}
+function parseFailedResponse(status, headers, text) {
+	try {
+		const body = JSON.parse(text);
+		if (body.error?.message) throw new ResponseError({
+			message: body.error.message,
+			status,
+			headers,
+			body
+		});
+		throw new ResponseError({
+			message: text,
+			status,
+			headers,
+			body
+		});
+	} catch (error) {
+		if (error instanceof ResponseError) throw error;
+		throw new ResponseError({
+			message: text,
+			status,
+			headers,
+			body: text
+		});
+	}
+}
+async function parseFetchResponse(response) {
+	const headers = toResponseHeaders(response.headers);
+	const text = await response.text();
+	if (response.status >= 200 && response.status < 300) return parseSuccessfulResponse(response.status, headers, text);
+	return parseFailedResponse(response.status, headers, text);
+}
+//#endregion
+//#region src/browser/client.ts
+/**
+* Browser client for FaasJS - provides HTTP client functionality for making API requests from web applications.
+*/
+var FaasBrowserClient = class {
+	/**
+	* Unique identifier for this client instance.
+	*/
+	id;
+	/**
+	* Base URL used to build action request URLs.
+	*/
+	baseUrl;
+	/**
+	* Default request options merged into every request.
+	*/
+	defaultOptions;
+	/**
+	* Creates a new FaasBrowserClient instance.
+	*/
+	constructor(baseUrl = "/", options = Object.create(null)) {
+		if (baseUrl && !baseUrl.endsWith("/")) throw Error("[FaasJS] baseUrl should end with /");
+		this.id = `FBC-${generateId()}`;
+		this.baseUrl = baseUrl;
+		this.defaultOptions = options;
+	}
+	/**
+	* Makes a request to a FaasJS function.
+	*/
+	async action(action, params, options) {
+		if (!action) throw Error("[FaasJS] action required");
+		if (!params) params = Object.create(null);
+		const requestId = `F-${generateId()}`;
+		const url = buildActionUrl(action, this.baseUrl, options, requestId);
+		const resolvedOptions = buildActionOptions(this.defaultOptions, options, params, requestId);
+		await runBeforeRequest(action, params, resolvedOptions);
+		if (mock) return resolveMockResponse(action, params, resolvedOptions);
+		if (resolvedOptions.request) return resolvedOptions.request(url, resolvedOptions);
+		if (resolvedOptions.stream) return fetch(url, resolvedOptions);
+		return parseFetchResponse(await fetch(url, resolvedOptions));
+	}
+};
+//#endregion
+//#region src/faas/index.ts
+/**
+* Call the currently configured FaasReactClient.
+*
+* This helper forwards the request to `getClient`. When the registered
+* client defines `onError`, the hook is invoked before the promise rejects.
+*
+* @template Path - Action path or response data type used for inference.
+*
+* @param {Path} action - Action path to invoke.
+* @param {FaasParams<Path>} 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 {Promise<Response<FaasData<Path>>>} Response returned by the active browser client.
+* @throws {ResponseError} When the request fails and the active client does not recover inside `onError`.
+*
+* @example
+* ```ts
+* import { faas } from '@faasjs/react'
+*
+* const response = await faas('posts/get', { id: 1 })
+*
+* console.log(response.data.title)
+* ```
+*/
+async function faas(action, params, options) {
+	const client = getClient(options?.baseUrl);
+	const onError = client.onError;
+	if (onError) return client.browserClient.action(action, params, options).catch(async (res) => {
+		await onError(action, params)(res);
+		return Promise.reject(res);
+	});
+	return client.browserClient.action(action, params, options);
+}
+//#endregion
+//#region src/equal/index.ts
+const AsyncFunction = (async () => {}).constructor;
+/**
+* Compares two values for deep equality.
+*
+* This function checks if two values are deeply equal by comparing their types and contents.
+* It handles various data types including primitives, arrays, dates, regular expressions, functions,
+* maps, sets, and promises.
+*
+* @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
+* import { equal } from '@faasjs/react'
+*
+* equal({ page: 1, filters: ['a'] }, { page: 1, filters: ['a'] }) // true
+* equal({ page: 1 }, { page: 2 }) // false
+* ```
+*/
 function equal(a, b) {
-  if (a === b) return true;
-  if ((a === null || a === void 0) && (b === null || b === void 0))
-    return true;
-  if (typeof a !== typeof b) return false;
-  if (a === null || a === void 0 || b === null || b === void 0)
-    return false;
-  const ctor = a.constructor;
-  if (ctor !== b.constructor) return false;
-  switch (ctor) {
-    case String:
-    case Boolean:
-      return a === b;
-    case Number:
-      return Number.isNaN(a) && Number.isNaN(b) || a === b;
-    case Array: {
-      if (a.length !== b.length) return false;
-      for (let i = 0; i < a.length; i++) {
-        if (!equal(a[i], b[i])) return false;
-      }
-      return true;
-    }
-    case Date:
-      return a.getTime() === b.getTime();
-    case RegExp:
-    case Function:
-    case AsyncFunction:
-      return a.toString() === b.toString();
-    case Map:
-    case Set:
-      return equal(Array.from(a), Array.from(b));
-    case Promise:
-      return a === b;
-    case Object: {
-      for (const key of /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]))
-        if (!equal(a[key], b[key])) return false;
-      return true;
-    }
-    default:
-      throw Error(`Unsupported type: ${ctor}`);
-  }
+	if (a === b) return true;
+	if ((a === null || a === void 0) && (b === null || b === void 0)) return true;
+	if (typeof a !== typeof b) return false;
+	if (a === null || a === void 0 || b === null || b === void 0) return false;
+	const ctor = a.constructor;
+	if (ctor !== b.constructor) return false;
+	switch (ctor) {
+		case String:
+		case Boolean: return a === b;
+		case Number: return Number.isNaN(a) && Number.isNaN(b) || a === b;
+		case Array:
+			if (a.length !== b.length) return false;
+			for (let i = 0; i < a.length; i++) if (!equal(a[i], b[i])) return false;
+			return true;
+		case Date: return a.getTime() === b.getTime();
+		case RegExp:
+		case Function:
+		case AsyncFunction: return a.toString() === b.toString();
+		case Map:
+		case Set: return equal(Array.from(a), Array.from(b));
+		case Promise: return a === b;
+		case Object:
+			for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) if (!equal(a[key], b[key])) return false;
+			return true;
+		default: throw Error(`Unsupported type: ${ctor}`);
+	}
 }
+/**
+* Custom hook that memoizes a value using deep equality comparison.
+*
+* @param {any} value - The value to be memoized.
+* @returns {any} The memoized value.
+*
+* @example
+* ```tsx
+* import { useEqualMemoize } from '@faasjs/react'
+*
+* function Filters({ filters }: { filters: Record<string, any> }) {
+*   const memoizedFilters = useEqualMemoize(filters)
+*
+*   return <pre>{JSON.stringify(memoizedFilters)}</pre>
+* }
+* ```
+*/
 function useEqualMemoize(value) {
-  const ref = useRef(value);
-  const signalRef = useRef(0);
-  if (!equal(value, ref.current)) {
-    ref.current = value;
-    signalRef.current += 1;
-  }
-  return useMemo(() => ref.current, [signalRef.current]);
+	const ref = useRef(value);
+	if (!equal(value, ref.current)) ref.current = value;
+	return ref.current;
 }
+function useEqualSignal(value) {
+	const ref = useRef(value);
+	const signalRef = useRef(0);
+	if (!equal(value, ref.current)) {
+		ref.current = value;
+		signalRef.current += 1;
+	}
+	return signalRef.current;
+}
+/**
+* Custom hook that works like `useEffect` but uses deep comparison on 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
+* import { useEqualEffect } from '@faasjs/react'
+*
+* function Page({ filters }: { filters: Record<string, any> }) {
+*   useEqualEffect(() => {
+*     console.log('filters changed', filters)
+*   }, [filters])
+*
+*   return null
+* }
+* ```
+*/
 function useEqualEffect(callback, dependencies) {
-  return useEffect(callback, useEqualMemoize(dependencies));
+	return useEffect(callback, [useEqualSignal(dependencies)]);
 }
+/**
+* Custom hook that works like `useMemo` but uses deep comparison on dependencies.
+*
+* @template T - Memoized value type returned by the callback.
+*
+* @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
+* import { useEqualMemo } from '@faasjs/react'
+*
+* function Page({ filters }: { filters: Record<string, any> }) {
+*   const queryString = useEqualMemo(() => JSON.stringify(filters), [filters])
+*
+*   return <span>{queryString}</span>
+* }
+* ```
+*/
 function useEqualMemo(callback, dependencies) {
-  return useMemo(callback, useEqualMemoize(dependencies));
+	const signal = useEqualSignal(dependencies);
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	return useMemo(() => {
+		return callbackRef.current();
+	}, [signal]);
 }
+/**
+* Custom hook that works like `useCallback` but uses deep comparison on dependencies.
+*
+* @template T - Callback signature to memoize.
+*
+* @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
+* import { useEqualCallback } from '@faasjs/react'
+*
+* function Search({ filters }: { filters: Record<string, any> }) {
+*   const handleSubmit = useEqualCallback(() => {
+*     console.log(filters)
+*   }, [filters])
+*
+*   return <button onClick={handleSubmit}>Search</button>
+* }
+* ```
+*/
 function useEqualCallback(callback, dependencies) {
-  return useCallback(
-    (...args) => callback(...args),
-    useEqualMemoize(dependencies)
-  );
+	return useCallback((...args) => callback(...args), [useEqualSignal(dependencies)]);
 }
-var fixedForwardRef = forwardRef;
-var FaasDataWrapper = fixedForwardRef(
-  (props, ref) => {
-    const request = getClient(props.baseUrl).useFaas(
-      props.action,
-      props.params,
-      {
-        data: props.data,
-        setData: props.setData
-      }
-    );
-    const [loaded, setLoaded] = useState(false);
-    useImperativeHandle(ref, () => request, [request]);
-    useEqualEffect(() => {
-      if (!request.loading) setLoaded((prev) => prev === false ? true : prev);
-    }, [request.loading]);
-    useEqualEffect(() => {
-      if (props.onDataChange) props.onDataChange(request);
-    }, [request.data]);
-    const child = useEqualMemo(() => {
-      if (loaded) {
-        if (props.children) return cloneElement(props.children, request);
-        if (props.render) return props.render(request);
-      }
-      return props.fallback || null;
-    }, [
-      loaded,
-      request.action,
-      request.params,
-      request.data,
-      request.error,
-      request.loading
-    ]);
-    return child;
-  }
-);
-Object.assign(FaasDataWrapper, {
-  displayName: "FaasDataWrapper"
+/**
+* Fetch FaasJS data and inject the result into a render prop or child element.
+*
+* The wrapper defers rendering `children` or `render` until the first request
+* completes, then keeps passing the latest request state to the rendered output.
+*
+* @param {FaasDataWrapperProps<Path>} props - Wrapper props controlling the request and rendered fallback.
+* @param {(args: FaasDataInjection<Path>) => JSX.Element | JSX.Element[]} [props.render] - Render prop that receives the resolved Faas request state.
+* @param {React.ReactElement<Partial<FaasDataInjection<Path>>>} [props.children] - Child element cloned with injected Faas request state.
+* @param {JSX.Element | false} [props.fallback] - Element rendered before the first successful load.
+* @param {Path} props.action - Action path to request.
+* @param {FaasParams<Path>} [props.params] - Params sent to the action.
+* @param {number | false} [props.polling] - Milliseconds to wait after each completed request before refreshing data in the background.
+* @param {(args: FaasDataInjection<Path>) => void} [props.onDataChange] - Callback invoked when the resolved data value changes.
+* @param {FaasData<Path>} [props.data] - Controlled data value used instead of internal state.
+* @param {React.Dispatch<React.SetStateAction<FaasData<Path>>>} [props.setData] - Controlled setter used instead of internal state.
+* @param {BaseUrl} [props.baseUrl] - Base URL override used for this wrapper instance.
+*
+* @example
+* ```tsx
+* import { FaasDataWrapper } from '@faasjs/react'
+*
+* type User = {
+*   name: string
+* }
+*
+* function UserView(props: {
+*   data?: User
+*   error?: Error
+*   reload?: () => void
+* }) {
+*   if (props.error) {
+*     return (
+*       <div>
+*         <p>Failed to load user: {props.error.message}</p>
+*         <button type="button" onClick={() => props.reload?.()}>
+*           Retry
+*         </button>
+*       </div>
+*     )
+*   }
+*
+*   return <div>Hello, {props.data?.name}</div>
+* }
+*
+* // Render-prop mode
+* export function UserProfile(props: { id: number }) {
+*   return (
+*     <FaasDataWrapper<User>
+*       action="/pages/users/get"
+*       params={{ id: props.id }}
+*       fallback={<div>Loading user...</div>}
+*       render={({ data, error, reload }) => {
+*         if (error) {
+*           return (
+*             <div>
+*               <p>Failed to load user: {error.message}</p>
+*               <button type="button" onClick={() => reload()}>
+*                 Retry
+*               </button>
+*             </div>
+*           )
+*         }
+*
+*         return <div>Hello, {data.name}</div>
+*       }}
+*     />
+*   )
+* }
+*
+* // Children injection mode
+* export function UserProfileWithChildren(props: { id: number }) {
+*   return (
+*     <FaasDataWrapper<User>
+*       action="/pages/users/get"
+*       params={{ id: props.id }}
+*       fallback={<div>Loading user...</div>}
+*     >
+*       <UserView />
+*     </FaasDataWrapper>
+*   )
+* }
+* ```
+*
+* When a ref is provided, it exposes the current Faas request state imperatively.
+*/
+const FaasDataWrapper = forwardRef((props, ref) => {
+	const requestOptions = {
+		...props.data !== void 0 ? { data: props.data } : {},
+		...props.setData ? { setData: props.setData } : {},
+		...props.polling !== void 0 ? { polling: props.polling } : {}
+	};
+	const request = getClient(props.baseUrl).useFaas(props.action, props.params ?? {}, requestOptions);
+	const [loaded, setLoaded] = useState(false);
+	useImperativeHandle(ref, () => request, [request]);
+	useEqualEffect(() => {
+		if (!request.loading) setLoaded((prev) => prev === false ? true : prev);
+	}, [request.loading]);
+	useEqualEffect(() => {
+		if (props.onDataChange) props.onDataChange(request);
+	}, [request.data]);
+	return useEqualMemo(() => {
+		if (loaded) {
+			if (props.children) return cloneElement(props.children, request);
+			if (props.render) return props.render(request);
+		}
+		return props.fallback || null;
+	}, [
+		loaded,
+		request.action,
+		request.params,
+		request.data,
+		request.error,
+		request.loading,
+		request.refreshing
+	]);
 });
-function withFaasData(Component2, faasProps) {
-  return (props) => /* @__PURE__ */ jsx(FaasDataWrapper, { ...faasProps, children: /* @__PURE__ */ jsx(Component2, { ...props }) });
+Object.assign(FaasDataWrapper, { displayName: "FaasDataWrapper" });
+/**
+* Wrap a component with {@link FaasDataWrapper} and inject Faas request state as props.
+*
+* `withFaasData` is most useful for wrapper-style exports or when you want to
+* preserve an existing component boundary. For new code, prefer `useFaas` or
+* `FaasDataWrapper` when they express the request ownership more directly.
+*
+* @template Path - Action path or response data type used for inference.
+* @template TComponentProps - Component props including injected Faas data fields.
+* @param {React.FC<TComponentProps>} Component - Component that consumes injected Faas data props.
+* @param {FaasDataWrapperProps<Path>} faasProps - Request configuration forwarded to `FaasDataWrapper`.
+* @returns {React.FC<Omit<TComponentProps, keyof FaasDataInjection<Path>> & Record<string, any>>} Component that accepts the original props minus the injected Faas data fields.
+*
+* @example
+* ```tsx
+* import { withFaasData } from '@faasjs/react'
+*
+* const MyComponent = withFaasData(
+*   ({ data, error, reload }) => {
+*     if (error) {
+*       return (
+*         <button type="button" onClick={() => reload()}>
+*           Retry
+*         </button>
+*       )
+*     }
+*
+*     return <div>{data.name}</div>
+*   },
+*   { action: '/pages/users/get', params: { id: 1 } },
+* )
+* ```
+*/
+function withFaasData(Component, faasProps) {
+	return (props) => /* @__PURE__ */ jsx(FaasDataWrapper, {
+		...faasProps,
+		children: /* @__PURE__ */ jsx(Component, { ...props })
+	});
 }
-
-// src/faas.ts
-async function faas(action, params, options) {
-  const client = getClient(options?.baseUrl);
-  if (client.onError)
-    return client.browserClient.action(action, params, options).catch(async (res) => {
-      await client.onError(action, params)(res);
-      return Promise.reject(res);
-    });
-  return client.browserClient.action(action, params, options);
+//#endregion
+//#region src/useFaasRequest.ts
+/**
+* Run the shared request lifecycle used by the higher-level FaasJS React hooks.
+*
+* It manages loading state, background refresh state, abort signals, debounce timing,
+* retry-on-fetch-failure, polling, and queued reload promises while delegating the
+* actual transport to `send`.
+*
+* @template Path - Action path used for request params inference.
+* @template TData - Data type returned by `send` and resolved by `reload()`.
+* @param {UseFaasRequestArgs<Path>} args - Request lifecycle configuration.
+* @param {string} args.action - Action path or request key used to trigger the lifecycle.
+* @param {FaasParams<Path>} args.defaultParams - Initial params value stored by the lifecycle.
+* @param {Pick<SharedUseFaasOptions<FaasParams<Path>, FaasData<Path>>, 'params' | 'skip' | 'debounce' | 'polling' | 'baseUrl'>} args.options - Shared request options used by the lifecycle.
+* @param {(args: { silent: boolean }) => void} [args.beforeSend] - Optional callback invoked immediately before a request starts.
+* @param {(result: FaasData<Path>) => void} [args.onSuccess] - Optional callback invoked after a successful response.
+* @param {UseFaasRequestArgs<Path>['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
+* ```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 })
+*
+*       setPromise(promise)
+*
+*       return (await promise).data as { name: string }
+*     },
+*   })
+* }
+* ```
+*/
+function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess, send }) {
+	const [loading, setLoading] = useState(true);
+	const [refreshing, setRefreshing] = useState(false);
+	const [error, setError] = useState();
+	const [params, setParams] = useState(defaultParams);
+	const [requestTrigger, setRequestTrigger] = useState({
+		times: 0,
+		silent: false
+	});
+	const [skip, setSkip] = useState(typeof options.skip === "function" ? options.skip(defaultParams) : options.skip);
+	const promiseRef = useRef(null);
+	const controllerRef = useRef(null);
+	const failedOnceRef = useRef(false);
+	const pendingReloadsRef = useRef(/* @__PURE__ */ new Map());
+	const reloadCounterRef = useRef(0);
+	const requestVersionRef = useRef(0);
+	const handledRequestTriggerTimesRef = useRef(-1);
+	const pollingTimerRef = useRef(null);
+	const hasLoadedRef = useRef(false);
+	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]);
+	useEqualEffect(() => {
+		if (!equal(defaultParams, params)) setParams(defaultParams);
+	}, [defaultParams]);
+	useEqualEffect(() => {
+		if (!action || skip) {
+			setLoading(false);
+			setRefreshing(false);
+			return;
+		}
+		const isSilentRequest = requestTrigger.times !== handledRequestTriggerTimesRef.current && requestTrigger.silent && hasLoadedRef.current;
+		handledRequestTriggerTimesRef.current = requestTrigger.times;
+		if (isSilentRequest) setRefreshing(true);
+		else setLoading(true);
+		beforeSendRef.current?.({ silent: isSilentRequest });
+		failedOnceRef.current = false;
+		const controller = new AbortController();
+		const requestVersion = ++requestVersionRef.current;
+		controllerRef.current = controller;
+		const client = getClient(options.baseUrl);
+		const requestParams = options.params || params;
+		const clearPollingTimer = () => {
+			if (!pollingTimerRef.current) return;
+			clearTimeout(pollingTimerRef.current);
+			pollingTimerRef.current = null;
+		};
+		const schedulePolling = () => {
+			clearPollingTimer();
+			if (!options.polling || options.polling <= 0 || !isCurrentRequest()) return;
+			pollingTimerRef.current = setTimeout(() => {
+				if (!isCurrentRequest()) return;
+				setRequestTrigger((prev) => ({
+					times: prev.times + 1,
+					silent: true
+				}));
+			}, options.polling);
+		};
+		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 isCurrentRequest = () => requestVersion === requestVersionRef.current && controllerRef.current === controller;
+		const run = () => {
+			sendRef.current({
+				action,
+				params: requestParams,
+				signal: controller.signal,
+				client,
+				setPromise: (promise) => {
+					promiseRef.current = promise;
+				}
+			}).then((result) => {
+				if (!isCurrentRequest()) return;
+				failedOnceRef.current = false;
+				setError(null);
+				onSuccessRef.current?.(result);
+				hasLoadedRef.current = true;
+				setLoading(false);
+				setRefreshing(false);
+				resolvePending(result);
+				schedulePolling();
+			}).catch(async (e) => {
+				if (!isCurrentRequest()) return;
+				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(`[FaasJS] FaasReactClient: ${e.message} retry...`);
+					run();
+					return;
+				}
+				let nextError = e;
+				if (client.onError) try {
+					await client.onError(action, requestParams || Object.create(null))(e);
+				} catch (newError) {
+					nextError = newError;
+				}
+				if (!isCurrentRequest()) return;
+				setError(nextError);
+				setLoading(false);
+				setRefreshing(false);
+				rejectPending(nextError);
+				schedulePolling();
+			});
+		};
+		if (options.debounce) {
+			const timeout = setTimeout(run, options.debounce);
+			return () => {
+				clearTimeout(timeout);
+				clearPollingTimer();
+				if (controllerRef.current === controller) controllerRef.current = null;
+				controller.abort();
+				setLoading(false);
+				setRefreshing(false);
+			};
+		}
+		run();
+		return () => {
+			clearPollingTimer();
+			if (controllerRef.current === controller) controllerRef.current = null;
+			controller.abort();
+			setLoading(false);
+			setRefreshing(false);
+		};
+	}, [
+		action,
+		options.params || params,
+		requestTrigger,
+		skip,
+		options.debounce,
+		options.polling,
+		options.baseUrl
+	]);
+	const reload = useEqualCallback((nextParams, reloadOptions) => {
+		if (skip) setSkip(false);
+		if (nextParams) setParams(nextParams);
+		const reloadCounter = ++reloadCounterRef.current;
+		return new Promise((resolve, reject) => {
+			pendingReloadsRef.current.set(reloadCounter, {
+				resolve,
+				reject
+			});
+			setRequestTrigger((prev) => ({
+				times: prev.times + 1,
+				silent: Boolean(reloadOptions?.silent)
+			}));
+		});
+	}, [skip]);
+	return {
+		loading,
+		refreshing,
+		error,
+		params,
+		reloadTimes: requestTrigger.times,
+		reload,
+		promiseRef,
+		setError,
+		setLoading
+	};
 }
+//#endregion
+//#region src/useFaas/index.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, background refreshing, updating data, and handling errors.
+*
+* @template Path - Action path or response data type used for inference.
+*
+* @param {Path} action - Action path to invoke.
+* @param {FaasParams<Path>} defaultParams - Params used for the initial request and future reloads.
+* @param {UseFaasOptions<Path>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, polling, and base URL overrides.
+* See the `UseFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
+* @returns {FaasDataInjection<Path>} 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 [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 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);
-    controllerRef.current = new AbortController();
-    const client = getClient(options.baseUrl);
-    function send() {
-      const request = client.faas(
-        action,
-        options.params || params,
-        { signal: controllerRef.current.signal }
-      );
-      promiseRef.current = request;
-      request.then((r) => {
-        setFails(0);
-        setError(null);
-        options.setData ? options.setData(r.data) : setData(r.data);
-        setLoading(false);
-        for (const { resolve } of pendingReloadsRef.current.values())
-          resolve(r.data);
-        pendingReloadsRef.current.clear();
-      }).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 error2 = e;
-        if (client.onError)
-          try {
-            await client.onError(action, params)(e);
-          } catch (newError) {
-            error2 = newError;
-          }
-        setError(error2);
-        setLoading(false);
-        for (const { reject } of pendingReloadsRef.current.values())
-          reject(error2);
-        pendingReloadsRef.current.clear();
-        return;
-      });
-    }
-    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(
-    (params2) => {
-      if (skip) setSkip(false);
-      if (params2) setParams(params2);
-      const reloadCounter = ++reloadCounterRef.current;
-      setReloadTimes((prev) => prev + 1);
-      return new Promise((resolve, reject) => {
-        pendingReloadsRef.current.set(reloadCounter, { resolve, reject });
-        setReloadTimes((prev) => prev + 1);
-      });
-    },
-    [params, skip]
-  );
-  return {
-    action,
-    params,
-    loading,
-    data: options.data || data,
-    reloadTimes,
-    error,
-    promise: promiseRef.current,
-    reload,
-    setData: options.setData || setData,
-    setLoading,
-    setPromise: (newPromise) => typeof newPromise === "function" ? newPromise(promiseRef.current) : promiseRef.current = newPromise,
-    setError
-  };
+	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: async ({ action, params, signal, client, setPromise }) => {
+			const promise = client.faas(action, params, { signal });
+			setPromise(promise);
+			return (await promise).data;
+		}
+	});
+	const currentData = options.data ?? data;
+	const currentPromise = request.promiseRef.current ?? Promise.resolve({});
+	const updateData = options.setData ?? localSetData;
+	return {
+		action,
+		params: request.params,
+		loading: request.loading,
+		refreshing: request.refreshing,
+		data: currentData,
+		reloadTimes: request.reloadTimes,
+		error: request.error,
+		promise: currentPromise,
+		reload: request.reload,
+		setData: updateData,
+		setLoading: request.setLoading,
+		setPromise: (newPromise) => {
+			request.promiseRef.current = typeof newPromise === "function" ? newPromise(currentPromise) : newPromise;
+		},
+		setError: request.setError
+	};
 }
-var clients = {};
-function FaasReactClient({ baseUrl, options, onError } = {
-  baseUrl: "/"
-}) {
-  const client = new FaasBrowserClient(baseUrl, options);
-  const reactClient = {
-    id: client.id,
-    faas: async (action, params, options2) => faas(action, params, { baseUrl, ...options2 }),
-    useFaas: (action, defaultParams, options2) => useFaas(action, defaultParams, { baseUrl, ...options2 }),
-    FaasDataWrapper: (props) => /* @__PURE__ */ jsx(FaasDataWrapper, { baseUrl, ...props }),
-    onError,
-    browserClient: client
-  };
-  clients[baseUrl] = reactClient;
-  return reactClient;
+//#endregion
+//#region src/client.tsx
+const clients = {};
+/**
+* Create and register a FaasReactClient instance.
+*
+* The returned client is stored by `baseUrl` and becomes the default client
+* used by helpers such as {@link faas} and {@link useFaas}.
+*
+* @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 {FaasReactClientInstance} Registered FaasReactClient instance.
+*
+* @example
+* ```ts
+* import { FaasReactClient, ResponseError } from '@faasjs/react'
+*
+* const client = FaasReactClient({
+*   baseUrl: 'http://localhost:8080/api/',
+*   onError: (action, params) => async (res) => {
+*     if (res instanceof ResponseError) {
+*       reportErrorToSentry(res, {
+*         tags: { action },
+*         extra: { params },
+*       })
+*     }
+*   },
+* })
+* ```
+*/
+function FaasReactClient(options = { baseUrl: "/" }) {
+	const { baseUrl, options: clientOptions, onError } = options;
+	const resolvedBaseUrl = baseUrl ?? "/";
+	const client = new FaasBrowserClient(resolvedBaseUrl, clientOptions);
+	function withBaseUrl(options) {
+		if (options?.baseUrl) return options;
+		return {
+			...options ?? {},
+			baseUrl: resolvedBaseUrl
+		};
+	}
+	const reactClient = {
+		id: client.id,
+		faas: async (action, params, requestOptions) => faas(action, params, withBaseUrl(requestOptions)),
+		useFaas: (action, defaultParams, requestOptions) => useFaas(action, defaultParams, withBaseUrl(requestOptions)),
+		FaasDataWrapper: (props) => /* @__PURE__ */ jsx(FaasDataWrapper, {
+			...props,
+			baseUrl: resolvedBaseUrl
+		}),
+		...onError ? { onError } : {},
+		browserClient: client
+	};
+	clients[resolvedBaseUrl] = reactClient;
+	return reactClient;
 }
+/**
+* Get a registered FaasReactClient instance.
+*
+* When `host` is omitted, the first registered client is returned. If no client
+* has been created yet, a default client is initialized automatically.
+* Use `getClient` only for special cases such as multiple Faas clients with
+* different base URLs. In normal single-client app code, prefer the default
+* `faas`, `useFaas`, or `FaasReactClient` setup directly.
+*
+* @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
+* import { FaasReactClient, getClient } from '@faasjs/react'
+*
+* FaasReactClient({
+*   baseUrl: 'https://service-a.example.com/api/',
+* })
+*
+* FaasReactClient({
+*   baseUrl: 'https://service-b.example.com/api/',
+* })
+*
+* const client = getClient('https://service-b.example.com/api/')
+*
+* await client.faas('/pages/posts/get', { id: 1 })
+* ```
+*/
 function getClient(host) {
-  const client = clients[host || Object.keys(clients)[0]];
-  if (!client) {
-    console.warn("FaasReactClient is not initialized manually, use default.");
-    return FaasReactClient();
-  }
-  return client;
+	const client = clients[host || Object.keys(clients)[0]];
+	if (!client) {
+		console.warn("[FaasJS] FaasReactClient is not initialized manually, use default.");
+		return FaasReactClient();
+	}
+	return client;
 }
+//#endregion
+//#region src/constants/index.ts
+/**
+* Returns a constant value that is created by the given function.
+*
+* @template T - Constant value type returned by the initializer.
+* @param {() => T} fn - Initializer that runs only once for the current component instance.
+* @returns {T} Stable value returned by the initializer.
+*
+* @example
+* ```tsx
+* import { useConstant } from '@faasjs/react'
+*
+* function Page() {
+*   const requestId = useConstant(() => crypto.randomUUID())
+*
+*   return <span>{requestId}</span>
+* }
+* ```
+*/
 function useConstant(fn) {
-  const ref = useRef(null);
-  if (!ref.current) {
-    ref.current = { v: fn() };
-  }
-  return ref.current.v;
+	const ref = useRef(null);
+	if (!ref.current) ref.current = { v: fn() };
+	return ref.current.v;
 }
+//#endregion
+//#region src/ErrorBoundary/index.tsx
+/**
+* React error boundary with an optional custom fallback element.
+*
+* The boundary renders its children until a descendant throws. After that it
+* either clones `errorChildren` with injected error details or renders a simple
+* built-in fallback.
+*
+* @example
+* ```tsx
+* import { ErrorBoundary } from '@faasjs/react'
+*
+* function Fallback({ errorMessage }: { errorMessage?: string }) {
+*   return <div>{errorMessage}</div>
+* }
+*
+* <ErrorBoundary errorChildren={<Fallback />}>
+*   <DangerousWidget />
+* </ErrorBoundary>
+* ```
+*/
 var ErrorBoundary = class extends Component {
-  static displayName = "ErrorBoundary";
-  constructor(props) {
-    super(props);
-    this.state = {
-      error: void 0,
-      info: { componentStack: "" }
-    };
-  }
-  componentDidCatch(error, info) {
-    this.setState({
-      error,
-      info
-    });
-  }
-  render() {
-    const errorMessage = (this.state.error || "").toString();
-    const errorDescription = this.state.info?.componentStack ? this.state.info.componentStack : null;
-    if (this.state.error) {
-      if (this.props.onError)
-        this.props.onError(this.state.error, this.state.info);
-      if (this.props.errorChildren)
-        return cloneElement(this.props.errorChildren, {
-          error: this.state.error,
-          info: this.state.info,
-          errorMessage,
-          errorDescription
-        });
-      return /* @__PURE__ */ jsxs("div", { children: [
-        /* @__PURE__ */ jsx("p", { children: errorMessage }),
-        /* @__PURE__ */ jsx("pre", { children: errorDescription })
-      ] });
-    }
-    return this.props.children;
-  }
+	/**
+	* Stable display name used by React DevTools.
+	*/
+	static displayName = "ErrorBoundary";
+	/**
+	* Create an error boundary with empty error state.
+	*
+	* @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);
+		this.state = {
+			error: null,
+			info: { componentStack: "" }
+		};
+	}
+	/**
+	* Capture rendering errors from descendant components.
+	*
+	* @param {Error} error - Caught render error.
+	* @param {ErrorInfo} info - React component stack metadata.
+	*/
+	componentDidCatch(error, info) {
+		this.setState({
+			error,
+			info
+		});
+	}
+	/**
+	* Render children or the configured fallback for the captured error.
+	*/
+	render() {
+		const { error, info } = this.state;
+		const errorMessage = String(error ?? "");
+		const errorDescription = info.componentStack || void 0;
+		if (error) {
+			if (this.props.onError) this.props.onError(error, info);
+			if (this.props.errorChildren) return cloneElement(this.props.errorChildren, {
+				error,
+				info,
+				errorMessage,
+				...errorDescription ? { errorDescription } : {}
+			});
+			return /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("p", { children: errorMessage }), /* @__PURE__ */ jsx("pre", { children: errorDescription })] });
+		}
+		return this.props.children ?? null;
+	}
 };
-function useStateRef(initialValue) {
-  const [state, setState] = useState(initialValue ?? null);
-  const ref = useRef(state);
-  useEffect(() => {
-    ref.current = state;
-  }, [state]);
-  return [state, setState, ref];
+//#endregion
+//#region src/OptionalWrapper/index.tsx
+/**
+* Conditionally wrap children with another component.
+*
+* @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
+* import { OptionalWrapper } from '@faasjs/react'
+*
+* const Wrapper = ({ children }: { children: React.ReactNode }) => (
+*   <div className='wrapper'>{children}</div>
+* )
+*
+* const App = () => (
+*   <OptionalWrapper condition={true} Wrapper={Wrapper}>
+*     <span>Test</span>
+*   </OptionalWrapper>
+* )
+* ```
+*/
+function OptionalWrapper(props) {
+	const { condition, Wrapper, wrapperProps, children } = props;
+	if (condition) return /* @__PURE__ */ jsx(Wrapper, {
+		...wrapperProps,
+		children
+	});
+	return children;
 }
+OptionalWrapper.displayName = "OptionalWrapper";
+//#endregion
+//#region src/splitting-state/index.tsx
+/**
+* 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 {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
+* function Counter() {
+*   const { count, setCount, name, setName } = useSplittingState({ count: 0, name: 'John' })
+*
+*   return <>{name}: {count}</>
+* }
+* ```
+*/
 function useSplittingState(initialStates) {
-  const states = {};
-  for (const key of Object.keys(initialStates)) {
-    const state = useState(initialStates[key]);
-    Object.assign(states, {
-      [key]: state[0],
-      [`set${String(key).charAt(0).toUpperCase()}${String(key).slice(1)}`]: state[1]
-    });
-  }
-  return states;
+	const states = {};
+	for (const key of Object.keys(initialStates)) {
+		const state = useState(initialStates[key]);
+		Object.assign(states, {
+			[key]: state[0],
+			[`set${String(key).charAt(0).toUpperCase()}${String(key).slice(1)}`]: state[1]
+		});
+	}
+	return states;
 }
+//#endregion
+//#region src/splitting-context/index.tsx
+/**
+* Create a context whose keys can be consumed independently.
+*
+* `createSplittingContext` returns a `Provider` and a `use` hook. Each key in
+* the provided shape is backed by a separate React context so readers only
+* subscribe to the values they access.
+*
+* @template T - Context value shape exposed by the provider and hook.
+* @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
+* const { Provider, use } = createSplittingContext<{
+*   value: number
+*   setValue: React.Dispatch<React.SetStateAction<number>>
+* }>({
+*   value: 0,
+*   setValue: null,
+* })
+*
+* function ReaderComponent() {
+*   const { value } = use()
+*
+*   return <div>{value}</div>
+* }
+*
+* function WriterComponent() {
+*   const { setValue } = use()
+*
+*   return (
+*     <button type='button' onClick={() => setValue((p: number) => p + 1)}>
+*       Change
+*     </button>
+*   )
+* }
+*
+* function App() {
+*   const [value, setValue] = useState(0)
+*
+*   return (
+*     <Provider value={{ value, setValue }}>
+*       <ReaderComponent />
+*       <WriterComponent />
+*     </Provider>
+*   )
+* }
+* ```
+*/
 function createSplittingContext(defaultValue) {
-  const keys = Array.isArray(defaultValue) ? defaultValue : Object.keys(defaultValue);
-  const defaultValues = Array.isArray(defaultValue) ? keys.reduce(
-    (prev, cur) => {
-      prev[cur] = null;
-      return prev;
-    },
-    {}
-  ) : defaultValue;
-  const contexts = {};
-  for (const key of keys) contexts[key] = createContext(defaultValues[key]);
-  function Provider(props) {
-    const states = props.initializeStates ? useSplittingState(props.initializeStates) : {};
-    let children = props.memo ? useEqualMemo(
-      () => props.children,
-      props.memo === true ? [] : props.memo
-    ) : props.children;
-    for (const key of keys) {
-      const Context = contexts[key];
-      const value = props.value?.[key] ?? states[key] ?? defaultValues[key];
-      children = /* @__PURE__ */ jsx(Context.Provider, { value, children });
-    }
-    return children;
-  }
-  Provider.displayName = "SplittingContextProvider";
-  function use() {
-    return useConstant(() => {
-      const obj = /* @__PURE__ */ Object.create(null);
-      for (const key of Object.keys(contexts)) {
-        Object.defineProperty(obj, key, {
-          get: () => {
-            if (!contexts[key]) {
-              throw new Error(`Context for key "${key}" is undefined`);
-            }
-            return useContext(contexts[key]);
-          }
-        });
-      }
-      return Object.freeze(obj);
-    });
-  }
-  return {
-    Provider,
-    use
-  };
-}
-
-// src/Form/context.tsx
-var FormContext = createSplittingContext([
-  "items",
-  "onSubmit",
-  "Elements",
-  "lang",
-  "rules",
-  "submitting",
-  "setSubmitting",
-  "values",
-  "setValues",
-  "errors",
-  "setErrors",
-  "valuesRef"
-]);
-var FormContextProvider = FormContext.Provider;
-var useFormContext = FormContext.use;
-function processValue(input, rules) {
-  switch (rules?.type) {
-    case "number":
-      return Number(input);
-    case "string":
-      return String(input);
-    default:
-      return input;
-  }
-}
-function FormInput({
-  name,
-  rules,
-  ...rest
-}) {
-  const { Elements, values, setValues } = useFormContext();
-  const value = values?.[name];
-  if (rest.Input) {
-    return /* @__PURE__ */ jsx(
-      rest.Input,
-      {
-        name,
-        value,
-        onChange: (v) => setValues((prev) => ({
-          ...prev,
-          [name]: processValue(v, rules)
-        })),
-        ...rest.props
-      }
-    );
-  }
-  return /* @__PURE__ */ jsx(
-    Elements.Input,
-    {
-      name,
-      value,
-      onChange: (v) => setValues((prev) => ({
-        ...prev,
-        [name]: processValue(v, rules)
-      })),
-      ...rest.props
-    }
-  );
-}
-FormInput.displayName = "FormInput";
-function FormItem(props) {
-  const { Elements, errors } = useFormContext();
-  const Label = props.label?.Label ?? Elements.Label;
-  return /* @__PURE__ */ jsx(Label, { name: props.name, ...props.label, error: errors[props.name], children: /* @__PURE__ */ jsx(FormInput, { name: props.name, rules: props.rules, ...props.input }) });
-}
-FormItem.displayName = "FormItem";
-function FormBody() {
-  const { items } = useFormContext();
-  return items.map((item) => /* @__PURE__ */ jsx(FormItem, { ...item }, item.name));
-}
-FormBody.displayName = "FormBody";
-var FormButtonElement = forwardRef(({ children, submit, submitting, ...props }, ref) => /* @__PURE__ */ jsx(
-  "button",
-  {
-    type: "button",
-    disabled: submitting,
-    onClick: submit,
-    ...props,
-    ref,
-    children
-  }
-));
-FormButtonElement.displayName = "FormButtonElement";
-var FormInputElement = forwardRef(({ onChange, ...props }, ref) => /* @__PURE__ */ jsx("input", { ...props, onChange: (e) => onChange(e.target.value), ref }));
-FormInputElement.displayName = "FormInputElement";
-var FormLabelElement = ({
-  name,
-  title,
-  description,
-  error,
-  children
-}) => {
-  return /* @__PURE__ */ jsxs("label", { children: [
-    title ?? name,
-    children,
-    description,
-    error && /* @__PURE__ */ jsx("div", { style: { color: "red" }, children: error.message })
-  ] });
-};
-FormLabelElement.displayName = "FormLabelElement";
-
-// src/Form/elements/index.ts
-var FormDefaultElements = {
-  Label: FormLabelElement,
-  Input: FormInputElement,
-  Button: FormButtonElement
-};
-
-// src/Form/rules.ts
-var FormDefaultRules = {
-  required: async (value, _, lang) => {
-    if (value === null || value === void 0 || value === "" || Number.isNaN(value)) {
-      throw Error(lang?.required);
-    }
-  },
-  type: async (value, options, lang) => {
-    switch (options) {
-      case "string":
-        if (typeof value !== "string") throw Error(lang?.string);
-        break;
-      case "number":
-        if (Number.isNaN(Number(value))) throw Error(lang?.number);
-        break;
-    }
-  },
-  custom: async (value, options) => {
-    return options(value);
-  }
-};
-async function validValues(rules, items, values, lang) {
-  const errors = {};
-  for (const item of items) {
-    const value = values[item.name];
-    const rulesOptions = item.rules;
-    if (rulesOptions) {
-      for (const [name, options] of Object.entries(rulesOptions)) {
-        try {
-          await rules[name](value, options, lang);
-        } catch (error) {
-          errors[item.name] = error;
-          break;
-        }
-      }
-    }
-  }
-  return errors;
-}
-function FormFooter() {
-  const {
-    submitting,
-    setSubmitting,
-    onSubmit,
-    valuesRef,
-    Elements,
-    items,
-    setErrors,
-    lang,
-    rules
-  } = useFormContext();
-  const handleSubmit = useCallback(async () => {
-    setSubmitting(true);
-    setErrors({});
-    const errors = await validValues(rules, items, valuesRef.current, lang);
-    if (Object.keys(errors).length) {
-      setErrors(errors);
-      setSubmitting(false);
-      return;
-    }
-    onSubmit(valuesRef.current).finally(() => setSubmitting(false));
-  }, [setSubmitting, setErrors, rules, items, lang, onSubmit]);
-  const MemoizedButton = useMemo(
-    () => /* @__PURE__ */ jsx(Elements.Button, { submitting, submit: handleSubmit, children: lang.submit }),
-    [submitting, handleSubmit, lang.submit, Elements.Button]
-  );
-  return MemoizedButton;
-}
-FormFooter.displayName = "FormFooter";
-
-// src/Form/lang.ts
-var FormDefaultLang = {
-  submit: "Submit",
-  required: "This field is required",
-  string: "This field must be a string",
-  number: "This field must be a number"
-};
-function mergeValues(items, defaultValues = {}) {
-  const values = {};
-  for (const item of items)
-    values[item.name] = defaultValues[item.name] ?? "";
-  return values;
-}
-function FormContainer({
-  defaultValues,
-  Elements,
-  rules,
-  lang,
-  items,
-  ...props
-}) {
-  const [values, setValues, valuesRef] = useStateRef(
-    mergeValues(items, defaultValues)
-  );
-  return /* @__PURE__ */ jsxs(
-    FormContextProvider,
-    {
-      initializeStates: {
-        errors: {},
-        submitting: false
-      },
-      value: {
-        Elements: Object.assign(FormDefaultElements, Elements),
-        lang: Object.assign(FormDefaultLang, lang),
-        rules: Object.assign(FormDefaultRules, rules),
-        items,
-        values,
-        setValues,
-        valuesRef,
-        ...props
-      },
-      memo: true,
-      children: [
-        /* @__PURE__ */ jsx(FormBody, {}),
-        /* @__PURE__ */ jsx(FormFooter, {})
-      ]
-    }
-  );
+	const keys = Array.isArray(defaultValue) ? defaultValue : Object.keys(defaultValue);
+	const defaultValues = Array.isArray(defaultValue) ? keys.reduce((prev, cur) => {
+		prev[cur] = null;
+		return prev;
+	}, {}) : defaultValue;
+	const contexts = {};
+	for (const key of keys) contexts[key] = createContext(defaultValues[key]);
+	function Provider(props) {
+		const states = props.initializeStates ? useSplittingState(props.initializeStates) : {};
+		let children = props.memo ? useEqualMemo(() => props.children, props.memo === true ? [] : props.memo) : props.children;
+		for (const key of keys) {
+			const Context = contexts[key];
+			const value = props.value?.[key] ?? states[key] ?? defaultValues[key];
+			children = /* @__PURE__ */ jsx(Context.Provider, {
+				value,
+				children
+			});
+		}
+		return children;
+	}
+	Provider.displayName = "SplittingContextProvider";
+	function use() {
+		return useConstant(() => {
+			const obj = Object.create(null);
+			for (const key of Object.keys(contexts)) Object.defineProperty(obj, key, { get: () => {
+				if (!contexts[key]) throw new Error(`Context for key "${key}" is undefined`);
+				return useContext(contexts[key]);
+			} });
+			return Object.freeze(obj);
+		});
+	}
+	return {
+		Provider,
+		use
+	};
 }
-FormContainer.displayName = "FormContainer";
-function OptionalWrapper({
-  condition,
-  Wrapper,
-  wrapperProps,
-  children
-}) {
-  if (condition) return /* @__PURE__ */ jsx(Wrapper, { ...wrapperProps, children });
-  return children;
-}
-OptionalWrapper.displayName = "OptionalWrapper";
+//#endregion
+//#region src/useFaasStream/index.tsx
+/**
+* Stream a FaasJS response into React state.
+*
+* `useFaasStream` is the default hook for streaming FaasJS responses in React.
+* It sends a streaming request, appends decoded text chunks to `data`, and
+* exposes reload helpers for retrying the same action.
+*
+* @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, polling, and base URL overrides.
+* See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
+* @returns {UseFaasStreamResult} Streaming request state and helper methods described by {@link UseFaasStreamResult}.
+*
+* @example
+* ```tsx
+* import { useFaasStream } from '@faasjs/react'
+*
+* function Chat({ prompt }: { prompt: string }) {
+*   const { data, error, loading, reload } = useFaasStream('/pages/chat/stream', { prompt })
+*
+*   if (loading) return <div>Streaming...</div>
+*
+*   if (error) {
+*     return (
+*       <div>
+*         <div>Stream failed: {error.message}</div>
+*         <button type="button" onClick={() => reload()}>
+*           Retry
+*         </button>
+*       </div>
+*     )
+*   }
+*
+*   return <pre>{data}</pre>
+* }
+* ```
+*/
 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("");
-    controllerRef.current = new AbortController();
-    const client = getClient(options.baseUrl);
-    function send() {
-      client.browserClient.action(action, options.params || params, {
-        signal: controllerRef.current.signal,
-        stream: true
-      }).then(async (response) => {
-        if (!response.body) {
-          setError(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 error2 = e;
-        if (client.onError)
-          try {
-            await client.onError(action, params)(e);
-          } catch (newError) {
-            error2 = newError;
-          }
-        setError(error2);
-        setLoading(false);
-        for (const { reject } of pendingReloadsRef.current.values())
-          reject(error2);
-        pendingReloadsRef.current.clear();
-        return;
-      });
-    }
-    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(
-    (params2) => {
-      if (skip) setSkip(false);
-      if (params2) setParams(params2);
-      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,
-    data: options.data || data,
-    reloadTimes,
-    error,
-    reload,
-    setData: options.setData || setData,
-    setLoading,
-    setError
-  };
+	const [data, setData] = useState(options.data ?? "");
+	const updateData = options.setData ?? setData;
+	const request = useFaasRequest({
+		action,
+		defaultParams,
+		options,
+		beforeSend: ({ silent }) => {
+			if (!silent) updateData("");
+		},
+		send: async ({ action, params, signal, client }) => {
+			const response = await client.browserClient.action(action, params, {
+				signal,
+				stream: true
+			});
+			if (!response.body) throw new Error("Response body is null");
+			const reader = response.body.getReader();
+			const decoder = new TextDecoder();
+			let accumulatedText = "";
+			const onAbort = () => {
+				reader.cancel().catch(() => void 0);
+			};
+			if (signal.aborted) {
+				onAbort();
+				throw new Error("Request aborted");
+			}
+			signal.addEventListener("abort", onAbort, { once: true });
+			try {
+				while (true) {
+					if (signal.aborted) throw new Error("Request aborted");
+					const { done, value } = await reader.read();
+					if (done) break;
+					accumulatedText += decoder.decode(value, { stream: true });
+					updateData(accumulatedText);
+				}
+				accumulatedText += decoder.decode();
+				return accumulatedText;
+			} catch (error) {
+				if (signal.aborted) throw new Error("Request aborted");
+				throw error;
+			} finally {
+				signal.removeEventListener("abort", onAbort);
+				try {
+					reader.releaseLock();
+				} catch {}
+			}
+		}
+	});
+	return {
+		action,
+		params: request.params,
+		loading: request.loading,
+		refreshing: request.refreshing,
+		reloadTimes: request.reloadTimes,
+		data: options.data ?? data,
+		error: request.error,
+		reload: request.reload,
+		setData: updateData,
+		setLoading: request.setLoading,
+		setError: request.setError
+	};
 }
+//#endregion
+//#region src/usePrevious/index.ts
+/**
+* Hook to store the previous value of a state or prop.
+*
+* @template T - The type of the value.
+* @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
+* import { usePrevious } from '@faasjs/react'
+*
+* function Counter({ count }: { count: number }) {
+*   const previous = usePrevious(count)
+*
+*   return <span>{previous} -> {count}</span>
+* }
+* ```
+*/
 function usePrevious(value) {
-  const ref = useRef(void 0);
-  useEffect(() => {
-    ref.current = value;
-  });
-  return ref.current;
+	const ref = useRef(void 0);
+	useEffect(() => {
+		ref.current = value;
+	});
+	return ref.current;
+}
+//#endregion
+//#region src/useStateRef/index.ts
+/**
+* Custom hook that returns a stateful value and a ref to that value.
+*
+* @template T - The type of the value.
+* @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
+* import { useStateRef } from '@faasjs/react'
+*
+* function MyComponent() {
+*   const [value, setValue, ref] = useStateRef(0)
+*
+*   return (
+*     <div>
+*       <p>Value: {value}</p>
+*       <button onClick={() => setValue(value + 1)}>Increment</button>
+*       <button onClick={() => console.log(ref.current)}>Submit</button>
+*     </div>
+*   )
+* }
+* ```
+*/
+function useStateRef(initialValue) {
+	const [state, setState] = useState(initialValue ?? null);
+	const ref = useRef(state);
+	useEffect(() => {
+		ref.current = state;
+	}, [state]);
+	return [
+		state,
+		setState,
+		ref
+	];
 }
-
-export { ErrorBoundary, FaasDataWrapper, FaasReactClient, FormContainer as Form, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormItem, OptionalWrapper, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+//#endregion
+export { ErrorBoundary, FaasBrowserClient, FaasDataWrapper, FaasReactClient, OptionalWrapper, Response, ResponseError, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, usePrevious, useSplittingState, useStateRef, withFaasData };