@ametie/vue-muza-use 0.8.0 → 0.9.1

package/README.md

@@ -22,6 +22,7 @@ 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
 
 **Advanced Features** (When you need them):
 - ♻️ **Intelligent Retries** — Lifecycle-aware retry logic with configurable status codes
@@ -40,6 +41,7 @@ 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)
 - [Polling (Background Updates)](#polling-background-updates)
 - [Error Handling](#error-handling)
   - [retry — Automatic Request Retry](#retry--automatic-request-retry)
@@ -499,6 +501,184 @@ 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.
+
+---
+
 ### Polling (Background Updates)
 
 **TL;DR: Keep data fresh with smart polling that automatically pauses when the browser tab is hidden.**
@@ -1511,6 +1691,13 @@ 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 |
+
 **Polling:**
 
 | Option | Type | Default | Description |
@@ -1768,6 +1955,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

@@ -31,8 +31,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthEventType: () => AuthEventType,
+  clearAllCache: () => clearAllCache,
   createApi: () => createApi,
   createApiClient: () => createApiClient,
+  invalidateCache: () => invalidateCache,
   setAuthMonitor: () => setAuthMonitor,
   setupInterceptors: () => setupInterceptors,
   tokenManager: () => tokenManager,
@@ -212,8 +214,39 @@ function useAbortController() {
   };
 }
 
+// src/features/cacheManager.ts
+var DEFAULT_STALE_TIME = 3e5;
+var cacheStore = /* @__PURE__ */ new Map();
+function readCache(id) {
+  const entry = cacheStore.get(id);
+  if (!entry) return null;
+  const isValid = Date.now() - entry.cachedAt < entry.staleTime;
+  if (!isValid) {
+    cacheStore.delete(id);
+    return null;
+  }
+  return entry.data;
+}
+function writeCache(id, data, staleTime) {
+  cacheStore.set(id, { data, cachedAt: Date.now(), staleTime });
+}
+function invalidateCache(id) {
+  const ids = Array.isArray(id) ? id : [id];
+  ids.forEach((key) => cacheStore.delete(key));
+}
+function clearAllCache() {
+  cacheStore.clear();
+}
+
 // src/useApi.ts
 var DEFAULT_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+function normalizeCacheOptions(cache) {
+  if (!cache) return null;
+  if (typeof cache === "string") {
+    return { id: cache, staleTime: DEFAULT_STALE_TIME };
+  }
+  return { id: cache.id, staleTime: cache.staleTime ?? DEFAULT_STALE_TIME };
+}
 function cancellableSleep(ms, signal) {
   return new Promise((resolve) => {
     if (signal.aborted) {
@@ -272,6 +305,14 @@ function useApi(url, options = {}) {
     return { interval: 0, whenHidden: false };
   };
   const executeRequest = async (config) => {
+    const cacheOpts = normalizeCacheOptions(options.cache);
+    if (cacheOpts) {
+      const cached = readCache(cacheOpts.id);
+      if (cached !== null) {
+        state.mutate(cached);
+        return cached;
+      }
+    }
     if (pollTimer) clearTimeout(pollTimer);
     const requestUrl = (0, import_vue4.toValue)(url);
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
@@ -317,6 +358,12 @@ function useApi(url, options = {}) {
           });
           state.mutate(response.data, response);
           state.setStatusCode(response.status);
+          if (cacheOpts) {
+            writeCache(cacheOpts.id, response.data, cacheOpts.staleTime);
+          }
+          if (options.invalidateCache) {
+            invalidateCache(options.invalidateCache);
+          }
           onSuccess?.(response);
           return response.data;
         } catch (err) {
@@ -1015,8 +1062,10 @@ function createApiClient(options = {}) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthEventType,
+  clearAllCache,
   createApi,
   createApiClient,
+  invalidateCache,
   setAuthMonitor,
   setupInterceptors,
   tokenManager,

package/dist/index.d.cts

@@ -10,6 +10,14 @@ interface ApiError {
     details?: unknown;
 }
 type AuthMode = "default" | "public" | "optional";
+interface CacheOptions {
+    id: string;
+    /**
+     * How long the cached entry is valid in milliseconds.
+     * Default: 300_000 (5 minutes)
+     */
+    staleTime?: number;
+}
 interface ApiState<T = unknown> {
     data: T | null;
     loading: boolean;
@@ -47,6 +55,22 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
      * - Pass an **object** `{ interval: number, whenHidden?: boolean }` for advanced control.
      * Properties inside the object can also be Refs.
      */
+    /**
+     * Cache the response data by a string id.
+     * - String shorthand: `cache: 'key'` uses DEFAULT_STALE_TIME (5 min)
+     * - Object form: `cache: { id: 'key', staleTime: 10_000 }` for custom TTL
+     *
+     * On cache hit: mutate() is called with cached data, loading stays false,
+     * onBefore/onSuccess/onFinish are NOT called, axios request is NOT made.
+     * Cache is written only on HTTP 2xx success.
+     */
+    cache?: string | CacheOptions;
+    /**
+     * Invalidate one or more cache entries on HTTP 2xx success.
+     * Fires only after a confirmed successful response — never in catch/finally.
+     * Useful for POST/PUT/DELETE that should bust related GET caches.
+     */
+    invalidateCache?: string | string[];
     poll?: MaybeRefOrGetter<number | {
         interval: MaybeRefOrGetter<number>;
         whenHidden?: MaybeRefOrGetter<boolean>;
@@ -595,4 +619,13 @@ interface AuthEventPayload {
 type AuthMonitorFn = (type: AuthEventType, payload: AuthEventPayload) => void;
 declare function setAuthMonitor(fn: AuthMonitorFn): void;
 
-export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, createApi, createApiClient, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };
+/**
+ * Invalidate one or multiple cache entries by id.
+ */
+declare function invalidateCache(id: string | string[]): void;
+/**
+ * Clear all cache entries. Call on logout to prevent data leaks between users.
+ */
+declare function clearAllCache(): void;
+
+export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type CacheOptions, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, clearAllCache, createApi, createApiClient, invalidateCache, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };

package/dist/index.d.ts

@@ -10,6 +10,14 @@ interface ApiError {
     details?: unknown;
 }
 type AuthMode = "default" | "public" | "optional";
+interface CacheOptions {
+    id: string;
+    /**
+     * How long the cached entry is valid in milliseconds.
+     * Default: 300_000 (5 minutes)
+     */
+    staleTime?: number;
+}
 interface ApiState<T = unknown> {
     data: T | null;
     loading: boolean;
@@ -47,6 +55,22 @@ interface UseApiOptions<T = unknown, D = unknown> extends ApiRequestConfig<D> {
      * - Pass an **object** `{ interval: number, whenHidden?: boolean }` for advanced control.
      * Properties inside the object can also be Refs.
      */
+    /**
+     * Cache the response data by a string id.
+     * - String shorthand: `cache: 'key'` uses DEFAULT_STALE_TIME (5 min)
+     * - Object form: `cache: { id: 'key', staleTime: 10_000 }` for custom TTL
+     *
+     * On cache hit: mutate() is called with cached data, loading stays false,
+     * onBefore/onSuccess/onFinish are NOT called, axios request is NOT made.
+     * Cache is written only on HTTP 2xx success.
+     */
+    cache?: string | CacheOptions;
+    /**
+     * Invalidate one or more cache entries on HTTP 2xx success.
+     * Fires only after a confirmed successful response — never in catch/finally.
+     * Useful for POST/PUT/DELETE that should bust related GET caches.
+     */
+    invalidateCache?: string | string[];
     poll?: MaybeRefOrGetter<number | {
         interval: MaybeRefOrGetter<number>;
         whenHidden?: MaybeRefOrGetter<boolean>;
@@ -595,4 +619,13 @@ interface AuthEventPayload {
 type AuthMonitorFn = (type: AuthEventType, payload: AuthEventPayload) => void;
 declare function setAuthMonitor(fn: AuthMonitorFn): void;
 
-export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, createApi, createApiClient, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };
+/**
+ * Invalidate one or multiple cache entries by id.
+ */
+declare function invalidateCache(id: string | string[]): void;
+/**
+ * Clear all cache entries. Call on logout to prevent data leaks between users.
+ */
+declare function clearAllCache(): void;
+
+export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, type BatchRequestConfig, type BatchResultItem, type CacheOptions, type SetDataInput, type UseApiBatchOptions, type UseApiBatchReturn, type UseApiOptions, type UseApiReturn, clearAllCache, createApi, createApiClient, invalidateCache, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiBatch, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };

package/dist/index.mjs

@@ -161,8 +161,39 @@ function useAbortController() {
   };
 }
 
+// src/features/cacheManager.ts
+var DEFAULT_STALE_TIME = 3e5;
+var cacheStore = /* @__PURE__ */ new Map();
+function readCache(id) {
+  const entry = cacheStore.get(id);
+  if (!entry) return null;
+  const isValid = Date.now() - entry.cachedAt < entry.staleTime;
+  if (!isValid) {
+    cacheStore.delete(id);
+    return null;
+  }
+  return entry.data;
+}
+function writeCache(id, data, staleTime) {
+  cacheStore.set(id, { data, cachedAt: Date.now(), staleTime });
+}
+function invalidateCache(id) {
+  const ids = Array.isArray(id) ? id : [id];
+  ids.forEach((key) => cacheStore.delete(key));
+}
+function clearAllCache() {
+  cacheStore.clear();
+}
+
 // src/useApi.ts
 var DEFAULT_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+function normalizeCacheOptions(cache) {
+  if (!cache) return null;
+  if (typeof cache === "string") {
+    return { id: cache, staleTime: DEFAULT_STALE_TIME };
+  }
+  return { id: cache.id, staleTime: cache.staleTime ?? DEFAULT_STALE_TIME };
+}
 function cancellableSleep(ms, signal) {
   return new Promise((resolve) => {
     if (signal.aborted) {
@@ -221,6 +252,14 @@ function useApi(url, options = {}) {
     return { interval: 0, whenHidden: false };
   };
   const executeRequest = async (config) => {
+    const cacheOpts = normalizeCacheOptions(options.cache);
+    if (cacheOpts) {
+      const cached = readCache(cacheOpts.id);
+      if (cached !== null) {
+        state.mutate(cached);
+        return cached;
+      }
+    }
     if (pollTimer) clearTimeout(pollTimer);
     const requestUrl = toValue(url);
     if (abortController2.value) abortController2.value.abort("Cancelled by new request");
@@ -266,6 +305,12 @@ function useApi(url, options = {}) {
           });
           state.mutate(response.data, response);
           state.setStatusCode(response.status);
+          if (cacheOpts) {
+            writeCache(cacheOpts.id, response.data, cacheOpts.staleTime);
+          }
+          if (options.invalidateCache) {
+            invalidateCache(options.invalidateCache);
+          }
           onSuccess?.(response);
           return response.data;
         } catch (err) {
@@ -963,8 +1008,10 @@ function createApiClient(options = {}) {
 }
 export {
   AuthEventType,
+  clearAllCache,
   createApi,
   createApiClient,
+  invalidateCache,
   setAuthMonitor,
   setupInterceptors,
   tokenManager,

package/package.json

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