@emmvish/stable-request 1.5.1 → 1.5.3

package/README.md

@@ -4,6 +4,7 @@
 
 It ensures that **every request attempt**, whether it succeeds or fails, can be:
 
+- Sent reliably
 - Observed
 - Analyzed
 - Retried intelligently
@@ -17,1304 +18,416 @@ All without crashing your application or hiding context behind opaque errors.
 > If you’ve ever logged `error.message` and thought  
 > **“This tells me absolutely nothing”** — this library is for you.
 
-In addition, it enables **content-aware retries**, **hierarchical configuration**, **batch orchestration**, and **multi-phase workflows** with deep observability — all built on top of standard HTTP calls.
+In addition, it enables **reliability** **content-aware retries**, **hierarchical configuration**, **batch orchestration**, and **multi-phase workflows** with deep observability — all built on top of standard HTTP calls.
 
 All in all, it provides you with the **entire ecosystem** to build **API-integrations based workflows** with **complete flexibility**.
 
 ---
 
+## Choose your entry point
+
+| Need | Use |
+|-----|-----|
+| Reliable single API call | `stableRequest` |
+| Batch or fan-out requests | `stableApiGateway` |
+| Multi-step orchestration | `stableWorkflow` |
+
+Start small and scale
+
+---
+
 ## 📚 Table of Contents
 <!-- TOC START -->
