@faasjs/react 8.0.0-beta.17 → 8.0.0-beta.19

package/dist/index.d.ts

@@ -5,14 +5,18 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/generateId.d.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
  * ```
  */
 declare function generateId(prefix?: string, length?: number): string;
@@ -78,7 +82,7 @@ type BaseUrl = `${string}/`;
  * @see Response for response object structure
  */
 type Options = RequestInit & {
-  headers?: Record<string, string>; /** trigger before request */
+  headers?: Record<string, string>; /** Async hook called after request options are merged but before the request is sent. */
   beforeRequest?: ({
     action,
     params,
@@ -89,9 +93,9 @@ type Options = RequestInit & {
     params?: Record<string, any> | undefined;
     options: Options;
     headers: Record<string, string>;
-  }) => Promise<void>; /** custom request */
-  request?: <PathOrData extends FaasActionUnionType$1>(url: string, options: Options) => Promise<Response<FaasData$1<PathOrData>>>;
-  baseUrl?: BaseUrl;
+  }) => Promise<void>; /** Custom request implementation used instead of the native `fetch`. */
+  request?: <PathOrData extends FaasActionUnionType$1>(url: string, options: Options) => Promise<Response<FaasData$1<PathOrData>>>; /** Base URL override for the current request. */
+  baseUrl?: BaseUrl; /** When `true`, return the native fetch response so callers can consume the stream manually. */
   stream?: boolean;
 };
 /**
@@ -128,6 +132,8 @@ type ResponseHeaders = {
  * @param action - The function path to call.
  * @param params - Optional parameters for the function.
  * @param options - Optional request overrides.
+ * See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
+ * `request`, `baseUrl`, and `stream`.
  * @returns Promise resolving to the request response. In streaming mode the runtime returns the native fetch response.
  *
  * Notes:
@@ -294,23 +300,42 @@ type ResponseProps<T = any> = {
  * @see FaasBrowserClient.action for method returning Response
  */
 declare class Response<T = any> {
+  /**
+   * HTTP status code exposed to callers.
+   */
   readonly status: number;
+  /**
+   * Response headers keyed by header name.
+   */
   readonly headers: ResponseHeaders;
+  /**
+   * Raw response body.
+   */
   readonly body: any;
+  /**
+   * Parsed response payload when JSON data is available.
+   */
   readonly data?: T;
   /**
    * 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?: ResponseProps<T>);
 }
+/**
+ * Input accepted by the {@link ResponseError} constructor.
+ */
 type ResponseErrorProps = {
-  message: string; /** @default 500 */
-  status?: number; /** @default {} */
-  headers?: ResponseHeaders; /** @default { error: Error(message) } */
-  body?: any;
+  /** User-facing error message. */message: string; /** HTTP status code reported for the error. @default 500 */
+  status?: number; /** Response headers returned with the error. @default {} */
+  headers?: ResponseHeaders; /** Raw error body or structured error payload. @default { error: { message } } */
+  body?: any; /** Original error preserved when this instance wraps another exception. */
   originalError?: Error;
 };
 /**
@@ -410,12 +435,39 @@ type ResponseErrorProps = {
  * @see setMock for mocking errors in tests
  */
 declare class ResponseError extends Error {
+  /**
+   * HTTP status code reported for the failed request.
+   */
   readonly status: number;
+  /**
+   * Response headers returned with the error.
+   */
   readonly headers: ResponseHeaders;
+  /**
+   * Raw error body or fallback error payload.
+   */
   readonly body: any;
+  /**
+   * Original error used to construct this instance, when available.
+   */
   readonly originalError?: Error;
-  constructor(msg: string | Error, options?: Omit<ResponseErrorProps, 'message' | 'originalError'>);
-  constructor(props: ResponseErrorProps);
+  /**
+   * Create a ResponseError from a message, Error, or structured response error payload.
+   *
+   * @param data - Error message, Error object, or structured response error props.
+   * @param data.message - User-facing error message when `data` is a structured object.
+   * @param data.status - HTTP status code when `data` is a structured object.
+   * @param data.headers - Response headers returned with the error when `data` is a structured object.
+   * @param data.body - Raw error body or structured error payload when `data` is a structured object.
+   * @param data.originalError - Original error preserved on the instance when `data` is a structured object.
+   * @param options - Additional options such as status, headers, and body.
+   * @param options.status - HTTP status override used when `data` is a string or `Error`.
+   * @param options.headers - Response headers override used when `data` is a string or `Error`.
+   * @param options.body - Raw error body override used when `data` is a string or `Error`.
+   * @returns ResponseError instance.
+   */
+  constructor(data: string | Error, options?: Omit<ResponseErrorProps, 'message' | 'originalError'>);
+  constructor(data: ResponseErrorProps);
 }
 /**
  * Mock handler function type for testing FaasJS requests.
@@ -433,6 +485,8 @@ declare class ResponseError extends Error {
  * @param options - The full request options including headers, beforeRequest hook, and other config.
  *   Includes X-FaasJS-Request-Id header in the headers object.
  *   Contains merged client defaults and per-request options.
+ *   See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
+ *   `request`, `baseUrl`, and `stream`.
  *
  * @returns A promise resolving to:
  *   - ResponseProps: Mock response data (status, headers, body, data)
@@ -499,7 +553,7 @@ declare class ResponseError extends Error {
  */
 type MockHandler = (action: string, params: Record<string, any> | undefined, options: Options) => Promise<ResponseProps> | Promise<void> | Promise<Error>;
 /**
- * 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
@@ -507,24 +561,52 @@ type MockHandler = (action: string, params: Record<string, any> | undefined, opt
  *   - 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' } }
  * })
  * ```
  *
