@faasjs/react 8.0.0-beta.34 → 8.0.0-beta.36

package/README.md

@@ -6,7 +6,6 @@
 - [equal](functions/equal.md)
 - [faas](functions/faas.md)
 - [FaasReactClient](functions/FaasReactClient.md)
-- [generateId](functions/generateId.md)
 - [getClient](functions/getClient.md)
 - [OptionalWrapper](functions/OptionalWrapper.md)
 - [setMock](functions/setMock.md)

package/dist/index.d.ts

@@ -1,28 +1,6 @@
-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
-/**
- * Generate a random identifier with an optional prefix.
- *
- * @param {string} [prefix] - Prefix prepended to the generated identifier.
- * @param {number} [length] - Length of the generated identifier excluding `prefix`. Must be between `8` and `18`.
- * @returns {string} Generated identifier string.
- * @throws {Error} When `length` is outside the supported `8` to `18` range.
- *
- * @example
- * ```ts
- * import { generateId } from '@faasjs/react'
- *
- * const id = generateId('prefix-')
- *
- * id.startsWith('prefix-') // true
- * ```
- */
-declare function generateId(prefix?: string, length?: number): string;
-//#endregion
 //#region src/browser/response.d.ts
 /**
  * Wrapper class for HTTP responses from FaasJS functions.
@@ -119,7 +97,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 +133,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 +198,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>>>;
 }
@@ -309,7 +352,7 @@ type FaasDataWrapperRef<Path extends FaasActionPaths> = FaasDataInjection<Path>;
  * export function UserProfile(props: { id: number }) {
  *   return (
  *     <FaasDataWrapper<User>
- *       action="/pages/users/get"
+ *       action="features/users/api/get"
  *       params={{ id: props.id }}
  *       fallback={<div>Loading user...</div>}
  *       render={({ data, error, reload }) => {
@@ -334,7 +377,7 @@ type FaasDataWrapperRef<Path extends FaasActionPaths> = FaasDataInjection<Path>;
  * export function UserProfileWithChildren(props: { id: number }) {
  *   return (
  *     <FaasDataWrapper<User>
- *       action="/pages/users/get"
+ *       action="features/users/api/get"
  *       params={{ id: props.id }}
  *       fallback={<div>Loading user...</div>}
  *     >
@@ -346,7 +389,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.
  *
@@ -376,7 +419,7 @@ declare const FaasDataWrapper: <Path extends FaasActionPaths>(props: FaasDataWra
  *
  *     return <div>{data.name}</div>
  *   },
- *   { action: '/pages/users/get', params: { id: 1 } },
+ *   { action: 'features/users/api/get', params: { id: 1 } },
  * )
  * ```
  */
