@faasjs/react 8.0.0-beta.33 → 8.0.0-beta.35

package/dist/index.d.ts

@@ -1,6 +1,4 @@
-import * as _$react from "react";
 import { Component, ComponentProps, ComponentType, Dispatch, ErrorInfo, JSX, ReactElement, ReactNode, RefObject, SetStateAction } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { FaasActionPaths, FaasData, FaasParams } from "@faasjs/types";
 
 //#region src/generate-id/index.d.ts
@@ -119,7 +117,13 @@ type ResponseHeaders = {
   [key: string]: string;
 };
 /**
- * Type definition for the FaasBrowserClient.action method.
+ * Type signature for the {@link FaasBrowserClient.action} method.
+ *
+ * @template Path - Action path used to infer the request params and response data types.
+ * @param {Path} action - Action path to invoke.
+ * @param {FaasParams<Path>} [params] - Params sent to the action.
+ * @param {Options} [options] - Per-request overrides on top of client defaults.
+ * @returns {Promise<Response<FaasData<Path>> | Response>} FaasJS response or native fetch response when streaming.
  */
 type FaasBrowserClientAction = <Path extends FaasActionPaths>(action: Path, params?: FaasParams<Path>, options?: Options) => Promise<Response<FaasData<Path>> | Response>;
 /**
@@ -149,12 +153,55 @@ type MockHandler = (action: string, params: Record<string, any> | undefined, opt
 //#region src/browser/mock.d.ts
 /**
  * Set the global mock handler used by all {@link FaasBrowserClient} instances.
+ *
+ * When a mock handler is set, every {@link FaasBrowserClient.action} call will
+ * route through the mock instead of making a real network request, which is
+ * useful for testing and local development.
+ *
+ * @param {MockHandler | ResponseProps | Response | null | undefined} handler -
+ *   A mock function that receives `(action, params, options)` and returns a
+ *   response shape, or a static response/value, or `null`/`undefined` to
+ *   disable mocking.
+ *
+ * @example
+ * ```ts
+ * import { setMock, Response } from '@faasjs/react'
+ *
+ * // Mock all requests with a static response
+ * setMock({ data: { name: 'test' } })
+ *
+ * // Mock with a handler function
+ * setMock(async (action, params) => {
+ *   if (action === 'posts/get') {
+ *     return { data: { title: 'Hello' } }
+ *   }
+ *   return new Error('Not found')
+ * })
+ *
+ * // Disable mocking
+ * setMock(null)
+ * ```
  */
 declare function setMock(handler: MockHandler | ResponseProps | Response | null | undefined): void;
 //#endregion
 //#region src/browser/client.d.ts
 /**
  * Browser client for FaasJS - provides HTTP client functionality for making API requests from web applications.
+ *
+ * Handles request URL construction, default and per-request option merging,
+ * before-request hooks, mock resolution for testing, and native fetch dispatching.
+ *
+ * @example
+ * ```ts
+ * import { FaasBrowserClient } from '@faasjs/react'
+ *
+ * const client = new FaasBrowserClient('https://api.example.com/', {
+ *   headers: { 'X-Custom-Header': 'value' },
+ * })
+ *
+ * const response = await client.action('posts/get', { id: 1 })
+ * console.log(response.data)
+ * ```
  */
 declare class FaasBrowserClient {
   /**
@@ -171,10 +218,26 @@ declare class FaasBrowserClient {
   defaultOptions: Options;
   /**
    * Creates a new FaasBrowserClient instance.
+   *
+   * @param {BaseUrl} [baseUrl='/'] - Base URL used to build action request URLs. Must end with `/`.
+   * @param {Options} [options={}] - Default request options merged into every request.
+   * @throws {Error} When `baseUrl` does not end with a forward slash.
    */
   constructor(baseUrl?: BaseUrl, options?: Options);
   /**
    * Makes a request to a FaasJS function.
+   *
+   * Builds the request URL and resolved options, runs `beforeRequest` hooks,
+   * checks for mock handlers, and dispatches via native `fetch` or custom `request`.
+   * When `stream` is enabled the raw fetch response is returned so callers can
+   * consume the body stream themselves.
+   *
+   * @template Path - Action path used to infer the request params and response data types.
+   * @param {Path} action - Action path to invoke. Must be non-empty.
+   * @param {FaasParams<Path>} [params] - Params sent to the action. Defaults to an empty object.
+   * @param {Options} [options] - Per-request overrides on top of client defaults.
+   * @returns {Promise<Response<FaasData<Path>>>} FaasJS response containing the parsed data, or native fetch response when streaming.
+   * @throws {Error} When `action` is empty or falsy.
    */
   action<Path extends FaasActionPaths>(action: Path, params: FaasParams<Path>, options?: Options): Promise<Response<FaasData<Path>>>;
 }
