@ametie/vue-muza-use 0.2.0 → 0.3.1

package/README.md

@@ -200,6 +200,38 @@ useApiPost('/user/settings', {
 })
 ```
 
+### ⏰ Auto-Polling (Interval)
+Keep your data fresh with built-in polling support. It works smartly: by default, it **pauses** when the tab is hidden and **resumes immediately** when the user returns.
+
+#### Simple Polling
+Fetch data every 5 seconds.
+```typescript
+const { data } = useApi('/notifications', {
+  poll: 5000 // Simple number: interval in ms
+})
+```
+
+#### Smart Control
+Configure pause behavior and interval explicitly.
+```typescript
+useApi('/stock-prices', {
+  poll: {
+    interval: 1000,
+    whenHidden: true // ⚠️ Keep polling even if tab is backgrounded
+  }
+})
+```
+
+#### Reactive Polling
+You can pass a `Ref` to control polling dynamically. Perfect for "Pause/Resume" buttons.
+```typescript
+const interval = ref(3000)
+
+// If you set interval.value = 0, polling stops.
+// If you change it to 5000, it restarts with new interval immediately.
+useApi('/live-feed', { poll: interval })
+```
+
 ### Global Abort (Race Condition Killer)
 Useful for complex filters where changing one filter should invalidate all pending requests on the page (or scope).
 
@@ -290,6 +322,7 @@ The main composable.
 | `retry` | `boolean \| number` | `false` | Number of retries on failure. |
 | `debounce` | `number` | `0` | Debounce time in ms. |
 | `watch` | `WatchSource \| WatchSource[]` | `undefined` | Ref(s) to watch for auto-execution. |
+| `poll`  | `number \| { interval: number, whenHidden?: boolean } \| Ref` | `0` | Polling interval. Default pauses when hidden. |
 | `authMode` | `'default' \| 'public'` | `'default'` | `'public'` skips token injection. |
 | `initialData` | `T` | `null` | Initial value for `data` ref. |
 | `onSuccess` | `(res) => void` | - | Callback on 2xx response. |

package/dist/index.cjs

@@ -198,13 +198,27 @@ function useApi(url, options = {}) {
     authMode = "default",
     useGlobalAbort = globalOptions?.useGlobalAbort ?? true,
     initialLoading = false,
+    poll = 0,
     ...axiosConfig
   } = options;
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
   const abortController2 = (0, import_vue4.ref)(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
+  let pollTimer = null;
+  const getPollConfig = () => {
+    const val = (0, import_vue4.toValue)(poll);
+    if (typeof val === "number") return { interval: val, whenHidden: false };
+    if (val && typeof val === "object") {
+      return {
+        interval: (0, import_vue4.toValue)(val.interval),
+        whenHidden: (0, import_vue4.toValue)(val.whenHidden) ?? false
+      };
+    }
+    return { interval: 0, whenHidden: false };
+  };
   const executeRequest = async (config) => {
+    if (pollTimer) clearTimeout(pollTimer);
     const requestUrl = typeof url === "string" ? url : url.value;
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
     const controller = new AbortController();
@@ -260,11 +274,25 @@ function useApi(url, options = {}) {
       if (!wasCancelled) {
         state.setLoading(false);
         onFinish?.();
+        const { interval, whenHidden } = getPollConfig();
+        if (interval > 0) {
+          const shouldPoll = whenHidden || typeof document !== "undefined" && !document.hidden;
+          if (shouldPoll) {
+            pollTimer = setTimeout(() => {
+              pollTimer = null;
+              const { whenHidden: currentWhenHidden } = getPollConfig();
+              if (currentWhenHidden || (typeof document === "undefined" || !document.hidden)) {
+                execute();
+              }
+            }, interval);
+          }
+        }
       }
     }
   };
   const execute = debounce > 0 ? debounceFn(executeRequest, debounce) : executeRequest;
   const abort = (msg) => {
+    if (pollTimer) clearTimeout(pollTimer);
     abortController2.value?.abort(msg);
     abortController2.value = null;
   };
@@ -282,6 +310,38 @@ function useApi(url, options = {}) {
     (0, import_vue4.onScopeDispose)(() => abort("Scope disposed"));
   }
   if (immediate) execute();
+  if (typeof document !== "undefined") {
+    const handleVisibility = () => {
+      if (document.hidden) return;
+      const { interval } = getPollConfig();
+      if (interval > 0 && !pollTimer && !state.loading.value) {
+        execute();
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibility);
+    if ((0, import_vue4.getCurrentScope)()) {
+      (0, import_vue4.onScopeDispose)(() => document.removeEventListener("visibilitychange", handleVisibility));
+    }
+  }
+  if (poll) {
+    (0, import_vue4.watch)(() => (0, import_vue4.toValue)(poll), () => {
+      const { interval } = getPollConfig();
+      if (interval > 0) {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+        if (!state.loading.value) {
+          execute();
+        }
+      } else {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+      }
+    }, { deep: true });
+  }
   return { ...state, execute, abort, reset };
 }
 function useApiGet(url, options) {

package/dist/index.d.cts

@@ -34,6 +34,16 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
     watch?: WatchSource | WatchSource[];
+    /**
+     * Polling configuration.
+     * - Pass a **number** (ms) for simple polling.
+     * - Pass an **object** `{ interval: number, whenHidden?: boolean }` for advanced control.
+     * Properties inside the object can also be Refs.
+     */
+    poll?: MaybeRefOrGetter<number | {
+        interval: MaybeRefOrGetter<number>;
+        whenHidden?: MaybeRefOrGetter<boolean>;
+    }>;
 }
 interface UseApiReturn<T = unknown, D = unknown> {
     data: Ref<T | null>;

package/dist/index.d.ts

@@ -34,6 +34,16 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
     watch?: WatchSource | WatchSource[];
+    /**
+     * Polling configuration.
+     * - Pass a **number** (ms) for simple polling.
+     * - Pass an **object** `{ interval: number, whenHidden?: boolean }` for advanced control.
+     * Properties inside the object can also be Refs.
+     */
+    poll?: MaybeRefOrGetter<number | {
+        interval: MaybeRefOrGetter<number>;
+        whenHidden?: MaybeRefOrGetter<boolean>;
+    }>;
 }
 interface UseApiReturn<T = unknown, D = unknown> {
     data: Ref<T | null>;

package/dist/index.mjs

@@ -148,13 +148,27 @@ function useApi(url, options = {}) {
     authMode = "default",
     useGlobalAbort = globalOptions?.useGlobalAbort ?? true,
     initialLoading = false,
+    poll = 0,
     ...axiosConfig
   } = options;
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
   const abortController2 = ref3(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
+  let pollTimer = null;
+  const getPollConfig = () => {
+    const val = toValue(poll);
+    if (typeof val === "number") return { interval: val, whenHidden: false };
+    if (val && typeof val === "object") {
+      return {
+        interval: toValue(val.interval),
+        whenHidden: toValue(val.whenHidden) ?? false
+      };
+    }
+    return { interval: 0, whenHidden: false };
+  };
   const executeRequest = async (config) => {
+    if (pollTimer) clearTimeout(pollTimer);
     const requestUrl = typeof url === "string" ? url : url.value;
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
     const controller = new AbortController();
@@ -210,11 +224,25 @@ function useApi(url, options = {}) {
       if (!wasCancelled) {
         state.setLoading(false);
         onFinish?.();
+        const { interval, whenHidden } = getPollConfig();
+        if (interval > 0) {
+          const shouldPoll = whenHidden || typeof document !== "undefined" && !document.hidden;
+          if (shouldPoll) {
+            pollTimer = setTimeout(() => {
+              pollTimer = null;
+              const { whenHidden: currentWhenHidden } = getPollConfig();
+              if (currentWhenHidden || (typeof document === "undefined" || !document.hidden)) {
+                execute();
+              }
+            }, interval);
+          }
+        }
       }
     }
   };
   const execute = debounce > 0 ? debounceFn(executeRequest, debounce) : executeRequest;
   const abort = (msg) => {
+    if (pollTimer) clearTimeout(pollTimer);
     abortController2.value?.abort(msg);
     abortController2.value = null;
   };
@@ -232,6 +260,38 @@ function useApi(url, options = {}) {
     onScopeDispose(() => abort("Scope disposed"));
   }
   if (immediate) execute();
+  if (typeof document !== "undefined") {
+    const handleVisibility = () => {
+      if (document.hidden) return;
+      const { interval } = getPollConfig();
+      if (interval > 0 && !pollTimer && !state.loading.value) {
+        execute();
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibility);
+    if (getCurrentScope()) {
+      onScopeDispose(() => document.removeEventListener("visibilitychange", handleVisibility));
+    }
+  }
+  if (poll) {
+    watch(() => toValue(poll), () => {
+      const { interval } = getPollConfig();
+      if (interval > 0) {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+        if (!state.loading.value) {
+          execute();
+        }
+      } else {
+        if (pollTimer) {
+          clearTimeout(pollTimer);
+          pollTimer = null;
+        }
+      }
+    }, { deep: true });
+  }
   return { ...state, execute, abort, reset };
 }
 function useApiGet(url, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ametie/vue-muza-use",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Powerful Vue 3 API composable (Muza Kit) with Axios, Auto-Refresh & TypeScript",
   "author": "MortyQ",
   "license": "MIT",
@@ -44,6 +44,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "test": "vitest",
     "dev": "tsup --watch"
   },
   "peerDependencies": {
@@ -55,10 +56,13 @@
     "@semantic-release/github": "^12.0.3",
     "@semantic-release/npm": "^13.1.3",
     "@types/node": "^24.10.10",
+    "@vue/test-utils": "^2.4.6",
     "axios": "^1.13.4",
+    "happy-dom": "^20.5.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
     "vue": "^3.5.27"
   }
 }