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

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.
 *
-* @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/',
 * })
 * ```
 */
@@ -992,16 +1007,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) {
@@ -1057,53 +1076,46 @@ var ErrorBoundary = class extends 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] = useState(initialValue ?? null);
-	const ref = useRef(state);
-	useEffect(() => {
-		ref.current = state;
-	}, [state]);
-	return [
-		state,
-		setState,
-		ref
-	];
+function OptionalWrapper({ condition, Wrapper, wrapperProps, children }) {
+	if (condition) return /* @__PURE__ */ 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}</>
 * }
@@ -1203,291 +1215,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__ */ jsx(rest.Input, {
-		name,
-		value,
-		onChange: (v) => setValues((prev) => ({
-			...prev,
-			[name]: processValue(v, rules)
-		})),
-		...rest.props
-	});
-	return /* @__PURE__ */ 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__ */ jsx(props.label?.Label ?? Elements.Label, {
-		name: props.name,
-		...props.label,
-		error: errors[props.name],
-		children: /* @__PURE__ */ 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__ */ jsx(FormItem, { ...item }, item.name));
-}
-FormBody.displayName = "FormBody";
-//#endregion
-//#region src/Form/elements/Button.tsx
-const FormButtonElement = forwardRef(({ children, submit, submitting, ...props }, ref) => /* @__PURE__ */ jsx("button", {
-	type: "button",
-	disabled: submitting,
-	onClick: submit,
-	...props,
-	ref,
-	children
-}));
-FormButtonElement.displayName = "FormButtonElement";
-//#endregion
-//#region src/Form/elements/Input.tsx
-const FormInputElement = forwardRef(({ onChange, ...props }, ref) => /* @__PURE__ */ 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__ */ jsxs("label", { children: [
-		title ?? name,
-		children,
-		description,
-		error && /* @__PURE__ */ 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__ */ jsx(Button, {
-		submitting,
-		submit: 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__ */ 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__ */ jsx(FormBody, {}), /* @__PURE__ */ 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__ */ 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 })
@@ -1628,8 +1372,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);
@@ -1639,4 +1383,42 @@ function usePrevious(value) {
 	return ref.current;
 }
 //#endregion
-export { ErrorBoundary, FaasBrowserClient, FaasDataWrapper, FaasReactClient, FormContainer as Form, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormInput, FormItem, OptionalWrapper, Response, ResponseError, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+//#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] = useState(initialValue ?? null);
+	const ref = useRef(state);
+	useEffect(() => {
+		ref.current = state;
+	}, [state]);
+	return [
+		state,
+		setState,
+		ref
+	];
+}
+//#endregion
+export { ErrorBoundary, FaasBrowserClient, FaasDataWrapper, FaasReactClient, OptionalWrapper, Response, ResponseError, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, usePrevious, useSplittingState, useStateRef, withFaasData };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faasjs/react",
-  "version": "8.0.0-beta.15",
+  "version": "8.0.0-beta.17",
   "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.17",
     "@types/react": "^19.0.0",
     "react": "^19.0.0"
   },
   "peerDependencies": {
-    "@faasjs/types": ">=8.0.0-beta.15"
+    "@faasjs/types": ">=8.0.0-beta.17"
   },
   "engines": {
     "node": ">=24.0.0",