@faasjs/react 8.0.0-beta.25 → 8.0.0-beta.27

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { Component, ComponentProps, ComponentType, Dispatch, ErrorInfo, JSX, Rea
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { FaasAction, FaasAction as FaasAction$1, FaasActionUnionType, FaasActionUnionType as FaasActionUnionType$1, FaasData, FaasData as FaasData$1, FaasParams, FaasParams as FaasParams$1 } from "@faasjs/types";
 
-//#region src/generateId.d.ts
+//#region src/generateId/index.d.ts
 /**
  * Generate a random identifier with an optional prefix.
  *
@@ -23,7 +23,7 @@ import { FaasAction, FaasAction as FaasAction$1, FaasActionUnionType, FaasAction
  */
 declare function generateId(prefix?: string, length?: number): string;
 //#endregion
-//#region src/browser.d.ts
+//#region src/browser/index.d.ts
 /**
  * Template literal type for URL strings that must end with a forward slash.
  *
@@ -111,7 +111,7 @@ type Options = RequestInit & {
  *
  * Notes:
  * - Headers are case-insensitive in HTTP but stored with exact casing in this object
- * - Common headers include: Content-Type, Authorization, X-Request-Id, X-Custom-Header
+ * - Common headers include: Content-Type, Authorization, x-faasjs-request-id, X-Custom-Header
  * - No support for multi-value headers (use comma-separated values instead)
  * - Used in Response, ResponseError, and Options types
  * - Simplified model compared to browser's Headers interface (no .get(), .set() methods)
@@ -250,7 +250,7 @@ type ResponseProps<T = any> = {
  *   data: { created: true },
  *   headers: {
  *     'Content-Type': 'application/json',
- *     'X-Request-Id': 'req-123',
+ *     'x-faasjs-request-id': 'req-123',
  *     'X-Cache-Key': 'user-123'
  *   }
  * })
@@ -401,8 +401,8 @@ type ResponseErrorProps = {
  *     if (error.body) {
  *       console.error('Error details:', error.body)
  *     }
- *     if (error.headers['X-Request-Id']) {
- *       console.error('Request ID:', error.headers['X-Request-Id'])
+ *     if (error.headers['x-faasjs-request-id']) {
+ *       console.error('Request ID:', error.headers['x-faasjs-request-id'])
  *     }
  *   }
  * }
@@ -848,7 +848,7 @@ declare class FaasBrowserClient {
   action<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params?: FaasParams$1<PathOrData>, options?: Options): Promise<Response<FaasData$1<PathOrData>>>;
 }
 //#endregion
-//#region src/faas.d.ts
+//#region src/faas/index.d.ts
 /**
  * Call the currently configured FaasReactClient.
  *
@@ -876,7 +876,7 @@ declare class FaasBrowserClient {
  */
 declare function faas<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params: FaasParams$1<PathOrData>, options?: Options): Promise<Response<FaasData$1<PathOrData>>>;
 //#endregion
