@faasjs/react 8.0.0-beta.3 → 8.0.0-beta.31

package/dist/index.d.ts

@@ -1,187 +1,665 @@
-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 { FaasActionPaths, FaasData, FaasParams } from "@faasjs/types";
 
+//#region src/generate-id/index.d.ts
 /**
- * Injects FaasData props.
+ * Generate a random identifier with an optional prefix.
+ *
+ * @param {string} [prefix] - Prefix prepended to the generated identifier.
+ * @param {number} [length] - Length of the generated identifier excluding `prefix`. Must be between `8` and `18`.
+ * @returns {string} Generated identifier string.
+ * @throws {Error} When `length` is outside the supported `8` to `18` range.
+ *
+ * @example
+ * ```ts
+ * import { generateId } from '@faasjs/react'
+ *
+ * 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/response.d.ts
+/**
+ * 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
+ */
+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.
+   */
+  constructor(props?: ResponseProps<T>);
+}
+/**
+ * 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.
+ */
+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.
+   */
+  constructor(data: string | Error, options?: Omit<ResponseErrorProps, 'message' | 'originalError'>);
+  constructor(data: ResponseErrorProps);
+}
+//#endregion
+//#region src/browser/types.d.ts
+/**
+ * Template literal type for URL strings that must end with a forward slash.
+ */
+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.
+ */
+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?: (url: string, options: Options) => Promise<Response>; /** 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.
+ */
+type ResponseHeaders = {
+  [key: string]: string;
+};
+/**
+ * Type definition for the FaasBrowserClient.action method.
+ */
+type FaasBrowserClientAction = <Path extends FaasActionPaths>(action: Path, params?: FaasParams<Path>, options?: Options) => Promise<Response<FaasData<Path>> | Response>;
+/**
+ * Properties for creating a Response object.
+ */
+type ResponseProps<T = any> = {
+  status?: number;
+  headers?: ResponseHeaders;
+  body?: any;
+  data?: 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;
+};
+/**
+ * Mock handler function type for testing FaasJS requests.
+ */
+type MockHandler = (action: string, params: Record<string, any> | undefined, options: Options) => Promise<ResponseProps> | Promise<void> | Promise<Error>;
+//#endregion
+//#region src/browser/mock.d.ts
+/**
+ * Set the global mock handler used by all {@link FaasBrowserClient} instances.
+ */
+declare function setMock(handler: MockHandler | ResponseProps | Response | null | undefined): void;
+//#endregion
+//#region src/browser/client.d.ts
+/**
+ * Browser client for FaasJS - provides HTTP client functionality for making API requests from web applications.
+ */
+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.
+   */
+  constructor(baseUrl?: BaseUrl, options?: Options);
+  /**
+   * Makes a request to a FaasJS function.
+   */
+  action<Path extends FaasActionPaths>(action: Path, params: FaasParams<Path>, options?: Options): Promise<Response<FaasData<Path>>>;
+}
+//#endregion
+//#region src/faas/index.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 Path - Action path or response data type used for inference.
+ *
+ * @param {Path} action - Action path to invoke.
+ * @param {FaasParams<Path>} params - Parameters sent to the action.
+ * @param {Options} [options] - Optional per-request overrides such as headers or base URL.
+ * See the browser-client `Options` type for supported fields such as `headers`, `beforeRequest`,
+ * `request`, `baseUrl`, and `stream`.
+ * @returns {Promise<Response<FaasData<Path>>>} 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<Path extends FaasActionPaths>(action: Path, params: FaasParams<Path>, options?: Options): Promise<Response<FaasData<Path>>>;
+//#endregion
+//#region src/FaasDataWrapper/index.d.ts
+/**
+ * Request state injected by {@link useFaas}, {@link FaasDataWrapper}, and {@link withFaasData}.
+ *
+ * @template Path - Action path or response data type used for inference.
+ */
+type FaasDataInjection<Path extends FaasActionPaths> = {
+  /** Action path associated with the current request state. */action: Path; /** Params used for the most recent request attempt. */
+  params: FaasParams<Path>; /** Whether the request is currently in flight and should block the main UI. */
+  loading: boolean; /** Whether a background refresh request is currently in flight. */
+  refreshing: boolean; /** Number of times `reload()` or polling has triggered a new request. */
+  reloadTimes: number; /** Current resolved data value. */
+  data: FaasData<Path>; /** Last request error, if one occurred. */
+  error: any; /** Promise representing the latest request. */
+  promise: Promise<Response<FaasData<Path>>>;
+  /**
+   * 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?: FaasParams<Path>, options?: {
+    silent?: boolean;
+  }): Promise<FaasData<Path>>; /** Controlled or internal setter for the resolved data value. */
+  setData: React.Dispatch<React.SetStateAction<FaasData<Path>>>; /** 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<Path>>>>>; /** Setter for the last request error. */
+  setError: React.Dispatch<React.SetStateAction<any>>;
 };
