@emmvish/stable-request 1.5.2 → 1.6.0

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,178 +18,12 @@ 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**.
 
 ---
 
-## 📚 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)
-- [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)
-- [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
-
-🧠 **Graceful failure handling**  
-  
-  Suppress non-critical failures without crashing workflows
-
-🧪 **Trial mode / chaos testing**  
-  
-  Simulate failures without depending on real outages
-
-📊 **First-class observability hooks**  
-  
-  Inspect every failed and successful attempt
-
----
-
-### Scaling beyond single requests
-
-🚀 **Batch execution with shared state (`stableApiGateway`)**  
-  
-  Run many requests concurrently or sequentially with shared configuration and shared state
-
-🎯 **Request groups**  
-  
-  Apply different reliability rules to critical, standard, and optional services
-
-🧱 **Hierarchical configuration**  
-  
-  Workflow → Phase → Group → Request (predictable overrides)
-
----
-
-### Full workflow orchestration
-
-🧩 **Multi-phase workflows with shared state (`stableWorkflow`)**
-  
-  Model real-world business flows as deterministic, observable execution graphs.
-
-🔀 **Mix concurrent and sequential execution**
-  
-  Parallelize where safe, serialize where correctness matters.
-
-🛑 **Stop early or degrade gracefully**
-  
-  Stop execution early or continue based on business criticality.
-
-📈 **Phase-level metrics and hooks**
-  
-  Track execution time, success rates, and failure boundaries per phase.
-
-🧭 **Deterministic, observable execution paths**
-  
-  Every decision is explicit, traceable, and reproducible.
-
----
-
-## How stable-request is different
-
-| 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 |
-
----
-
 ## Choose your entry point
 
 | Need | Use |
@@ -197,7 +32,31 @@ Most HTTP clients answer only one question:
 | Batch or fan-out requests | `stableApiGateway` |
 | Multi-step orchestration | `stableWorkflow` |
 
-Start small and scale **without changing mental models**.
+
+Start small and scale.
+
+---
+
+## 📚 Table of Contents
+<!-- TOC START -->
+- [Installation](#installation)
+- [Core Features](#core-features)
+- [Quick Start](#quick-start)
+- [Advanced Features](#advanced-features)
+  - [Non-Linear Workflows](#non-linear-workflows)
+  - [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)
+- [License](#license)
+<!-- TOC END -->
 
 ---
 
@@ -207,1114 +66,1010 @@ Start small and scale **without changing mental models**.
 npm install @emmvish/stable-request
 ```
 
-## Quick Start
-
-### 1. Basic Request (No Retries)
+## 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 Non-Linear 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
 
-```typescript
-import { stableRequest, REQUEST_METHODS } from '@emmvish/stable-request';
-
-interface PatchRequestBodyParams {
-  id: number;
-  updates: {
-    name?: string;
-    age?: number;
-  }
-}
-
-interface ResponseParams {
-  id: number;
-  name: string;
-  age: number;
-}
-
-const getStableResponse = async () => {
-
-  const token = 'my-auth-token';
-
-  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 }
-}
-
-getStableResponse();
-```
+## Quick Start
 
-### 2. Add Simple Retries
+### Basic Request with Retry
 
 ```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...
-  });
-
-  console.log(data);
-}
-
-getStableResponse();
-```
-
-**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...)
-
-### 3. Validate Response Content (Content-Aware Retries)
-
-Sometimes an API returns HTTP 200 but the data isn't ready yet. Use `responseAnalyzer`:
-
-```typescript
 const data = await stableRequest({
   reqData: {
     hostname: 'api.example.com',
-    path: '/jobs/456/status'
+    path: '/users/123',
+    method: 'GET'
   },
   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
-  }
+  attempts: 3,
+  wait: 1000,
+  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
 });
 
-console.log('Job completed:', data);
+console.log(data);
 ```
 
-**Hook Signature:**
+### Batch Requests via API Gateway
+
 ```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>;
-```
+import { stableApiGateway } from '@emmvish/stable-request';
 
-### 4. Monitor Errors (Observability)
+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 } }
+];
 
-Track every failed attempt with `handleErrors`:
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  concurrentExecution: true,
+  maxConcurrentRequests: 10
+});
 
-```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
-    });
+results.forEach(result => {
+  if (result.success) {
+    console.log(`Request ${result.requestId}:`, result.data);
+  } else {
+    console.error(`Request ${result.requestId} failed:`, result.error);
   }
 });
 ```
 
-**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>;
-```
+### Multi-Phase Workflow
 
-**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?
-}
-```
+import { stableWorkflow, STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
+
+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
+});
 
-### 5. Monitor Successful Attempts
+console.log(`Workflow completed: ${result.successfulRequests}/${result.totalRequests} successful`);
+```
 