@@ -536,11 +618,22 @@ type MockHandler = (action: string, params: Record<string, any> | undefined, opt
  * }))
  * ```
  *
+ * @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
@@ -551,7 +644,7 @@ type MockHandler = (action: string, params: Record<string, any> | undefined, opt
  * // This will reject with ResponseError
  * ```
  */
-declare function setMock(handler: MockHandler | ResponseProps | Response | null): void;
+declare function setMock(handler: MockHandler | ResponseProps | Response | null | undefined): void;
 /**
  * Browser client for FaasJS - provides HTTP client functionality for making API requests from web applications.
  *
@@ -622,14 +715,25 @@ declare function setMock(handler: MockHandler | ResponseProps | Response | null)
  * @see ResponseError for error handling
  */
 declare class FaasBrowserClient {
+  /**
+   * Unique identifier for this client instance.
+   */
   readonly id: string;
+  /**
+   * Base URL used to build action request URLs.
+   */
   baseUrl: BaseUrl;
+  /**
+   * Default request options merged into every request.
+   */
   defaultOptions: Options;
   /**
    * 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
@@ -693,9 +797,11 @@ declare class FaasBrowserClient {
    *   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)
@@ -791,16 +897,24 @@ declare class FaasBrowserClient {
 /**
  * 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)
  * ```
@@ -809,57 +923,182 @@ declare function faas<PathOrData extends FaasActionUnionType$1>(action: FaasActi
 //#endregion
 //#region src/FaasDataWrapper.d.ts
 /**
- * Injects FaasData props.
+ * Request state injected by {@link useFaas}, {@link FaasDataWrapper}, and {@link withFaasData}.
+ *
+ * @template PathOrData - Action path or response data type used for inference.
  */
 type FaasDataInjection<PathOrData extends FaasActionUnionType$1 = any> = {
-  action: FaasAction$1<PathOrData>;
-  params: FaasParams$1<PathOrData>;
-  loading: boolean;
-  reloadTimes: number;
-  data: FaasData$1<PathOrData>;
-  error: any;
+  /** Action path associated with the current request state. */action: FaasAction$1<PathOrData>; /** Params used for the most recent request attempt. */
+  params: FaasParams$1<PathOrData>; /** Whether the request is currently in flight. */
+  loading: boolean; /** Number of times `reload()` has triggered a new request. */
+  reloadTimes: number; /** Current resolved data value. */
+  data: FaasData$1<PathOrData>; /** Last request error, if one occurred. */
+  error: any; /** Promise representing the latest request. */
   promise: Promise<Response<FaasData$1<PathOrData>>>;
   /**
    * Reloads data with new or existing parameters.
    *
-   * **Note**: It will sets skip to false before loading data.
+   * When the source hook is currently skipped, calling `reload` clears the skip
+   * flag before starting the next request.
    */
-  reload(params?: Record<string, any>): Promise<FaasData$1<PathOrData>>;
-  setData: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
-  setLoading: React.Dispatch<React.SetStateAction<boolean>>;
-  setPromise: React.Dispatch<React.SetStateAction<Promise<Response<FaasData$1<PathOrData>>>>>;
+  reload(params?: Record<string, any>): Promise<FaasData$1<PathOrData>>; /** Controlled or internal setter for the resolved data value. */
+  setData: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>; /** Setter for the loading flag. */
+  setLoading: React.Dispatch<React.SetStateAction<boolean>>; /** Setter for the latest request promise. */
+  setPromise: React.Dispatch<React.SetStateAction<Promise<Response<FaasData$1<PathOrData>>>>>; /** Setter for the last request error. */
   setError: React.Dispatch<React.SetStateAction<any>>;
 };
+/**
+ * Props for the {@link FaasDataWrapper} render-prop component.
+ *
+ * @template PathOrData - Action path or response data type used for inference.
+ */
 type FaasDataWrapperProps<PathOrData extends FaasActionUnionType$1> = {
-  render?(args: FaasDataInjection<PathOrData>): JSX.Element | JSX.Element[];
-  children?: React.ReactElement<Partial<FaasDataInjection<PathOrData>>>;
-  fallback?: JSX.Element | false;
-  action: FaasAction$1<PathOrData>;
-  params?: FaasParams$1<PathOrData>;
-  onDataChange?(args: FaasDataInjection<PathOrData>): void; /** use custom data, should work with setData */
-  data?: FaasData$1<PathOrData>; /** use custom setData, should work with data */
-  setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
-  baseUrl?: BaseUrl;
+  /** Render prop invoked with the resolved request state after the first load completes. */render?(args: FaasDataInjection<PathOrData>): JSX.Element | JSX.Element[]; /** Child element cloned with injected request state after the first load completes. */
+  children?: React.ReactElement<Partial<FaasDataInjection<PathOrData>>>; /** Element rendered before the first successful load. */
+  fallback?: JSX.Element | false; /** Action path to request. */
+  action: FaasAction$1<PathOrData>; /** Params sent to the action. */
+  params?: FaasParams$1<PathOrData>; /** Callback invoked whenever the resolved data value changes. */
+  onDataChange?(args: FaasDataInjection<PathOrData>): void; /** Controlled data value used instead of internal state. */
+  data?: FaasData$1<PathOrData>; /** Controlled setter used instead of internal state. */
+  setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>; /** Base URL override used for this wrapper instance. */
+  baseUrl?: BaseUrl; /** Imperative ref exposing the current injected request state. */
   ref?: React.Ref<FaasDataWrapperRef<PathOrData>>;
 };
+/**
+ * Imperative ref shape exposed by {@link FaasDataWrapper}.
+ *
+ * @template PathOrData - Action path or response data type used for inference.
+ */
 type FaasDataWrapperRef<PathOrData extends FaasActionUnionType$1 = any> = FaasDataInjection<PathOrData>;
+/**
+ * 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.
+ */
 declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType$1 = any>(props: FaasDataWrapperProps<PathOrData> & react.RefAttributes<FaasDataWrapperRef<PathOrData>>) => React.ReactElement | null;
 /**
- * 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 } },
+ * )
  * ```
  */
 declare function withFaasData<PathOrData extends FaasActionUnionType$1, TComponentProps extends Required<FaasDataInjection<PathOrData>> = Required<FaasDataInjection<PathOrData>>>(Component: React.FC<TComponentProps>, faasProps: FaasDataWrapperProps<PathOrData>): React.FC<Omit<TComponentProps, keyof FaasDataInjection<PathOrData>> & Record<string, any>>;
 //#endregion
 //#region src/useFaas.d.ts
 /**
- * Options for {@link useFaas}.
+ * Options that customize the {@link useFaas} request lifecycle.
+ *
+ * @template PathOrData - Action path or response data type used for inference.
  */
 type useFaasOptions<PathOrData extends FaasActionUnionType$1> = {
-  /** Override the request params without changing the hook's stored params state. */params?: FaasParams$1<PathOrData>; /** Controlled data value used instead of the hook's internal state. */
+  /** Override the current request params without changing the hook's stored params state. */params?: FaasParams$1<PathOrData>; /** Controlled data value used instead of the hook's internal state. */
   data?: FaasData$1<PathOrData>; /** Controlled setter that is called instead of the hook's internal `setData`. */
   setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
   /**
@@ -867,35 +1106,71 @@ type useFaasOptions<PathOrData extends FaasActionUnionType$1> = {
    *
    * However, you can still use reload to send the request.
    */
-  skip?: boolean | ((params: FaasParams$1<PathOrData>) => boolean); /** Send the last request after milliseconds */
+  skip?: boolean | ((params: FaasParams$1<PathOrData>) => boolean); /** Delay the latest automatic request by the given number of milliseconds. */
   debounce?: number; /** Override the default base URL for this hook instance. */
   baseUrl?: BaseUrl;
 };
 /**
  * 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>
  *
- *   return <h1>{data.title}</h1>
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         <div>Load failed: {error.message}</div>
+ *         <button type="button" onClick={() => reload()}>
+ *           Retry
+ *         </button>
+ *       </div>
+ *     )
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <span>{data.name}</span>
+ *       <button type="button" onClick={() => reload()}>
+ *         Refresh
+ *       </button>
+ *     </div>
+ *   )
  * }
  * ```
  */
 declare function useFaas<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, defaultParams: FaasParams$1<PathOrData>, options?: useFaasOptions<PathOrData>): FaasDataInjection<PathOrData>;
 //#endregion
 //#region src/client.d.ts
