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

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.
 *
-* @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/',
 * })
 * ```
 */
@@ -996,16 +1011,20 @@ function FaasReactClient({ baseUrl, options: clientOptions, onError } = { baseUr
 	return reactClient;
 }
 /**
-* 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/')
 * ```
 */
 function getClient(host) {
@@ -1061,53 +1080,46 @@ var ErrorBoundary = class extends react.Component {
 	}
 };
 //#endregion
-//#region src/useStateRef.ts
+//#region src/OptionalWrapper.tsx
 /**
-* 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.
+* A wrapper component that conditionally wraps its children with a provided wrapper component.
 *
 * @example
 * ```tsx
-* import { useStateRef } from '@faasjs/react'
+* import { OptionalWrapper } 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 Wrapper = ({ children }: { children: React.ReactNode }) => (
+*   <div className='wrapper'>{children}</div>
+* )
+*
+* const App = () => (
+*   <OptionalWrapper condition={true} Wrapper={Wrapper}>
+*     <span>Test</span>
+*   </OptionalWrapper>
 * )
+* ```
 */
-function useStateRef(initialValue) {
-	const [state, setState] = (0, react.useState)(initialValue ?? null);
-	const ref = (0, react.useRef)(state);
-	(0, react.useEffect)(() => {
-		ref.current = state;
-	}, [state]);
-	return [
-		state,
-		setState,
-		ref
-	];
+function OptionalWrapper({ condition, Wrapper, wrapperProps, children }) {
+	if (condition) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Wrapper, {
+		...wrapperProps,
+		children
+	});
+	return children;
 }
+OptionalWrapper.displayName = "OptionalWrapper";
 //#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}</>
 * }
@@ -1207,291 +1219,23 @@ function createSplittingContext(defaultValue) {
 	};
 }
 //#endregion