-Track successful requests with `handleSuccessfulAttemptData`:
+### Non-Linear Workflow with Dynamic Routing
 
 ```typescript
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/data'
+import { stableWorkflow, STABLE_WORKFLOW_PHASE, PHASE_DECISION_ACTIONS } from '@emmvish/stable-request';
+
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'check-status',
+    requests: [
+      { id: 'status', requestOptions: { reqData: { path: '/status' }, resReq: true } }
+    ],
+    phaseDecisionHook: async ({ phaseResult, sharedBuffer }) => {
+      const status = phaseResult.responses[0]?.data?.status;
+      
+      if (status === 'completed') {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'finalize' };
+      } else if (status === 'processing') {
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        return { action: PHASE_DECISION_ACTIONS.REPLAY };  // Replay this phase
+      } else {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'error-handler' };
+      }
+    },
+    allowReplay: true,
+    maxReplayCount: 10
   },
-  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
-    });
+  {
+    id: 'process',
+    requests: [
+      { id: 'process', requestOptions: { reqData: { path: '/process' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'error-handler',
+    requests: [
+      { id: 'error', requestOptions: { reqData: { path: '/error' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'finalize',
+    requests: [
+      { id: 'final', requestOptions: { reqData: { path: '/finalize' }, resReq: true } }
+    ]
   }
+];
+
+const result = await stableWorkflow(phases, {
+  workflowId: 'dynamic-workflow',
+  commonRequestData: { hostname: 'api.example.com' },
+  enableNonLinearExecution: true,
+  maxWorkflowIterations: 50,
+  sharedBuffer: {}
 });
-```
 
-**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>;
+console.log('Execution history:', result.executionHistory);
+console.log('Terminated early:', result.terminatedEarly);
 ```
 
-**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
-}
-```
+## Advanced Features
+
+### Non-Linear Workflows
+
+Non-linear workflows enable dynamic phase execution based on runtime decisions, allowing you to build complex orchestrations with conditional branching, polling loops, error recovery, and adaptive routing.
 
-### 6. Handle Final Errors Gracefully
+#### Phase Decision Actions
 
-Decide what to do when all retries fail using `finalErrorAnalyzer`:
+Each phase can make decisions about workflow execution:
+
+- **`continue`**: Proceed to the next sequential phase
+- **`jump`**: Jump to a specific phase by ID
+- **`replay`**: Re-execute the current phase
+- **`skip`**: Skip to a target phase or skip the next phase
+- **`terminate`**: Stop the workflow immediately
+
+#### Basic Non-Linear Workflow
 
 ```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
+import { stableWorkflow, STABLE_WORKFLOW_PHASE, PhaseExecutionDecision, PHASE_DECISION_ACTIONS } from '@emmvish/stable-request';
+
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'validate-input',
+    requests: [
+      { id: 'validate', requestOptions: { reqData: { path: '/validate' }, resReq: true } }
+    ],
+    phaseDecisionHook: async ({ phaseResult, sharedBuffer }) => {
+      const isValid = phaseResult.responses[0]?.data?.valid;
+      
+      if (isValid) {
+        sharedBuffer.validationPassed = true;
+        return { action: PHASE_DECISION_ACTIONS.CONTINUE };  // Go to next phase
+      } else {
+        return { 
+          action: PHASE_DECISION_ACTIONS.TERMINATE,
+          metadata: { reason: 'Validation failed' }
+        };
+      }
     }
-    
-    // For critical errors
-    await alerting.sendAlert('Critical API failure', error);
-    return false;  // Throw the error
+  },
+  {
+    id: 'process-data',
+    requests: [
+      { id: 'process', requestOptions: { reqData: { path: '/process' }, resReq: true } }
+    ]
   }
+];
+
+const result = await stableWorkflow(phases, {
+  workflowId: 'validation-workflow',
+  commonRequestData: { hostname: 'api.example.com' },
+  enableNonLinearExecution: true,
+  sharedBuffer: {}
 });
 
-if (data === false) {
-  console.log('Optional feature unavailable, using default');
+if (result.terminatedEarly) {
+  console.log('Workflow terminated:', result.terminationReason);
 }
 ```
 
-**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
-
-You can pass custom data to `responseAnalyzer` and `finalErrorAnalyzer`:
+#### Conditional Branching
 
 ```typescript
-const expectedVersion = 42;
-
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/data'
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'check-user-type',
+    requests: [
+      { id: 'user', requestOptions: { reqData: { path: '/user/info' }, resReq: true } }
+    ],
+    phaseDecisionHook: async ({ phaseResult, sharedBuffer }) => {
+      const userType = phaseResult.responses[0]?.data?.type;
+      sharedBuffer.userType = userType;
+      
+      if (userType === 'premium') {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'premium-flow' };
+      } else if (userType === 'trial') {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'trial-flow' };
+      } else {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'free-flow' };
+      }
+    }
   },
-  resReq: true,
-  attempts: 5,
-  
-  // Pass custom parameters
-  hookParams: {
-    responseAnalyzerParams: { expectedVersion, minItems: 10 },
-    finalErrorAnalyzerParams: { alertTeam: true }
+  {
+    id: 'premium-flow',
+    requests: [
+      { id: 'premium', requestOptions: { reqData: { path: '/premium/data' }, resReq: true } }
+    ],
+    phaseDecisionHook: async () => ({ action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'finalize' })
   },
-  
-  responseAnalyzer: async ({ data, params }) => {
-    // Access custom parameters
-    return data.version >= params.expectedVersion && 
-           data.items.length >= params.minItems;
+  {
+    id: 'trial-flow',
+    requests: [
+      { id: 'trial', requestOptions: { reqData: { path: '/trial/data' }, resReq: true } }
+    ],
+    phaseDecisionHook: async () => ({ action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'finalize' })
   },
-  
-  finalErrorAnalyzer: async ({ error, params }) => {
-    if (params.alertTeam) {
-      await pagerDuty.alert('API failure', error);
-    }
-    return false;
+  {
+    id: 'free-flow',
+    requests: [
+      { id: 'free', requestOptions: { reqData: { path: '/free/data' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'finalize',
+    requests: [
+      { id: 'final', requestOptions: { reqData: { path: '/finalize' }, resReq: true } }
+    ]
+  }
+];
+
+const result = await stableWorkflow(phases, {
+  enableNonLinearExecution: true,
+  sharedBuffer: {},
+  handlePhaseDecision: (decision, phaseResult) => {
+    console.log(`Phase ${phaseResult.phaseId} decided: ${decision.action}`);
   }
 });
 ```
 