-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>>;
+/**
+ * Props for the {@link FaasDataWrapper} render-prop component.
+ *
+ * @template Path - Action path or response data type used for inference.
+ */
+type FaasDataWrapperProps<Path extends FaasActionPaths> = {
+  /** Render prop invoked with the resolved request state after the first load completes. */render?(args: FaasDataInjection<Path>): JSX.Element | JSX.Element[]; /** Child element cloned with injected request state after the first load completes. */
+  children?: React.ReactElement<Partial<FaasDataInjection<Path>>>; /** Element rendered before the first successful load. */
+  fallback?: JSX.Element | false; /** Action path to request. */
+  action: Path; /** Params sent to the action. */
+  params?: FaasParams<Path>; /** Milliseconds to wait after each completed request before refreshing data in the background. */
+  polling?: number | false; /** Callback invoked whenever the resolved data value changes. */
+  onDataChange?(args: FaasDataInjection<Path>): void; /** Controlled data value used instead of internal state. */
+  data?: FaasData<Path>; /** Controlled setter used instead of internal state. */
+  setData?: React.Dispatch<React.SetStateAction<FaasData<Path>>>; /** Base URL override used for this wrapper instance. */
+  baseUrl?: BaseUrl; /** Imperative ref exposing the current injected request state. */
+  ref?: React.Ref<FaasDataWrapperRef<Path>>;
 };
-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
+ * Imperative ref shape exposed by {@link FaasDataWrapper}.
+ *
+ * @template Path - Action path or response data type used for inference.
+ */
+type FaasDataWrapperRef<Path extends FaasActionPaths> = FaasDataInjection<Path>;
+/**
+ * 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 {FaasDataWrapperProps<Path>} props - Wrapper props controlling the request and rendered fallback.
+ * @param {(args: FaasDataInjection<Path>) => JSX.Element | JSX.Element[]} [props.render] - Render prop that receives the resolved Faas request state.
+ * @param {React.ReactElement<Partial<FaasDataInjection<Path>>>} [props.children] - Child element cloned with injected Faas request state.
+ * @param {JSX.Element | false} [props.fallback] - Element rendered before the first successful load.
+ * @param {Path} props.action - Action path to request.
+ * @param {FaasParams<Path>} [props.params] - Params sent to the action.
+ * @param {number | false} [props.polling] - Milliseconds to wait after each completed request before refreshing data in the background.
+ * @param {(args: FaasDataInjection<Path>) => void} [props.onDataChange] - Callback invoked when the resolved data value changes.
+ * @param {FaasData<Path>} [props.data] - Controlled data value used instead of internal state.
+ * @param {React.Dispatch<React.SetStateAction<FaasData<Path>>>} [props.setData] - Controlled setter used instead of internal state.
+ * @param {BaseUrl} [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: <Path extends FaasActionPaths>(props: FaasDataWrapperProps<Path> & _$react.RefAttributes<FaasDataWrapperRef<Path>>) => 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 when you want to
+ * preserve an existing component boundary. For new code, prefer `useFaas` or
+ * `FaasDataWrapper` when they express the request ownership more directly.
+ *
+ * @template Path - Action path or response data type used for inference.
+ * @template TComponentProps - Component props including injected Faas data fields.
+ * @param {React.FC<TComponentProps>} Component - Component that consumes injected Faas data props.
+ * @param {FaasDataWrapperProps<Path>} faasProps - Request configuration forwarded to `FaasDataWrapper`.
+ * @returns {React.FC<Omit<TComponentProps, keyof FaasDataInjection<Path>> & Record<string, any>>} 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<Path extends FaasActionPaths, TComponentProps extends Required<FaasDataInjection<Path>> = Required<FaasDataInjection<Path>>>(Component: React.FC<TComponentProps>, faasProps: FaasDataWrapperProps<Path>): React.FC<Omit<TComponentProps, keyof FaasDataInjection<Path>> & Record<string, any>>;
+//#endregion
+//#region src/useFaasRequest.d.ts
+/**
+ * Shared request options consumed by `useFaas` and `useFaasStream`.
+ *
+ * @property {Params} [params] - Controlled params override sent with the request without mutating local params state.
+ * @property {Data} [data] - Controlled data value used by higher-level hooks.
+ * @property {React.Dispatch<React.SetStateAction<Data>>} [setData] - Controlled setter paired with `data`.
+ * @property {boolean | ((params: Params) => boolean)} [skip] - Boolean or predicate that suppresses the automatic request.
+ * @property {number} [debounce] - Milliseconds to wait before sending the latest request.
+ * @property {number | false} [polling] - Milliseconds to wait after each completed request before refreshing data in the background.
+ * @property {BaseUrl} [baseUrl] - Base URL override used for this request lifecycle.
+ */
+type SharedUseFaasOptions<Params, Data> = {
+  params?: Params;
+  data?: Data;
+  setData?: React.Dispatch<React.SetStateAction<Data>>;
+  skip?: boolean | ((params: Partial<Params>) => boolean);
+  debounce?: number;
+  polling?: number | false;
+  baseUrl?: BaseUrl;
 };
