@ametie/vue-muza-use 0.4.10 → 0.6.0

package/README.md

@@ -13,18 +13,50 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 
 ## ✨ Features
 
+**Core Features** (Get started in minutes):
 - 🎯 **Fully Type-Safe** — End-to-end TypeScript support with strict typing for requests and responses
 - 🔄 **Smart Reactivity** — Watch refs and automatically refetch when dependencies change
 - ⏱️ **Built-in Debouncing** — Perfect for search inputs and auto-save forms
 - 🛡️ **Race Condition Protection** — Global abort controller cancels stale requests automatically
-- 🔐 **JWT Token Management** — Automatic token refresh with request queueing on 401 responses
-- ♻️ **Intelligent Retries** — Lifecycle-aware retry logic that respects component unmounting
 - 📊 **Auto-Polling** — Built-in interval fetching with smart tab visibility detection
+- 🚀 **Batch Requests** — Execute multiple requests in parallel with progress tracking
 - 🧹 **Zero Memory Leaks** — Automatic cleanup of pending requests on component unmount
+
+**Advanced Features** (When you need them):
+- ♻️ **Intelligent Retries** — Lifecycle-aware retry logic that respects component unmounting
+- 🔐 **JWT Token Management** — Automatic token refresh with request queueing on 401 responses
 - 🎛️ **Flexible Architecture** — Bring your own Axios instance with full configuration control
 
 ---
 
