@faasjs/react 8.0.0-beta.17 → 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/',
+* })
+*
+* const client = getClient('https://service-b.example.com/api/')
 *
-* getClient()
-* getClient('http://localhost:8080/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 ?? "");
@@ -1078,7 +1442,14 @@ var ErrorBoundary = class extends Component {
 //#endregion
 //#region src/OptionalWrapper.tsx
 /**
-* A wrapper component that conditionally wraps its children with a provided wrapper component.
+* Conditionally wrap children with another component.
+*
+* @param props - Wrapper condition, wrapper component, and child content.
+* @param props.condition - When `true`, wrap children with `Wrapper`.
+* @param props.Wrapper - Component used as the wrapper when the condition passes.
+* @param props.wrapperProps - Props forwarded to the wrapper component.
+* @param props.children - Content rendered directly or inside the wrapper.
+* @returns Wrapped children or the original children when `condition` is false.
 *
 * @example
 * ```tsx
@@ -1095,7 +1466,8 @@ var ErrorBoundary = class extends Component {
 * )
 * ```
 */
-function OptionalWrapper({ condition, Wrapper, wrapperProps, children }) {
+function OptionalWrapper(props) {
+	const { condition, Wrapper, wrapperProps, children } = props;
 	if (condition) return /* @__PURE__ */ jsx(Wrapper, {
 		...wrapperProps,
 		children
@@ -1135,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
@@ -1219,30 +1597,42 @@ function createSplittingContext(defaultValue) {
 /**
 * 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>
 * }
 * ```
 */
@@ -1374,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);