-### 8. Pre-Execution Hook (Dynamic Configuration)
-
-Use `preExecution` to modify request configuration dynamically before execution:
+#### Polling with Replay
 
 ```typescript
-const outputBuffer: Record<string, any> = {};
-
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/protected-resource'
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'poll-job-status',
+    allowReplay: true,
+    maxReplayCount: 20,
+    requests: [
+      { id: 'check', requestOptions: { reqData: { path: '/job/status' }, resReq: true } }
+    ],
+    phaseDecisionHook: async ({ phaseResult, executionHistory }) => {
+      const status = phaseResult.responses[0]?.data?.status;
+      const attempts = executionHistory.filter(h => h.phaseId === 'poll-job-status').length;
+      
+      if (status === 'completed') {
+        return { action: PHASE_DECISION_ACTIONS.CONTINUE };
+      } else if (status === 'failed') {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'error-recovery' };
+      } else if (attempts < 20) {
+        // Still processing, wait and replay
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        return { action: PHASE_DECISION_ACTIONS.REPLAY };
+      } else {
+        return { 
+          action: PHASE_DECISION_ACTIONS.TERMINATE,
+          metadata: { reason: 'Job timeout after 20 attempts' }
+        };
+      }
+    }
   },
-  resReq: true,
-  attempts: 3,
-  
-  preExecution: {
-    // Hook executed before any request attempts
-    preExecutionHook: async ({ inputParams, commonBuffer }) => {
-      const token = await authService.getToken(inputParams.userId);
-      commonBuffer.token = token;
-      commonBuffer.fetchedAt = new Date().toISOString();
-      // Return configuration overrides
-      return {
-        reqData: {
-          hostname: 'api.example.com',
-          path: '/protected-resource',
-          headers: {
-            'Authorization': `Bearer ${token}`
-          }
-        },
-        attempts: 5
-      };
-    },
-    preExecutionHookParams: {
-      userId: 'user-123',
-      environment: 'production'
-    },
-    applyPreExecutionConfigOverride: true,
-    continueOnPreExecutionHookFailure: false
+  {
+    id: 'process-results',
+    requests: [
+      { id: 'process', requestOptions: { reqData: { path: '/job/results' }, resReq: true } }
+    ]
   },
-  commonBuffer: outputBuffer
-});
-
-console.log('Token used:', outputBuffer.token);
-console.log('Fetched at:', outputBuffer.fetchedAt);
-```
+  {
+    id: 'error-recovery',
+    requests: [
+      { id: 'recover', requestOptions: { reqData: { path: '/job/retry' }, resReq: true } }
+    ]
+  }
+];
 
-**Pre-Execution Options:**
+const result = await stableWorkflow(phases, {
+  workflowId: 'polling-workflow',
+  commonRequestData: { hostname: 'api.example.com' },
+  enableNonLinearExecution: true,
+  maxWorkflowIterations: 100
+});
 
-```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)
-}
+console.log('Total iterations:', result.executionHistory.length);
+console.log('Phases executed:', result.completedPhases);
 ```
 
-## Intermediate Concepts
-
-### Making POST/PUT/PATCH/DELETE Requests
+#### Retry Logic with Replay
 
 ```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'
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'attempt-operation',
+    allowReplay: true,
+    maxReplayCount: 3,
+    requests: [
+      { 
+        id: 'operation',
+        requestOptions: { 
+          reqData: { path: '/risky-operation', method: 'POST' },
+          resReq: true,
+          attempts: 1  // No retries at request level
+        }
+      }
+    ],
+    phaseDecisionHook: async ({ phaseResult, executionHistory, sharedBuffer }) => {
+      const success = phaseResult.responses[0]?.success;
+      const attemptCount = executionHistory.filter(h => h.phaseId === 'attempt-operation').length;
+      
+      if (success) {
+        sharedBuffer.operationResult = phaseResult.responses[0]?.data;
+        return { action: PHASE_DECISION_ACTIONS.CONTINUE };
+      } else if (attemptCount < 3) {
+        // Exponential backoff
+        const delay = 1000 * Math.pow(2, attemptCount);
+        await new Promise(resolve => setTimeout(resolve, delay));
+        
+        sharedBuffer.retryAttempts = attemptCount;
+        return { action: PHASE_DECISION_ACTIONS.REPLAY };
+      } else {
+        return {
+          action: PHASE_DECISION_ACTIONS.JUMP,
+          targetPhaseId: 'fallback-operation',
+          metadata: { reason: 'Max retries exceeded' }
+        };
+      }
     }
   },
-  resReq: true,
-  attempts: 3
+  {
+    id: 'primary-flow',
+    requests: [
+      { id: 'primary', requestOptions: { reqData: { path: '/primary' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'fallback-operation',
+    requests: [
+      { id: 'fallback', requestOptions: { reqData: { path: '/fallback' }, resReq: true } }
+    ]
+  }
+];
+
+const result = await stableWorkflow(phases, {
+  enableNonLinearExecution: true,
+  sharedBuffer: { retryAttempts: 0 },
+  logPhaseResults: true
 });
 ```
 
