@emmvish/stable-request 1.0.8 → 1.1.0

package/README.md

@@ -1,17 +1,18 @@
 ## stable-request
 
-`stable-request` is a TypeScript-first HTTP reliability framework that goes beyond status-code retries by validating response content, handling eventual consistency, coordinating batch workflows, and providing deep observability into every request attempt. It is designed for real-world distributed systems where HTTP success does not guarantee business success.
+`stable-request` is a TypeScript-first HTTP reliability framework that goes beyond status-code retries by validating response content, handling eventual consistency, coordinating batch workflows with intelligent grouping, and providing deep observability into every request attempt. It is designed for real-world distributed systems where HTTP success does not guarantee business success.
 
 ## Why stable-request?
 
 Most HTTP client libraries only retry on network failures or specific HTTP status codes. **stable-request** goes further by providing:
 
 - ✅ **Content-aware retries** - Validate response content and retry even on successful HTTP responses
-- 🚀 **Batch processing** - Execute multiple requests concurrently or sequentially with shared configuration
+- 🚀 **Batch processing with groups** - Execute multiple requests with hierarchical configuration (global → group → request)
+- 🎯 **Request grouping** - Organize related requests with shared settings and logical boundaries
 - 🧪 **Trial mode** - Simulate failures to test your retry logic without depending on real network instability
 - 📊 **Granular observability** - Monitor every attempt with detailed hooks
 - ⚡ **Multiple retry strategies** - Fixed, linear, or exponential backoff
-- 🎯 **Flexible error handling** - Custom error analysis and graceful degradation
+- 🔧 **Flexible error handling** - Custom error analysis and graceful degradation
 
 ## Installation
 
@@ -70,6 +71,56 @@ const results = await stableApiGateway(requests, {
 });
 ```
 
+### Grouped Requests
+
+```typescript
+import { stableApiGateway, RETRY_STRATEGIES } from '@emmvish/stable-request';
+
+const results = await stableApiGateway(
+  [
+    {
+      id: 'auth-check',
+      groupId: 'critical-services',
+      requestOptions: {
+        reqData: { path: '/auth/verify' },
+        resReq: true
+      }
+    },
+    {
+      id: 'analytics-track',
+      groupId: 'optional-services',
+      requestOptions: {
+        reqData: { path: '/analytics/event' },
+        resReq: true
+      }
+    }
+  ],
+  {
+    // Global defaults
+    commonAttempts: 2,
+    commonRequestData: { hostname: 'api.example.com' },
+    
+    // Define groups with their own configurations
+    requestGroups: [
+      {
+        id: 'critical-services',
+        commonConfig: {
+          commonAttempts: 10,
+          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+        }
+      },
+      {
+        id: 'optional-services',
+        commonConfig: {
+          commonAttempts: 1,
+          commonFinalErrorAnalyzer: async () => true // Don't throw on failure
+        }
+      }
+    ]
+  }
+);
+```
+
 ## Core Features
 
 ### 1. Content-Aware Retries with `stableRequest`
@@ -142,9 +193,9 @@ const results = await stableApiGateway(requests, {
 // Process results
 results.forEach(result => {
   if (result.success) {
-    console.log(`${result.id} succeeded:`, result.data);
+    console.log(`${result.requestId} succeeded:`, result.data);
   } else {
-    console.error(`${result.id} failed:`, result.error);
+    console.error(`${result.requestId} failed:`, result.error);
   }
 });
 ```
