@emmvish/stable-request 1.7.2 → 1.8.0

package/README.md

@@ -16,6 +16,11 @@ A production-grade HTTP Workflow Execution Engine for Node.js that transforms un
   - [Circuit Breaker Pattern](#circuit-breaker-pattern)
   - [Response Caching](#response-caching)
   - [Rate Limiting and Concurrency Control](#rate-limiting-and-concurrency-control)
+- [Metrics and Observability](#metrics-and-observability)
+  - [Request-Level Metrics](#request-level-metrics)
+  - [API Gateway Metrics](#api-gateway-metrics)
+  - [Workflow Metrics](#workflow-metrics)
+  - [MetricsAggregator Utility](#metricsaggregator-utility)
 - [Workflow Execution Patterns](#workflow-execution-patterns)
   - [Sequential and Concurrent Phases](#sequential-and-concurrent-phases)
   - [Mixed Execution Mode](#mixed-execution-mode)
@@ -260,9 +265,10 @@ await stableRequest({
   reqData: { hostname: 'unreliable-api.example.com', path: '/data' },
   attempts: 3,
   circuitBreaker: {
-    failureThreshold: 5,                        // Open after 5 failures
-    successThreshold: 2,                        // Close after 2 successes in half-open
-    timeout: 60000,                             // Wait 60s before trying again (half-open)
+    failureThresholdPercentage: 50,             // Open after 50% failures
+    minimumRequests: 10,                        // Minimum requests before evaluation
+    recoveryTimeoutMs: 60000,                   // Wait 60s before trying again (half-open)
+    successThresholdPercentage: 20,             // Close after 20% successes in half-open
     trackIndividualAttempts: false              // Track at request level (not attempt level)
   }
 });
@@ -278,9 +284,10 @@ await stableRequest({
 import { CircuitBreaker } from '@emmvish/stable-request';
 
 const sharedBreaker = new CircuitBreaker({
-  failureThreshold: 10,
-  successThreshold: 3,
-  timeout: 120000
+  failureThresholdPercentage: 50,               // 50% failure rate triggers open
+  minimumRequests: 10,                          // Minimum 10 requests before evaluation
+  recoveryTimeoutMs: 120000,                    // 120s timeout in open state
+  successThresholdPercentage: 50                // 50% success rate closes circuit
 });
 
 await stableWorkflow(phases, {
@@ -347,7 +354,7 @@ await stableWorkflow(phases, {
   // Rate limiting (token bucket algorithm)
   rateLimit: {
     maxRequests: 100,                           // 100 requests
-    timeWindow: 60000                           // per 60 seconds
+    windowMs: 60000                             // per 60 seconds
   },
   
   // Concurrency limiting
@@ -363,7 +370,7 @@ const phases = [
     maxConcurrentRequests: 10,                  // Override workflow limit
     rateLimit: {
       maxRequests: 50,
-      timeWindow: 10000
+      windowMs: 10000
     },
     requests: [...]
   }
@@ -374,15 +381,343 @@ const phases = [
 ```typescript
 import { RateLimiter } from '@emmvish/stable-request';
 
-const limiter = new RateLimiter({
-  maxRequests: 1000,
-  timeWindow: 3600000                           // 1000 requests per hour
+const limiter = new RateLimiter(1000, 3600000); // 1000 requests per hour
+
+const state = await limiter.getState();          // Get current state
+console.log(state);
+// { availableTokens: 1000, queueLength: 0, maxRequests: 1000, windowMs: 3600000 }
+```
+
+## Metrics and Observability
+
+`@emmvish/stable-request` provides comprehensive metrics at every level of execution, from individual requests to complete workflows. All metrics are automatically computed and included in results.
+
+### Request-Level Metrics
+
+Every `stableRequest` call returns detailed metrics about the request execution:
+
+```typescript
+import { stableRequest } from '@emmvish/stable-request';
+
+const result = await stableRequest({
+  reqData: {
+    hostname: 'api.example.com',
+    path: '/users/123'
+  },
+  resReq: true,
+  attempts: 3,
+  wait: 1000,
+  logAllErrors: true
 });
 
-await limiter.acquire();                        // Waits if limit exceeded
-// Make request
+// Access request metrics
+console.log('Request Result:', {
+  success: result.success,              // true/false
+  data: result.data,                    // Response data
+  error: result.error,                  // Error message (if failed)
+  errorLogs: result.errorLogs,          // All failed attempts
+  successfulAttempts: result.successfulAttempts,  // All successful attempts
+  metrics: {
+    totalAttempts: result.metrics.totalAttempts,           // 3
+    successfulAttempts: result.metrics.successfulAttempts, // 1
+    failedAttempts: result.metrics.failedAttempts,         // 2
+    totalExecutionTime: result.metrics.totalExecutionTime, // ms
+    averageAttemptTime: result.metrics.averageAttemptTime, // ms
+    infrastructureMetrics: {
+      circuitBreaker: result.metrics.infrastructureMetrics?.circuitBreaker,
+      cache: result.metrics.infrastructureMetrics?.cache
+    }
+  }
+});
+
+// Error logs provide detailed attempt information
+result.errorLogs?.forEach(log => {
+  console.log({
+    attempt: log.attempt,              // "1/3"
+    timestamp: log.timestamp,
+    error: log.error,
+    statusCode: log.statusCode,
+    type: log.type,                    // "HTTP_ERROR" | "INVALID_CONTENT"
+    isRetryable: log.isRetryable,
+    executionTime: log.executionTime
+  });
+});
+
+// Successful attempts show what worked
+result.successfulAttempts?.forEach(attempt => {
+  console.log({
+    attempt: attempt.attempt,          // "3/3"
+    timestamp: attempt.timestamp,
+    executionTime: attempt.executionTime,
+    data: attempt.data,
+    statusCode: attempt.statusCode
+  });
+});
 ```
 
+**STABLE_REQUEST_RESULT Structure:**
+- `success`: Boolean indicating if request succeeded
+- `data`: Response data (if `resReq: true`)
+- `error`: Error message (if request failed)
+- `errorLogs`: Array of all failed attempt details
+- `successfulAttempts`: Array of all successful attempt details
+- `metrics`: Computed execution metrics and infrastructure statistics
+
+### API Gateway Metrics
+
+`stableApiGateway` provides aggregated metrics for batch requests:
+
+```typescript
+import { stableApiGateway } from '@emmvish/stable-request';
+
+const requests = [
+  { id: 'user-1', groupId: 'users', requestOptions: { reqData: { path: '/users/1' }, resReq: true } },
+  { id: 'user-2', groupId: 'users', requestOptions: { reqData: { path: '/users/2' }, resReq: true } },
+  { id: 'order-1', groupId: 'orders', requestOptions: { reqData: { path: '/orders/1' }, resReq: true } },
+  { id: 'product-1', requestOptions: { reqData: { path: '/products/1' }, resReq: true } }
+];
+
+const results = await stableApiGateway(requests, {
+  concurrentExecution: true,
+  commonRequestData: { hostname: 'api.example.com' },
+  commonAttempts: 3,
+  circuitBreaker: { failureThresholdPercentage: 50, minimumRequests: 5 },
+  rateLimit: { maxRequests: 100, windowMs: 60000 },
+  maxConcurrentRequests: 5
+});
+
+// Gateway-level metrics
+console.log('Gateway Metrics:', {
+  totalRequests: results.metrics.totalRequests,           // 4
+  successfulRequests: results.metrics.successfulRequests, // 3
+  failedRequests: results.metrics.failedRequests,         // 1
+  successRate: results.metrics.successRate,               // 75%
+  failureRate: results.metrics.failureRate                // 25%
+});
+
+// Request group metrics
+results.metrics.requestGroups?.forEach(group => {
+  console.log(`Group ${group.groupId}:`, {
+    totalRequests: group.totalRequests,
+    successfulRequests: group.successfulRequests,
+    failedRequests: group.failedRequests,
+    successRate: group.successRate,                      // %
+    failureRate: group.failureRate,                      // %
+    requestIds: group.requestIds                         // Array of request IDs
+  });
+});
+
+// Infrastructure metrics (when utilities are used)
+if (results.metrics.infrastructureMetrics) {
+  const infra = results.metrics.infrastructureMetrics;
+  
+  // Circuit Breaker metrics
+  if (infra.circuitBreaker) {
+    console.log('Circuit Breaker:', {
+      state: infra.circuitBreaker.state,                 // CLOSED | OPEN | HALF_OPEN
+      isHealthy: infra.circuitBreaker.isHealthy,
+      totalRequests: infra.circuitBreaker.totalRequests,
+      failurePercentage: infra.circuitBreaker.failurePercentage,
+      openCount: infra.circuitBreaker.openCount,
+      recoveryAttempts: infra.circuitBreaker.recoveryAttempts
+    });
+  }
+  
+  // Cache metrics
+  if (infra.cache) {
+    console.log('Cache:', {
+      hitRate: infra.cache.hitRate,                      // %
+      currentSize: infra.cache.currentSize,
+      networkRequestsSaved: infra.cache.networkRequestsSaved,
+      cacheEfficiency: infra.cache.cacheEfficiency       // %
+    });
+  }
+  
+  // Rate Limiter metrics
+  if (infra.rateLimiter) {
+    console.log('Rate Limiter:', {
+      throttledRequests: infra.rateLimiter.throttledRequests,
+      throttleRate: infra.rateLimiter.throttleRate,      // %
+      peakRequestRate: infra.rateLimiter.peakRequestRate
+    });
+  }
+  
+  // Concurrency Limiter metrics
+  if (infra.concurrencyLimiter) {
+    console.log('Concurrency:', {
+      peakConcurrency: infra.concurrencyLimiter.peakConcurrency,
+      utilizationPercentage: infra.concurrencyLimiter.utilizationPercentage,
+      averageQueueWaitTime: infra.concurrencyLimiter.averageQueueWaitTime
+    });
+  }
+}
+```
+
+### Workflow Metrics
+
+`stableWorkflow` provides end-to-end metrics for complex orchestrations:
+
+```typescript
+import { stableWorkflow, PHASE_DECISION_ACTIONS } from '@emmvish/stable-request';
+
+const phases = [
+  {
+    id: 'fetch-users',
+    requests: [/* ... */]
+  },
+  {
+    id: 'process-data',
+    concurrent: true,
+    requests: [/* ... */]
+  },
+  {
+    id: 'store-results',
+    requests: [/* ... */]
+  }
+];
+
+const result = await stableWorkflow(phases, {
+  workflowId: 'data-processing-pipeline',
+  enableMixedExecution: true,
+  commonRequestData: { hostname: 'api.example.com' },
+  logPhaseResults: true
+});
+
+// Workflow-level metrics
+console.log('Workflow Metrics:', {
+  workflowId: result.metrics.workflowId,
+  success: result.metrics.success,
+  executionTime: result.metrics.executionTime,           // Total time in ms
+  
+  // Phase statistics
+  totalPhases: result.metrics.totalPhases,
+  completedPhases: result.metrics.completedPhases,
+  skippedPhases: result.metrics.skippedPhases,
+  failedPhases: result.metrics.failedPhases,
+  phaseCompletionRate: result.metrics.phaseCompletionRate,  // %
+  averagePhaseExecutionTime: result.metrics.averagePhaseExecutionTime,  // ms
+  
+  // Request statistics
+  totalRequests: result.metrics.totalRequests,
+  successfulRequests: result.metrics.successfulRequests,
+  failedRequests: result.metrics.failedRequests,
+  requestSuccessRate: result.metrics.requestSuccessRate,    // %
+  requestFailureRate: result.metrics.requestFailureRate,    // %
+  
+  // Performance
+  throughput: result.metrics.throughput,                    // requests/second
+  totalPhaseReplays: result.metrics.totalPhaseReplays,
+  totalPhaseSkips: result.metrics.totalPhaseSkips,
+  
+  // Branch metrics (if using branch execution)
+  totalBranches: result.metrics.totalBranches,
+  completedBranches: result.metrics.completedBranches,
+  failedBranches: result.metrics.failedBranches,
+  branchSuccessRate: result.metrics.branchSuccessRate       // %
+});
+
+// Request group metrics aggregated across entire workflow
+result.requestGroupMetrics?.forEach(group => {
+  console.log(`Request Group ${group.groupId}:`, {
+    totalRequests: group.totalRequests,
+    successRate: group.successRate,                        // %
+    requestIds: group.requestIds
+  });
+});
+
+// Per-phase metrics
+result.phases.forEach(phase => {
+  console.log(`Phase ${phase.phaseId}:`, {
+    executionTime: phase.metrics?.executionTime,
+    totalRequests: phase.metrics?.totalRequests,
+    successfulRequests: phase.metrics?.successfulRequests,
+    requestSuccessRate: phase.metrics?.requestSuccessRate,  // %
+    hasDecision: phase.metrics?.hasDecision,
+    decisionAction: phase.metrics?.decisionAction          // CONTINUE | JUMP | REPLAY | etc.
+  });
+});
+
+// Branch metrics (for branched workflows)
+result.branches?.forEach(branch => {
+  console.log(`Branch ${branch.branchId}:`, {
+    success: branch.metrics?.success,
+    executionTime: branch.metrics?.executionTime,
+    totalPhases: branch.metrics?.totalPhases,
+    completedPhases: branch.metrics?.completedPhases,
+    totalRequests: branch.metrics?.totalRequests,
+    requestSuccessRate: branch.metrics?.requestSuccessRate  // %
+  });
+});
+```
+
+### MetricsAggregator Utility
+
+For custom metrics extraction and analysis:
+
+```typescript
+import { MetricsAggregator } from '@emmvish/stable-request';
+
+// Extract workflow metrics
+const workflowMetrics = MetricsAggregator.extractWorkflowMetrics(workflowResult);
+
+// Extract phase metrics
+const phaseMetrics = MetricsAggregator.extractPhaseMetrics(phaseResult);
+
+// Extract branch metrics
+const branchMetrics = MetricsAggregator.extractBranchMetrics(branchResult);
+
+// Extract request group metrics
+const requestGroups = MetricsAggregator.extractRequestGroupMetrics(responses);
+
+// Extract individual request metrics
+const requestMetrics = MetricsAggregator.extractRequestMetrics(responses);
+
+// Extract circuit breaker metrics
+const cbMetrics = MetricsAggregator.extractCircuitBreakerMetrics(circuitBreaker);
+
+// Extract cache metrics
+const cacheMetrics = MetricsAggregator.extractCacheMetrics(cacheManager);
+
+// Extract rate limiter metrics
+const rateLimiterMetrics = MetricsAggregator.extractRateLimiterMetrics(rateLimiter);
+
+// Extract concurrency limiter metrics
+const concurrencyMetrics = MetricsAggregator.extractConcurrencyLimiterMetrics(limiter);
+
+// Aggregate all system metrics
+const systemMetrics = MetricsAggregator.aggregateSystemMetrics(
+  workflowResult,
+  circuitBreaker,
+  cacheManager,
+  rateLimiter,
+  concurrencyLimiter
+);
+
+console.log('Complete System View:', {
+  workflow: systemMetrics.workflow,
+  phases: systemMetrics.phases,
+  branches: systemMetrics.branches,
+  requestGroups: systemMetrics.requestGroups,
+  requests: systemMetrics.requests,
+  circuitBreaker: systemMetrics.circuitBreaker,
+  cache: systemMetrics.cache,
+  rateLimiter: systemMetrics.rateLimiter,
+  concurrencyLimiter: systemMetrics.concurrencyLimiter
+});
+```
+
+**Available Metrics Types:**
+- `WorkflowMetrics`: Complete workflow statistics
+- `BranchMetrics`: Branch execution metrics
+- `PhaseMetrics`: Individual phase metrics
+- `RequestGroupMetrics`: Grouped request statistics
+- `RequestMetrics`: Individual request metrics
+- `CircuitBreakerDashboardMetrics`: Circuit breaker state and performance
+- `CacheDashboardMetrics`: Cache hit rates and efficiency
+- `RateLimiterDashboardMetrics`: Throttling and rate limit statistics
+- `ConcurrencyLimiterDashboardMetrics`: Concurrency and queue metrics
+- `SystemMetrics`: Complete system-wide aggregation
+
 ## Workflow Execution Patterns
 
 ### Sequential and Concurrent Phases
@@ -659,7 +994,6 @@ const branches = [
       if (branchResult.failedRequests > 0) {
         return { 
           action: PHASE_DECISION_ACTIONS.TERMINATE, 
-          terminateWorkflow: true,              // Terminate entire workflow
           metadata: { reason: 'Critical branch failed' }
         };
       }
@@ -1074,7 +1408,7 @@ await stableWorkflow(phases, {
   },
   
   // Monitor non-linear execution decisions
-  handlePhaseDecision: async ({ workflowId, decision, phaseResult }) => {
+  handlePhaseDecision: async ({ decision, phaseResult }) => {
     console.log(`Phase decision: ${decision.action}`);
     if (decision.targetPhaseId) {
       console.log(`Target: ${decision.targetPhaseId}`);
@@ -1285,12 +1619,13 @@ await stableWorkflow(pollingPhases, {
 ### Webhook Retry with Circuit Breaker
 
 ```typescript
-import { CircuitBreaker, REQUEST_METHODS } from '@emmvish/stable-request';
+import { CircuitBreaker, REQUEST_METHODS, RETRY_STRATEGIES } from '@emmvish/stable-request';
 
 const webhookBreaker = new CircuitBreaker({
-  failureThreshold: 3,
-  successThreshold: 2,
-  timeout: 30000
+  failureThresholdPercentage: 60,               // 60% failure rate triggers open
+  minimumRequests: 5,                           // Minimum 5 requests before evaluation
+  recoveryTimeoutMs: 30000,                     // 30s timeout in open state
+  successThresholdPercentage: 40                // 40% success rate closes circuit
 });
 
 async function sendWebhook(eventData: any) {

package/dist/core/stable-api-gateway.d.ts

@@ -1,3 +1,3 @@
-import { API_GATEWAY_OPTIONS, API_GATEWAY_REQUEST } from '../types/index.js';
-export declare function stableApiGateway<RequestDataType = any, ResponseDataType = any>(requests?: API_GATEWAY_REQUEST<RequestDataType, ResponseDataType>[], options?: API_GATEWAY_OPTIONS<RequestDataType, ResponseDataType>): Promise<import("../types/index.js").API_GATEWAY_RESPONSE<ResponseDataType>[]>;
+import { API_GATEWAY_OPTIONS, API_GATEWAY_REQUEST, API_GATEWAY_RESULT } from '../types/index.js';
+export declare function stableApiGateway<RequestDataType = any, ResponseDataType = any>(requests?: API_GATEWAY_REQUEST<RequestDataType, ResponseDataType>[], options?: API_GATEWAY_OPTIONS<RequestDataType, ResponseDataType>): Promise<API_GATEWAY_RESULT<ResponseDataType>>;
 //# sourceMappingURL=stable-api-gateway.d.ts.map

package/dist/core/stable-api-gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stable-api-gateway.d.ts","sourceRoot":"","sources":["../../src/core/stable-api-gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EAGtB,MAAM,mBAAmB,CAAC;AAO3B,wBAAsB,gBAAgB,CAAC,eAAe,GAAG,GAAG,EAAE,gBAAgB,GAAG,GAAG,EAChF,QAAQ,GAAE,mBAAmB,CAAC,eAAe,EAAE,gBAAgB,CAAC,EAAO,EACvE,OAAO,GAAE,mBAAmB,CAAC,eAAe,EAAE,gBAAgB,CAAM,iFA8BvE"}
+{"version":3,"file":"stable-api-gateway.d.ts","sourceRoot":"","sources":["../../src/core/stable-api-gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EAEnB,kBAAkB,EAOrB,MAAM,mBAAmB,CAAC;AAY3B,wBAAsB,gBAAgB,CAAC,eAAe,GAAG,GAAG,EAAE,gBAAgB,GAAG,GAAG,EAChF,QAAQ,GAAE,mBAAmB,CAAC,eAAe,EAAE,gBAAgB,CAAC,EAAO,EACvE,OAAO,GAAE,mBAAmB,CAAC,eAAe,EAAE,gBAAgB,CAAM,GACrE,OAAO,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,CA6F/C"}

package/dist/core/stable-api-gateway.js

@@ -1,8 +1,20 @@
-import { executeConcurrently, executeSequentially, extractCommonRequestConfigOptions as extractCommonOptions } from '../utilities/index.js';
+import { executeConcurrently, executeSequentially, extractCommonRequestConfigOptions as extractCommonOptions, MetricsAggregator } from '../utilities/index.js';
+import { CircuitBreaker, getGlobalCircuitBreaker } from '../utilities/circuit-breaker.js';
+import { getGlobalCacheManager } from '../utilities/cache-manager.js';
+import { getGlobalRateLimiter } from '../utilities/rate-limiter.js';
+import { getGlobalConcurrencyLimiter } from '../utilities/concurrency-limiter.js';
 export async function stableApiGateway(requests = [], options = {}) {
     const { concurrentExecution = true, stopOnFirstError = false, requestGroups = [], maxConcurrentRequests, rateLimit, circuitBreaker, } = options;
     if (!Array.isArray(requests) || requests.length === 0) {
-        return [];
+        const emptyResult = [];
+        emptyResult.metrics = {
+            totalRequests: 0,
+            successfulRequests: 0,
+            failedRequests: 0,
+            successRate: 0,
+            failureRate: 0
+        };
+        return emptyResult;
     }
     const requestExecutionOptions = {
         stopOnFirstError,
@@ -13,11 +25,53 @@ export async function stableApiGateway(requests = [], options = {}) {
         ...(circuitBreaker !== undefined && { circuitBreaker }),
         ...extractCommonOptions(options)
     };
+    let responses;
     if (concurrentExecution) {
-        return executeConcurrently(requests, requestExecutionOptions);
+        responses = await executeConcurrently(requests, requestExecutionOptions);
     }
     else {
-        return executeSequentially(requests, requestExecutionOptions);
+        responses = await executeSequentially(requests, requestExecutionOptions);
     }
+    const successfulRequests = responses.filter(r => r.success).length;
+    const failedRequests = responses.filter(r => !r.success).length;
+    const totalRequests = responses.length;
+    const result = responses;
+    result.metrics = {
+        totalRequests,
+        successfulRequests,
+        failedRequests,
+        successRate: totalRequests > 0 ? (successfulRequests / totalRequests) * 100 : 0,
+        failureRate: totalRequests > 0 ? (failedRequests / totalRequests) * 100 : 0,
+        requestGroups: MetricsAggregator.extractRequestGroupMetrics(responses)
+    };
+    const infrastructureMetrics = {};
+    if (circuitBreaker) {
+        const cb = circuitBreaker instanceof CircuitBreaker ? circuitBreaker : getGlobalCircuitBreaker();
+        if (cb) {
+            infrastructureMetrics.circuitBreaker = MetricsAggregator.extractCircuitBreakerMetrics(cb);
+        }
+    }
+    if (options.commonCache) {
+        const cache = getGlobalCacheManager();
+        if (cache) {
+            infrastructureMetrics.cache = MetricsAggregator.extractCacheMetrics(cache);
+        }
+    }
+    if (rateLimit) {
+        const rateLimiter = getGlobalRateLimiter();
+        if (rateLimiter) {
+            infrastructureMetrics.rateLimiter = MetricsAggregator.extractRateLimiterMetrics(rateLimiter);
+        }
+    }
+    if (maxConcurrentRequests) {
+        const concurrencyLimiter = getGlobalConcurrencyLimiter();
+        if (concurrencyLimiter) {
+            infrastructureMetrics.concurrencyLimiter = MetricsAggregator.extractConcurrencyLimiterMetrics(concurrencyLimiter);
+        }
+    }
+    if (Object.keys(infrastructureMetrics).length > 0) {
+        result.metrics.infrastructureMetrics = infrastructureMetrics;
+    }
+    return result;
 }
 //# sourceMappingURL=stable-api-gateway.js.map

package/dist/core/stable-api-gateway.js.map

@@ -1 +1 @@
-{"version":3,"file":"stable-api-gateway.js","sourceRoot":"","sources":["../../src/core/stable-api-gateway.ts"],"names":[],"mappings":"AAMA,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EACnB,iCAAiC,IAAI,oBAAoB,EAC5D,MAAM,uBAAuB,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAClC,WAAqE,EAAE,EACvE,UAAkE,EAAE;IAEpE,MAAM,EACF,mBAAmB,GAAG,IAAI,EAC1B,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,EAAE,EAClB,qBAAqB,EACrB,SAAS,EACT,cAAc,GACjB,GAAG,OAAO,CAAC;IAEZ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,CAAC;IACd,CAAC;IAED,MAAM,uBAAuB,GAAgF;QACzG,gBAAgB;QAChB,aAAa;QACb,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,GAAG,CAAC,qBAAqB,KAAK,SAAS,IAAI,EAAE,qBAAqB,EAAE,CAAC;QACrE,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,CAAC;QACvD,GAAG,oBAAoB,CAAoC,OAAO,CAAC;KACtE,CAAA;IAED,IAAI,mBAAmB,EAAE,CAAC;QACtB,OAAO,mBAAmB,CAAoC,QAAQ,EAAE,uBAAkG,CAAC,CAAC;IAChL,CAAC;SAAM,CAAC;QACJ,OAAO,mBAAmB,CAAoC,QAAQ,EAAE,uBAAkG,CAAC,CAAC;IAChL,CAAC;AACL,CAAC"}
+{"version":3,"file":"stable-api-gateway.js","sourceRoot":"","sources":["../../src/core/stable-api-gateway.ts"],"names":[],"mappings":"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"}

package/dist/core/stable-request.d.ts

@@ -1,3 +1,3 @@
-import { STABLE_REQUEST } from '../types/index.js';
-export declare function stableRequest<RequestDataType = any, ResponseDataType = any>(options: STABLE_REQUEST<RequestDataType, ResponseDataType>): Promise<ResponseDataType | boolean>;
+import { STABLE_REQUEST, STABLE_REQUEST_RESULT } from '../types/index.js';
+export declare function stableRequest<RequestDataType = any, ResponseDataType = any>(options: STABLE_REQUEST<RequestDataType, ResponseDataType>): Promise<STABLE_REQUEST_RESULT<ResponseDataType>>;
 //# sourceMappingURL=stable-request.d.ts.map

package/dist/core/stable-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stable-request.d.ts","sourceRoot":"","sources":["../../src/core/stable-request.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAe3B,wBAAsB,aAAa,CAAC,eAAe,GAAG,GAAG,EAAE,gBAAgB,GAAG,GAAG,EAC/E,OAAO,EAAE,cAAc,CAAC,eAAe,EAAE,gBAAgB,CAAC,GACzD,OAAO,CAAC,gBAAgB,GAAG,OAAO,CAAC,CAmVrC"}
+{"version":3,"file":"stable-request.d.ts","sourceRoot":"","sources":["../../src/core/stable-request.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,cAAc,EACd,qBAAqB,EAEtB,MAAM,mBAAmB,CAAC;AAkB3B,wBAAsB,aAAa,CAAC,eAAe,GAAG,GAAG,EAAE,gBAAgB,GAAG,GAAG,EAC/E,OAAO,EAAE,cAAc,CAAC,eAAe,EAAE,gBAAgB,CAAC,GACzD,OAAO,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,CAAC,CAqXlD"}

package/dist/core/stable-request.js

@@ -1,5 +1,5 @@
 import { RETRY_STRATEGIES, RESPONSE_ERRORS, CircuitBreakerState } from '../enums/index.js';
-import { CircuitBreaker, CircuitBreakerOpenError, executeWithPersistence, formatLogContext, generateAxiosRequestConfig, getNewDelayTime, delay, reqFn, safelyStringify, validateTrialModeProbabilities } from '../utilities/index.js';
+import { CircuitBreaker, CircuitBreakerOpenError, executeWithPersistence, formatLogContext, generateAxiosRequestConfig, getNewDelayTime, getGlobalCacheManager, delay, reqFn, safelyStringify, validateTrialModeProbabilities, MetricsAggregator } from '../utilities/index.js';
 export async function stableRequest(options) {
     const { preExecution = {
         preExecutionHook: ({ inputParams, commonBuffer }) => { },
@@ -30,6 +30,33 @@ export async function stableRequest(options) {
     const { reqData: givenReqData, responseAnalyzer = ({ reqData, data, trialMode = { enabled: false } }) => true, resReq = false, attempts: givenAttempts = 1, performAllAttempts = false, wait = 1000, maxAllowedWait = 60000, retryStrategy = RETRY_STRATEGIES.FIXED, logAllErrors = false, handleErrors = ({ reqData, errorLog, maxSerializableChars = 1000, executionContext }) => console.error(`${formatLogContext(executionContext)}stable-request:\n`, 'Request data:\n', safelyStringify(reqData, maxSerializableChars), '\nError log:\n', safelyStringify(errorLog, maxSerializableChars)), logAllSuccessfulAttempts = false, handleSuccessfulAttemptData = ({ reqData, successfulAttemptData, maxSerializableChars = 1000, executionContext }) => console.info(`${formatLogContext(executionContext)}stable-request:\n`, 'Request data:\n', safelyStringify(reqData, maxSerializableChars), '\nSuccessful attempt:\n', safelyStringify(successfulAttemptData, maxSerializableChars)), maxSerializableChars = 1000, finalErrorAnalyzer = ({ reqData, error, trialMode = { enabled: false } }) => false, trialMode = { enabled: false }, hookParams = {}, cache, circuitBreaker, jitter = 0, statePersistence } = options;
     let attempts = givenAttempts;
     const reqData = generateAxiosRequestConfig(givenReqData);
+    const requestStartTime = Date.now();
+    const errorLogs = [];
+    const successfulAttemptsList = [];
+    let totalAttemptsMade = 0;
+    const buildResult = (success, data, error) => {
+        const totalExecutionTime = Date.now() - requestStartTime;
+        const successfulAttemptsCount = successfulAttemptsList.length;
+        const failedAttemptsCount = totalAttemptsMade - successfulAttemptsCount;
+        return {
+            success,
+            ...(data !== undefined && { data }),
+            ...(error && { error }),
+            ...(errorLogs.length > 0 && { errorLogs }),
+            ...(successfulAttemptsList.length > 0 && { successfulAttempts: successfulAttemptsList }),
+            metrics: {
+                totalAttempts: totalAttemptsMade,
+                successfulAttempts: successfulAttemptsCount,
+                failedAttempts: failedAttemptsCount,
+                totalExecutionTime,
+                averageAttemptTime: totalAttemptsMade > 0 ? totalExecutionTime / totalAttemptsMade : 0,
+                infrastructureMetrics: {
+                    ...(circuitBreakerInstance && { circuitBreaker: MetricsAggregator.extractCircuitBreakerMetrics(circuitBreakerInstance) }),
+                    ...(cache && getGlobalCacheManager() && { cache: MetricsAggregator.extractCacheMetrics(getGlobalCacheManager()) })
+                }
+            }
+        };
+    };
     let circuitBreakerInstance = null;
     if (circuitBreaker) {
         circuitBreakerInstance = circuitBreaker instanceof CircuitBreaker
@@ -51,6 +78,7 @@ export async function stableRequest(options) {
         do {
             attempts--;
             const currentAttempt = maxAttempts - attempts;
+            totalAttemptsMade = currentAttempt;
             if (circuitBreakerInstance) {
                 const cbConfig = circuitBreakerInstance.getState().config;
                 if (cbConfig.trackIndividualAttempts || currentAttempt === 1) {
@@ -66,7 +94,7 @@ export async function stableRequest(options) {
                     if (trialMode.enabled) {
                         console.info(`${formatLogContext(executionContext)}stable-request: Response served from cache:\n`, safelyStringify(res?.data, maxSerializableChars));
                     }
-                    return resReq ? res?.data : true;
+                    return buildResult(true, resReq ? res?.data : true);
                 }
             }
             catch (attemptError) {
@@ -125,6 +153,7 @@ export async function stableRequest(options) {
                     executionTime: res.executionTime,
                     statusCode: res.statusCode
                 };
+                errorLogs.push(errorLog);
                 try {
                     await executeWithPersistence(handleErrors, {
                         reqData,
@@ -151,6 +180,7 @@ export async function stableRequest(options) {
                         executionTime: res.executionTime,
                         statusCode: res.statusCode
                     };
+                    successfulAttemptsList.push(successfulAttemptLog);
                     try {
                         await executeWithPersistence(handleSuccessfulAttemptData, {
                             reqData,
@@ -182,14 +212,14 @@ export async function stableRequest(options) {
             if (trialMode.enabled) {
                 console.info(`${formatLogContext(executionContext)}stable-request: Final response (performAllAttempts mode):\n`, safelyStringify(lastSuccessfulAttemptData, maxSerializableChars));
             }
-            return resReq ? lastSuccessfulAttemptData : true;
+            return buildResult(true, resReq ? lastSuccessfulAttemptData : true);
         }
         else if (res.ok) {
             if (trialMode.enabled) {
                 const finalResponse = res?.data ?? lastSuccessfulAttemptData;
                 console.info(`${formatLogContext(executionContext)}stable-request: Final response:\n`, safelyStringify(finalResponse, maxSerializableChars));
             }
-            return resReq ? res?.data ?? lastSuccessfulAttemptData : true;
+            return buildResult(true, resReq ? (res?.data ?? lastSuccessfulAttemptData) : true);
         }
         else {
             throw new Error(safelyStringify({
@@ -221,7 +251,7 @@ export async function stableRequest(options) {
             throw e;
         }
         else {
-            return false;
+            return buildResult(false, undefined, e.message || 'Request failed');
         }
     }
 }