+## 📖 Table of Contents
+
+**Getting Started:**
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Basic Usage](#-basic-usage)
+
+**Core Features:**
+- [Watch & Auto-Refetch](#watch--auto-refetch)
+- [Polling](#polling-background-updates)
+- [Error Handling](#error-handling)
+- [Loading States](#loading-states)
+- [Manual Data Updates](#manual-data-updates)
+
+**Real-World Examples:**
+- [Data Table with Pagination](#data-table-with-pagination--sorting)
+- [Request Cancellation](#request-cancellation)
+- [Batch Requests](#batch-requests)
+
+**Advanced:**
+- [Custom Axios Instance](#-advanced-configuration)
+- [Authentication & Tokens](#-authentication--token-management) *(Optional)*
+- [API Reference](#-api-reference)
+
+> 💡 **New to the library?** Start with [Quick Start](#-quick-start), then explore [Basic Usage](#-basic-usage). Skip authentication until you need it!
+
+---
+
 ## 📦 Installation
 
 ```bash
@@ -344,6 +376,108 @@ const { execute } = useApi('/analytics', {
 
 ---
 
+### Manual Data Updates
+
+Use `setData` to manually update the data ref. Supports direct values or updater functions (like React's `setState`).
+
+> 🎓 **When to use `setData`:**  
+> ✅ Adding/removing/updating items in arrays  
+> ✅ Local sorting/filtering (without refetching)  
+> ✅ Transform data in `onSuccess` (adding computed fields)
+> 
+> **When to use `computed` instead:**  
+> ✅ Completely changing data structure (e.g., API format → App format)  
+> ✅ Extracting nested data that changes the return type  
+> ✅ Complex transformations that depend on other refs
+
+#### Add/Remove/Update Items
+```typescript
+const { data, setData } = useApi<Todo[]>('/todos', { immediate: true })
+
+// Add item
+const addTodo = (newTodo: Todo) => {
+  setData(prev => prev ? [...prev, newTodo] : [newTodo])
+}
+
+// Remove item
+const removeTodo = (id: number) => {
+  setData(prev => prev?.filter(t => t.id !== id) ?? null)
+}
+
+// Update item
+const updateTodo = (id: number, updates: Partial<Todo>) => {
+  setData(prev => 
+    prev?.map(t => t.id === id ? { ...t, ...updates } : t) ?? null
+  )
+}
+```
+
+#### Sort/Filter Locally
+```typescript
+const { data, setData } = useApi<Product[]>('/products', { immediate: true })
+
+const sortByPrice = () => {
+  setData(prev => prev ? [...prev].sort((a, b) => a.price - b.price) : null)
+}
+
+const filterActive = () => {
+  setData(prev => prev?.filter(p => p.active) ?? null)
+}
+
+// Reset to original
+const resetFilters = () => execute()
+```
+
+#### Transform in `onSuccess`
+
+Use `setData` in `onSuccess` to transform data right after fetching. Two approaches:
+
+**Approach 1: Same type (recommended)**
+```typescript
+interface User {
+  id: number
+  firstName: string
+  lastName: string
+  fullName?: string  // Optional field
+}
+
+const { data, setData } = useApi<User[]>('/users', {
+  immediate: true,
+  onSuccess: ({ data: users }) => {
+    // Add computed field - still User[] type
+    setData(users.map(u => ({
+      ...u,
+      fullName: `${u.firstName} ${u.lastName}`
+    })))
+  }
+})
+```
+
+**Approach 2: Different structure (use separate computed)**
+```typescript
+interface ApiUser {
+  first_name: string
+  last_name: string
+}
+
+// If API returns different structure, use computed for transformation
+const { data: rawData } = useApi<ApiUser[]>('/users', { immediate: true })
+
+const users = computed(() => 
+  rawData.value?.map(u => ({
+    firstName: u.first_name,
+    lastName: u.last_name,
+    fullName: `${u.first_name} ${u.last_name}`
+  })) ?? []
+)
+```
+
+> 💡 **Rule of thumb:**  
+> - ✅ **Use `setData` in `onSuccess`** if you're adding/modifying fields but keeping the same base type  
+> - ✅ **Use `computed`** if you're completely changing the data structure (e.g., snake_case → camelCase)
+
+---
+
 ## 📊 Real-World Examples
 
 ### Data Table with Pagination & Sorting
@@ -389,21 +523,6 @@ const { data, loading } = useApi('/orders', {
 </template>
 ```
 
-### Optimistic UI Updates
-```typescript
-const { execute: updateProfile } = useApi('/user/profile', {
-  method: 'PUT',
-  onBefore: () => {
-    // Show update immediately
-    localProfile.value = { ...localProfile.value, ...changes }
-  },
-  onError: () => {
-    // Rollback on error
-    localProfile.value = originalProfile
-    toast.error('Update failed')
-  }
-})
-```
 
 ### Request Cancellation
 ```typescript
@@ -424,6 +543,219 @@ const resetFilters = () => {
 
 ---
 
+### Batch Requests
+
+Execute multiple API requests in parallel with full reactive state, progress tracking, and error tolerance.
+
+#### Basic Usage
+
+```typescript
+import { useApiBatch } from '@ametie/vue-muza-use'
+
+interface User {
+  id: number
+  name: string
+}
+
+const { 
+  successfulData,  // Ref<User[]> - only successful results
+  loading,         // Ref<boolean>
+  progress,        // Ref<{ completed, total, percentage, succeeded, failed }>
+  execute 
+} = useApiBatch<User>([
+  '/users/1',
+  '/users/2',
+  '/users/3'
+])
+
+await execute()
+console.log(successfulData.value)  // [User, User, User]
+console.log(progress.value)        // { completed: 3, total: 3, percentage: 100, succeeded: 3, failed: 0 }
+```
+
+#### Error Tolerance (Default)
+
+By default, `useApiBatch` uses `settled: true` — failed requests don't stop the batch:
+
+```typescript
+const { 
+  successfulData, 
+  errors,    // Ref<ApiError[]> - all errors
+  progress,
+  execute 
+} = useApiBatch<User>([
+  '/users/1',
+  '/users/999',  // Will fail (404)
+  '/users/3'
+])
+
+await execute()
+
+console.log(successfulData.value.length)  // 2 (successful)
+console.log(errors.value.length)          // 1 (failed)
+console.log(progress.value)               // { succeeded: 2, failed: 1, ... }
+```
+
+#### Strict Mode
+
+Fail immediately on first error:
+
+```typescript
+const { execute } = useApiBatch<User>(urls, { 
+  settled: false  // First error will reject the entire batch
+})
+
+try {
+  await execute()
+} catch (error) {
+  console.log('Batch failed:', error.message)
+}
+```
+
+#### With Progress Tracking
+
+Perfect for loading indicators and progress bars:
+
+```vue
+<script setup lang="ts">
+const { loading, progress, execute } = useApiBatch<User>(urls, {
+  onProgress: (p) => {
+    console.log(`${p.percentage}% complete (${p.succeeded} ok, ${p.failed} failed)`)
+  }
+})
+</script>
+
+<template>
+  <div v-if="loading">
+    <div class="progress-bar">
+      <div :style="{ width: progress.percentage + '%' }"></div>
+    </div>
+    <span>{{ progress.completed }} / {{ progress.total }}</span>
+  </div>
+</template>
+```
+
+#### Concurrency Limit
+
+Control how many requests run in parallel (useful for rate limiting):
+
+```typescript
+// Only 3 requests at a time
+const { execute } = useApiBatch<User>(hundredUrls, {
+  concurrency: 3
+})
+```
+
+#### Reactive URLs
+
+URLs can be reactive — use refs or computed:
+
+```typescript
+const userIds = ref([1, 2, 3])
+const urls = computed(() => userIds.value.map(id => `/users/${id}`))
+
+const { successfulData, execute } = useApiBatch<User>(urls, {
+  immediate: true  // Execute on mount
+})
+
+// When userIds changes, call execute() to refetch
+watch(userIds, () => execute())
+```
+
+#### Auto Re-Execute with Watch
+
+```typescript
+const filters = ref({ status: 'active' })
+
+const { data } = useApiBatch<User>(urls, {
+  watch: filters,     // Re-execute when filters change
+  immediate: true
+})
+```
+
+#### Item-Level Callbacks
+
+```typescript
+const { execute } = useApiBatch<User>(urls, {
+  onItemSuccess: (item, index) => {
+    console.log(`✅ [${index}] Loaded: ${item.url}`)
+  },
+  onItemError: (item, index) => {
+    console.log(`❌ [${index}] Failed: ${item.url}`, item.error?.message)
+  },
+  onFinish: (results) => {
+    console.log(`Batch complete: ${results.length} items processed`)
+  }
+})
+```
+
+#### Full Return Type
+
+```typescript
+const {
+  data,            // Ref<BatchResultItem<T>[]> - all results with metadata
+  successfulData,  // Ref<T[]> - only successful data (computed)
+  loading,         // Ref<boolean>
+  error,           // Ref<ApiError | null> - set if ALL requests failed
+  errors,          // Ref<ApiError[]> - all individual errors
+  progress,        // Ref<BatchProgress>
+  execute,         // () => Promise<BatchResultItem<T>[]>
+  abort,           // (message?: string) => void
+  reset            // () => void
+} = useApiBatch<User>(urls)
+```
+
+#### BatchResultItem Structure
+
+Each item in `data` contains:
+
+```typescript
+interface BatchResultItem<T> {
+  url: string           // The requested URL
+  index: number         // Position in original array
+  success: boolean      // Whether request succeeded
+  data: T | null        // Response data (null if failed)
+  error: ApiError | null // Error details (null if succeeded)
+  statusCode: number | null
+}
+```
+
+#### Real-World Example: Dashboard Loader
+
+```vue
+<script setup lang="ts">
+const dashboardUrls = [
+  '/api/stats',
+  '/api/recent-orders',
+  '/api/notifications',
+  '/api/user-activity'
+]
+
+const { 
+  data: results, 
+  loading, 
+  progress,
+  execute 
+} = useApiBatch(dashboardUrls, {
+  immediate: true,
+  onProgress: (p) => console.log(`Dashboard loading: ${p.percentage}%`)
+})
+
+// Extract individual data
+const stats = computed(() => results.value.find(r => r.url.includes('stats'))?.data)
+const orders = computed(() => results.value.find(r => r.url.includes('orders'))?.data)
+</script>
+
+<template>
+  <div v-if="loading" class="loading">
+    Loading dashboard... {{ progress.percentage }}%
+  </div>
+  <Dashboard v-else :stats="stats" :orders="orders" />
+</template>
+```
+
+---
+
 ## ⚙️ Advanced Configuration
 
 ### Custom Axios Instance
@@ -752,11 +1084,14 @@ The main composable for making HTTP requests.
   data: Ref<T | null>              // Response data
   loading: Ref<boolean>            // Loading state
   error: Ref<ApiError | null>      // Error object
+  statusCode: Ref<number | null>   // HTTP status code
   response: Ref<AxiosResponse<T>>  // Full Axios response
   
   // Methods
   execute: (config?: AxiosRequestConfig) => Promise<T | null>
+  setData: (data: T | null | ((prev: T | null) => T | null)) => void
   abort: (reason?: string) => void
+  reset: () => void
 }
 ```
 
@@ -773,6 +1108,24 @@ await execute()
 await execute({ params: { page: 2 } })
 ```
 
+#### `setData(newData)`
+Manually update the `data` ref. Supports direct values or updater functions:
+
+```typescript
+const { data, setData } = useApi<User[]>('/users')
+
+// Direct value
+setData([{ id: 1, name: 'John' }])
+
+// Updater function (like React's setState)
+setData(prev => prev ? [...prev, newUser] : [newUser])
+
+// Remove item
+setData(prev => prev?.filter(u => u.id !== userId) ?? null)
+```
+
+> **Note:** `setData` automatically clears any existing error.
+
 #### `abort(reason?)`
 Cancel the current request:
 
@@ -785,6 +1138,20 @@ execute()
 setTimeout(() => abort('Timeout'), 5000)
 ```
 
+#### `reset()`
+Reset all state to initial values:
+
+```typescript
+const { data, error, loading, reset } = useApi('/users')
+
+// Clear everything
+reset()
+// data.value = null, error.value = null, loading.value = false
+
+// Cancel after 5 seconds
+setTimeout(() => abort('Timeout'), 5000)
+```
+
 ---
 
 ### `createApiClient(options)`
@@ -899,6 +1266,89 @@ app.use(createApi({
 
 ---
 
+### `useApiBatch<T>(urls, options)`
+
+Execute multiple API requests in parallel with full reactive state.
+
+**Type Parameters:**
+- `T` — Response data type for each request
+
+**Arguments:**
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `urls` | `MaybeRefOrGetter<string[]>` | Array of API endpoints. Can be static array, ref, or getter. |
+| `options` | `UseApiBatchOptions<T>` | Configuration object (see below). |
+
+---
+
+#### Batch Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `settled` | `boolean` | `true` | If `true`, failed requests don't stop the batch. If `false`, first error rejects entire batch. |
+| `concurrency` | `number` | `undefined` | Max parallel requests. Default: unlimited. |
+| `immediate` | `boolean` | `false` | Auto-execute on mount. |
+| `skipErrorNotification` | `boolean` | `true` | Skip global error handler for individual failures. |
+| `watch` | `WatchSource \| WatchSource[]` | `undefined` | Re-execute when sources change. |
+
+**Callbacks:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onItemSuccess` | `(item: BatchResultItem<T>, index: number) => void` | Called when individual request succeeds. |
+| `onItemError` | `(item: BatchResultItem<T>, index: number) => void` | Called when individual request fails. |
+| `onProgress` | `(progress: BatchProgress) => void` | Called when progress updates. |
+| `onFinish` | `(results: BatchResultItem<T>[]) => void` | Called when all requests complete. |
+
+---
+
+#### Batch Return Values
+
+```typescript
+{
+  // State
+  data: Ref<BatchResultItem<T>[]>  // All results with metadata
+  successfulData: Ref<T[]>         // Only successful data (computed)
+  loading: Ref<boolean>            // True while any request pending
+  error: Ref<ApiError | null>      // Set if ALL requests failed
+  errors: Ref<ApiError[]>          // All individual errors
+  progress: Ref<BatchProgress>     // Progress tracking
+  
+  // Methods
+  execute: () => Promise<BatchResultItem<T>[]>
+  abort: (message?: string) => void
+  reset: () => void
+}
+```
+
+#### `BatchProgress`
+
+```typescript
+interface BatchProgress {
+  completed: number   // Requests finished (success + failed)
+  total: number       // Total requests
+  percentage: number  // 0-100
+  succeeded: number   // Successful requests
+  failed: number      // Failed requests
+}
+```
+
+#### `BatchResultItem<T>`
+
+```typescript
+interface BatchResultItem<T> {
+  url: string              // Requested URL
+  index: number            // Position in original array
+  success: boolean         // Whether succeeded
+  data: T | null           // Response data
+  error: ApiError | null   // Error if failed
+  statusCode: number | null
+}
+```
+
+---
+
 ### `useAbortController()`
 
 Access the global abort controller for cancelling multiple requests.