@ametie/vue-muza-use 0.9.0 → 0.10.0

package/README.md

@@ -9,6 +9,14 @@
 
 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-useApi/blob/main/.claude/skills/use-api/SKILL.md)**
+
 ---
 
 ## ✨ Features
@@ -22,11 +30,15 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 - 🚀 **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
+- 🗄️ **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
 
 ---
 
@@ -40,11 +52,14 @@ 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)
+- [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)
@@ -499,6 +514,248 @@ ignoreUpdates(() => {
 
 ---
 
+### Response Caching
+
+**TL;DR: Pass `cache: 'key'` to serve repeated requests from memory instead of the network. Entries expire after 5 minutes by default.**
+
+The cache is an in-memory `Map` shared across all `useApi` instances in the app.
+It is intentionally simple: no reactive subscriptions, no persistence, no background timers.
+Entries expire **lazily** — stale entries are removed the next time they are read.
+
+#### Basic Usage — String Shorthand
+
+```vue
+<script setup lang="ts">
+import { useApi } from '@ametie/vue-muza-use'
+
+const { data, loading } = useApi<Category[]>('/categories', {
+  cache: 'categories', // uses DEFAULT_STALE_TIME (5 minutes)
+  immediate: true,
+})
+</script>
+```
+
+The first call hits the network and caches the result under the key `'categories'`.
+Every subsequent `execute()` within 5 minutes is served from cache instantly — `loading` never becomes `true` and no axios request is made.
+
+#### Custom TTL — CacheOptions Object
+
+```vue
+<script setup lang="ts">
+import { useApi } from '@ametie/vue-muza-use'
+
+const { data, execute } = useApi<Product[]>('/products', {
+  cache: {
+    id: 'products',
+    staleTime: 60_000, // 1 minute
+  },
+  immediate: true,
+})
+</script>
+```
+
+#### Cache Hit Behavior
+
+When a valid cache entry is found:
+
+| Property / Hook | Cache Hit |
+|---|---|
+| `loading` | stays `false` — never set to `true` |
+| `data` | updated immediately via `mutate()` |
+| `onBefore` | **not called** |
+| `onSuccess` | **not called** |
+| `onFinish` | **not called** |
+| axios request | **not made** |
+
+This is intentional — a cache hit is silent. If you need to know when data comes from cache vs the network, track it with `onSuccess` (only fires on network hits).
+
+#### invalidateCache — Bust Related Caches on Mutation
+
+Use `invalidateCache` on a POST/PUT/DELETE to automatically clear caches when the mutation succeeds.
+
+```vue
+<script setup lang="ts">
+import { useApi } from '@ametie/vue-muza-use'
+
+// GET — caches the list
+const { data: products, execute: reload } = useApi<Product[]>('/products', {
+  cache: 'products',
+  immediate: true,
+})
+
+// POST — busts the list cache on success so the next GET hits the network
+const { execute: createProduct, loading } = useApi('/products', {
+  method: 'POST',
+  invalidateCache: 'products',
+})
+
+async function submit(form: NewProduct) {
+  await createProduct({ data: form })
+  await reload() // cache is gone — fetches fresh data
+}
+</script>
+```
+
+`invalidateCache` fires **only on HTTP 2xx success**. It never runs in `catch` or `finally`.
+Pass an array to bust multiple keys at once:
+
+```typescript
+const { execute } = useApi('/orders', {
+  method: 'POST',
+  invalidateCache: ['orders', 'products', 'inventory'],
+})
+```
+
+#### Imperative Cache Control
+
+Import `invalidateCache` or `clearAllCache` anywhere in your app — outside components, in Pinia stores, in route guards:
+
+```typescript
+import { invalidateCache, clearAllCache } from '@ametie/vue-muza-use'
+
+// Bust a single key (e.g. after a WebSocket push)
+invalidateCache('products')
+
+// Bust multiple keys at once
+invalidateCache(['products', 'categories'])
+
+// Wipe everything — call on logout to prevent data leaks between users
+clearAllCache()
+```
+
+#### cache + watch
+
+When `watch` is configured, each watch-triggered `execute()` still checks the cache first:
+
+```vue
+<script setup lang="ts">
+import { useApi } from '@ametie/vue-muza-use'
+import { ref } from 'vue'
+
+const categoryId = ref<number>(1)
+
+const { data } = useApi<Product[]>(() => `/categories/${categoryId.value}/products`, {
+  cache: { id: `products-cat-${categoryId.value}`, staleTime: 30_000 },
+  watch: categoryId,
+  immediate: true,
+})
+</script>
+```
+
+> [!NOTE]
+> The cache `id` is evaluated once when `useApi` is called. To cache per category,
+> use a computed or a dynamic key string derived from your reactive state.
+
+#### cache + retry
+
+Cache is written **after the final successful attempt**, not after the first.
+If the first attempt fails and a retry succeeds, the retry's response is cached:
+
+```typescript
+const { data } = useApi('/reports', {
+  cache: 'reports',
+  retry: 2,
+  retryStatusCodes: [500, 503],
+  immediate: true,
+})
+```
+
+#### Complete Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cache` | `string \| CacheOptions` | `undefined` | Enable caching. String = `{ id, staleTime: 300_000 }` shorthand |
+| `invalidateCache` | `string \| string[]` | `undefined` | Cache key(s) to delete on 2xx success |
+
+**`CacheOptions`**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `id` | `string` | — | Unique cache key |
+| `staleTime` | `number` | `300_000` | TTL in milliseconds. Entry is deleted on next read after this time |
+
+#### Out of Scope (by design)
+
+The following are intentionally **not** supported in v1:
+
+- 🚫 No reactive cache entries — the cache is a plain `Map`, not Vue refs
+- 🚫 No `localStorage` / `sessionStorage` persistence
+- 🚫 No background TTL timers — expiry is checked lazily on read
+- 🚫 No cache for `useApiBatch` — batch requests manage their own state
+- 🚫 No automatic refetch on cache invalidation — call `execute()` manually after invalidating
+- 🚫 No request deduplication — concurrent calls for the same key each fire their own request
+
+> [!WARNING]
+> The cache store is **module-level** (a singleton). In SSR / Node.js environments it is
+> shared between all incoming requests. Call `clearAllCache()` between requests or avoid
+> using caching in SSR contexts.
+
+---
+
+### 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: 'users',
+  staleWhileRevalidate: 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: 'dashboard',
+  staleWhileRevalidate: 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.**
@@ -768,6 +1025,73 @@ const { mutate } = useApi<User[]>('/users', { immediate: true })
 
 ---
 
+### select — Declarative Data Transformation
+
+**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
 
 ### Data Table with Pagination & Sorting
@@ -1172,6 +1496,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
@@ -1480,14 +1836,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). |
 
 ---
 
@@ -1511,6 +1875,14 @@ function useMyCustomComposable<T>(fetchFn: () => Promise<T>) {
 | `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 |
 
+**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) |
+| `invalidateCache` | `string \| string[]` | `undefined` | Cache key(s) to delete on 2xx success. Never fires on error |
+| `staleWhileRevalidate` | `boolean` | `false` | When `true` and a cache hit occurs, return stale data immediately and revalidate in the background. `revalidating` is `true` during the background fetch. See [SWR](#stale-while-revalidate-swr) |
+
 **Polling:**
 
 | Option | Type | Default | Description |
@@ -1525,11 +1897,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:**
@@ -1547,6 +1925,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 |
@@ -1559,13 +1943,14 @@ 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 `staleWhileRevalidate` 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 |
@@ -1768,6 +2153,45 @@ const { data, loading, error, mutate, setLoading, setError, reset } =
 
 ---
 
+### `invalidateCache(id)` / `clearAllCache()`
+
+**TL;DR: Imperatively delete one, many, or all cache entries from anywhere in your app.**
+
+```typescript
+import { invalidateCache, clearAllCache } from '@ametie/vue-muza-use'
+```
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `invalidateCache` | `(id: string \| string[]) => void` | Delete one or more cache entries by key |
+| `clearAllCache` | `() => void` | Wipe the entire cache — use on logout |
+
+**Example — bust cache after a WebSocket push:**
+
+```typescript
+// pinia store or composable outside a component
+import { invalidateCache } from '@ametie/vue-muza-use'
+
+socket.on('products:updated', () => {
+  invalidateCache('products')
+})
+```
+
+**Example — clear all on logout:**
+
+```typescript
+import { clearAllCache } from '@ametie/vue-muza-use'
+import { tokenManager } from '@ametie/vue-muza-use'
+
+function logout() {
+  tokenManager.clearTokens()
+  clearAllCache() // prevent stale data from leaking to the next user session
+  router.push('/login')
+}
+```
+
+---
+
 ## 🧩 Common Patterns
 
 ### 1. Search with Debounce and Reset

package/dist/index.cjs

@@ -285,11 +285,20 @@ function useApi(url, options = {}) {
     useGlobalAbort = globalOptions?.useGlobalAbort ?? true,
     initialLoading = false,
     poll = 0,
+    // Explicitly excluded from axiosConfig — these are useApi-only options
+    // and must not be forwarded to axios.request()
+    cache: _cache,
+    invalidateCache: _invalidateCache,
+    watch: _watch,
+    staleWhileRevalidate = false,
+    select,
     ...axiosConfig
   } = options;
   const maxRetries = retry === false ? 0 : retry === true ? 3 : retry;
+  const applySelect = (raw) => select ? select(raw) : raw;
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
+  const revalidating = (0, import_vue4.ref)(false);
   const abortController2 = (0, import_vue4.ref)(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
   let pollTimer = null;
@@ -306,11 +315,16 @@ function useApi(url, options = {}) {
   };
   const executeRequest = async (config) => {
     const cacheOpts = normalizeCacheOptions(options.cache);
+    let isRevalidating = false;
     if (cacheOpts) {
       const cached = readCache(cacheOpts.id);
       if (cached !== null) {
-        state.mutate(cached);
-        return cached;
+        state.mutate(applySelect(cached));
+        if (!staleWhileRevalidate) {
+          return applySelect(cached);
+        }
+        isRevalidating = true;
+        revalidating.value = true;
       }
     }
     if (pollTimer) clearTimeout(pollTimer);
@@ -324,15 +338,16 @@ function useApi(url, options = {}) {
       const gs = globalAbort.getSignal();
       if (!gs.aborted) {
         subscribedSignal = gs;
-        const currentCount = globalAbort.abortCount.value;
         globalAbortHandler = () => {
-          if (globalAbort.abortCount.value === currentCount) controller.abort("Global filter change");
+          controller.abort("Cancelled by global abort");
         };
         gs.addEventListener("abort", globalAbortHandler);
       }
     }
-    onBefore?.();
-    state.setLoading(true);
+    if (!isRevalidating) {
+      onBefore?.();
+      state.setLoading(true);
+    }
     state.setError(null);
     let wasCancelled = false;
     let retryCount = 0;
@@ -356,7 +371,8 @@ function useApi(url, options = {}) {
             signal: controller.signal,
             ...{ authMode: config?.authMode || authMode }
           });
-          state.mutate(response.data, response);
+          const selected = applySelect(response.data);
+          state.mutate(selected, response);
           state.setStatusCode(response.status);
           if (cacheOpts) {
             writeCache(cacheOpts.id, response.data, cacheOpts.staleTime);
@@ -365,7 +381,7 @@ function useApi(url, options = {}) {
             invalidateCache(options.invalidateCache);
           }
           onSuccess?.(response);
-          return response.data;
+          return selected;
         } catch (err) {
           if (controller.signal.aborted || (0, import_axios2.isAxiosError)(err) && err.code === "ERR_CANCELED") {
             wasCancelled = true;
@@ -407,8 +423,9 @@ function useApi(url, options = {}) {
       return null;
     } finally {
       if (globalAbortHandler && subscribedSignal) subscribedSignal.removeEventListener("abort", globalAbortHandler);
+      revalidating.value = false;
       if (!wasCancelled) {
-        state.setLoading(false);
+        if (!isRevalidating) state.setLoading(false);
         onFinish?.();
         const { interval, whenHidden } = getPollConfig();
         if (interval > 0) {
@@ -492,8 +509,10 @@ function useApi(url, options = {}) {
       }
     }, { deep: true });
   }
-  return { ...state, execute, abort, reset, ignoreUpdates };
+  return { ...state, revalidating, execute, abort, reset, ignoreUpdates };
 }
+
+// src/useApi.helpers.ts
 function useApiGet(url, options) {
   return useApi(url, { ...options, method: "GET" });
 }

package/dist/index.d.cts

@@ -37,18 +37,97 @@ interface ApiRequestConfig<D = unknown> extends Omit<AxiosRequestConfig<D>, "dat
      * Empty array = retry on any error (network errors included).
      */
     retryStatusCodes?: number[];
+    /**
+     * Include credentials (cookies, Authorization headers) in cross-origin requests.
+     *
+     * Supports three auth strategies:
+     *
+     * **1. Bearer token (default)** — tokens in localStorage, no cookies needed:
+     * ```ts
+     * createApiClient({ baseURL: '/api' }) // withCredentials: false by default
+     * ```
+     *
+     * **2. Full cookie-based auth** — server sets httpOnly cookies for both tokens:
+     * ```ts
+     * createApiClient({ baseURL: '/api', withCredentials: true })
+     * ```
+     *
+     * **3. Hybrid** — Bearer access token + httpOnly refresh cookie:
+     * ```ts
+     * createApiClient({
+     *   baseURL: '/api',
+     *   authOptions: { refreshWithCredentials: true } // cookies only on /auth/refresh
+     * })
+     * ```
+     *
+     * **Per-request override** — override the global setting for a specific request:
+     * ```ts
+     * // Global: withCredentials: false, but this endpoint needs cookies
+     * const { data } = useApi('/user/profile', { withCredentials: true })
+     *
+     * // Global: withCredentials: true, but skip cookies for public CDN
+     * const { data } = useApi('https://cdn.example.com/config.json', {
+     *   withCredentials: false,
+     *   immediate: true
+     * })
+     * ```
+     */
+    withCredentials?: boolean;
 }
-interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
+interface UseApiOptions<T = unknown, D = unknown, TSelected = T> extends ApiRequestConfig<D> {
     immediate?: boolean;
     onSuccess?: (response: AxiosResponse<T>) => void;
     onError?: (error: ApiError) => void;
     onBefore?: () => void;
     onFinish?: () => void;
-    initialData?: T;
+    /**
+     * Transform the raw response data before it is stored in `data`.
+     * Applied on every successful response — including polling, SWR revalidation,
+     * and watch-triggered re-fetches. The cache always stores the raw server data;
+     * `select` is re-applied each time data is read from cache.
+     *
+     * The second generic parameter of `useApi` becomes the output type of `select`.
+     *
+     * @example
+     * ```ts
+     * // Extract nested field
+     * const { data } = useApi<ApiResponse, User[]>('/users', {
+     *   select: (res) => res.data,
+     * })
+     *
+     * // Transform items
+     * const { data } = useApi<RawUser[], User[]>('/users', {
+     *   select: (users) => users.map(u => ({ ...u, fullName: `${u.first} ${u.last}` })),
+     * })
+     * ```
+     */
+    select?: (data: T) => TSelected;
+    initialData?: TSelected;
     debounce?: number;
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
     watch?: WatchSource | WatchSource[];
+    /**
+     * Return cached data immediately and revalidate in the background.
+     *
+     * Requires the `cache` option to be set. On a cache hit the cached value
+     * is returned right away (no loading state, no spinner) while a fresh
+     * request runs silently. The `revalidating` ref is `true` during the
+     * background fetch so you can show a subtle indicator if needed.
+     *
+     * On a cache miss the request behaves normally (loading: true).
+     *
+     * @example
+     * ```ts
+     * const { data, revalidating } = useApi('/users', {
+     *   cache: 'users',
+     *   staleWhileRevalidate: true,
+     *   immediate: true,
+     * })
+     * // Template: <span v-if="revalidating">↻</span>
+     * ```
+     */
+    staleWhileRevalidate?: boolean;
     /**
      * Polling configuration.
      * - Pass a **number** (ms) for simple polling.
@@ -81,7 +160,13 @@ interface UseApiReturn<T = unknown, D = unknown> {
     loading: Ref<boolean>;
     error: Ref<ApiError | null>;
     statusCode: Ref<number | null>;
-    response: Ref<AxiosResponse<T> | null>;
+    response: Ref<AxiosResponse<unknown> | null>;
+    /**
+     * `true` while a background revalidation request is in-flight.
+     * Only active when `staleWhileRevalidate: true` and a cache hit occurred.
+     * Use it to show a subtle refresh indicator without blocking the UI.
+     */
+    revalidating: Ref<boolean>;
     execute: (config?: ApiRequestConfig<D>) => Promise<T | null | undefined>;
     abort: (message?: string) => void;
     reset: () => void;
@@ -254,7 +339,8 @@ declare function createApi(options: ApiPluginOptions): {
 };
 declare function useApiConfig(): ApiPluginOptions;
 
-declare function useApi<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: UseApiOptions<T, D>): UseApiReturn<T, D>;
+declare function useApi<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: UseApiOptions<T, D, TSelected>): UseApiReturn<TSelected, D>;
+
 /**
  * Helper for GET requests
  *
@@ -263,9 +349,14 @@ declare function useApi<T = unknown, D = unknown>(url: MaybeRefOrGetter<string |
  * const { data, loading, error } = useApiGet<User[]>('/users', {
  *   immediate: true
  * })
+ *
+ * // With select:
+ * const { data } = useApiGet<ApiResponse, User[]>('/users', {
+ *   select: (res) => res.data,
+ * })
  * ```
  */
-declare function useApiGet<T = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T>, "method">): UseApiReturn<T>;
+declare function useApiGet<T = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, unknown, TSelected>, "method">): UseApiReturn<TSelected>;
 /**
  * Helper for POST requests
  *
@@ -275,7 +366,7 @@ declare function useApiGet<T = unknown>(url: MaybeRefOrGetter<string | undefined
  * await execute({ data: { name: 'John' } })
  * ```
  */
