@faasjs/react 8.0.0-beta.16 → 8.0.0-beta.18

package/dist/index.mjs

@@ -2,14 +2,18 @@ import { Component, cloneElement, createContext, forwardRef, useCallback, useCon
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/generateId.ts
 /**
-* Generate random id with prefix
+* Generate a random identifier with an optional prefix.
 *
-* @param prefix prefix of id
-* @param length length of id without prefix, range is 8 ~ 18, default is 18
+* @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.
+* @throws {Error} When `length` is outside the supported `8` to `18` range.
 *
 * @example
 * ```ts
-* generateId('prefix-') // prefix-1z3b4c5d6e
+* const id = generateId('prefix-')
+*
+* id.startsWith('prefix-') // true
 * ```
 */
 function generateId(prefix = "", length = 18) {
@@ -134,14 +138,30 @@ function generateId(prefix = "", length = 18) {
 * @see FaasBrowserClient.action for method returning Response
 */
 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.
 	*
 	* @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.
 	*/
 	constructor(props = {}) {
@@ -249,17 +269,22 @@ var Response = class {
 * @see setMock for mocking errors in tests
 */
 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;
-	originalError;
 	/**
-	* Create a ResponseError from a message, Error, or structured response error payload.
-	*
-	* @param data - Error message, Error object, or structured response error props.
-	* @param options - Additional options such as status, headers, and body.
-	* @returns ResponseError instance.
+	* Original error used to construct this instance, when available.
 	*/
+	originalError;
 	constructor(data, options) {
 		let props;
 		if (typeof data === "string") props = {
@@ -276,11 +301,12 @@ var ResponseError = class extends Error {
 		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;
 	}
 };
 let mock = null;
 /**
-* Set global mock handler for testing. Mock affects all FaasBrowserClient instances.
+* Set the global mock handler used by all {@link FaasBrowserClient} instances.
 *
 * @param handler - Mock handler, can be:
 *   - MockHandler function: receives (action, params, options) and returns response data
@@ -288,24 +314,52 @@ let mock = null;
 *   - Response instance: pre-configured Response object
 *   - null or undefined: clear mock
 *
+* @example Reset in Vitest shared setup
+* ```ts
+* import { afterEach } from 'vitest'
+*
+* afterEach(() => {
+*   setMock(null)
+* })
+* ```
+*
+* @example Use ResponseProps object
+* ```ts
+* setMock({
+*   data: { name: 'FaasJS' },
+* })
+*
+* setMock({
+*   status: 500,
+*   data: { message: 'Internal Server Error' },
+* })
+* ```
+*
 * @example Use MockHandler function
 * ```ts
-* setMock(async (action, params, options) => {
-*   if (action === 'user') {
-*     return { data: { name: 'John' } }
+* setMock(async (action) => {
+*   if (action === '/pages/users/get') {
+*     return { data: { id: 1, name: 'FaasJS' } }
 *   }
-*   return { status: 404, data: { error: 'Not found' } }
+*
+*   return { status: 404, data: { message: 'Not Found' } }
 * })
 *
-* const response = await client.action('user')
+* const response = await client.action('/pages/users/get')
 * ```
 *
-* @example Use ResponseProps object
+* @example Branch by action and params
 * ```ts
-* setMock({
-*   status: 200,
-*   data: { result: 'success' },
-*   headers: { 'X-Custom': 'value' }
+* setMock(async (action, params) => {
+*   if (action === '/pages/users/get' && params?.id === 1) {
+*     return { data: { id: 1, name: 'Admin' } }
+*   }
+*
+*   if (action === '/pages/users/get' && params?.id === 2) {
+*     return { data: { id: 2, name: 'Editor' } }
+*   }
+*
+*   return { status: 404, data: { message: 'User not found' } }
 * })
 * ```
 *
@@ -317,11 +371,22 @@ let mock = null;
 * }))
 * ```
 *
+* @example Streaming response
+* ```ts
+* setMock({
+*   body: new ReadableStream({
+*     start(controller) {
+*       controller.enqueue(new TextEncoder().encode('hello'))
+*       controller.enqueue(new TextEncoder().encode(' world'))
+*       controller.close()
+*     },
+*   }),
+* })
+* ```
+*
 * @example Clear mock
 * ```ts
 * setMock(null)
-* // or
-* setMock(undefined)
 * ```
 *
 * @example Handle errors
@@ -405,14 +470,25 @@ function setMock(handler) {
 * @see ResponseError for error handling
 */
 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.
 	*
 	* @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.
+	* See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
+	* `request`, `baseUrl`, and `stream`.
 	*
 	* @example Basic initialization
 	* ```ts
@@ -482,9 +558,11 @@ var FaasBrowserClient = class {
 	*   Optional if the function accepts no parameters.
 	* @param 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 that resolves to a Response object containing status, headers, body, and data.
-	*   The data property is typed based on the PathOrData generic parameter.
+	* @returns 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
 	* @throws {ResponseError} When the server returns an error response (status >= 400 or body.error exists)
@@ -662,16 +740,24 @@ var FaasBrowserClient = class {
 /**
 * 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 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`,
+* `request`, `baseUrl`, and `stream`.
 * @returns 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<{ title: string }>('post/get', { id: 1 })
+* const response = await faas('posts/get', { id: 1 })
 *
 * console.log(response.data.title)
 * ```
@@ -698,6 +784,14 @@ const AsyncFunction = (async () => {}).constructor;
 * @param a - The first value to compare.
 * @param b - The second value to compare.
 * @returns `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;
@@ -732,6 +826,17 @@ function equal(a, b) {
 *
 * @param value - The value to be memoized.
 * @returns 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);
@@ -753,6 +858,19 @@ function useEqualSignal(value) {
 * @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.
+*
+* @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, [useEqualSignal(dependencies)]);
@@ -760,9 +878,22 @@ function useEqualEffect(callback, dependencies) {
 /**
 * Custom hook that works like `useMemo` but uses deep comparison on 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.
+*
+* @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) {
 	const signal = useEqualSignal(dependencies);
@@ -775,13 +906,113 @@ function useEqualMemo(callback, dependencies) {
 /**
 * Custom hook that works like `useCallback` but uses deep comparison on 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.
+*
+* @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), [useEqualSignal(dependencies)]);
 }
+/**
+* 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 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.
+*
+* @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 } : {},
@@ -813,11 +1044,36 @@ const FaasDataWrapper = forwardRef((props, ref) => {
 });
 Object.assign(FaasDataWrapper, { displayName: "FaasDataWrapper" });
 /**
-* HOC to wrap a component with FaasDataWrapper
+* Wrap a component with {@link FaasDataWrapper} and inject Faas request state as props.
+*
+* `withFaasData` is most useful for wrapper-style exports or compatibility with
+* an existing component boundary. For new code, prefer `useFaas` or
+* `FaasDataWrapper` when they express the request ownership more directly.
+*
+* @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.
 *
 * @example
 * ```tsx
-* const MyComponent = withFaasData(({ data }) => <div>{data.name}</div>, { action: 'test', params: { a: 1 } })
+* 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) {
@@ -831,22 +1087,51 @@ function withFaasData(Component, faasProps) {
 /**
 * Request FaasJS data and keep request state in React state.
 *
-* `useFaas` sends an initial request unless `skip` is enabled, and returns
-* request state plus helpers for reloading, updating data, and handling errors.
+* `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.
-* @returns Request state and helper methods for the action.
+* @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}.
 *
 * @example
 * ```tsx
 * import { useFaas } from '@faasjs/react'
 *
-* function Post({ id }: { id: number }) {
-*   const { data } = useFaas<{ title: string }>('post/get', { id })
+* 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 <h1>{data.title}</h1>
+*   return (
+*     <div>
+*       <span>{data.name}</span>
+*       <button type="button" onClick={() => reload()}>
+*         Refresh
+*       </button>
+*     </div>
+*   )
 * }
 * ```
 */
@@ -933,7 +1218,6 @@ function useFaas(action, defaultParams, options = {}) {
 		if (skip) setSkip(false);
 		if (params) setParams(params);
 		const reloadCounter = ++reloadCounterRef.current;
-		setReloadTimes((prev) => prev + 1);
 		return new Promise((resolve, reject) => {
 			pendingReloadsRef.current.set(reloadCounter, {
 				resolve,
@@ -971,18 +1255,32 @@ const clients = {};
 * 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.
+* See {@link Options} for supported browser-client request fields such as `headers`,
+* `beforeRequest`, `request`, `baseUrl`, and `stream`.
 * @returns Registered FaasReactClient instance.
 *
 * @example
 * ```ts
-* import { FaasReactClient } from '@faasjs/react'
+* 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({ baseUrl, options: clientOptions, onError } = { baseUrl: "/" }) {
+function FaasReactClient(options = { baseUrl: "/" }) {
+	const { baseUrl, options: clientOptions, onError } = options;
 	const resolvedBaseUrl = baseUrl ?? "/";
 	const client = new FaasBrowserClient(resolvedBaseUrl, clientOptions);
 	function withBaseUrl(options) {
@@ -1011,16 +1309,28 @@ function FaasReactClient({ baseUrl, options: clientOptions, onError } = { baseUr
 *
 * 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 host - Registered base URL to look up. Omit it to use the default client.
 * @returns Registered or newly created FaasReactClient instance.
 *
 * @example
 * ```ts
-* import { getClient } from '@faasjs/react'
+* import { FaasReactClient, getClient } from '@faasjs/react'
+*
+* FaasReactClient({
+*   baseUrl: 'https://service-a.example.com/api/',
+* })
+*
+* FaasReactClient({
+*   baseUrl: 'https://service-b.example.com/api/',
+* })
 *
-* getClient()
-* getClient('http://localhost:8080/api/')
+* const client = getClient('https://service-b.example.com/api/')
+*
+* await client.faas('/pages/posts/get', { id: 1 })
 * ```
 */
 function getClient(host) {
@@ -1035,6 +1345,20 @@ function getClient(host) {
 //#region src/constant.ts
 /**
 * 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.
+*
+* @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);
@@ -1043,8 +1367,39 @@ function useConstant(fn) {
 }
 //#endregion
 //#region src/ErrorBoundary.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 {
+	/**
+	* Stable display name used by React DevTools.
+	*/
 	static displayName = "ErrorBoundary";
+	/**
+	* 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.
+	*/
 	constructor(props) {
 		super(props);
 		this.state = {
@@ -1052,12 +1407,21 @@ var ErrorBoundary = class extends Component {
 			info: { componentStack: "" }
 		};
 	}
+	/**
+	* Capture rendering errors from descendant components.
+	*
+	* @param error - Caught render error.
+	* @param 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 ?? "");
@@ -1076,43 +1440,41 @@ var ErrorBoundary = class extends Component {
 	}
 };
 //#endregion
-//#region src/useStateRef.ts
+//#region src/OptionalWrapper.tsx
 /**
-* Custom hook that returns a stateful value and a ref to that value.
+* Conditionally wrap children with another component.
 *
-* @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 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.
 *
 * @example
 * ```tsx
-* import { useStateRef } from '@faasjs/react'
+* import { OptionalWrapper } from '@faasjs/react'
 *
-* function MyComponent() {
-*   const [value, setValue, ref] = useStateRef(0)
+* const Wrapper = ({ children }: { children: React.ReactNode }) => (
+*   <div className='wrapper'>{children}</div>
+* )
 *
-*   return (
-*     <div>
-*       <p>Value: {value}</p>
-*       <button onClick={() => setValue(value + 1)}>Increment</button>
-*       <button onClick={() => console.log(ref.current)}>Submit</button>
-*     </div>
-*   )
-* }
+* const App = () => (
+*   <OptionalWrapper condition={true} Wrapper={Wrapper}>
+*     <span>Test</span>
+*   </OptionalWrapper>
+* )
 * ```
 */
-function useStateRef(initialValue) {
-	const [state, setState] = useState(initialValue ?? null);
-	const ref = useRef(state);
-	useEffect(() => {
-		ref.current = state;
-	}, [state]);
-	return [
-		state,
-		setState,
-		ref
-	];
+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/splittingState.tsx
 /**
@@ -1145,9 +1507,15 @@ function useSplittingState(initialStates) {
 //#endregion
 //#region src/splittingContext.tsx
 /**
-* Creates a splitting context with the given default value.
+* 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.
 *
-* @param defaultValue The default value of the splitting context.
+* @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.
 *
 * @example
 * ```tsx
@@ -1225,306 +1593,46 @@ function createSplittingContext(defaultValue) {
 	};
 }
 //#endregion
-//#region src/Form/context.tsx
-const FormContext = createSplittingContext([
-	"items",
-	"onSubmit",
-	"Elements",
-	"lang",
-	"rules",
-	"submitting",
-	"setSubmitting",
-	"values",
-	"setValues",
-	"errors",
-	"setErrors",
-	"valuesRef"
-]);
-const FormContextProvider = FormContext.Provider;
-const useFormContext = FormContext.use;
-//#endregion
-//#region src/Form/Input.tsx
-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";
-//#endregion
-//#region src/Form/Item.tsx
-function FormItem(props) {
-	const { Elements, errors } = useFormContext();
-	return /* @__PURE__ */ jsx(props.label?.Label ?? Elements.Label, {
-		name: props.name,
-		...props.label,
-		error: errors[props.name],
-		children: /* @__PURE__ */ jsx(FormInput, {
-			name: props.name,
-			...props.input,
-			...props.rules ? { rules: props.rules } : {}
-		})
-	});
-}
-FormItem.displayName = "FormItem";
-//#endregion
-//#region src/Form/Body.tsx
-function FormBody() {
-	const { items } = useFormContext();
-	return items.map((item) => /* @__PURE__ */ jsx(FormItem, { ...item }, item.name));
-}
-FormBody.displayName = "FormBody";
-//#endregion
-//#region src/Form/elements/Button.tsx
-const FormButtonElement = forwardRef(({ children, submit, submitting, ...props }, ref) => /* @__PURE__ */ jsx("button", {
-	type: "button",
-	disabled: submitting,
-	onClick: submit,
-	...props,
-	ref,
-	children
-}));
-FormButtonElement.displayName = "FormButtonElement";
-//#endregion
-//#region src/Form/elements/Input.tsx
-const FormInputElement = forwardRef(({ onChange, ...props }, ref) => /* @__PURE__ */ jsx("input", {
-	...props,
-	onChange: (e) => onChange(e.target.value),
-	ref
-}));
-FormInputElement.displayName = "FormInputElement";
-//#endregion
-//#region src/Form/elements/Label.tsx
-const 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";
-//#endregion
-//#region src/Form/elements/index.ts
-const FormDefaultElements = {
-	Label: FormLabelElement,
-	Input: FormInputElement,
-	Button: FormButtonElement
-};
-//#endregion
-//#region src/Form/rules.ts
-/**
-* Default validation rules for a form.
-*/
-const 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;
-}
-//#endregion
-//#region src/Form/Footer.tsx
-function FormFooter() {
-	const { submitting, setSubmitting, onSubmit, valuesRef, Elements, items, setErrors, lang, rules } = useFormContext();
-	const Button = Elements.Button;
-	return /* @__PURE__ */ jsx(Button, {
-		submitting,
-		submit: 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,
-			valuesRef,
-			lang,
-			onSubmit
-		]),
-		children: lang.submit
-	});
-}
-FormFooter.displayName = "FormFooter";
-//#endregion
-//#region src/Form/lang.ts
-const FormDefaultLang = {
-	submit: "Submit",
-	required: "This field is required",
-	string: "This field must be a string",
-	number: "This field must be a number"
-};
-//#endregion
-//#region src/Form/Container.tsx
-function mergeValues(items, defaultValues = {}) {
-	const values = {};
-	for (const item of items) values[item.name] = defaultValues[item.name] ?? "";
-	return values;
-}
-/**
-* Render a form with context, default elements, and validation state.
-*
-* `FormContainer` merges provided elements, language strings, and rules with
-* the package defaults, then exposes them through form context.
-*
-* @template Values - The type of form values, defaults to Record<string, any>.
-* @template FormElements - The type of form elements, defaults to FormElementTypes.
-* @template Rules - The type of form rules, defaults to FormDefaultRules.
-* @param props - Form items and optional overrides for defaults, language, rules, and submit behavior.
-* @returns React form container with shared form context.
-*
-* @example
-* ```tsx
-* import { Form } from '@faasjs/react'
-*
-* function MyForm() {
-*   return (
-*     <Form
-*       items={[
-*         { name: 'name' },
-*       ]}
-*     />
-*   )
-* }
-* ```
-*/
-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, {})]
-	});
-}
-FormContainer.displayName = "FormContainer";
-//#endregion
-//#region src/OptionalWrapper.tsx
-/**
-* A wrapper component that conditionally wraps its children with a provided wrapper component.
-*
-* @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({ condition, Wrapper, wrapperProps, children }) {
-	if (condition) return /* @__PURE__ */ jsx(Wrapper, {
-		...wrapperProps,
-		children
-	});
-	return children;
-}
-OptionalWrapper.displayName = "OptionalWrapper";
-//#endregion
 //#region src/useFaasStream.tsx
 /**
 * Stream a FaasJS response into React state.
 *
-* The hook sends a streaming request, appends decoded text chunks to `data`,
-* and exposes reload helpers for retrying the same action.
+* `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 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.
-* @returns Streaming request state and helper methods.
+* @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}.
 *
 * @example
 * ```tsx
-* import { useState } from 'react'
 * import { useFaasStream } from '@faasjs/react'
 *
-* function Chat() {
-*   const [prompt, setPrompt] = useState('')
-*   const { data, loading, reload } = useFaasStream('chat', { prompt })
+* function Chat({ prompt }: { prompt: string }) {
+*   const { data, error, loading, reload } = useFaasStream('/pages/chat/stream', { prompt })
 *
-*   return (
-*     <div>
-*       <textarea value={prompt} onChange={e => setPrompt(e.target.value)} />
-*       <button onClick={reload} disabled={loading}>Send</button>
-*       <div>{data}</div>
-*     </div>
-*   )
+*   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>
 * }
 * ```
 */
@@ -1656,6 +1764,17 @@ function useFaasStream(action, defaultParams, options = {}) {
 * @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.
+*
+* @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);
@@ -1665,4 +1784,42 @@ function usePrevious(value) {
 	return ref.current;
 }
 //#endregion
-export { ErrorBoundary, FaasBrowserClient, FaasDataWrapper, FaasReactClient, FormContainer as Form, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormInput, FormItem, OptionalWrapper, Response, ResponseError, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+//#region src/useStateRef.ts
+/**
+* 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.
+*
+* @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
+	];
+}
+//#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 };