-### Query Parameters
+#### Skip Phases
 
 ```typescript
-const users = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/users',
-    query: {
-      page: 1,
-      limit: 10,
-      sort: 'createdAt'
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'check-cache',
+    allowSkip: true,
+    requests: [
+      { id: 'cache', requestOptions: { reqData: { path: '/cache/check' }, resReq: true } }
+    ],
+    phaseDecisionHook: async ({ phaseResult, sharedBuffer }) => {
+      const cached = phaseResult.responses[0]?.data?.cached;
+      
+      if (cached) {
+        sharedBuffer.cachedData = phaseResult.responses[0]?.data;
+        // Skip expensive-computation and go directly to finalize
+        return { action: PHASE_DECISION_ACTIONS.SKIP, targetPhaseId: 'finalize' };
+      }
+      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
     }
   },
-  resReq: true
+  {
+    id: 'expensive-computation',
+    requests: [
+      { id: 'compute', requestOptions: { reqData: { path: '/compute' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'save-to-cache',
+    requests: [
+      { id: 'save', requestOptions: { reqData: { path: '/cache/save' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'finalize',
+    requests: [
+      { id: 'final', requestOptions: { reqData: { path: '/finalize' }, resReq: true } }
+    ]
+  }
+];
+
+const result = await stableWorkflow(phases, {
+  enableNonLinearExecution: true,
+  sharedBuffer: {}
 });
-// Requests: https://api.example.com:443/users?page=1&limit=10&sort=createdAt
 ```
 
-### Custom Timeout and Port
+#### Execution History and Tracking
 
 ```typescript
-const data = await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/slow-endpoint',
-    port: 8080,
-    protocol: 'http',
-    timeout: 30000  // 30 seconds
+const result = await stableWorkflow(phases, {
+  workflowId: 'tracked-workflow',
+  enableNonLinearExecution: true,
+  handlePhaseCompletion: ({ phaseResult, workflowId }) => {
+    console.log(`[${workflowId}] Phase ${phaseResult.phaseId} completed:`, {
+      executionNumber: phaseResult.executionNumber,
+      success: phaseResult.success,
+      decision: phaseResult.decision
+    });
   },
-  resReq: true,
-  attempts: 2
+  handlePhaseDecision: (decision, phaseResult) => {
+    console.log(`Decision made:`, {
+      phase: phaseResult.phaseId,
+      action: decision.action,
+      target: decision.targetPhaseId,
+      metadata: decision.metadata
+    });
+  }
 });
-```
 
-### Request Cancellation
+// Analyze execution history
+console.log('Total phase executions:', result.executionHistory.length);
+console.log('Unique phases executed:', new Set(result.executionHistory.map(h => h.phaseId)).size);
+console.log('Replay count:', result.executionHistory.filter(h => h.decision?.action === 'replay').length);
 
-```typescript
-const controller = new AbortController();
+result.executionHistory.forEach(record => {
+  console.log(`- ${record.phaseId} (attempt ${record.executionNumber}): ${record.success ? '✓' : '✗'}`);
+});
+```
 
-// Cancel after 5 seconds
-setTimeout(() => controller.abort(), 5000);
+#### Loop Protection
 
-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');
+```typescript
+const result = await stableWorkflow(phases, {
+  enableNonLinearExecution: true,
+  maxWorkflowIterations: 50,  // Prevent infinite loops
+  handlePhaseCompletion: ({ phaseResult }) => {
+    if (phaseResult.executionNumber && phaseResult.executionNumber > 10) {
+      console.warn(`Phase ${phaseResult.phaseId} executed ${phaseResult.executionNumber} times`);
+    }
   }
+});
+
+if (result.terminatedEarly && result.terminationReason?.includes('iterations')) {
+  console.error('Workflow hit iteration limit - possible infinite loop');
 }
 ```
 
-### Trial Mode (Testing Your Retry Logic)
+#### Mixed Serial and Parallel Execution
+
+Non-linear workflows support mixing serial and parallel phase execution. Mark consecutive phases with `markConcurrentPhase: true` to execute them in parallel, while other phases execute serially.
 