@@ -159,7 +210,98 @@ const results = await stableApiGateway(requests, {
 });
 ```
 
-### 3. Trial Mode - Test Your Retry Logic
+### 3. Request Grouping - Hierarchical Configuration
+
+Organize requests into logical groups with their own configuration. The configuration priority is:
+
+**Individual Request Options** (highest) → **Group Common Options** (middle) → **Global Common Options** (lowest)
+
+```typescript
+const results = await stableApiGateway(
+  [
+    {
+      id: 'payment-stripe',
+      groupId: 'payment-providers',
+      requestOptions: {
+        reqData: { path: '/stripe/charge' },
+        resReq: true,
+        // Individual override: even more attempts for Stripe
+        attempts: 15
+      }
+    },
+    {
+      id: 'payment-paypal',
+      groupId: 'payment-providers',
+      requestOptions: {
+        reqData: { path: '/paypal/charge' },
+        resReq: true
+      }
+    },
+    {
+      id: 'analytics-event',
+      groupId: 'analytics',
+      requestOptions: {
+        reqData: { path: '/track' },
+        resReq: true
+      }
+    }
+  ],
+  {
+    // Global configuration - applies to all ungrouped requests
+    commonAttempts: 2,
+    commonWait: 500,
+    commonRequestData: {
+      hostname: 'api.example.com',
+      method: REQUEST_METHODS.POST
+    },
+    
+    // Group-specific configurations
+    requestGroups: [
+      {
+        id: 'payment-providers',
+        commonConfig: {
+          // Payment group: aggressive retries
+          commonAttempts: 10,
+          commonWait: 2000,
+          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+          commonRequestData: {
+            headers: { 'X-Idempotency-Key': crypto.randomUUID() }
+          },
+          commonHandleErrors: async (reqData, error) => {
+            await alertPagerDuty('Payment failure', error);
+          }
+        }
+      },
+      {
+        id: 'analytics',
+        commonConfig: {
+          // Analytics group: minimal retries, failures acceptable
+          commonAttempts: 1,
+          commonFinalErrorAnalyzer: async () => true // Don't throw
+        }
+      }
+    ]
+  }
+);
+
+// Filter results by group
+const paymentResults = results.filter(r => r.groupId === 'payment-providers');
+const analyticsResults = results.filter(r => r.groupId === 'analytics');
+
+console.log('Payment success rate:', 
+  paymentResults.filter(r => r.success).length / paymentResults.length);
+```
+
+**Key Benefits of Request Grouping:**
+
+1. **Service Tiering** - Different retry strategies for critical vs. optional services
+2. **Regional Configuration** - Customize timeouts and retries per geographic region
+3. **Priority Management** - Handle high-priority requests more aggressively
+4. **Organized Configuration** - Group related requests with shared settings
+5. **Simplified Maintenance** - Update group config instead of individual requests
+6. **Better Monitoring** - Track metrics and failures by logical groups
+
+### 4. Trial Mode - Test Your Retry Logic
 
 Simulate request and retry failures with configurable probabilities.
 
@@ -186,7 +328,7 @@ await stableRequest({
 - Validating monitoring and alerting
 - Testing circuit breaker patterns
 
-### 4. Multiple Retry Strategies
+### 5. Multiple Retry Strategies
 
 Choose the backoff strategy that fits your use case.
 
@@ -221,7 +363,7 @@ await stableRequest({
 });
 ```
 
-### 5. Comprehensive Observability
+### 6. Comprehensive Observability
 
 Monitor every request attempt with detailed logging hooks.
 
@@ -260,7 +402,7 @@ await stableRequest({
 });
 ```
 
-### 6. Smart Retry Logic
+### 7. Smart Retry Logic
 
 Automatically retries on common transient errors:
 
@@ -284,7 +426,7 @@ await stableRequest({
 });
 ```
 
-### 7. Final Error Analysis
+### 8. Final Error Analysis
 
 Decide whether to throw or return false based on error analysis.
 
@@ -312,7 +454,7 @@ if (result === false) {
 }
 ```
 
-### 8. Request Cancellation Support
+### 9. Request Cancellation Support
 
 Support for AbortController to cancel requests.
 
@@ -336,7 +478,7 @@ try {
 }
 ```
 
-### 9. Perform All Attempts Mode
+### 10. Perform All Attempts Mode
 
 Execute all retry attempts regardless of success, useful for warm-up scenarios.
 
