@ametie/vue-muza-use 0.9.1 → 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
@@ -23,11 +31,14 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 - 🧹 **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
 
 ---
 
@@ -42,11 +53,13 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 - [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)
@@ -679,6 +692,70 @@ 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: '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.**
@@ -948,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
@@ -1352,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
@@ -1660,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). |
 
 ---
 
@@ -1697,6 +1881,7 @@ function useMyCustomComposable<T>(fetchFn: () => Promise<T>) {
 |--------|------|---------|-------------|
 | `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:**
 
@@ -1712,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:**
@@ -1734,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 |
@@ -1746,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 |

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.1",
+  "version": "0.10.0",
   "description": "Powerful Vue 3 API composable (Muza Kit) with Axios, Auto-Refresh & TypeScript",
   "author": "MortyQ",
   "license": "MIT",