@ametie/vue-muza-use 0.5.0 → 0.6.0

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)
@@ -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
@@ -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.

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   tokenManager: () => tokenManager,
   useAbortController: () => useAbortController,
   useApi: () => useApi,
+  useApiBatch: () => useApiBatch,
   useApiConfig: () => useApiConfig,
   useApiDelete: () => useApiDelete,
   useApiGet: () => useApiGet,
@@ -380,6 +381,242 @@ function useApiDelete(url, options) {
   return useApi(url, { ...options, method: "DELETE" });
 }
 
+// src/useApiBatch.ts
+var import_vue5 = require("vue");
+function useApiBatch(urls, options = {}) {
+  const {
+    settled = true,
+    concurrency,
+    immediate = false,
+    skipErrorNotification = true,
+    watch: watchSource,
+    onItemSuccess,
+    onItemError,
+    onFinish,
+    onProgress,
+    ...apiOptions
+  } = options;
+  const getUrls = () => (0, import_vue5.toValue)(urls);
+  const data = (0, import_vue5.ref)([]);
+  const loading = (0, import_vue5.ref)(false);
+  const error = (0, import_vue5.ref)(null);
+  const errors = (0, import_vue5.ref)([]);
+  const progress = (0, import_vue5.ref)({
+    completed: 0,
+    total: 0,
+    percentage: 0,
+    succeeded: 0,
+    failed: 0
+  });
+  const successfulData = (0, import_vue5.computed)(
+    () => data.value.filter((item) => item.success && item.data !== null).map((item) => item.data)
+  );
+  const abortControllers = (0, import_vue5.ref)([]);
+  let isAborted = false;
+  const updateProgress = (succeeded, failed) => {
+    const currentUrls = getUrls();
+    const completed = succeeded + failed;
+    const newProgress = {
+      completed,
+      total: currentUrls.length,
+      percentage: currentUrls.length > 0 ? Math.round(completed / currentUrls.length * 100) : 0,
+      succeeded,
+      failed
+    };
+    progress.value = newProgress;
+    onProgress?.(newProgress);
+  };
+  const executeRequest = async (url, index, signal) => {
+    const { execute: execute2, error: reqError, statusCode } = useApi(url, {
+      ...apiOptions,
+      useGlobalAbort: false,
+      skipErrorNotification
+    });
+    try {
+      const result = await execute2({ signal });
+      if (signal.aborted) {
+        return {
+          url,
+          index,
+          success: false,
+          data: null,
+          error: { message: "Request aborted", status: 0, code: "ABORTED" },
+          statusCode: null
+        };
+      }
+      const item = {
+        url,
+        index,
+        success: result !== null && result !== void 0,
+        data: result ?? null,
+        error: reqError.value,
+        statusCode: statusCode.value
+      };
+      if (item.success) {
+        onItemSuccess?.(item, index);
+      } else if (item.error) {
+        onItemError?.(item, index);
+      }
+      return item;
+    } catch (err) {
+      const apiError = {
+        message: err instanceof Error ? err.message : "Unknown error",
+        status: 0,
+        code: "BATCH_ERROR"
+      };
+      const item = {
+        url,
+        index,
+        success: false,
+        data: null,
+        error: apiError,
+        statusCode: null
+      };
+      onItemError?.(item, index);
+      return item;
+    }
+  };
+  const executeWithConcurrency = async (urls2, limit) => {
+    const results = new Array(urls2.length);
+    let succeededCount = 0;
+    let failedCount = 0;
+    if (!limit || limit >= urls2.length) {
+      const promises = urls2.map((url, index) => {
+        const controller = new AbortController();
+        abortControllers.value.push(controller);
+        return executeRequest(url, index, controller.signal).then((result) => {
+          results[index] = result;
+          if (result.success) {
+            succeededCount++;
+          } else {
+            failedCount++;
+            if (result.error) {
+              errors.value.push(result.error);
+            }
+          }
+          updateProgress(succeededCount, failedCount);
+          if (!settled && !result.success && result.error) {
+            throw result.error;
+          }
+          return result;
+        });
+      });
+      if (settled) {
+        await Promise.allSettled(promises);
+      } else {
+        await Promise.all(promises);
+      }
+    } else {
+      let currentIndex = 0;
+      const executeNext = async () => {
+        while (currentIndex < urls2.length && !isAborted) {
+          const index = currentIndex++;
+          const url = urls2[index];
+          const controller = new AbortController();
+          abortControllers.value.push(controller);
+          const result = await executeRequest(url, index, controller.signal);
+          results[index] = result;
+          if (result.success) {
+            succeededCount++;
+          } else {
+            failedCount++;
+            if (result.error) {
+              errors.value.push(result.error);
+            }
+          }
+          updateProgress(succeededCount, failedCount);
+          if (!settled && !result.success && result.error) {
+            abort("First request failed in non-settled mode");
+            throw result.error;
+          }
+        }
+      };
+      const workers = Array.from({ length: Math.min(limit, urls2.length) }, () => executeNext());
+      if (settled) {
+        await Promise.allSettled(workers);
+      } else {
+        await Promise.all(workers);
+      }
+    }
+    return results;
+  };
+  const execute = async () => {
+    const currentUrls = getUrls();
+    isAborted = false;
+    loading.value = true;
+    error.value = null;
+    errors.value = [];
+    data.value = [];
+    abortControllers.value = [];
+    updateProgress(0, 0);
+    try {
+      const results = await executeWithConcurrency(currentUrls, concurrency);
+      data.value = results;
+      const allFailed = results.every((r) => !r.success);
+      if (allFailed && results.length > 0) {
+        error.value = {
+          message: `All ${results.length} requests failed`,
+          status: 0,
+          code: "BATCH_ALL_FAILED"
+        };
+      }
+      onFinish?.(results);
+      return results;
+    } catch (err) {
+      if (!settled) {
+        error.value = err;
+      }
+      throw err;
+    } finally {
+      loading.value = false;
+      abortControllers.value = [];
+    }
+  };
+  const abort = (message = "Batch aborted") => {
+    isAborted = true;
+    for (const controller of abortControllers.value) {
+      controller.abort(message);
+    }
+    abortControllers.value = [];
+  };
+  const reset = () => {
+    abort();
+    loading.value = false;
+    error.value = null;
+    errors.value = [];
+    data.value = [];
+    progress.value = {
+      completed: 0,
+      total: getUrls().length,
+      percentage: 0,
+      succeeded: 0,
+      failed: 0
+    };
+  };
+  if ((0, import_vue5.getCurrentScope)()) {
+    (0, import_vue5.onScopeDispose)(() => abort("Scope disposed"));
+  }
+  if (watchSource) {
+    (0, import_vue5.watch)(watchSource, () => {
+      execute();
+    }, { deep: true });
+  }
+  if (immediate) {
+    execute();
+  }
+  return {
+    data,
+    successfulData,
+    loading,
+    error,
+    errors,
+    progress,
+    execute,
+    abort,
+    reset
+  };
+}
+
 // src/features/createInstance.ts
 var import_axios3 = __toESM(require("axios"), 1);
 