-Simulate failures without depending on actual API issues:
+**Basic Mixed Execution:**
 
 ```typescript
-await stableRequest({
-  reqData: {
-    hostname: 'api.example.com',
-    path: '/data'
+import { stableWorkflow, STABLE_WORKFLOW_PHASE, PHASE_DECISION_ACTIONS } from '@emmvish/stable-request';
+
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'init',
+    requests: [
+      { id: 'init', requestOptions: { reqData: { path: '/init' }, resReq: true } }
+    ],
+    phaseDecisionHook: async () => ({ action: PHASE_DECISION_ACTIONS.CONTINUE })
   },
-  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
+  // These two phases execute in parallel
+  {
+    id: 'check-inventory',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'inv', requestOptions: { reqData: { path: '/inventory' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'check-pricing',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'price', requestOptions: { reqData: { path: '/pricing' }, resReq: true } }
+    ],
+    // Decision hook receives results from all concurrent phases
+    phaseDecisionHook: async ({ concurrentPhaseResults }) => {
+      const inventory = concurrentPhaseResults![0].responses[0]?.data;
+      const pricing = concurrentPhaseResults![1].responses[0]?.data;
+      
+      if (inventory.available && pricing.inBudget) {
+        return { action: PHASE_DECISION_ACTIONS.CONTINUE };
+      }
+      return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'out-of-stock' };
+    }
+  },
+  // This phase executes serially after the parallel group
+  {
+    id: 'process-order',
+    requests: [
+      { id: 'order', requestOptions: { reqData: { path: '/order' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'out-of-stock',
+    requests: [
+      { id: 'notify', requestOptions: { reqData: { path: '/notify' }, resReq: true } }
+    ]
   }
+];
+
+const result = await stableWorkflow(phases, {
+  workflowId: 'mixed-execution',
+  commonRequestData: { hostname: 'api.example.com' },
+  enableNonLinearExecution: true
 });
 ```
 
-**Use cases:**
-- Test your error handling logic
-- Verify monitoring alerts work
-- Chaos engineering experiments
-- Integration testing
-
-## Batch Processing - Multiple Requests
-
-### Basic Batch Request
+**Multiple Parallel Groups:**
 
 ```typescript
-import { stableApiGateway } from '@emmvish/stable-request';
-
-const requests = [
+const phases: STABLE_WORKFLOW_PHASE[] = [
   {
-    id: 'user-1',
-    requestOptions: {
-      reqData: { path: '/users/1' },
-      resReq: true
-    }
+    id: 'authenticate',
+    requests: [
+      { id: 'auth', requestOptions: { reqData: { path: '/auth' }, resReq: true } }
+    ]
   },
+  // First parallel group: Data validation
   {
-    id: 'user-2',
-    requestOptions: {
-      reqData: { path: '/users/2' },
-      resReq: true
-    }
+    id: 'validate-user',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'val-user', requestOptions: { reqData: { path: '/validate/user' }, resReq: true } }
+    ]
   },
   {
-    id: 'user-3',
-    requestOptions: {
-      reqData: { path: '/users/3' },
-      resReq: true
+    id: 'validate-payment',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'val-pay', requestOptions: { reqData: { path: '/validate/payment' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'validate-shipping',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'val-ship', requestOptions: { reqData: { path: '/validate/shipping' }, resReq: true } }
+    ],
+    phaseDecisionHook: async ({ concurrentPhaseResults }) => {
+      const allValid = concurrentPhaseResults!.every(r => r.success && r.responses[0]?.data?.valid);
+      if (!allValid) {
+        return { action: PHASE_DECISION_ACTIONS.TERMINATE, metadata: { reason: 'Validation failed' } };
+      }
+      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
     }
+  },
+  // Serial processing phase
+  {
+    id: 'calculate-total',
+    requests: [
+      { id: 'calc', requestOptions: { reqData: { path: '/calculate' }, resReq: true } }
+    ]
+  },
+  // Second parallel group: External integrations
+  {
+    id: 'notify-warehouse',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'warehouse', requestOptions: { reqData: { path: '/notify/warehouse' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'notify-shipping',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'shipping', requestOptions: { reqData: { path: '/notify/shipping' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'update-inventory',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'inventory', requestOptions: { reqData: { path: '/update/inventory' }, resReq: true } }
+    ]
+  },
+  // Final serial phase
+  {
+    id: 'finalize',
+    requests: [
+      { id: 'final', requestOptions: { reqData: { path: '/finalize' }, 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
+const result = await stableWorkflow(phases, {
+  workflowId: 'multi-parallel-workflow',
+  commonRequestData: { hostname: 'api.example.com' },
+  enableNonLinearExecution: true
 });
 
-// Process results
-results.forEach(result => {
-  if (result.success) {
-    console.log(`${result.requestId} succeeded:`, result.data);
-  } else {
-    console.error(`${result.requestId} failed:`, result.error);
-  }
-});
+console.log('Execution order demonstrates mixed serial/parallel execution');
 ```
 