-declare function useApiPost<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D>, "method">): UseApiReturn<T, D>;
+declare function useApiPost<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D, TSelected>, "method">): UseApiReturn<TSelected, D>;
 /**
  * Helper for PUT requests
  *
@@ -285,7 +376,7 @@ declare function useApiPost<T = unknown, D = unknown>(url: MaybeRefOrGetter<stri
  * await execute({ data: { name: 'John Doe' } })
  * ```
  */
-declare function useApiPut<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D>, "method">): UseApiReturn<T, D>;
+declare function useApiPut<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D, TSelected>, "method">): UseApiReturn<TSelected, D>;
 /**
  * Helper for PATCH requests
  *
@@ -295,7 +386,7 @@ declare function useApiPut<T = unknown, D = unknown>(url: MaybeRefOrGetter<strin
  * await execute({ data: { name: 'John' } })
  * ```
  */
-declare function useApiPatch<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D>, "method">): UseApiReturn<T, D>;
+declare function useApiPatch<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D, TSelected>, "method">): UseApiReturn<TSelected, D>;
 /**
  * Helper for DELETE requests
  *
@@ -305,7 +396,7 @@ declare function useApiPatch<T = unknown, D = unknown>(url: MaybeRefOrGetter<str
  * await execute()
  * ```
  */