-- [Why stable-request exists](#why-stable-request-exists)
-- [What stable-request gives you](#what-stable-request-gives-you)
-  - [Core capabilities](#core-capabilities)
-  - [Scaling beyond single requests](#scaling-beyond-single-requests)
-  - [Full workflow orchestration](#full-workflow-orchestration)
-- [How stable-request is different](#how-stable-request-is-different)
-- [Choose your entry point](#choose-your-entry-point)
 - [Installation](#installation)
+- [Core Features](#core-features)
 - [Quick Start](#quick-start)
-  - [Basic Request (No Retries)](#1-basic-request-no-retries)
-  - [Add Simple Retries](#2-add-simple-retries)
-  - [Validate Response Content](#3-validate-response-content-content-aware-retries)
-  - [Monitor Errors](#4-monitor-errors-observability)
-  - [Monitor Successful Attempts](#5-monitor-successful-attempts)
-  - [Handle Final Errors Gracefully](#6-handle-final-errors-gracefully)
-  - [Pass Custom Parameters to Hooks](#7-pass-custom-parameters-to-hooks)
-  - [Pre-Execution Hook](#8-pre-execution-hook-dynamic-configuration)
-- [Intermediate Concepts](#intermediate-concepts)
-  - [Making POST/PUT/PATCH/DELETE Requests](#making-postputpatchdelete-requests)
-  - [Query Parameters](#query-parameters)
-  - [Custom Timeout and Port](#custom-timeout-and-port)
-  - [Request Cancellation](#request-cancellation)
-  - [Trial Mode](#trial-mode-testing-your-retry-logic)
-- [Batch Processing - Multiple Requests](#batch-processing---multiple-requests)
-  - [Basic Batch Request](#basic-batch-request)
-  - [Sequential Execution (With Dependencies)](#sequential-execution-with-dependencies)
-  - [Shared Configuration (Common Options)](#shared-configuration-common-options)
-- [Advanced: Request Grouping](#advanced-request-grouping)
-  - [Service Tiers](#example-service-tiers)
-  - [Multi-Region Configuration](#example-multi-region-configuration)
-  - [Shared Buffer Across Requests](#example-shared-buffer-is-common-across-the-entire-batch-of-requests)
-- [Multi-Phase Workflows](#multi-phase-workflows)
-  - [Basic Workflow](#basic-workflow)
-  - [Phase Configuration](#phase-configuration)
-  - [Workflow with Request Groups](#workflow-with-request-groups)
-  - [Phase Observability Hooks](#phase-observability-hooks)
-  - [Workflow Buffer](#workflow-buffer)
-  - [Concurrent Execution of Phases](#concurrent-execution-of-phases)
-  - [Mixed Execution of Phases](#mixed-execution-of-phases)
-- [Real-World Examples](#real-world-examples)
-  - [Polling for Job Completion](#1-polling-for-job-completion)
-  - [Database Replication Lag](#2-database-replication-lag)
-  - [Idempotent Payment Processing](#3-idempotent-payment-processing)
-  - [Batch User Creation](#4-batch-user-creation-with-error-handling)
-  - [Health Check Monitoring System](#5-health-check-monitoring-system)
-  - [Data Pipeline (ETL Workflow)](#6-data-pipeline-etl-workflow)
-- [Complete API Reference](#complete-api-reference)
-  - [`stableRequest`](#stablerequestoptions)
-  - [`stableApiGateway`](#stableapigatewayrequests-options)
-  - [`stableWorkflow`](#stableworkflowphases-options)
-- [Hooks Reference](#hooks-reference)
-  - [`preExecutionHook`](#preexecutionhook)
-  - [`responseAnalyzer`](#responseanalyzer)
-  - [`handleErrors`](#handleerrors)
-  - [`handleSuccessfulAttemptData`](#handlesuccessfulattemptdata)
-  - [`finalErrorAnalyzer`](#finalerroranalyzer)
-  - [`handlePhaseCompletion`](#handlephasecompletion)
-  - [`handlePhaseError`](#handlephaseerror)
-- [Configuration Hierarchy](#configuration-hierarchy)
-- [TypeScript Support](#typescript-support)
+- [API Reference](#api-reference)
+  - [stableRequest](#stableRequest)
+  - [stableApiGateway](#stableApiGateway)
+  - [stableWorkflow](#stableWorkflow)
+- [Advanced Features](#advanced-features)
+  - [Retry Strategies](#retry-strategies)
+  - [Circuit Breaker](#circuit-breaker)
+  - [Rate Limiting](#rate-limiting)
+  - [Caching](#caching)
+  - [Pre-Execution Hooks](#pre-execution-hooks)
+  - [Shared Buffer](#shared-buffer)
+  - [Request Grouping](#request-grouping)
+  - [Concurrency Control](#concurrency-control)
+  - [Response Analysis](#response-analysis)
+  - [Error Handling](#error-handling)
+- [Advanced Use Cases](#advanced-use-cases)
+- [Configuration Options](#configuration-options)
 - [License](#license)
 <!-- TOC END -->
 
 ---
 
-## Why stable-request exists
-
-Modern systems fail in subtle and dangerous ways:
-
-- APIs return `200` but the resource isn’t ready
-- Databases are eventually consistent
-- Downstream services partially fail
-- Some requests are critical, others are optional
-- Blind retries amplify failures
-- Workflows fail midway and leave systems inconsistent
-
-Most HTTP clients answer only one question:
-
-> “Did the request fail at the network or HTTP layer?”
-
-**stable-request answers a different one:**
-
-> “Is the system state actually correct yet?”
-
----
-
-## What stable-request gives you
-
-### Core capabilities
-
-✅ **Content-aware retries**  
-  
-  Retry based on response validation, not just status codes
-
-🔄 **Deterministic execution semantics**  
-  
-  Fixed, linear, or exponential retry strategies with hard limits
+## Installation
 
-🧠 **Graceful failure handling**  
-  
-  Suppress non-critical failures without crashing workflows
+```bash
+npm install @emmvish/stable-request
+```
 
-🧪 **Trial mode / chaos testing**  
-  
-  Simulate failures without depending on real outages
+## Core Features
+
+- ✅ **Configurable Retry Strategies**: Fixed, Linear, and Exponential backoff
+- ✅ **Circuit Breaker**: Prevent cascading failures with automatic circuit breaking
+- ✅ **Rate Limiting**: Control request throughput across single or multiple requests
+- ✅ **Response Caching**: Built-in TTL-based caching with global cache manager
+- ✅ **Batch Processing**: Execute multiple requests concurrently or sequentially via API Gateway
+- ✅ **Multi-Phase Workflows**: Orchestrate complex request workflows with phase dependencies
+- ✅ **Pre-Execution Hooks**: Transform requests before execution with dynamic configuration
+- ✅ **Shared Buffer**: Share state across requests in workflows and gateways
+- ✅ **Request Grouping**: Apply different configurations to request groups
+- ✅ **Observability Hooks**: Track errors, successful attempts, and phase completions
+- ✅ **Response Analysis**: Validate responses and trigger retries based on content
+- ✅ **Trial Mode**: Test configurations without making real API calls
+- ✅ **TypeScript Support**: Full type safety with generics for request/response data
 
-📊 **First-class observability hooks**  
-  
-  Inspect every failed and successful attempt
+## Quick Start
 
----
+### Basic Request with Retry
 
-### Scaling beyond single requests
+```typescript
+import { stableRequest, RETRY_STRATEGIES } from '@emmvish/stable-request';
 
-🚀 **Batch execution with shared state (`stableApiGateway`)**  
-  
-  Run many requests concurrently or sequentially with shared configuration and shared state
+const data = await stableRequest({
+  reqData: {
+    hostname: 'api.example.com',
+    path: '/users/123',
+    method: 'GET'
+  },
+  resReq: true,
+  attempts: 3,
+  wait: 1000,
+  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+});
 
-🎯 **Request groups**  
-  
-  Apply different reliability rules to critical, standard, and optional services
+console.log(data);
+```
 
-🧱 **Hierarchical configuration**  
-  
-  Workflow → Phase → Group → Request (predictable overrides)
+### Batch Requests via API Gateway
 
----
+```typescript
+import { stableApiGateway } from '@emmvish/stable-request';
 
-### Full workflow orchestration
+const requests = [
+  { id: 'user-1', requestOptions: { reqData: { path: '/users/1' }, resReq: true } },
+  { id: 'user-2', requestOptions: { reqData: { path: '/users/2' }, resReq: true } },
+  { id: 'user-3', requestOptions: { reqData: { path: '/users/3' }, resReq: true } }
+];
 
-🧩 **Multi-phase workflows with shared state (`stableWorkflow`)**
-  
-  Model real-world business flows as deterministic, observable execution graphs.
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  concurrentExecution: true,
+  maxConcurrentRequests: 10
+});
 
-🔀 **Mix concurrent and sequential execution**
-  
-  Parallelize where safe, serialize where correctness matters.
+results.forEach(result => {
+  if (result.success) {
+    console.log(`Request ${result.requestId}:`, result.data);
+  } else {
+    console.error(`Request ${result.requestId} failed:`, result.error);
+  }
+});
+```
 
-🛑 **Stop early or degrade gracefully**
-  
-  Stop execution early or continue based on business criticality.
+### Multi-Phase Workflow
 
-📈 **Phase-level metrics and hooks**
-  
-  Track execution time, success rates, and failure boundaries per phase.
+```typescript
+import { stableWorkflow, STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
 
-🧭 **Deterministic, observable execution paths**
-  
-  Every decision is explicit, traceable, and reproducible.
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'authentication',
+    requests: [
+      { id: 'login', requestOptions: { reqData: { path: '/auth/login' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'data-fetching',
+    concurrentExecution: true,
+    requests: [
+      { id: 'users', requestOptions: { reqData: { path: '/users' }, resReq: true } },
+      { id: 'posts', requestOptions: { reqData: { path: '/posts' }, resReq: true } }
+    ]
+  }
+];
 
----
+const result = await stableWorkflow(phases, {
+  workflowId: 'data-pipeline',
+  commonRequestData: { hostname: 'api.example.com' },
+  stopOnFirstPhaseError: true,
+  logPhaseResults: true
+});
 
-## How stable-request is different
+console.log(`Workflow completed: ${result.successfulRequests}/${result.totalRequests} successful`);
+```
 
-| Traditional HTTP Clients | stable-request |
-|--------------------------|---------------|
-| Status-code based retries | Content-aware retries |
-| Per-request thinking | System-level thinking |
-| Fire-and-forget | Deterministic workflows |
-| Best-effort retries | Business-aware execution |
-| Little observability | Deep, structured hooks |
+## API Reference
 
----
+### stableRequest
 
-## Choose your entry point
+Execute a single HTTP request with retry logic and observability.
 
-| Need | Use |
-|-----|-----|
-| Reliable single API call | `stableRequest` |
-| Batch or fan-out requests | `stableApiGateway` |
-| Multi-step orchestration | `stableWorkflow` |
+**Signature:**
+```typescript
+async function stableRequest<RequestDataType, ResponseDataType>(
+  options: STABLE_REQUEST<RequestDataType, ResponseDataType>
+): Promise<ResponseDataType | boolean>
+```
 
-Start small and scale **without changing mental models**.
+**Key Options:**
+- `reqData`: Request configuration (hostname, path, method, headers, body, etc.)
+- `resReq`: If `true`, returns response data; if `false`, returns boolean success status
+- `attempts`: Number of retry attempts (default: 1)
+- `wait`: Base wait time between retries in milliseconds (default: 1000)
+- `retryStrategy`: `FIXED`, `LINEAR`, or `EXPONENTIAL` (default: FIXED)
+- `responseAnalyzer`: Custom function to validate response content
+- `finalErrorAnalyzer`: Handle final errors gracefully (return `true` to suppress error)
+- `cache`: Enable response caching with TTL
+- `circuitBreaker`: Circuit breaker configuration
+- `preExecution`: Pre-execution hooks for dynamic request transformation
+- `commonBuffer`: Shared state object across hooks
 
----
+### stableApiGateway
 
-## Installation
+Execute multiple requests concurrently or sequentially with shared configuration.
 
-```bash
-npm install @emmvish/stable-request
+**Signature:**
+```typescript
+async function stableApiGateway<RequestDataType, ResponseDataType>(
+  requests: API_GATEWAY_REQUEST<RequestDataType, ResponseDataType>[],
+  options: API_GATEWAY_OPTIONS<RequestDataType, ResponseDataType>
+): Promise<API_GATEWAY_RESPONSE<ResponseDataType>[]>
 ```
 
-## Quick Start
-
-### 1. Basic Request (No Retries)
+**Key Options:**
+- `concurrentExecution`: Execute requests concurrently (default: true)
+- `stopOnFirstError`: Stop processing on first error (sequential mode only)
+- `maxConcurrentRequests`: Limit concurrent execution
+- `rateLimit`: Rate limiting configuration
+- `circuitBreaker`: Shared circuit breaker across requests
+- `requestGroups`: Apply different configurations to request groups
+- `sharedBuffer`: Shared state across all requests
+- `common*`: Common configuration applied to all requests (e.g., `commonAttempts`, `commonCache`)
 
-```typescript
-import { stableRequest, REQUEST_METHODS } from '@emmvish/stable-request';
+### stableWorkflow
 
-interface PatchRequestBodyParams {
-  id: number;
-  updates: {
-    name?: string;
-    age?: number;
-  }
-}
+Execute multi-phase workflows with sequential or concurrent phase execution.
 
-interface ResponseParams {
-  id: number;
-  name: string;
-  age: number;
-}
+**Signature:**
+```typescript
+async function stableWorkflow<RequestDataType, ResponseDataType>(
+  phases: STABLE_WORKFLOW_PHASE<RequestDataType, ResponseDataType>[],
+  options: STABLE_WORKFLOW_OPTIONS<RequestDataType, ResponseDataType>
+): Promise<STABLE_WORKFLOW_RESULT<ResponseDataType>>
+```
 
-const getStableResponse = async () => {
+**Key Options:**
+- `workflowId`: Unique workflow identifier
+- `concurrentPhaseExecution`: Execute phases concurrently (default: false)
+- `stopOnFirstPhaseError`: Stop workflow on first phase failure
+- `enableMixedExecution`: Allow mixed concurrent/sequential phase execution
+- `handlePhaseCompletion`: Hook called after each phase completes
+- `handlePhaseError`: Hook called when phase fails
+- `sharedBuffer`: Shared state across all phases and requests
 
-  const token = 'my-auth-token';
+**Phase Configuration:**
+- `id`: Phase identifier
+- `requests`: Array of requests in this phase
+- `concurrentExecution`: Execute phase requests concurrently
+- `stopOnFirstError`: Stop phase on first request error
+- `markConcurrentPhase`: Mark phase for concurrent execution in mixed mode
+- `commonConfig`: Phase-level configuration overrides
 
-  const data = await stableRequest<PatchRequestBodyParams, ResponseParams>({
-    reqData: {
-      method: REQUEST_METHODS.PATCH,
-      hostname: 'api.example.com',
-      path: '/users',
-      headers: { Authorization: `Bearer ${token}` },
-      body: { id: 123, updates: { age: 27 } }
-    },
-    resReq: true  // Return the response data
-  });
-  
-  console.log(data); // { id: 123, name: 'MV', age: 27 }
-}
+## Advanced Features
 
-getStableResponse();
-```
+### Retry Strategies
 
-### 2. Add Simple Retries
+Control the delay between retry attempts:
 
 ```typescript
 import { stableRequest, RETRY_STRATEGIES } from '@emmvish/stable-request';
 
-const getStableResponse = async () => {
-  const data = await stableRequest({
-    reqData: {
-      hostname: 'api.example.com',
-      path: '/users/123'
-    },
-    resReq: true,
-    attempts: 3,              // Retry up to 3 times
-    wait: 1000,               // Wait 1 second between retries
-    maxAllowedWait: 8000,   // Maximum permissible wait time between retries
-    retryStrategy: RETRY_STRATEGIES.EXPONENTIAL  // 1s, 2s, 4s, 8s...
-  });
+// Fixed delay: 1000ms between each retry
+await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
+  attempts: 3,
+  wait: 1000,
+  retryStrategy: RETRY_STRATEGIES.FIXED
+});
 
-  console.log(data);
-}
+// Linear backoff: 1000ms, 2000ms, 3000ms
+await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
+  attempts: 3,
+  wait: 1000,
+  retryStrategy: RETRY_STRATEGIES.LINEAR
+});
 
-getStableResponse();
+// Exponential backoff: 1000ms, 2000ms, 4000ms
+await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
+  attempts: 3,
+  wait: 1000,
+  maxAllowedWait: 10000,
+  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+});
 ```
 
-**Retry Strategies:**
-- `RETRY_STRATEGIES.FIXED` - Same delay every time (1s, 1s, 1s...)
-- `RETRY_STRATEGIES.LINEAR` - Increasing delay (1s, 2s, 3s...)
-- `RETRY_STRATEGIES.EXPONENTIAL` - Exponential backoff (1s, 2s, 4s, 8s...)
+### Circuit Breaker
 
-### 3. Validate Response Content (Content-Aware Retries)
-
-Sometimes an API returns HTTP 200 but the data isn't ready yet. Use `responseAnalyzer`:
+Prevent cascading failures by automatically blocking requests when error thresholds are exceeded:
 
 ```typescript
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/jobs/456/status'
-  },
-  resReq: true,
-  attempts: 10,
-  wait: 2000,
-  
-  // This hook validates the response content
-  responseAnalyzer: async ({ reqData, data, trialMode, params, commonBuffer }) => {
-    // Return true if response is valid, false to retry
-    if (data.status === 'completed') {
-      return true;  // Success! Don't retry
-    }
-    
-    console.log(`Job still processing... (${data.percentComplete}%)`);
-    return false;  // Retry this request
+import { stableApiGateway, CircuitBreakerState } from '@emmvish/stable-request';
+
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  circuitBreaker: {
+    failureThresholdPercentage: 50,  // Open circuit at 50% failure rate
+    minimumRequests: 5,               // Need at least 5 requests to calculate
+    recoveryTimeoutMs: 30000,         // Try recovery after 30 seconds
+    trackIndividualAttempts: false    // Track per-request success/failure
   }
 });
 
-console.log('Job completed:', data);
-```
-
-**Hook Signature:**
-```typescript
-responseAnalyzer?: (options: {
-  reqData: AxiosRequestConfig;     // Request configuration
-  data: ResponseDataType;           // Response data from API
-  trialMode?: TRIAL_MODE_OPTIONS;   // Trial mode settings (if enabled)
-  params?: any;                     // Custom parameters (via hookParams)
-  commonBuffer: Record<string, any> // For communication between request hooks
-}) => boolean | Promise<boolean>;
-```
-
-### 4. Monitor Errors (Observability)
-
-Track every failed attempt with `handleErrors`:
-
-```typescript
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/data'
-  },
-  resReq: true,
-  attempts: 5,
-  logAllErrors: true,  // Enable error logging
-  
-  // This hook is called on every failed attempt
-  handleErrors: async ({ reqData, errorLog, maxSerializableChars, commonBuffer }) => {
-    // Log to your monitoring service
-    await monitoring.logError({
-      url: reqData.url,
-      attempt: errorLog.attempt,        // e.g., "3/5"
-      error: errorLog.error,            // Error message
-      isRetryable: errorLog.isRetryable,  // Can we retry?
-      type: errorLog.type,              // 'HTTP_ERROR' or 'INVALID_CONTENT'
-      statusCode: errorLog.statusCode,  // HTTP status code
-      timestamp: errorLog.timestamp,    // ISO timestamp
-      executionTime: errorLog.executionTime  // ms
-    });
-  }
+// Circuit breaker can be shared across workflows
+const breaker = new CircuitBreaker({
+  failureThresholdPercentage: 50,
+  minimumRequests: 10,
+  recoveryTimeoutMs: 60000
 });
-```
 
-**Hook Signature:**
-```typescript
-handleErrors?: (options: {
-  reqData: AxiosRequestConfig;       // Request configuration
-  errorLog: ERROR_LOG;               // Detailed error information
-  maxSerializableChars?: number;     // Max chars for stringification
-  commonBuffer: Record<string, any> // For communication between request hooks
-}) => any | Promise<any>;
-```
+const result = await stableWorkflow(phases, {
+  circuitBreaker: breaker,
+  // ... other options
+});
 
-**ERROR_LOG Structure:**
-```typescript
-interface ERROR_LOG {
-  timestamp: string;        // ISO timestamp
-  executionTime: number;    // Request duration in ms
-  statusCode: number;       // HTTP status code (0 if network error)
-  attempt: string;          // e.g., "3/5"
-  error: string;            // Error message
-  type: 'HTTP_ERROR' | 'INVALID_CONTENT';
-  isRetryable: boolean;     // Can this error be retried?
-}
+// Check circuit breaker state
+const state = breaker.getState();
+console.log(`Circuit breaker state: ${state.state}`); // CLOSED, OPEN, or HALF_OPEN
 ```
 
-### 5. Monitor Successful Attempts
+### Rate Limiting
 
-Track successful requests with `handleSuccessfulAttemptData`:
+Control request throughput to prevent overwhelming APIs:
 
 ```typescript
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/data'
-  },
-  resReq: true,
-  attempts: 3,
-  logAllSuccessfulAttempts: true,  // Enable success logging
-  
-  // This hook is called on every successful attempt
-  handleSuccessfulAttemptData: async ({ reqData, successfulAttemptData, maxSerializableChars }) => {
-    // Track metrics
-    await analytics.track('api_success', {
-      url: reqData.url,
-      attempt: successfulAttemptData.attempt,  // e.g., "2/3"
-      duration: successfulAttemptData.executionTime,  // ms
-      statusCode: successfulAttemptData.statusCode,   // 200, 201, etc.
-      timestamp: successfulAttemptData.timestamp
-    });
+import { stableApiGateway } from '@emmvish/stable-request';
+
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  concurrentExecution: true,
+  rateLimit: {
+    maxRequests: 10,  // Maximum 10 requests
+    windowMs: 1000    // Per 1 second window
   }
 });
-```
 
-**Hook Signature:**
-```typescript
-handleSuccessfulAttemptData?: (options: {
-  reqData: AxiosRequestConfig;              // Request configuration
-  successfulAttemptData: SUCCESSFUL_ATTEMPT_DATA;  // Success details
-  maxSerializableChars?: number;            // Max chars for stringification
-  commonBuffer: Record<string, any> // For communication between request hooks
-}) => any | Promise<any>;
-```
-
-**SUCCESSFUL_ATTEMPT_DATA Structure:**
-```typescript
-interface SUCCESSFUL_ATTEMPT_DATA<ResponseDataType> {
-  attempt: string;          // e.g., "2/3"
-  timestamp: string;        // ISO timestamp
-  executionTime: number;    // Request duration in ms
-  data: ResponseDataType;   // Response data
-  statusCode: number;       // HTTP status code
-}
-```
-
-### 6. Handle Final Errors Gracefully
-
-Decide what to do when all retries fail using `finalErrorAnalyzer`:
-
-```typescript
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/optional-feature'
-  },
-  resReq: true,
-  attempts: 3,
-  
-  // This hook is called when all retries are exhausted
-  finalErrorAnalyzer: async ({ reqData, error, trialMode, params }) => {
-    // Check if this is a non-critical error
-    if (error.message.includes('404')) {
-      console.log('Feature not available, continuing without it');
-      return true;  // Suppress error, return false instead of throwing
-    }
-    
-    // For critical errors
-    await alerting.sendAlert('Critical API failure', error);
-    return false;  // Throw the error
+// Rate limiting in workflows
+const result = await stableWorkflow(phases, {
+  rateLimit: {
+    maxRequests: 5,
+    windowMs: 1000
   }
 });
-
-if (data === false) {
-  console.log('Optional feature unavailable, using default');
-}
-```
-
-**Hook Signature:**
-```typescript
-finalErrorAnalyzer?: (options: {
-  reqData: AxiosRequestConfig;     // Request configuration
-  error: any;                      // The final error object
-  trialMode?: TRIAL_MODE_OPTIONS;  // Trial mode settings (if enabled)
-  params?: any;                    // Custom parameters (via hookParams)
-  commonBuffer: Record<string, any> // For communication between request hooks
-}) => boolean | Promise<boolean>;
 ```
 
-**Return value:**
-- `true` - Suppress the error, function returns `false` instead of throwing
-- `false` - Throw the error
-
-### 7. Pass Custom Parameters to Hooks
+### Caching
 
-You can pass custom data to `responseAnalyzer` and `finalErrorAnalyzer`:
+Cache responses with TTL to reduce redundant API calls:
 
 ```typescript
-const expectedVersion = 42;
+import { stableRequest, getGlobalCacheManager } from '@emmvish/stable-request';
 
+// Enable caching for a request
 const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/data'
-  },
+  reqData: { hostname: 'api.example.com', path: '/users/123' },
   resReq: true,
-  attempts: 5,
-  
-  // Pass custom parameters
-  hookParams: {
-    responseAnalyzerParams: { expectedVersion, minItems: 10 },
-    finalErrorAnalyzerParams: { alertTeam: true }
-  },
-  
-  responseAnalyzer: async ({ data, params }) => {
-    // Access custom parameters
-    return data.version >= params.expectedVersion && 
-           data.items.length >= params.minItems;
-  },
-  
-  finalErrorAnalyzer: async ({ error, params }) => {
-    if (params.alertTeam) {
-      await pagerDuty.alert('API failure', error);
-    }
-    return false;
+  cache: {
+    enabled: true,
+    ttl: 60000  // Cache for 60 seconds
   }
 });
+
+// Use global cache manager across requests
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  commonCache: { enabled: true, ttl: 300000 }  // 5 minutes
+});
+
+// Manage cache manually
+const cacheManager = getGlobalCacheManager();
+const stats = cacheManager.getStats();
+console.log(`Cache size: ${stats.size}, Valid entries: ${stats.validEntries}`);
+cacheManager.clear();  // Clear all cache
 ```
 
-### 8. Pre-Execution Hook (Dynamic Configuration)
+### Pre-Execution Hooks
 
-Use `preExecution` to modify request configuration dynamically before execution:
+Transform requests dynamically before execution:
 
 ```typescript
-const outputBuffer: Record<string, any> = {};
+import { stableRequest } from '@emmvish/stable-request';
+
+const commonBuffer: Record<string, any> = {};
 
 const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/protected-resource'
-  },
+  reqData: { hostname: 'api.example.com', path: '/data' },
   resReq: true,
-  attempts: 3,
-  
   preExecution: {
-    // Hook executed before any request attempts
     preExecutionHook: async ({ inputParams, commonBuffer }) => {
-      const token = await authService.getToken(inputParams.userId);
+      // Fetch authentication token
+      const token = await getAuthToken();
+      
+      // Store in shared buffer
       commonBuffer.token = token;
-      commonBuffer.fetchedAt = new Date().toISOString();
-      // Return configuration overrides
+      commonBuffer.timestamp = Date.now();
+      
+      // Override request configuration
       return {
         reqData: {
           hostname: 'api.example.com',
-          path: '/protected-resource',
-          headers: {
-            'Authorization': `Bearer ${token}`
-          }
-        },
-        attempts: 5
+          path: '/authenticated-data',
+          headers: { Authorization: `Bearer ${token}` }
+        }
       };
     },
-    preExecutionHookParams: {
-      userId: 'user-123',
-      environment: 'production'
-    },
-    applyPreExecutionConfigOverride: true,
+    preExecutionHookParams: { userId: 'user123' },
+    applyPreExecutionConfigOverride: true,  // Apply returned config
     continueOnPreExecutionHookFailure: false
   },
-  commonBuffer: outputBuffer
-});
-
-console.log('Token used:', outputBuffer.token);
-console.log('Fetched at:', outputBuffer.fetchedAt);
-```
-
-**Pre-Execution Options:**
-
-```typescript
-interface PreExecutionOptions {
-  preExecutionHook: (options: {
-    inputParams: any;        // Custom parameters you provide
-  }) => any | Promise<any>;  // Returns config overrides
-  preExecutionHookParams?: any;              // Custom input parameters
-  applyPreExecutionConfigOverride?: boolean;  // Apply returned overrides (default: false)
-  continueOnPreExecutionHookFailure?: boolean; // Continue if hook fails (default: false)
-}
-```
-
-## Intermediate Concepts
-
-### Making POST/PUT/PATCH/DELETE Requests
-
-```typescript
-import { stableRequest, REQUEST_METHODS } from '@emmvish/stable-request';
-
-const newUser = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/users',
-    method: REQUEST_METHODS.POST,
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': 'Bearer your-token'
-    },
-    body: {
-      name: 'John Doe',
-      email: 'john@example.com'
-    }
-  },
-  resReq: true,
-  attempts: 3
-});
-```
-
-### Query Parameters
-
-```typescript
-const users = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/users',
-    query: {
-      page: 1,
-      limit: 10,
-      sort: 'createdAt'
-    }
-  },
-  resReq: true
-});
-// Requests: https://api.example.com:443/users?page=1&limit=10&sort=createdAt
-```
-
-### Custom Timeout and Port
-
-```typescript
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/slow-endpoint',
-    port: 8080,
-    protocol: 'http',
-    timeout: 30000  // 30 seconds
-  },
-  resReq: true,
-  attempts: 2
-});
-```
-
-### Request Cancellation
-
-```typescript
-const controller = new AbortController();
-
-// Cancel after 5 seconds
-setTimeout(() => controller.abort(), 5000);
-
-try {
-  await stableRequest({
-    reqData: {
-      hostname: 'api.example.com',
-      path: '/data',
-      signal: controller.signal
-    },
-    resReq: true
-  });
-} catch (error) {
-  if (error.message.includes('cancelled')) {
-    console.log('Request was cancelled');
-  }
-}
-```
-
-### Trial Mode (Testing Your Retry Logic)
-
-Simulate failures without depending on actual API issues:
-
-```typescript
-await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/data'
-  },
-  resReq: true,
-  attempts: 5,
-  logAllErrors: true,
-  
-  trialMode: {
-    enabled: true,
-    reqFailureProbability: 0.3,    // 30% chance each request fails
-    retryFailureProbability: 0.2   // 20% chance error is non-retryable
-  }
-});
-```
-
-**Use cases:**
-- Test your error handling logic
-- Verify monitoring alerts work
-- Chaos engineering experiments
-- Integration testing
-
-## Batch Processing - Multiple Requests
-
-### Basic Batch Request
-
-```typescript
-import { stableApiGateway } from '@emmvish/stable-request';
-
-const requests = [
-  {
-    id: 'user-1',
-    requestOptions: {
-      reqData: { path: '/users/1' },
-      resReq: true
-    }
-  },
-  {
-    id: 'user-2',
-    requestOptions: {
-      reqData: { path: '/users/2' },
-      resReq: true
-    }
-  },
-  {
-    id: 'user-3',
-    requestOptions: {
-      reqData: { path: '/users/3' },
-      resReq: true
-    }
-  }
-];
-
-const results = await stableApiGateway(requests, {
-  // Common options applied to ALL requests
-  commonRequestData: {
-    hostname: 'api.example.com'
-  },
-  commonAttempts: 3,
-  commonWait: 1000,
-  concurrentExecution: true  // Run all requests in parallel
-});
-
-// Process results
-results.forEach(result => {
-  if (result.success) {
-    console.log(`${result.requestId} succeeded:`, result.data);
-  } else {
-    console.error(`${result.requestId} failed:`, result.error);
-  }
-});
-```
-
-**Response Format:**
-```typescript
-interface API_GATEWAY_RESPONSE<ResponseDataType> {
-  requestId: string;     // The ID you provided
-  groupId?: string;      // Group ID (if request was grouped)
-  success: boolean;      // Did the request succeed?
-  data?: ResponseDataType;  // Response data (if success)
-  error?: string;        // Error message (if failed)
-}
-```
-
-### Sequential Execution (With Dependencies)
-
-```typescript
-const steps = [
-  {
-    id: 'step-1-create',
-    requestOptions: {
-      reqData: { 
-        path: '/orders',
-        method: REQUEST_METHODS.POST,
-        body: { item: 'Widget' }
-      },
-      resReq: true
-    }
-  },
-  {
-    id: 'step-2-process',
-    requestOptions: {
-      reqData: { 
-        path: '/orders/123/process',
-        method: REQUEST_METHODS.POST
-      },
-      resReq: true
-    }
-  },
-  {
-    id: 'step-3-ship',
-    requestOptions: {
-      reqData: { path: '/orders/123/ship' },
-      resReq: true
-    }
-  }
-];
-
-const results = await stableApiGateway(steps, {
-  concurrentExecution: false,  // Run one at a time
-  stopOnFirstError: true,      // Stop if any step fails
-  commonRequestData: {
-    hostname: 'api.example.com'
-  },
-  commonAttempts: 3
-});
-
-if (results.every(r => r.success)) {
-  console.log('Workflow completed successfully');
-} else {
-  const failedStep = results.findIndex(r => !r.success);
-  console.error(`Workflow failed at step ${failedStep + 1}`);
-}
-```
-
-### Shared Configuration (Common Options)
-
-Instead of repeating configuration for each request:
-
-```typescript
-const results = await stableApiGateway(
-  [
-    { id: 'req-1', requestOptions: { reqData: { path: '/users/1' } } },
-    { id: 'req-2', requestOptions: { reqData: { path: '/users/2' } } },
-    { id: 'req-3', requestOptions: { reqData: { path: '/users/3' } } }
-  ],
-  {
-    // Applied to ALL requests
-    commonRequestData: {
-      hostname: 'api.example.com',
-      headers: { 'Authorization': `Bearer ${token}` }
-    },
-    commonResReq: true,
-    commonAttempts: 5,
-    commonWait: 2000,
-    commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-    commonLogAllErrors: true,
-    
-    // Shared hooks
-    commonHandleErrors: async ({ reqData, errorLog }) => {
-      console.log(`Request to ${reqData.url} failed (${errorLog.attempt})`);
-    },
-    
-    commonResponseAnalyzer: async ({ data }) => {
-      return data?.success === true;
-    }
-  }
-);
-```
-
-## Advanced: Request Grouping
-
-Group related requests with different configurations. Configuration priority:
-
-**Individual Request** > **Group Config** > **Global Common Config**
-
-### Example: Service Tiers
-
-```typescript
-const results = await stableApiGateway(
-  [
-    // Critical services - need high reliability
-    {
-      id: 'auth-check',
-      groupId: 'critical',
-      requestOptions: {
-        reqData: { path: '/auth/verify' },
-        resReq: true
-      }
-    },
-    {
-      id: 'payment-process',
-      groupId: 'critical',
-      requestOptions: {
-        reqData: { path: '/payments/charge' },
-        resReq: true,
-        // Individual override: even MORE attempts for payments
-        attempts: 15
-      }
-    },
-    
-    // Analytics - failures are acceptable
-    {
-      id: 'track-event',
-      groupId: 'analytics',
-      requestOptions: {
-        reqData: { path: '/analytics/track' },
-        resReq: true
-      }
-    }
-  ],
-  {
-    // Global defaults (lowest priority)
-    commonRequestData: {
-      hostname: 'api.example.com'
-    },
-    commonAttempts: 2,
-    commonWait: 500,
-    
-    // Define groups with their own configs
-    requestGroups: [
-      {
-        id: 'critical',
-        commonConfig: {
-          // Critical services: aggressive retries
-          commonAttempts: 10,
-          commonWait: 2000,
-          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-          
-          commonHandleErrors: async ({ errorLog }) => {
-            // Alert on critical failures
-            await pagerDuty.alert('Critical service failure', errorLog);
-          },
-          
-          commonResponseAnalyzer: async ({ data }) => {
-            // Strict validation
-            return data?.status === 'success' && !data?.errors;
-          }
-        }
-      },
-      {
-        id: 'analytics',
-        commonConfig: {
-          // Analytics: minimal retries, don't throw on failure
-          commonAttempts: 1,
-          
-          commonFinalErrorAnalyzer: async () => {
-            return true;  // Suppress errors
-          }
-        }
-      }
-    ]
-  }
-);
-
-// Analyze by group
-const criticalOk = results
-  .filter(r => r.groupId === 'critical')
-  .every(r => r.success);
-
-const analyticsCount = results
-  .filter(r => r.groupId === 'analytics' && r.success)
-  .length;
-
-console.log('Critical services:', criticalOk ? 'HEALTHY' : 'DEGRADED');
-console.log('Analytics events tracked:', analyticsCount);
-```
-
-### Example: Multi-Region Configuration
-
-```typescript
-const results = await stableApiGateway(
-  [
-    { id: 'us-data', groupId: 'us-east', requestOptions: { reqData: { path: '/data' }, resReq: true } },
-    { id: 'eu-data', groupId: 'eu-west', requestOptions: { reqData: { path: '/data' }, resReq: true } },
-    { id: 'ap-data', groupId: 'ap-southeast', requestOptions: { reqData: { path: '/data' }, resReq: true } }
-  ],
-  {
-    commonAttempts: 3,
-    
-    requestGroups: [
-      {
-        id: 'us-east',
-        commonConfig: {
-          commonRequestData: {
-            hostname: 'api-us.example.com',
-            timeout: 5000,  // Low latency expected
-            headers: { 'X-Region': 'us-east-1' }
-          },
-          commonAttempts: 3
-        }
-      },
-      {
-        id: 'eu-west',
-        commonConfig: {
-          commonRequestData: {
-            hostname: 'api-eu.example.com',
-            timeout: 8000,  // Medium latency
-            headers: { 'X-Region': 'eu-west-1' }
-          },
-          commonAttempts: 5
-        }
-      },
-      {
-        id: 'ap-southeast',
-        commonConfig: {
-          commonRequestData: {
-            hostname: 'api-ap.example.com',
-            timeout: 12000,  // Higher latency expected
-            headers: { 'X-Region': 'ap-southeast-1' }
-          },
-          commonAttempts: 7,
-          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
-        }
-      }
-    ]
-  }
-);
-```
-
-### Example: Shared Buffer is common across the entire batch of requests
-
-```typescript
-const sharedBuffer: Record<string, any> = {};
-
-const requests = [
-  {
-    id: 'a',
-    requestOptions: {
-      reqData: { path: '/a' },
-      resReq: true,
-      preExecution: {
-        preExecutionHook: ({ commonBuffer }: any) => {
-          commonBuffer.fromA = true;
-          return {};
-        },
-        preExecutionHookParams: {},
-        applyPreExecutionConfigOverride: false,
-        continueOnPreExecutionHookFailure: false
-      }
-    }
-  },
-  {
-    id: 'b',
-    requestOptions: {
-      reqData: { path: '/b' },
-      resReq: true,
-      preExecution: {
-        preExecutionHook: ({ commonBuffer }: any) => {
-          commonBuffer.fromB = true;
-          return {};
-        },
-        preExecutionHookParams: {},
-        applyPreExecutionConfigOverride: false,
-        continueOnPreExecutionHookFailure: false
-      }
-    }
-  }
-] satisfies API_GATEWAY_REQUEST[];
-
-const results = await stableApiGateway(requests, {
-  concurrentExecution: true,
-  commonRequestData: { hostname: 'api.example.com' },
-  sharedBuffer
-});
-
-console.log(sharedBuffer); // { fromA: true, fromB: true }
-```
-
-
-## Multi-Phase Workflows
-
-For complex operations that require multiple stages of execution, use `stableWorkflow` to orchestrate phase-based workflows with full control over execution order and error handling.
-
-### Basic Workflow
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-
-const workflow = await stableWorkflow(
-  [
-    {
-      id: 'validation',
-      concurrentExecution: true,
-      requests: [
-        {
-          id: 'check-inventory',
-          requestOptions: {
-            reqData: { path: '/inventory/check' },
-            resReq: true
-          }
-        },
-        {
-          id: 'validate-payment',
-          requestOptions: {
-            reqData: { path: '/payment/validate' },
-            resReq: true
-          }
-        }
-      ]
-    },
-    {
-      id: 'processing',
-      concurrentExecution: false,
-      stopOnFirstError: true,
-      requests: [
-        {
-          id: 'charge-payment',
-          requestOptions: {
-            reqData: { path: '/payment/charge', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        },
-        {
-          id: 'reserve-inventory',
-          requestOptions: {
-            reqData: { path: '/inventory/reserve', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        }
-      ]
-    }
-  ],
-  {
-    workflowId: 'order-processing-123',
-    stopOnFirstPhaseError: true,
-    logPhaseResults: true,
-    commonRequestData: {
-      hostname: 'api.example.com',
-      headers: { 'X-Transaction-Id': 'txn-123' }
-    },
-    commonAttempts: 3,
-    commonWait: 1000
-  }
-);
-
-console.log('Workflow completed:', workflow.success);
-console.log(`${workflow.successfulRequests}/${workflow.totalRequests} requests succeeded`);
-console.log(`Completed in ${workflow.executionTime}ms`);
-```
-
-**Workflow Result:**
-```typescript
-interface STABLE_WORKFLOW_RESULT {
-  workflowId: string;           // Workflow identifier
-  success: boolean;             // Did all phases succeed?
-  executionTime: number;        // Total workflow duration (ms)
-  timestamp: string;            // ISO timestamp
-  totalPhases: number;          // Number of phases defined
-  completedPhases: number;      // Number of phases executed
-  totalRequests: number;        // Total requests across all phases
-  successfulRequests: number;   // Successful requests
-  failedRequests: number;       // Failed requests
-  phases: PHASE_RESULT[];       // Detailed results per phase
-  error?: string;               // Workflow-level error (if any)
-}
-```
-
-### Phase Configuration
-
-Each phase can have its own execution mode and error handling, and can also work upon the shared buffer:
-
-```typescript
-{
-  id: 'phase-name',                    // Optional: phase identifier
-  concurrentExecution?: boolean,       // true = parallel, false = sequential
-  stopOnFirstError?: boolean,          // Stop phase on first request failure
-  commonConfig?: { /* phase-level common config */ },
-  requests: [/* array of requests */],
-  sharedBuffer?: Record<string, any> // State to be shared among all requests in the phase
-}
-```
-
-**Configuration Priority:**
-Individual Request > Phase Common Config > Workflow Common Config
-
-### Workflow with Request Groups
-
-Combine workflows with request groups for fine-grained control:
-
-```typescript
-const workflow = await stableWorkflow(
-  [
-    {
-      id: 'critical-validation',
-      concurrentExecution: true,
-      requests: [
-        {
-          id: 'auth-check',
-          groupId: 'critical',
-          requestOptions: {
-            reqData: { path: '/auth/verify' },
-            resReq: true
-          }
-        },
-        {
-          id: 'rate-limit-check',
-          groupId: 'critical',
-          requestOptions: {
-            reqData: { path: '/ratelimit/check' },
-            resReq: true
-          }
-        }
-      ]
-    },
-    {
-      id: 'data-processing',
-      concurrentExecution: false,
-      commonConfig: {
-        // Phase-specific overrides
-        commonAttempts: 5,
-        commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
-      },
-      requests: [
-        {
-          id: 'process-data',
-          groupId: 'standard',
-          requestOptions: {
-            reqData: { path: '/data/process', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        },
-        {
-          id: 'store-result',
-          groupId: 'standard',
-          requestOptions: {
-            reqData: { path: '/data/store', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        }
-      ]
-    },
-    {
-      id: 'notifications',
-      concurrentExecution: true,
-      requests: [
-        {
-          id: 'email-notification',
-          groupId: 'optional',
-          requestOptions: {
-            reqData: { path: '/notify/email' },
-            resReq: true
-          }
-        },
-        {
-          id: 'webhook-notification',
-          groupId: 'optional',
-          requestOptions: {
-            reqData: { path: '/notify/webhook' },
-            resReq: true
-          }
-        }
-      ]
-    }
-  ],
-  {
-    workflowId: 'data-pipeline-workflow',
-    stopOnFirstPhaseError: true,
-    logPhaseResults: true,
-    
-    commonRequestData: {
-      hostname: 'api.example.com'
-    },
-    commonAttempts: 3,
-    commonWait: 1000,
-    
-    // Request groups with different reliability requirements
-    requestGroups: [
-      {
-        id: 'critical',
-        commonConfig: {
-          commonAttempts: 10,
-          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-          commonWait: 2000,
-          commonHandleErrors: async ({ errorLog }) => {
-            await alerting.critical('Critical service failure', errorLog);
-          }
-        }
-      },
-      {
-        id: 'standard',
-        commonConfig: {
-          commonAttempts: 5,
-          commonRetryStrategy: RETRY_STRATEGIES.LINEAR,
-          commonWait: 1000
-        }
-      },
-      {
-        id: 'optional',
-        commonConfig: {
-          commonAttempts: 2,
-          commonFinalErrorAnalyzer: async () => true  // Suppress errors
-        }
-      }
-    ]
-  }
-);
-```
-
-### Phase Observability Hooks
-
-Monitor workflow execution with phase-level hooks:
-
-```typescript
-const workflow = await stableWorkflow(
-  [
-    // ...phases...
-  ],
-  {
-    workflowId: 'monitored-workflow',
-    
-    // Called after each phase completes successfully
-    handlePhaseCompletion: async ({ workflowId, phaseResult, sharedBuffer }) => {
-      console.log(`Phase ${phaseResult.phaseId} completed`);
-      
-      await analytics.track('workflow_phase_complete', {
-        workflowId,
-        phaseId: phaseResult.phaseId,
-        duration: phaseResult.executionTime,
-        successRate: phaseResult.successfulRequests / phaseResult.totalRequests
-      });
-    },
-    
-    // Called when a phase fails
-    handlePhaseError: async ({ workflowId, phaseResult, error, sharedBuffer }) => {
-      console.error(`Phase ${phaseResult.phaseId} failed`);
-      
-      await alerting.notify('workflow_phase_failed', {
-        workflowId,
-        phaseId: phaseResult.phaseId,
-        error: error.message,
-        failedRequests: phaseResult.failedRequests
-      });
-    },
-    
-    logPhaseResults: true  // Enable console logging
-  }
-);
+  commonBuffer
+});
+
+console.log('Token used:', commonBuffer.token);
 ```
 
-### Workflow Buffer
+### Shared Buffer
 
-Workflow Buffer is shared by all phases and by extension, all requests contained in every phase of the workflow :
+Share state across requests in gateways and workflows:
 
 ```typescript
-const workflowBuffer: Record<string, any> = {};
+import { stableWorkflow } from '@emmvish/stable-request';
+
+const sharedBuffer: Record<string, any> = { requestCount: 0 };
 
-const phases = [
+const phases: STABLE_WORKFLOW_PHASE[] = [
   {
-    id: 'p1',
-    concurrentExecution: false,
+    id: 'phase-1',
     requests: [
       {
-        id: 'r1',
+        id: 'req-1',
         requestOptions: {
-          reqData: { path: '/p1' },
+          reqData: { path: '/step1' },
           resReq: true,
           preExecution: {
-            preExecutionHook: ({ commonBuffer }: any) => {
-              commonBuffer.token = 'wf-token';
-              commonBuffer.setIn = 'p1';
+            preExecutionHook: ({ commonBuffer }) => {
+              commonBuffer.requestCount++;
+              commonBuffer.phase1Data = 'initialized';
               return {};
             },
             preExecutionHookParams: {},
@@ -1326,17 +439,18 @@ const phases = [
     ]
   },
   {
-    id: 'p2',
-    concurrentExecution: false,
+    id: 'phase-2',
     requests: [
       {
-        id: 'r2',
+        id: 'req-2',
         requestOptions: {
-          reqData: { path: '/p2' },
+          reqData: { path: '/step2' },
           resReq: true,
           preExecution: {
-            preExecutionHook: ({ commonBuffer }: any) => {
-              commonBuffer.usedIn = 'p2';
+            preExecutionHook: ({ commonBuffer }) => {
+              commonBuffer.requestCount++;
+              // Access data from phase-1
+              console.log('Phase 1 data:', commonBuffer.phase1Data);
               return {};
             },
             preExecutionHookParams: {},
@@ -1347,713 +461,572 @@ const phases = [
       }
     ]
   }
-] satisfies STABLE_WORKFLOW_PHASE[];
+];
 
 const result = await stableWorkflow(phases, {
-  workflowId: 'wf-buffer-demo',
+  workflowId: 'stateful-workflow',
   commonRequestData: { hostname: 'api.example.com' },
-  sharedBuffer: workflowBuffer
+  sharedBuffer
 });
 
-console.log(workflowBuffer); // { token: 'wf-token' setIn: 'p1', usedIn: 'p2' }
+console.log('Total requests processed:', sharedBuffer.requestCount);
 ```
-### Concurrent Execution of Phases
+
+### Request Grouping
+
+Apply different configurations to request groups:
 
 ```typescript
-const phases = [
+import { stableApiGateway } from '@emmvish/stable-request';
+
+const requests = [
   {
-    id: 'phase-1',
-    requests: [
-      { id: 'r1', requestOptions: { reqData: { path: '/p1/r1' }, resReq: true } }
-    ]
+    id: 'critical-1',
+    groupId: 'critical',
+    requestOptions: { reqData: { path: '/critical/1' }, resReq: true }
   },
   {
-    id: 'phase-2',
-    requests: [
-      { id: 'r2', requestOptions: { reqData: { path: '/p2/r1' }, resReq: true } }
-    ]
+    id: 'critical-2',
+    groupId: 'critical',
+    requestOptions: { reqData: { path: '/critical/2' }, resReq: true }
   },
   {
-    id: 'phase-3',
-    requests: [
-      { id: 'r3', requestOptions: { reqData: { path: '/p3/r1' }, resReq: true } }
-    ]
+    id: 'optional-1',
+    groupId: 'optional',
+    requestOptions: { reqData: { path: '/optional/1' }, resReq: true }
   }
-] satisfies STABLE_WORKFLOW_PHASE[];
+];
 
-const result = await stableWorkflow(phases, {
-  workflowId: 'wf-concurrent-phases',
+const results = await stableApiGateway(requests, {
   commonRequestData: { hostname: 'api.example.com' },
   commonAttempts: 1,
-  commonWait: 1,
-  concurrentPhaseExecution: true
-});
-```
-### Mixed Execution of Phases
-
-```typescript
-const workflow = await stableWorkflow(
-  [
-    {
-      id: 'phase-1-sequential',
-      requests: [/* ... */]
-    },
-    {
-      id: 'phase-2-concurrent-start',
-      markConcurrentPhase: true,  // Will run concurrently with phase-3
-      requests: [/* ... */]
-    },
+  commonWait: 100,
+  requestGroups: [
     {
-      id: 'phase-3-concurrent',
-      markConcurrentPhase: true,  // Will run concurrently with phase-2
-      requests: [/* ... */]
+      id: 'critical',
+      commonConfig: {
+        commonAttempts: 5,  // More retries for critical requests
+        commonWait: 2000,
+        commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+      }
     },
     {
-      id: 'phase-4-sequential',
-      requests: [/* ... */]  // Runs after phases 2 & 3 complete
+      id: 'optional',
+      commonConfig: {
+        commonAttempts: 1,  // No retries for optional requests
+        commonFinalErrorAnalyzer: async () => true  // Suppress errors
+      }
     }
-  ],
-  {
-    workflowId: 'mixed-execution-workflow',
-    allowExecutionMixing: true  // Enable mixed execution mode
-  }
-);
+  ]
+});
 ```
 
-## Real-World Examples
+### Concurrency Control
 
-### 1. Polling for Job Completion
+Limit concurrent request execution:
 
 ```typescript
-const jobResult = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/jobs/abc123/status'
-  },
-  resReq: true,
-  attempts: 20,             // Poll up to 20 times
-  wait: 3000,               // Wait 3 seconds between polls
-  retryStrategy: RETRY_STRATEGIES.FIXED,
-  
-  responseAnalyzer: async ({ data }) => {
-    if (data.status === 'completed') {
-      console.log('Job completed!');
-      return true;  // Success
-    }
-    
-    if (data.status === 'failed') {
-      throw new Error(`Job failed: ${data.error}`);
-    }
-    
-    console.log(`Job ${data.status}... ${data.progress}%`);
-    return false;  // Keep polling
-  },
-  
-  handleErrors: async ({ errorLog }) => {
-    console.log(`Poll attempt ${errorLog.attempt}`);
-  }
+import { stableApiGateway } from '@emmvish/stable-request';
+
+// Limit to 5 concurrent requests
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  concurrentExecution: true,
+  maxConcurrentRequests: 5
 });
 
-console.log('Final result:', jobResult);
+// Phase-level concurrency control
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'limited-phase',
+    concurrentExecution: true,
+    maxConcurrentRequests: 3,
+    requests: [/* ... */]
+  }
+];
 ```
 
-### 2. Database Replication Lag
+### Response Analysis
+
+Validate response content and trigger retries:
 
 ```typescript
-const expectedVersion = 42;
+import { stableRequest } from '@emmvish/stable-request';
 
 const data = await stableRequest({
-  reqData: {
-    hostname: 'replica.db.example.com',
-    path: '/records/123'
-  },
+  reqData: { hostname: 'api.example.com', path: '/job/status' },
   resReq: true,
   attempts: 10,
-  wait: 500,
-  retryStrategy: RETRY_STRATEGIES.LINEAR,
-  
-  hookParams: {
-    responseAnalyzerParams: { expectedVersion }
-  },
-  
-  responseAnalyzer: async ({ data, params }) => {
-    // Wait until replica catches up
-    if (data.version >= params.expectedVersion) {
-      return true;
+  wait: 2000,
+  responseAnalyzer: async ({ data, reqData, params }) => {
+    // Retry until job is completed
+    if (data.status === 'processing') {
+      console.log('Job still processing, will retry...');
+      return false;  // Trigger retry
     }
-    
-    console.log(`Replica at version ${data.version}, waiting for ${params.expectedVersion}`);
-    return false;
+    return data.status === 'completed';
   }
 });
+
+console.log('Job completed:', data);
 ```
 
-### 3. Idempotent Payment Processing
+### Error Handling
+
+Comprehensive error handling with observability hooks:
 
 ```typescript
-const paymentResult = await stableRequest({
-  reqData: {
-    hostname: 'api.stripe.com',
-    path: '/v1/charges',
-    method: REQUEST_METHODS.POST,
-    headers: {
-      'Authorization': 'Bearer sk_...',
-      'Idempotency-Key': crypto.randomUUID()  // Ensure idempotency
-    },
-    body: {
-      amount: 1000,
-      currency: 'usd',
-      source: 'tok_visa'
-    }
-  },
+import { stableRequest } from '@emmvish/stable-request';
+
+const data = await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
   resReq: true,
-  attempts: 5,
-  wait: 2000,
-  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-  
+  attempts: 3,
+  wait: 1000,
   logAllErrors: true,
-  logAllSuccessfulAttempts: true,
-  
-  handleErrors: async ({ errorLog }) => {
-    await paymentLogger.error({
+  handleErrors: ({ reqData, errorLog, params }) => {
+    // Custom error logging
+    console.error('Request failed:', {
+      url: reqData.url,
       attempt: errorLog.attempt,
+      statusCode: errorLog.statusCode,
       error: errorLog.error,
       isRetryable: errorLog.isRetryable
     });
+    
+    // Send to monitoring service
+    monitoringService.trackError(errorLog);
   },
-  
-  responseAnalyzer: async ({ data }) => {
-    // Validate payment succeeded
-    return data.status === 'succeeded' && data.paid === true;
+  logAllSuccessfulAttempts: true,
+  handleSuccessfulAttemptData: ({ successfulAttemptData }) => {
+    console.log('Request succeeded on attempt:', successfulAttemptData.attempt);
   },
-  
-  finalErrorAnalyzer: async ({ error }) => {
-    // Alert team on payment failure
-    await alerting.critical('Payment processing failed', error);
+  finalErrorAnalyzer: async ({ error, reqData }) => {
+    // Gracefully handle specific errors
+    if (error.response?.status === 404) {
+      console.warn('Resource not found, continuing...');
+      return true;  // Return false to suppress error
+    }
     return false;  // Throw error
   }
 });
 ```
 
-### 4. Batch User Creation with Error Handling
-
-```typescript
-const users = [
-  { name: 'Alice', email: 'alice@example.com' },
-  { name: 'Bob', email: 'bob@example.com' },
-  { name: 'Charlie', email: 'charlie@example.com' }
-];
-
-const requests = users.map((user, index) => ({
-  id: `user-${index}`,
-  requestOptions: {
-    reqData: {
-      body: user
-    },
-    resReq: true
-  }
-}));
-
-const results = await stableApiGateway(requests, {
-  concurrentExecution: true,
-  
-  commonRequestData: {
-    hostname: 'api.example.com',
-    path: '/users',
-    method: REQUEST_METHODS.POST,
-    headers: {
-      'Content-Type': 'application/json'
-    }
-  },
-  
-  commonAttempts: 3,
-  commonWait: 1000,
-  commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-  commonResReq: true,
-  commonLogAllErrors: true,
-  
-  commonHandleErrors: async ({ reqData, errorLog }) => {
-    const user = reqData.data;
-    console.error(`Failed to create user ${user.name}: ${errorLog.error}`);
-  },
-  
-  commonResponseAnalyzer: async ({ data }) => {
-    // Ensure user was created with an ID
-    return data?.id && data?.email;
-  }
-});
-
-const successful = results.filter(r => r.success);
-const failed = results.filter(r => !r.success);
-
-console.log(`✓ Created ${successful.length} users`);
-console.log(`✗ Failed to create ${failed.length} users`);
-
-failed.forEach(r => {
-  console.error(`  - ${r.requestId}: ${r.error}`);
-});
-```
+## Advanced Use Cases
 
-### 5. Health Check Monitoring System
+### Use Case 1: Multi-Tenant API with Dynamic Authentication
 
 ```typescript
-const healthChecks = await stableApiGateway(
-  [
-    // Core services - must be healthy
-    { id: 'auth', groupId: 'core', requestOptions: { reqData: { hostname: 'auth.internal', path: '/health' } } },
-    { id: 'database', groupId: 'core', requestOptions: { reqData: { hostname: 'db.internal', path: '/health' } } },
-    { id: 'api', groupId: 'core', requestOptions: { reqData: { hostname: 'api.internal', path: '/health' } } },
-    
-    // Optional services
-    { id: 'cache', groupId: 'optional', requestOptions: { reqData: { hostname: 'cache.internal', path: '/health' } } },
-    { id: 'search', groupId: 'optional', requestOptions: { reqData: { hostname: 'search.internal', path: '/health' } } }
-  ],
-  {
-    commonResReq: true,
-    concurrentExecution: true,
-    
-    requestGroups: [
-      {
-        id: 'core',
-        commonConfig: {
-          commonAttempts: 5,
-          commonWait: 2000,
-          commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-          
-          commonResponseAnalyzer: async ({ data }) => {
-            // Core services need strict validation
-            return data?.status === 'healthy' && 
-                   data?.uptime > 0 &&
-                   data?.dependencies?.every(d => d.healthy);
-          },
-          
-          commonHandleErrors: async ({ reqData, errorLog }) => {
-            // Alert on core service issues
-            await pagerDuty.trigger({
-              severity: 'critical',
-              service: reqData.baseURL,
-              message: errorLog.error
-            });
-          }
-        }
-      },
-      {
-        id: 'optional',
-        commonConfig: {
-          commonAttempts: 2,
-          
-          commonResponseAnalyzer: async ({ data }) => {
-            // Optional services: basic check
-            return data?.status === 'ok';
-          },
-          
-          commonFinalErrorAnalyzer: async ({ reqData, error }) => {
-            // Log but don't alert
-            console.warn(`Optional service ${reqData.baseURL} unhealthy`);
-            return true;  // Don't throw
-          }
-        }
-      }
-    ]
-  }
-);
+import { stableWorkflow, RETRY_STRATEGIES } from '@emmvish/stable-request';
 
-const report = {
-  timestamp: new Date().toISOString(),
-  core: healthChecks.filter(r => r.groupId === 'core').every(r => r.success),
-  optional: healthChecks.filter(r => r.groupId === 'optional').every(r => r.success),
-  overall: healthChecks.every(r => r.success) ? 'HEALTHY' : 'DEGRADED'
-};
-
-console.log('System Health:', report);
-```
+interface TenantConfig {
+  tenantId: string;
+  apiKey: string;
+  baseUrl: string;
+}
 
-### 6. Data Pipeline (ETL Workflow)
+async function executeTenantWorkflow(tenantConfig: TenantConfig) {
+  const sharedBuffer: Record<string, any> = {
+    tenantId: tenantConfig.tenantId,
+    authToken: null,
+    processedItems: []
+  };
 
-```typescript
-const etlWorkflow = await stableWorkflow(
-  [
+  const phases: STABLE_WORKFLOW_PHASE[] = [
     {
-      id: 'extract',
-      concurrentExecution: true,
-      commonConfig: {
-        commonAttempts: 5,
-        commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL
-      },
+      id: 'authentication',
       requests: [
-        { id: 'extract-users', requestOptions: { reqData: { path: '/extract/users' }, resReq: true } },
-        { id: 'extract-orders', requestOptions: { reqData: { path: '/extract/orders' }, resReq: true } },
-        { id: 'extract-products', requestOptions: { reqData: { path: '/extract/products' }, resReq: true } }
+        {
+          id: 'get-token',
+          requestOptions: {
+            reqData: {
+              path: '/auth/token',
+              method: 'POST',
+              headers: { 'X-API-Key': tenantConfig.apiKey }
+            },
+            resReq: true,
+            attempts: 3,
+            wait: 2000,
+            retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+            responseAnalyzer: async ({ data, commonBuffer }) => {
+              if (data?.token) {
+                commonBuffer.authToken = data.token;
+                commonBuffer.tokenExpiry = Date.now() + (data.expiresIn * 1000);
+                return true;
+              }
+              return false;
+            }
+          }
+        }
       ]
     },
     {
-      id: 'transform',
-      concurrentExecution: false,
-      stopOnFirstError: true,
+      id: 'data-fetching',
+      concurrentExecution: true,
+      maxConcurrentRequests: 5,
       requests: [
         {
-          id: 'clean-data',
-          requestOptions: {
-            reqData: { path: '/transform/clean', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        },
-        {
-          id: 'enrich-data',
+          id: 'fetch-users',
           requestOptions: {
-            reqData: { path: '/transform/enrich', method: REQUEST_METHODS.POST },
-            resReq: true
+            reqData: { path: '/users' },
+            resReq: true,
+            preExecution: {
+              preExecutionHook: ({ commonBuffer }) => ({
+                reqData: {
+                  path: '/users',
+                  headers: { Authorization: `Bearer ${commonBuffer.authToken}` }
+                }
+              }),
+              applyPreExecutionConfigOverride: true
+            }
           }
         },
         {
-          id: 'validate-data',
+          id: 'fetch-settings',
           requestOptions: {
-            reqData: { path: '/transform/validate', method: REQUEST_METHODS.POST },
+            reqData: { path: '/settings' },
             resReq: true,
-            responseAnalyzer: async ({ data }) => {
-              return data?.validationErrors?.length === 0;
+            preExecution: {
+              preExecutionHook: ({ commonBuffer }) => ({
+                reqData: {
+                  path: '/settings',
+                  headers: { Authorization: `Bearer ${commonBuffer.authToken}` }
+                }
+              }),
+              applyPreExecutionConfigOverride: true
             }
           }
         }
       ]
     },
     {
-      id: 'load',
+      id: 'data-processing',
       concurrentExecution: true,
       requests: [
         {
-          id: 'load-warehouse',
-          requestOptions: {
-            reqData: { path: '/load/warehouse', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        },
-        {
-          id: 'update-indexes',
+          id: 'process-users',
           requestOptions: {
-            reqData: { path: '/load/indexes', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        },
-        {
-          id: 'refresh-cache',
-          requestOptions: {
-            reqData: { path: '/cache/refresh', method: REQUEST_METHODS.POST },
-            resReq: true
+            reqData: { path: '/process/users', method: 'POST' },
+            resReq: true,
+            preExecution: {
+              preExecutionHook: ({ commonBuffer }) => {
+                const usersPhase = commonBuffer.phases?.find(p => p.phaseId === 'data-fetching');
+                const usersData = usersPhase?.responses?.find(r => r.requestId === 'fetch-users')?.data;
+                
+                return {
+                  reqData: {
+                    path: '/process/users',
+                    method: 'POST',
+                    headers: { Authorization: `Bearer ${commonBuffer.authToken}` },
+                    body: { users: usersData }
+                  }
+                };
+              },
+              applyPreExecutionConfigOverride: true
+            },
+            responseAnalyzer: async ({ data, commonBuffer }) => {
+              if (data?.processed) {
+                commonBuffer.processedItems.push(...data.processed);
+                return true;
+              }
+              return false;
+            }
           }
         }
       ]
     }
-  ],
-  {
-    workflowId: `etl-${new Date().toISOString()}`,
+  ];
+
+  const result = await stableWorkflow(phases, {
+    workflowId: `tenant-${tenantConfig.tenantId}-workflow`,
+    commonRequestData: {
+      hostname: tenantConfig.baseUrl,
+      headers: { 'X-Tenant-ID': tenantConfig.tenantId }
+    },
     stopOnFirstPhaseError: true,
     logPhaseResults: true,
-    
-    commonRequestData: {
-      hostname: 'pipeline.example.com'
+    sharedBuffer,
+    circuitBreaker: {
+      failureThresholdPercentage: 40,
+      minimumRequests: 5,
+      recoveryTimeoutMs: 30000
     },
-    commonAttempts: 3,
-    commonRetryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-    
-    handlePhaseCompletion: async ({ phaseResult }) => {
-      const recordsProcessed = phaseResult.responses
-        .filter(r => r.success)
-        .reduce((sum, r) => sum + (r.data?.recordCount || 0), 0);
-      
-      await metrics.gauge('etl.phase.records', recordsProcessed, {
-        phase: phaseResult.phaseId
-      });
+    rateLimit: {
+      maxRequests: 20,
+      windowMs: 1000
     },
-    
-    handlePhaseError: async ({ phaseResult, error }) => {
-      await pagerDuty.alert('ETL Pipeline Phase Failed', {
-        phase: phaseResult.phaseId,
-        error: error.message,
-        failedRequests: phaseResult.failedRequests
+    commonCache: {
+      enabled: true,
+      ttl: 300000  // Cache for 5 minutes
+    },
+    handlePhaseCompletion: ({ workflowId, phaseResult }) => {
+      console.log(`[${workflowId}] Phase ${phaseResult.phaseId} completed:`, {
+        success: phaseResult.success,
+        successfulRequests: phaseResult.successfulRequests,
+        executionTime: `${phaseResult.executionTime}ms`
       });
+    },
+    handlePhaseError: ({ workflowId, error, phaseResult }) => {
+      console.error(`[${workflowId}] Phase ${phaseResult.phaseId} failed:`, error);
+      // Send to monitoring
+      monitoringService.trackPhaseError(workflowId, phaseResult.phaseId, error);
     }
-  }
-);
+  });
 
-console.log(`ETL Pipeline: ${etlWorkflow.success ? 'SUCCESS' : 'FAILED'}`);
-console.log(`Total time: ${etlWorkflow.executionTime}ms`);
-console.log(`Records processed: ${etlWorkflow.successfulRequests}/${etlWorkflow.totalRequests}`);
-```
+  return {
+    success: result.success,
+    tenantId: tenantConfig.tenantId,
+    processedItems: sharedBuffer.processedItems,
+    executionTime: result.executionTime,
+    phases: result.phases.map(p => ({
+      id: p.phaseId,
+      success: p.success,
+      requestCount: p.totalRequests
+    }))
+  };
+}
 
-## Complete API Reference
-
-### `stableRequest(options)`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `reqData` | `REQUEST_DATA` | **required** | Request configuration |
-| `resReq` | `boolean` | `false` | Return response data vs. just boolean |
-| `attempts` | `number` | `1` | Max retry attempts |
-| `wait` | `number` | `1000` | Base delay between retries (ms) |
-| `maxAllowedWait` | `number` | `60000` | Maximum permitted wait duration between retries (ms) |
-| `retryStrategy` | `RETRY_STRATEGY_TYPES` | `'fixed'` | Retry backoff strategy |
-| `performAllAttempts` | `boolean` | `false` | Execute all attempts regardless |
-| `logAllErrors` | `boolean` | `false` | Enable error logging |
-| `logAllSuccessfulAttempts` | `boolean` | `false` | Enable success logging |
-| `maxSerializableChars` | `number` | `1000` | Max chars for logs |
-| `trialMode` | `TRIAL_MODE_OPTIONS` | `{ enabled: false }` | Failure simulation |
-| `hookParams` | `HookParams` | `{}` | Custom parameters for hooks |
-| `preExecution` | `RequestPreExecutionOptions` | `{}` | Executes before actually sending request, can modify request config |
-| `commonBuffer` | `Record<string, any>` | `{}` | For communication between various request hooks |
-| `responseAnalyzer` | `function` | `() => true` | Validate response content |
-| `handleErrors` | `function` | `console.log` | Error handler |
-| `handleSuccessfulAttemptData` | `function` | `console.log` | Success handler |
-| `finalErrorAnalyzer` | `function` | `() => false` | Final error handler |
-
-### REQUEST_DATA
+// Execute workflows for multiple tenants
+const tenants: TenantConfig[] = [
+  { tenantId: 'tenant-1', apiKey: 'key1', baseUrl: 'api.tenant1.com' },
+  { tenantId: 'tenant-2', apiKey: 'key2', baseUrl: 'api.tenant2.com' }
+];
 
-```typescript
-interface REQUEST_DATA<RequestDataType = any> {
-  hostname: string;                    // Required
-  protocol?: 'http' | 'https';         // Default: 'https'
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; // Default: 'GET'
-  path?: `/${string}`;                 // Default: ''
-  port?: number;                       // Default: 443
-  headers?: Record<string, any>;       // Default: {}
-  body?: RequestDataType;              // Request body
-  query?: Record<string, any>;         // Query parameters
-  timeout?: number;                    // Default: 15000ms
-  signal?: AbortSignal;                // For cancellation
-}
+const results = await Promise.all(tenants.map(executeTenantWorkflow));
+results.forEach(result => {
+  console.log(`Tenant ${result.tenantId}:`, result.success ? 'Success' : 'Failed');
+});
 ```
 
-### `stableApiGateway(requests, options)`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `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 |
-| `commonMaxAllowedWait` | `number` | `60000` | Default maximum permitted wait time for all requests |
-| `commonRetryStrategy` | `RETRY_STRATEGY_TYPES` | `'fixed'` | Default retry strategy for all requests |
-| `commonLogAllErrors` | `boolean` | `false` | Default error logging for all requests |
-| `commonLogAllSuccessfulAttempts` | `boolean` | `false` | Default success logging for all requests |
-| `commonMaxSerializableChars` | `number` | `1000` | Default max chars for serialization |
-| `commonTrialMode` | `TRIAL_MODE_OPTIONS` | `{ enabled: false }` | Default trial mode for all requests |
-| `commonResponseAnalyzer` | `function` | `() => true` | Default response analyzer for all requests |
-| `commonResReq` | `boolean` | `false` | Default resReq for all requests |
-| `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 request options for each request |
-| `commonHookParams` | `HookParams` | `{ }` | Common options for each request hook |
-| `sharedBuffer` | `Record<string, any>` | `undefined` | For communication between various requests |
-
-### `stableWorkflow(phases, options)`
-
-Execute a multi-phase workflow with full control over execution order and error handling.
-
-**Phases Array:**
-```typescript
-interface STABLE_WORKFLOW_PHASE {
-  id?: string;                     // Phase identifier (auto-generated if omitted)
-  concurrentExecution?: boolean;   // true = parallel, false = sequential (default: true)
-  stopOnFirstError?: boolean;      // Stop phase on first request failure (default: false)
-  commonConfig?: Omit<API_GATEWAY_OPTIONS; 'concurrentExecution' | 'stopOnFirstError' | 'requestGroups'>;
-  requests: API_GATEWAY_REQUEST[]; // Array of requests for this phase
-  markConcurrentPhase?: boolean; // Allows this phase to be executed concurrently with immediately next phase marked as concurrent
-}
-```
+### Use Case 2: Resilient Data Pipeline with Fallback Strategies
 
-**Workflow Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `workflowId` | `string` | `workflow-{timestamp}` | Workflow identifier |
-| `stopOnFirstPhaseError` | `boolean` | `false` | Stop workflow if any phase fails |
-| `logPhaseResults` | `boolean` | `false` | Log phase execution to console |
-| `concurrentPhaseExecution` | `boolean` | `false` | Execute all phases in parallel. Overrides `enableMixedExecution` |
-| `handlePhaseCompletion` | `function` | `undefined` | Hook called after each successful phase |
-| `handlePhaseError` | `function` | `undefined` | Hook called when a phase fails |
-| `maxSerializableChars` | `number` | `1000` | Max chars for serialization in hooks |
-| `workflowHookParams` | `WorkflowHookParams` | {} | Custom set of params passed to hooks |
-| `sharedBuffer` | `Record<string, any>` | `undefined` | Buffer shared by all phases and all requests within them |
-| `enableMixedExecution` | `boolean` | `false` | Enables mixing of sequential and parallel sub-workflows |
-| All `stableApiGateway` options | - | - | Applied as workflow-level defaults |
-
-**STABLE_WORKFLOW_RESULT response:**
 ```typescript
-interface STABLE_WORKFLOW_RESULT {
-  workflowId: string;
-  success: boolean;             // All phases successful?
-  executionTime: number;        // Total workflow duration (ms)
-  timestamp: string;            // ISO timestamp
-  totalPhases: number;
-  completedPhases: number;
-  totalRequests: number;
-  successfulRequests: number;
-  failedRequests: number;
-  phases: PHASE_RESULT[];      // Detailed results per phase
-  error?: string;              // Workflow-level error
-}
-```
+import { stableApiGateway, RETRY_STRATEGIES, CircuitBreaker } from '@emmvish/stable-request';
 
-### Hooks Reference
+interface DataSource {
+  id: string;
+  priority: number;
+  endpoint: string;
+  hostname: string;
+}
 
-#### preExecutionHook
+async function fetchDataWithFallback(dataSources: DataSource[]) {
+  // Sort by priority
+  const sortedSources = [...dataSources].sort((a, b) => a.priority - b.priority);
+  
+  // Create circuit breakers for each source
+  const circuitBreakers = new Map(
+    sortedSources.map(source => [
+      source.id,
+      new CircuitBreaker({
+        failureThresholdPercentage: 50,
+        minimumRequests: 3,
+        recoveryTimeoutMs: 60000
+      })
+    ])
+  );
+
+  // Try each data source in priority order
+  for (const source of sortedSources) {
+    const breaker = circuitBreakers.get(source.id)!;
+    const breakerState = breaker.getState();
+    
+    // Skip if circuit is open
+    if (breakerState.state === 'OPEN') {
+      console.warn(`Circuit breaker open for ${source.id}, skipping...`);
+      continue;
+    }
 
-**Purpose:** Dynamically configure request before execution
+    console.log(`Attempting to fetch from ${source.id}...`);
 
-```typescript
-preExecution: {
-  preExecutionHook: async ({ inputParams, commonBuffer }) => {
-    // Fetch dynamic data
-    const token = await getAuthToken();
-    
-    // Store in common buffer
-    commonBuffer.token = token;
-    commonBuffer.timestamp = Date.now();
-    
-    // Return config overrides
-    return {
-      reqData: {
-        headers: { 'Authorization': `Bearer ${token}` }
-      },
-      attempts: 5
-    };
-  },
-  preExecutionHookParams: { userId: 'user-123' },
-  applyPreExecutionConfigOverride: true,
-  continueOnPreExecutionHookFailure: false
-}
-```
+    try {
+      const requests = [
+        {
+          id: 'users',
+          requestOptions: {
+            reqData: { path: `${source.endpoint}/users` },
+            resReq: true,
+            attempts: 3,
+            wait: 1000,
+            retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+          }
+        },
+        {
+          id: 'products',
+          requestOptions: {
+            reqData: { path: `${source.endpoint}/products` },
+            resReq: true,
+            attempts: 3,
+            wait: 1000,
+            retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+          }
+        },
+        {
+          id: 'orders',
+          requestOptions: {
+            reqData: { path: `${source.endpoint}/orders` },
+            resReq: true,
+            attempts: 3,
+            wait: 1000,
+            retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+          }
+        }
+      ];
 
-#### responseAnalyzer
+      const results = await stableApiGateway(requests, {
+        commonRequestData: {
+          hostname: source.hostname,
+          headers: { 'X-Source-ID': source.id }
+        },
+        concurrentExecution: true,
+        maxConcurrentRequests: 10,
+        circuitBreaker: breaker,
+        rateLimit: {
+          maxRequests: 50,
+          windowMs: 1000
+        },
+        commonCache: {
+          enabled: true,
+          ttl: 60000
+        },
+        commonResponseAnalyzer: async ({ data }) => {
+          // Validate data structure
+          return data && typeof data === 'object' && !data.error;
+        },
+        commonHandleErrors: ({ errorLog }) => {
+          console.error(`Error from ${source.id}:`, errorLog);
+        }
+      });
 
-**Purpose:** Validate response content, retry even on HTTP 200
+      // Check if all requests succeeded
+      const allSuccessful = results.every(r => r.success);
+      
+      if (allSuccessful) {
+        console.log(`Successfully fetched data from ${source.id}`);
+        return {
+          source: source.id,
+          data: {
+            users: results.find(r => r.requestId === 'users')?.data,
+            products: results.find(r => r.requestId === 'products')?.data,
+            orders: results.find(r => r.requestId === 'orders')?.data
+          }
+        };
+      } else {
+        console.warn(`Partial failure from ${source.id}, trying next source...`);
+      }
+    } catch (error) {
+      console.error(`Failed to fetch from ${source.id}:`, error);
+      // Continue to next source
+    }
+  }
 
-```typescript
-responseAnalyzer: async ({ reqData, data, trialMode, params, commonBuffer }) => {
-  // Return true if valid, false to retry
-  return data.status === 'ready';
+  throw new Error('All data sources failed');
 }
+
+// Usage
+const dataSources: DataSource[] = [
+  {
+    id: 'primary-db',
+    priority: 1,
+    endpoint: '/api/v1',
+    hostname: 'primary.example.com'
+  },
+  {
+    id: 'replica-db',
+    priority: 2,
+    endpoint: '/api/v1',
+    hostname: 'replica.example.com'
+  },
+  {
+    id: 'backup-cache',
+    priority: 3,
+    endpoint: '/cached',
+    hostname: 'cache.example.com'
+  }
+];
+
+const result = await fetchDataWithFallback(dataSources);
+console.log('Data fetched from:', result.source);
+console.log('Users:', result.data.users?.length);
+console.log('Products:', result.data.products?.length);
+console.log('Orders:', result.data.orders?.length);
 ```
 
-#### handleErrors
+## Configuration Options
 
-**Purpose:** Monitor and log failed attempts
+### Request Data Configuration
 
 ```typescript
-handleErrors: async ({ reqData, errorLog, maxSerializableChars, params, commonBuffer }) => {
-  await logger.error({
-    url: reqData.url,
-    attempt: errorLog.attempt,
-    error: errorLog.error
-  });
+interface REQUEST_DATA<RequestDataType> {
+  hostname: string;
+  protocol?: 'http' | 'https';  // default: 'https'
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';  // default: 'GET'
+  path?: `/${string}`;
+  port?: number;  // default: 443
+  headers?: Record<string, any>;
+  body?: RequestDataType;
+  query?: Record<string, any>;
+  timeout?: number;  // default: 15000ms
+  signal?: AbortSignal;
 }
 ```
 
-#### handleSuccessfulAttemptData
-
-**Purpose:** Monitor and log successful attempts
+### Retry Configuration
 
 ```typescript
-handleSuccessfulAttemptData: async ({ reqData, successfulAttemptData, maxSerializableChars, params, commonBuffer }) => {
-  await analytics.track({
-    url: reqData.url,
-    duration: successfulAttemptData.executionTime
-  });
+interface RetryConfig {
+  attempts?: number;  // default: 1
+  wait?: number;  // default: 1000ms
+  maxAllowedWait?: number;  // default: 60000ms
+  retryStrategy?: 'fixed' | 'linear' | 'exponential';  // default: 'fixed'
+  performAllAttempts?: boolean;  // default: false
 }
 ```
 
-#### finalErrorAnalyzer
-
-**Purpose:** Handle final error after all retries exhausted
+### Circuit Breaker Configuration
 
 ```typescript
-finalErrorAnalyzer: async ({ reqData, error, trialMode, params, commonBuffer }) => {
-  // Return true to suppress error (return false)
-  // Return false to throw error
-  if (error.message.includes('404')) {
-    return true;  // Treat as non-critical
-  }
-  return false;  // Throw
+interface CircuitBreakerConfig {
+  failureThresholdPercentage: number;  // 0-100
+  minimumRequests: number;
+  recoveryTimeoutMs: number;
+  trackIndividualAttempts?: boolean;  // default: false
 }
 ```
 
-#### handlePhaseCompletion
-
-**Purpose:** Execute phase-bridging code upon successful completion of a phase
+### Rate Limit Configuration
 
 ```typescript
-handlePhaseCompletion: async ({ workflowId, phaseResult, maxSerializableChars, params, sharedBuffer }) => {
-  await logger.log(phaseResult.phaseId, phaseResult.success);
+interface RateLimitConfig {
+  maxRequests: number;
+  windowMs: number;
 }
 ```
 
-#### handlePhaseError
-
-**Purpose:** Execute error handling code if a phase runs into an error
+### Cache Configuration
 
 ```typescript
-handlePhaseError: async ({ workflowId, phaseResult, error, maxSerializableChars, params, sharedBuffer }) => {
-  await logger.error(error);
+interface CacheConfig {
+  enabled: boolean;
+  ttl?: number;  // milliseconds, default: 300000 (5 minutes)
 }
 ```
 
-## Configuration Hierarchy
-
-Configuration precedence across orchestration:
-
-- Workflow-level (options.sharedBuffer)
-- Phase-level (commonConfig)
-- Request group (requestGroups[].commonConfig)
-- Individual request options (highest priority)
-
-Buffers are state (not config):
-
-- Request scope: commonBuffer
-- Gateway scope: Gateway's / Phase's sharedBuffer
-- Workflow scope: Workflow's sharedBuffer
-
-## TypeScript Support
-
-Fully typed with generics:
+### Pre-Execution Configuration
 
 ```typescript
-interface CreateUserRequest {
-  name: string;
-  email: string;
-}
-
-interface UserResponse {
-  id: string;
-  name: string;
-  email: string;
-  createdAt: string;
+interface RequestPreExecutionOptions {
+  preExecutionHook: (options: PreExecutionHookOptions) => any | Promise<any>;
+  preExecutionHookParams?: any;
+  applyPreExecutionConfigOverride?: boolean;  // default: false
+  continueOnPreExecutionHookFailure?: boolean;  // default: false
 }
-
-const user = await stableRequest<CreateUserRequest, UserResponse>({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/users',
-    method: REQUEST_METHODS.POST,
-    body: {
-      name: 'John Doe',
-      email: 'john@example.com'
-    }
-  },
-  resReq: true
-});
-
-// user is typed as UserResponse
-console.log(user.id);  // TypeScript knows this exists
 ```
 
 ## License
 
 MIT © Manish Varma
 
-
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---