+/**
+ * Factory for per-request error handlers used by {@link FaasReactClient}.
+ *
+ * @param action - Action name that failed.
+ * @param params - Params sent with the failed request.
+ * @returns Async callback invoked with the resulting {@link ResponseError}.
+ */
 type OnError = (action: string, params: Record<string, any>) => (res: ResponseError) => Promise<void>;
 /**
  * Options for creating a {@link FaasReactClient} instance.
@@ -908,8 +1183,15 @@ type FaasReactClientOptions = {
    *
    * @example
    * ```ts
+   * import { ResponseError } from '@faasjs/react'
+   *
    * onError: (action, params) => async (res) => {
-   *   console.error(action, params, res)
+   *   if (res instanceof ResponseError) {
+   *     reportErrorToSentry(res, {
+   *       tags: { action },
+   *       extra: { params },
+   *     })
+   *   }
    * }
    * ```
    */
@@ -919,11 +1201,11 @@ type FaasReactClientOptions = {
  * Public interface returned by {@link FaasReactClient}.
  */
 type FaasReactClientInstance = {
-  id: string;
-  faas: typeof faas;
-  useFaas: typeof useFaas;
-  FaasDataWrapper: typeof FaasDataWrapper;
-  onError?: OnError;
+  /** Unique identifier inherited from the underlying browser client. */id: string; /** Promise-based request helper bound to the registered base URL. */
+  faas: typeof faas; /** Hook bound to the registered base URL. */
+  useFaas: typeof useFaas; /** Wrapper component bound to the registered base URL. */
+  FaasDataWrapper: typeof FaasDataWrapper; /** Optional error hook shared by `faas` and `useFaas`. */
+  onError?: OnError; /** Underlying browser client used for the actual HTTP requests. */
   browserClient: FaasBrowserClient;
 };
 /**
@@ -933,37 +1215,58 @@ type FaasReactClientInstance = {
  * 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 },
+ *       })
+ *     }
+ *   },
  * })
  * ```
  */
-declare function FaasReactClient({
-  baseUrl,
-  options: clientOptions,
-  onError
-}?: FaasReactClientOptions): FaasReactClientInstance;
+declare function FaasReactClient(options?: FaasReactClientOptions): FaasReactClientInstance;
 /**
  * Get a registered FaasReactClient instance.
  *
  * When `host` is omitted, the first registered client is returned. If no client
  * has been created yet, a default client is initialized automatically.
+ * Use `getClient` only for special cases such as multiple Faas clients with
+ * different base URLs. In normal single-client app code, prefer the default
+ * `faas`, `useFaas`, or `FaasReactClient` setup directly.
  *
  * @param 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 })
  * ```
  */
 declare function getClient(host?: string): FaasReactClientInstance;
@@ -971,28 +1274,91 @@ declare function getClient(host?: string): FaasReactClientInstance;
 //#region src/constant.d.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>
+ * }
+ * ```
  */
 declare function useConstant<T>(fn: () => T): T;
 //#endregion
 //#region src/ErrorBoundary.d.ts
+/**
+ * Props for the {@link ErrorBoundary} component.
+ */
 interface ErrorBoundaryProps {
+  /** Descendant elements protected by the boundary. */
   children?: ReactNode;
+  /** Callback invoked after a descendant throws during rendering or lifecycle work. */
   onError?: (error: Error | null, info: any) => void;
+  /** Custom fallback element cloned with captured error details. */
   errorChildren?: ReactElement<ErrorChildrenProps>;
 }
+/**
+ * Props injected into a custom error fallback element.
+ */
 type ErrorChildrenProps = {
-  error?: Error;
-  info?: any;
-  errorMessage?: string;
+  /** Captured error instance. */error?: Error; /** React component stack metadata for the captured error. */
+  info?: any; /** Stringified error message shown by the default fallback. */
+  errorMessage?: string; /** Component stack description shown by the default fallback. */
   errorDescription?: string;
 };
+/**
+ * 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>
+ * ```
+ */
 declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
   error: Error | null;
   info: ErrorInfo;
 }> {
+  /**
+   * Stable display name used by React DevTools.
+   */
   static displayName: string;
+  /**
+   * 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: ErrorBoundaryProps);
+  /**
+   * Capture rendering errors from descendant components.
+   *
+   * @param error - Caught render error.
+   * @param info - React component stack metadata.
+   */
   componentDidCatch(error: Error, info: ErrorInfo): void;
+  /**
+   * Render children or the configured fallback for the captured error.
+   */
   render(): string | number | bigint | boolean | react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
 }
 //#endregion