-declare function useApiDelete<T = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T>, "method">): UseApiReturn<T>;
+declare function useApiDelete<T = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, unknown, TSelected>, "method">): UseApiReturn<TSelected>;
 
 /**
  * Execute multiple API requests in parallel with full reactive state

package/dist/index.d.ts

@@ -37,18 +37,97 @@ interface ApiRequestConfig<D = unknown> extends Omit<AxiosRequestConfig<D>, "dat
      * Empty array = retry on any error (network errors included).
      */
     retryStatusCodes?: number[];
+    /**
+     * Include credentials (cookies, Authorization headers) in cross-origin requests.
+     *
+     * Supports three auth strategies:
+     *
+     * **1. Bearer token (default)** — tokens in localStorage, no cookies needed:
+     * ```ts
+     * createApiClient({ baseURL: '/api' }) // withCredentials: false by default
+     * ```
+     *
+     * **2. Full cookie-based auth** — server sets httpOnly cookies for both tokens:
+     * ```ts
+     * createApiClient({ baseURL: '/api', withCredentials: true })
+     * ```
+     *
+     * **3. Hybrid** — Bearer access token + httpOnly refresh cookie:
+     * ```ts
+     * createApiClient({
+     *   baseURL: '/api',
+     *   authOptions: { refreshWithCredentials: true } // cookies only on /auth/refresh
+     * })
+     * ```
+     *
+     * **Per-request override** — override the global setting for a specific request:
+     * ```ts
+     * // Global: withCredentials: false, but this endpoint needs cookies
+     * const { data } = useApi('/user/profile', { withCredentials: true })
+     *
+     * // Global: withCredentials: true, but skip cookies for public CDN
+     * const { data } = useApi('https://cdn.example.com/config.json', {
+     *   withCredentials: false,
+     *   immediate: true
+     * })
+     * ```
+     */
+    withCredentials?: boolean;
 }
-interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
+interface UseApiOptions<T = unknown, D = unknown, TSelected = T> extends ApiRequestConfig<D> {
     immediate?: boolean;
     onSuccess?: (response: AxiosResponse<T>) => void;
     onError?: (error: ApiError) => void;
     onBefore?: () => void;
     onFinish?: () => void;
-    initialData?: T;
+    /**
+     * Transform the raw response data before it is stored in `data`.
+     * Applied on every successful response — including polling, SWR revalidation,
+     * and watch-triggered re-fetches. The cache always stores the raw server data;
+     * `select` is re-applied each time data is read from cache.
+     *
+     * The second generic parameter of `useApi` becomes the output type of `select`.
+     *
+     * @example
+     * ```ts
+     * // Extract nested field
+     * const { data } = useApi<ApiResponse, User[]>('/users', {
+     *   select: (res) => res.data,
+     * })
+     *
+     * // Transform items
+     * const { data } = useApi<RawUser[], User[]>('/users', {
+     *   select: (users) => users.map(u => ({ ...u, fullName: `${u.first} ${u.last}` })),
+     * })
+     * ```
+     */
+    select?: (data: T) => TSelected;
+    initialData?: TSelected;
     debounce?: number;
     useGlobalAbort?: boolean;
     initialLoading?: boolean;
     watch?: WatchSource | WatchSource[];
+    /**
+     * Return cached data immediately and revalidate in the background.
+     *
+     * Requires the `cache` option to be set. On a cache hit the cached value
+     * is returned right away (no loading state, no spinner) while a fresh
+     * request runs silently. The `revalidating` ref is `true` during the
+     * background fetch so you can show a subtle indicator if needed.
+     *
+     * On a cache miss the request behaves normally (loading: true).
+     *
+     * @example
+     * ```ts
+     * const { data, revalidating } = useApi('/users', {
+     *   cache: 'users',
+     *   staleWhileRevalidate: true,
+     *   immediate: true,
+     * })
+     * // Template: <span v-if="revalidating">↻</span>
+     * ```
+     */
+    staleWhileRevalidate?: boolean;
     /**
      * Polling configuration.
      * - Pass a **number** (ms) for simple polling.
@@ -81,7 +160,13 @@ interface UseApiReturn<T = unknown, D = unknown> {
     loading: Ref<boolean>;
     error: Ref<ApiError | null>;
     statusCode: Ref<number | null>;
-    response: Ref<AxiosResponse<T> | null>;
+    response: Ref<AxiosResponse<unknown> | null>;
+    /**
+     * `true` while a background revalidation request is in-flight.
+     * Only active when `staleWhileRevalidate: true` and a cache hit occurred.
+     * Use it to show a subtle refresh indicator without blocking the UI.
+     */
+    revalidating: Ref<boolean>;
     execute: (config?: ApiRequestConfig<D>) => Promise<T | null | undefined>;
     abort: (message?: string) => void;
     reset: () => void;
@@ -254,7 +339,8 @@ declare function createApi(options: ApiPluginOptions): {
 };
 declare function useApiConfig(): ApiPluginOptions;
 
-declare function useApi<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: UseApiOptions<T, D>): UseApiReturn<T, D>;
+declare function useApi<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: UseApiOptions<T, D, TSelected>): UseApiReturn<TSelected, D>;
+
 /**
  * Helper for GET requests
  *
@@ -263,9 +349,14 @@ declare function useApi<T = unknown, D = unknown>(url: MaybeRefOrGetter<string |
  * const { data, loading, error } = useApiGet<User[]>('/users', {
  *   immediate: true
  * })
+ *
+ * // With select:
+ * const { data } = useApiGet<ApiResponse, User[]>('/users', {
+ *   select: (res) => res.data,
+ * })
  * ```
  */