-//#region src/FaasDataWrapper.d.ts
+//#region src/FaasDataWrapper/index.d.ts
 /**
  * Request state injected by {@link useFaas}, {@link FaasDataWrapper}, and {@link withFaasData}.
  *
@@ -884,8 +884,9 @@ declare function faas<PathOrData extends FaasActionUnionType$1>(action: FaasActi
  */
 type FaasDataInjection<PathOrData extends FaasActionUnionType$1 = any> = {
   /** Action path associated with the current request state. */action: FaasAction$1<PathOrData>; /** Params used for the most recent request attempt. */
-  params: FaasParams$1<PathOrData>; /** Whether the request is currently in flight. */
-  loading: boolean; /** Number of times `reload()` has triggered a new request. */
+  params: FaasParams$1<PathOrData>; /** Whether the request is currently in flight and should block the main UI. */
+  loading: boolean; /** Whether a background refresh request is currently in flight. */
+  refreshing: boolean; /** Number of times `reload()` or polling has triggered a new request. */
   reloadTimes: number; /** Current resolved data value. */
   data: FaasData$1<PathOrData>; /** Last request error, if one occurred. */
   error: any; /** Promise representing the latest request. */
@@ -896,7 +897,9 @@ type FaasDataInjection<PathOrData extends FaasActionUnionType$1 = any> = {
    * When the source hook is currently skipped, calling `reload` clears the skip
    * flag before starting the next request.
    */
-  reload(params?: Record<string, any>): Promise<FaasData$1<PathOrData>>; /** Controlled or internal setter for the resolved data value. */
+  reload(params?: Record<string, any>, options?: {
+    silent?: boolean;
+  }): Promise<FaasData$1<PathOrData>>; /** Controlled or internal setter for the resolved data value. */
   setData: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>; /** Setter for the loading flag. */
   setLoading: React.Dispatch<React.SetStateAction<boolean>>; /** Setter for the latest request promise. */
   setPromise: React.Dispatch<React.SetStateAction<Promise<Response<FaasData$1<PathOrData>>>>>; /** Setter for the last request error. */
@@ -912,7 +915,8 @@ type FaasDataWrapperProps<PathOrData extends FaasActionUnionType$1> = {
   children?: React.ReactElement<Partial<FaasDataInjection<PathOrData>>>; /** Element rendered before the first successful load. */
   fallback?: JSX.Element | false; /** Action path to request. */
   action: FaasAction$1<PathOrData>; /** Params sent to the action. */
-  params?: FaasParams$1<PathOrData>; /** Callback invoked whenever the resolved data value changes. */
+  params?: FaasParams$1<PathOrData>; /** Milliseconds to wait after each completed request before refreshing data in the background. */
+  polling?: number | false; /** Callback invoked whenever the resolved data value changes. */
   onDataChange?(args: FaasDataInjection<PathOrData>): void; /** Controlled data value used instead of internal state. */
   data?: FaasData$1<PathOrData>; /** Controlled setter used instead of internal state. */
   setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>; /** Base URL override used for this wrapper instance. */
@@ -937,6 +941,7 @@ type FaasDataWrapperRef<PathOrData extends FaasActionUnionType$1 = any> = FaasDa
  * @param {JSX.Element | false} [props.fallback] - Element rendered before the first successful load.
  * @param {FaasAction<PathOrData>} props.action - Action path to request.
  * @param {FaasParams<PathOrData>} [props.params] - Params sent to the action.
+ * @param {number | false} [props.polling] - Milliseconds to wait after each completed request before refreshing data in the background.
  * @param {(args: FaasDataInjection<PathOrData>) => void} [props.onDataChange] - Callback invoked when the resolved data value changes.
  * @param {FaasData<PathOrData>} [props.data] - Controlled data value used instead of internal state.
  * @param {React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>} [props.setData] - Controlled setter used instead of internal state.
@@ -1014,8 +1019,8 @@ declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType$1 = any>(
 /**
  * Wrap a component with {@link FaasDataWrapper} and inject Faas request state as props.
  *
- * `withFaasData` is most useful for wrapper-style exports or compatibility with
- * an existing component boundary. For new code, prefer `useFaas` or
+ * `withFaasData` is most useful for wrapper-style exports or when you want to
+ * preserve an existing component boundary. For new code, prefer `useFaas` or
  * `FaasDataWrapper` when they express the request ownership more directly.
  *
  * @template PathOrData - Action path or response data type used for inference.
@@ -1055,6 +1060,7 @@ declare function withFaasData<PathOrData extends FaasActionUnionType$1, TCompone
  * @property {React.Dispatch<React.SetStateAction<Data>>} [setData] - Controlled setter paired with `data`.
  * @property {boolean | ((params: Params) => boolean)} [skip] - Boolean or predicate that suppresses the automatic request.
  * @property {number} [debounce] - Milliseconds to wait before sending the latest request.
+ * @property {number | false} [polling] - Milliseconds to wait after each completed request before refreshing data in the background.
  * @property {BaseUrl} [baseUrl] - Base URL override used for this request lifecycle.
  */
 type SharedUseFaasOptions<Params, Data> = {
@@ -1063,10 +1069,11 @@ type SharedUseFaasOptions<Params, Data> = {
   setData?: React.Dispatch<React.SetStateAction<Data>>;
   skip?: boolean | ((params: Params) => boolean);
   debounce?: number;
+  polling?: number | false;
   baseUrl?: BaseUrl;
 };
 //#endregion
-//#region src/useFaas.d.ts
+//#region src/useFaas/index.d.ts
 /**
  * Options that customize the {@link useFaas} request lifecycle.
  *
@@ -1078,14 +1085,14 @@ type useFaasOptions<PathOrData extends FaasActionUnionType$1> = SharedUseFaasOpt
  *
  * `useFaas` is the default hook for standard FaasJS request-response flows in React.
  * It sends an initial request unless `skip` is enabled, and returns request state
- * plus helpers for reloading, updating data, and handling errors.
+ * plus helpers for reloading, background refreshing, updating data, and handling errors.
  *
  * @template PathOrData - Action path or response data type used for inference.
  *
  * @param {FaasAction<PathOrData>} action - Action path to invoke.
  * @param {FaasParams<PathOrData>} defaultParams - Params used for the initial request and future reloads.
- * @param {useFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, and base URL overrides.
- * See the `useFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+ * @param {useFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, polling, and base URL overrides.
+ * See the `useFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
  * @returns {FaasDataInjection<PathOrData>} Request state and helper methods described by {@link FaasDataInjection}.
  *
  * @example
@@ -1229,7 +1236,7 @@ declare function FaasReactClient(options?: FaasReactClientOptions): FaasReactCli
  */
 declare function getClient(host?: string): FaasReactClientInstance;
 //#endregion
-//#region src/constant.d.ts
+//#region src/constant/index.d.ts
 /**
  * Returns a constant value that is created by the given function.
  *
@@ -1250,7 +1257,7 @@ declare function getClient(host?: string): FaasReactClientInstance;
  */
 declare function useConstant<T>(fn: () => T): T;
 //#endregion
-//#region src/ErrorBoundary.d.ts
+//#region src/ErrorBoundary/index.d.ts
 /**
  * Props for the {@link ErrorBoundary} component.
  */
@@ -1318,10 +1325,10 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
   /**
    * Render children or the configured fallback for the captured error.
    */
-  render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | _$react_jsx_runtime0.JSX.Element | null;
+  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;
 }
 //#endregion
-//#region src/equal.d.ts
+//#region src/equal/index.d.ts
 /**
  * Compares two values for deep equality.
  *
@@ -1426,7 +1433,7 @@ declare function useEqualMemo<T>(callback: () => T, dependencies: any[]): T;
  */
 declare function useEqualCallback<T extends (...args: any[]) => any>(callback: T, dependencies: any[]): T;
 //#endregion
-//#region src/OptionalWrapper.d.ts
+//#region src/OptionalWrapper/index.d.ts
 /**
  * Props for the {@link OptionalWrapper} helper component.
  *
@@ -1465,12 +1472,12 @@ type OptionalWrapperProps<TWrapper extends ComponentType<{
  * )
  * ```
  */
-declare function OptionalWrapper(props: OptionalWrapperProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | _$react.ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | _$react_jsx_runtime0.JSX.Element | null | undefined;
+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 namespace OptionalWrapper {
   var displayName: string;
 }
 //#endregion
-//#region src/splittingContext.d.ts
+//#region src/splittingContext/index.d.ts
 /**
  * Create a context whose keys can be consumed independently.
  *
@@ -1586,7 +1593,7 @@ declare function createSplittingContext<T extends Record<string, any>>(defaultVa
   use: <NewT extends T = T>(this: void) => Readonly<NewT>;
 };
 //#endregion
-//#region src/splittingState.d.ts
+//#region src/splittingState/index.d.ts
 /**
  * Setter map generated by {@link useSplittingState} for each state key.
  *
@@ -1617,7 +1624,7 @@ type StatesWithSetters<T> = T & StateSetters<T>;
  */
 declare function useSplittingState<T extends Record<string, unknown>>(initialStates: T): StatesWithSetters<T>;
 //#endregion
-//#region src/useFaasStream.d.ts
+//#region src/useFaasStream/index.d.ts
 /**
  * Options that customize the {@link useFaasStream} request lifecycle.
  */
@@ -1627,12 +1634,15 @@ type UseFaasStreamOptions = SharedUseFaasOptions<Record<string, any>, string>;
  */
 type UseFaasStreamResult = {
   /** Action path currently associated with the stream request. */action: string; /** Params used for the most recent request attempt. */
-  params: Record<string, any>; /** Whether the hook is currently waiting for stream data. */
-  loading: boolean; /** Number of times `reload()` has triggered a new request. */
+  params: Record<string, any>; /** Whether the hook is currently waiting for stream data and should block the main UI. */
+  loading: boolean; /** Whether a background stream refresh is currently in flight. */
+  refreshing: boolean; /** Number of times `reload()` or polling has triggered a new request. */
   reloadTimes: number; /** Accumulated text decoded from the stream response. */
   data: string; /** Last error raised while opening or consuming the stream. */
   error: any; /** Trigger a new streaming request with optional params. */
-  reload: (params?: Record<string, any>) => Promise<string>; /** Controlled or internal setter for the accumulated text. */
+  reload: (params?: Record<string, any>, options?: {
+    silent?: boolean;
+  }) => Promise<string>; /** Controlled or internal setter for the accumulated text. */
   setData: React.Dispatch<React.SetStateAction<string>>; /** Setter for the loading flag. */
   setLoading: React.Dispatch<React.SetStateAction<boolean>>; /** Setter for the last stream error. */
   setError: React.Dispatch<React.SetStateAction<any>>;
@@ -1646,8 +1656,8 @@ type UseFaasStreamResult = {
  *
  * @param {string} action - Action path to invoke.
  * @param {Record<string, any>} defaultParams - Params used for the initial request and future reloads.
- * @param {UseFaasStreamOptions} [options] - Optional hook configuration such as controlled stream text, skip logic, debounce timing, and base URL overrides.
- * See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+ * @param {UseFaasStreamOptions} [options] - Optional hook configuration such as controlled stream text, skip logic, debounce timing, polling, and base URL overrides.
+ * See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
  * @returns {UseFaasStreamResult} Streaming request state and helper methods described by {@link UseFaasStreamResult}.
  *
  * @example
@@ -1676,7 +1686,7 @@ type UseFaasStreamResult = {
  */
 declare function useFaasStream(action: string, defaultParams: Record<string, any>, options?: UseFaasStreamOptions): UseFaasStreamResult;
 //#endregion
-//#region src/usePrevious.d.ts
+//#region src/usePrevious/index.d.ts
 /**
  * Hook to store the previous value of a state or prop.
  *
@@ -1697,7 +1707,7 @@ declare function useFaasStream(action: string, defaultParams: Record<string, any
  */
 declare function usePrevious<T = any>(value: T): T | undefined;
 //#endregion
-//#region src/useStateRef.d.ts
+//#region src/useStateRef/index.d.ts
 /**
  * Custom hook that returns a stateful value and a ref to that value.
  *

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { Component, cloneElement, createContext, forwardRef, useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/generateId.ts
+//#region src/generateId/index.ts
 /**
 * Generate a random identifier with an optional prefix.
 *
@@ -23,7 +23,7 @@ function generateId(prefix = "", length = 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.ts
+//#region src/browser/index.ts
 /**
 * Wrapper class for HTTP responses from FaasJS functions.
 *
@@ -88,7 +88,7 @@ function generateId(prefix = "", length = 18) {
 *   data: { created: true },
 *   headers: {
 *     'Content-Type': 'application/json',
-*     'X-Request-Id': 'req-123',
+*     'x-faasjs-request-id': 'req-123',
 *     'X-Cache-Key': 'user-123'
 *   }
 * })
@@ -235,8 +235,8 @@ var Response = class {
 *     if (error.body) {
 *       console.error('Error details:', error.body)
 *     }
-*     if (error.headers['X-Request-Id']) {
-*       console.error('Request ID:', error.headers['X-Request-Id'])
+*     if (error.headers['x-faasjs-request-id']) {
+*       console.error('Request ID:', error.headers['x-faasjs-request-id'])
 *     }
 *   }
 * }
@@ -778,7 +778,7 @@ var FaasBrowserClient = class {
 	}
 };
 //#endregion
-//#region src/faas.ts
+//#region src/faas/index.ts
 /**
 * Call the currently configured FaasReactClient.
 *
@@ -814,7 +814,7 @@ async function faas(action, params, options) {
 	return client.browserClient.action(action, params, options);
 }
 //#endregion
-//#region src/equal.ts
+//#region src/equal/index.ts
 const AsyncFunction = (async () => {}).constructor;
 /**
 * Compares two values for deep equality.
@@ -982,6 +982,7 @@ function useEqualCallback(callback, dependencies) {
 * @param {JSX.Element | false} [props.fallback] - Element rendered before the first successful load.
 * @param {FaasAction<PathOrData>} props.action - Action path to request.
 * @param {FaasParams<PathOrData>} [props.params] - Params sent to the action.
+* @param {number | false} [props.polling] - Milliseconds to wait after each completed request before refreshing data in the background.
 * @param {(args: FaasDataInjection<PathOrData>) => void} [props.onDataChange] - Callback invoked when the resolved data value changes.
 * @param {FaasData<PathOrData>} [props.data] - Controlled data value used instead of internal state.
 * @param {React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>} [props.setData] - Controlled setter used instead of internal state.
@@ -1058,7 +1059,8 @@ function useEqualCallback(callback, dependencies) {
 const FaasDataWrapper = forwardRef((props, ref) => {
 	const requestOptions = {
 		...props.data !== void 0 ? { data: props.data } : {},
-		...props.setData ? { setData: props.setData } : {}
+		...props.setData ? { setData: props.setData } : {},
+		...props.polling !== void 0 ? { polling: props.polling } : {}
 	};
 	const request = getClient(props.baseUrl).useFaas(props.action, props.params ?? {}, requestOptions);
 	const [loaded, setLoaded] = useState(false);
@@ -1081,15 +1083,16 @@ const FaasDataWrapper = forwardRef((props, ref) => {
 		request.params,
 		request.data,
 		request.error,
-		request.loading
+		request.loading,
+		request.refreshing
 	]);
 });
 Object.assign(FaasDataWrapper, { displayName: "FaasDataWrapper" });
 /**
 * Wrap a component with {@link FaasDataWrapper} and inject Faas request state as props.
 *
-* `withFaasData` is most useful for wrapper-style exports or compatibility with
-* an existing component boundary. For new code, prefer `useFaas` or
+* `withFaasData` is most useful for wrapper-style exports or when you want to
+* preserve an existing component boundary. For new code, prefer `useFaas` or
 * `FaasDataWrapper` when they express the request ownership more directly.
 *
 * @template PathOrData - Action path or response data type used for inference.
@@ -1129,8 +1132,9 @@ function withFaasData(Component, faasProps) {
 /**
 * Run the shared request lifecycle used by the higher-level FaasJS React hooks.
 *
-* It manages loading state, abort signals, debounce timing, retry-on-fetch-failure,
-* and queued reload promises while delegating the actual transport to `send`.
+* It manages loading state, background refresh state, abort signals, debounce timing,
+* retry-on-fetch-failure, polling, and queued reload promises while delegating the
+* actual transport to `send`.
 *
 * @template Params - Request params type tracked by the lifecycle.
 * @template Result - Successful response payload type.
@@ -1138,8 +1142,8 @@ function withFaasData(Component, faasProps) {
 * @param {UseFaasRequestArgs<Params, Result, RequestPromise>} args - Request lifecycle configuration.
 * @param {string} args.action - Action path or request key used to trigger the lifecycle.
 * @param {Params} args.defaultParams - Initial params value stored by the lifecycle.
-* @param {Pick<SharedUseFaasOptions<Params, Result>, 'params' | 'skip' | 'debounce' | 'baseUrl'>} args.options - Shared request options used by the lifecycle.
-* @param {() => void} [args.beforeSend] - Optional callback invoked immediately before a request starts.
+* @param {Pick<SharedUseFaasOptions<Params, Result>, 'params' | 'skip' | 'debounce' | 'polling' | 'baseUrl'>} args.options - Shared request options used by the lifecycle.
+* @param {(args: { silent: boolean }) => void} [args.beforeSend] - Optional callback invoked immediately before a request starts.
 * @param {(result: Result) => void} [args.onSuccess] - Optional callback invoked after a successful response.
 * @param {UseFaasRequestArgs<Params, Result, RequestPromise>['send']} args.send - Transport function responsible for creating and resolving the request.
 * @returns Shared request state, reload helpers, and refs used by `useFaas` and `useFaasStream`.
@@ -1163,9 +1167,13 @@ function withFaasData(Component, faasProps) {
 */
 function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess, send }) {
 	const [loading, setLoading] = useState(true);
+	const [refreshing, setRefreshing] = useState(false);
 	const [error, setError] = useState();
 	const [params, setParams] = useState(defaultParams);
-	const [reloadTimes, setReloadTimes] = useState(0);
+	const [requestTrigger, setRequestTrigger] = useState({
+		times: 0,
+		silent: false
+	});
 	const [skip, setSkip] = useState(typeof options.skip === "function" ? options.skip(defaultParams) : options.skip);
 	const promiseRef = useRef(null);
 	const controllerRef = useRef(null);
@@ -1173,6 +1181,9 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 	const pendingReloadsRef = useRef(/* @__PURE__ */ new Map());
 	const reloadCounterRef = useRef(0);
 	const requestVersionRef = useRef(0);
+	const handledRequestTriggerTimesRef = useRef(-1);
+	const pollingTimerRef = useRef(null);
+	const hasLoadedRef = useRef(false);
 	const beforeSendRef = useRef(beforeSend);
 	const onSuccessRef = useRef(onSuccess);
 	const sendRef = useRef(send);
@@ -1188,16 +1199,36 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 	useEqualEffect(() => {
 		if (!action || skip) {
 			setLoading(false);
+			setRefreshing(false);
 			return;
 		}
-		setLoading(true);
-		beforeSendRef.current?.();
+		const isSilentRequest = requestTrigger.times !== handledRequestTriggerTimesRef.current && requestTrigger.silent && hasLoadedRef.current;
+		handledRequestTriggerTimesRef.current = requestTrigger.times;
+		if (isSilentRequest) setRefreshing(true);
+		else setLoading(true);
+		beforeSendRef.current?.({ silent: isSilentRequest });
 		failedOnceRef.current = false;
 		const controller = new AbortController();
 		const requestVersion = ++requestVersionRef.current;
 		controllerRef.current = controller;
 		const client = getClient(options.baseUrl);
 		const requestParams = options.params || params;
+		const clearPollingTimer = () => {
+			if (!pollingTimerRef.current) return;
+			clearTimeout(pollingTimerRef.current);
+			pollingTimerRef.current = null;
+		};
+		const schedulePolling = () => {
+			clearPollingTimer();
+			if (!options.polling || options.polling <= 0 || !isCurrentRequest()) return;
+			pollingTimerRef.current = setTimeout(() => {
+				if (!isCurrentRequest()) return;
+				setRequestTrigger((prev) => ({
+					times: prev.times + 1,
+					silent: true
+				}));
+			}, options.polling);
+		};
 		const rejectPending = (reason) => {
 			for (const { reject } of pendingReloadsRef.current.values()) reject(reason);
 			pendingReloadsRef.current.clear();
@@ -1221,8 +1252,11 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 				failedOnceRef.current = false;
 				setError(null);
 				onSuccessRef.current?.(result);
+				hasLoadedRef.current = true;
 				setLoading(false);
+				setRefreshing(false);
 				resolvePending(result);
+				schedulePolling();
 			}).catch(async (e) => {
 				if (!isCurrentRequest()) return;
 				if (typeof e?.message === "string" && e.message.toLowerCase().includes("aborted")) return;
@@ -1241,67 +1275,81 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 				if (!isCurrentRequest()) return;
 				setError(nextError);
 				setLoading(false);
+				setRefreshing(false);
 				rejectPending(nextError);
+				schedulePolling();
 			});
 		};
 		if (options.debounce) {
 			const timeout = setTimeout(run, options.debounce);
 			return () => {
 				clearTimeout(timeout);
+				clearPollingTimer();
 				if (controllerRef.current === controller) controllerRef.current = null;
 				controller.abort();
 				setLoading(false);
+				setRefreshing(false);
 			};
 		}
 		run();
 		return () => {
+			clearPollingTimer();
 			if (controllerRef.current === controller) controllerRef.current = null;
 			controller.abort();
 			setLoading(false);
+			setRefreshing(false);
 		};
 	}, [
 		action,
 		options.params || params,
-		reloadTimes,
-		skip
+		requestTrigger,
+		skip,
+		options.debounce,
+		options.polling,
+		options.baseUrl
 	]);
+	const reload = useEqualCallback((nextParams, reloadOptions) => {
+		if (skip) setSkip(false);
+		if (nextParams) setParams(nextParams);
+		const reloadCounter = ++reloadCounterRef.current;
+		return new Promise((resolve, reject) => {
+			pendingReloadsRef.current.set(reloadCounter, {
+				resolve,
+				reject
+			});
+			setRequestTrigger((prev) => ({
+				times: prev.times + 1,
+				silent: Boolean(reloadOptions?.silent)
+			}));
+		});
+	}, [skip]);
 	return {
 		loading,
+		refreshing,
 		error,
 		params,
-		reloadTimes,
-		reload: useEqualCallback((nextParams) => {
-			if (skip) setSkip(false);
-			if (nextParams) setParams(nextParams);
-			const reloadCounter = ++reloadCounterRef.current;
-			return new Promise((resolve, reject) => {
-				pendingReloadsRef.current.set(reloadCounter, {
-					resolve,
-					reject
-				});
-				setReloadTimes((prev) => prev + 1);
-			});
-		}, [skip]),
+		reloadTimes: requestTrigger.times,
+		reload,
 		promiseRef,
 		setError,
 		setLoading
 	};
 }
 //#endregion
-//#region src/useFaas.tsx
+//#region src/useFaas/index.tsx
 /**
 * Request FaasJS data and keep request state in React state.
 *
 * `useFaas` is the default hook for standard FaasJS request-response flows in React.
 * It sends an initial request unless `skip` is enabled, and returns request state
-* plus helpers for reloading, updating data, and handling errors.
+* plus helpers for reloading, background refreshing, updating data, and handling errors.
 *
 * @template PathOrData - Action path or response data type used for inference.
 *
 * @param {FaasAction<PathOrData>} action - Action path to invoke.
 * @param {FaasParams<PathOrData>} defaultParams - Params used for the initial request and future reloads.
-* @param {useFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, and base URL overrides.
-* See the `useFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+* @param {useFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, polling, and base URL overrides.
+* See the `useFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
 * @returns {FaasDataInjection<PathOrData>} Request state and helper methods described by {@link FaasDataInjection}.
 *
 * @example
@@ -1359,6 +1407,7 @@ function useFaas(action, defaultParams, options = {}) {
 		action,
 		params: request.params,
 		loading: request.loading,
+		refreshing: request.refreshing,
 		data: currentData,
 		reloadTimes: request.reloadTimes,
 		error: request.error,
@@ -1469,7 +1518,7 @@ function getClient(host) {
 	return client;
 }
 //#endregion
-//#region src/constant.ts
+//#region src/constant/index.ts
 /**
 * Returns a constant value that is created by the given function.
 *
@@ -1494,7 +1543,7 @@ function useConstant(fn) {
 	return ref.current.v;
 }
 //#endregion
-//#region src/ErrorBoundary.tsx
+//#region src/ErrorBoundary/index.tsx
 /**
 * React error boundary with an optional custom fallback element.
 *
@@ -1568,7 +1617,7 @@ var ErrorBoundary = class extends Component {
 	}
 };
 //#endregion
-//#region src/OptionalWrapper.tsx
+//#region src/OptionalWrapper/index.tsx
 /**
 * Conditionally wrap children with another component.
 *
@@ -1604,7 +1653,7 @@ function OptionalWrapper(props) {
 }
 OptionalWrapper.displayName = "OptionalWrapper";
 //#endregion
-//#region src/splittingState.tsx
+//#region src/splittingState/index.tsx
 /**
 * Create local state entries and matching setters for each key in an object.
 *
@@ -1633,7 +1682,7 @@ function useSplittingState(initialStates) {
 	return states;
 }
 //#endregion
-//#region src/splittingContext.tsx
+//#region src/splittingContext/index.tsx
 /**
 * Create a context whose keys can be consumed independently.
 *
@@ -1721,7 +1770,7 @@ function createSplittingContext(defaultValue) {
 	};
 }
 //#endregion
-//#region src/useFaasStream.tsx
+//#region src/useFaasStream/index.tsx
 /**
 * Stream a FaasJS response into React state.
 *
@@ -1731,8 +1780,8 @@ function createSplittingContext(defaultValue) {
 *
 * @param {string} action - Action path to invoke.
 * @param {Record<string, any>} defaultParams - Params used for the initial request and future reloads.
-* @param {UseFaasStreamOptions} [options] - Optional hook configuration such as controlled stream text, skip logic, debounce timing, and base URL overrides.
-* See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, and `baseUrl`.
+* @param {UseFaasStreamOptions} [options] - Optional hook configuration such as controlled stream text, skip logic, debounce timing, polling, and base URL overrides.
+* See the `UseFaasStreamOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
 * @returns {UseFaasStreamResult} Streaming request state and helper methods described by {@link UseFaasStreamResult}.
 *
 * @example
@@ -1766,7 +1815,9 @@ function useFaasStream(action, defaultParams, options = {}) {
 		action,
 		defaultParams,
 		options,
-		beforeSend: () => updateData(""),
+		beforeSend: ({ silent }) => {
+			if (!silent) updateData("");
+		},
 		send: async ({ action, params, signal, client }) => {
 			const response = await client.browserClient.action(action, params, {
 				signal,
@@ -1809,6 +1860,7 @@ function useFaasStream(action, defaultParams, options = {}) {
 		action,
 		params: request.params,
 		loading: request.loading,
+		refreshing: request.refreshing,
 		reloadTimes: request.reloadTimes,
 		data: options.data ?? data,
 		error: request.error,
@@ -1819,7 +1871,7 @@ function useFaasStream(action, defaultParams, options = {}) {
 	};
 }
 //#endregion
-//#region src/usePrevious.ts
+//#region src/usePrevious/index.ts
 /**
 * Hook to store the previous value of a state or prop.
 *
@@ -1846,7 +1898,7 @@ function usePrevious(value) {
 	return ref.current;
 }
 //#endregion
-//#region src/useStateRef.ts
+//#region src/useStateRef/index.ts
 /**
 * Custom hook that returns a stateful value and a ref to that value.
 *

package/package.json

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