@faasjs/react 8.0.0-beta.2 → 8.0.0-beta.21

package/dist/index.d.ts

@@ -1,191 +1,1366 @@
-import { Response, BaseUrl, Options, ResponseError, FaasBrowserClient } from '@faasjs/browser';
-export { Options, Response, ResponseError, ResponseHeaders } from '@faasjs/browser';
-import { FaasActionUnionType, FaasAction, FaasParams, FaasData } from '@faasjs/types';
-export { FaasAction, FaasActionUnionType, FaasData, FaasParams } from '@faasjs/types';
-import * as react from 'react';
-import { JSX, Component, ReactNode, ReactElement, ComponentType, JSXElementConstructor, ComponentProps, Dispatch, SetStateAction, RefObject } from 'react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _$react from "react";
+import { Component, ComponentProps, ComponentType, Dispatch, ErrorInfo, JSX, ReactElement, ReactNode, RefObject, SetStateAction } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { FaasAction, FaasAction as FaasAction$1, FaasActionUnionType, FaasActionUnionType as FaasActionUnionType$1, FaasData, FaasData as FaasData$1, FaasParams, FaasParams as FaasParams$1 } from "@faasjs/types";
 
+//#region src/generateId.d.ts
 /**
- * Injects FaasData props.
+ * Generate a random identifier with an optional prefix.
+ *
+ * @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
+ * const id = generateId('prefix-')
+ *
+ * id.startsWith('prefix-') // true
+ * ```
  */