-declare function useApiGet<T = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T>, "method">): UseApiReturn<T>;
+declare function useApiGet<T = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, unknown, TSelected>, "method">): UseApiReturn<TSelected>;
 /**
  * Helper for POST requests
  *
@@ -275,7 +366,7 @@ declare function useApiGet<T = unknown>(url: MaybeRefOrGetter<string | undefined
  * await execute({ data: { name: 'John' } })
  * ```
  */
-declare function useApiPost<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D>, "method">): UseApiReturn<T, D>;
+declare function useApiPost<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D, TSelected>, "method">): UseApiReturn<TSelected, D>;
 /**
  * Helper for PUT requests
  *
@@ -285,7 +376,7 @@ declare function useApiPost<T = unknown, D = unknown>(url: MaybeRefOrGetter<stri
  * await execute({ data: { name: 'John Doe' } })
  * ```
  */
-declare function useApiPut<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D>, "method">): UseApiReturn<T, D>;
+declare function useApiPut<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D, TSelected>, "method">): UseApiReturn<TSelected, D>;
 /**
  * Helper for PATCH requests
  *
@@ -295,7 +386,7 @@ declare function useApiPut<T = unknown, D = unknown>(url: MaybeRefOrGetter<strin
  * await execute({ data: { name: 'John' } })
  * ```
  */