@@ -684,6 +921,7 @@ function createApiClient(options = {}) {
   tokenManager,
   useAbortController,
   useApi,
+  useApiBatch,
   useApiConfig,
   useApiDelete,
   useApiGet,

package/dist/index.d.cts

@@ -94,6 +94,87 @@ interface AuthTokens$1 {
     refreshToken?: string;
     expiresIn?: number;
 }
+/**
+ * Result of a single request in a batch operation
+ */
+interface BatchResultItem<T = unknown> {
+    /** The URL that was requested */
+    url: string;
+    /** Index in the original urls array */
+    index: number;
+    /** Whether the request succeeded */
+    success: boolean;
+    /** The response data (null if failed) */
+    data: T | null;
+    /** Error details (null if succeeded) */
+    error: ApiError | null;
+    /** HTTP status code */
+    statusCode: number | null;
+}
+/**
+ * Progress information for batch operations
+ */
+interface BatchProgress {
+    /** Number of completed requests (success + failed) */
+    completed: number;
+    /** Total number of requests */
+    total: number;
+    /** Completion percentage (0-100) */
+    percentage: number;
+    /** Number of successful requests */
+    succeeded: number;
+    /** Number of failed requests */
+    failed: number;
+}
+/**
+ * Options for useApiBatch
+ */
+interface UseApiBatchOptions<T = unknown, D = unknown> extends Omit<ApiRequestConfig<D>, "url"> {
+    /**
+     * If true (default), failed requests don't stop the batch.
+     * If false, first error will reject the entire batch.
+     */
+    settled?: boolean;
+    /** Maximum concurrent requests. Default: unlimited */
+    concurrency?: number;
+    /** Execute immediately on mount */
+    immediate?: boolean;
+    /** Skip individual error notifications */
+    skipErrorNotification?: boolean;
+    /** Watch sources to trigger re-execution */
+    watch?: WatchSource | WatchSource[];
+    /** Callback when a single request succeeds */
+    onItemSuccess?: (item: BatchResultItem<T>, index: number) => void;
+    /** Callback when a single request fails */
+    onItemError?: (item: BatchResultItem<T>, index: number) => void;
+    /** Callback when all requests complete */
+    onFinish?: (results: BatchResultItem<T>[]) => void;
+    /** Callback when progress updates */
+    onProgress?: (progress: BatchProgress) => void;
+}
+/**
+ * Return type for useApiBatch
+ */
+interface UseApiBatchReturn<T = unknown> {
+    /** All results with their status */
+    data: Ref<BatchResultItem<T>[]>;
+    /** Only successful results' data */
+    successfulData: Ref<T[]>;
+    /** Whether any request is still loading */
+    loading: Ref<boolean>;
+    /** Aggregated error (set if all requests failed) */
+    error: Ref<ApiError | null>;
+    /** List of all errors from failed requests */
+    errors: Ref<ApiError[]>;
+    /** Progress tracking */
+    progress: Ref<BatchProgress>;
+    /** Execute the batch */
+    execute: () => Promise<BatchResultItem<T>[]>;
+    /** Abort all pending requests */
+    abort: (message?: string) => void;
+    /** Reset state to initial */
+    reset: () => void;
+}
 
 declare function createApi(options: ApiPluginOptions): {
     install(app: App): void;
@@ -153,6 +234,59 @@ declare function useApiPatch<T = unknown, D = unknown>(url: MaybeRefOrGetter<str
  */
 declare function useApiDelete<T = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T>, "method">): UseApiReturn<T>;
 
+/**
+ * Execute multiple API requests in parallel with full reactive state
+ *
+ * Features:
+ * - Reactive loading, data, error, progress states
+ * - Reactive urls support (MaybeRefOrGetter)
+ * - Error tolerance with `settled: true` (default)
+ * - Concurrency limiting
+ * - Abort support for all pending requests
+ * - Detailed per-request results with URL mapping
+ * - Progress tracking
+ * - Watch option for auto re-execution
+ *
+ * @example
+ * ```ts
+ * // Basic usage - fetch multiple users
+ * const { data, loading, progress, execute } = useApiBatch<User>([
+ *   '/users/1',
+ *   '/users/2',
+ *   '/users/3'
+ * ])
+ *
+ * await execute()
+ * console.log(data.value) // BatchResultItem<User>[]
+ *
+ * // With reactive urls
+ * const userIds = ref([1, 2, 3])
+ * const urls = computed(() => userIds.value.map(id => `/users/${id}`))
+ * const { successfulData } = useApiBatch<User>(urls, { immediate: true })
+ *
+ * // With options
+ * const { successfulData, errors, progress } = useApiBatch<Post>(
+ *   ['/posts/1', '/posts/2', '/posts/3'],
+ *   {
+ *     concurrency: 2,        // Max 2 parallel requests
+ *     immediate: true,       // Execute on mount
+ *     onProgress: (p) => console.log(`${p.percentage}%`)
+ *   }
+ * )
+ *
+ * // Strict mode - fail on first error
+ * const { execute } = useApiBatch<User>(urls, { settled: false })
+ *
+ * // Auto re-execute when dependency changes
+ * const filters = ref({ status: 'active' })
+ * const { data } = useApiBatch<User>(urls, {
+ *   watch: filters,
+ *   immediate: true
+ * })
+ * ```
+ */
+declare function useApiBatch<T = unknown>(urls: MaybeRefOrGetter<string[]>, options?: UseApiBatchOptions<T>): UseApiBatchReturn<T>;
+
 /**
  * API State Composable
  *
@@ -424,4 +558,4 @@ 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 SetDataInput, type UseApiOptions, type UseApiReturn, createApi, createApiClient, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };
+export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, 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 };

package/dist/index.d.ts

@@ -94,6 +94,87 @@ interface AuthTokens$1 {
     refreshToken?: string;
     expiresIn?: number;
 }
+/**
+ * Result of a single request in a batch operation
+ */
+interface BatchResultItem<T = unknown> {
+    /** The URL that was requested */
+    url: string;
+    /** Index in the original urls array */
+    index: number;
+    /** Whether the request succeeded */
+    success: boolean;
+    /** The response data (null if failed) */
+    data: T | null;
+    /** Error details (null if succeeded) */
+    error: ApiError | null;
+    /** HTTP status code */
+    statusCode: number | null;
+}
+/**
+ * Progress information for batch operations
+ */
+interface BatchProgress {
+    /** Number of completed requests (success + failed) */
+    completed: number;
+    /** Total number of requests */
+    total: number;
+    /** Completion percentage (0-100) */
+    percentage: number;
+    /** Number of successful requests */
+    succeeded: number;
+    /** Number of failed requests */
+    failed: number;
+}
+/**
+ * Options for useApiBatch
+ */
+interface UseApiBatchOptions<T = unknown, D = unknown> extends Omit<ApiRequestConfig<D>, "url"> {
+    /**
+     * If true (default), failed requests don't stop the batch.
+     * If false, first error will reject the entire batch.
+     */
+    settled?: boolean;
+    /** Maximum concurrent requests. Default: unlimited */
+    concurrency?: number;
+    /** Execute immediately on mount */
+    immediate?: boolean;
+    /** Skip individual error notifications */
+    skipErrorNotification?: boolean;
+    /** Watch sources to trigger re-execution */
+    watch?: WatchSource | WatchSource[];
+    /** Callback when a single request succeeds */
+    onItemSuccess?: (item: BatchResultItem<T>, index: number) => void;
+    /** Callback when a single request fails */
+    onItemError?: (item: BatchResultItem<T>, index: number) => void;
+    /** Callback when all requests complete */
+    onFinish?: (results: BatchResultItem<T>[]) => void;
+    /** Callback when progress updates */
+    onProgress?: (progress: BatchProgress) => void;
+}
+/**
+ * Return type for useApiBatch
+ */
+interface UseApiBatchReturn<T = unknown> {
+    /** All results with their status */
+    data: Ref<BatchResultItem<T>[]>;
+    /** Only successful results' data */
+    successfulData: Ref<T[]>;
+    /** Whether any request is still loading */
+    loading: Ref<boolean>;
+    /** Aggregated error (set if all requests failed) */
+    error: Ref<ApiError | null>;
+    /** List of all errors from failed requests */
+    errors: Ref<ApiError[]>;
+    /** Progress tracking */
+    progress: Ref<BatchProgress>;
+    /** Execute the batch */
+    execute: () => Promise<BatchResultItem<T>[]>;
+    /** Abort all pending requests */
+    abort: (message?: string) => void;
+    /** Reset state to initial */
+    reset: () => void;
+}
 
 declare function createApi(options: ApiPluginOptions): {
     install(app: App): void;
@@ -153,6 +234,59 @@ declare function useApiPatch<T = unknown, D = unknown>(url: MaybeRefOrGetter<str
  */
 declare function useApiDelete<T = unknown>(url: MaybeRefOrGetter<string | undefined>, options?: Omit<UseApiOptions<T>, "method">): UseApiReturn<T>;
 
+/**
+ * Execute multiple API requests in parallel with full reactive state
+ *
+ * Features:
+ * - Reactive loading, data, error, progress states
+ * - Reactive urls support (MaybeRefOrGetter)
+ * - Error tolerance with `settled: true` (default)
+ * - Concurrency limiting
+ * - Abort support for all pending requests
+ * - Detailed per-request results with URL mapping
+ * - Progress tracking
+ * - Watch option for auto re-execution
+ *
+ * @example
+ * ```ts
+ * // Basic usage - fetch multiple users
+ * const { data, loading, progress, execute } = useApiBatch<User>([
+ *   '/users/1',
+ *   '/users/2',
+ *   '/users/3'
+ * ])
+ *
+ * await execute()
+ * console.log(data.value) // BatchResultItem<User>[]
+ *
+ * // With reactive urls
+ * const userIds = ref([1, 2, 3])
+ * const urls = computed(() => userIds.value.map(id => `/users/${id}`))
+ * const { successfulData } = useApiBatch<User>(urls, { immediate: true })
+ *
+ * // With options
+ * const { successfulData, errors, progress } = useApiBatch<Post>(
+ *   ['/posts/1', '/posts/2', '/posts/3'],
+ *   {
+ *     concurrency: 2,        // Max 2 parallel requests
+ *     immediate: true,       // Execute on mount
+ *     onProgress: (p) => console.log(`${p.percentage}%`)
+ *   }
+ * )
+ *
+ * // Strict mode - fail on first error
+ * const { execute } = useApiBatch<User>(urls, { settled: false })
+ *
+ * // Auto re-execute when dependency changes
+ * const filters = ref({ status: 'active' })
+ * const { data } = useApiBatch<User>(urls, {
+ *   watch: filters,
+ *   immediate: true
+ * })
+ * ```
+ */
+declare function useApiBatch<T = unknown>(urls: MaybeRefOrGetter<string[]>, options?: UseApiBatchOptions<T>): UseApiBatchReturn<T>;
+
 /**
  * API State Composable
  *
@@ -424,4 +558,4 @@ 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 SetDataInput, type UseApiOptions, type UseApiReturn, createApi, createApiClient, setAuthMonitor, setupInterceptors, tokenManager, useAbortController, useApi, useApiConfig, useApiDelete, useApiGet, useApiPatch, useApiPost, useApiPut, useApiState };
+export { type ApiError, type ApiPluginOptions, type ApiRequestConfig, type ApiState, type AuthEventPayload, AuthEventType, type AuthMode, type AuthMonitorFn, type AuthTokens$1 as AuthTokens, type BatchProgress, 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 };

package/dist/index.mjs

@@ -330,6 +330,242 @@ function useApiDelete(url, options) {
   return useApi(url, { ...options, method: "DELETE" });
 }
 
+// src/useApiBatch.ts
+import { ref as ref4, computed, getCurrentScope as getCurrentScope2, onScopeDispose as onScopeDispose2, toValue as toValue2, watch as watch2 } from "vue";
+function useApiBatch(urls, options = {}) {
+  const {
+    settled = true,
+    concurrency,
+    immediate = false,
+    skipErrorNotification = true,
+    watch: watchSource,
+    onItemSuccess,
+    onItemError,
+    onFinish,
+    onProgress,
+    ...apiOptions
+  } = options;
+  const getUrls = () => toValue2(urls);
+  const data = ref4([]);
+  const loading = ref4(false);
+  const error = ref4(null);
+  const errors = ref4([]);
+  const progress = ref4({
+    completed: 0,
+    total: 0,
+    percentage: 0,
+    succeeded: 0,
+    failed: 0
+  });
+  const successfulData = computed(
+    () => data.value.filter((item) => item.success && item.data !== null).map((item) => item.data)
+  );
+  const abortControllers = ref4([]);
+  let isAborted = false;
+  const updateProgress = (succeeded, failed) => {
+    const currentUrls = getUrls();
+    const completed = succeeded + failed;
+    const newProgress = {
+      completed,
+      total: currentUrls.length,
+      percentage: currentUrls.length > 0 ? Math.round(completed / currentUrls.length * 100) : 0,
+      succeeded,
+      failed
+    };
+    progress.value = newProgress;
+    onProgress?.(newProgress);
+  };
+  const executeRequest = async (url, index, signal) => {
+    const { execute: execute2, error: reqError, statusCode } = useApi(url, {
+      ...apiOptions,
+      useGlobalAbort: false,
+      skipErrorNotification
+    });
+    try {
+      const result = await execute2({ signal });
+      if (signal.aborted) {
+        return {
+          url,
+          index,
+          success: false,
+          data: null,
+          error: { message: "Request aborted", status: 0, code: "ABORTED" },
+          statusCode: null
+        };
+      }
+      const item = {
+        url,
+        index,
+        success: result !== null && result !== void 0,
+        data: result ?? null,
+        error: reqError.value,
+        statusCode: statusCode.value
+      };
+      if (item.success) {
+        onItemSuccess?.(item, index);
+      } else if (item.error) {
+        onItemError?.(item, index);
+      }
+      return item;
+    } catch (err) {
+      const apiError = {
+        message: err instanceof Error ? err.message : "Unknown error",
+        status: 0,
+        code: "BATCH_ERROR"
+      };
+      const item = {
+        url,
+        index,
+        success: false,
+        data: null,
+        error: apiError,
+        statusCode: null
+      };
+      onItemError?.(item, index);
+      return item;
+    }
+  };
+  const executeWithConcurrency = async (urls2, limit) => {
+    const results = new Array(urls2.length);
+    let succeededCount = 0;
+    let failedCount = 0;
+    if (!limit || limit >= urls2.length) {
+      const promises = urls2.map((url, index) => {
+        const controller = new AbortController();
+        abortControllers.value.push(controller);
+        return executeRequest(url, index, controller.signal).then((result) => {
+          results[index] = result;
+          if (result.success) {
+            succeededCount++;
+          } else {
+            failedCount++;
+            if (result.error) {
+              errors.value.push(result.error);
+            }
+          }
+          updateProgress(succeededCount, failedCount);
+          if (!settled && !result.success && result.error) {
+            throw result.error;
+          }
+          return result;
+        });
+      });
+      if (settled) {
+        await Promise.allSettled(promises);
+      } else {
+        await Promise.all(promises);
+      }
+    } else {
+      let currentIndex = 0;
+      const executeNext = async () => {
+        while (currentIndex < urls2.length && !isAborted) {
+          const index = currentIndex++;
+          const url = urls2[index];
+          const controller = new AbortController();
+          abortControllers.value.push(controller);
+          const result = await executeRequest(url, index, controller.signal);
+          results[index] = result;
+          if (result.success) {
+            succeededCount++;
+          } else {
+            failedCount++;
+            if (result.error) {
+              errors.value.push(result.error);
+            }
+          }
+          updateProgress(succeededCount, failedCount);
+          if (!settled && !result.success && result.error) {
+            abort("First request failed in non-settled mode");
+            throw result.error;
+          }
+        }
+      };
+      const workers = Array.from({ length: Math.min(limit, urls2.length) }, () => executeNext());
+      if (settled) {
+        await Promise.allSettled(workers);
+      } else {
+        await Promise.all(workers);
+      }
+    }
+    return results;
+  };
+  const execute = async () => {
+    const currentUrls = getUrls();
+    isAborted = false;
+    loading.value = true;
+    error.value = null;
+    errors.value = [];
+    data.value = [];
+    abortControllers.value = [];
+    updateProgress(0, 0);
+    try {
+      const results = await executeWithConcurrency(currentUrls, concurrency);
+      data.value = results;
+      const allFailed = results.every((r) => !r.success);
+      if (allFailed && results.length > 0) {
+        error.value = {
+          message: `All ${results.length} requests failed`,
+          status: 0,
+          code: "BATCH_ALL_FAILED"
+        };
+      }
+      onFinish?.(results);
+      return results;
+    } catch (err) {
+      if (!settled) {
+        error.value = err;
+      }
+      throw err;
+    } finally {
+      loading.value = false;
+      abortControllers.value = [];
+    }
+  };
+  const abort = (message = "Batch aborted") => {
+    isAborted = true;
+    for (const controller of abortControllers.value) {
+      controller.abort(message);
+    }
+    abortControllers.value = [];
+  };
+  const reset = () => {
+    abort();
+    loading.value = false;
+    error.value = null;
+    errors.value = [];
+    data.value = [];
+    progress.value = {
+      completed: 0,
+      total: getUrls().length,
+      percentage: 0,
+      succeeded: 0,
+      failed: 0
+    };
+  };
+  if (getCurrentScope2()) {
+    onScopeDispose2(() => abort("Scope disposed"));
+  }
+  if (watchSource) {
+    watch2(watchSource, () => {
+      execute();
+    }, { deep: true });
+  }
+  if (immediate) {
+    execute();
+  }
+  return {
+    data,
+    successfulData,
+    loading,
+    error,
+    errors,
+    progress,
+    execute,
+    abort,
+    reset
+  };
+}
+
 // src/features/createInstance.ts
 import axios from "axios";
 
@@ -633,6 +869,7 @@ export {
   tokenManager,
   useAbortController,
   useApi,
+  useApiBatch,
   useApiConfig,
   useApiDelete,
   useApiGet,

package/package.json

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