+//#endregion
+//#region src/useFaas/index.d.ts
 /**
- * Request faas server with React hook
+ * Options that customize the {@link useFaas} request lifecycle.
  *
- * @param action {string} action name
- * @param defaultParams {object} initial action params
- * @returns {FaasDataInjection<any>}
+ * @template Path - Action path or response data type used for inference.
+ */
+type UseFaasOptions<Path extends FaasActionPaths> = SharedUseFaasOptions<FaasParams<Path>, FaasData<Path>>;
+/**
+ * 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, background refreshing, updating data, and handling errors.
+ *
+ * @template Path - Action path or response data type used for inference.
+ *
+ * @param {Path} action - Action path to invoke.
+ * @param {FaasParams<Path>} defaultParams - Params used for the initial request and future reloads.
+ * @param {UseFaasOptions<Path>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, polling, and base URL overrides.
+ * See the `UseFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
+ * @returns {FaasDataInjection<Path>} 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<Path extends FaasActionPaths>(action: Path, defaultParams: FaasParams<Path>, options?: UseFaasOptions<Path>): FaasDataInjection<Path>;
+//#endregion
+//#region src/client.d.ts
+/**
+ * Factory for per-request error handlers used by {@link FaasReactClient}.
+ *
+ * @param {string} action - Action name that failed.
+ * @param {Record<string, any>} params - Params sent with the failed request.
+ * @returns {(res: ResponseError) => Promise<void>} 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.
+ *
+ * The returned client is stored by `baseUrl` and becomes the default client
+ * used by helpers such as {@link faas} and {@link useFaas}.
  *
- * @param props.baseUrl {string} The baseUrl of your faas server
- * @param props.options {Options} The options of client
- * @returns {FaasReactClientInstance}
+ * @param {FaasReactClientOptions} [options] - Client configuration including base URL, default request options, and error hooks.
+ * @param {BaseUrl} [options.baseUrl] - Base URL used to register and route the client instance.
+ * @param {Options} [options.options] - Default browser-client request options forwarded to `FaasBrowserClient`.
+ * @param {OnError} [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 {FaasReactClientInstance} 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 {string} [host] - Registered base URL to look up. Omit it to use the default client.
+ * @returns {FaasReactClientInstance} 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/constants/index.d.ts
 /**
  * Returns a constant value that is created by the given function.
+ *
+ * @template T - Constant value type returned by the initializer.
+ * @param {() => T} fn - Initializer that runs only once for the current component instance.
+ * @returns {T} Stable value returned by the initializer.
+ *
+ * @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/index.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;
-    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 {ErrorBoundaryProps} props - Boundary props.
+   * @param {ReactNode} [props.children] - Descendant elements protected by the boundary.
+   * @param {(error: Error | null, info: any) => void} [props.onError] - Callback invoked after a render error is captured.
+   * @param {ReactElement<ErrorChildrenProps>} [props.errorChildren] - Custom fallback element that receives error details.
+   */
+  constructor(props: ErrorBoundaryProps);
+  /**
+   * Capture rendering errors from descendant components.
+   *
+   * @param {Error} error - Caught render error.
+   * @param {ErrorInfo} 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/index.d.ts
 /**
  * Compares two values for deep equality.
  *
@@ -189,248 +667,126 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
  * It handles various data types including primitives, arrays, dates, regular expressions, functions,
  * maps, sets, and promises.
  *
- * @param a - The first value to compare.
- * @param b - The second value to compare.
- * @returns `true` if the values are deeply equal, `false` otherwise.
+ * @param {any} a - The first value to compare.
+ * @param {any} b - The second value to compare.
+ * @returns {boolean} `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;
 /**
  * Custom hook that memoizes a value using deep equality comparison.
  *
- * @param value - The value to be memoized.
- * @returns The memoized value.
+ * @param {any} value - The value to be memoized.
+ * @returns {any} 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;
 /**
  * Custom hook that works like `useEffect` but uses deep comparison on dependencies.
  *
- * @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.
- */
-declare function useEqualEffect(callback: React.EffectCallback, dependencies: any[]): void;
-/**
- * Custom hook that works like `useMemo` but uses deep comparison on dependencies.
+ * @param {React.EffectCallback} callback - The effect callback function to run.
+ * @param {any[]} dependencies - The list of dependencies for the effect.
+ * @returns {void} The result of the `useEffect` hook with memoized dependencies.
  *
- * @param callback - The callback function to run.
- * @param dependencies - The list of dependencies.
- * @returns The result of the `useMemo` hook with memoized dependencies.
- */
-declare function useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
-/**
- * Custom hook that works like `useCallback` but uses deep comparison on dependencies.
+ * @example
+ * ```tsx
+ * import { useEqualEffect } from '@faasjs/react'
  *
- * @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.
+ * function Page({ filters }: { filters: Record<string, any> }) {
+ *   useEqualEffect(() => {
+ *     console.log('filters changed', filters)
+ *   }, [filters])
  *
- * @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.
+ *   return null
+ * }
+ * ```
  */
