http-request-manager 18.15.32 → 18.15.34

package/src/docs/BATCH_REQUEST_README.md

@@ -0,0 +1,467 @@
+# Batch Request Functionality
+
+Execute multiple HTTP requests with configurable execution strategies (sequential/parallel), error handling, and automatic order preservation.
+
+## Overview
+
+The batch request functionality allows you to process multiple HTTP requests efficiently with full control over:
+
+- **Execution order**: Sequential or parallel
+- **Error handling**: Stop on error or continue
+- **Concurrency**: Control parallel request limits
+- **Result ordering**: Results always match the order of requests provided
+
+## Features
+
+✅ **Sequential Execution** - Process requests one-by-one in order  
+✅ **Parallel Execution** - Process multiple requests concurrently  
+✅ **Configurable Concurrency** - Limit parallel requests (default: 3)  
+✅ **Error Handling** - Stop on error or continue with all requests  
+✅ **Order Preservation** - Results always in request order  
+✅ **Optional Configuration** - All options optional with sensible defaults  
+✅ **Type Safe** - Full TypeScript generic support  
+
+## Usage
+
+### Basic Sequential (Default)
+
+```typescript
+import { HTTPManagerService, ApiRequest, BatchOptions } from 'http-request-manager';
+
+const requests = [
+  ApiRequest.adapt({ path: ['users', 1] }),
+  ApiRequest.adapt({ path: ['users', 2] }),
+  ApiRequest.adapt({ path: ['users', 3] })
+];
+
+httpManager.getBatchRequests(requests).subscribe(results => {
+  // results is User[] in the same order as requests
+  console.log(results[0]); // User 1
+  console.log(results[1]); // User 2
+  console.log(results[2]); // User 3
+});
+```
+
+### Sequential with Stop on Error
+
+```typescript
+httpManager.getBatchRequests(requests, {
+  mode: 'sequential',
+  stopOnError: true
+}).subscribe({
+  next: results => {
+    console.log('All succeeded:', results);
+  },
+  error: error => {
+    console.error('Stopped at first error:', error);
+  }
+});
+```
+
+### Parallel Execution
+
+```typescript
+httpManager.getBatchRequests(requests, {
+  mode: 'parallel',
+  concurrency: 5  // Process up to 5 requests simultaneously
+}).subscribe(results => {
+  console.log('All completed:', results);
+});
+```
+
+### Ignore Errors and Complete All
+
+```typescript
+httpManager.getBatchRequests(requests, {
+  ignoreErrors: true,
+  logErrors: false  // Suppress console.error output
+}).subscribe(results => {
+  // Results array contains data or undefined for failed requests
+  const validResults = results.filter(r => r !== undefined);
+  console.log(`Success: ${validResults.length} of ${results.length}`);
+});
+```
+
+### With Per-Request Configuration
+
+Each request can have its own retry, polling, adapter, etc.:
+
+```typescript
+const requests = [
+  ApiRequest.adapt({
+    path: ['users', 1],
+    retry: { times: 3, delay: 1 },
+    adapter: User.adapt
+  }),
+  ApiRequest.adapt({
+    path: ['users', 2],
+    polling: 10,  // This request will poll
+    adapter: User.adapt
+  }),
+  ApiRequest.adapt({
+    path: ['users', 3],
+    displayError: true,
+    adapter: User.adapt
+  })
+];
+
+httpManager.getBatchRequests<User>(requests, {
+  mode: 'parallel',
+  concurrency: 2
+}).subscribe(results => {
+  results.forEach((user, index) => {
+    console.log(`User ${index}:`, user);
+  });
+});
+```
+
+## Configuration Options
+
+All options are **optional** with sensible defaults:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mode` | `'sequential' \| 'parallel'` | `'sequential'` | Execution strategy |
+| `stopOnError` | `boolean` | `false` | Stop sequential execution on first error |
+| `concurrency` | `number` | `3` | Max concurrent requests (parallel mode) |
+| `ignoreErrors` | `boolean` | `false` | Continue on errors, failed requests return `undefined` |
+| `logErrors` | `boolean` | `true` | Log errors to console |
+
+## Error Handling Matrix
+
+| Mode | stopOnError | ignoreErrors | Behavior |
+| :--- | :--- | :--- | :--- |
+| Sequential | false | false | Continue on error, observable errors |
+| Sequential | true | N/A | Stop on first error, observable errors |
+| Sequential | false | true | Continue, failed = `undefined`, no error |
+| Parallel | N/A | false | Complete all, failed = `undefined`, no error |
+| Parallel | N/A | true | Complete all, failed = `undefined`, no logging |
+
+## Return Value
+
+The method returns `Observable<U[]>` where:
+
+- `U` is the generic type (inferred or explicitly provided)
+- Array length matches the number of requests
+- Results are in the **same order** as requests provided
+- Failed requests return `undefined` when `ignoreErrors: true`
+
+### Example with Type Safety
+
+```typescript
+// Homogeneous batch (recommended)
+httpManager.getBatchRequests<User>(userRequests)
+  .subscribe((users: User[]) => {
+    // users is typed as User[]
+  });
+
+// Heterogeneous batch
+httpManager.getBatchRequests(mixedRequests)
+  .subscribe((results: any[]) => {
+    // results is any[]
+  });
+```
+
+## Best Practices
+
+### 1. Use Type Parameters
+
+```typescript
+// ✅ Good - Type safe
+httpManager.getBatchRequests<User>(requests)
+
+// ❌ Avoid - No type safety
+httpManager.getBatchRequests(requests)
+```
+
+### 2. Choose Appropriate Concurrency
+
+```typescript
+// For small batches (< 10)
+{ mode: 'parallel', concurrency: 5 }
+
+// For large batches (10-100)
+{ mode: 'parallel', concurrency: 3 }
+
+// For API rate limiting
+{ mode: 'parallel', concurrency: 1 }  // Effectively sequential
+```
+
+### 3. Handle Errors Appropriately
+
+```typescript
+// Critical operations - stop on error
+{ mode: 'sequential', stopOnError: true }
+
+// Non-critical - ignore errors
+{ ignoreErrors: true }
+
+// Default - log and continue
+// (no options needed)
+```
+
+### 4. Use `BatchOptions.adapt()` for Direct Method Calls
+
+When calling `getParallelRequest` or `getSequentialRequest` directly, wrap options with `BatchOptions.adapt()` to satisfy the class type:
+
+```typescript
+// ✅ Correct
+httpManager.getParallelRequest(requests, BatchOptions.adapt({ concurrency: 5 }))
+
+// ❌ Type error - plain object is not assignable to BatchOptions class
+httpManager.getParallelRequest(requests, { concurrency: 5 })
+```
+
+### 5. Keep Batch Sizes Reasonable
+
+- **Recommended**: < 100 requests per batch
+- **Large batches**: Consider splitting into multiple batches
+- **Very large**: Use pagination or streaming (future enhancement)
+
+## Direct Parallel / Sequential Methods
+
+As an alternative to `getBatchRequests`, you can call the execution methods directly. Both return `Observable<U[]>` — a **single emission** of all results after every request completes, preserving request order.
+
+### `getParallelRequest`
+
+```typescript
+import { BatchOptions } from 'http-request-manager';
+
+httpManager.getParallelRequest<User>(requests, BatchOptions.adapt({
+  concurrency: 5,
+  ignoreErrors: true,
+  logErrors: true
+})).subscribe(users => {
+  // users: User[] — one array emitted when all requests finish
+  console.log(users[0]); // index-matched to requests[0]
+  console.log(users[1]); // index-matched to requests[1]
+});
+```
+
+### `getSequentialRequest`
+
+```typescript
+httpManager.getSequentialRequest<Todo>(requests, BatchOptions.adapt({
+  stopOnError: false,
+  ignoreErrors: true,
+  logErrors: true
+})).subscribe(todos => {
+  // todos: Todo[] — one array emitted after ALL requests complete in order
+  todos.forEach((todo, i) => {
+    if (todo) console.log(`Todo ${i + 1}:`, todo.title);
+  });
+});
+```
+
+### When to use which
+
+| Method | Use when |
+| :--- | :--- |
+| `getBatchRequests` | Mode is selected at runtime via `options.mode` |
+| `getParallelRequest` | Mode is always parallel; called directly |
+| `getSequentialRequest` | Mode is always sequential; called directly |
+| `getBatchRequestsStream` | Real-time per-request state updates needed (`isPending`, `data`, `error`) |
+
+## Examples
+
+### Load Multiple Resources
+
+```typescript
+const resourceIds = [1, 2, 3, 4, 5];
+const requests = resourceIds.map(id => 
+  ApiRequest.adapt({ path: ['resources', id] })
+);
+
+httpManager.getBatchRequests<Resource>(requests).subscribe(resources => {
+  resources.forEach(resource => {
+    if (resource) {
+      console.log('Resource:', resource.name);
+    }
+  });
+});
+```
+
+### Bulk Create Operations
+
+```typescript
+const newUsers = [
+  { name: 'User 1', email: 'user1@example.com' },
+  { name: 'User 2', email: 'user2@example.com' },
+  { name: 'User 3', email: 'user3@example.com' }
+];
+
+const requests = newUsers.map(user =>
+  ApiRequest.adapt({
+    path: ['users'],
+    mapper: (u) => u
+  })
+);
+
+httpManager.getBatchRequests<User>(requests, {
+  mode: 'parallel',
+  concurrency: 2
+}).subscribe(createdUsers => {
+  createdUsers.forEach(user => {
+    console.log('Created:', user);
+  });
+});
+```
+
+### Sequential with Fallback
+
+```typescript
+const primaryRequests = [
+  ApiRequest.adapt({ path: ['primary', 'data1'] }),
+  ApiRequest.adapt({ path: ['primary', 'data2'] })
+];
+
+httpManager.getBatchRequests(primaryRequests, {
+  mode: 'sequential',
+  stopOnError: false,
+  ignoreErrors: true
+}).subscribe(results => {
+  // Check for failures and trigger fallback
+  const failures = results.filter((r, i) => !r);
+  if (failures.length > 0) {
+    // Trigger fallback for failed requests
+    const fallbackRequests = failures.map((_, i) => 
+      ApiRequest.adapt({ path: ['fallback', 'data' + i] })
+    );
+    // Execute fallback...
+  }
+});
+```
+
+## Performance Considerations
+
+### Memory Usage
+
+- **Small batches (< 10)**: Negligible impact
+- **Medium batches (10-100)**: Acceptable for most use cases
+- **Large batches (100+)**: Consider splitting into multiple batches
+
+### Network Concurrency
+
+- Default concurrency of 3 balances throughput and server load
+- Adjust based on API rate limits
+- Browser connection limits typically 6-8 per domain
+
+### Server Load
+
+```typescript
+// High concurrency (use with caution)
+{ mode: 'parallel', concurrency: 10 }
+
+// Moderate (recommended default)
+{ mode: 'parallel', concurrency: 3 }
+
+// Conservative (for rate-limited APIs)
+{ mode: 'parallel', concurrency: 1 }
+```
+
+## Troubleshooting
+
+### Results Not in Expected Order
+
+Results are **always** in the order of requests provided, not completion order:
+
+```typescript
+// Even with parallel mode, results maintain request order
+const requests = [req1, req2, req3];
+// Results: [result1, result2, result3] (not completion order)
+```
+
+### Undefined Values in Results
+
+When `ignoreErrors: true`, failed requests return `undefined`:
+
+```typescript
+httpManager.getBatchRequests(requests, {
+  ignoreErrors: true
+}).subscribe(results => {
+  // Filter out undefined values
+  const validResults = results.filter(r => r !== undefined);
+});
+```
+
+### Type Errors
+
+Ensure you're using the generic type parameter:
+
+```typescript
+// ✅ Correct
+httpManager.getBatchRequests<User>(requests)
+
+// ❌ May cause type issues
+httpManager.getBatchRequests(requests)
+```
+
+## API Reference
+
+### Method Signatures
+
+```typescript
+// Route by mode at runtime
+getBatchRequests<U = T>(
+  requests: ApiRequest[],
+  options?: BatchOptions
+): Observable<U[]>
+
+// Call parallel execution directly
+getParallelRequest<U = T>(
+  requests: ApiRequest[],
+  options?: BatchOptions
+): Observable<U[]>
+
+// Call sequential execution directly
+getSequentialRequest<U = T>(
+  requests: ApiRequest[],
+  options?: BatchOptions
+): Observable<U[]>
+
+// Real-time per-request state stream
+getBatchRequestsStream<U = T>(
+  requests: ApiRequest[],
+  options?: BatchOptions
+): Observable<BatchRequestState<U>>
+```
+
+### Parameters
+
+- **requests**: `ApiRequest[]` - Array of request configurations
+- **options**: `BatchOptions` (optional) - Created via `BatchOptions.adapt()` for partial inputs
+
+### Returns
+
+- `Observable<U[]>` — Single emission of all results in request order (`getBatchRequests`, `getParallelRequest`, `getSequentialRequest`)
+- `Observable<BatchRequestState<U>>` — Stream of pending/success/error states per request (`getBatchRequestsStream`)
+
+### BatchOptions Class
+
+`BatchOptions` is a class, not a plain interface. Use `BatchOptions.adapt()` to construct from a partial object — it fills in all defaults:
+
+```typescript
+// ✅ Use adapt() when passing a partial options object
+BatchOptions.adapt({ concurrency: 5 })
+
+// ✅ Also fine when using getBatchRequests (accepts optional partial via overload)
+httpManager.getBatchRequests(requests, { mode: 'parallel' })
+```
+
+```typescript
+class BatchOptions {
+  mode: 'sequential' | 'parallel' = 'sequential';
+  stopOnError: boolean = false;
+  concurrency: number = 3;
+  ignoreErrors: boolean = false;
+  logErrors: boolean = true;
+
+  static adapt(item?: Partial<BatchOptions>): BatchOptions;
+}
+```
+
+## Related Documentation
+
+- [HTTP Manager Service](./HTTP_MANAGER_README.md)
+- [HTTP Signals Manager Service](./HTTP_SIGNALS_MANAGER_README.md)
+- [ApiRequest Configuration](./MODELS_README.md)