-type FaasDataInjection<PathOrData extends FaasActionUnionType = any> = {
-    action: FaasAction<PathOrData>;
-    params: FaasParams<PathOrData>;
-    loading: boolean;
-    reloadTimes: number;
-    data: FaasData<PathOrData>;
-    error: any;
-    promise: Promise<Response<FaasData<PathOrData>>>;
-    /**
-     * Reloads data with new or existing parameters.
-     *
-     * **Note**: It will sets skip to false before loading data.
-     */
-    reload(params?: Record<string, any>): Promise<FaasData<PathOrData>>;
-    setData: React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>;
-    setLoading: React.Dispatch<React.SetStateAction<boolean>>;
-    setPromise: React.Dispatch<React.SetStateAction<Promise<Response<FaasData<PathOrData>>>>>;
-    setError: React.Dispatch<React.SetStateAction<any>>;
+declare function generateId(prefix?: string, length?: number): string;
+//#endregion
+//#region src/browser.d.ts
+/**
+ * Template literal type for URL strings that must end with a forward slash.
+ *
+ * Ensures that base URLs used in FaasJS requests always have a trailing '/' character,
+ * which is required for proper URL construction when appending action paths.
+ *
+ * Notes:
+ * - Type only accepts strings ending with '/' (e.g., 'https://api.example.com/', '/')
+ * - Strings without trailing '/' will fail TypeScript type checking
+ * - Used by FaasBrowserClient constructor and Options type
+ * - Ensures consistent URL formatting across the codebase
+ * - Throws Error at runtime if baseUrl doesn't end with '/'
+ *
+ * @see FaasBrowserClient for usage in client creation
+ * @see Options for usage in request options
+ */
+type BaseUrl = `${string}/`;
+/**
+ * Configuration options for FaasJS requests.
+ *
+ * Extends the standard RequestInit interface with FaasJS-specific options for
+ * customizing request behavior, adding request hooks, and overriding defaults.
+ *
+ * Notes:
+ * - Options can be provided at client creation (defaultOptions) or per-request
+ * - Per-request options override client default options
+ * - headers are merged: per-request headers override default headers
+ * - beforeRequest hook is called before the request is sent, allowing modification
+ * - Custom request function completely replaces the default fetch implementation
+ * - baseUrl in options overrides the client's baseUrl for this specific request
+ * - When stream is true, returns the native fetch Response instead of wrapped Response
+ *
+ * @property {Record<string, string>} [headers] - Default headers to include in all requests.
+ *   Merged with client default headers, with per-request headers taking precedence.
+ *   Common headers include Content-Type, Authorization, and custom application headers.
+ *
+ * @property {Function} [beforeRequest] - Async hook called before sending each request.
+ *   Receives action, params, options, and headers, allowing modification before the request is sent.
+ *   Useful for logging, authentication, adding timestamps, or modifying headers dynamically.
+ *   Any changes to the headers object will affect the actual request.
+ *
+ * @property {Function} [request] - Custom request function to replace the default fetch.
+ *   Allows using alternative HTTP clients like axios, XMLHttpRequest, or custom implementations.
+ *   Receives the URL and parsed options, must return a Promise resolving to a Response object.
+ *   When provided, this function is used instead of the native fetch API.
+ *
+ * @property {BaseUrl} [baseUrl] - Optional override for the base URL for this specific request.
+ *   If provided, overrides the client's baseUrl. Must end with '/'.
+ *   Useful for making requests to different endpoints or environments from the same client instance.
+ *
+ * @property {boolean} [stream] - Enable streaming mode for large responses.
+ *   When true, returns the raw fetch Response object instead of a wrapped Response.
+ *   Useful for processing large data incrementally or working with binary data streams.
+ *   When false or undefined, returns a wrapped Response with automatic JSON parsing.
+ *
+ * @augments RequestInit
+ * @see FaasBrowserClient for client creation
+ * @see Response for response object structure
+ */
+type Options = RequestInit & {
+  headers?: Record<string, string>; /** Async hook called after request options are merged but before the request is sent. */
+  beforeRequest?: ({
+    action,
+    params,
+    options,
+    headers
+  }: {
+    action: string;
+    params?: Record<string, any> | undefined;
+    options: Options;
+    headers: Record<string, string>;
+  }) => 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;
+};
+/**
+ * Simple key-value object for HTTP response headers.
+ *
+ * Represents headers as a plain object with string keys and string values.
+ * Used by Response, ResponseError, and Options types.
+ *
+ * @property {string} [key] - Dynamic string keys for header names (e.g., 'Content-Type', 'Authorization').
+ *   Values must be strings. Multiple values for the same key are not supported.
+ *
+ * Notes:
+ * - Headers are case-insensitive in HTTP but stored with exact casing in this object
+ * - Common headers include: Content-Type, Authorization, X-Request-Id, X-Custom-Header
+ * - No support for multi-value headers (use comma-separated values instead)
+ * - Used in Response, ResponseError, and Options types
+ * - Simplified model compared to browser's Headers interface (no .get(), .set() methods)
+ *
+ * @see Response for usage in response objects
+ * @see ResponseError for usage in error objects
+ * @see Options for usage in request options
+ */
+type ResponseHeaders = {
+  [key: string]: string;
 };
-type FaasDataWrapperProps<PathOrData extends FaasActionUnionType> = {
-    render?(args: FaasDataInjection<PathOrData>): JSX.Element | JSX.Element[];
-    children?: React.ReactElement<Partial<FaasDataInjection<PathOrData>>>;
-    fallback?: JSX.Element | false;
-    action: FaasAction<PathOrData>;
-    params?: FaasParams<PathOrData>;
-    onDataChange?(args: FaasDataInjection<PathOrData>): void;
-    /** use custom data, should work with setData */
-    data?: FaasData<PathOrData>;
-    /** use custom setData, should work with data */
-    setData?: React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>;
-    baseUrl?: BaseUrl;
-    ref?: React.Ref<FaasDataWrapperRef<PathOrData>>;
+/**
+ * Type definition for the FaasBrowserClient.action method.
+ *
+ * Defines the signature of the method used to make requests to FaasJS functions.
+ * Provides type-safe parameter and return value handling.
+ *
+ * @template PathOrData - The function path or data type for type safety
+ *
+ * @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:
+ * - Used internally by FaasBrowserClient.action method
+ * - Provides type-safe action method signature
+ * - Return type includes both typed and untyped Response variants
+ * - Params are optional and can be undefined
+ * - Options override client defaults when provided
+ *
+ * @see FaasBrowserClient for the class that uses this type
+ * @see Response for the return type
+ * @see Options for the options parameter type
+ */
+type FaasBrowserClientAction = <PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params?: FaasParams$1<PathOrData>, options?: Options) => Promise<Response<FaasData$1<PathOrData>> | Response>;
+/**
+ * Properties for creating a Response object.
+ *
+ * Defines the structure of response data that can be passed to the Response constructor
+ * or returned from mock handlers.
+ *
+ * @template T - The type of the data property for type-safe response creation
+ *
+ * @property {number} [status] - The HTTP status code for the response.
+ *   Optional: defaults to 200 if data or body is provided, 204 otherwise.
+ *
+ * @property {ResponseHeaders} [headers] - The response headers as a key-value object.
+ *   Optional: defaults to an empty object if not provided.
+ *
+ * @property {any} [body] - The raw response body as a string or object.
+ *   Optional: if not provided, body is automatically populated from data using JSON.stringify.
+ *
+ * @property {T} [data] - The parsed JSON data to include in the response.
+ *   Optional: contains the response payload when JSON data is provided.
+ *
+ * Notes:
+ * - All properties are optional
+ * - At least one of data or body should be provided for meaningful responses
+ * - The Response class automatically defaults status to 200 or 204 based on content
+ * - If data is provided without body, body is automatically JSON.stringify(data)
+ * - Used by Response constructor and mock handlers
+ *
+ * @see Response for the class that uses these properties
+ * @see ResponseErrorProps for error response properties
+ */
+type ResponseProps<T = any> = {
+  status?: number;
+  headers?: ResponseHeaders;
+  body?: any;
+  data?: T;
 };
-type FaasDataWrapperRef<PathOrData extends FaasActionUnionType = any> = FaasDataInjection<PathOrData>;
-declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType = any>(props: FaasDataWrapperProps<PathOrData> & react.RefAttributes<FaasDataWrapperRef<PathOrData>>) => React.ReactElement | null;
 /**
- * HOC to wrap a component with FaasDataWrapper
+ * Wrapper class for HTTP responses from FaasJS functions.
+ *
+ * Provides a consistent interface for handling server responses with status code, headers,
+ * body, and parsed data. Automatically handles JSON serialization and status code defaults.
+ *
+ * @template T - The type of the data property for type-safe response handling
+ *
+ * @property {number} status - The HTTP status code of the response.
+ *   Defaults to 200 if data or body is provided, 204 if neither is present.
+ * @property {ResponseHeaders} headers - The response headers as a key-value object.
+ *   Empty object if no headers were provided.
+ * @property {any} body - The raw response body as a string or object.
+ *   If data is provided without body, body is automatically set to JSON.stringify(data).
+ * @property {T} [data] - The parsed JSON data from the response.
+ *   Optional property that contains the response payload when JSON is provided.
+ *
+ * Notes:
+ * - status defaults to 200 if data or body is present, 204 otherwise
+ * - body is automatically populated from data if not explicitly provided
+ * - headers defaults to an empty object if not provided
+ * - Use generic type parameter T for type-safe data access
+ * - Commonly used as the return type from client.action() method
+ * - Can be used in mock handlers to return structured responses
+ * - The data property is optional and may be undefined for responses without data
+ *
+ * @example Create successful response with data
+ * ```ts
+ * const response = new Response({
+ *   status: 200,
+ *   data: {
+ *     id: 123,
+ *     name: 'John Doe'
+ *   }
+ * })
+ * console.log(response.status) // 200
+ * console.log(response.data.name) // 'John Doe'
+ * ```
+ *
+ * @example Create response with type safety
+ * ```ts
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
+ * }
+ *
+ * const response = new Response<User>({
+ *   data: {
+ *     id: 123,
+ *     name: 'John',
+ *     email: 'john@example.com'
+ *   }
+ * })
+ * // TypeScript knows response.data.name is a string
+ * ```
+ *
+ * @example Create response with headers
+ * ```ts
+ * const response = new Response({
+ *   status: 201,
+ *   data: { created: true },
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *     'X-Request-Id': 'req-123',
+ *     'X-Cache-Key': 'user-123'
+ *   }
+ * })
+ * ```
+ *
+ * @example Create response with custom body
+ * ```ts
+ * const response = new Response({
+ *   status: 200,
+ *   body: JSON.stringify({ custom: 'format' }),
+ *   headers: { 'Content-Type': 'application/json' }
+ * })
+ * ```
+ *
+ * @example Create empty response (204 No Content)
+ * ```ts
+ * const response = new Response()
+ * // status: 204, headers: {}, body: undefined, data: undefined
+ * ```
+ *
+ * @example Create error response
+ * ```ts
+ * const response = new Response({
+ *   status: 404,
+ *   data: {
+ *     error: {
+ *       message: 'User not found',
+ *       code: 'USER_NOT_FOUND'
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example Use in mock handler
+ * ```ts
+ * setMock(async (action, params) => {
+ *   if (action === 'user') {
+ *     return new Response({
+ *       status: 200,
+ *       data: { id: params.id, name: 'Mock User' }
+ *     })
+ *   }
+ *   return new Response({ status: 404, data: { error: 'Not found' } })
+ * })
+ * ```
+ *
+ * @see ResponseProps for response property type
+ * @see ResponseError for error response handling
+ * @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 = {
+  /** 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;
+};
+/**
+ * Custom error class for handling HTTP response errors from FaasJS requests.
+ *
+ * Extends the built-in Error class to provide additional information about failed requests,
+ * including HTTP status code, response headers, response body, and the original error.
+ *
+ * @augments Error
+ *
+ * @property {number} status - The HTTP status code of the failed response. Defaults to 500 if not provided.
+ * @property {ResponseHeaders} headers - The response headers from the failed request.
+ * @property {any} body - The response body containing error details or the original error if available.
+ * @property {Error} [originalError] - The original Error object if this ResponseError was created from another Error.
+ *
+ * @example Basic error with message
+ * ```ts
+ * throw new ResponseError('User not found')
+ * // or inside action method:
+ * catch (error) {
+ *   throw new ResponseError(error.message)
+ * }
+ * ```
+ *
+ * @example Error from existing Error
+ * ```ts
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   throw new ResponseError(error, {
+ *     status: 500,
+ *     headers: { 'X-Error-Type': 'internal' }
+ *   })
+ * }
+ * ```
+ *
+ * @example Error with complete response details
+ * ```ts
+ * throw new ResponseError({
+ *   message: 'Validation failed',
+ *   status: 400,
+ *   headers: { 'X-Error-Code': 'VALIDATION_ERROR' },
+ *   body: {
+ *     error: {
+ *       message: 'Validation failed',
+ *       fields: ['email', 'password']
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example Handling ResponseError in client
+ * ```ts
+ * try {
+ *   const response = await client.action('user', { id: 123 })
+ *   console.log(response.data)
+ * } catch (error) {
+ *   if (error instanceof ResponseError) {
+ *     console.error(`Request failed: ${error.message}`)
+ *     console.error(`Status: ${error.status}`)
+ *     if (error.body) {
+ *       console.error('Error details:', error.body)
+ *     }
+ *     if (error.headers['X-Request-Id']) {
+ *       console.error('Request ID:', error.headers['X-Request-Id'])
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Throwing ResponseError from mock
+ * ```ts
+ * setMock(async (action, params) => {
+ *   if (action === 'login') {
+ *     if (!params.email || !params.password) {
+ *       throw new ResponseError({
+ *         message: 'Email and password are required',
+ *         status: 400,
+ *         body: { error: 'missing_fields' }
+ *       })
+ *     }
+ *     return { data: { token: 'abc123' } }
+ *   }
+ * })
+ * ```
+ *
+ * Notes:
+ * - ResponseError is automatically thrown by the action method when the server returns an error (status >= 400)
+ * - The error message from server responses is extracted from body.error.message if available
+ * - When created from an Error object, the original error is preserved in the originalError property
+ * - The status property defaults to 500 if not explicitly provided
+ * - Use instanceof ResponseError to distinguish FaasJS errors from other JavaScript errors
+ * - The body property can contain structured error information from the server response
+ *
+ * @see FaasBrowserClient.action for how ResponseError is thrown in requests
+ * @see ResponseProps for the structure of response data
+ * @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;
+  /**
+   * 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.
+ *
+ * Defines the signature for functions that can mock API requests during testing.
+ * Mock handlers receive request parameters and return simulated responses or errors.
+ *
+ * @param action - The function path/action being requested (for example, `user` or `data/list`).
+ *   Converted to lowercase by the client before being passed to the handler.
+ *
+ * @param params - The parameters passed to the action.
+ *   May be undefined if the action was called without parameters.
+ *   Parameters are passed as a plain object (already JSON-serialized if needed).
+ *
+ * @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)
+ *   - void: Returns an empty response (204 No Content)
+ *   - Error: Throws ResponseError when returning an Error object
+ *
+ * Notes:
+ * - Used by setMock() function to mock API calls during tests
+ * - Affects all FaasBrowserClient instances when set globally
+ * - Can return different responses based on action or params
+ * - Returning an Error object causes the action() method to reject with ResponseError
+ * - Async function - must return a Promise
+ * - Receives the fully merged options including default headers
+ *
+ * @example Basic mock returning data
+ * ```ts
+ * setMock(async (action, params, options) => {
+ *   if (action === 'user') {
+ *     return {
+ *       status: 200,
+ *       data: { id: params.id, name: 'Mock User' }
+ *     }
+ *   }
+ *   return { status: 404, data: { error: 'Not found' } }
+ * })
+ * ```
+ *
+ * @example Conditional mock based on parameters
+ * ```ts
+ * setMock(async (action, params) => {
+ *   if (action === 'login') {
+ *     if (params.email === 'admin@example.com' && params.password === 'admin') {
+ *       return { data: { token: 'admin-token', role: 'admin' } }
+ *     }
+ *     return { status: 401, data: { error: 'Invalid credentials' } }
+ *   }
+ * })
+ * ```
+ *
+ * @example Throwing error from mock
+ * ```ts
+ * setMock(async (action) => {
+ *   if (action === 'protected') {
+ *     return new Error('Unauthorized access')
+ *     // This will be wrapped in ResponseError and thrown
+ *   }
+ * })
+ * ```
+ *
+ * @example Returning void for empty response
+ * ```ts
+ * setMock(async (action) => {
+ *   if (action === 'delete') {
+ *     // Return void for 204 No Content
+ *     return
+ *   }
+ *   return { data: { success: true } }
+ * })
+ * ```
+ *
+ * @see setMock for setting up mock handlers
+ * @see ResponseProps for response structure
+ * @see ResponseError for error handling
+ */
+type MockHandler = (action: string, params: Record<string, any> | undefined, options: Options) => Promise<ResponseProps> | Promise<void> | Promise<Error>;
+/**
+ * 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
+ *   - ResponseProps object: static response data
+ *   - 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) => {
+ *   if (action === '/pages/users/get') {
+ *     return { data: { id: 1, name: 'FaasJS' } }
+ *   }
+ *
+ *   return { status: 404, data: { message: 'Not Found' } }
+ * })
+ *
+ * const response = await client.action('/pages/users/get')
+ * ```
+ *
+ * @example Branch by action and params
+ * ```ts
+ * 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' } }
+ * })
+ * ```
+ *
+ * @example Use Response instance
+ * ```ts
+ * setMock(new Response({
+ *   status: 200,
+ *   data: { result: 'success' }
+ * }))
+ * ```
+ *
+ * @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)
+ * ```
+ *
+ * @example Handle errors
+ * ```ts
+ * setMock(async () => {
+ *   throw new Error('Internal error')
+ * })
+ * // This will reject with ResponseError
+ * ```
+ */
+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.
+ *
+ * @template PathOrData - Type parameter extending FaasActionUnionType for type-safe requests
+ *
+ * Features:
+ * - Type-safe API requests with TypeScript support
+ * - Built-in mock support for testing
+ * - Custom request function support
+ * - Request/response hooks (beforeRequest)
+ * - Automatic error handling with ResponseError
+ * - Streaming support for large responses
+ * - Multiple instance support with unique IDs
+ *
+ * Notes:
+ * - All requests are POST requests by default
+ * - Automatically adds X-FaasJS-Request-Id header for request tracking
+ * - baseUrl must end with '/' (will throw Error if not)
+ * - Supports global mock via setMock() for testing all instances
+ *
+ * @example Basic usage
+ * ```ts
+ * import { FaasBrowserClient } from '@faasjs/react'
+ *
+ * const client = new FaasBrowserClient('http://localhost:8080/')
+ * const response = await client.action('func', { key: 'value' })
+ * console.log(response.data)
+ * ```
+ *
+ * @example With custom headers and options
+ * ```ts
+ * const client = new FaasBrowserClient('https://api.example.com/', {
+ *   headers: { 'X-API-Key': 'secret' },
+ *   beforeRequest: async ({ action, params, headers }) => {
+ *     console.log(`Calling ${action} with params:`, params)
+ *   }
+ * })
+ * ```
+ *
+ * @example Multiple instances
+ * ```ts
+ * const apiClient = new FaasBrowserClient('https://api.example.com/')
+ * const localClient = new FaasBrowserClient('http://localhost:3000/')
+ *
+ * const apiData = await apiClient.action('users')
+ * const localData = await localClient.action('data')
+ * ```
+ *
+ * @example Error handling
+ * ```ts
+ * const client = new FaasBrowserClient('https://api.example.com/')
+ *
+ * try {
+ *   const response = await client.action('user', { id: 123 })
+ *   console.log(response.data)
+ * } catch (error) {
+ *   if (error instanceof ResponseError) {
+ *     console.error(`Request failed: ${error.message}`, error.status)
+ *   } else {
+ *     console.error('Unexpected error:', error)
+ *   }
+ * }
+ * ```
+ *
+ * @throws {Error} When baseUrl does not end with '/'
+ *
+ * @see setMock for testing support
+ * @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
+   * const client = new FaasBrowserClient('/')
+   * ```
+   *
+   * @example With API endpoint
+   * ```ts
+   * const client = new FaasBrowserClient('https://api.example.com/')
+   * ```
+   *
+   * @example With custom headers
+   * ```ts
+   * const client = new FaasBrowserClient('https://api.example.com/', {
+   *   headers: {
+   *     'Authorization': 'Bearer token123',
+   *     'X-Custom-Header': 'value'
+   *   }
+   * })
+   * ```
+   *
+   * @example With beforeRequest hook
+   * ```ts
+   * const client = new FaasBrowserClient('https://api.example.com/', {
+   *   beforeRequest: async ({ action, params, headers }) => {
+   *     console.log(`Requesting ${action}`, params)
+   *     // Modify headers before request
+   *     headers['X-Timestamp'] = Date.now().toString()
+   *   }
+   * })
+   * ```
+   *
+   * @example With custom request function
+   * ```ts
+   * import axios from 'axios'
+   *
+   * const client = new FaasBrowserClient('/', {
+   *   request: async (url, options) => {
+   *     const response = await axios.post(url, options.body, {
+   *       headers: options.headers
+   *     })
+   *     return new Response({
+   *       status: response.status,
+   *       headers: response.headers,
+   *       data: response.data
+   *     })
+   *   }
+   * })
+   * ```
+   *
+   * @throws {Error} When `baseUrl` does not end with `/`
+   */
+  constructor(baseUrl?: BaseUrl, options?: Options);
+  /**
+   * Makes a request to a FaasJS function.
+   *
+   * @template PathOrData - The function path or data type for type safety
+   * @param action - The function path to call. Converted to lowercase when constructing the URL.
+   *   Must be a non-empty string.
+   * @param params - The parameters to send to the function. Will be serialized as JSON.
+   *   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 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)
+   * @throws {Error} When the request fails before a response is received
+   *
+   * Notes:
+   * - All requests are POST requests by default
+   * - Action path is automatically converted to lowercase
+   * - A unique request ID is generated for each request and sent in X-FaasJS-Request-Id header
+   * - Headers are merged from client defaults and request options (request options take precedence)
+   * - If a global mock is set via setMock(), it will be used instead of making real requests
+   * - If a custom request function is provided in options, it will be used instead of fetch
+   * - When stream option is true, returns the native fetch Response instead of a wrapped Response
+   * - Response body is automatically parsed as JSON when possible
+   * - Server errors (body.error) are automatically converted to ResponseError
+   *
+   * @example Basic request
+   * ```ts
+   * const response = await client.action('user', { id: 123 })
+   * console.log(response.data)
+   * ```
+   *
+   * @example With no parameters
+   * ```ts
+   * const response = await client.action('status')
+   * console.log(response.data.status)
+   * ```
+   *
+   * @example With custom options
+   * ```ts
+   * const response = await client.action('data', {
+   *   limit: 10,
+   *   offset: 0
+   * }, {
+   *   headers: { 'X-Custom-Header': 'value' }
+   * })
+   * ```
+   *
+   * @example Streaming large response
+   * ```ts
+   * const response = await client.action('stream', {
+   *   format: 'json'
+   * }, {
+   *   stream: true
+   * })
+   * // response is native fetch Response with streaming support
+   * const reader = response.body.getReader()
+   * ```
+   *
+   * @example With type safety
+   * ```ts
+   * interface UserData {
+   *   id: number
+   *   name: string
+   *   email: string
+   * }
+   *
+   * const response = await client.action<UserData>('user', { id: 123 })
+   * console.log(response.data.name) // TypeScript knows it's a string
+   * ```
+   *
+   * @example Handling errors
+   * ```ts
+   * try {
+   *   const response = await client.action('user', { id: 123 })
+   *   console.log(response.data)
+   * } catch (error) {
+   *   if (error instanceof ResponseError) {
+   *     console.error(`Server error: ${error.message}`, error.status)
+   *     if (error.body) console.error('Error details:', error.body)
+   *   } else {
+   *     console.error('Network error:', error)
+   *   }
+   * }
+   * ```
+   *
+   * @example Chaining requests
+   * ```ts
+   * const userId = await client.action('createUser', {
+   *   name: 'John',
+   *   email: 'john@example.com'
+   * })
+   *
+   * const profile = await client.action('getProfile', {
+   *   userId: userId.data.id
+   * })
+   * ```
+   */
+  action<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params?: FaasParams$1<PathOrData>, options?: Options): Promise<Response<FaasData$1<PathOrData>>>;
+}
+//#endregion
+//#region src/faas.d.ts
+/**
+ * Call the currently configured FaasReactClient.
+ *
+ * This helper forwards the request to `getClient`. When the registered
+ * client defines `onError`, the hook is invoked before the promise rejects.
+ *
+ * @template 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('posts/get', { id: 1 })
+ *
+ * console.log(response.data.title)
+ * ```
+ */
+declare function faas<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params: FaasParams$1<PathOrData>, options?: Options): Promise<Response<FaasData$1<PathOrData>>>;
+//#endregion
+//#region src/FaasDataWrapper.d.ts
+/**
+ * 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 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.
+   *
+   * 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>>; /** 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 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
- * const MyComponent = withFaasData(({ data }) => <div>{data.name}</div>, { action: 'test', params: { a: 1 } })
+ * 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 function withFaasData<PathOrData extends FaasActionUnionType, 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>>;
-
+declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType$1 = any>(props: FaasDataWrapperProps<PathOrData> & _$react.RefAttributes<FaasDataWrapperRef<PathOrData>>) => React.ReactElement | null;
 /**
- * Request faas server
+ * Wrap a component with {@link FaasDataWrapper} and inject Faas request state as props.
  *
- * @param action {string} action name
- * @param params {object} action params
- * @returns {Promise<Response<any>>}
+ * `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
- * ```ts
- * faas<{ title: string }>('post/get', { id: 1 }).then(res => {
- *   console.log(res.data.title)
- * })
+ * ```tsx
+ * import { withFaasData } from '@faasjs/react'
+ *
+ * const MyComponent = withFaasData(
+ *   ({ data, error, reload }) => {
+ *     if (error) {
+ *       return (
+ *         <button type="button" onClick={() => reload()}>
+ *           Retry
+ *         </button>
+ *       )
+ *     }
+ *
+ *     return <div>{data.name}</div>
+ *   },
+ *   { action: '/pages/users/get', params: { id: 1 } },
+ * )
  * ```
  */