-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;
-};
-
+declare function useEqualEffect(callback: React.EffectCallback, dependencies: any[]): void;
 /**
- * Represents the types of form elements used in the form.
+ * Custom hook that works like `useMemo` but uses deep comparison on dependencies.
  *
- * @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 T - Memoized value type returned by the callback.
  *
- * @template Options - The type of the options that can be passed to the rule.
+ * @param {() => T} callback - The callback function to run.
+ * @param {any[]} dependencies - The list of dependencies.
+ * @returns {T} The result of the `useMemo` hook with memoized dependencies.
  *
- * @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 { useEqualMemo } from '@faasjs/react'
  *
- * @returns A promise that resolves if the validation is successful, or rejects with an error if the validation fails.
+ * function Page({ filters }: { filters: Record<string, any> }) {
+ *   const queryString = useEqualMemo(() => JSON.stringify(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 <span>{queryString}</span>
  * }
  * ```
  */
-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;
-}
-
-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 useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
 /**
- * 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.
+ * Custom hook that works like `useCallback` but uses deep comparison on dependencies.
  *
- * @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.
+ * @template T - Callback signature to memoize.
  *
- * @returns {JSX.Element} The FormContainer component.
+ * @param {T} callback - The callback function to run.
+ * @param {any[]} dependencies - The list of dependencies.
+ * @returns {T} The result of the `useCallback` hook with memoized dependencies.
  *
  * @example
  * ```tsx
- * import { Form } from '@faasjs/react'
- *
- * function MyForm() {
- *   return <Form
- *     items={[
- *       { name: 'name' },
- *     ]}
- *   />
+ * 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 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;
-}
-
-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>;
-
+declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
+//#endregion
+//#region src/OptionalWrapper/index.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;
+  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 {OptionalWrapperProps} props - Wrapper condition, wrapper component, and child content.
+ * @param {boolean} props.condition - When `true`, wrap children with `Wrapper`.
+ * @param {OptionalWrapperProps['Wrapper']} props.Wrapper - Component used as the wrapper when the condition passes.
+ * @param {OptionalWrapperProps['wrapperProps']} [props.wrapperProps] - Props forwarded to the wrapper component.
+ * @param {ReactNode} props.children - Content rendered directly or inside the wrapper.
+ * @returns {ReactNode} Wrapped children or the original children when `condition` is false.
  *
  * @example
  * ```tsx
@@ -447,15 +803,22 @@ type OptionalWrapperProps<TWrapper extends ComponentType<{
  * )
  * ```
  */
-declare function OptionalWrapper({ condition, Wrapper, wrapperProps, children, }: OptionalWrapperProps): string | number | bigint | boolean | react_jsx_runtime.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode>>;
+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;
+  var displayName: string;
 }
-
+//#endregion
+//#region src/splitting-context/index.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 {Record<string, any> | (keyof T)[]} defaultValue - Default value map or key list used to create split contexts.
+ * @returns {{ Provider<NewT extends T = T>(this: void, props: { value?: Partial<NewT>; children: ReactNode; memo?: true | any[]; initializeStates?: Partial<NewT> }): ReactNode; use<NewT extends T = T>(this: void): Readonly<NewT> }} Provider and hook helpers for the split context.
  *
  * @example
  * ```tsx
@@ -495,176 +858,213 @@ declare namespace OptionalWrapper {
  * }
  * ```
  */
