@ametie/vue-muza-use 0.5.0 → 0.6.1

package/README.md

@@ -19,6 +19,7 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 - ⏱️ **Built-in Debouncing** — Perfect for search inputs and auto-save forms
 - 🛡️ **Race Condition Protection** — Global abort controller cancels stale requests automatically
 - 📊 **Auto-Polling** — Built-in interval fetching with smart tab visibility detection
+- 🚀 **Batch Requests** — Execute multiple requests in parallel with progress tracking
 - 🧹 **Zero Memory Leaks** — Automatic cleanup of pending requests on component unmount
 
 **Advanced Features** (When you need them):
@@ -45,6 +46,7 @@ A production-ready composable that eliminates boilerplate and solves the hard pr
 **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)
@@ -376,9 +378,9 @@ 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`).
+Use `mutate` to manually update the data ref. Supports direct values or updater functions (like React's `setState`).
 
-> 🎓 **When to use `setData`:**  
+> 🎓 **When to use `mutate`:**  
 > ✅ Adding/removing/updating items in arrays  
 > ✅ Local sorting/filtering (without refetching)  
 > ✅ Transform data in `onSuccess` (adding computed fields)
@@ -390,21 +392,21 @@ Use `setData` to manually update the data ref. Supports direct values or updater
 
 #### Add/Remove/Update Items
 ```typescript
-const { data, setData } = useApi<Todo[]>('/todos', { immediate: true })
+const { data, mutate } = useApi<Todo[]>('/todos', { immediate: true })
 
 // Add item
 const addTodo = (newTodo: Todo) => {
-  setData(prev => prev ? [...prev, newTodo] : [newTodo])
+  mutate(prev => prev ? [...prev, newTodo] : [newTodo])
 }
 
 // Remove item
 const removeTodo = (id: number) => {
-  setData(prev => prev?.filter(t => t.id !== id) ?? null)
+  mutate(prev => prev?.filter(t => t.id !== id) ?? null)
 }
 
 // Update item
 const updateTodo = (id: number, updates: Partial<Todo>) => {
-  setData(prev => 
+  mutate(prev => 
     prev?.map(t => t.id === id ? { ...t, ...updates } : t) ?? null
   )
 }
@@ -412,14 +414,14 @@ const updateTodo = (id: number, updates: Partial<Todo>) => {
 
 #### Sort/Filter Locally
 ```typescript
-const { data, setData } = useApi<Product[]>('/products', { immediate: true })
+const { data, mutate } = useApi<Product[]>('/products', { immediate: true })
 
 const sortByPrice = () => {
-  setData(prev => prev ? [...prev].sort((a, b) => a.price - b.price) : null)
+  mutate(prev => prev ? [...prev].sort((a, b) => a.price - b.price) : null)
 }
 
 const filterActive = () => {
-  setData(prev => prev?.filter(p => p.active) ?? null)
+  mutate(prev => prev?.filter(p => p.active) ?? null)
 }
 
 // Reset to original
@@ -428,7 +430,7 @@ const resetFilters = () => execute()
 
 #### Transform in `onSuccess`
 
-Use `setData` in `onSuccess` to transform data right after fetching. Two approaches:
+Use `mutate` in `onSuccess` to transform data right after fetching. Two approaches:
 
 **Approach 1: Same type (recommended)**
 ```typescript
@@ -439,11 +441,11 @@ interface User {
   fullName?: string  // Optional field
 }
 
-const { data, setData } = useApi<User[]>('/users', {
+const { data, mutate } = useApi<User[]>('/users', {
   immediate: true,
   onSuccess: ({ data: users }) => {
     // Add computed field - still User[] type
-    setData(users.map(u => ({
+    mutate(users.map(u => ({
       ...u,
       fullName: `${u.firstName} ${u.lastName}`
     })))
@@ -471,7 +473,7 @@ const users = computed(() =>
 ```
 
 > 💡 **Rule of thumb:**  
-> - ✅ **Use `setData` in `onSuccess`** if you're adding/modifying fields but keeping the same base type  
+> - ✅ **Use `mutate` 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)
 
 ---
@@ -541,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
@@ -874,7 +1089,7 @@ The main composable for making HTTP requests.
   
   // Methods
   execute: (config?: AxiosRequestConfig) => Promise<T | null>
-  setData: (data: T | null | ((prev: T | null) => T | null)) => void
+  mutate: (data: T | null | ((prev: T | null) => T | null)) => void
   abort: (reason?: string) => void
   reset: () => void
 }
@@ -893,23 +1108,23 @@ await execute()
 await execute({ params: { page: 2 } })
 ```
 
-#### `setData(newData)`
+#### `mutate(newData)`
 Manually update the `data` ref. Supports direct values or updater functions:
 
 ```typescript
-const { data, setData } = useApi<User[]>('/users')
+const { data, mutate } = useApi<User[]>('/users')
 
 // Direct value
-setData([{ id: 1, name: 'John' }])
+mutate([{ id: 1, name: 'John' }])
 
 // Updater function (like React's setState)
-setData(prev => prev ? [...prev, newUser] : [newUser])
+mutate(prev => prev ? [...prev, newUser] : [newUser])
 
 // Remove item
-setData(prev => prev?.filter(u => u.id !== userId) ?? null)
+mutate(prev => prev?.filter(u => u.id !== userId) ?? null)
 ```
 
-> **Note:** `setData` automatically clears any existing error.
+> **Note:** `mutate` automatically clears any existing error.
 
 #### `abort(reason?)`
 Cancel the current request:
@@ -1051,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.