-**Response Format:**
+**Decision Making with Concurrent Results:**
+
 ```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)
-}
+const phases: STABLE_WORKFLOW_PHASE[] = [
+  {
+    id: 'api-check-1',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'api1', requestOptions: { reqData: { path: '/health/api1' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'api-check-2',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'api2', requestOptions: { reqData: { path: '/health/api2' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'api-check-3',
+    markConcurrentPhase: true,
+    requests: [
+      { id: 'api3', requestOptions: { reqData: { path: '/health/api3' }, resReq: true } }
+    ],
+    phaseDecisionHook: async ({ concurrentPhaseResults, sharedBuffer }) => {
+      // Aggregate results from all parallel phases
+      const healthScores = concurrentPhaseResults!.map(result => 
+        result.responses[0]?.data?.score || 0
+      );
+      
+      const averageScore = healthScores.reduce((a, b) => a + b, 0) / healthScores.length;
+      sharedBuffer!.healthScore = averageScore;
+      
+      if (averageScore > 0.8) {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'optimal-path' };
+      } else if (averageScore > 0.5) {
+        return { action: PHASE_DECISION_ACTIONS.CONTINUE };  // Go to degraded-path
+      } else {
+        return { action: PHASE_DECISION_ACTIONS.JUMP, targetPhaseId: 'fallback-path' };
+      }
+    }
+  },
+  {
+    id: 'degraded-path',
+    requests: [
+      { id: 'degraded', requestOptions: { reqData: { path: '/degraded' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'optimal-path',
+    requests: [
+      { id: 'optimal', requestOptions: { reqData: { path: '/optimal' }, resReq: true } }
+    ]
+  },
+  {
+    id: 'fallback-path',
+    requests: [
+      { id: 'fallback', requestOptions: { reqData: { path: '/fallback' }, resReq: true } }
+    ]
+  }
+];
+
+const sharedBuffer = {};
+const result = await stableWorkflow(phases, {
+  workflowId: 'adaptive-routing',
+  commonRequestData: { hostname: 'api.example.com' },
+  enableNonLinearExecution: true,
+  sharedBuffer
+});
+
+console.log('Average health score:', sharedBuffer.healthScore);
 ```
 
-### Sequential Execution (With Dependencies)
+**Error Handling in Parallel Groups:**
 
 ```typescript
-const steps = [
+const phases: STABLE_WORKFLOW_PHASE[] = [
   {
-    id: 'step-1-create',
-    requestOptions: {
-      reqData: { 
-        path: '/orders',
-        method: REQUEST_METHODS.POST,
-        body: { item: 'Widget' }
-      },
-      resReq: true
-    }
+    id: 'critical-check',
+    markConcurrentPhase: true,
+    requests: [
+      { 
+        id: 'check1',
+        requestOptions: { 
+          reqData: { path: '/critical/check1' },
+          resReq: true,
+          attempts: 3
+        }
+      }
+    ]
   },
   {
-    id: 'step-2-process',
-    requestOptions: {
-      reqData: { 
-        path: '/orders/123/process',
-        method: REQUEST_METHODS.POST
-      },
-      resReq: true
+    id: 'optional-check',
+    markConcurrentPhase: true,
+    requests: [
+      { 
+        id: 'check2',
+        requestOptions: { 
+          reqData: { path: '/optional/check2' },
+          resReq: true,
+          attempts: 1,
+          finalErrorAnalyzer: async () => true  // Suppress errors
+        }
+      }
+    ],
+    phaseDecisionHook: async ({ concurrentPhaseResults }) => {
+      // Check if critical phase succeeded
+      const criticalSuccess = concurrentPhaseResults![0].success;
+      
+      if (!criticalSuccess) {
+        return { 
+          action: PHASE_DECISION_ACTIONS.TERMINATE,
+          metadata: { reason: 'Critical check failed' }
+        };
+      }
+      
+      // Continue even if optional check failed
+      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
     }
   },
   {
-    id: 'step-3-ship',
-    requestOptions: {
-      reqData: { path: '/orders/123/ship' },
-      resReq: true
-    }
+    id: 'process',
+    requests: [
+      { id: 'process', requestOptions: { reqData: { path: '/process' }, 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
+const result = await stableWorkflow(phases, {
+  workflowId: 'resilient-parallel',
+  commonRequestData: { hostname: 'api.example.com' },
+  enableNonLinearExecution: true,
+  stopOnFirstPhaseError: false  // Continue even with phase errors
 });
-
-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)
+**Key Points:**
+- Only **consecutive phases** with `markConcurrentPhase: true` execute in parallel
+- The **last phase** in a concurrent group can have a `phaseDecisionHook` that receives `concurrentPhaseResults`
+- Parallel groups are separated by phases **without** `markConcurrentPhase` (or phases with it set to false)
+- All decision actions work with parallel groups except `REPLAY` (not supported for concurrent groups)
+- Error handling follows normal workflow rules - use `stopOnFirstPhaseError` to control behavior
 
-Instead of repeating configuration for each request:
+#### Configuration Options
 
+**Workflow Options:**
+- `enableNonLinearExecution`: Enable non-linear workflow (required)
+- `maxWorkflowIterations`: Maximum total iterations (default: 1000)
+- `handlePhaseDecision`: Called when phase makes a decision
+- `stopOnFirstPhaseError`: Stop on phase failure (default: false)
+
+**Phase Options:**
+- `phaseDecisionHook`: Function returning `PhaseExecutionDecision`
+- `allowReplay`: Allow phase replay (default: false)
+- `allowSkip`: Allow phase skip (default: false)
+- `maxReplayCount`: Maximum replays (default: Infinity)
+
+**Decision Hook Parameters:**
 ```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;