-//#region src/Form/context.tsx
-const FormContext = createSplittingContext([
-	"items",
-	"onSubmit",
-	"Elements",
-	"lang",
-	"rules",
-	"submitting",
-	"setSubmitting",
-	"values",
-	"setValues",
-	"errors",
-	"setErrors",
-	"valuesRef"
-]);
-const FormContextProvider = FormContext.Provider;
-const useFormContext = FormContext.use;
-//#endregion
-//#region src/Form/Input.tsx
-function processValue(input, rules) {
-	switch (rules?.type) {
-		case "number": return Number(input);
-		case "string": return String(input);
-		default: return input;
-	}
-}
-function FormInput({ name, rules, ...rest }) {
-	const { Elements, values, setValues } = useFormContext();
-	const value = values?.[name];
-	if (rest.Input) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(rest.Input, {
-		name,
-		value,
-		onChange: (v) => setValues((prev) => ({
-			...prev,
-			[name]: processValue(v, rules)
-		})),
-		...rest.props
-	});
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Elements.Input, {
-		name,
-		value,
-		onChange: (v) => setValues((prev) => ({
-			...prev,
-			[name]: processValue(v, rules)
-		})),
-		...rest.props
-	});
-}
-FormInput.displayName = "FormInput";
-//#endregion
-//#region src/Form/Item.tsx
-function FormItem(props) {
-	const { Elements, errors } = useFormContext();
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(props.label?.Label ?? Elements.Label, {
-		name: props.name,
-		...props.label,
-		error: errors[props.name],
-		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FormInput, {
-			name: props.name,
-			...props.input,
-			...props.rules ? { rules: props.rules } : {}
-		})
-	});
-}
-FormItem.displayName = "FormItem";
-//#endregion
-//#region src/Form/Body.tsx
-function FormBody() {
-	const { items } = useFormContext();
-	return items.map((item) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FormItem, { ...item }, item.name));
-}
-FormBody.displayName = "FormBody";
-//#endregion
-//#region src/Form/elements/Button.tsx
-const FormButtonElement = (0, react.forwardRef)(({ children, submit, submitting, ...props }, ref) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-	type: "button",
-	disabled: submitting,
-	onClick: submit,
-	...props,
-	ref,
-	children
-}));
-FormButtonElement.displayName = "FormButtonElement";
-//#endregion
-//#region src/Form/elements/Input.tsx
-const FormInputElement = (0, react.forwardRef)(({ onChange, ...props }, ref) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-	...props,
-	onChange: (e) => onChange(e.target.value),
-	ref
-}));
-FormInputElement.displayName = "FormInputElement";
-//#endregion
-//#region src/Form/elements/Label.tsx
-const FormLabelElement = ({ name, title, description, error, children }) => {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", { children: [
-		title ?? name,
-		children,
-		description,
-		error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-			style: { color: "red" },
-			children: error.message
-		})
-	] });
-};
-FormLabelElement.displayName = "FormLabelElement";
-//#endregion
-//#region src/Form/elements/index.ts
-const FormDefaultElements = {
-	Label: FormLabelElement,
-	Input: FormInputElement,
-	Button: FormButtonElement
-};
-//#endregion
-//#region src/Form/rules.ts
-/**
-* Default validation rules for a form.
-*/
-const FormDefaultRules = {
-	required: async (value, _, lang) => {
-		if (value === null || value === void 0 || value === "" || Number.isNaN(value)) throw Error(lang?.required);
-	},
-	type: async (value, options, lang) => {
-		switch (options) {
-			case "string":
-				if (typeof value !== "string") throw Error(lang?.string);
-				break;
-			case "number":
-				if (Number.isNaN(Number(value))) throw Error(lang?.number);
-				break;
-		}
-	},
-	custom: async (value, options) => {
-		return options(value);
-	}
-};
-async function validValues(rules, items, values, lang) {
-	const errors = {};
-	for (const item of items) {
-		const value = values[item.name];
-		const rulesOptions = item.rules;
-		if (rulesOptions) for (const [name, options] of Object.entries(rulesOptions)) try {
-			await rules[name](value, options, lang);
-		} catch (error) {
-			errors[item.name] = error;
-			break;
-		}
-	}
-	return errors;
-}
-//#endregion
-//#region src/Form/Footer.tsx
-function FormFooter() {
-	const { submitting, setSubmitting, onSubmit, valuesRef, Elements, items, setErrors, lang, rules } = useFormContext();
-	const Button = Elements.Button;
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Button, {
-		submitting,
-		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
-	});
-}
-FormFooter.displayName = "FormFooter";
-//#endregion
-//#region src/Form/lang.ts
-const FormDefaultLang = {
-	submit: "Submit",
-	required: "This field is required",
-	string: "This field must be a string",
-	number: "This field must be a number"
-};
-//#endregion
-//#region src/Form/Container.tsx
-function mergeValues(items, defaultValues = {}) {
-	const values = {};
-	for (const item of items) values[item.name] = defaultValues[item.name] ?? "";
-	return values;
-}
+//#region src/useFaasStream.tsx
 /**
-* FormContainer component is a wrapper that provides context and state management for form elements.
-* It initializes form states such as values, errors, submitting status, elements, language, and rules.
-*
-* @template Values - The type of form values, defaults to Record<string, any>.
-* @template FormElements - The type of form elements, defaults to FormElementTypes.
-* @template Rules - The type of form rules, defaults to FormDefaultRules.
+* Stream a FaasJS response into React state.
 *
-* @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.
+* The hook sends a streaming request, appends decoded text chunks to `data`,
+* and exposes reload helpers for retrying the same action.
 *
-* @returns {JSX.Element} The FormContainer component.
+* @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 { Form } from '@faasjs/react'
-*
-* function MyForm() {
-*   return <Form
-*     items={[
-*       { name: 'name' },
-*     ]}
-*   />
-* }
-* ```
-*/
-function FormContainer({ defaultValues, Elements, rules, lang, items, ...props }) {
-	const [values, setValues, valuesRef] = useStateRef(mergeValues(items, defaultValues));
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(FormContextProvider, {
-		initializeStates: {
-			errors: {},
-			submitting: false
-		},
-		value: {
-			Elements: Object.assign(FormDefaultElements, Elements),
-			lang: Object.assign(FormDefaultLang, lang),
-			rules: Object.assign(FormDefaultRules, rules),
-			items,
-			values,
-			setValues,
-			valuesRef,
-			...props
-		},
-		memo: true,
-		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(FormBody, {}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FormFooter, {})]
-	});
-}
-FormContainer.displayName = "FormContainer";
-//#endregion
-//#region src/OptionalWrapper.tsx
-/**
-* A wrapper component that conditionally wraps its children with a provided wrapper component.
-*
-* @example
-* ```tsx
-* import { OptionalWrapper } from '@faasjs/react'
-*
-* const Wrapper = ({ children }: { children: React.ReactNode }) => (
-*   <div className='wrapper'>{children}</div>
-* )
-*
-* const App = () => (
-*   <OptionalWrapper condition={true} Wrapper={Wrapper}>
-*     <span>Test</span>
-*   </OptionalWrapper>
-* )
-* ```
-*/
-function OptionalWrapper({ condition, Wrapper, wrapperProps, children }) {
-	if (condition) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Wrapper, {
-		...wrapperProps,
-		children
-	});
-	return children;
-}
-OptionalWrapper.displayName = "OptionalWrapper";
-//#endregion
-//#region src/useFaasStream.tsx
-/**
-* Stream faas server response with React hook
+* import { useState } from 'react'
+* import { useFaasStream } from '@faasjs/react'
 *
-* @param action {string} action name
-* @param defaultParams {object} initial action params
-* @returns {UseFaasStreamResult}
-*
-* @example
-* ```tsx
 * function Chat() {
 *   const [prompt, setPrompt] = useState('')
 *   const { data, loading, reload } = useFaasStream('chat', { prompt })
@@ -1632,8 +1376,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);
@@ -1643,17 +1387,48 @@ function usePrevious(value) {
 	return ref.current;
 }
 //#endregion
+//#region src/useStateRef.ts
+/**
+* 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.
+*
+* @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>
+*   )
+* }
+* ```
+*/
+function useStateRef(initialValue) {
+	const [state, setState] = (0, react.useState)(initialValue ?? null);
+	const ref = (0, react.useRef)(state);
+	(0, react.useEffect)(() => {
+		ref.current = state;
+	}, [state]);
+	return [
+		state,
+		setState,
+		ref
+	];
+}
+//#endregion
 exports.ErrorBoundary = ErrorBoundary;
 exports.FaasBrowserClient = FaasBrowserClient;
 exports.FaasDataWrapper = FaasDataWrapper;
 exports.FaasReactClient = FaasReactClient;
-exports.Form = FormContainer;
-exports.FormContextProvider = FormContextProvider;
-exports.FormDefaultElements = FormDefaultElements;
-exports.FormDefaultLang = FormDefaultLang;
-exports.FormDefaultRules = FormDefaultRules;
-exports.FormInput = FormInput;
-exports.FormItem = FormItem;
 exports.OptionalWrapper = OptionalWrapper;
 exports.Response = Response;
 exports.ResponseError = ResponseError;
@@ -1670,9 +1445,7 @@ exports.useEqualMemo = useEqualMemo;
 exports.useEqualMemoize = useEqualMemoize;
 exports.useFaas = useFaas;
 exports.useFaasStream = useFaasStream;
-exports.useFormContext = useFormContext;
 exports.usePrevious = usePrevious;
 exports.useSplittingState = useSplittingState;
 exports.useStateRef = useStateRef;
-exports.validValues = validValues;
 exports.withFaasData = withFaasData;