@ametie/vue-muza-use 0.9.1 → 0.11.0

package/README.md

@@ -5,29 +5,71 @@
 [![Vue 3](https://img.shields.io/badge/Vue-3.x-green.svg?style=flat-square)](https://vuejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Included-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
 
-**Type-safe, feature-rich Axios wrapper for Vue 3 Composition API. Built for real-world business logic.**
+**TypeScript-first, feature-rich Axios wrapper for Vue 3 Composition API. Built for real-world business logic.**
 
 A production-ready composable that eliminates boilerplate and solves the hard problems: race conditions, token refresh queues, automatic retries, and reactive request management. Write less code, ship faster, sleep better.
 
+> [!IMPORTANT]
+> ### 🤖 Claude Code — Built-in AI Skill
+>
+> This library ships with a skill that teaches Claude the feature wrapper pattern, naming conventions, and all `UseApiOptions`.
+> Claude will generate correct, architecture-consistent API layer code out of the box — no extra prompting needed.
+>
+> 📄 **[View skill file →](https://github.com/MortyQ/vue-muza-use/blob/main/.claude/skills/use-api/SKILL.md)**
+
 ---
 
+> **Using v0.x?** The legacy documentation is available at [v0.10.0 README](https://github.com/MortyQ/vue-muza-use/blob/v0.10.0/packages/use-api/README.md).
+
 ## ✨ Features
 
 **Core Features** (Get started in minutes):
-- 🎯 **Fully Type-Safe** — End-to-end TypeScript support with strict typing for requests and responses
-- 🔄 **Smart Reactivity** — Watch refs and automatically refetch when dependencies change
+- 🎯 **TypeScript-first** — Full TypeScript support with strict typing for requests and responses
+- 🔄 **Smart Reactivity** — Auto-tracks reactive deps in `url`, `params`, and `data` — refetches automatically when they change
 - ⏱️ **Built-in Debouncing** — Perfect for search inputs and auto-save forms
 - 🛡️ **Race Condition Protection** — Global abort controller cancels stale requests automatically
 - 📊 **Auto-Polling** — Built-in interval fetching with smart tab visibility detection
 - 🚀 **Batch Requests** — Execute multiple requests in parallel with progress tracking
 - 🧹 **Zero Memory Leaks** — Automatic cleanup of pending requests on component unmount
-- 🔕 **ignoreUpdates** — Atomic updates without triggering intermediate requests
+- 🔕 **ignoreUpdates** — Update reactive deps silently without triggering a re-fetch
 - 🗄️ **Response Caching** — In-memory cache with configurable TTL and manual invalidation
+- ⚡ **Stale-While-Revalidate** — Serve cached data instantly while refreshing silently in the background
+- 🔬 **select** — Transform or filter response data declaratively; re-applied on every fetch automatically
 
 **Advanced Features** (When you need them):
 - ♻️ **Intelligent Retries** — Lifecycle-aware retry logic with configurable status codes
 - 🔐 **JWT Token Management** — Automatic token refresh with request queueing on 401 responses
 - 🎛️ **Flexible Architecture** — Bring your own Axios instance with full configuration control
+- 🍪 **withCredentials** — Per-request cookie and cross-origin credential control
+
+---
+
+## 🆚 How it compares
+
+> Honest comparison. ✅ built-in · ⚠️ partial or plugin needed · ❌ not supported
+
+| Feature | vue-muza-use | @vueuse/useFetch | TanStack Query | swrv |
+|---------|:---:|:---:|:---:|:---:|
+| **Axios-first** | ✅ | ❌ fetch | ⚠️ adapter | ❌ fetch |
+| **JWT auto-refresh + queue** | ✅ | ❌ | ❌ | ❌ |
+| **Race condition protection** | ✅ | ❌ | ✅ | ❌ |
+| **ignoreUpdates** | ✅ | ❌ | ❌ | ❌ |
+| **Built-in debounce** | ✅ | ❌ | ❌ | ❌ |
+| **Batch requests** | ✅ | ❌ | ❌ | ❌ |
+| **Built-in retry** | ✅ | ❌ | ✅ | ❌ |
+| **Auto-polling** | ✅ | ❌ | ✅ | ✅ |
+| **SWR (stale-while-revalidate)** | ✅ | ❌ | ✅ | ✅ |
+| **select / transform** | ✅ | ❌ | ✅ | ❌ |
+| **Response caching** | ✅ | ❌ | ✅ | ✅ |
+| **TypeScript** | ✅ | ✅ | ✅ | ✅ |
+| **SSR / Nuxt** | ❌ | ✅ | ✅ | ✅ |
+| **DevTools** | ❌ | ❌ | ✅ | ❌ |
+
+**Choose vue-muza-use if:** you build Vue 3 SPAs with Axios, need JWT token refresh out of the box, and want reactive request management without a heavyweight server-state solution.
+
+**Choose TanStack Query if:** you need SSR, DevTools, or advanced server-state normalization.
+
+**Choose @vueuse/useFetch if:** you want a minimal fetch wrapper with no opinions.
 
 ---
 
@@ -40,13 +82,15 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 
 **Core Features:**
 - [Watch & Auto-Refetch](#watch--auto-refetch)
-  - [ignoreUpdates — Atomic Updates Without Refetch](#ignoreupdates--atomic-updates-without-refetch)
+  - [ignoreUpdates — Update Without Re-fetching](#ignoreupdates--update-without-re-fetching)
 - [Response Caching](#response-caching)
+  - [Stale-While-Revalidate (SWR)](#stale-while-revalidate-swr)
 - [Polling (Background Updates)](#polling-background-updates)
 - [Error Handling](#error-handling)
   - [retry — Automatic Request Retry](#retry--automatic-request-retry)
 - [Loading States](#loading-states)
 - [Manual Data Updates (mutate)](#manual-data-updates-mutate)
+- [select — Declarative Data Transformation](#select--declarative-data-transformation)
 
 **Real-World Examples:**
 - [Data Table with Pagination](#data-table-with-pagination--sorting)
@@ -154,7 +198,6 @@ const searchQuery = ref('')
 const { data, loading } = useApi<Product[]>(
   () => `/products/search?q=${searchQuery.value}`,
   {
-    watch: searchQuery,
     debounce: 500
   }
 )
@@ -257,7 +300,6 @@ const filters = ref({
 
 const { data } = useApi('/users', {
   params: filters,
-  watch: filters,
   immediate: true
 })
 ```
@@ -279,7 +321,6 @@ const id = ref<number | null>(null)
 
 const { data } = useApi<User>(
   () => id.value ? `/users/${id.value}` : undefined,
-  { watch: id }
 )
 
 // No request fires until id.value is set
@@ -342,162 +383,130 @@ const { execute, loading, error } = useApi<LoginResponse>(
 
 ### Watch & Auto-Refetch
 
-Watch refs and automatically refetch when they change. Perfect for filters, search, and dynamic content.
+**TL;DR: Pass reactive refs or getters to `url`, `params`, or `data` — the request re-fires automatically when they change.**
+
+Any reactive dependency accessed inside a getter is tracked automatically. No explicit `watch` option needed.
 
-#### Single Dependency
 ```typescript
 import { ref } from 'vue'
 import { useApi } from '@ametie/vue-muza-use'
 
-interface User {
-  id: number
-  name: string
-}
-
-const userId = ref(1)
+const search = ref('')
+const page = ref(1)
 
-const { data } = useApi<User>(
-  () => `/users/${userId.value}`,
-  { watch: userId, immediate: true }
-)
+// Reactive params getter — both search and page are tracked automatically
+const { data, loading } = useApi('/products', {
+  params: () => ({ q: search.value, page: page.value }),
+  immediate: true,
+})
 
-userId.value = 2  // → automatic refetch
+// Change any dep → request re-fires automatically
+search.value = 'shoes'
+page.value = 2
 ```
 
-#### Multiple Dependencies
+**Reactive URL:**
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+const userId = ref(1)
 
-const searchQuery = ref('')
-const category = ref('all')
+const { data } = useApi(() => `/users/${userId.value}`, {
+  immediate: true,
+})
 
-const { data } = useApi(
-  () => `/products?q=${searchQuery.value}&category=${category.value}`,
-  {
-    watch: [searchQuery, category],
-    debounce: 500
-  }
-)
+userId.value = 2  // → re-fetches /users/2 automatically
 ```
 
-#### Auto-Save Form
+**Opt-out with `lazy: true`:**
+
+For forms and manual mutations where you control when `execute()` is called:
+
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+const form = ref({ name: '', email: '' })
 
-const settings = ref({
-  theme: 'dark',
-  notifications: true
+const { execute, loading } = useApi('/users', {
+  method: 'POST',
+  data: form,
+  lazy: true,  // form changes do NOT trigger re-fetch
+  onSuccess: () => router.push('/users'),
 })
 
-useApi('/user/settings', {
-  method: 'PUT',
-  data: settings,
-  watch: settings,
-  debounce: 1000,
-  onSuccess: () => console.log('Saved!')
-})
+// Only fires when you call it
+async function submit() {
+  await execute()
+}
 ```
 
----
-
-### ignoreUpdates — Atomic Updates Without Refetch
-
-**TL;DR: Change multiple reactive values at once without triggering a request between each change.**
-
-When `watch` is active, every change to a watched ref triggers a new request. If you need to update three filter fields at once, you'd get three requests instead of one. `ignoreUpdates` wraps your changes so the watcher stays silent while you update all fields, then you call `execute()` once.
-
-#### ❌ Without ignoreUpdates — 2 requests fire
+**`immediate` works independently of auto-tracking:**
 
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
-
-const page = ref(1)
-const search = ref('')
-
-const { execute } = useApi('/users', {
-  params: { page, search },
-  watch: [page, search]
+// Fetch on mount + re-fetch on dep change
+useApi('/products', {
+  params: () => ({ q: search.value }),
+  immediate: true,
 })
 
-// BAD: each assignment triggers a separate request
-page.value = 1    // → request 1: page=1, search=''
-search.value = 'john'  // → request 2: page=1, search=john
+// No fetch on mount, but re-fetch on dep change
+useApi('/products', {
+  params: () => ({ q: search.value }),
+  // immediate: false is the default
+})
 ```
 
-#### ✅ With ignoreUpdates — 1 request fires
+**Batching:** Vue batches synchronous reactive changes before triggering auto-tracking — two synchronous ref changes fire only one request.
 
 ```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+// Only one request fires (Vue batches sync changes)
+status.value = 'active'
+page.value = 1
+```
 
-const page = ref(1)
-const search = ref('')
+---
 
-const { execute, ignoreUpdates } = useApi('/users', {
-  params: { page, search },
-  watch: [page, search]
-})
+### ignoreUpdates — Update Without Re-fetching
 
-// GOOD: all changes are batched, only one request fires
-ignoreUpdates(() => {
-  page.value = 1
-  search.value = 'john'
-})
-await execute()  // → single request: page=1, search=john
-```
+**TL;DR: Update a reactive dep without triggering auto-tracking.**
 
-#### Reset filters without auto-fetching
+When auto-tracking is active, any reactive dep change fires a new request. `ignoreUpdates` pauses the tracking scope for the duration of the callback — changes inside do not trigger a re-fetch.
 
-Use `ignoreUpdates` to reset all filters to their defaults, then manually trigger a single request.
+#### Example — clear search input without fetching
 
 ```typescript
 import { ref } from 'vue'
 import { useApi } from '@ametie/vue-muza-use'
 
-const page = ref(1)
 const search = ref('')
-const status = ref('all')
 
-const { execute, ignoreUpdates } = useApi('/users', {
-  params: { page, search, status },
-  watch: [page, search, status]
+const { data, ignoreUpdates } = useApi('/products', {
+  params: () => ({ q: search.value }),
+  debounce: 300,
 })
 
-function resetFilters() {
+function clearSearch() {
   ignoreUpdates(() => {
-    page.value = 1
     search.value = ''
-    status.value = 'all'
   })
-  execute()  // single request with reset values
+  // auto-tracking is paused — no request fires
 }
 ```
 
-#### Safe to call without a watch option
+The user types → auto-tracking fires → debounced request. Clicking "Clear" resets the input without triggering a fetch.
 
-If no `watch` option is configured, `ignoreUpdates` still runs the updater — it just has nothing to suppress.
+#### Safe to call when `lazy: true`
 
-```typescript
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+If `lazy: true`, `ignoreUpdates` still runs the updater — it just has nothing to suppress.
 
-const counter = ref(0)
+```typescript
 const { ignoreUpdates } = useApi('/data')
 
-// Safe — no error thrown, updater still runs
 ignoreUpdates(() => {
-  counter.value = 42
+  someRef.value = 42  // runs normally, nothing to suppress
 })
 ```
 
 > [!NOTE]
 > `ignoreUpdates` is synchronous only. Changes made after an `await` inside the
 > updater function will NOT be suppressed — the flag resets after the synchronous
-> portion completes. If you need to update async values, update them outside
-> `ignoreUpdates` and call `execute()` manually.
+> portion completes.
 
 ---
 
@@ -610,9 +619,9 @@ invalidateCache(['products', 'categories'])
 clearAllCache()
 ```
 
-#### cache + watch
+#### cache + auto-tracking
 
-When `watch` is configured, each watch-triggered `execute()` still checks the cache first:
+When auto-tracking is active, each dep-change-triggered `execute()` still checks the cache first:
 
 ```vue
 <script setup lang="ts">
@@ -623,7 +632,7 @@ const categoryId = ref<number>(1)
 
 const { data } = useApi<Product[]>(() => `/categories/${categoryId.value}/products`, {
   cache: { id: `products-cat-${categoryId.value}`, staleTime: 30_000 },
-  watch: categoryId,
+  params: () => ({ category: categoryId.value }),
   immediate: true,
 })
 </script>
@@ -660,6 +669,7 @@ const { data } = useApi('/reports', {
 |-------|------|---------|-------------|
 | `id` | `string` | — | Unique cache key |
 | `staleTime` | `number` | `300_000` | TTL in milliseconds. Entry is deleted on next read after this time |
+| `swr` | `boolean` | `false` | Stale-while-revalidate: serve cached data instantly while revalidating in the background. See [SWR](#stale-while-revalidate-swr) |
 
 #### Out of Scope (by design)
 
@@ -679,6 +689,68 @@ The following are intentionally **not** supported in v1:
 
 ---
 
+### Stale-While-Revalidate (SWR)
+
+**TL;DR: Return cached data instantly while fetching fresh data in the background. No loading spinner, no blank screen.**
+
+Requires the `cache` option to be set. On a cache hit, the stale data is returned immediately (no `loading: true`, no spinner) while a silent background request runs. Use the `revalidating` ref to show a subtle refresh indicator if needed.
+
+On a **cache miss** (first load), the request behaves exactly like a normal request — `loading: true`, no stale data.
+
+#### Basic Usage
+
+```vue
+<script setup lang="ts">
+import { useApi } from '@ametie/vue-muza-use'
+
+interface User { id: number; name: string }
+
+const { data, revalidating } = useApi<User[]>('/users', {
+  cache: { id: 'users', swr: true },
+  immediate: true,
+})
+</script>
+
+<template>
+  <!-- data renders immediately from cache — no blank screen -->
+  <ul>
+    <li v-for="user in data" :key="user.id">
+      {{ user.name }}
+      <span v-if="revalidating">↻</span>
+    </li>
+  </ul>
+</template>
+```
+
+#### SWR vs Normal Cache Hit
+
+| | Normal cache hit | SWR cache hit |
+|---|---|---|
+| `loading` | `false` | `false` |
+| `data` | Stale data, no new request | Stale data → then fresh data |
+| `revalidating` | `false` | `true` while fetching, then `false` |
+| Axios request | **Not made** | **Made** (silent background fetch) |
+| `onBefore` | Not called | **Not called** (silent) |
+| `onSuccess` | Not called | **Called** with fresh response |
+| `onFinish` | Not called | **Called** after background fetch |
+
+#### Error Handling
+
+If the background revalidation request fails:
+- `revalidating` resets to `false`
+- `error` is set
+- The **stale data is preserved** — your UI doesn't go blank
+
+```typescript
+const { data, revalidating, error } = useApi('/dashboard', {
+  cache: { id: 'dashboard', swr: true },
+  immediate: true,
+})
+// data.value stays the cached value even after a failed revalidation
+```
+
+---
+
 ### Polling (Background Updates)
 
 **TL;DR: Keep data fresh with smart polling that automatically pauses when the browser tab is hidden.**
@@ -922,7 +994,10 @@ const toggleTodo = (id: number) => {
 }
 ```
 
-#### Transform in `onSuccess`
+#### Transform after fetch
+
+Use `mutate` from the **same** `useApi` call to post-process data after it arrives:
+
 ```typescript
 import { useApi } from '@ametie/vue-muza-use'
 
@@ -933,7 +1008,7 @@ interface User {
   fullName?: string
 }
 
-const { data } = useApi<User[]>('/users', {
+const { data, mutate } = useApi<User[]>('/users', {
   immediate: true,
   onSuccess: ({ data: users }) => {
     mutate(users.map(u => ({
@@ -942,10 +1017,80 @@ const { data } = useApi<User[]>('/users', {
     })))
   }
 })
+```
+
+> [!TIP]
+> If the same transformation runs on every fetch (including polling or watch re-triggers),
+> use [`select`](#select--declarative-data-transformation) instead — it's applied automatically
+> and keeps your options object clean.
+
+---
+
+### select — Declarative Data Transformation
 
-const { mutate } = useApi<User[]>('/users', { immediate: true })
+**TL;DR: Transform, filter, or reshape response data once — it's re-applied automatically on every fetch, polling tick, and SWR revalidation.**
+
+Use `select` when you want the same transformation applied every time the request fires. Unlike `mutate` (which you call manually), `select` is declared once and runs silently on each response.
+
+The second generic parameter of `useApi` controls the output type of `select`.
+
+#### Extract a Nested Field
+
+APIs that wrap responses in `{ data: [...], meta: {...} }`:
+
+```typescript
+interface ApiResponse { data: User[]; meta: { total: number } }
+interface User { id: number; name: string }
+
+const { data } = useApi<ApiResponse, User[]>('/users', {
+  immediate: true,
+  select: (res) => res.data,
+  // data.value is User[], not ApiResponse
+})
 ```
 
+#### Transform Items
+
+```typescript
+interface RawUser { id: number; firstName: string; lastName: string }
+interface User { id: number; fullName: string }
+
+const { data } = useApi<RawUser[], User[]>('/users', {
+  immediate: true,
+  select: (users) => users.map(u => ({
+    id: u.id,
+    fullName: `${u.firstName} ${u.lastName}`,
+  })),
+})
+```
+
+#### Filter Results
+
+```typescript
+const { data } = useApi<Task[]>('/tasks', {
+  immediate: true,
+  select: (tasks) => tasks.filter(t => t.status === 'active'),
+})
+```
+
+#### select vs mutate
+
+| | `select` | `mutate` |
+|---|---|---|
+| When it runs | On every successful response (auto) | When you call it manually |
+| With polling | Re-applied on every tick | Need to call in `onSuccess` each time |
+| With SWR | Re-applied on revalidation | Need to call in `onSuccess` |
+| `onSuccess` receives | Raw `AxiosResponse<TRaw>` | — |
+
+> [!NOTE]
+> `onSuccess` always receives the **raw** `AxiosResponse` from the server, not the selected value.
+> This lets you access headers, status, and the original shape if needed.
+
+> [!NOTE]
+> The cache always stores the **raw** server response, not the selected value.
+> `select` is re-applied each time data is read from cache — including SWR cache hits.
+> If you change your `select` function, the next cache hit will re-apply the new transformation.
+
 ---
 
 ## 📊 Real-World Examples
@@ -980,7 +1125,6 @@ const params = computed(() => ({
 
 const { data, loading } = useApi<OrdersResponse>('/orders', {
   params,
-  watch: params,
   immediate: true
 })
 </script>
@@ -1277,6 +1421,8 @@ createApp(App).use(createApi({
 | `retryDelay` | `number` | `1000` | How many milliseconds to wait between retry attempts for all requests |
 | `retryStatusCodes` | `number[]` | `[408,429,500,502,503,504]` | Default HTTP status codes that trigger a retry across all requests |
 | `useGlobalAbort` | `boolean` | `true` | When `true`, all requests subscribe to the global abort controller |
+| `refetchOnFocus` | `boolean \| { throttle?: number }` | `undefined` | Apply `refetchOnFocus` to all `useApi` instances. Per-request value takes precedence (including `false` to opt-out) |
+| `refetchOnReconnect` | `boolean` | `undefined` | Apply `refetchOnReconnect` to all `useApi` instances. Per-request value takes precedence (including `false` to opt-out) |
 
 ---
 
@@ -1352,6 +1498,38 @@ const api = createApiClient({
 
 ---
 
+### withCredentials — Per-Request Cookie Control
+
+**TL;DR: Override the Axios instance default for a single request without changing global settings.**
+
+`withCredentials` controls whether cookies and other credentials are included in cross-origin requests (CORS). Set it globally in `createApiClient` and override it per request when needed.
+
+```typescript
+// Global: withCredentials: false (Bearer token auth, no cookies)
+const api = createApiClient({ baseURL: '/api' })
+
+// Override: this specific endpoint needs cookies
+const { data } = useApi('/user/session', {
+  withCredentials: true,
+  immediate: true,
+})
+```
+
+```typescript
+// Global: withCredentials: true (full cookie-based auth)
+const api = createApiClient({ baseURL: '/api', withCredentials: true })
+
+// Override: skip cookies for a public CDN request
+const { data } = useApi('https://cdn.example.com/config.json', {
+  withCredentials: false,
+  immediate: true,
+})
+```
+
+Omitting `withCredentials` in `useApi` options means the Axios instance default is used — no override applied.
+
+---
+
 ### Saving Tokens After Login
 
 ```typescript
@@ -1660,14 +1838,22 @@ function useMyCustomComposable<T>(fetchFn: () => Promise<T>) {
 
 ## 📚 API Reference
 
-### `useApi<T, D>(url, options)`
+### `useApi<TRaw, D, TSelected>(url, options)`
+
+Three type parameters — all optional with defaults:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `TRaw` | `unknown` | Shape of the raw response data from the server |
+| `D` | `unknown` | Shape of the request body / params |
+| `TSelected` | `TRaw` | Shape of `data.value` after `select` is applied. Equals `TRaw` when `select` is not used |
 
 **Arguments:**
 
 | Argument | Type | Description |
 |----------|------|-------------|
 | `url` | `MaybeRefOrGetter<string \| undefined>` | API endpoint. String, ref, or getter function. Returning `undefined` prevents the request. |
-| `options` | `UseApiOptions<T, D>` | Configuration object (see below). |
+| `options` | `UseApiOptions<TRaw, D, TSelected>` | Configuration object (see below). |
 
 ---
 
@@ -1688,16 +1874,23 @@ function useMyCustomComposable<T>(fetchFn: () => Promise<T>) {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `immediate` | `boolean` | `false` | When `true`, executes the request automatically when the composable is created |
-| `watch` | `WatchSource \| WatchSource[]` | `undefined` | One or more refs to watch — request re-fires when any of them change |
-| `debounce` | `number` | `0` | Milliseconds to wait after the last watch change before firing the request |
+| `lazy` | `boolean` | `false` | Disable auto-tracking — reactive changes to `url`, `params`, and `data` will NOT trigger a re-fetch |
+| `debounce` | `number` | `0` | Milliseconds to debounce auto-tracked re-fetches |
 
 **Caching:**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `cache` | `string \| CacheOptions` | `undefined` | Cache the response in memory. String shorthand uses default 5-min TTL. See [Response Caching](#response-caching) |
+| `cache` | `string \| CacheOptions` | `undefined` | Cache the response in memory. String shorthand uses default 5-min TTL. `CacheOptions.swr: true` enables stale-while-revalidate. See [Response Caching](#response-caching) |
 | `invalidateCache` | `string \| string[]` | `undefined` | Cache key(s) to delete on 2xx success. Never fires on error |
 
+**Refetch Triggers:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `refetchOnFocus` | `boolean \| { throttle?: number }` | `undefined` | Re-fetch when the browser tab regains focus. `true` uses a 60s throttle. Pass `{ throttle: 0 }` to always re-fetch. Configurable globally via `globalOptions` |
+| `refetchOnReconnect` | `boolean` | `undefined` | Re-fetch when the browser regains network connectivity (`online` event). No throttle. Configurable globally via `globalOptions` |
+
 **Polling:**
 
 | Option | Type | Default | Description |
@@ -1712,11 +1905,17 @@ function useMyCustomComposable<T>(fetchFn: () => Promise<T>) {
 | `retryDelay` | `number` | `1000` | How many milliseconds to wait between retry attempts |
 | `retryStatusCodes` | `number[]` | `[408,429,500,502,503,504]` | HTTP status codes that trigger a retry. `[]` means retry on any error |
 
+**Data Transformation:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `select` | `(data: TRaw) => TSelected` | `undefined` | Transform response data before it is stored in `data`. Re-applied on every fetch, polling tick, and SWR revalidation. Cache always stores raw data. See [select](#select--declarative-data-transformation) |
+
 **State Initialization:**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `initialData` | `T` | `null` | Initial value for `data` before the first request completes |
+| `initialData` | `TSelected` | `null` | Initial value for `data` before the first request completes |
 | `initialLoading` | `boolean` | `false` | Initial value for `loading` — set `true` to show a spinner before the first request fires |
 
 **Lifecycle Hooks:**
@@ -1734,6 +1933,12 @@ function useMyCustomComposable<T>(fetchFn: () => Promise<T>) {
 |--------|------|---------|-------------|
 | `skipErrorNotification` | `boolean` | `false` | When `true`, the global `onError` handler is NOT called for this request |
 
+**Credentials:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `withCredentials` | `boolean` | `undefined` | Override the Axios instance default for this request only. `true` = send cookies/credentials, `false` = omit them. Omitting uses the instance default set in `createApiClient` |
+
 **Advanced:**
 
 | Option | Type | Default | Description |
@@ -1746,16 +1951,17 @@ function useMyCustomComposable<T>(fetchFn: () => Promise<T>) {
 
 | Name | Type | Description |
 |------|------|-------------|
-| `data` | `Ref<T \| null>` | Response data from the last successful request |
+| `data` | `Ref<TSelected \| null>` | Response data from the last successful request (transformed by `select` if provided) |
 | `loading` | `Ref<boolean>` | `true` while a request is in flight (including retry delays) |
 | `error` | `Ref<ApiError \| null>` | Error from the last failed request; `null` on success |
 | `statusCode` | `Ref<number \| null>` | HTTP status code from the last completed request |
-| `response` | `Ref<AxiosResponse<T> \| null>` | Full Axios response object including headers |
-| `execute(config?)` | `(config?: ApiRequestConfig<D>) => Promise<T \| null>` | Manually trigger the request, optionally overriding options |
-| `mutate(newData)` | `(newData: T \| null \| ((prev: T \| null) => T \| null)) => void` | Update `data` locally without a network request; clears `error` |
+| `response` | `Ref<AxiosResponse<unknown> \| null>` | Full Axios response object including headers (raw, before `select`) |
+| `revalidating` | `Ref<boolean>` | `true` while a background SWR revalidation is in flight. Always `false` when `cache: { swr: true }` is not set |
+| `execute(config?)` | `(config?: ApiRequestConfig<D>) => Promise<TSelected \| null>` | Manually trigger the request, optionally overriding options |
+| `mutate(newData)` | `(newData: TSelected \| null \| ((prev: TSelected \| null) => TSelected \| null)) => void` | Update `data` locally without a network request; clears `error` |
 | `abort(msg?)` | `(message?: string) => void` | Cancel the current in-flight request |
 | `reset()` | `() => void` | Cancel the request and reset all state to initial values |
-| `ignoreUpdates(fn)` | `(updater: () => void) => void` | Run `updater` without triggering watch-based re-execution |
+| `ignoreUpdates(fn)` | `(updater: () => void) => void` | Run `updater` without triggering auto-tracked re-execution |
 
 #### `execute(config?)`
 
@@ -1998,7 +2204,7 @@ function logout() {
 
 ### 1. Search with Debounce and Reset
 
-Full component: debounced search that resets cleanly without triggering an intermediate request.
+Debounced search input. Typing triggers a request; "Clear" resets the input silently without fetching.
 
 ```vue
 <script setup lang="ts">
@@ -2012,30 +2218,25 @@ interface User {
 }
 
 const search = ref('')
-const page = ref(1)
 
-const { data, loading, execute, ignoreUpdates } = useApi<User[]>(
-  () => `/users?search=${search.value}&page=${page.value}`,
-  {
-    watch: [search, page],
-    debounce: 400,
-    immediate: true
-  }
-)
+const { data, loading, ignoreUpdates } = useApi<User[]>('/users', {
+  params: () => ({ q: search.value }),
+  debounce: 400,
+  immediate: true,
+})
 
-function resetSearch() {
+function clearSearch() {
   ignoreUpdates(() => {
     search.value = ''
-    page.value = 1
   })
-  execute()  // single request with reset values
+  // auto-tracking is paused — no request fires on clear
 }
 </script>
 
 <template>
   <div>
     <input v-model="search" placeholder="Search users..." />
-    <button @click="resetSearch">Clear</button>
+    <button @click="clearSearch">Clear</button>
 
     <div v-if="loading">Searching...</div>
     <ul v-else>
@@ -2051,7 +2252,7 @@ function resetSearch() {
 
 ### 2. Paginated List with Filter Reset
 
-When the user changes a filter, reset the page to 1 using `ignoreUpdates` so only one request fires.
+When the user changes a filter, also reset the page to 1. Vue batches synchronous ref changes, so auto-tracking fires once — no `ignoreUpdates` needed here.
 
 ```vue
 <script setup lang="ts">
@@ -2067,18 +2268,15 @@ interface Post {
 const page = ref(1)
 const status = ref('all')
 
-const { data, loading, execute, ignoreUpdates } = useApi<Post[]>(
-  () => `/posts?status=${status.value}&page=${page.value}`,
-  { watch: [status, page], immediate: true }
-)
+const { data, loading } = useApi<Post[]>('/posts', {
+  params: () => ({ status: status.value, page: page.value }),
+  immediate: true,
+})
 
 function changeStatus(newStatus: string) {
-  // Reset page to 1 when filter changes — one request, not two
-  ignoreUpdates(() => {
-    status.value = newStatus
-    page.value = 1
-  })
-  execute()
+  status.value = newStatus
+  page.value = 1
+  // Vue batches these sync changes — auto-tracking fires once, one request
 }
 </script>
 
@@ -2282,36 +2480,35 @@ Start polling every 2 seconds and stop automatically when the job reaches a term
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue'
-import { useApi } from '@ametie/vue-muza-use'
+  import { ref } from 'vue'
+  import { useApi } from '@ametie/vue-muza-use'
 
-interface JobStatus {
-  id: string
-  status: 'pending' | 'processing' | 'complete' | 'failed'
-  progress: number
-}
+  interface JobStatus {
+    id: string
+    status: 'pending' | 'processing' | 'complete' | 'failed'
+    progress: number
+  }
 
-const jobId = ref<string | null>(null)
-const pollInterval = ref(0)
+  const jobId = ref<string | null>(null)
+  const pollInterval = ref(0)
+
+  const { data: job, error } = useApi<JobStatus>(
+          () => jobId.value ? `/jobs/${jobId.value}` : undefined,
+          {
+            poll: { interval: pollInterval },
+            onSuccess(response) {
+              const { status } = response.data
+              if (status === 'complete' || status === 'failed') {
+                pollInterval.value = 0  // Stop polling
+              }
+            }
+          }
+  )
 
-const { data: job, error } = useApi<JobStatus>(
-  () => jobId.value ? `/jobs/${jobId.value}` : undefined,
-  {
-    watch: jobId,
-    poll: { interval: pollInterval },
-    onSuccess(response) {
-      const { status } = response.data
-      if (status === 'complete' || status === 'failed') {
-        pollInterval.value = 0  // Stop polling
-      }
-    }
+  function startJob(id: string) {
+    jobId.value = id
+    pollInterval.value = 2000  // Start polling every 2s
   }
-)
-
-function startJob(id: string) {
-  jobId.value = id
-  pollInterval.value = 2000  // Start polling every 2s
-}
 </script>
 
 <template>
@@ -2332,7 +2529,7 @@ function startJob(id: string) {
 | Problem | Likely Cause | Fix |
 |---------|--------------|-----|
 | `"createApi config not found"` | `createApi()` not called | Call `app.use(createApi(...))` in `main.ts` before mounting |
-| Request fires twice on mount | `immediate: true` AND `watch` on a ref both trigger on setup | Use only `immediate` OR `watch` for the first load — not both |
+| Request fires twice on mount | `immediate: true` fires on mount; auto-tracking also fires when a dep changes immediately | Ensure deps don't change synchronously right after mount, or use `lazy: true` with manual `execute()` |
 | `retry` option does nothing | Default is `retry: false` | Set `retry: true` or `retry: 3` |
 | ALL errors trigger retry, not just some | `retryStatusCodes` not set — uses library default | Specify exact codes or use `retryStatusCodes: []` to retry on any error |
 | `ignoreUpdates` still triggers a request | Updater function contains an `await` | `ignoreUpdates` is sync-only — move async logic outside the updater |