@@ -1007,6 +1373,14 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
  * @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
+ * ```
  */
 declare function equal(a: any, b: any): boolean;
 /**
@@ -1014,6 +1388,17 @@ declare function equal(a: any, b: any): boolean;
  *
  * @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>
+ * }
+ * ```
  */
 declare function useEqualMemoize(value: any): any;
 /**
@@ -1022,36 +1407,89 @@ declare function useEqualMemoize(value: any): any;
  * @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
+ * }
+ * ```
  */
 declare function useEqualEffect(callback: React.EffectCallback, dependencies: any[]): void;
 /**
  * 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>
+ * }
+ * ```
  */
 declare function useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
 /**
  * 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>
+ * }
+ * ```
  */
 declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
 //#endregion
 //#region src/OptionalWrapper.d.ts
+/**
+ * Props for the {@link OptionalWrapper} helper component.
+ *
+ * @template TWrapper - Wrapper component type used when `condition` is true.
+ */
 type OptionalWrapperProps<TWrapper extends ComponentType<{
   children: ReactNode;
 }> = any> = {
-  condition: boolean;
-  Wrapper: TWrapper;
-  wrapperProps?: ComponentProps<TWrapper>;
+  /** When `true`, render `children` inside `Wrapper`. */condition: boolean; /** Wrapper component used when `condition` passes. */
+  Wrapper: TWrapper; /** Props forwarded to `Wrapper` together with `children`. */
+  wrapperProps?: ComponentProps<TWrapper>; /** Content rendered directly or inside the wrapper. */
   children: ReactNode;
 };
 /**
- * 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
@@ -1068,21 +1506,22 @@ type OptionalWrapperProps<TWrapper extends ComponentType<{
  * )
  * ```
  */