-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 [Provider docs](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.
+     * Memoization mode for `children`.
      *
-     * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#provider
+     * @default false
      *
-     * @example
-     * ```tsx
-     * function App() {
-     *   const [value, setValue] = useState(0)
-     *
-     *   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 [Hook docs](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/splitting-state/index.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 {T} initialStates - Object whose keys become state values and `setXxx` setters.
+ * @returns {StatesWithSetters<T>} 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>;
-
-type UseFaasStreamOptions = {
-    params?: Record<string, any>;
-    data?: string;
-    setData?: React.Dispatch<React.SetStateAction<string>>;
-    /**
-     * If skip is true, the request will not be sent.
-     *
-     * However, you can still use reload to send the request.
-     */
-    skip?: boolean | ((params: Record<string, any>) => boolean);
-    /** Send the last request after milliseconds */
-    debounce?: number;
-    baseUrl?: BaseUrl;
-};
-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>>;
-    setError: React.Dispatch<React.SetStateAction<any>>;
+//#endregion
+//#region src/useFaasStream/index.d.ts
+/**
+ * Options that customize the {@link useFaasStream} request lifecycle.
+ */
+type UseFaasStreamOptions = SharedUseFaasOptions<Record<string, any>, string>;
+/**
+ * Result returned by {@link useFaasStream}.
+ *
+ * @template Path - Action path used for params inference.
+ */
+type UseFaasStreamResult<Path extends FaasActionPaths> = {
+  /** Action path currently associated with the stream request. */action: Path; /** Params used for the most recent request attempt. */
+  params: FaasParams<Path>; /** Whether the hook is currently waiting for stream data and should block the main UI. */
+  loading: boolean; /** Whether a background stream refresh is currently in flight. */
+  refreshing: boolean; /** Number of times `reload()` or polling 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?: FaasParams<Path>, options?: {
+    silent?: boolean;
+  }) => 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 faas server response with React hook
+ * 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 {string} action name
- * @param defaultParams {object} initial action params
- * @returns {UseFaasStreamResult}
+ * @param {string} action - Action path to invoke.
+ * @param {Record<string, any>} defaultParams - Params used for the initial request and future reloads.
+ * @param {UseFaasStreamOptions} [options] - Optional hook configuration such as controlled stream text, skip logic, debounce timing, polling, and base URL overrides.
+ * See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
+ * @returns {UseFaasStreamResult} Streaming request state and helper methods described by {@link UseFaasStreamResult}.
  *
  * @example
  * ```tsx
- * function Chat() {
- *   const [prompt, setPrompt] = useState('')
- *   const { data, loading, reload } = useFaasStream('chat', { prompt })
+ * import { useFaasStream } from '@faasjs/react'
  *
- *   return (
- *     <div>
- *       <textarea value={prompt} onChange={e => setPrompt(e.target.value)} />
- *       <button onClick={reload} disabled={loading}>Send</button>
- *       <div>{data}</div>
- *     </div>
- *   )
+ * 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;
-
+declare function useFaasStream<Path extends FaasActionPaths>(action: Path, defaultParams: FaasParams<Path>, options?: UseFaasStreamOptions): UseFaasStreamResult<Path>;
+//#endregion
+//#region src/usePrevious/index.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 {T} value - The current value to track.
+ * @returns {T | undefined} 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/index.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 {T} [initialValue] - Initial state value. When omitted, state starts as `null`.
+ * @returns {[T | null, Dispatch<SetStateAction<T | null>>, RefObject<T | null>]} 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, type UseFaasStreamOptions, type UseFaasStreamResult, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, type useFaasOptions, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+declare function useStateRef<T = any>(initialValue?: T): [T | null, Dispatch<SetStateAction<T | null>>, RefObject<T | null>];
+//#endregion
+export { type BaseUrl, ErrorBoundary, ErrorBoundaryProps, ErrorChildrenProps, FaasBrowserClient, type FaasBrowserClientAction, FaasDataInjection, FaasDataWrapper, FaasDataWrapperProps, FaasDataWrapperRef, FaasReactClient, FaasReactClientInstance, FaasReactClientOptions, type MockHandler, OnError, OptionalWrapper, OptionalWrapperProps, type Options, Response, ResponseError, type ResponseErrorProps, type ResponseHeaders, type ResponseProps, StateSetters, StatesWithSetters, UseFaasOptions, UseFaasStreamOptions, UseFaasStreamResult, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, usePrevious, useSplittingState, useStateRef, withFaasData };