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

package/dist/index.cjs

@@ -3,14 +3,18 @@ let react = require("react");
 let react_jsx_runtime = require("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) {
@@ -135,14 +139,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 = {}) {
@@ -250,17 +270,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 = {
@@ -277,11 +302,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
@@ -289,24 +315,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' } }
 * })
 * ```
 *
@@ -318,11 +372,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
@@ -406,14 +471,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
@@ -483,9 +559,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)
@@ -663,16 +741,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)
 * ```
@@ -699,6 +785,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;
@@ -733,6 +827,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 = (0, react.useRef)(value);
@@ -754,6 +859,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 (0, react.useEffect)(callback, [useEqualSignal(dependencies)]);
@@ -761,9 +879,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);
@@ -776,9 +907,24 @@ 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 (0, react.useCallback)((...args) => callback(...args), [useEqualSignal(dependencies)]);
@@ -786,6 +932,91 @@ function useEqualCallback(callback, dependencies) {
 //#endregion
 //#region src/FaasDataWrapper.tsx
 const fixedForwardRef = react.forwardRef;
+/**
+* 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 = fixedForwardRef((props, ref) => {
 	const requestOptions = {
 		...props.data !== void 0 ? { data: props.data } : {},
@@ -817,11 +1048,36 @@ const FaasDataWrapper = fixedForwardRef((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) {
@@ -835,22 +1091,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>
+*   )
 * }
 * ```
 */
@@ -937,7 +1222,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,
@@ -975,18 +1259,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) {
@@ -1015,16 +1313,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) {
@@ -1039,6 +1349,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 = (0, react.useRef)(null);
@@ -1047,8 +1371,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 react.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 = {
@@ -1056,12 +1411,21 @@ var ErrorBoundary = class extends react.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 ?? "");
@@ -1080,43 +1444,41 @@ var ErrorBoundary = class extends react.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] = (0, react.useState)(initialValue ?? null);
-	const ref = (0, react.useRef)(state);
-	(0, react.useEffect)(() => {
-		ref.current = state;
-	}, [state]);
-	return [
-		state,
-		setState,
-		ref
-	];
+function OptionalWrapper(props) {
+	const { condition, Wrapper, wrapperProps, children } = props;
+	if (condition) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Wrapper, {
+		...wrapperProps,
+		children
+	});
+	return children;
 }
+OptionalWrapper.displayName = "OptionalWrapper";
 //#endregion
 //#region src/splittingState.tsx
 /**
@@ -1149,9 +1511,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
@@ -1229,306 +1597,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__ */ (0, react_jsx_runtime.jsx)(rest.Input, {
-		name,
-		value,
-		onChange: (v) => setValues((prev) => ({
-			...prev,
-			[name]: processValue(v, rules)
-		})),
-		...rest.props
-	});
-	return /* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.jsx)(props.label?.Label ?? Elements.Label, {
-		name: props.name,
-		...props.label,
-		error: errors[props.name],
-		children: /* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.jsx)(FormItem, { ...item }, item.name));
-}
-FormBody.displayName = "FormBody";
-//#endregion
-//#region src/Form/elements/Button.tsx
-const FormButtonElement = (0, react.forwardRef)(({ children, submit, submitting, ...props }, ref) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-	type: "button",
-	disabled: submitting,
-	onClick: submit,
-	...props,
-	ref,
-	children
-}));
-FormButtonElement.displayName = "FormButtonElement";
-//#endregion
-//#region src/Form/elements/Input.tsx
-const FormInputElement = (0, react.forwardRef)(({ onChange, ...props }, ref) => /* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.jsxs)("label", { children: [
-		title ?? name,
-		children,
-		description,
-		error && /* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.jsx)(Button, {
-		submitting,
-		submit: (0, react.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__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.jsx)(FormBody, {}), /* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.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>
 * }
 * ```
 */
@@ -1660,6 +1768,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 = (0, react.useRef)(void 0);
@@ -1669,17 +1788,48 @@ function usePrevious(value) {
 	return ref.current;
 }
 //#endregion
+//#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] = (0, react.useState)(initialValue ?? null);
+	const ref = (0, react.useRef)(state);
+	(0, react.useEffect)(() => {
+		ref.current = state;
+	}, [state]);
+	return [
+		state,
+		setState,
+		ref
+	];
+}
+//#endregion
 exports.ErrorBoundary = ErrorBoundary;
 exports.FaasBrowserClient = FaasBrowserClient;
 exports.FaasDataWrapper = FaasDataWrapper;
 exports.FaasReactClient = FaasReactClient;
-exports.Form = FormContainer;
-exports.FormContextProvider = FormContextProvider;
-exports.FormDefaultElements = FormDefaultElements;
-exports.FormDefaultLang = FormDefaultLang;
-exports.FormDefaultRules = FormDefaultRules;
-exports.FormInput = FormInput;
-exports.FormItem = FormItem;
 exports.OptionalWrapper = OptionalWrapper;
 exports.Response = Response;
 exports.ResponseError = ResponseError;
@@ -1696,9 +1846,7 @@ exports.useEqualMemo = useEqualMemo;
 exports.useEqualMemoize = useEqualMemoize;
 exports.useFaas = useFaas;
 exports.useFaasStream = useFaasStream;
-exports.useFormContext = useFormContext;
 exports.usePrevious = usePrevious;
 exports.useSplittingState = useSplittingState;
 exports.useStateRef = useStateRef;
-exports.validValues = validValues;
 exports.withFaasData = withFaasData;