-declare function OptionalWrapper({
-  condition,
-  Wrapper,
-  wrapperProps,
-  children
-}: OptionalWrapperProps): string | number | bigint | boolean | react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+declare function OptionalWrapper(props: OptionalWrapperProps): string | number | bigint | boolean | react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 declare namespace OptionalWrapper {
   var displayName: string;
 }
 //#endregion
 //#region src/splittingContext.d.ts
 /**
- * Creates a splitting context with the given default value.
+ * Create a context whose keys can be consumed independently.
  *
- * @param defaultValue The default value of the splitting context.
+ * `createSplittingContext` returns a `Provider` and a `use` hook. Each key in
+ * the provided shape is backed by a separate React context so readers only
+ * subscribe to the values they access.
+ *
+ * @template T - Context value shape exposed by the provider and hook.
+ * @param defaultValue - Default value map or key list used to create split contexts.
+ * @returns Provider and hook helpers for the split context.
  *
  * @example
  * ```tsx
@@ -1143,34 +1582,36 @@ declare function createSplittingContext<T extends Record<string, any>>(defaultVa
    * ```
    */
   Provider<NewT extends T = T>(this: void, props: {
-    value?: Partial<NewT>;
+    /** Partial context value supplied by the caller. */value?: Partial<NewT>; /** Descendant elements that should read from the split contexts. */
     children: ReactNode;
     /**
-     * Whether to use memoization for the children.
+     * Memoization mode for `children`.
      *
      * @default false
      *
-     * `true`: memoize the children without dependencies.
-     * `any[]`: memoize the children with specific dependencies.
+     * Pass `true` to memoize without dependencies or an array to control the
+     * deep-equality dependency list manually.
      */
     memo?: true | any[];
     /**
-     * An object containing initial values that will be automatically converted into state variables using {@link useSplittingState} hook. Each property will create both a state value and its setter following the pattern: value/setValue.
+     * Initial values converted into local state via `useSplittingState`.
+     *
+     * Each key produces both a state value and its matching setter using the
+     * `value` / `setValue` naming convention.
      *
      * @example
      * ```tsx
-     * <Provider
-     *  initializeStates={{
-     *    value: 0,
-     *  }}
-     * >
-     *   // Children will have access to: value, setValue
+     * <Provider initializeStates={{ value: 0 }}>
+     *   <Child />
      * </Provider>
+     *
+     * // `Child` can read `value` and `setValue`
+     * ```
      */
     initializeStates?: Partial<NewT>;
   }): ReactNode;
   /**
-   * The hook to use the splitting context.
+   * Hook used to read values from the splitting context.
    *
    * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#use
    *
@@ -1187,7 +1628,17 @@ declare function createSplittingContext<T extends Record<string, any>>(defaultVa
 };
 //#endregion
 //#region src/splittingState.d.ts
+/**
+ * Setter map generated by {@link useSplittingState} for each state key.
+ *
+ * @template T - Object shape whose keys receive generated setter functions.
+ */
 type StateSetters<T> = { [K in keyof T as K extends string ? K extends `${infer First}${infer Rest}` ? `set${Capitalize<First>}${Rest}` : never : never]: Dispatch<SetStateAction<T[K]>> };