-    }
-  }
-);
+interface PhaseDecisionHookOptions {
+  workflowId: string;
+  phaseResult: STABLE_WORKFLOW_PHASE_RESULT;
+  phaseId: string;
+  phaseIndex: number;
+  executionHistory: PhaseExecutionRecord[];
+  sharedBuffer?: Record<string, any>;
+  params?: any;
+}
 ```
 
-## Advanced: Request Grouping
-
-Group related requests with different configurations. Configuration priority:
+**Decision Object:**
+```typescript
+interface PhaseExecutionDecision {
+  action: PHASE_DECISION_ACTIONS;
+  targetPhaseId?: string;
+  replayCount?: number;
+  metadata?: Record<string, any>;
+}
+```
 
-**Individual Request** > **Group Config** > **Global Common Config**
+### Retry Strategies
 
-### Example: Service Tiers
+Control the delay between retry attempts:
 
 ```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
-          }
-        }
-      }
-    ]
-  }
-);
+import { stableRequest, RETRY_STRATEGIES } from '@emmvish/stable-request';
 
-// Analyze by group
-const criticalOk = results
-  .filter(r => r.groupId === 'critical')
-  .every(r => r.success);
+// Fixed delay: 1000ms between each retry
+await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
+  attempts: 3,
+  wait: 1000,
+  retryStrategy: RETRY_STRATEGIES.FIXED
+});
 
-const analyticsCount = results
-  .filter(r => r.groupId === 'analytics' && r.success)
-  .length;
+// Linear backoff: 1000ms, 2000ms, 3000ms
+await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
+  attempts: 3,
+  wait: 1000,
+  retryStrategy: RETRY_STRATEGIES.LINEAR
+});
 
-console.log('Critical services:', criticalOk ? 'HEALTHY' : 'DEGRADED');
-console.log('Analytics events tracked:', analyticsCount);
+// Exponential backoff: 1000ms, 2000ms, 4000ms
+await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
+  attempts: 3,
+  wait: 1000,
+  maxAllowedWait: 10000,
+  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
+});
 ```
 
-### Example: Multi-Region Configuration
+### Circuit Breaker
 
-```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
+Prevent cascading failures by automatically blocking requests when error thresholds are exceeded:
 
 ```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[];
+import { stableApiGateway, CircuitBreakerState } from '@emmvish/stable-request';
 
 const results = await stableApiGateway(requests, {
-  concurrentExecution: true,
   commonRequestData: { hostname: 'api.example.com' },
-  sharedBuffer
+  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(sharedBuffer); // { fromA: true, fromB: true }
-```
+// Circuit breaker can be shared across workflows
+const breaker = new CircuitBreaker({
+  failureThresholdPercentage: 50,
+  minimumRequests: 10,
+  recoveryTimeoutMs: 60000
+});
 
+const result = await stableWorkflow(phases, {
+  circuitBreaker: breaker,
+  // ... other options
+});
 
-## Multi-Phase Workflows
+// Check circuit breaker state
+const state = breaker.getState();
+console.log(`Circuit breaker state: ${state.state}`); // CLOSED, OPEN, or HALF_OPEN
+```
 
-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.
+### Rate Limiting
 
-### Basic Workflow
+Control request throughput to prevent overwhelming APIs:
 
 ```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
+import { stableApiGateway } 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
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  concurrentExecution: true,
+  rateLimit: {
+    maxRequests: 10,  // Maximum 10 requests
+    windowMs: 1000    // Per 1 second window
   }
-);
-
-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)
-}
+// Rate limiting in workflows
+const result = await stableWorkflow(phases, {
+  rateLimit: {
+    maxRequests: 5,
+    windowMs: 1000
+  }
+});
 ```
 
-### Phase Configuration
+### Caching
 
-Each phase can have its own execution mode and error handling, and can also work upon the shared buffer:
+Cache responses with TTL to reduce redundant API calls:
 
 ```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
+import { stableRequest, getGlobalCacheManager } from '@emmvish/stable-request';
 
-### Workflow with Request Groups
+// Enable caching for a request
+const data = await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/users/123' },
+  resReq: true,
+  cache: {
+    enabled: true,
+    ttl: 60000  // Cache for 60 seconds
+  }
+});
 
-Combine workflows with request groups for fine-grained control:
+// Use global cache manager across requests
+const results = await stableApiGateway(requests, {
+  commonRequestData: { hostname: 'api.example.com' },
+  commonCache: { enabled: true, ttl: 300000 }  // 5 minutes
+});
 
-```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
-        }
-      }
-    ]
-  }
-);
+// 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
 ```
 
-### Phase Observability Hooks
+### Pre-Execution Hooks
 
-Monitor workflow execution with phase-level hooks:
+Transform requests dynamically before execution:
 
 ```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`);
