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

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { FaasAction, FaasAction as FaasAction$1, FaasActionUnionType, FaasActionUnionType as FaasActionUnionType$1, FaasData, FaasData as FaasData$1, FaasParams, FaasParams as FaasParams$1 } from "@faasjs/types";
 import * as react from "react";
-import { Component, ComponentProps, ComponentType, Dispatch, ErrorInfo, JSX, JSXElementConstructor, ReactElement, ReactNode, RefObject, SetStateAction } from "react";
+import { Component, ComponentProps, ComponentType, Dispatch, ErrorInfo, JSX, ReactElement, ReactNode, RefObject, SetStateAction } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/generateId.d.ts
@@ -125,11 +125,10 @@ type ResponseHeaders = {
  *
  * @template PathOrData - The function path or data type for type safety
  *
- * @param {FaasAction<PathOrData>} action - The function path to call
- * @param {FaasParams<PathOrData>} [params] - Optional parameters for the function
- * @param {Options} [options] - Optional request options
- *
- * @returns {Promise<Response<FaasData<PathOrData>> | Response>} - A Promise resolving to a Response object
+ * @param action - The function path to call.
+ * @param params - Optional parameters for the function.
+ * @param options - Optional request overrides.
+ * @returns Promise resolving to the request response. In streaming mode the runtime returns the native fetch response.
  *
  * Notes:
  * - Used internally by FaasBrowserClient.action method
@@ -196,9 +195,6 @@ type ResponseProps<T = any> = {
  * @property {T} [data] - The parsed JSON data from the response.
  *   Optional property that contains the response payload when JSON is provided.
  *
- * @param {ResponseProps<T>} [props] - Response properties including status, headers, body, and data.
- *   All properties are optional with sensible defaults.
- *
  * Notes:
  * - status defaults to 200 if data or body is present, 204 otherwise
  * - body is automatically populated from data if not explicitly provided
@@ -302,6 +298,12 @@ declare class Response<T = any> {
   readonly headers: ResponseHeaders;
   readonly body: any;
   readonly data?: T;
+  /**
+   * Create a wrapped response object.
+   *
+   * @param props - Response properties including status, headers, body, and data.
+   * @returns Wrapped response instance.
+   */
   constructor(props?: ResponseProps<T>);
 }
 type ResponseErrorProps = {
@@ -317,7 +319,6 @@ type ResponseErrorProps = {
  * 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.
  *
- * @class ResponseError
  * @augments Error
  *
  * @property {number} status - The HTTP status code of the failed response. Defaults to 500 if not provided.
@@ -325,9 +326,6 @@ type ResponseErrorProps = {
  * @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.
  *
- * @param {string | Error | ResponseErrorProps} data - The error message, an Error object, or a ResponseErrorProps object.
- * @param {Omit<ResponseErrorProps, 'message' | 'originalError'>} [options] - Additional options for the error (status, headers, body).
- *
  * @example Basic error with message
  * ```ts
  * throw new ResponseError('User not found')
@@ -425,18 +423,18 @@ declare class ResponseError extends Error {
  * Defines the signature for functions that can mock API requests during testing.
  * Mock handlers receive request parameters and return simulated responses or errors.
  *
- * @param {string} action - The function path/action being requested (e.g., 'user', 'data/list').
+ * @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 {Record<string, any> | undefined} params - The parameters passed to the action.
+ * @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} options - The full request options including headers, beforeRequest hook, and other config.
+ * @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.
  *
- * @returns {Promise<ResponseProps> | Promise<void> | Promise<Error>} - A Promise resolving to:
+ * @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
@@ -630,11 +628,8 @@ declare class FaasBrowserClient {
   /**
    * Creates a new FaasBrowserClient instance.
    *
-   * @param baseUrl - Base URL for all API requests. Must end with '/'. Defaults to '/' for relative requests.
-   *   @throws {Error} If baseUrl does not end with '/'
-   * @param options - Configuration options for the client.
-   *   Supports default headers, beforeRequest hook, custom request function,
-   *   baseUrl override, and streaming mode.
+   * @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.
    *
    * @example Basic initialization
    * ```ts
@@ -685,7 +680,7 @@ declare class FaasBrowserClient {
    * })
    * ```
    *
-   * @throws {Error} When baseUrl does not end with '/'
+   * @throws {Error} When `baseUrl` does not end with `/`
    */
   constructor(baseUrl?: BaseUrl, options?: Options);
   /**
@@ -704,7 +699,7 @@ declare class FaasBrowserClient {
    *
    * @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 {NetworkError} When network request fails
+   * @throws {Error} When the request fails before a response is received
    *
    * Notes:
    * - All requests are POST requests by default
@@ -758,11 +753,7 @@ declare class FaasBrowserClient {
    *   email: string
    * }
    *
-   * const response = await client.action<{
-   *   action: 'user'
-   *   params: { id: number }
-   *   data: UserData
-   * }>('user', { id: 123 })
+   * const response = await client.action<UserData>('user', { id: 123 })
    * console.log(response.data.name) // TypeScript knows it's a string
    * ```
    *
@@ -774,7 +765,7 @@ declare class FaasBrowserClient {
    * } catch (error) {
    *   if (error instanceof ResponseError) {
    *     console.error(`Server error: ${error.message}`, error.status)
-   *     if (error.data) console.error('Error details:', error.data)
+   *     if (error.body) console.error('Error details:', error.body)
    *   } else {
    *     console.error('Network error:', error)
    *   }
@@ -798,17 +789,20 @@ declare class FaasBrowserClient {
 //#endregion
 //#region src/faas.d.ts
 /**
- * Request faas server
+ * Call the currently configured FaasReactClient.
  *
- * @param action {string} action name
- * @param params {object} action params
- * @returns {Promise<Response<any>>}
+ * @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.
+ * @returns Response returned by the active browser client.
  *
  * @example
  * ```ts
- * faas<{ title: string }>('post/get', { id: 1 }).then(res => {
- *   console.log(res.data.title)
- * })
+ * import { faas } from '@faasjs/react'
+ *
+ * const response = await faas<{ title: string }>('post/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>>>;
@@ -861,9 +855,12 @@ declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType$1 = any>(
 declare function withFaasData<PathOrData extends FaasActionUnionType$1, TComponentProps extends Required<FaasDataInjection<PathOrData>> = Required<FaasDataInjection<PathOrData>>>(Component: React.FC<TComponentProps>, faasProps: FaasDataWrapperProps<PathOrData>): React.FC<Omit<TComponentProps, keyof FaasDataInjection<PathOrData>> & Record<string, any>>;
 //#endregion
 //#region src/useFaas.d.ts
+/**
+ * Options for {@link useFaas}.
+ */
 type useFaasOptions<PathOrData extends FaasActionUnionType$1> = {
-  params?: FaasParams$1<PathOrData>;
-  data?: FaasData$1<PathOrData>;
+  /** Override the request params without changing the hook's stored params state. */params?: FaasParams$1<PathOrData>; /** Controlled data value used instead of the hook's internal state. */
+  data?: FaasData$1<PathOrData>; /** Controlled setter that is called instead of the hook's internal `setData`. */
   setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
   /**
    * If skip is true, the request will not be sent.
@@ -871,20 +868,27 @@ type useFaasOptions<PathOrData extends FaasActionUnionType$1> = {
    * However, you can still use reload to send the request.
    */
   skip?: boolean | ((params: FaasParams$1<PathOrData>) => boolean); /** Send the last request after milliseconds */
-  debounce?: number;
+  debounce?: number; /** Override the default base URL for this hook instance. */
   baseUrl?: BaseUrl;
 };
 /**
- * Request faas server with React hook
+ * Request FaasJS data and keep request state in React state.
+ *
+ * `useFaas` sends an initial request unless `skip` is enabled, and returns
+ * request state plus helpers for reloading, updating data, and handling errors.
  *
- * @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.
+ * @returns Request state and helper methods for the action.
  *
  * @example
  * ```tsx
- * function Post ({ id }) {
+ * import { useFaas } from '@faasjs/react'
+ *
+ * function Post({ id }: { id: number }) {
  *   const { data } = useFaas<{ title: string }>('post/get', { id })
+ *
  *   return <h1>{data.title}</h1>
  * }
  * ```
@@ -893,10 +897,15 @@ declare function useFaas<PathOrData extends FaasActionUnionType$1>(action: FaasA
 //#endregion
 //#region src/client.d.ts
 type OnError = (action: string, params: Record<string, any>) => (res: ResponseError) => Promise<void>;
+/**
+ * Options for creating a {@link FaasReactClient} instance.
+ */
 type FaasReactClientOptions = {
-  /** @default `/` */baseUrl?: BaseUrl;
+  /** @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
    * onError: (action, params) => async (res) => {
@@ -906,6 +915,9 @@ type FaasReactClientOptions = {
    */
   onError?: OnError;
 };
+/**
+ * Public interface returned by {@link FaasReactClient}.
+ */
 type FaasReactClientInstance = {
   id: string;
   faas: typeof faas;
@@ -915,14 +927,20 @@ type FaasReactClientInstance = {
   browserClient: FaasBrowserClient;
 };
 /**
- * Before use faas, you should initialize a FaasReactClient.
+ * Create and register a FaasReactClient instance.
  *
- * @returns 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 options - Client configuration including base URL, default request options, and error hooks.
+ * @returns Registered FaasReactClient instance.
  *
  * @example
  * ```ts
+ * import { FaasReactClient } from '@faasjs/react'
+ *
  * const client = FaasReactClient({
- *   baseUrl: 'localhost:8080/api/'
+ *   baseUrl: 'http://localhost:8080/api/',
  * })
  * ```
  */
@@ -932,16 +950,20 @@ declare function FaasReactClient({
   onError
 }?: FaasReactClientOptions): FaasReactClientInstance;
 /**
- * Get FaasReactClient instance
+ * Get a registered FaasReactClient instance.
+ *
+ * When `host` is omitted, the first registered client is returned. If no client
+ * has been created yet, a default client is initialized automatically.
  *
- * @param host {string} empty string for default host
- * @returns {FaasReactClientInstance}
+ * @param host - Registered base URL to look up. Omit it to use the default client.
+ * @returns Registered or newly created FaasReactClient instance.
  *
  * @example
  * ```ts
+ * import { getClient } from '@faasjs/react'
+ *
  * getClient()
- * // or
- * getClient('another-host')
+ * getClient('http://localhost:8080/api/')
  * ```
  */
 declare function getClient(host?: string): FaasReactClientInstance;
@@ -1019,223 +1041,6 @@ declare function useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
  */
 declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
 //#endregion
-//#region src/Form/elements/Button.d.ts
-/**
- * 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>;
-};
-//#endregion
-//#region src/Form/elements/Input.d.ts
-/**
- * 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;
-};
-//#endregion
-//#region src/Form/elements/Label.d.ts
-/**
- * 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;
-};
-//#endregion
-//#region src/Form/elements/index.d.ts
-/**
- * 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;
-//#endregion
-//#region src/Form/lang.d.ts
-declare const FormDefaultLang: {
-  submit: string;
-  required: string;
-  string: string;
-  number: string;
-};
-type FormLang = typeof FormDefaultLang;
-//#endregion
-//#region src/Form/rules.d.ts
-/**
- * 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.
- *
- * @returns A promise that resolves if the validation is successful, or rejects with an error if the validation fails.
- *
- * @example
- * ```ts
- * async function required(value: any, options: boolean, lang?: FormLang) {
- *   if (value === null || value === undefined || value === '' || Number.isNaN(value))
- *     throw Error(lang?.required)
- * }
- * ```
- */
-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.
- */
-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>>;
-//#endregion
-//#region src/Form/Input.d.ts
-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']>;
-};
-declare function FormInput({
-  name,
-  rules,
-  ...rest
-}: FormInputProps & {
-  name: string;
-  rules?: FormDefaultRulesOptions;
-}): react_jsx_runtime0.JSX.Element;
-declare namespace FormInput {
-  var displayName: string;
-}
-//#endregion
-//#region src/Form/Item.d.ts
-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_runtime0.JSX.Element;
-declare namespace FormItem {
-  var displayName: string;
-}
-//#endregion
-//#region src/Form/Container.d.ts
-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;
-};
-/**
- * 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.
- *
- * @returns {JSX.Element} The FormContainer component.
- *
- * @example
- * ```tsx
- * import { Form } from '@faasjs/react'
- *
- * function MyForm() {
- *   return <Form
- *     items={[
- *       { name: 'name' },
- *     ]}
- *   />
- * }
- * ```
- */
-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_runtime0.JSX.Element;
-declare namespace FormContainer {
-  var displayName: string;
-}
-//#endregion
-//#region src/Form/context.d.ts
-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>>(this: void, 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>>(this: void) => Readonly<NewT>;
-//#endregion
 //#region src/OptionalWrapper.d.ts
 type OptionalWrapperProps<TWrapper extends ComponentType<{
   children: ReactNode;
@@ -1385,15 +1190,16 @@ declare function createSplittingContext<T extends Record<string, any>>(defaultVa
 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]>> };
 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}</>
  * }
@@ -1402,9 +1208,12 @@ type StatesWithSetters<T> = T & StateSetters<T>;
 declare function useSplittingState<T extends Record<string, unknown>>(initialStates: T): StatesWithSetters<T>;
 //#endregion
 //#region src/useFaasStream.d.ts
+/**
+ * Options for {@link useFaasStream}.
+ */
 type UseFaasStreamOptions = {
-  params?: Record<string, any>;
-  data?: string;
+  /** Override the request params without changing the hook's stored params state. */params?: Record<string, any>; /** Controlled stream text used instead of the hook's internal state. */
+  data?: string; /** Controlled setter that is called instead of the hook's internal `setData`. */
   setData?: React.Dispatch<React.SetStateAction<string>>;
   /**
    * If skip is true, the request will not be sent.
@@ -1412,9 +1221,12 @@ type UseFaasStreamOptions = {
    * However, you can still use reload to send the request.
    */
   skip?: boolean | ((params: Record<string, any>) => boolean); /** Send the last request after milliseconds */
-  debounce?: number;
+  debounce?: number; /** Override the default base URL for this hook instance. */
   baseUrl?: BaseUrl;
 };
+/**
+ * Result returned by {@link useFaasStream}.
+ */
 type UseFaasStreamResult = {
   action: string;
   params: Record<string, any>;
@@ -1428,14 +1240,21 @@ type UseFaasStreamResult = {
   setError: React.Dispatch<React.SetStateAction<any>>;
 };
 /**
- * Stream faas server response with React hook
+ * Stream a FaasJS response into React state.
+ *
+ * The hook sends a streaming request, appends decoded text chunks to `data`,
+ * and exposes reload helpers for retrying the same action.
  *
- * @param action {string} action name
- * @param defaultParams {object} initial action params
- * @returns {UseFaasStreamResult}
+ * @param action - Action path to invoke.
+ * @param defaultParams - Params used for the initial request and future reloads.
+ * @param options - Optional hook configuration such as controlled data, debounce, and skip logic.
+ * @returns Streaming request state and helper methods.
  *
  * @example
  * ```tsx
+ * import { useState } from 'react'
+ * import { useFaasStream } from '@faasjs/react'
+ *
  * function Chat() {
  *   const [prompt, setPrompt] = useState('')
  *   const { data, loading, reload } = useFaasStream('chat', { prompt })
@@ -1457,8 +1276,8 @@ declare function useFaasStream(action: string, defaultParams: Record<string, any
  * 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.
  */
 declare function usePrevious<T = any>(value: T): T | undefined;
 //#endregion
@@ -1467,24 +1286,26 @@ declare function usePrevious<T = any>(value: T): T | undefined;
  * 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 | 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, FormContainer as Form, type FormButtonElementProps, FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormDefaultRulesOptions, FormElementTypes, FormInput, type FormInputElementProps, FormInputProps, FormItem, FormItemName, FormItemProps, type FormLabelElementProps, FormLang, FormProps, FormRule, FormRules, InferFormInputProps, InferFormRulesOptions, InferRuleOption, 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, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+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 };