@ametie/vue-muza-use 0.0.4 → 0.1.0

package/README.md

@@ -151,21 +151,52 @@ const { execute } = useApiPost('/auth/register', {
 })
 ```
 
-### Debounced Search
-Perfect for search inputs to avoid spamming the API.
+### 🔄 Auto-Refetching (Watch & Debounce)
+You can automatically trigger the request whenever specific Refs change. This is perfect for **Live Search** or **Auto-Save** forms.
 
+> **💡 Pro Tip:** When watching text inputs (like search), **always** use `debounce` to prevent flooding your server with requests on every keystroke.
+
+#### Live Search
 ```typescript
 const searchQuery = ref('')
+// Use a computed URL so it updates when execute() is triggered
+const url = computed(() => `/search?q=${searchQuery.value}`)
 
-const { data, execute } = useApi<SearchResult[]>('/search', {
+const { data, loading } = useApi(url, {
   method: 'GET',
-  debounce: 500, // Wait 500ms after last call
-  abortPrevious: true // Kill previous request if new one starts
+  watch: searchQuery, // 👀 Auto-execute when this ref changes
+  debounce: 500,      // ⏳ Wait 500ms after user stops typing
+  abortPrevious: true // Kill previous request if it's still running
 })
+```
+
+#### Filters (Immediate Refetch)
+For inputs like Selects, Toggles, or Tabs where you want instant updates without delay. `watch` accepts an array of Refs.
+
+```typescript
+const category = ref('all')
+const inStock = ref(true)
+
+// URL updates reactively
+const url = computed(() => 
+  `/products?cat=${category.value}&stock=${inStock.value}`
+)
+
+const { data } = useApi(url, {
+  watch: [category, inStock], // 👀 Re-fetch instantly when any filter changes
+  // default debounce is 0
+})
+```
+
+#### Auto-Save Form
+```typescript
+const settings = ref({ theme: 'dark', notifications: true })
 
-// Watcher triggers execute wrapped in debounce
-watch(searchQuery, (newVal) => {
-  execute({ params: { q: newVal } })
+useApiPost('/user/settings', {
+  data: settings,     // Passing ref: library automatically unwraps it
+  watch: settings,    // Watch the form for changes (deep watch supported)
+  debounce: 1000,     // Save after 1 second of inactivity
+  onSuccess: () => console.log('Settings saved!')
 })
 ```
 
@@ -209,6 +240,7 @@ The main composable.
 | `immediate` | `boolean` | `false` | Trigger request automatically on creation. |
 | `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. |
 | `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

@@ -273,6 +273,11 @@ function useApi(url, options = {}) {
     state.reset();
     state.setLoading(false);
   };
+  if (options.watch) {
+    (0, import_vue4.watch)(options.watch, () => {
+      execute();
+    }, { deep: true });
+  }
   if ((0, import_vue4.getCurrentScope)()) {
     (0, import_vue4.onScopeDispose)(() => abort("Scope disposed"));
   }

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as vue from 'vue';
-import { MaybeRefOrGetter, Ref, App } from 'vue';
+import { MaybeRefOrGetter, WatchSource, Ref, App } from 'vue';
 import { AxiosInstance, AxiosRequestConfig, AxiosResponse, CreateAxiosDefaults } from 'axios';
 
 interface ApiError {
@@ -33,6 +33,7 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
     debounce?: number;
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
+    watch?: WatchSource | WatchSource[];
 }
 interface UseApiReturn<T = unknown, D = unknown> {
     data: Ref<T | null>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as vue from 'vue';
-import { MaybeRefOrGetter, Ref, App } from 'vue';
+import { MaybeRefOrGetter, WatchSource, Ref, App } from 'vue';
 import { AxiosInstance, AxiosRequestConfig, AxiosResponse, CreateAxiosDefaults } from 'axios';
 
 interface ApiError {
@@ -33,6 +33,7 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
     debounce?: number;
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
+    watch?: WatchSource | WatchSource[];
 }
 interface UseApiReturn<T = unknown, D = unknown> {
     data: Ref<T | null>;

package/dist/index.mjs

@@ -34,7 +34,7 @@ function debounceFn(fn, delay) {
 }
 
 // src/useApi.ts
-import { ref as ref3, getCurrentScope, onScopeDispose, toValue } from "vue";
+import { ref as ref3, getCurrentScope, onScopeDispose, toValue, watch } from "vue";
 
 // src/utils/errorParser.ts
 function parseApiError(error) {
@@ -223,6 +223,11 @@ function useApi(url, options = {}) {
     state.reset();
     state.setLoading(false);
   };
+  if (options.watch) {
+    watch(options.watch, () => {
+      execute();
+    }, { deep: true });
+  }
   if (getCurrentScope()) {
     onScopeDispose(() => abort("Scope disposed"));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ametie/vue-muza-use",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "Powerful Vue 3 API composable (Muza Kit) with Axios, Auto-Refresh & TypeScript",
   "author": "MortyQ",
   "license": "MIT",