+import { stableRequest } from '@emmvish/stable-request';
+
+const commonBuffer: Record<string, any> = {};
+
+const data = await stableRequest({
+  reqData: { hostname: 'api.example.com', path: '/data' },
+  resReq: true,
+  preExecution: {
+    preExecutionHook: async ({ inputParams, commonBuffer }) => {
+      // Fetch authentication token
+      const token = await getAuthToken();
       
-      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`);
+      // Store in shared buffer
+      commonBuffer.token = token;
+      commonBuffer.timestamp = Date.now();
       
-      await alerting.notify('workflow_phase_failed', {
-        workflowId,
-        phaseId: phaseResult.phaseId,
-        error: error.message,
-        failedRequests: phaseResult.failedRequests
-      });
+      // Override request configuration
+      return {
+        reqData: {
+          hostname: 'api.example.com',
+          path: '/authenticated-data',
+          headers: { Authorization: `Bearer ${token}` }
+        }
+      };
     },
-    
-    logPhaseResults: true  // Enable console logging
-  }
-);
+    preExecutionHookParams: { userId: 'user123' },
+    applyPreExecutionConfigOverride: true,  // Apply returned config
+    continueOnPreExecutionHookFailure: false
+  },
+  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 phases = [
+const sharedBuffer: Record<string, any> = { requestCount: 0 };
+
+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 +1081,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,715 +1103,502 @@ 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
-          }
-        }
-      }
-    ]
-  }
-);
-
-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'
-};
+import { stableWorkflow, RETRY_STRATEGIES } from '@emmvish/stable-request';
 
-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',
-          requestOptions: {
-            reqData: { path: '/load/indexes', method: REQUEST_METHODS.POST },
-            resReq: true
-          }
-        },
-        {
-          id: 'refresh-cache',
+          id: 'process-users',
           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}`);
-```
-
-## 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
-
-```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
-}
-```
-
-### `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
-}
-```
-
-**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
-}
-```
-
-### Hooks Reference
-
-#### preExecutionHook
-
-**Purpose:** Dynamically configure request before execution
-
-```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
-}
-```
-
-#### responseAnalyzer
-
-**Purpose:** Validate response content, retry even on HTTP 200
-
-```typescript
-responseAnalyzer: async ({ reqData, data, trialMode, params, commonBuffer }) => {
-  // Return true if valid, false to retry
-  return data.status === 'ready';
-}
-```
-
-#### handleErrors
-
-**Purpose:** Monitor and log failed attempts
-
-```typescript
-handleErrors: async ({ reqData, errorLog, maxSerializableChars, params, commonBuffer }) => {
-  await logger.error({
-    url: reqData.url,
-    attempt: errorLog.attempt,
-    error: errorLog.error
   });
-}
-```
-
-#### handleSuccessfulAttemptData
 
-**Purpose:** Monitor and log successful attempts
-
-```typescript
-handleSuccessfulAttemptData: async ({ reqData, successfulAttemptData, maxSerializableChars, params, commonBuffer }) => {
-  await analytics.track({
-    url: reqData.url,
-    duration: successfulAttemptData.executionTime
-  });
+  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
+    }))
+  };
 }
-```
 
-#### finalErrorAnalyzer
-
-**Purpose:** Handle final error after all retries exhausted
+// 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
-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
-}
+const results = await Promise.all(tenants.map(executeTenantWorkflow));
+results.forEach(result => {
+  console.log(`Tenant ${result.tenantId}:`, result.success ? 'Success' : 'Failed');
+});
 ```
 
-#### handlePhaseCompletion
-
-**Purpose:** Execute phase-bridging code upon successful completion of a phase
+### Use Case 2: Resilient Data Pipeline with Fallback Strategies
 
 ```typescript
-handlePhaseCompletion: async ({ workflowId, phaseResult, maxSerializableChars, params, sharedBuffer }) => {
-  await logger.log(phaseResult.phaseId, phaseResult.success);
-}
-```
+import { stableApiGateway, RETRY_STRATEGIES, CircuitBreaker } from '@emmvish/stable-request';
 
-#### handlePhaseError
-
-**Purpose:** Execute error handling code if a phase runs into an error
-
-```typescript
-handlePhaseError: async ({ workflowId, phaseResult, error, maxSerializableChars, params, sharedBuffer }) => {
-  await logger.error(error);
+interface DataSource {
+  id: string;
+  priority: number;
+  endpoint: string;
+  hostname: string;
 }
-```
-
-## 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):
+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;
+    }
 
-- Request scope: commonBuffer
-- Gateway scope: Gateway's / Phase's sharedBuffer
-- Workflow scope: Workflow's sharedBuffer
+    console.log(`Attempting to fetch from ${source.id}...`);
 
-## TypeScript Support
+    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
+          }
+        }
+      ];
 
-Fully typed with generics:
+      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);
+        }
+      });
 
-```typescript
-interface CreateUserRequest {
-  name: string;
-  email: string;
-}
+      // 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
+    }
+  }
 
-interface UserResponse {
-  id: string;
-  name: string;
-  email: string;
-  createdAt: string;
+  throw new Error('All data sources failed');
 }
 
-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'
-    }
+// Usage
+const dataSources: DataSource[] = [
+  {
+    id: 'primary-db',
+    priority: 1,
+    endpoint: '/api/v1',
+    hostname: 'primary.example.com'
   },
-  resReq: true
-});
+  {
+    id: 'replica-db',
+    priority: 2,
+    endpoint: '/api/v1',
+    hostname: 'replica.example.com'
+  },
+  {
+    id: 'backup-cache',
+    priority: 3,
+    endpoint: '/cached',
+    hostname: 'cache.example.com'
+  }
+];
 
-// user is typed as UserResponse
-console.log(user.id);  // TypeScript knows this exists
+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);
 ```
 
 ## License
 
 MIT © Manish Varma
 
-
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
 ---
 
 **Made with ❤️ for developers integrating with unreliable APIs**