+/**
+ * State object returned by {@link useSplittingState}, including generated setters.
+ *
+ * @template T - Object shape returned together with generated setter functions.
+ */
 type StatesWithSetters<T> = T & StateSetters<T>;
 /**
  * Create local state entries and matching setters for each key in an object.
@@ -1209,10 +1660,10 @@ declare function useSplittingState<T extends Record<string, unknown>>(initialSta
 //#endregion
 //#region src/useFaasStream.d.ts
 /**
- * Options for {@link useFaasStream}.
+ * Options that customize the {@link useFaasStream} request lifecycle.
  */
 type UseFaasStreamOptions = {
-  /** Override the request params without changing the hook's stored params state. */params?: Record<string, any>; /** Controlled stream text used instead of the hook's internal state. */
+  /** Override the current request params without changing the hook's stored params state. */params?: Record<string, any>; /** Controlled stream text used instead of the hook's internal state. */
   data?: string; /** Controlled setter that is called instead of the hook's internal `setData`. */
   setData?: React.Dispatch<React.SetStateAction<string>>;
   /**
@@ -1220,7 +1671,7 @@ type UseFaasStreamOptions = {
    *
    * However, you can still use reload to send the request.
    */
-  skip?: boolean | ((params: Record<string, any>) => boolean); /** Send the last request after milliseconds */
+  skip?: boolean | ((params: Record<string, any>) => boolean); /** Delay the latest automatic request by the given number of milliseconds. */
   debounce?: number; /** Override the default base URL for this hook instance. */
   baseUrl?: BaseUrl;
 };
@@ -1228,44 +1679,56 @@ type UseFaasStreamOptions = {
  * Result returned by {@link useFaasStream}.
  */
 type UseFaasStreamResult = {
-  action: string;
-  params: Record<string, any>;
-  loading: boolean;
-  reloadTimes: number;
-  data: string;
-  error: any;
-  reload: (params?: Record<string, any>) => Promise<string>;
-  setData: React.Dispatch<React.SetStateAction<string>>;
-  setLoading: React.Dispatch<React.SetStateAction<boolean>>;
+  /** Action path currently associated with the stream request. */action: string; /** Params used for the most recent request attempt. */
+  params: Record<string, any>; /** Whether the hook is currently waiting for stream data. */
+  loading: boolean; /** Number of times `reload()` has triggered a new request. */
+  reloadTimes: number; /** Accumulated text decoded from the stream response. */
+  data: string; /** Last error raised while opening or consuming the stream. */
+  error: any; /** Trigger a new streaming request with optional params. */
+  reload: (params?: Record<string, any>) => Promise<string>; /** Controlled or internal setter for the accumulated text. */
+  setData: React.Dispatch<React.SetStateAction<string>>; /** Setter for the loading flag. */
+  setLoading: React.Dispatch<React.SetStateAction<boolean>>; /** Setter for the last stream error. */
   setError: React.Dispatch<React.SetStateAction<any>>;
 };
 /**
  * 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>
  * }
  * ```
  */
@@ -1278,6 +1741,17 @@ declare function useFaasStream(action: string, defaultParams: Record<string, any
  * @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>
+ * }
+ * ```
  */
 declare function usePrevious<T = any>(value: T): T | undefined;
 //#endregion