@@ -346,7 +409,7 @@ type FaasDataWrapperRef<Path extends FaasActionPaths> = FaasDataInjection<Path>;
  *
  * When a ref is provided, it exposes the current Faas request state imperatively.
  */
-declare const FaasDataWrapper: <Path extends FaasActionPaths>(props: FaasDataWrapperProps<Path> & _$react.RefAttributes<FaasDataWrapperRef<Path>>) => React.ReactElement | null;
+declare const FaasDataWrapper: <Path extends FaasActionPaths>(props: FaasDataWrapperProps<Path> & import("react").RefAttributes<FaasDataWrapperRef<Path>>) => React.ReactElement | null;
 /**
  * Wrap a component with {@link FaasDataWrapper} and inject Faas request state as props.
  *
@@ -656,7 +719,7 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
   /**
    * Render children or the configured fallback for the captured error.
    */
-  render(): string | number | bigint | boolean | _$react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
+  render(): string | number | bigint | boolean | import("react/jsx-runtime").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
 }
 //#endregion
 //#region src/equal/index.d.ts
@@ -803,7 +866,7 @@ type OptionalWrapperProps<TWrapper extends ComponentType<{
  * )
  * ```
  */
-declare function OptionalWrapper(props: OptionalWrapperProps): string | number | bigint | boolean | _$react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | _$react.ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+declare function OptionalWrapper(props: OptionalWrapperProps): string | number | bigint | boolean | import("react/jsx-runtime").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 declare namespace OptionalWrapper {
   var displayName: string;
 }
@@ -958,6 +1021,12 @@ declare function useSplittingState<T extends Record<string, unknown>>(initialSta
 //#region src/useFaasStream/index.d.ts
 /**
  * Options that customize the {@link useFaasStream} request lifecycle.
+ *
+ * Extends the shared request options so stream consumers can control params,
+ * skip logic, debounce timing, polling, and base URL overrides the same way
+ * {@link useFaas} does.
+ *
+ * @see {@link SharedUseFaasOptions} for a full description of each field.
  */
 type UseFaasStreamOptions = SharedUseFaasOptions<Record<string, any>, string>;
 /**

package/dist/index.mjs

@@ -107,6 +107,34 @@ var ResponseError = class extends Error {
 let mock = null;
 /**
 * Set the global mock handler used by all {@link FaasBrowserClient} instances.
+*
+* When a mock handler is set, every {@link FaasBrowserClient.action} call will
+* route through the mock instead of making a real network request, which is
+* useful for testing and local development.
+*
+* @param {MockHandler | ResponseProps | Response | null | undefined} handler -
+*   A mock function that receives `(action, params, options)` and returns a
+*   response shape, or a static response/value, or `null`/`undefined` to
+*   disable mocking.
+*
+* @example
+* ```ts
+* import { setMock, Response } from '@faasjs/react'
+*
+* // Mock all requests with a static response
+* setMock({ data: { name: 'test' } })
+*
+* // Mock with a handler function
+* setMock(async (action, params) => {
+*   if (action === 'posts/get') {
+*     return { data: { title: 'Hello' } }
+*   }
+*   return new Error('Not found')
+* })
+*
+* // Disable mocking
+* setMock(null)
+* ```
 */
 function setMock(handler) {
 	mock = handler;
@@ -137,15 +165,50 @@ function normalizeMockResponse(response) {
 	}
 	return new Response(response || {});
 }
+/**
+* Resolve a mock response for the current request.
+*
+* If the global mock is a function it is invoked with the action, params, and
+* resolved options. Otherwise the static mock value is normalized into a
+* {@link Response} object.
+*
+* @template Path - Action path used for response data inference.
+* @param {string} action - Action path being requested.
+* @param {Record<string, any>} params - Params sent with the request.
+* @param {ResolvedActionOptions} options - Fully resolved request options.
+* @returns {Promise<Response<FaasData<Path>>>} Normalized mock response.
+*/
 async function resolveMockResponse(action, params, options) {
 	if (typeof mock === "function") return normalizeMockResponse(await mock(action, params, options));
 	return normalizeMockResponse(mock);
 }
 //#endregion
 //#region src/browser/helpers.ts
+/**
+* Build the full request URL for an action, with optional request-id query parameter.
+*
+* @param {string} action - Action path to append to the base URL.
+* @param {BaseUrl} baseUrl - Default base URL used when the request options do not override it.
+* @param {Options} [options] - Per-request options whose `baseUrl` field overrides `baseUrl`.
+* @param {string} [requestId] - Unique request identifier appended as the `_` query parameter.
+* @returns {string} Fully assembled request URL.
+*/
 function buildActionUrl(action, baseUrl, options, requestId) {
 	return `${(options?.baseUrl || baseUrl) + action}?_=${requestId}`;
 }
+/**
+* Merge default and per-request options into a fully resolved request configuration.
+*
+* Sets method to `POST`, adds JSON content-type and CORS credentials, serializes params
+* as JSON body, and injects the `X-FaasJS-Request-Id` header unless already present.
+*
+* @template Path - Action path used for params inference.
+* @param {Options} defaultOptions - Client-wide default options merged into every request.
+* @param {Options | undefined} options - Per-request overrides applied on top of defaults.
+* @param {FaasParams<Path>} params - Params to serialize as the JSON request body.
+* @param {string} requestId - Unique request identifier injected into headers.
+* @returns {ResolvedActionOptions} Fully resolved request options ready for `fetch`.
+*/
 function buildActionOptions(defaultOptions, options, params, requestId) {
 	const resolvedOptions = {
 		method: "POST",
@@ -159,6 +222,15 @@ function buildActionOptions(defaultOptions, options, params, requestId) {
 	if (!resolvedOptions.headers["X-FaasJS-Request-Id"] && !resolvedOptions.headers["x-faasjs-request-id"]) resolvedOptions.headers["X-FaasJS-Request-Id"] = requestId;
 	return resolvedOptions;
 }
+/**
+* Invoke the `beforeRequest` hook if it is configured in the resolved options.
+*
+* @template Path - Action path used for params inference.
+* @param {Path} action - Action path being requested.
+* @param {FaasParams<Path>} params - Params being sent with the request.
+* @param {ResolvedActionOptions} options - Resolved options that may carry a `beforeRequest` callback.
+* @returns {Promise<void>} Resolves after the hook (if any) completes.
+*/
 async function runBeforeRequest(action, params, options) {
 	if (!options.beforeRequest) return;
 	await options.beforeRequest({
@@ -168,11 +240,30 @@ async function runBeforeRequest(action, params, options) {
 		headers: options.headers
 	});
 }
+/**
+* Convert fetch `Headers` iterable to a plain key-value object.
+*
+* @param {Iterable<[string, string]>} headers - Iterable of header name/value pairs.
+* @returns {ResponseHeaders} Plain object keyed by lower-cased header names.
+*/
 function toResponseHeaders(headers) {
 	const responseHeaders = {};
 	for (const [key, value] of headers) responseHeaders[key] = value;
 	return responseHeaders;
 }
+/**
+* Parse a successful (2xx) HTTP response body into a {@link Response} object.
+*
+* If the parsed body contains an `error.message` property the response is treated
+* as a logical error and a {@link ResponseError} is thrown instead.
+*
+* @template Path - Action path used for response data inference.
+* @param {number} status - HTTP status code.
+* @param {ResponseHeaders} headers - Response headers.
+* @param {string} text - Raw response body text.
+* @returns {Response<FaasData<Path>>} Wrapped response containing the parsed data.
+* @throws {ResponseError} When the body contains a logical `error.message`.
+*/
 function parseSuccessfulResponse(status, headers, text) {
 	if (!text) return new Response({
 		status,
@@ -192,6 +283,15 @@ function parseSuccessfulResponse(status, headers, text) {
 		data: body.data
 	});
 }
+/**
+* Parse a failed (non-2xx) HTTP response and always throw a {@link ResponseError}.
+*
+* @param {number} status - HTTP status code.
+* @param {ResponseHeaders} headers - Response headers.
+* @param {string} text - Raw response body text.
+* @returns {never} Always throws – never returns normally.
+* @throws {ResponseError} Wrapped error containing the HTTP status, headers, and body.
+*/
 function parseFailedResponse(status, headers, text) {
 	try {
 		const body = JSON.parse(text);
@@ -217,6 +317,17 @@ function parseFailedResponse(status, headers, text) {
 		});
 	}
 }
+/**
+* Read and parse a native fetch response into a FaasJS {@link Response} or throw on failure.
+*
+* Routes to {@link parseSuccessfulResponse} for 2xx status codes and
+* {@link parseFailedResponse} for all others.
+*
+* @template Path - Action path used for response data inference.
+* @param {ParsedFetchResponse} response - Parsed fetch response with headers, status, and text body.
+* @returns {Promise<Response<FaasData<Path>>>} Wrapped FaasJS response on success.
+* @throws {ResponseError} When the HTTP status indicates a failure.
+*/
 async function parseFetchResponse(response) {
 	const headers = toResponseHeaders(response.headers);
 	const text = await response.text();
@@ -227,6 +338,21 @@ async function parseFetchResponse(response) {
 //#region src/browser/client.ts
 /**
 * Browser client for FaasJS - provides HTTP client functionality for making API requests from web applications.
+*
+* Handles request URL construction, default and per-request option merging,
+* before-request hooks, mock resolution for testing, and native fetch dispatching.
+*
+* @example
+* ```ts
+* import { FaasBrowserClient } from '@faasjs/react'
+*
+* const client = new FaasBrowserClient('https://api.example.com/', {
+*   headers: { 'X-Custom-Header': 'value' },
+* })
+*
+* const response = await client.action('posts/get', { id: 1 })
+* console.log(response.data)
+* ```
 */
 var FaasBrowserClient = class {
 	/**
@@ -243,6 +369,10 @@ var FaasBrowserClient = class {
 	defaultOptions;
 	/**
 	* Creates a new FaasBrowserClient instance.
+	*
+	* @param {BaseUrl} [baseUrl='/'] - Base URL used to build action request URLs. Must end with `/`.
+	* @param {Options} [options={}] - Default request options merged into every request.
+	* @throws {Error} When `baseUrl` does not end with a forward slash.
 	*/
 	constructor(baseUrl = "/", options = Object.create(null)) {
 		if (baseUrl && !baseUrl.endsWith("/")) throw Error("[FaasJS] baseUrl should end with /");
@@ -252,6 +382,18 @@ var FaasBrowserClient = class {
 	}
 	/**
 	* Makes a request to a FaasJS function.
+	*
+	* Builds the request URL and resolved options, runs `beforeRequest` hooks,
+	* checks for mock handlers, and dispatches via native `fetch` or custom `request`.
+	* When `stream` is enabled the raw fetch response is returned so callers can
+	* consume the body stream themselves.
+	*
+	* @template Path - Action path used to infer the request params and response data types.
+	* @param {Path} action - Action path to invoke. Must be non-empty.
+	* @param {FaasParams<Path>} [params] - Params sent to the action. Defaults to an empty object.
+	* @param {Options} [options] - Per-request overrides on top of client defaults.
+	* @returns {Promise<Response<FaasData<Path>>>} FaasJS response containing the parsed data, or native fetch response when streaming.
+	* @throws {Error} When `action` is empty or falsy.
 	*/
 	async action(action, params, options) {
 		if (!action) throw Error("[FaasJS] action required");
@@ -672,6 +814,7 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 	const handledRequestTriggerTimesRef = useRef(-1);
 	const pollingTimerRef = useRef(null);
 	const hasLoadedRef = useRef(false);
+	const isOnlineRef = useRef(typeof navigator !== "undefined" ? navigator.onLine : true);
 	const beforeSendRef = useRef(beforeSend);
 	const onSuccessRef = useRef(onSuccess);
 	const sendRef = useRef(send);
@@ -709,14 +852,34 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 		const schedulePolling = () => {
 			clearPollingTimer();
 			if (!options.polling || options.polling <= 0 || !isCurrentRequest()) return;
+			if (!isOnlineRef.current) return;
 			pollingTimerRef.current = setTimeout(() => {
 				if (!isCurrentRequest()) return;
+				if (!isOnlineRef.current) return;
 				setRequestTrigger((prev) => ({
 					times: prev.times + 1,
 					silent: true
 				}));
 			}, options.polling);
 		};
+		const handleOnline = () => {
+			isOnlineRef.current = true;
+			if (options.polling && options.polling > 0 && !skip) setRequestTrigger((prev) => ({
+				times: prev.times + 1,
+				silent: hasLoadedRef.current
+			}));
+		};
+		const handleOffline = () => {
+			isOnlineRef.current = false;
+			if (pollingTimerRef.current) {
+				clearTimeout(pollingTimerRef.current);
+				pollingTimerRef.current = null;
+			}
+		};
+		if (typeof window !== "undefined") {
+			window.addEventListener("online", handleOnline);
+			window.addEventListener("offline", handleOffline);
+		}
 		const rejectPending = (reason) => {
 			for (const { reject } of pendingReloadsRef.current.values()) reject(reason);
 			pendingReloadsRef.current.clear();
@@ -773,6 +936,10 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 			return () => {
 				clearTimeout(timeout);
 				clearPollingTimer();
+				if (typeof window !== "undefined") {
+					window.removeEventListener("online", handleOnline);
+					window.removeEventListener("offline", handleOffline);
+				}
 				if (controllerRef.current === controller) controllerRef.current = null;
 				controller.abort();
 				setLoading(false);
@@ -782,6 +949,10 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 		run();
 		return () => {
 			clearPollingTimer();
+			if (typeof window !== "undefined") {
+				window.removeEventListener("online", handleOnline);
+				window.removeEventListener("offline", handleOffline);
+			}
 			if (controllerRef.current === controller) controllerRef.current = null;
 			controller.abort();
 			setLoading(false);

package/package.json

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