@@ -396,7 +538,7 @@ interface REQUEST_DATA<RequestDataType = any> {
 
 ### `stableApiGateway<RequestDataType, ResponseDataType>(requests, options)`
 
-Execute multiple HTTP requests with shared configuration.
+Execute multiple HTTP requests with shared configuration and optional grouping.
 
 #### Gateway Configuration Options
 
@@ -404,6 +546,7 @@ Execute multiple HTTP requests with shared configuration.
 |--------|------|---------|-------------|
 | `concurrentExecution` | `boolean` | `true` | Execute requests concurrently or sequentially |
 | `stopOnFirstError` | `boolean` | `false` | Stop execution on first error (sequential only) |
+| `requestGroups` | `RequestGroup[]` | `[]` | Define groups with their own common configurations |
 | `commonAttempts` | `number` | `1` | Default attempts for all requests |
 | `commonPerformAllAttempts` | `boolean` | `false` | Default performAllAttempts for all requests |
 | `commonWait` | `number` | `1000` | Default wait time for all requests |
@@ -417,25 +560,44 @@ Execute multiple HTTP requests with shared configuration.
 | `commonFinalErrorAnalyzer` | `function` | `() => false` | Default final error analyzer for all requests |
 | `commonHandleErrors` | `function` | console.log | Default error handler for all requests |
 | `commonHandleSuccessfulAttemptData` | `function` | console.log | Default success handler for all requests |
-| `commonRequestData` | `Partial REQUEST_DATA` | { hostname: '' } | Common set of axios options for each request |
+| `commonRequestData` | `Partial<REQUEST_DATA>` | `{ hostname: '' }` | Common set of request options for each request |
 
+#### Request Group Configuration
+
+```typescript
+interface RequestGroup {
+  id: string;                          // Unique group identifier
+  commonConfig?: {
+    // Any common* option can be specified here
+    commonAttempts?: number;
+    commonWait?: number;
+    commonRetryStrategy?: RETRY_STRATEGY_TYPES;
+    commonRequestData?: Partial<REQUEST_DATA>;
+    commonResponseAnalyzer?: function;
+    commonHandleErrors?: function;
+    // ... all other common* options
+  };
+}
+```
 
 #### Request Format
 
 ```typescript
 interface API_GATEWAY_REQUEST<RequestDataType, ResponseDataType> {
   id: string;                          // Unique identifier for the request
+  groupId?: string;                    // Optional group identifier
   requestOptions: API_GATEWAY_REQUEST_OPTIONS_TYPE<RequestDataType, ResponseDataType>;
 }
 ```
 
-**Note:** Individual request options override common options. If a specific option is not provided in `requestOptions`, the corresponding `common*` option is used.
+**Configuration Priority:** Individual request options override group options, which override global common options.
 
 #### Response Format
 
 ```typescript
 interface API_GATEWAY_RESPONSE<ResponseDataType> {
-  id: string;                          // Request identifier
+  requestId: string;                   // Request identifier
+  groupId?: string;                    // Group identifier (if request was grouped)
   success: boolean;                    // Whether the request succeeded
   data?: ResponseDataType;             // Response data (if success is true)
   error?: string;                      // Error message (if success is false)
@@ -444,7 +606,224 @@ interface API_GATEWAY_RESPONSE<ResponseDataType> {
 
 ## Real-World Use Cases
 
-### 1. Polling for Async Job Completion
+### 1. Environment-Based Service Tiers with Groups
+
+Organize API calls by criticality with different retry strategies per tier.
+
+```typescript
+const results = await stableApiGateway(
+  [
+    // Critical services
+    { id: 'auth-validate', groupId: 'critical', requestOptions: { reqData: { path: '/auth/validate' }, resReq: true } },
+    { id: 'db-primary', groupId: 'critical', requestOptions: { reqData: { path: '/db/health' }, resReq: true } },
+    
+    // Payment services
+    { id: 'stripe-charge', groupId: 'payments', requestOptions: { reqData: { path: '/stripe/charge', body: { amount: 1000 } }, resReq: true } },
+    { id: 'paypal-charge', groupId: 'payments', requestOptions: { reqData: { path: '/paypal/charge', body: { amount: 1000 } }, resReq: true } },
+    
+    // Analytics services
+    { id: 'track-event', groupId: 'analytics', requestOptions: { reqData: { path: '/track' }, resReq: true } }
+  ],
+  {
+    // Global defaults
+    commonAttempts: 2,
+    commonWait: 500,
+    commonRequestData: { hostname: 'api.example.com', method: REQUEST_METHODS.POST },
+    
+    requestGroups: [
+      {
+        id: 'critical',
+        commonConfig: {
+          commonAttempts: 10,
+          commonWait: 2000,
+          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+          commonHandleErrors: async (reqData, error) => {
+            await pagerDuty.alert('CRITICAL', error);
+          }
+        }
+      },
+      {
+        id: 'payments',
+        commonConfig: {
+          commonAttempts: 5,
+          commonWait: 1500,
+          commonRetryStrategy: RETRY_STRATEGIES.LINEAR,
+          commonRequestData: {
+            headers: { 'X-Idempotency-Key': crypto.randomUUID() }
+          },
+          commonResponseAnalyzer: async (reqData, data) => {
+            return data?.status === 'succeeded' && data?.transactionId;
+          }
+        }
+      },
+      {
+        id: 'analytics',
+        commonConfig: {
+          commonAttempts: 1,
+          commonFinalErrorAnalyzer: async () => true // Don't throw
+        }
+      }
+    ]
+  }
+);
+
+// Analyze results by group
+const criticalHealth = results.filter(r => r.groupId === 'critical').every(r => r.success);
+const paymentSuccess = results.filter(r => r.groupId === 'payments').filter(r => r.success).length;
+
+if (!criticalHealth) {
+  console.error('CRITICAL SERVICES DEGRADED');
+}
+console.log(`Payments: ${paymentSuccess} successful`);
+```
+
+### 2. Multi-Region API Deployment with Groups
+
+Handle requests to different geographic regions with region-specific configurations.
+
+```typescript
+const results = await stableApiGateway(
+  [
+    { id: 'us-user-profile', groupId: 'us-east', requestOptions: { reqData: { path: '/users/profile' }, resReq: true } },
+    { id: 'us-orders', groupId: 'us-east', requestOptions: { reqData: { path: '/orders' }, resReq: true } },
+    
+    { id: 'eu-user-profile', groupId: 'eu-west', requestOptions: { reqData: { path: '/users/profile' }, resReq: true } },
+    { id: 'eu-orders', groupId: 'eu-west', requestOptions: { reqData: { path: '/orders' }, resReq: true } },
+    
+    { id: 'ap-user-profile', groupId: 'ap-southeast', requestOptions: { reqData: { path: '/users/profile' }, resReq: true } },
+    { id: 'ap-orders', groupId: 'ap-southeast', requestOptions: { reqData: { path: '/orders' }, resReq: true } }
+  ],
+  {
+    commonAttempts: 3,
+    commonWait: 1000,
+    
+    requestGroups: [
+      {
+        id: 'us-east',
+        commonConfig: {
+          commonRequestData: {
+            hostname: 'api-us-east.example.com',
+            headers: { 'X-Region': 'us-east-1' },
+            timeout: 5000 // Lower latency expected
+          },
+          commonAttempts: 3,
+          commonRetryStrategy: RETRY_STRATEGIES.LINEAR
+        }
+      },
+      {
+        id: 'eu-west',
+        commonConfig: {
+          commonRequestData: {
+            hostname: 'api-eu-west.example.com',
+            headers: { 'X-Region': 'eu-west-1' },
+            timeout: 8000
+          },
+          commonAttempts: 5,
+          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+        }
+      },
+      {
+        id: 'ap-southeast',
+        commonConfig: {
+          commonRequestData: {
+            hostname: 'api-ap-southeast.example.com',
+            headers: { 'X-Region': 'ap-southeast-1' },
+            timeout: 10000 // Higher latency expected
+          },
+          commonAttempts: 7,
+          commonWait: 1500,
+          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+        }
+      }
+    ]
+  }
+);
+
+// Regional performance analysis
+const regionPerformance = results.reduce((acc, result) => {
+  if (!acc[result.groupId!]) acc[result.groupId!] = { success: 0, failed: 0 };
+  result.success ? acc[result.groupId!].success++ : acc[result.groupId!].failed++;
+  return acc;
+}, {} as Record<string, { success: number; failed: number }>);
+
+console.log('Regional performance:', regionPerformance);
+```
+
+### 3. Microservices Health Monitoring with Groups
+
+Monitor different microservices with service-specific health check configurations.
+
+```typescript
+const healthChecks = await stableApiGateway(
+  [
+    // Core services
+    { id: 'auth-health', groupId: 'core', requestOptions: { reqData: { hostname: 'auth.internal.example.com', path: '/health' } } },
+    { id: 'user-health', groupId: 'core', requestOptions: { reqData: { hostname: 'users.internal.example.com', path: '/health' } } },
+    { id: 'order-health', groupId: 'core', requestOptions: { reqData: { hostname: 'orders.internal.example.com', path: '/health' } } },
+    
+    // Auxiliary services
+    { id: 'cache-health', groupId: 'auxiliary', requestOptions: { reqData: { hostname: 'cache.internal.example.com', path: '/health' } } },
+    { id: 'search-health', groupId: 'auxiliary', requestOptions: { reqData: { hostname: 'search.internal.example.com', path: '/health' } } },
+    
+    // Third-party
+    { id: 'stripe-health', groupId: 'third-party', requestOptions: { reqData: { hostname: 'api.stripe.com', path: '/v1/health' } } }
+  ],
+  {
+    commonResReq: true,
+    concurrentExecution: true,
+    
+    requestGroups: [
+      {
+        id: 'core',
+        commonConfig: {
+          commonAttempts: 5,
+          commonWait: 2000,
+          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+          commonResponseAnalyzer: async (reqData, data) => {
+            return data?.status === 'healthy' && 
+                   data?.dependencies?.every(d => d.status === 'healthy');
+          },
+          commonHandleErrors: async (reqData, error) => {
+            await pagerDuty.trigger({ severity: 'critical', message: `Core service down: ${error.error}` });
+          }
+        }
+      },
+      {
+        id: 'auxiliary',
+        commonConfig: {
+          commonAttempts: 2,
+          commonResponseAnalyzer: async (reqData, data) => data?.status === 'ok',
+          commonFinalErrorAnalyzer: async () => true // Don't fail on auxiliary issues
+        }
+      },
+      {
+        id: 'third-party',
+        commonConfig: {
+          commonAttempts: 3,
+          commonWait: 3000,
+          commonRequestData: { timeout: 15000 },
+          commonHandleErrors: async (reqData, error) => {
+            logger.warn('Third-party health check failed', { error });
+          },
+          commonFinalErrorAnalyzer: async () => true
+        }
+      }
+    ]
+  }
+);
+
+const healthReport = {
+  timestamp: new Date().toISOString(),
+  core: healthChecks.filter(r => r.groupId === 'core').every(r => r.success),
+  auxiliary: healthChecks.filter(r => r.groupId === 'auxiliary').every(r => r.success),
+  thirdParty: healthChecks.filter(r => r.groupId === 'third-party').every(r => r.success),
+  overall: healthChecks.every(r => r.success) ? 'HEALTHY' : 'DEGRADED'
+};
+
+console.log('Health Report:', healthReport);
+```
+
+### 4. Polling for Async Job Completion
 
 ```typescript
 const jobResult = await stableRequest({
@@ -465,7 +844,7 @@ const jobResult = await stableRequest({
 });
 ```
 
-### 2. Resilient External API Integration
+### 5. Resilient External API Integration
 
 ```typescript
 const weatherData = await stableRequest({
@@ -489,7 +868,7 @@ const weatherData = await stableRequest({
 });
 ```
 
-### 3. Database Replication Consistency Check
+### 6. Database Replication Consistency Check
 
 ```typescript
 const consistentData = await stableRequest({
@@ -508,7 +887,7 @@ const consistentData = await stableRequest({
 });
 ```
 
-### 4. Batch User Creation
+### 7. Batch User Creation
 
 ```typescript
 const users = [
@@ -537,9 +916,9 @@ const results = await stableApiGateway(requests, {
     console.log(`Failed to create user: ${error.error}`);
   },
   commonRequestData: {
-      hostname: 'api.example.com',
-      path: '/users',
-      method: REQUEST_METHODS.POST
+    hostname: 'api.example.com',
+    path: '/users',
+    method: REQUEST_METHODS.POST
   }
 });
 
@@ -550,156 +929,97 @@ console.log(`Created ${successful.length} users`);
 console.log(`Failed to create ${failed.length} users`);
 ```
 
-### 5. Rate-Limited API with Backoff
-
-```typescript
-const searchResults = await stableRequest({
-  reqData: {
-    hostname: 'api.ratelimited-service.com',
-    path: '/search',
-    query: { q: 'nodejs' }
-  },
-  resReq: true,
-  attempts: 10,
-  wait: 1000,
-  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL, // Exponential backoff for rate limits
-  handleErrors: async (reqConfig, error) => {
-    if (error.type === 'HTTP_ERROR' && error.error.includes('429')) {
-      console.log('Rate limited, backing off...');
-    }
-  }
-});
-```
-
-### 6. Microservices Health Check
+### 8. Batch Data Processing with Tiered Priority Groups
 
 ```typescript
-const services = ['auth', 'users', 'orders', 'payments'];
+const dataItems = [
+  { id: 1, data: 'critical-transaction', priority: 'high' },
+  { id: 2, data: 'user-action', priority: 'medium' },
+  { id: 3, data: 'analytics-event', priority: 'low' }
+];
 
-const healthChecks = services.map(service => ({
-  id: `health-${service}`,
+const requests = dataItems.map(item => ({
+  id: `item-${item.id}`,
+  groupId: item.priority === 'high' ? 'high-priority' :
+           item.priority === 'medium' ? 'medium-priority' : 'low-priority',
   requestOptions: {
-    reqData: {
-      hostname: `${service}.internal.example.com`,
-    },
-    resReq: true,
-    attempts: 3,
-    wait: 500
+    reqData: { body: item },
+    resReq: true
   }
 }));
 
-const results = await stableApiGateway(healthChecks, {
+const results = await stableApiGateway(requests, {
   concurrentExecution: true,
   commonRequestData: {
-    path: '/health'
+    hostname: 'processing.example.com',
+    path: '/process',
+    method: REQUEST_METHODS.POST
   },
-  commonRetryStrategy: RETRY_STRATEGIES.LINEAR
+  
+  requestGroups: [
+    {
+      id: 'high-priority',
+      commonConfig: {
+        commonAttempts: 10,
+        commonWait: 2000,
+        commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+        commonRequestData: { headers: { 'X-Priority': 'high' } },
+        commonResponseAnalyzer: async (reqData, data) => {
+          return data?.processed && !data?.errors?.length && data?.validationStatus === 'passed';
+        }
+      }
+    },
+    {
+      id: 'medium-priority',
+      commonConfig: {
+        commonAttempts: 5,
+        commonWait: 1000,
+        commonRetryStrategy: RETRY_STRATEGIES.LINEAR,
+        commonRequestData: { headers: { 'X-Priority': 'medium' } }
+      }
+    },
+    {
+      id: 'low-priority',
+      commonConfig: {
+        commonAttempts: 2,
+        commonRequestData: { headers: { 'X-Priority': 'low' } },
+        commonFinalErrorAnalyzer: async () => true // Accept failures
+      }
+    }
+  ]
 });
 
-const healthStatus = results.reduce((acc, result) => {
-  const serviceName = result.id.replace('health-', '');
-  acc[serviceName] = result.success ? 'healthy' : 'unhealthy';
-  return acc;
-}, {});
+// Report by priority
+const report = {
+  high: results.filter(r => r.groupId === 'high-priority'),
+  medium: results.filter(r => r.groupId === 'medium-priority'),
+  low: results.filter(r => r.groupId === 'low-priority')
+};
 
-console.log('Service health status:', healthStatus);
+console.log(`High: ${report.high.filter(r => r.success).length}/${report.high.length}`);
+console.log(`Medium: ${report.medium.filter(r => r.success).length}/${report.medium.length}`);
+console.log(`Low: ${report.low.filter(r => r.success).length}/${report.low.length}`);
 ```
 
-### 7. Payment Processing with Idempotency
+### 9. Rate-Limited API with Backoff
 
 ```typescript
-const payment = await stableRequest({
+const searchResults = await stableRequest({
   reqData: {
-    hostname: 'payment-gateway.com',
-    path: '/charge',
-    method: REQUEST_METHODS.POST,
-    headers: { 'Idempotency-Key': uniqueId },
-    body: { amount: 1000, currency: 'USD' }
+    hostname: 'api.ratelimited-service.com',
+    path: '/search',
+    query: { q: 'nodejs' }
   },
   resReq: true,
-  attempts: 3,
+  attempts: 10,
   wait: 1000,
-  responseAnalyzer: async (reqConfig, data) => {
-    return data.status === 'succeeded';
-  },
-  finalErrorAnalyzer: async (reqConfig, error) => {
-    // Check if payment actually went through despite error
-    const status = await checkPaymentStatus(uniqueId);
-    return status === 'succeeded';
-  }
-});
-```
-
-### 8. Bulk Data Migration
-
-```typescript
-const records = await fetchLegacyRecords();
-
-const migrationRequests = records.map((record, index) => ({
-  id: `migrate-${record.id}`,
-  requestOptions: {
-    reqData: {
-      body: record
-    },
-    resReq: true,
-    // Individual retry config for critical records
-    ...(record.critical && { 
-      attempts: 5,
-      wait: 2000,
-      retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
-    })
-  }
-}));
-
-const results = await stableApiGateway(migrationRequests, {
-  concurrentExecution: true,
-  commonRequestData: {
-      hostname: 'new-system.example.com',
-      path: '/import',
-      method: REQUEST_METHODS.POST,
-  }
-  commonAttempts: 3,
-  commonWait: 1000,
-  commonRetryStrategy: RETRY_STRATEGIES.LINEAR,
-  commonHandleErrors: async (reqConfig, error) => {
-    await logMigrationError(reqConfig.data.id, error);
-  }
-});
-```
-
-### 9. Multi-Source Data Aggregation
-
-```typescript
-const sources = [
-  { id: 'source-1', hostname: 'api1.example.com', path: '/data' },
-  { id: 'source-2', hostname: 'api2.example.com', path: '/info' },
-  { id: 'source-3', hostname: 'api3.example.com', path: '/stats' }
-];
-
-const requests = sources.map(source => ({
-  id: source.id,
-  requestOptions: {
-    reqData: {
-      hostname: source.hostname,
-      path: source.path
-    },
-    resReq: true,
-    attempts: 3,
-    finalErrorAnalyzer: async () => true // Don't fail if one source is down
+  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+  handleErrors: async (reqConfig, error) => {
+    if (error.type === 'HTTP_ERROR' && error.error.includes('429')) {
+      console.log('Rate limited, backing off...');
+    }
   }
-}));
-
-const results = await stableApiGateway(requests, {
-  concurrentExecution: true,
-  commonWait: 1000,
-  commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
 });
-
-const aggregatedData = results
-  .filter(r => r.success)
-  .map(r => r.data);
-
-console.log(`Collected data from ${aggregatedData.length}/${sources.length} sources`);
 ```
 
 ### 10. Sequential Workflow with Dependencies
@@ -709,18 +1029,14 @@ const workflowSteps = [
   {
     id: 'step-1-init',
     requestOptions: {
-      reqData: {
-        path: '/init',
-      },
+      reqData: { path: '/init' },
       resReq: true
     }
   },
   {
     id: 'step-2-process',
     requestOptions: {
-      reqData: {
-        path: '/process',
-      },
+      reqData: { path: '/process' },
       resReq: true,
       responseAnalyzer: async (reqConfig, data) => {
         return data.status === 'completed';
@@ -730,22 +1046,20 @@ const workflowSteps = [
   {
     id: 'step-3-finalize',
     requestOptions: {
-      reqData: {
-        path: '/finalize',
-      },
+      reqData: { path: '/finalize' },
       resReq: true
     }
   }
 ];
 
 const results = await stableApiGateway(workflowSteps, {
-  concurrentExecution: false, // Execute sequentially
-  stopOnFirstError: true,     // Stop if any step fails
+  concurrentExecution: false,
+  stopOnFirstError: true,
   commonRequestData: {
     hostname: 'workflow.example.com',
     method: REQUEST_METHODS.POST,
     body: { workflowId: 'wf-123' }
-  }
+  },
   commonAttempts: 5,
   commonWait: 2000,
   commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
@@ -780,25 +1094,26 @@ async function resilientRequest(endpoint: string) {
         failureCount++;
       }
     });
-    failureCount = 0; // Reset on success
+    failureCount = 0;
     return result;
   } catch (error) {
     if (failureCount >= CIRCUIT_THRESHOLD) {
       console.log('Circuit breaker activated');
-      setTimeout(() => { failureCount = 0; }, 60000); // Reset after 1 minute
+      setTimeout(() => { failureCount = 0; }, 60000);
     }
     throw error;
   }
 }
 ```
 
-### Dynamic Request Configuration
+### Dynamic Request Configuration with Groups
 
 ```typescript
 const endpoints = await getEndpointsFromConfig();
 
 const requests = endpoints.map(endpoint => ({
   id: endpoint.id,
+  groupId: endpoint.tier, // 'critical', 'standard', or 'optional'
   requestOptions: {
     reqData: {
       hostname: endpoint.hostname,
@@ -808,15 +1123,37 @@ const requests = endpoints.map(endpoint => ({
         headers: { Authorization: `Bearer ${endpoint.auth}` }
       })
     },
-    resReq: true,
-    attempts: endpoint.critical ? 5 : 3,
-    retryStrategy: endpoint.critical ? RETRY_STRATEGIES.EXPONENTIAL : RETRY_STRATEGIES.FIXED
+    resReq: true
   }
 }));
 
 const results = await stableApiGateway(requests, {
   concurrentExecution: true,
-  commonWait: 1000
+  commonWait: 1000,
+  
+  requestGroups: [
+    {
+      id: 'critical',
+      commonConfig: {
+        commonAttempts: 10,
+        commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+      }
+    },
+    {
+      id: 'standard',
+      commonConfig: {
+        commonAttempts: 5,
+        commonRetryStrategy: RETRY_STRATEGIES.LINEAR
+      }
+    },
+    {
+      id: 'optional',
+      commonConfig: {
+        commonAttempts: 2,
+        commonFinalErrorAnalyzer: async () => true
+      }
+    }
+  ]
 });
 ```
 
@@ -831,13 +1168,11 @@ await stableRequest({
   resReq: true,
   attempts: 5,
   responseAnalyzer: async (reqConfig, data) => {
-    // Only retry if data is incomplete
     if (!data.complete) {
       console.log('Data incomplete, retrying...');
       return false;
     }
     
-    // Don't retry if data is invalid (different from incomplete)
     if (data.error) {
       throw new Error('Invalid data, cannot retry');
     }
@@ -890,6 +1225,7 @@ console.log(user.id);
 |---------|----------------|-------------|
 | **Content validation** | ✅ Full support with `responseAnalyzer` | ❌ Only HTTP status codes |
 | **Batch processing** | ✅ Built-in `stableApiGateway` | ❌ Manual implementation needed |
+| **Request grouping** | ✅ Hierarchical configuration | ❌ No grouping support |
 | **Trial mode** | ✅ Built-in failure simulation | ❌ No testing utilities |
 | **Retry strategies** | ✅ Fixed, Linear, Exponential | ✅ Exponential only |
 | **Observability** | ✅ Granular hooks for every attempt | ⚠️ Limited |
@@ -901,7 +1237,8 @@ console.log(user.id);
 |---------|----------------|-----|
 | **Built on Axios** | ✅ Leverages Axios ecosystem | ❌ Standalone client |
 | **Content validation** | ✅ Response analyzer | ❌ Only HTTP errors |
-| **Batch processing** | ✅ Built-in gateway | ❌ Manual implementation |
+| **Batch processing** | ✅ Built-in gateway with grouping | ❌ Manual implementation |
+| **Request grouping** | ✅ Multi-tier configuration | ❌ No grouping |
 | **Trial mode** | ✅ Simulation for testing | ❌ No |
 | **Retry strategies** | ✅ 3 configurable strategies | ✅ Exponential with jitter |
 
@@ -912,19 +1249,23 @@ console.log(user.id);
 | **All-in-one** | ✅ Single package | ❌ Requires multiple packages |
 | **HTTP-aware** | ✅ Built for HTTP | ❌ Generic retry wrapper |
 | **Content validation** | ✅ Built-in | ❌ Manual implementation |
-| **Batch processing** | ✅ Built-in | ❌ Manual implementation |
+| **Batch processing** | ✅ Built-in with groups | ❌ Manual implementation |
+| **Request grouping** | ✅ Native support | ❌ No grouping |
 | **Observability** | ✅ Request-specific hooks | ⚠️ Generic callbacks |
 
 ## Best Practices
 
 1. **Use exponential backoff for rate-limited APIs** to avoid overwhelming the server
-2. **Set reasonable timeout values** in `reqData.timeout` to prevent hanging requests
-3. **Implement responseAnalyzer** for APIs that return 200 OK with error details in the body
-4. **Use concurrent execution** in `stableApiGateway` for independent requests
-5. **Use sequential execution** when requests have dependencies or need to maintain order
-6. **Leverage finalErrorAnalyzer** for graceful degradation in non-critical paths
-7. **Enable logging in development** with `logAllErrors` and `logAllSuccessfulAttempts`
-8. **Use Trial Mode** to test your error handling without relying on actual failures
+2. **Organize related requests into groups** for easier configuration management
+3. **Set reasonable timeout values** in `reqData.timeout` to prevent hanging requests
+4. **Implement responseAnalyzer** for APIs that return 200 OK with error details in the body
+5. **Use concurrent execution** in `stableApiGateway` for independent requests
+6. **Use sequential execution** when requests have dependencies or need to maintain order
+7. **Leverage request groups** to differentiate between critical and optional services
+8. **Use finalErrorAnalyzer** for graceful degradation in non-critical paths
+9. **Enable logging in development** with `logAllErrors` and `logAllSuccessfulAttempts`
+10. **Use Trial Mode** to test your error handling without relying on actual failures
+11. **Group requests by region or service tier** for better monitoring and configuration
 
 ## License