-declare function useApiPatch<T = unknown, D = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D>, "method">): UseApiReturn<T, D>;
+declare function useApiPatch<T = unknown, D = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, D, TSelected>, "method">): UseApiReturn<TSelected, D>;
 /**
  * Helper for DELETE requests
  *
@@ -305,7 +396,7 @@ declare function useApiPatch<T = unknown, D = unknown>(url: MaybeRefOrGetter<str
  * await execute()
  * ```
  */
-declare function useApiDelete<T = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T>, "method">): UseApiReturn<T>;
+declare function useApiDelete<T = unknown, TSelected = T>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T, unknown, TSelected>, "method">): UseApiReturn<TSelected>;
 
 /**
  * Execute multiple API requests in parallel with full reactive state

package/dist/index.mjs

@@ -232,11 +232,20 @@ function useApi(url, options = {}) {
     useGlobalAbort = globalOptions?.useGlobalAbort ?? true,
     initialLoading = false,
     poll = 0,
+    // Explicitly excluded from axiosConfig — these are useApi-only options
+    // and must not be forwarded to axios.request()
+    cache: _cache,
+    invalidateCache: _invalidateCache,
+    watch: _watch,
+    staleWhileRevalidate = false,
+    select,
     ...axiosConfig
   } = options;
   const maxRetries = retry === false ? 0 : retry === true ? 3 : retry;
+  const applySelect = (raw) => select ? select(raw) : raw;
   const startLoading = initialLoading ?? immediate;
   const state = useApiState(initialData, { initialLoading: startLoading });
+  const revalidating = ref3(false);
   const abortController2 = ref3(null);
   const globalAbort = useGlobalAbort ? useAbortController() : null;
   let pollTimer = null;
@@ -253,11 +262,16 @@ function useApi(url, options = {}) {
   };
   const executeRequest = async (config) => {
     const cacheOpts = normalizeCacheOptions(options.cache);
+    let isRevalidating = false;
     if (cacheOpts) {
       const cached = readCache(cacheOpts.id);
       if (cached !== null) {
-        state.mutate(cached);
-        return cached;
+        state.mutate(applySelect(cached));
+        if (!staleWhileRevalidate) {
+          return applySelect(cached);
+        }
+        isRevalidating = true;
+        revalidating.value = true;
       }
     }
     if (pollTimer) clearTimeout(pollTimer);
@@ -271,15 +285,16 @@ function useApi(url, options = {}) {
       const gs = globalAbort.getSignal();
       if (!gs.aborted) {
         subscribedSignal = gs;
-        const currentCount = globalAbort.abortCount.value;
         globalAbortHandler = () => {
-          if (globalAbort.abortCount.value === currentCount) controller.abort("Global filter change");
+          controller.abort("Cancelled by global abort");
         };
         gs.addEventListener("abort", globalAbortHandler);
       }
     }
-    onBefore?.();
-    state.setLoading(true);
+    if (!isRevalidating) {
+      onBefore?.();
+      state.setLoading(true);
+    }
     state.setError(null);
     let wasCancelled = false;
     let retryCount = 0;
@@ -303,7 +318,8 @@ function useApi(url, options = {}) {
             signal: controller.signal,
             ...{ authMode: config?.authMode || authMode }
           });
-          state.mutate(response.data, response);
+          const selected = applySelect(response.data);
+          state.mutate(selected, response);
           state.setStatusCode(response.status);
           if (cacheOpts) {
             writeCache(cacheOpts.id, response.data, cacheOpts.staleTime);
@@ -312,7 +328,7 @@ function useApi(url, options = {}) {
             invalidateCache(options.invalidateCache);
           }
           onSuccess?.(response);
-          return response.data;
+          return selected;
         } catch (err) {
           if (controller.signal.aborted || isAxiosError2(err) && err.code === "ERR_CANCELED") {
             wasCancelled = true;
@@ -354,8 +370,9 @@ function useApi(url, options = {}) {
       return null;
     } finally {
       if (globalAbortHandler && subscribedSignal) subscribedSignal.removeEventListener("abort", globalAbortHandler);
+      revalidating.value = false;
       if (!wasCancelled) {
-        state.setLoading(false);
+        if (!isRevalidating) state.setLoading(false);
         onFinish?.();
         const { interval, whenHidden } = getPollConfig();
         if (interval > 0) {
@@ -439,8 +456,10 @@ function useApi(url, options = {}) {
       }
     }, { deep: true });
   }
-  return { ...state, execute, abort, reset, ignoreUpdates };
+  return { ...state, revalidating, execute, abort, reset, ignoreUpdates };
 }
+
+// src/useApi.helpers.ts
 function useApiGet(url, options) {
   return useApi(url, { ...options, method: "GET" });
 }

package/package.json

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