@@ -431,7 +474,7 @@ type UseFaasOptions<Path extends FaasActionPaths> = SharedUseFaasOptions<FaasPar
  * import { useFaas } from '@faasjs/react'
  *
  * function Profile({ id }: { id: number }) {
- *   const { data, error, loading, reload } = useFaas('/pages/users/get', { id })
+ *   const { data, error, loading, reload } = useFaas('features/users/api/get', { id })
  *
  *   if (loading) return <div>Loading...</div>
  *
@@ -562,7 +605,7 @@ declare function FaasReactClient(options?: FaasReactClientOptions): FaasReactCli
  *
  * const client = getClient('https://service-b.example.com/api/')
  *
- * await client.faas('/pages/posts/get', { id: 1 })
+ * await client.faas('features/posts/api/get', { id: 1 })
  * ```
  */
 declare function getClient(host?: string): FaasReactClientInstance;
@@ -656,7 +699,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.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 +846,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.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 +1001,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>;
 /**
@@ -998,7 +1047,7 @@ type UseFaasStreamResult<Path extends FaasActionPaths> = {
  * import { useFaasStream } from '@faasjs/react'
  *
  * function Chat({ prompt }: { prompt: string }) {
- *   const { data, error, loading, reload } = useFaasStream('/pages/chat/stream', { prompt })
+ *   const { data, error, loading, reload } = useFaasStream('features/chat/api/stream', { prompt })
  *
  *   if (loading) return <div>Streaming...</div>
  *
@@ -1068,4 +1117,4 @@ declare function usePrevious<T = any>(value: T): T | undefined;
 declare function useStateRef<T>(initialValue: T | (() => T)): [T, Dispatch<SetStateAction<T>>, RefObject<T>];
 declare function useStateRef<T = undefined>(): [T | undefined, Dispatch<SetStateAction<T | undefined>>, RefObject<T | undefined>];
 //#endregion
-export { type BaseUrl, ErrorBoundary, ErrorBoundaryProps, ErrorChildrenProps, FaasBrowserClient, type FaasBrowserClientAction, FaasDataInjection, FaasDataWrapper, FaasDataWrapperProps, FaasDataWrapperRef, FaasReactClient, FaasReactClientInstance, FaasReactClientOptions, type MockHandler, OnError, OptionalWrapper, OptionalWrapperProps, type Options, Response, ResponseError, type ResponseErrorProps, type ResponseHeaders, type ResponseProps, StateSetters, StatesWithSetters, UseFaasOptions, UseFaasStreamOptions, UseFaasStreamResult, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, usePrevious, useSplittingState, useStateRef, withFaasData };
+export { type BaseUrl, ErrorBoundary, ErrorBoundaryProps, ErrorChildrenProps, FaasBrowserClient, type FaasBrowserClientAction, FaasDataInjection, FaasDataWrapper, FaasDataWrapperProps, FaasDataWrapperRef, FaasReactClient, FaasReactClientInstance, FaasReactClientOptions, type MockHandler, OnError, OptionalWrapper, OptionalWrapperProps, type Options, Response, ResponseError, type ResponseErrorProps, type ResponseHeaders, type ResponseProps, StateSetters, StatesWithSetters, UseFaasOptions, UseFaasStreamOptions, UseFaasStreamResult, createSplittingContext, equal, faas, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, usePrevious, useSplittingState, useStateRef, withFaasData };

package/dist/index.mjs

@@ -1,28 +1,6 @@
+import { generateId } from "@faasjs/utils";
 import { Component, cloneElement, createContext, forwardRef, useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/generate-id/index.ts
-/**
-* Generate a random identifier with an optional prefix.
-*
-* @param {string} [prefix] - Prefix prepended to the generated identifier.
-* @param {number} [length] - Length of the generated identifier excluding `prefix`. Must be between `8` and `18`.
-* @returns {string} Generated identifier string.
-* @throws {Error} When `length` is outside the supported `8` to `18` range.
-*
-* @example
-* ```ts
-* import { generateId } from '@faasjs/react'
-*
-* const id = generateId('prefix-')
-*
-* id.startsWith('prefix-') // true
-* ```
-*/
-function generateId(prefix = "", length = 18) {
-	if (length < 8 || length > 18) throw new Error("Length must be 8 ~ 18");
-	return `${prefix}${Date.now().toString(36).padStart(8, "0")}${Math.random().toString(36).substring(2, length - 6).padEnd(length - 8, "0")}`;
-}
-//#endregion
 //#region src/browser/response.ts
 /**
 * Wrapper class for HTTP responses from FaasJS functions.
@@ -107,6 +85,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 +143,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 +200,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 +218,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 +261,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 +295,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 +316,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 +347,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 +360,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");
@@ -508,7 +628,7 @@ function useEqualCallback(callback, dependencies) {
 * export function UserProfile(props: { id: number }) {
 *   return (
 *     <FaasDataWrapper<User>
-*       action="/pages/users/get"
+*       action="features/users/api/get"
 *       params={{ id: props.id }}
 *       fallback={<div>Loading user...</div>}
 *       render={({ data, error, reload }) => {
@@ -533,7 +653,7 @@ function useEqualCallback(callback, dependencies) {
 * export function UserProfileWithChildren(props: { id: number }) {
 *   return (
 *     <FaasDataWrapper<User>
-*       action="/pages/users/get"
+*       action="features/users/api/get"
 *       params={{ id: props.id }}
 *       fallback={<div>Loading user...</div>}
 *     >
@@ -606,7 +726,7 @@ Object.assign(FaasDataWrapper, { displayName: "FaasDataWrapper" });
 *
 *     return <div>{data.name}</div>
 *   },
-*   { action: '/pages/users/get', params: { id: 1 } },
+*   { action: 'features/users/api/get', params: { id: 1 } },
 * )
 * ```
 */
@@ -639,7 +759,7 @@ function withFaasData(Component, faasProps) {
 * ```ts
 * function useUserRequest(id: number) {
 *   return useFaasRequest({
-*     action: '/pages/users/get',
+*     action: 'features/users/api/get',
 *     defaultParams: { id },
 *     options: {},
 *     send: async ({ action, params, signal, client, setPromise }) => {
@@ -672,6 +792,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 +830,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 +914,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 +927,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);
@@ -845,7 +994,7 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 * import { useFaas } from '@faasjs/react'
 *
 * function Profile({ id }: { id: number }) {
-*   const { data, error, loading, reload } = useFaas('/pages/users/get', { id })
+*   const { data, error, loading, reload } = useFaas('features/users/api/get', { id })
 *
 *   if (loading) return <div>Loading...</div>
 *
@@ -994,7 +1143,7 @@ function FaasReactClient(options = { baseUrl: "/" }) {
 *
 * const client = getClient('https://service-b.example.com/api/')
 *
-* await client.faas('/pages/posts/get', { id: 1 })
+* await client.faas('features/posts/api/get', { id: 1 })
 * ```
 */
 function getClient(host) {
@@ -1277,7 +1426,7 @@ function createSplittingContext(defaultValue) {
 * import { useFaasStream } from '@faasjs/react'
 *
 * function Chat({ prompt }: { prompt: string }) {
-*   const { data, error, loading, reload } = useFaasStream('/pages/chat/stream', { prompt })
+*   const { data, error, loading, reload } = useFaasStream('features/chat/api/stream', { prompt })
 *
 *   if (loading) return <div>Streaming...</div>
 *
@@ -1400,4 +1549,4 @@ function useStateRef(initialValue) {
 	];
 }
 //#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 };
+export { ErrorBoundary, FaasBrowserClient, FaasDataWrapper, FaasReactClient, OptionalWrapper, Response, ResponseError, createSplittingContext, equal, faas, 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.34",
+  "version": "8.0.0-beta.36",
   "homepage": "https://faasjs.com/doc/react/",
   "bugs": {
     "url": "https://github.com/faasjs/faasjs/issues"
@@ -26,12 +26,14 @@
     }
   },
   "devDependencies": {
-    "@faasjs/types": ">=8.0.0-beta.34",
+    "@faasjs/types": ">=8.0.0-beta.36",
+    "@faasjs/utils": ">=8.0.0-beta.36",
     "@types/react": "^19.0.0",
     "react": "^19.0.0"
   },
   "peerDependencies": {
-    "@faasjs/types": ">=8.0.0-beta.34"
+    "@faasjs/types": ">=8.0.0-beta.36",
+    "@faasjs/utils": ">=8.0.0-beta.36"
   },
   "engines": {
     "node": ">=26.0.0",