@faasjs/react 8.0.0-beta.20 → 8.0.0-beta.22

package/dist/index.d.ts

@@ -7,13 +7,15 @@ import { FaasAction, FaasAction as FaasAction$1, FaasActionUnionType, FaasAction
 /**
  * Generate a random identifier with an optional prefix.
  *
- * @param prefix - Prefix prepended to the generated identifier.
- * @param length - Length of the generated identifier excluding `prefix`. Must be between `8` and `18`.
- * @returns Generated identifier string.
+ * @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
@@ -35,8 +37,8 @@ declare function generateId(prefix?: string, length?: number): string;
  * - Ensures consistent URL formatting across the codebase
  * - Throws Error at runtime if baseUrl doesn't end with '/'
  *
- * @see FaasBrowserClient for usage in client creation
- * @see Options for usage in request options
+ * @see {@link FaasBrowserClient} for usage in client creation.
+ * @see {@link Options} for usage in request options.
  */
 type BaseUrl = `${string}/`;
 /**
@@ -78,8 +80,8 @@ type BaseUrl = `${string}/`;
  *   When false or undefined, returns a wrapped Response with automatic JSON parsing.
  *
  * @augments RequestInit
- * @see FaasBrowserClient for client creation
- * @see Response for response object structure
+ * @see {@link FaasBrowserClient} for client creation.
+ * @see {@link Response} for response object structure.
  */
 type Options = RequestInit & {
   headers?: Record<string, string>; /** Async hook called after request options are merged but before the request is sent. */
@@ -114,9 +116,9 @@ type Options = RequestInit & {
  * - Used in Response, ResponseError, and Options types
  * - Simplified model compared to browser's Headers interface (no .get(), .set() methods)
  *
- * @see Response for usage in response objects
- * @see ResponseError for usage in error objects
- * @see Options for usage in request options
+ * @see {@link Response} for usage in response objects.
+ * @see {@link ResponseError} for usage in error objects.
+ * @see {@link Options} for usage in request options.
  */
 type ResponseHeaders = {
   [key: string]: string;
@@ -129,12 +131,12 @@ type ResponseHeaders = {
  *
  * @template PathOrData - The function path or data type for type safety
  *
- * @param action - The function path to call.
- * @param params - Optional parameters for the function.
- * @param options - Optional request overrides.
+ * @param {FaasAction<PathOrData>} action - The function path to call.
+ * @param {FaasParams<PathOrData>} [params] - Optional parameters for the function.
+ * @param {Options} [options] - Optional request overrides.
  * See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
  * `request`, `baseUrl`, and `stream`.
- * @returns Promise resolving to the request response. In streaming mode the runtime returns the native fetch response.
+ * @returns {Promise<Response<FaasData<PathOrData>> | Response>} Promise resolving to the request response. In streaming mode the runtime returns the native fetch response.
  *
  * Notes:
  * - Used internally by FaasBrowserClient.action method
@@ -143,9 +145,9 @@ type ResponseHeaders = {
  * - Params are optional and can be undefined
  * - Options override client defaults when provided
  *
- * @see FaasBrowserClient for the class that uses this type
- * @see Response for the return type
- * @see Options for the options parameter type
+ * @see {@link FaasBrowserClient} for the class that uses this type.
+ * @see {@link Response} for the return type.
+ * @see {@link Options} for the options parameter type.
  */
 type FaasBrowserClientAction = <PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params?: FaasParams$1<PathOrData>, options?: Options) => Promise<Response<FaasData$1<PathOrData>> | Response>;
 /**
@@ -175,8 +177,8 @@ type FaasBrowserClientAction = <PathOrData extends FaasActionUnionType$1>(action
  * - If data is provided without body, body is automatically JSON.stringify(data)
  * - Used by Response constructor and mock handlers
  *
- * @see Response for the class that uses these properties
- * @see ResponseErrorProps for error response properties
+ * @see {@link Response} for the class that uses these properties.
+ * @see {@link ResponseErrorProps} for error response properties.
  */
 type ResponseProps<T = any> = {
   status?: number;
@@ -295,9 +297,9 @@ type ResponseProps<T = any> = {
  * })
  * ```
  *
- * @see ResponseProps for response property type
- * @see ResponseError for error response handling
- * @see FaasBrowserClient.action for method returning Response
+ * @see {@link ResponseProps} for response property type.
+ * @see {@link ResponseError} for error response handling.
+ * @see {@link FaasBrowserClient.action} for method returning Response.
  */
 declare class Response<T = any> {
   /**
@@ -319,12 +321,12 @@ declare class Response<T = any> {
   /**
    * Create a wrapped response object.
    *
-   * @param props - Response properties including status, headers, body, and data.
-   * @param props.status - HTTP status code. Defaults to `200` when `data` or `body` exists, otherwise `204`.
-   * @param props.headers - Response headers keyed by header name.
-   * @param props.body - Raw response body to expose without additional parsing.
-   * @param props.data - Parsed response payload to expose on `response.data`.
-   * @returns Wrapped response instance.
+   * @param {ResponseProps<T>} [props] - Response properties including status, headers, body, and data.
+   * @param {number} [props.status] - HTTP status code. Defaults to `200` when `data` or `body` exists, otherwise `204`.
+   * @param {ResponseHeaders} [props.headers] - Response headers keyed by header name.
+   * @param {any} [props.body] - Raw response body to expose without additional parsing.
+   * @param {T} [props.data] - Parsed response payload to expose on `response.data`.
+   * @returns {Response<T>} Wrapped response instance.
    */
   constructor(props?: ResponseProps<T>);
 }
@@ -430,9 +432,9 @@ type ResponseErrorProps = {
  * - Use instanceof ResponseError to distinguish FaasJS errors from other JavaScript errors
  * - The body property can contain structured error information from the server response
  *
- * @see FaasBrowserClient.action for how ResponseError is thrown in requests
- * @see ResponseProps for the structure of response data
- * @see setMock for mocking errors in tests
+ * @see {@link FaasBrowserClient.action} for how ResponseError is thrown in requests.
+ * @see {@link ResponseProps} for the structure of response data.
+ * @see {@link setMock} for mocking errors in tests.
  */
 declare class ResponseError extends Error {
   /**
@@ -454,17 +456,17 @@ declare class ResponseError extends Error {
   /**
    * Create a ResponseError from a message, Error, or structured response error payload.
    *
-   * @param data - Error message, Error object, or structured response error props.
-   * @param data.message - User-facing error message when `data` is a structured object.
-   * @param data.status - HTTP status code when `data` is a structured object.
-   * @param data.headers - Response headers returned with the error when `data` is a structured object.
-   * @param data.body - Raw error body or structured error payload when `data` is a structured object.
-   * @param data.originalError - Original error preserved on the instance when `data` is a structured object.
-   * @param options - Additional options such as status, headers, and body.
-   * @param options.status - HTTP status override used when `data` is a string or `Error`.
-   * @param options.headers - Response headers override used when `data` is a string or `Error`.
-   * @param options.body - Raw error body override used when `data` is a string or `Error`.
-   * @returns ResponseError instance.
+   * @param {string | Error | ResponseErrorProps} data - Error message, Error object, or structured response error props.
+   * @param {string} data.message - User-facing error message when `data` is a structured object.
+   * @param {number} [data.status] - HTTP status code when `data` is a structured object.
+   * @param {ResponseHeaders} [data.headers] - Response headers returned with the error when `data` is a structured object.
+   * @param {any} [data.body] - Raw error body or structured error payload when `data` is a structured object.
+   * @param {Error} [data.originalError] - Original error preserved on the instance when `data` is a structured object.
+   * @param {Omit<ResponseErrorProps, 'message' | 'originalError'>} [options] - Additional options such as status, headers, and body.
+   * @param {number} [options.status] - HTTP status override used when `data` is a string or `Error`.
+   * @param {ResponseHeaders} [options.headers] - Response headers override used when `data` is a string or `Error`.
+   * @param {any} [options.body] - Raw error body override used when `data` is a string or `Error`.
+   * @returns {ResponseError} ResponseError instance.
    */
   constructor(data: string | Error, options?: Omit<ResponseErrorProps, 'message' | 'originalError'>);
   constructor(data: ResponseErrorProps);
@@ -475,20 +477,20 @@ 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 action - The function path/action being requested (for example, `user` or `data/list`).
+ * @param {string} action - The function path/action being requested (for example, `user` or `data/list`).
  *   Converted to lowercase by the client before being passed to the handler.
  *
- * @param params - The parameters passed to the action.
+ * @param {Record<string, any> | undefined} params - The parameters passed to the action.
  *   May be undefined if the action was called without parameters.
  *   Parameters are passed as a plain object (already JSON-serialized if needed).
  *
- * @param options - The full request options including headers, beforeRequest hook, and other config.
+ * @param {Options} options - The full request options including headers, beforeRequest hook, and other config.
  *   Includes X-FaasJS-Request-Id header in the headers object.
  *   Contains merged client defaults and per-request options.
  *   See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
  *   `request`, `baseUrl`, and `stream`.
  *
- * @returns A promise resolving to:
+ * @returns {Promise<ResponseProps> | Promise<void> | Promise<Error>} 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
@@ -500,62 +502,15 @@ declare class ResponseError extends Error {
  * - Returning an Error object causes the action() method to reject with ResponseError
  * - Async function - must return a Promise
  * - Receives the fully merged options including default headers
- *
- * @example Basic mock returning data
- * ```ts
- * setMock(async (action, params, options) => {
- *   if (action === 'user') {
- *     return {
- *       status: 200,
- *       data: { id: params.id, name: 'Mock User' }
- *     }
- *   }
- *   return { status: 404, data: { error: 'Not found' } }
- * })
- * ```
- *
- * @example Conditional mock based on parameters
- * ```ts
- * setMock(async (action, params) => {
- *   if (action === 'login') {
- *     if (params.email === 'admin@example.com' && params.password === 'admin') {
- *       return { data: { token: 'admin-token', role: 'admin' } }
- *     }
- *     return { status: 401, data: { error: 'Invalid credentials' } }
- *   }
- * })
- * ```
- *
- * @example Throwing error from mock
- * ```ts
- * setMock(async (action) => {
- *   if (action === 'protected') {
- *     return new Error('Unauthorized access')
- *     // This will be wrapped in ResponseError and thrown
- *   }
- * })
- * ```
- *
- * @example Returning void for empty response
- * ```ts
- * setMock(async (action) => {
- *   if (action === 'delete') {
- *     // Return void for 204 No Content
- *     return
- *   }
- *   return { data: { success: true } }
- * })
- * ```
- *
- * @see setMock for setting up mock handlers
- * @see ResponseProps for response structure
- * @see ResponseError for error handling
+ * @see {@link setMock} for setting up mock handlers.
+ * @see {@link ResponseProps} for response structure.
+ * @see {@link ResponseError} for error handling.
  */
 type MockHandler = (action: string, params: Record<string, any> | undefined, options: Options) => Promise<ResponseProps> | Promise<void> | Promise<Error>;
 /**
  * Set the global mock handler used by all {@link FaasBrowserClient} instances.
  *
- * @param handler - Mock handler, can be:
+ * @param {MockHandler | ResponseProps | Response | null | undefined} handler - Mock handler, can be:
  *   - MockHandler function: receives (action, params, options) and returns response data
  *   - ResponseProps object: static response data
  *   - Response instance: pre-configured Response object
@@ -711,8 +666,8 @@ declare function setMock(handler: MockHandler | ResponseProps | Response | null
  *
  * @throws {Error} When baseUrl does not end with '/'
  *
- * @see setMock for testing support
- * @see ResponseError for error handling
+ * @see {@link setMock} for testing support.
+ * @see {@link ResponseError} for error handling.
  */
 declare class FaasBrowserClient {
   /**
@@ -730,8 +685,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.
-   * @param options - Default request options such as headers, hooks, request override, or stream mode.
+   * @param {BaseUrl} [baseUrl] - Base URL for all API requests. Must end with `/`. Defaults to `/` for relative requests.
+   * @param {Options} [options] - Default request options such as headers, hooks, request override, or stream mode.
    * See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
    * `request`, `baseUrl`, and `stream`.
    *
@@ -791,16 +746,16 @@ declare class FaasBrowserClient {
    * Makes a request to a FaasJS function.
    *
    * @template PathOrData - The function path or data type for type safety
-   * @param action - The function path to call. Converted to lowercase when constructing the URL.
+   * @param {FaasAction<PathOrData>} action - The function path to call. Converted to lowercase when constructing the URL.
    *   Must be a non-empty string.
-   * @param params - The parameters to send to the function. Will be serialized as JSON.
+   * @param {FaasParams<PathOrData>} [params] - The parameters to send to the function. Will be serialized as JSON.
    *   Optional if the function accepts no parameters.
-   * @param options - Optional request options that override client defaults.
+   * @param {Options} [options] - Optional request options that override client defaults.
    *   Supports headers, beforeRequest hook, custom request function, baseUrl override, and streaming mode.
    *   See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
    *   `request`, `baseUrl`, and `stream`.
    *
-   * @returns A promise resolving to the wrapped FaasJS response. When `options.stream`
+   * @returns {Promise<Response<FaasData<PathOrData>>>} A promise resolving to the wrapped FaasJS response. When `options.stream`
    *   is `true`, the runtime returns the native fetch response so callers can read the stream.
    *
    * @throws {Error} When action is not provided or is empty
@@ -902,12 +857,12 @@ declare class FaasBrowserClient {
  *
  * @template PathOrData - Action path or response data type used for inference.
  *
- * @param action - Action path to invoke.
- * @param params - Parameters sent to the action.
- * @param options - Optional per-request overrides such as headers or base URL.
- * See the request `Options` type for supported fields such as `headers`, `beforeRequest`,
+ * @param {FaasAction<PathOrData>} action - Action path to invoke.
+ * @param {FaasParams<PathOrData>} 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 Response returned by the active browser client.
+ * @returns {Promise<Response<FaasData<PathOrData>>>} Response returned by the active browser client.
  * @throws {ResponseError} When the request fails and the active client does not recover inside `onError`.
  *
  * @example
@@ -976,16 +931,16 @@ type FaasDataWrapperRef<PathOrData extends FaasActionUnionType$1 = any> = FaasDa
  * The wrapper defers rendering `children` or `render` until the first request
  * completes, then keeps passing the latest request state to the rendered output.
  *
- * @param props - Wrapper props controlling the request and rendered fallback.
- * @param props.render - Render prop that receives the resolved Faas request state.
- * @param props.children - Child element cloned with injected Faas request state.
- * @param props.fallback - Element rendered before the first successful load.
- * @param props.action - Action path to request.
- * @param props.params - Params sent to the action.
- * @param props.onDataChange - Callback invoked when the resolved data value changes.
- * @param props.data - Controlled data value used instead of internal state.
- * @param props.setData - Controlled setter used instead of internal state.
- * @param props.baseUrl - Base URL override used for this wrapper instance.
+ * @param {FaasDataWrapperProps<PathOrData>} props - Wrapper props controlling the request and rendered fallback.
+ * @param {(args: FaasDataInjection<PathOrData>) => JSX.Element | JSX.Element[]} [props.render] - Render prop that receives the resolved Faas request state.
+ * @param {React.ReactElement<Partial<FaasDataInjection<PathOrData>>>} [props.children] - Child element cloned with injected Faas request state.
+ * @param {JSX.Element | false} [props.fallback] - Element rendered before the first successful load.
+ * @param {FaasAction<PathOrData>} props.action - Action path to request.
+ * @param {FaasParams<PathOrData>} [props.params] - Params sent to the action.
+ * @param {(args: FaasDataInjection<PathOrData>) => void} [props.onDataChange] - Callback invoked when the resolved data value changes.
+ * @param {FaasData<PathOrData>} [props.data] - Controlled data value used instead of internal state.
+ * @param {React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>} [props.setData] - Controlled setter used instead of internal state.
+ * @param {BaseUrl} [props.baseUrl] - Base URL override used for this wrapper instance.
  *
  * @example
  * ```tsx
@@ -1065,9 +1020,9 @@ declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType$1 = any>(
  *
  * @template PathOrData - Action path or response data type used for inference.
  * @template TComponentProps - Component props including injected Faas data fields.
- * @param Component - Component that consumes injected Faas data props.
- * @param faasProps - Request configuration forwarded to `FaasDataWrapper`.
- * @returns Component that accepts the original props minus the injected Faas data fields.
+ * @param {React.FC<TComponentProps>} Component - Component that consumes injected Faas data props.
+ * @param {FaasDataWrapperProps<PathOrData>} faasProps - Request configuration forwarded to `FaasDataWrapper`.
+ * @returns {React.FC<Omit<TComponentProps, keyof FaasDataInjection<PathOrData>> & Record<string, any>>} Component that accepts the original props minus the injected Faas data fields.
  *
  * @example
  * ```tsx
@@ -1091,25 +1046,33 @@ 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/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 {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: Params) => boolean);
+  debounce?: number;
+  baseUrl?: BaseUrl;
+};
+//#endregion
 //#region src/useFaas.d.ts
 /**
  * Options that customize the {@link useFaas} request lifecycle.
  *
  * @template PathOrData - Action path or response data type used for inference.
  */
-type useFaasOptions<PathOrData extends FaasActionUnionType$1> = {
-  /** Override the current request params without changing the hook's stored params state. */params?: FaasParams$1<PathOrData>; /** Controlled data value used instead of the hook's internal state. */
-  data?: FaasData$1<PathOrData>; /** Controlled setter that is called instead of the hook's internal `setData`. */
-  setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
-  /**
-   * If skip is true, the request will not be sent.
-   *
-   * However, you can still use reload to send the request.
-   */
-  skip?: boolean | ((params: FaasParams$1<PathOrData>) => boolean); /** Delay the latest automatic request by the given number of milliseconds. */
-  debounce?: number; /** Override the default base URL for this hook instance. */
-  baseUrl?: BaseUrl;
-};
+type useFaasOptions<PathOrData extends FaasActionUnionType$1> = SharedUseFaasOptions<FaasParams$1<PathOrData>, FaasData$1<PathOrData>>;
 /**
  * Request FaasJS data and keep request state in React state.
  *
@@ -1119,16 +1082,11 @@ type useFaasOptions<PathOrData extends FaasActionUnionType$1> = {
  *
  * @template PathOrData - Action path or response data type used for inference.
  *
- * @param action - Action path to invoke.
- * @param defaultParams - Params used for the initial request and future reloads.
- * @param options - Optional hook configuration such as controlled data, debounce, and skip logic.
- * @param options.params - Request params override used without mutating the hook's stored params state.
- * @param options.data - Controlled data value used instead of the hook's internal state.
- * @param options.setData - Controlled setter used instead of the hook's internal `setData`.
- * @param options.skip - Boolean or predicate that suppresses the automatic request until `reload()` runs.
- * @param options.debounce - Milliseconds to wait before sending the latest request.
- * @param options.baseUrl - Base URL override used for this hook instance.
- * @returns Request state and helper methods described by {@link FaasDataInjection}.
+ * @param {FaasAction<PathOrData>} action - Action path to invoke.
+ * @param {FaasParams<PathOrData>} defaultParams - Params used for the initial request and future reloads.
+ * @param {useFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, and base URL overrides.
+ * See the `useFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+ * @returns {FaasDataInjection<PathOrData>} Request state and helper methods described by {@link FaasDataInjection}.
  *
  * @example
  * ```tsx
@@ -1167,9 +1125,9 @@ declare function useFaas<PathOrData extends FaasActionUnionType$1>(action: FaasA
 /**
  * Factory for per-request error handlers used by {@link FaasReactClient}.
  *
- * @param action - Action name that failed.
- * @param params - Params sent with the failed request.
- * @returns Async callback invoked with the resulting {@link ResponseError}.
+ * @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>;
 /**
@@ -1214,13 +1172,13 @@ type FaasReactClientInstance = {
  * The returned client is stored by `baseUrl` and becomes the default client
  * used by helpers such as {@link faas} and {@link useFaas}.
  *
- * @param options - Client configuration including base URL, default request options, and error hooks.
- * @param options.baseUrl - Base URL used to register and route the client instance.
- * @param options.options - Default browser-client request options forwarded to `FaasBrowserClient`.
- * @param options.onError - Hook factory used to handle failed `faas` and `useFaas` requests.
+ * @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 Registered FaasReactClient instance.
+ * @returns {FaasReactClientInstance} Registered FaasReactClient instance.
  *
  * @example
  * ```ts
@@ -1249,8 +1207,8 @@ declare function FaasReactClient(options?: FaasReactClientOptions): FaasReactCli
  * different base URLs. In normal single-client app code, prefer the default
  * `faas`, `useFaas`, or `FaasReactClient` setup directly.
  *
- * @param host - Registered base URL to look up. Omit it to use the default client.
- * @returns Registered or newly created FaasReactClient instance.
+ * @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
@@ -1276,7 +1234,8 @@ declare function getClient(host?: string): FaasReactClientInstance;
  * Returns a constant value that is created by the given function.
  *
  * @template T - Constant value type returned by the initializer.
- * @param fn - Initializer that runs only once for the current component instance.
+ * @param {() => T} fn - Initializer that runs only once for the current component instance.
+ * @returns {T} Stable value returned by the initializer.
  *
  * @example
  * ```tsx
@@ -1343,17 +1302,17 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
   /**
    * Create an error boundary with empty error state.
    *
-   * @param props - Boundary props.
-   * @param props.children - Descendant elements protected by the boundary.
-   * @param props.onError - Callback invoked after a render error is captured.
-   * @param props.errorChildren - Custom fallback element that receives error details.
+   * @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 - Caught render error.
-   * @param info - React component stack metadata.
+   * @param {Error} error - Caught render error.
+   * @param {ErrorInfo} info - React component stack metadata.
    */
   componentDidCatch(error: Error, info: ErrorInfo): void;
   /**
@@ -1370,9 +1329,9 @@ 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
@@ -1386,8 +1345,8 @@ 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
@@ -1404,9 +1363,9 @@ 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.
+ * @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.
  *
  * @example
  * ```tsx
@@ -1427,9 +1386,9 @@ declare function useEqualEffect(callback: React.EffectCallback, dependencies: an
  *
  * @template T - Memoized value type returned by the callback.
  *
- * @param callback - The callback function to run.
- * @param dependencies - The list of dependencies.
- * @returns The result of the `useMemo` hook with memoized dependencies.
+ * @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.
  *
  * @example
  * ```tsx
@@ -1448,9 +1407,9 @@ declare function useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
  *
  * @template T - Callback signature to memoize.
  *
- * @param callback - The callback function to run.
- * @param dependencies - The list of dependencies.
- * @returns The result of the `useCallback` hook with memoized dependencies.
+ * @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
@@ -1484,12 +1443,12 @@ type OptionalWrapperProps<TWrapper extends ComponentType<{
 /**
  * Conditionally wrap children with another component.
  *
- * @param props - Wrapper condition, wrapper component, and child content.
- * @param props.condition - When `true`, wrap children with `Wrapper`.
- * @param props.Wrapper - Component used as the wrapper when the condition passes.
- * @param props.wrapperProps - Props forwarded to the wrapper component.
- * @param props.children - Content rendered directly or inside the wrapper.
- * @returns Wrapped children or the original children when `condition` is false.
+ * @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
@@ -1520,8 +1479,8 @@ declare namespace OptionalWrapper {
  * subscribe to the values they access.
  *
  * @template T - Context value shape exposed by the provider and hook.
- * @param defaultValue - Default value map or key list used to create split contexts.
- * @returns Provider and hook helpers for the split context.
+ * @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
@@ -1565,7 +1524,7 @@ declare function createSplittingContext<T extends Record<string, any>>(defaultVa
   /**
    * The provider component of the splitting context.
    *
-   * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#provider
+   * @see [Provider docs](https://faasjs.com/doc/react/functions/createSplittingContext.html#provider)
    *
    * @example
    * ```tsx
@@ -1613,7 +1572,7 @@ declare function createSplittingContext<T extends Record<string, any>>(defaultVa
   /**
    * Hook used to read values from the splitting context.
    *
-   * @see https://faasjs.com/doc/react/functions/createSplittingContext.html#use
+   * @see [Hook docs](https://faasjs.com/doc/react/functions/createSplittingContext.html#use)
    *
    * @example
    * ```tsx
@@ -1644,8 +1603,8 @@ type StatesWithSetters<T> = T & StateSetters<T>;
  * 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 initialStates - Object whose keys become state values and `setXxx` setters.
- * @returns Object containing the original keys plus generated setter functions.
+ * @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
@@ -1662,19 +1621,7 @@ declare function useSplittingState<T extends Record<string, unknown>>(initialSta
 /**
  * Options that customize the {@link useFaasStream} request lifecycle.
  */
-type UseFaasStreamOptions = {
-  /** Override the current request params without changing the hook's stored params state. */params?: Record<string, any>; /** Controlled stream text used instead of the hook's internal state. */
-  data?: string; /** Controlled setter that is called instead of the hook's internal `setData`. */
-  setData?: React.Dispatch<React.SetStateAction<string>>;
-  /**
-   * 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); /** Delay the latest automatic request by the given number of milliseconds. */
-  debounce?: number; /** Override the default base URL for this hook instance. */
-  baseUrl?: BaseUrl;
-};
+type UseFaasStreamOptions = SharedUseFaasOptions<Record<string, any>, string>;
 /**
  * Result returned by {@link useFaasStream}.
  */
@@ -1697,16 +1644,11 @@ type UseFaasStreamResult = {
  * It sends a streaming request, appends decoded text chunks to `data`, and
  * exposes reload helpers for retrying the same action.
  *
- * @param action - Action path to invoke.
- * @param defaultParams - Params used for the initial request and future reloads.
- * @param options - Optional hook configuration such as controlled data, debounce, and skip logic.
- * @param options.params - Request params override used without mutating the hook's stored params state.
- * @param options.data - Controlled stream text used instead of the hook's internal state.
- * @param options.setData - Controlled setter used instead of the hook's internal `setData`.
- * @param options.skip - Boolean or predicate that suppresses the automatic request until `reload()` runs.
- * @param options.debounce - Milliseconds to wait before sending the latest request.
- * @param options.baseUrl - Base URL override used for this hook instance.
- * @returns Streaming request state and helper methods described by {@link UseFaasStreamResult}.
+ * @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, and base URL overrides.
+ * See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+ * @returns {UseFaasStreamResult} Streaming request state and helper methods described by {@link UseFaasStreamResult}.
  *
  * @example
  * ```tsx
@@ -1739,8 +1681,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 value - The current value to track.
- * @returns Previous value from the prior render, or `undefined` on the first render.
+ * @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
@@ -1760,8 +1702,8 @@ 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 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.
+ * @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