http-request-manager 18.15.34 → 18.16.1

package/src/docs/BATCH_REQUEST_README.md

@@ -1,467 +0,0 @@
-# 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)