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

package/dist/index.cjs

@@ -36,9 +36,6 @@ function generateId(prefix = "", length = 18) {
 * @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
@@ -142,6 +139,12 @@ var Response = class {
 	headers;
 	body;
 	data;
+	/**
+	* Create a wrapped response object.
+	*
+	* @param props - Response properties including status, headers, body, and data.
+	* @returns Wrapped response instance.
+	*/
 	constructor(props = {}) {
 		this.status = props.status || (props.data || props.body ? 200 : 204);
 		this.headers = props.headers || {};
@@ -156,7 +159,6 @@ var Response = class {
 * 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.
@@ -164,9 +166,6 @@ var Response = class {
 * @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')
@@ -255,6 +254,13 @@ var ResponseError = class extends Error {
 	headers;
 	body;
 	originalError;
+	/**
+	* Create a ResponseError from a message, Error, or structured response error payload.
+	*
+	* @param data - Error message, Error object, or structured response error props.
+	* @param options - Additional options such as status, headers, and body.
+	* @returns ResponseError instance.
+	*/
 	constructor(data, options) {
 		let props;
 		if (typeof data === "string") props = {
@@ -406,11 +412,8 @@ var FaasBrowserClient = class {
 	/**
 	* 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
@@ -461,7 +464,7 @@ var FaasBrowserClient = class {
 	* })
 	* ```
 	*
-	* @throws {Error} When baseUrl does not end with '/'
+	* @throws {Error} When `baseUrl` does not end with `/`
 	*/
 	constructor(baseUrl = "/", options = Object.create(null)) {
 		if (baseUrl && !baseUrl.endsWith("/")) throw Error("[FaasJS] baseUrl should end with /");
@@ -486,7 +489,7 @@ var FaasBrowserClient = class {
 	*
 	* @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
@@ -540,11 +543,7 @@ var FaasBrowserClient = class {
 	*   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
 	* ```
 	*
@@ -556,7 +555,7 @@ var FaasBrowserClient = class {
 	* } 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)
 	*   }
@@ -662,17 +661,20 @@ var FaasBrowserClient = class {
 //#endregion
 //#region src/faas.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)
 * ```
 */
 async function faas(action, params, options) {
@@ -831,16 +833,23 @@ function withFaasData(Component, faasProps) {
 //#endregion
 //#region src/useFaas.tsx
 /**
-* Request faas server with React hook
+* Request FaasJS data and keep request state in React state.
 *
-* @param action {string} action name
-* @param defaultParams {object} initial action params
-* @returns {FaasDataInjection<any>}
+* `useFaas` sends an initial request unless `skip` is enabled, and returns
+* request state plus helpers for reloading, updating data, and handling errors.
+*
+* @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>
 * }
 * ```
@@ -960,14 +969,20 @@ function useFaas(action, defaultParams, options = {}) {
 //#region src/client.tsx
 const clients = {};
 /**
-* 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}.
 *
-* @returns FaasReactClient instance.
+* @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/',
 * })
 * ```
 */
@@ -996,16 +1011,20 @@ function FaasReactClient({ baseUrl, options: clientOptions, onError } = { baseUr
 	return reactClient;
 }
 /**
-* 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/')
 * ```
 */
 function getClient(host) {
@@ -1066,23 +1085,25 @@ var ErrorBoundary = class extends react.Component {
 * 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>
+*   )
+* }
+* ```
 */
 function useStateRef(initialValue) {
 	const [state, setState] = (0, react.useState)(initialValue ?? null);
@@ -1099,15 +1120,16 @@ function useStateRef(initialValue) {
 //#endregion
 //#region src/splittingState.tsx
 /**
-* 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,32 +1424,29 @@ function mergeValues(items, defaultValues = {}) {
 	return values;
 }
 /**
-* 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.
+* Render a form with context, default elements, and validation state.
+*
+* `FormContainer` merges provided elements, language strings, and rules with
+* the package defaults, then exposes them through form context.
 *
 * @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.
+* @param props - Form items and optional overrides for defaults, language, rules, and submit behavior.
+* @returns React form container with shared form context.
 *
 * @example
 * ```tsx
 * import { Form } from '@faasjs/react'
 *
 * function MyForm() {
-*   return <Form
-*     items={[
-*       { name: 'name' },
-*     ]}
-*   />
+*   return (
+*     <Form
+*       items={[
+*         { name: 'name' },
+*       ]}
+*     />
+*   )
 * }
 * ```
 */
@@ -1484,14 +1503,21 @@ OptionalWrapper.displayName = "OptionalWrapper";
 //#endregion
 //#region src/useFaasStream.tsx
 /**
-* Stream faas server response with React hook
+* Stream a FaasJS response into React state.
 *
-* @param action {string} action name
-* @param defaultParams {object} initial action params
-* @returns {UseFaasStreamResult}
+* The hook sends a streaming request, appends decoded text chunks to `data`,
+* and exposes reload helpers for retrying the same action.
+*
+* @param action - Action path to invoke.
+* @param defaultParams - Params used for the initial request and future reloads.
+* @param options - Optional hook configuration such as controlled data, debounce, and skip logic.
+* @returns Streaming request state and helper methods.
 *
 * @example
 * ```tsx
+* import { useState } from 'react'
+* import { useFaasStream } from '@faasjs/react'
+*
 * function Chat() {
 *   const [prompt, setPrompt] = useState('')
 *   const { data, loading, reload } = useFaasStream('chat', { prompt })
@@ -1632,8 +1658,8 @@ function useFaasStream(action, defaultParams, options = {}) {
 * 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.
 */
 function usePrevious(value) {
 	const ref = (0, react.useRef)(void 0);

package/dist/index.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.
  *
- * @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.
+ *
+ * @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;
@@ -1172,32 +1194,29 @@ type FormProps<Values extends Record<string, any> = Record<string, any>, FormEle
   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.
+ * Render a form with context, default elements, and validation state.
+ *
+ * `FormContainer` merges provided elements, language strings, and rules with
+ * the package defaults, then exposes them through form context.
  *
  * @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.
+ * @param props - Form items and optional overrides for defaults, language, rules, and submit behavior.
+ * @returns React form container with shared form context.
  *
  * @example
  * ```tsx
  * import { Form } from '@faasjs/react'
  *
  * function MyForm() {
- *   return <Form
- *     items={[
- *       { name: 'name' },
- *     ]}
- *   />
+ *   return (
+ *     <Form
+ *       items={[
+ *         { name: 'name' },
+ *       ]}
+ *     />
+ *   )
  * }
  * ```
  */
@@ -1385,15 +1404,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 +1422,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 +1435,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 +1454,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 +1490,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,23 +1500,25 @@ 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

package/dist/index.mjs

@@ -35,9 +35,6 @@ function generateId(prefix = "", length = 18) {
 * @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
@@ -141,6 +138,12 @@ var Response = class {
 	headers;
 	body;
 	data;
+	/**
+	* Create a wrapped response object.
+	*
+	* @param props - Response properties including status, headers, body, and data.
+	* @returns Wrapped response instance.
+	*/
 	constructor(props = {}) {
 		this.status = props.status || (props.data || props.body ? 200 : 204);
 		this.headers = props.headers || {};
@@ -155,7 +158,6 @@ var Response = class {
 * 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.
@@ -163,9 +165,6 @@ var Response = class {
 * @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')
@@ -254,6 +253,13 @@ var ResponseError = class extends Error {
 	headers;
 	body;
 	originalError;
+	/**
+	* Create a ResponseError from a message, Error, or structured response error payload.
+	*
+	* @param data - Error message, Error object, or structured response error props.
+	* @param options - Additional options such as status, headers, and body.
+	* @returns ResponseError instance.
+	*/
 	constructor(data, options) {
 		let props;
 		if (typeof data === "string") props = {
@@ -405,11 +411,8 @@ var FaasBrowserClient = class {
 	/**
 	* 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
@@ -460,7 +463,7 @@ var FaasBrowserClient = class {
 	* })
 	* ```
 	*
-	* @throws {Error} When baseUrl does not end with '/'
+	* @throws {Error} When `baseUrl` does not end with `/`
 	*/
 	constructor(baseUrl = "/", options = Object.create(null)) {
 		if (baseUrl && !baseUrl.endsWith("/")) throw Error("[FaasJS] baseUrl should end with /");
@@ -485,7 +488,7 @@ var FaasBrowserClient = class {
 	*
 	* @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
@@ -539,11 +542,7 @@ var FaasBrowserClient = class {
 	*   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
 	* ```
 	*
@@ -555,7 +554,7 @@ var FaasBrowserClient = class {
 	* } 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)
 	*   }
@@ -661,17 +660,20 @@ var FaasBrowserClient = class {
 //#endregion
 //#region src/faas.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)
 * ```
 */
 async function faas(action, params, options) {
@@ -827,16 +829,23 @@ function withFaasData(Component, faasProps) {
 //#endregion
 //#region src/useFaas.tsx
 /**
-* Request faas server with React hook
+* Request FaasJS data and keep request state in React state.
 *
-* @param action {string} action name
-* @param defaultParams {object} initial action params
-* @returns {FaasDataInjection<any>}
+* `useFaas` sends an initial request unless `skip` is enabled, and returns
+* request state plus helpers for reloading, updating data, and handling errors.
+*
+* @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>
 * }
 * ```
@@ -956,14 +965,20 @@ function useFaas(action, defaultParams, options = {}) {
 //#region src/client.tsx
 const clients = {};
 /**
-* 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}.
 *
-* @returns FaasReactClient instance.
+* @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/',
 * })
 * ```
 */
@@ -992,16 +1007,20 @@ function FaasReactClient({ baseUrl, options: clientOptions, onError } = { baseUr
 	return reactClient;
 }
 /**
-* 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/')
 * ```
 */
 function getClient(host) {
@@ -1062,23 +1081,25 @@ var ErrorBoundary = class extends Component {
 * 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>
+*   )
+* }
+* ```
 */
 function useStateRef(initialValue) {
 	const [state, setState] = useState(initialValue ?? null);
@@ -1095,15 +1116,16 @@ function useStateRef(initialValue) {
 //#endregion
 //#region src/splittingState.tsx
 /**
-* 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}</>
 * }
@@ -1398,32 +1420,29 @@ function mergeValues(items, defaultValues = {}) {
 	return values;
 }
 /**
-* 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.
+* Render a form with context, default elements, and validation state.
+*
+* `FormContainer` merges provided elements, language strings, and rules with
+* the package defaults, then exposes them through form context.
 *
 * @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.
+* @param props - Form items and optional overrides for defaults, language, rules, and submit behavior.
+* @returns React form container with shared form context.
 *
 * @example
 * ```tsx
 * import { Form } from '@faasjs/react'
 *
 * function MyForm() {
-*   return <Form
-*     items={[
-*       { name: 'name' },
-*     ]}
-*   />
+*   return (
+*     <Form
+*       items={[
+*         { name: 'name' },
+*       ]}
+*     />
+*   )
 * }
 * ```
 */
@@ -1480,14 +1499,21 @@ OptionalWrapper.displayName = "OptionalWrapper";
 //#endregion
 //#region src/useFaasStream.tsx
 /**
-* Stream faas server response with React hook
+* Stream a FaasJS response into React state.
 *
-* @param action {string} action name
-* @param defaultParams {object} initial action params
-* @returns {UseFaasStreamResult}
+* The hook sends a streaming request, appends decoded text chunks to `data`,
+* and exposes reload helpers for retrying the same action.
+*
+* @param action - Action path to invoke.
+* @param defaultParams - Params used for the initial request and future reloads.
+* @param options - Optional hook configuration such as controlled data, debounce, and skip logic.
+* @returns Streaming request state and helper methods.
 *
 * @example
 * ```tsx
+* import { useState } from 'react'
+* import { useFaasStream } from '@faasjs/react'
+*
 * function Chat() {
 *   const [prompt, setPrompt] = useState('')
 *   const { data, loading, reload } = useFaasStream('chat', { prompt })
@@ -1628,8 +1654,8 @@ function useFaasStream(action, defaultParams, options = {}) {
 * 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.
 */
 function usePrevious(value) {
 	const ref = useRef(void 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faasjs/react",
-  "version": "8.0.0-beta.15",
+  "version": "8.0.0-beta.16",
   "homepage": "https://faasjs.com/doc/react/",
   "bugs": {
     "url": "https://github.com/faasjs/faasjs/issues"
@@ -27,12 +27,12 @@
     }
   },
   "devDependencies": {
-    "@faasjs/types": ">=8.0.0-beta.15",
+    "@faasjs/types": ">=8.0.0-beta.16",
     "@types/react": "^19.0.0",
     "react": "^19.0.0"
   },
   "peerDependencies": {
-    "@faasjs/types": ">=8.0.0-beta.15"
+    "@faasjs/types": ">=8.0.0-beta.16"
   },
   "engines": {
     "node": ">=24.0.0",