@faasjs/react 8.0.0-beta.24 → 8.0.0-beta.26

package/dist/index.d.ts

@@ -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,6 +1069,7 @@ type SharedUseFaasOptions<Params, Data> = {
   setData?: React.Dispatch<React.SetStateAction<Data>>;
   skip?: boolean | ((params: Params) => boolean);
   debounce?: number;
+  polling?: number | false;
   baseUrl?: BaseUrl;
 };
 //#endregion
@@ -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
@@ -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

package/dist/index.mjs

@@ -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,47 +1275,61 @@ 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
@@ -1294,14 +1342,14 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 *
 * `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,
@@ -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,

package/package.json

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