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

package/README.md

@@ -1,46 +1,5 @@
 # @faasjs/react
 
-React plugin for FaasJS.
-
-[![License: MIT](https://img.shields.io/npm/l/@faasjs/react.svg)](https://github.com/faasjs/faasjs/blob/main/packages/react/LICENSE)
-[![NPM Version](https://img.shields.io/npm/v/@faasjs/react.svg)](https://www.npmjs.com/package/@faasjs/react)
-
-Includes browser client utilities (`FaasBrowserClient`, `ResponseError`, `setMock`) and React helpers.
-
-## Features
-
-- Support [FaasJS Request Specifications](https://faasjs.com/guide/request-spec.html).
-- Support global and per-request configurations.
-- Compatible with [why-did-you-render](https://github.com/welldone-software/why-did-you-render).
-- Additional React functions:
-  - Utils:
-    - `equal`: Compare two values for deep equality.
-    - `createSplittingContext`: Create a context for code splitting.
-    - `useSplittingState`: Create splitting states.
-  - Hooks:
-    - `useEqualMemoize`: Memoize a value with deep equality.
-    - `useEqualEffect`: Run an effect with deep equality.
-    - `useEqualMemo`: Memoize a value with deep equality.
-    - `useEqualCallback`: Memoize a callback with deep equality.
-    - `useConstant`: Create a constant value with hooks.
-    - `usePrevious`: Get the previous value of a state.
-    - `useStateRef`: Create a state with a ref.
-  - Components:
-    - `OptionalWrapper`: Render a component optionally.
-    - `ErrorBoundary`: Catch errors in the component tree.
-  - Fetch Data:
-    - `faas`: Fetch data from FaasJS.
-    - `useFaas`: Fetch data from FaasJS with hooks.
-    - `useFaasStream`: Fetch streaming data from FaasJS with hooks.
-    - `FaasDataWrapper`: Fetch data from FaasJS with a wrapper component.
-    - `withFaasData`: Fetch data from FaasJS using a higher-order component (HOC).
-
-## Install
-
-```sh
-npm install @faasjs/react react
-```
-
 ## Functions
 
 - [createSplittingContext](functions/createSplittingContext.md)

package/dist/index.cjs

@@ -36,10 +36,7 @@ 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.
-*
-* @remarks
+* Notes:
 * - status defaults to 200 if data or body is present, 204 otherwise
 * - body is automatically populated from data if not explicitly provided
 * - headers defaults to an empty object if not provided
@@ -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,17 +159,13 @@ 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
-* @extends {Error}
+* @augments Error
 *
 * @property {number} status - The HTTP status code of the failed response. Defaults to 500 if not provided.
 * @property {ResponseHeaders} headers - The response headers from the failed request.
 * @property {any} body - The response body containing error details or the original error if available.
 * @property {Error} [originalError] - The original Error object if this ResponseError was created from another Error.
 *
-* @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')
@@ -238,7 +237,7 @@ var Response = class {
 * })
 * ```
 *
-* @remarks
+* Notes:
 * - ResponseError is automatically thrown by the action method when the server returns an error (status >= 400)
 * - The error message from server responses is extracted from body.error.message if available
 * - When created from an Error object, the original error is preserved in the originalError property
@@ -255,13 +254,20 @@ 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 = {
 			message: data,
 			...options
 		};
-		else if (data instanceof Error || data?.constructor?.name?.includes("Error")) props = {
+		else if (data instanceof Error || typeof data === "object" && data !== null && typeof data.constructor?.name === "string" && data.constructor.name.includes("Error")) props = {
 			message: data.message,
 			originalError: data,
 			...options
@@ -344,7 +350,7 @@ function setMock(handler) {
 * - Streaming support for large responses
 * - Multiple instance support with unique IDs
 *
-* @remarks
+* Notes:
 * - All requests are POST requests by default
 * - Automatically adds X-FaasJS-Request-Id header for request tracking
 * - baseUrl must end with '/' (will throw Error if not)
@@ -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,9 +489,9 @@ 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
 	*
-	* @remarks
+	* Notes:
 	* - All requests are POST requests by default
 	* - Action path is automatically converted to lowercase
 	* - A unique request ID is generated for each request and sent in X-FaasJS-Request-Id header
@@ -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)
 	*   }
@@ -647,7 +646,7 @@ var FaasBrowserClient = class {
 						headers,
 						body
 					}));
-				} catch (_) {
+				} catch {
 					return Promise.reject(new ResponseError({
 						message: res,
 						status: response.status,
@@ -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) {
@@ -733,13 +735,18 @@ function equal(a, b) {
 * @returns The memoized value.
 */
 function useEqualMemoize(value) {
+	const ref = (0, react.useRef)(value);
+	if (!equal(value, ref.current)) ref.current = value;
+	return ref.current;
+}
+function useEqualSignal(value) {
 	const ref = (0, react.useRef)(value);
 	const signalRef = (0, react.useRef)(0);
 	if (!equal(value, ref.current)) {
 		ref.current = value;
 		signalRef.current += 1;
 	}
-	return (0, react.useMemo)(() => ref.current, [signalRef.current]);
+	return signalRef.current;
 }
 /**
 * Custom hook that works like `useEffect` but uses deep comparison on dependencies.
@@ -749,7 +756,7 @@ function useEqualMemoize(value) {
 * @returns The result of the `useEffect` hook with memoized dependencies.
 */
 function useEqualEffect(callback, dependencies) {
-	return (0, react.useEffect)(callback, useEqualMemoize(dependencies));
+	return (0, react.useEffect)(callback, [useEqualSignal(dependencies)]);
 }
 /**
 * Custom hook that works like `useMemo` but uses deep comparison on dependencies.
@@ -759,7 +766,12 @@ function useEqualEffect(callback, dependencies) {
 * @returns The result of the `useMemo` hook with memoized dependencies.
 */
 function useEqualMemo(callback, dependencies) {
-	return (0, react.useMemo)(callback, useEqualMemoize(dependencies));
+	const signal = useEqualSignal(dependencies);
+	const callbackRef = (0, react.useRef)(callback);
+	callbackRef.current = callback;
+	return (0, react.useMemo)(() => {
+		return callbackRef.current();
+	}, [signal]);
 }
 /**
 * Custom hook that works like `useCallback` but uses deep comparison on dependencies.
@@ -769,7 +781,7 @@ function useEqualMemo(callback, dependencies) {
 * @returns The result of the `useCallback` hook with memoized dependencies.
 */
 function useEqualCallback(callback, dependencies) {
-	return (0, react.useCallback)((...args) => callback(...args), useEqualMemoize(dependencies));
+	return (0, react.useCallback)((...args) => callback(...args), [useEqualSignal(dependencies)]);
 }
 //#endregion
 //#region src/FaasDataWrapper.tsx
@@ -821,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.
+*
+* `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>
 * }
 * ```
@@ -871,7 +890,8 @@ function useFaas(action, defaultParams, options = {}) {
 				const nextData = r.data;
 				setFails(0);
 				setError(null);
-				options.setData ? options.setData(nextData) : localSetData(nextData);
+				if (options.setData) options.setData(nextData);
+				else localSetData(nextData);
 				setLoading(false);
 				for (const { resolve } of pendingReloadsRef.current.values()) resolve(nextData);
 				pendingReloadsRef.current.clear();
@@ -949,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/',
 * })
 * ```
 */
@@ -985,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) {
@@ -1055,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);
@@ -1088,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}</>
 * }
@@ -1349,34 +1382,30 @@ async function validValues(rules, items, values, lang) {
 //#region src/Form/Footer.tsx
 function FormFooter() {
 	const { submitting, setSubmitting, onSubmit, valuesRef, Elements, items, setErrors, lang, rules } = useFormContext();
-	const handleSubmit = (0, react.useCallback)(async () => {
-		setSubmitting(true);
-		setErrors({});
-		const errors = await validValues(rules, items, valuesRef.current, lang);
-		if (Object.keys(errors).length) {
-			setErrors(errors);
-			setSubmitting(false);
-			return;
-		}
-		onSubmit(valuesRef.current).finally(() => setSubmitting(false));
-	}, [
-		setSubmitting,
-		setErrors,
-		rules,
-		items,
-		lang,
-		onSubmit
-	]);
-	return (0, react.useMemo)(() => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Elements.Button, {
+	const Button = Elements.Button;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
 		submitting,
-		submit: handleSubmit,
+		submit: (0, react.useCallback)(async () => {
+			setSubmitting(true);
+			setErrors({});
+			const errors = await validValues(rules, items, valuesRef.current, lang);
+			if (Object.keys(errors).length) {
+				setErrors(errors);
+				setSubmitting(false);
+				return;
+			}
+			onSubmit(valuesRef.current).finally(() => setSubmitting(false));
+		}, [
+			setSubmitting,
+			setErrors,
+			rules,
+			items,
+			valuesRef,
+			lang,
+			onSubmit
+		]),
 		children: lang.submit
-	}), [
-		submitting,
-		handleSubmit,
-		lang.submit,
-		Elements.Button
-	]);
+	});
 }
 FormFooter.displayName = "FormFooter";
 //#endregion
@@ -1395,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' },
+*       ]}
+*     />
+*   )
 * }
 * ```
 */
@@ -1477,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 })
@@ -1625,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);