-declare function faas<PathOrData extends FaasActionUnionType>(action: FaasAction<PathOrData>, params: FaasParams<PathOrData>, options?: Options): Promise<Response<FaasData<PathOrData>>>;
-
-type useFaasOptions<PathOrData extends FaasActionUnionType> = {
-    params?: FaasParams<PathOrData>;
-    data?: FaasData<PathOrData>;
-    setData?: React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>;
-    /**
-     * If skip is true, the request will not be sent.
-     *
-     * However, you can still use reload to send the request.
-     */
-    skip?: boolean | ((params: FaasParams<PathOrData>) => boolean);
-    /** Send the last request after milliseconds */
-    debounce?: number;
-    baseUrl?: BaseUrl;
+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/useFaasRequest.d.ts
+type SharedUseFaasOptions<Params, Data> = {
+  params?: Params;
+  data?: Data;
+  setData?: React.Dispatch<React.SetStateAction<Data>>;
+  skip?: boolean | ((params: Params) => boolean);
+  debounce?: number;
+  baseUrl?: BaseUrl;
 };
+//#endregion
+//#region src/useFaas.d.ts
+/**
+ * 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> = SharedUseFaasOptions<FaasParams$1<PathOrData>, FaasData$1<PathOrData>>;
 /**
- * Request faas server with React hook
+ * Request FaasJS data and keep request state in React state.
+ *
+ * `useFaas` is the default hook for standard FaasJS request-response flows in React.
+ * It sends an initial request unless `skip` is enabled, and returns request state
+ * plus helpers for reloading, updating data, and handling errors.
+ *
+ * @template PathOrData - Action path or response data type used for inference.
  *
- * @param action {string} action name
- * @param defaultParams {object} initial action params
- * @returns {FaasDataInjection<any>}
+ * @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.
+ * @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
- * function Post ({ id }) {
- *   const { data } = useFaas<{ title: string }>('post/get', { id })
- *   return <h1>{data.title}</h1>
+ * import { useFaas } from '@faasjs/react'
+ *
+ * function Profile({ id }: { id: number }) {
+ *   const { data, error, loading, reload } = useFaas('/pages/users/get', { id })
+ *
+ *   if (loading) return <div>Loading...</div>
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         <div>Load failed: {error.message}</div>
+ *         <button type="button" onClick={() => reload()}>
+ *           Retry
+ *         </button>
+ *       </div>
+ *     )
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <span>{data.name}</span>
+ *       <button type="button" onClick={() => reload()}>
+ *         Refresh
+ *       </button>
+ *     </div>
+ *   )
  * }
  * ```
  */
-declare function useFaas<PathOrData extends FaasActionUnionType>(action: FaasAction<PathOrData>, defaultParams: FaasParams<PathOrData>, options?: useFaasOptions<PathOrData>): FaasDataInjection<PathOrData>;
-
+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.
+ */
 type FaasReactClientOptions = {
-    /** @default `/` */
-    baseUrl?: BaseUrl;
-    options?: Options;
-    /**
-     * @example
-     * ```ts
-     * onError: (action, params) => async (res) => {
-     *   console.error(action, params, res)
-     * }
-     * ```
-     */
-    onError?: OnError;
+  /** @default `/` */baseUrl?: BaseUrl; /** Default request options forwarded to the underlying browser client. */
+  options?: Options;
+  /**
+   * Error hook invoked when `faas` or `useFaas` receives a failed response.
+   *
+   * @example
+   * ```ts
+   * import { ResponseError } from '@faasjs/react'
+   *
+   * onError: (action, params) => async (res) => {
+   *   if (res instanceof ResponseError) {
+   *     reportErrorToSentry(res, {
+   *       tags: { action },
+   *       extra: { params },
+   *     })
+   *   }
+   * }
+   * ```
+   */
+  onError?: OnError;
 };
+/**
+ * Public interface returned by {@link FaasReactClient}.
+ */
 type FaasReactClientInstance = {
-    id: string;
-    faas: typeof faas;
-    useFaas: typeof useFaas;
-    FaasDataWrapper: typeof FaasDataWrapper;
-    onError?: OnError;
-    browserClient: FaasBrowserClient;
+  /** 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;
 };
 /**
- * Before use faas, you should initialize a FaasReactClient.
+ * Create and register a FaasReactClient instance.
  *
- * @param props.baseUrl {string} The baseUrl of your faas server
- * @param props.options {Options} The options of client
- * @returns {FaasReactClientInstance}
+ * The returned client is stored by `baseUrl` and becomes the default client
+ * 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, ResponseError } from '@faasjs/react'
+ *
  * const client = FaasReactClient({
- *   baseUrl: 'localhost:8080/api/'
+ *   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, onError }?: FaasReactClientOptions): FaasReactClientInstance;
+declare function FaasReactClient(options?: FaasReactClientOptions): FaasReactClientInstance;
 /**
- * Get FaasReactClient instance
+ * Get a registered FaasReactClient instance.
  *
- * @param host {string} empty string for default host
- * @returns {FaasReactClientInstance}
+ * 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
- * getClient()
- * // or
- * getClient('another-host')
+ * import { FaasReactClient, getClient } from '@faasjs/react'
+ *
+ * FaasReactClient({
+ *   baseUrl: 'https://service-a.example.com/api/',
+ * })
+ *
+ * FaasReactClient({
+ *   baseUrl: 'https://service-b.example.com/api/',
+ * })
+ *
+ * const client = getClient('https://service-b.example.com/api/')
+ *
+ * await client.faas('/pages/posts/get', { id: 1 })
  * ```
  */
 declare function getClient(host?: string): FaasReactClientInstance;
-
+//#endregion
+//#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;
-declare namespace useConstant {
-    var whyDidYouRender: boolean;
-}
-
+//#endregion
+//#region src/ErrorBoundary.d.ts
+/**
+ * Props for the {@link ErrorBoundary} component.
+ */
 interface ErrorBoundaryProps {
-    children?: ReactNode;
-    onError?: (error: Error | null, info: any) => void;
-    errorChildren?: ReactElement<ErrorChildrenProps>;
+  /** 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;
-    errorDescription?: 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;
-    info?: {
-        componentStack?: string;
-    };
+  error: Error | null;
+  info: ErrorInfo;
 }> {
-    static displayName: string;
-    static whyDidYouRender: boolean;
-    constructor(props: ErrorBoundaryProps);
-    componentDidCatch(error: Error | null, info: any): void;
-    render(): string | number | bigint | boolean | react_jsx_runtime.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode>>;
+  /**
+   * 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 | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | _$react_jsx_runtime0.JSX.Element | null;
 }
-
+//#endregion
+//#region src/equal.d.ts
 /**
  * Compares two values for deep equality.
  *
@@ -196,6 +1371,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;
 /**
@@ -203,6 +1386,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;
 /**
@@ -211,232 +1405,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.
- */
-declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
-
-/**
- * Props for the FormButtonElement component.
- *
- * @property {React.ReactNode} [children] - The content to be displayed inside the button.
- * @property {boolean} disabled - Indicates whether the button is disabled.
- * @property {() => Promise<void>} submit - A function to be called when the button is clicked, which returns a promise.
- */
-type FormButtonElementProps = {
-    children?: React.ReactNode;
-    submitting: boolean;
-    submit: () => Promise<void>;
-};
-
-/**
- * Props for the Form Input Element component.
  *
- * @property {string} name - The name of the input element.
- * @property {any} value - The current value of the input element.
- * @property {(value: any) => void} onChange - Callback function to handle changes to the input value.
- */
-type FormInputElementProps = {
-    name: string;
-    value: any;
-    onChange: (value: any) => void;
-};
-
-/**
- * Props for the FormLabelElement component.
- *
- * @typedef {Object} FormLabelElementProps
- * @property {string} name - The name of the form element.
- * @property {ReactNode} [title] - Optional title for the form element.
- * @property {ReactNode} [description] - Optional description for the form element.
- * @property {Error} [error] - Optional error associated with the form element.
- * @property {ReactNode} children - The child elements, typically an input element.
- */
-type FormLabelElementProps = {
-    name: string;
-    title?: ReactNode;
-    description?: ReactNode;
-    error?: Error;
-    /** as Input element */
-    children: ReactNode;
-};
-
-/**
- * Represents the types of form elements used in the form.
- *
- * @typedef {Object} FormElementTypes
- * @property {ComponentType<FormLabelElementProps>} Label - The component type for the form label element.
- * @property {ComponentType<FormInputElementProps>} Input - The component type for the form input element.
- * @property {ComponentType<FormButtonElementProps>} Button - The component type for the form button element.
- */
-type FormElementTypes = {
-    Label: ComponentType<FormLabelElementProps>;
-    Input: ComponentType<FormInputElementProps>;
-    Button: ComponentType<FormButtonElementProps>;
-};
-declare const FormDefaultElements: FormElementTypes;
-
-declare const FormDefaultLang: {
-    submit: string;
-    required: string;
-    string: string;
-    number: string;
-};
-type FormLang = typeof FormDefaultLang;
-
-/**
- * A type representing a form validation rule.
- *
- * @template Options - The type of the options that can be passed to the rule.
- *
- * @param value - The value to be validated.
- * @param options - Optional. Additional options that can be used in the validation.
- * @param lang - Optional. The language settings that can be used in the validation.
+ * @example
+ * ```tsx
+ * import { useEqualCallback } from '@faasjs/react'
  *
- * @returns A promise that resolves if the validation is successful, or rejects with an error if the validation fails.
+ * function Search({ filters }: { filters: Record<string, any> }) {
+ *   const handleSubmit = useEqualCallback(() => {
+ *     console.log(filters)
+ *   }, [filters])
  *
- * @example
- * ```ts
- * async function required(value: any, options: boolean, lang?: FormLang) {
- *   if (value === null || value === undefined || value === '' || Number.isNaN(value))
- *     throw Error(lang?.required)
+ *   return <button onClick={handleSubmit}>Search</button>
  * }
  * ```
  */
-type FormRule<Options = any> = (value: any, options?: Options, lang?: FormLang) => Promise<void>;
-type InferRuleOption<T> = T extends (value: any, options: infer O, lang?: FormLang) => Promise<void> ? O : never;
-/**
- * A type representing a set of form validation rules.
- *
- * @typedef {Record<string, FormRule>} FormRules
- *
- * Each key in the record represents the name of a form field, and the corresponding value is a `FormRule` object that defines the validation rules for that field.
- */
-type FormRules = Record<string, FormRule>;
-type InferFormRulesOptions<T> = {
-    [K in keyof T]: InferRuleOption<T[K]>;
-};
-/**
- * Default validation rules for a form.
- *
- * @constant
- * @type {FormRules}
- */
-declare const FormDefaultRules: FormRules;
-type FormDefaultRulesOptions = InferFormRulesOptions<typeof FormDefaultRules>;
-declare function validValues(rules: FormRules, items: FormItemProps[], values: Record<string, any>, lang: FormLang): Promise<Record<string, Error>>;
-
-type InferFormInputProps<T extends ComponentType<FormInputElementProps> | JSXElementConstructor<any>> = T extends ComponentType<FormInputElementProps> ? Omit<ComponentProps<T>, 'name' | 'value' | 'onChange'> : Omit<ComponentProps<T>, 'name' | 'value'>;
-type FormInputProps<FormElements extends FormElementTypes = FormElementTypes> = {
-    Input?: ComponentType<FormInputElementProps>;
-    props?: InferFormInputProps<FormElements['Input']>;
-};
-
-type FormItemName = string;
-type FormItemProps<FormElements extends FormElementTypes = FormElementTypes, FormRulesOptions extends Record<string, any> = FormDefaultRulesOptions> = {
-    name: FormItemName;
-    label?: Omit<FormLabelElementProps, 'name' | 'children'> & {
-        Label?: ComponentType<FormLabelElementProps>;
-    };
-    input?: FormInputProps<FormElements>;
-    rules?: FormRulesOptions;
-};
-declare function FormItem(props: FormItemProps): react_jsx_runtime.JSX.Element;
-declare namespace FormItem {
-    var displayName: string;
-    var whyDidYouRender: boolean;
-}
-
-type FormProps<Values extends Record<string, any> = Record<string, any>, FormElements extends FormElementTypes = FormElementTypes, Rules extends FormRules = typeof FormDefaultRules> = {
-    items: FormItemProps<FormElements, InferFormRulesOptions<Rules>>[];
-    onSubmit?: (values: Values) => Promise<void>;
-    Elements?: Partial<FormElements>;
-    lang?: Partial<FormLang>;
-    defaultValues?: Values;
-    rules?: typeof FormDefaultRules & Rules;
-};
+declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
+//#endregion
+//#region src/OptionalWrapper.d.ts
 /**
- * FormContainer component is a wrapper that provides context and state management for form elements.
- * It initializes form states such as values, errors, submitting status, elements, language, and rules.
- *
- * @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 {FormProps<Values, FormElements, Rules>} props - The properties for the FormContainer component.
- * @param {Values} props.defaultValues - The default values for the form fields.
- * @param {FormElements} props.Elements - The form elements to be used in the form.
- * @param {Rules} props.rules - The validation rules for the form fields.
- * @param {FormLang} props.lang - The language settings for the form.
- * @param {Partial<FormContextProps>} props - Additional properties for the form context.
+ * Props for the {@link OptionalWrapper} helper component.
  *
- * @returns {JSX.Element} The FormContainer component.
- *
- * @example
- * ```tsx
- * import { Form } from '@faasjs/react'
- *
- * function MyForm() {
- *   return <Form
- *     items={[
- *       { name: 'name' },
- *     ]}
- *   />
- * }
- * ```
+ * @template TWrapper - Wrapper component type used when `condition` is true.
  */
-declare function FormContainer<Values extends Record<string, any> = Record<string, any>, FormElements extends FormElementTypes = FormElementTypes, Rules extends FormRules = typeof FormDefaultRules>({ defaultValues, Elements, rules, lang, items, ...props }: FormProps<Values, FormElements, Rules>): react_jsx_runtime.JSX.Element;
-declare namespace FormContainer {
-    var displayName: string;
-    var whyDidYouRender: boolean;
-}
-
-type FormContextProps<Values extends Record<string, any> = Record<string, any>, FormElements extends FormElementTypes = FormElementTypes, Rules extends FormRules = typeof FormDefaultRules> = {
-    items: FormItemProps<FormElements, InferFormRulesOptions<Rules>>[];
-    onSubmit: (values: Values) => Promise<void>;
-    Elements: FormElementTypes;
-    lang: FormLang;
-    rules: typeof FormDefaultRules & Rules;
-    submitting: boolean;
-    setSubmitting: Dispatch<SetStateAction<boolean>>;
-    values: Values;
-    setValues: Dispatch<SetStateAction<Values>>;
-    errors: Record<string, Error>;
-    setErrors: Dispatch<SetStateAction<Record<string, Error>>>;
-    valuesRef: RefObject<Values>;
-};
-declare const FormContextProvider: <NewT extends FormContextProps<Record<string, any>, FormElementTypes, FormRules> = FormContextProps<Record<string, any>, FormElementTypes, FormRules>>(props: {
-    value?: Partial<NewT>;
-    children: react.ReactNode;
-    memo?: true | any[];
-    initializeStates?: Partial<NewT>;
-}) => react.ReactNode;
-declare const useFormContext: <NewT extends FormContextProps<Record<string, any>, FormElementTypes, FormRules> = FormContextProps<Record<string, any>, FormElementTypes, FormRules>>() => Readonly<NewT>;
-
 type OptionalWrapperProps<TWrapper extends ComponentType<{
-    children: ReactNode;
+  children: ReactNode;
 }> = any> = {
-    condition: boolean;
-    Wrapper: TWrapper;
-    wrapperProps?: ComponentProps<TWrapper>;
-    children: ReactNode;
+  /** 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
@@ -453,14 +1504,22 @@ type OptionalWrapperProps<TWrapper extends ComponentType<{
  * )
  * ```
  */
-declare const OptionalWrapper: React.FC<OptionalWrapperProps> & {
-    whyDidYouRender: boolean;
-};
-
+declare function OptionalWrapper(props: OptionalWrapperProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | _$react.ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | _$react_jsx_runtime0.JSX.Element | 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.
+ *
+ * `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
@@ -500,125 +1559,213 @@ declare const OptionalWrapper: React.FC<OptionalWrapperProps> & {
  * }
  * ```
  */
-declare function createSplittingContext<T extends Record<string, any>>(defaultValue: {
-    [K in keyof T]: Partial<T[K]> | null;
-} | (keyof T)[]): {
+declare function createSplittingContext<T extends Record<string, any>>(defaultValue: { [K in keyof T]: Partial<T[K]> | null } | (keyof T)[]): {
+  /**
+   * The provider component of the splitting context.
+   *
+   * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#provider
+   *
+   * @example
+   * ```tsx
+   * function App() {
+   *   const [value, setValue] = useState(0)
+   *
+   *   return (
+   *     <Provider value={{ value, setValue }}>
+   *       <ReaderComponent />
+   *       <WriterComponent />
+   *     </Provider>
+   *   )
+   * }
+   * ```
+   */
+  Provider<NewT extends T = T>(this: void, props: {
+    /** Partial context value supplied by the caller. */value?: Partial<NewT>; /** Descendant elements that should read from the split contexts. */
+    children: ReactNode;
     /**
-     * The provider component of the splitting context.
-     *
-     * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#provider
+     * Memoization mode for `children`.
      *
-     * @example
-     * ```tsx
-     * function App() {
-     *   const [value, setValue] = useState(0)
+     * @default false
      *
-     *   return (
-     *     <Provider value={{ value, setValue }}>
-     *       <ReaderComponent />
-     *       <WriterComponent />
-     *     </Provider>
-     *   )
-     * }
-     * ```
+     * Pass `true` to memoize without dependencies or an array to control the
+     * deep-equality dependency list manually.
      */
-    Provider<NewT extends T = T>(props: {
-        value?: Partial<NewT>;
-        children: ReactNode;
-        /**
-         * Whether to use memoization for the children.
-         *
-         * @default false
-         *
-         * `true`: memoize the children without dependencies.
-         * `any[]`: memoize the children with specific dependencies.
-         */
-        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.
-         *
-         * @example
-         * ```tsx
-         * <Provider
-         *  initializeStates={{
-         *    value: 0,
-         *  }}
-         * >
-         *   // Children will have access to: value, setValue
-         * </Provider>
-         */
-        initializeStates?: Partial<NewT>;
-    }): ReactNode;
+    memo?: true | any[];
     /**
-     * The hook to use the splitting context.
+     * Initial values converted into local state via `useSplittingState`.
      *
-     * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#use
+     * Each key produces both a state value and its matching setter using the
+     * `value` / `setValue` naming convention.
      *
      * @example
      * ```tsx
-     * function ChildComponent() {
-     *   const { value, setValue } = use()
+     * <Provider initializeStates={{ value: 0 }}>
+     *   <Child />
+     * </Provider>
      *
-     *   return <div>{value}<button onClick={() => setValue(1)}>change value</button></div>
-     * }
+     * // `Child` can read `value` and `setValue`
      * ```
      */
-    use: <NewT extends T = T>() => Readonly<NewT>;
-};
-
-type SetPrefix<S extends string | number | symbol> = S extends string ? S extends `${infer First}${infer Rest}` ? `set${Capitalize<First>}${Rest}` : never : never;
-type StateSetters<T> = {
-    [K in keyof T as SetPrefix<K>]: Dispatch<SetStateAction<T[K]>>;
+    initializeStates?: Partial<NewT>;
+  }): ReactNode;
+  /**
+   * Hook used to read values from the splitting context.
+   *
+   * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#use
+   *
+   * @example
+   * ```tsx
+   * function ChildComponent() {
+   *   const { value, setValue } = use()
+   *
+   *   return <div>{value}<button onClick={() => setValue(1)}>change value</button></div>
+   * }
+   * ```
+   */
+  use: <NewT extends T = T>(this: void) => Readonly<NewT>;
 };
+//#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>;
 /**
- * A hook that initializes and splits state variables and their corresponding setters.
+ * Create local state entries and matching setters for each key in an object.
  *
  * @template T - A generic type that extends a record with string keys and any values.
- * @param {T} initialStates - An object containing the initial states.
+ * @param initialStates - Object whose keys become state values and `setXxx` setters.
+ * @returns Object containing the original keys plus generated setter functions.
  *
  * @example
  * ```tsx
  * function Counter() {
- *   const { count, setCount, name, setName } = useSplittingState({ count: 0, name: 'John' });
+ *   const { count, setCount, name, setName } = useSplittingState({ count: 0, name: 'John' })
  *
  *   return <>{name}: {count}</>
  * }
  * ```
  */
 declare function useSplittingState<T extends Record<string, unknown>>(initialStates: T): StatesWithSetters<T>;
-
+//#endregion
+//#region src/useFaasStream.d.ts
+/**
+ * Options that customize the {@link useFaasStream} request lifecycle.
+ */
+type UseFaasStreamOptions = SharedUseFaasOptions<Record<string, any>, string>;
+/**
+ * Result returned by {@link useFaasStream}.
+ */
+type UseFaasStreamResult = {
+  /** 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.
+ *
+ * `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.
+ * @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 { useFaasStream } from '@faasjs/react'
+ *
+ * function Chat({ prompt }: { prompt: string }) {
+ *   const { data, error, loading, reload } = useFaasStream('/pages/chat/stream', { prompt })
+ *
+ *   if (loading) return <div>Streaming...</div>
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         <div>Stream failed: {error.message}</div>
+ *         <button type="button" onClick={() => reload()}>
+ *           Retry
+ *         </button>
+ *       </div>
+ *     )
+ *   }
+ *
+ *   return <pre>{data}</pre>
+ * }
+ * ```
+ */
+declare function useFaasStream(action: string, defaultParams: Record<string, any>, options?: UseFaasStreamOptions): UseFaasStreamResult;
+//#endregion
+//#region src/usePrevious.d.ts
 /**
  * Hook to store the previous value of a state or prop.
  *
  * @template T - The type of the value.
- * @param {T} value - The current value to be stored.
- * @returns {T | undefined} - The previous value, or undefined if there is no previous 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
+//#region src/useStateRef.d.ts
 /**
  * Custom hook that returns a stateful value and a ref to that value.
  *
  * @template T - The type of the value.
- * @param {T} initialValue - The initial value of the state.
- * @returns {[T, (value: T) => void, RefObject<T>]} - The stateful value, a function to set the value, and a ref to 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>
- * )
+ *   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>
+ *   )
+ * }
+ * ```
  */
-declare function useStateRef<T = any>(initialValue?: T): [T, Dispatch<SetStateAction<T>>, RefObject<T>];
-
-export { ErrorBoundary, type ErrorBoundaryProps, type ErrorChildrenProps, type FaasDataInjection, FaasDataWrapper, type FaasDataWrapperProps, type FaasDataWrapperRef, FaasReactClient, type FaasReactClientInstance, type FaasReactClientOptions, FormContainer as Form, type FormButtonElementProps, type FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, type FormDefaultRulesOptions, type FormElementTypes, type FormInputElementProps, FormItem, type FormItemName, type FormItemProps, type FormLabelElementProps, type FormLang, type FormProps, type FormRule, type FormRules, type InferFormRulesOptions, type OnError, OptionalWrapper, type OptionalWrapperProps, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, type useFaasOptions, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+declare function useStateRef<T = any>(initialValue?: T): [T | null, Dispatch<SetStateAction<T | null>>, RefObject<T | null>];
+//#endregion
+export { BaseUrl, ErrorBoundary, ErrorBoundaryProps, ErrorChildrenProps, type FaasAction, type FaasActionUnionType, FaasBrowserClient, FaasBrowserClientAction, type FaasData, FaasDataInjection, FaasDataWrapper, FaasDataWrapperProps, FaasDataWrapperRef, type FaasParams, FaasReactClient, FaasReactClientInstance, FaasReactClientOptions, MockHandler, OnError, OptionalWrapper, OptionalWrapperProps, Options, Response, ResponseError, ResponseErrorProps, ResponseHeaders, ResponseProps, StateSetters, StatesWithSetters, UseFaasStreamOptions, UseFaasStreamResult, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasOptions, useFaasStream, usePrevious, useSplittingState, useStateRef, withFaasData };