@emmvish/stable-request 2.2.0 → 2.2.1

package/README.md

@@ -470,6 +470,196 @@ console.log(`Graph workflow success: ${result.success}`);
 
 ## Resilience Mechanisms
 
+### Execution Timeouts
+
+Set maximum execution time for functions to prevent indefinite hangs. Timeouts are enforced at multiple levels with proper inheritance.
+
+#### Function-Level Timeout
+
+Set timeout directly on a function:
+
+```typescript
+import { stableFunction } from '@emmvish/stable-request';
+
+const result = await stableFunction({
+  fn: async () => {
+    // Long-running operation
+    await processLargeDataset();
+    return 'success';
+  },
+  args: [],
+  returnResult: true,
+  executionTimeout: 5000, // 5 seconds max
+  attempts: 3,
+});
+
+if (!result.success && result.error?.includes('timeout')) {
+  console.log('Function timed out');
+}
+```
+
+#### Gateway-Level Timeout
+
+Apply timeout to all functions in a gateway:
+
+```typescript
+import { stableApiGateway, RequestOrFunction } from '@emmvish/stable-request';
+
+const results = await stableApiGateway(
+  [
+    {
+      type: RequestOrFunction.FUNCTION,
+      function: {
+        id: 'task1',
+        functionOptions: {
+          fn: async () => await task1(),
+          args: [],
+          // No timeout specified - inherits from gateway
+        },
+      },
+    },
+    {
+      type: RequestOrFunction.FUNCTION,
+      function: {
+        id: 'task2',
+        functionOptions: {
+          fn: async () => await task2(),
+          args: [],
+          executionTimeout: 10000, // Override gateway timeout
+        },
+      },
+    },
+  ],
+  {
+    commonExecutionTimeout: 3000, // Default 3s for all functions
+  }
+);
+```
+
+#### Request Group Timeout
+
+Different timeouts for different groups:
+
+```typescript
+const results = await stableApiGateway(
+  [
+    {
+      type: RequestOrFunction.FUNCTION,
+      function: {
+        id: 'critical',
+        groupId: 'criticalOps',
+        functionOptions: { fn: criticalOp, args: [] },
+      },
+    },
+    {
+      type: RequestOrFunction.FUNCTION,
+      function: {
+        id: 'background',
+        groupId: 'backgroundOps',
+        functionOptions: { fn: backgroundOp, args: [] },
+      },
+    },
+  ],
+  {
+    requestGroups: [
+      {
+        id: 'criticalOps',
+        commonConfig: {
+          commonExecutionTimeout: 1000, // Strict 1s timeout
+        },
+      },
+      {
+        id: 'backgroundOps',
+        commonConfig: {
+          commonExecutionTimeout: 30000, // Lenient 30s timeout
+        },
+      },
+    ],
+  }
+);
+```
+
+#### Workflow Phase Timeout
+
+Apply timeout at phase level in workflows:
+
+```typescript
+import { stableWorkflow } from '@emmvish/stable-request';
+
+const result = await stableWorkflow(
+  [
+    {
+      id: 'initialization',
+      functions: [
+        {
+          id: 'init',
+          functionOptions: {
+            fn: initializeSystem,
+            args: [],
+          },
+        },
+      ],
+      commonConfig: {
+        commonExecutionTimeout: 5000, // 5s for initialization
+      },
+    },
+    {
+      id: 'processing',
+      functions: [
+        {
+          id: 'process',
+          functionOptions: {
+            fn: processData,
+            args: [],
+          },
+        },
+      ],
+      commonConfig: {
+        commonExecutionTimeout: 30000, // 30s for processing
+      },
+    },
+  ],
+  {
+    commonExecutionTimeout: 10000, // Default for phases without specific timeout
+  }
+);
+```
+
+#### Timeout Precedence
+
+Timeouts follow the configuration cascade pattern:
+
+**Function > Group > Phase/Branch > Gateway**
+
+- Function-level `executionTimeout` always wins
+- If not set, inherits from request group's `commonExecutionTimeout`
+- If not set, inherits from phase/branch's `commonExecutionTimeout`
+- If not set, inherits from gateway's `commonExecutionTimeout`
+- If not set, no timeout is applied
+
+#### Timeout Behavior
+
+- Timeout applies to **entire function execution** including all retry attempts
+- When timeout is exceeded, function returns failed result with timeout error
+- Timeout does NOT stop execution mid-flight (no AbortController)
+- Metrics are still collected even when timeout occurs
+- Use with retries: timeout encompasses all attempts, not per-attempt
+
+```typescript
+const result = await stableFunction({
+  fn: slowFunction,
+  args: [],
+  attempts: 5,
+  wait: 1000,
+  executionTimeout: 3000, // Total time for all 5 attempts
+});
+
+// If each attempt takes 800ms:
+// - Attempt 1: 800ms
+// - Attempt 2: starts at 1800ms (after 1s wait)
+// - Attempt 3: would start at 3600ms → TIMEOUT at 3000ms
+```
+
 ### Retry Strategies
 
 When a request or function fails and is retryable, retry with configurable backoff.

package/dist/constants/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElF,eAAO,MAAM,wBAAwB,EAAE,CAAC,MAAM,mBAAmB,CAAC,EAqBjE,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,wBAAwB,EAqBrE,CAAC;AAEF,eAAO,MAAM,gCAAgC,gHAMnC,CAAC;AAEX,eAAO,MAAM,oCAAoC,2JASvC,CAAC;AAEX,eAAO,MAAM,iCAAiC,qPAapC,CAAC;AAEX,eAAO,MAAM,wCAAwC,6DAI3C,CAAC;AAEX,eAAO,MAAM,8BAA8B,2EAKjC,CAAC;AAEX,eAAO,MAAM,qCAAqC,2FAKxC,CAAC;AAEX,eAAO,MAAM,4CAA4C,2EAI/C,CAAC;AAEX,eAAO,MAAM,8BAA8B,iIAOjC,CAAC;AAEX,eAAO,MAAM,+BAA+B,oLAUlC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElF,eAAO,MAAM,wBAAwB,EAAE,CAAC,MAAM,mBAAmB,CAAC,EAsBjE,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,wBAAwB,EAqBrE,CAAC;AAEF,eAAO,MAAM,gCAAgC,gHAMnC,CAAC;AAEX,eAAO,MAAM,oCAAoC,2JASvC,CAAC;AAEX,eAAO,MAAM,iCAAiC,qPAapC,CAAC;AAEX,eAAO,MAAM,wCAAwC,6DAI3C,CAAC;AAEX,eAAO,MAAM,8BAA8B,2EAKjC,CAAC;AAEX,eAAO,MAAM,qCAAqC,2FAKxC,CAAC;AAEX,eAAO,MAAM,4CAA4C,2EAI/C,CAAC;AAEX,eAAO,MAAM,8BAA8B,iIAOjC,CAAC;AAEX,eAAO,MAAM,+BAA+B,oLAUlC,CAAC"}

package/dist/constants/index.js

@@ -19,6 +19,7 @@ export const extractCommonOptionsKeys = [
     'commonTrialMode',
     'commonCache',
     'commonStatePersistence',
+    'commonExecutionTimeout',
 ];
 export const PrepareApiRequestOptionsMapping = [
     { localKey: 'preExecution', commonKey: 'commonPreExecution', groupCommonKey: 'commonPreExecution', targetKey: 'preExecution' },

package/dist/constants/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,wBAAwB,GAAkC;IACnE,oBAAoB;IACpB,kBAAkB;IAClB,sBAAsB;IACtB,mBAAmB;IACnB,wBAAwB;IACxB,oBAAoB;IACpB,mCAAmC;IACnC,0BAA0B;IAC1B,cAAc;IACd,gBAAgB;IAChB,0BAA0B;IAC1B,YAAY;IACZ,qBAAqB;IACrB,cAAc;IACd,oBAAoB;IACpB,gCAAgC;IAChC,4BAA4B;IAC5B,iBAAiB;IACjB,aAAa;IACb,wBAAwB;CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,+BAA+B,GAA+B;IACvE,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,SAAS,EAAE,cAAc,EAAE;IAC9H,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,cAAc,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE;IACtH,EAAE,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,sBAAsB,EAAE,SAAS,EAAE,gBAAgB,EAAE;IACtI,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE;IACtG,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE;IAC9G,EAAE,QAAQ,EAAE,oBAAoB,EAAE,SAAS,EAAE,0BAA0B,EAAE,cAAc,EAAE,0BAA0B,EAAE,SAAS,EAAE,oBAAoB,EAAE;IACtJ,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE;IAC9F,EAAE,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,qBAAqB,EAAE,cAAc,EAAE,qBAAqB,EAAE,SAAS,EAAE,eAAe,EAAE;IAClI,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE;IACtG,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,SAAS,EAAE,cAAc,EAAE;IAC9H,EAAE,QAAQ,EAAE,0BAA0B,EAAE,SAAS,EAAE,gCAAgC,EAAE,cAAc,EAAE,gCAAgC,EAAE,SAAS,EAAE,0BAA0B,EAAE;IAC9K,EAAE,QAAQ,EAAE,sBAAsB,EAAE,SAAS,EAAE,4BAA4B,EAAE,cAAc,EAAE,4BAA4B,EAAE,SAAS,EAAE,sBAAsB,EAAE;IAC9J,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE;IAClH,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,wBAAwB,EAAE,cAAc,EAAE,wBAAwB,EAAE,SAAS,EAAE,kBAAkB,EAAE;IAC9I,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,SAAS,EAAE,cAAc,EAAE;IAC9H,EAAE,QAAQ,EAAE,6BAA6B,EAAE,SAAS,EAAE,mCAAmC,EAAE,cAAc,EAAE,mCAAmC,EAAE,SAAS,EAAE,6BAA6B,EAAE;IAC1L,EAAE,QAAQ,EAAE,oBAAoB,EAAE,SAAS,EAAE,0BAA0B,EAAE,cAAc,EAAE,0BAA0B,EAAE,SAAS,EAAE,oBAAoB,EAAE;IACtJ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE;IAClG,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE;IAClH,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,wBAAwB,EAAE,cAAc,EAAE,wBAAwB,EAAE,SAAS,EAAE,kBAAkB,EAAE;CACjJ,CAAC;AAEF,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC5C,eAAe;IACf,oBAAoB;IACpB,gBAAgB;IAChB,oBAAoB;IACpB,oBAAoB;CACd,CAAC;AAEX,MAAM,CAAC,MAAM,oCAAoC,GAAG;IAChD,eAAe;IACf,oBAAoB;IACpB,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,eAAe;IACf,YAAY;IACZ,wBAAwB;CAClB,CAAC;AAEX,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC7C,aAAa;IACb,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,oBAAoB;IACpB,gBAAgB;IAChB,oBAAoB;IACpB,oBAAoB;IACpB,eAAe;IACf,2BAA2B;IAC3B,YAAY;IACZ,qBAAqB;CACf,CAAC;AAEX,MAAM,CAAC,MAAM,wCAAwC,GAAG;IACpD,aAAa;IACb,eAAe;IACf,gBAAgB;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC1C,SAAS;IACT,UAAU;IACV,uBAAuB;IACvB,cAAc;CACR,CAAC;AAEX,MAAM,CAAC,MAAM,qCAAqC,GAAG;IACjD,cAAc;IACd,aAAa;IACb,uBAAuB;IACvB,sBAAsB;CAChB,CAAC;AAEX,MAAM,CAAC,MAAM,4CAA4C,GAAG;IACxD,uBAAuB;IACvB,aAAa;IACb,sBAAsB;CAChB,CAAC;AAEX,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,eAAe;IACf,oBAAoB;IACpB,gBAAgB;IAChB,oBAAoB;IACpB,oBAAoB;IACpB,eAAe;CACP,CAAC;AAEX,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,aAAa;IACb,iBAAiB;IACjB,cAAc;IACd,qBAAqB;IACrB,eAAe;IACf,oBAAoB;IACpB,gBAAgB;IAChB,oBAAoB;IACpB,eAAe;CACP,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"stable-function.d.ts","sourceRoot":"","sources":["../../src/core/stable-function.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,eAAe,EACf,sBAAsB,EAEvB,MAAM,mBAAmB,CAAC;AAmB3B,wBAAsB,cAAc,CAAC,KAAK,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,OAAO,GAAG,GAAG,EAC7E,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,GACvC,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CA8a1C"}
+{"version":3,"file":"stable-function.d.ts","sourceRoot":"","sources":["../../src/core/stable-function.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,eAAe,EACf,sBAAsB,EAEvB,MAAM,mBAAmB,CAAC;AAqB3B,wBAAsB,cAAc,CAAC,KAAK,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,OAAO,GAAG,GAAG,EAC7E,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,GACvC,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAkc1C"}

package/dist/core/stable-function.js

@@ -1,5 +1,5 @@
 import { RETRY_STRATEGIES, CircuitBreakerState } from '../enums/index.js';
-import { CircuitBreaker, CircuitBreakerOpenError, executeWithPersistence, formatLogContext, getGlobalFunctionCacheManager, getNewDelayTime, delay, fnExec, safelyStringify, validateTrialModeProbabilities, MetricsAggregator, MetricsValidator, RateLimiter, ConcurrencyLimiter } from '../utilities/index.js';
+import { CircuitBreaker, CircuitBreakerOpenError, executeWithPersistence, executeWithTimeout, TimeoutError, formatLogContext, getGlobalFunctionCacheManager, getNewDelayTime, delay, fnExec, safelyStringify, validateTrialModeProbabilities, MetricsAggregator, MetricsValidator, RateLimiter, ConcurrencyLimiter } from '../utilities/index.js';
 export async function stableFunction(options) {
     const { preExecution = {
         preExecutionHook: ({ inputParams, commonBuffer }) => { },
@@ -27,7 +27,7 @@ export async function stableFunction(options) {
             throw e;
         }
     }
-    const { fn, args, responseAnalyzer = ({ data, trialMode = { enabled: false } }) => true, returnResult = false, attempts: givenAttempts = 1, performAllAttempts = false, wait = 1000, maxAllowedWait = 60000, retryStrategy = RETRY_STRATEGIES.FIXED, logAllErrors = false, handleErrors = ({ fn, args, errorLog, maxSerializableChars = 1000, executionContext }) => console.error(`${formatLogContext(executionContext)}stable-request:\n`, `Function: ${fn.name || 'anonymous'}\n`, 'Args:\n', safelyStringify(args, maxSerializableChars), '\nError log:\n', safelyStringify(errorLog, maxSerializableChars)), logAllSuccessfulAttempts = false, handleSuccessfulAttemptData = ({ fn, args, successfulAttemptData, maxSerializableChars = 1000, executionContext }) => console.info(`${formatLogContext(executionContext)}stable-request:\n`, `Function: ${fn.name || 'anonymous'}\n`, 'Args:\n', safelyStringify(args, maxSerializableChars), '\nSuccessful attempt:\n', safelyStringify(successfulAttemptData, maxSerializableChars)), maxSerializableChars = 1000, finalErrorAnalyzer = ({ fn, args, error, trialMode = { enabled: false } }) => false, trialMode = { enabled: false }, hookParams = {}, cache, circuitBreaker, jitter = 0, statePersistence, rateLimit, maxConcurrentRequests } = options;
+    const { fn, args, responseAnalyzer = ({ data, trialMode = { enabled: false } }) => true, returnResult = false, attempts: givenAttempts = 1, performAllAttempts = false, wait = 1000, maxAllowedWait = 60000, retryStrategy = RETRY_STRATEGIES.FIXED, logAllErrors = false, handleErrors = ({ fn, args, errorLog, maxSerializableChars = 1000, executionContext }) => console.error(`${formatLogContext(executionContext)}stable-request:\n`, `Function: ${fn.name || 'anonymous'}\n`, 'Args:\n', safelyStringify(args, maxSerializableChars), '\nError log:\n', safelyStringify(errorLog, maxSerializableChars)), logAllSuccessfulAttempts = false, handleSuccessfulAttemptData = ({ fn, args, successfulAttemptData, maxSerializableChars = 1000, executionContext }) => console.info(`${formatLogContext(executionContext)}stable-request:\n`, `Function: ${fn.name || 'anonymous'}\n`, 'Args:\n', safelyStringify(args, maxSerializableChars), '\nSuccessful attempt:\n', safelyStringify(successfulAttemptData, maxSerializableChars)), maxSerializableChars = 1000, finalErrorAnalyzer = ({ fn, args, error, trialMode = { enabled: false } }) => false, trialMode = { enabled: false }, hookParams = {}, cache, circuitBreaker, jitter = 0, statePersistence, rateLimit, maxConcurrentRequests, executionTimeout } = options;
     let attempts = givenAttempts;
     const functionStartTime = Date.now();
     const errorLogs = [];
@@ -76,210 +76,226 @@ export async function stableFunction(options) {
     if (maxConcurrentRequests && maxConcurrentRequests > 0) {
         concurrencyLimiterInstance = new ConcurrencyLimiter(maxConcurrentRequests);
     }
-    try {
-        validateTrialModeProbabilities(trialMode);
-        let res = {
-            ok: false,
-            isRetryable: true,
-            timestamp: new Date().toISOString(),
-            executionTime: 0
-        };
-        const maxAttempts = attempts;
-        let lastSuccessfulAttemptData = undefined;
-        let hadAtLeastOneSuccess = false;
-        do {
-            attempts--;
-            const currentAttempt = maxAttempts - attempts;
-            totalAttemptsMade = currentAttempt;
-            if (circuitBreakerInstance) {
-                const cbConfig = circuitBreakerInstance.getState().config;
-                if (cbConfig.trackIndividualAttempts || currentAttempt === 1) {
-                    const canExecute = await circuitBreakerInstance.canExecute();
-                    if (!canExecute) {
-                        throw new CircuitBreakerOpenError(`${formatLogContext(executionContext)}stable-request: Circuit breaker is ${circuitBreakerInstance.getState().state}. Function execution blocked at attempt ${currentAttempt}.`);
+    const executeFunction = async () => {
+        try {
+            validateTrialModeProbabilities(trialMode);
+            let res = {
+                ok: false,
+                isRetryable: true,
+                timestamp: new Date().toISOString(),
+                executionTime: 0
+            };
+            const maxAttempts = attempts;
+            let lastSuccessfulAttemptData = undefined;
+            let hadAtLeastOneSuccess = false;
+            do {
+                attempts--;
+                const currentAttempt = maxAttempts - attempts;
+                totalAttemptsMade = currentAttempt;
+                if (circuitBreakerInstance) {
+                    const cbConfig = circuitBreakerInstance.getState().config;
+                    if (cbConfig.trackIndividualAttempts || currentAttempt === 1) {
+                        const canExecute = await circuitBreakerInstance.canExecute();
+                        if (!canExecute) {
+                            throw new CircuitBreakerOpenError(`${formatLogContext(executionContext)}stable-request: Circuit breaker is ${circuitBreakerInstance.getState().state}. Function execution blocked at attempt ${currentAttempt}.`);
+                        }
                     }
                 }
-            }
-            try {
-                const executeAttempt = async () => {
-                    return await fnExec(fn, args, returnResult, maxSerializableChars, trialMode, cache, executionContext);
-                };
-                if (rateLimiterInstance && concurrencyLimiterInstance) {
-                    res = await rateLimiterInstance.execute(() => concurrencyLimiterInstance.execute(executeAttempt));
-                }
-                else if (rateLimiterInstance) {
-                    res = await rateLimiterInstance.execute(executeAttempt);
-                }
-                else if (concurrencyLimiterInstance) {
-                    res = await concurrencyLimiterInstance.execute(executeAttempt);
-                }
-                else {
-                    res = await executeAttempt();
-                }
-                if (res.fromCache && res.ok) {
-                    if (trialMode.enabled) {
-                        console.info(`${formatLogContext(executionContext)}stable-request: Response served from cache:\n`, safelyStringify(res?.data, maxSerializableChars));
+                try {
+                    const executeAttempt = async () => {
+                        return await fnExec(fn, args, returnResult, maxSerializableChars, trialMode, cache, executionContext);
+                    };
+                    if (rateLimiterInstance && concurrencyLimiterInstance) {
+                        res = await rateLimiterInstance.execute(() => concurrencyLimiterInstance.execute(executeAttempt));
+                    }
+                    else if (rateLimiterInstance) {
+                        res = await rateLimiterInstance.execute(executeAttempt);
+                    }
+                    else if (concurrencyLimiterInstance) {
+                        res = await concurrencyLimiterInstance.execute(executeAttempt);
+                    }
+                    else {
+                        res = await executeAttempt();
+                    }
+                    if (res.fromCache && res.ok) {
+                        if (trialMode.enabled) {
+                            console.info(`${formatLogContext(executionContext)}stable-request: Response served from cache:\n`, safelyStringify(res?.data, maxSerializableChars));
+                        }
+                        return buildResult(true, returnResult ? res?.data : true);
                     }
-                    return buildResult(true, returnResult ? res?.data : true);
                 }
-            }
-            catch (attemptError) {
-                if (attemptError instanceof CircuitBreakerOpenError) {
+                catch (attemptError) {
+                    if (attemptError instanceof CircuitBreakerOpenError) {
+                        throw attemptError;
+                    }
+                    if (circuitBreakerInstance && circuitBreakerInstance.getState().config.trackIndividualAttempts) {
+                        circuitBreakerInstance.recordAttemptFailure();
+                        if (circuitBreakerInstance.getState().state === CircuitBreakerState.OPEN) {
+                            throw new CircuitBreakerOpenError(`${formatLogContext(executionContext)}stable-request: Circuit breaker opened after attempt ${currentAttempt}. No further retries.`);
+                        }
+                    }
                     throw attemptError;
                 }
-                if (circuitBreakerInstance && circuitBreakerInstance.getState().config.trackIndividualAttempts) {
-                    circuitBreakerInstance.recordAttemptFailure();
-                    if (circuitBreakerInstance.getState().state === CircuitBreakerState.OPEN) {
-                        throw new CircuitBreakerOpenError(`${formatLogContext(executionContext)}stable-request: Circuit breaker opened after attempt ${currentAttempt}. No further retries.`);
+                const originalResOk = res.ok;
+                let performNextAttempt = false;
+                if (res.ok) {
+                    try {
+                        performNextAttempt = !(await executeWithPersistence(responseAnalyzer, {
+                            fn,
+                            args,
+                            data: res?.data,
+                            trialMode,
+                            params: hookParams?.responseAnalyzerParams,
+                            preExecutionResult,
+                            commonBuffer,
+                            executionContext
+                        }, statePersistence, executionContext || {}, commonBuffer));
                     }
-                }
-                throw attemptError;
-            }
-            const originalResOk = res.ok;
-            let performNextAttempt = false;
-            if (res.ok) {
-                try {
-                    performNextAttempt = !(await executeWithPersistence(responseAnalyzer, {
-                        fn,
-                        args,
-                        data: res?.data,
-                        trialMode,
-                        params: hookParams?.responseAnalyzerParams,
-                        preExecutionResult,
-                        commonBuffer,
-                        executionContext
-                    }, statePersistence, executionContext || {}, commonBuffer));
-                }
-                catch (e) {
-                    console.error(`${formatLogContext(executionContext)}stable-request: Unable to analyze the response returned on attempt #${currentAttempt}. Response: ${safelyStringify(res?.data, maxSerializableChars)}`);
-                    console.error(`${formatLogContext(executionContext)}stable-request: Error message provided by your responseAnalyzer: ${safelyStringify(e.message, maxSerializableChars)}`);
-                    performNextAttempt = true;
-                }
-            }
-            if (circuitBreakerInstance && circuitBreakerInstance.getState().config.trackIndividualAttempts) {
-                if (res.ok && !performNextAttempt) {
-                    circuitBreakerInstance.recordAttemptSuccess();
-                }
-                else if (!res.ok || performNextAttempt) {
-                    circuitBreakerInstance.recordAttemptFailure();
-                    if (circuitBreakerInstance.getState().state === CircuitBreakerState.OPEN) {
-                        throw new CircuitBreakerOpenError(`${formatLogContext(executionContext)}stable-request: Circuit breaker opened after attempt ${currentAttempt}/${maxAttempts}. Blocking further retries.`);
+                    catch (e) {
+                        console.error(`${formatLogContext(executionContext)}stable-request: Unable to analyze the response returned on attempt #${currentAttempt}. Response: ${safelyStringify(res?.data, maxSerializableChars)}`);
+                        console.error(`${formatLogContext(executionContext)}stable-request: Error message provided by your responseAnalyzer: ${safelyStringify(e.message, maxSerializableChars)}`);
+                        performNextAttempt = true;
                     }
                 }
-            }
-            if ((!res.ok || (res.ok && performNextAttempt)) && logAllErrors) {
-                const errorLog = {
-                    timestamp: res.timestamp,
-                    attempt: `${currentAttempt}/${maxAttempts}`,
-                    error: res?.error ??
-                        `${formatLogContext(executionContext)}stable-request: The response did not match your expectations! Response: ${safelyStringify(res?.data, maxSerializableChars)}`,
-                    isRetryable: res.isRetryable,
-                    executionTime: res.executionTime
-                };
-                errorLogs.push(errorLog);
-                try {
-                    await executeWithPersistence(handleErrors, {
-                        fn,
-                        args,
-                        errorLog,
-                        maxSerializableChars,
-                        params: hookParams?.handleErrorsParams,
-                        preExecutionResult,
-                        commonBuffer,
-                        executionContext
-                    }, statePersistence, executionContext || {}, commonBuffer);
-                }
-                catch (e) {
-                    console.error(`${formatLogContext(executionContext)}stable-request: Unable to report errors due to issues with error handler! Error message provided by your handleErrors: ${safelyStringify(e.message, maxSerializableChars)}`);
+                if (circuitBreakerInstance && circuitBreakerInstance.getState().config.trackIndividualAttempts) {
+                    if (res.ok && !performNextAttempt) {
+                        circuitBreakerInstance.recordAttemptSuccess();
+                    }
+                    else if (!res.ok || performNextAttempt) {
+                        circuitBreakerInstance.recordAttemptFailure();
+                        if (circuitBreakerInstance.getState().state === CircuitBreakerState.OPEN) {
+                            throw new CircuitBreakerOpenError(`${formatLogContext(executionContext)}stable-request: Circuit breaker opened after attempt ${currentAttempt}/${maxAttempts}. Blocking further retries.`);
+                        }
+                    }
                 }
-            }
-            if (res.ok && !performNextAttempt) {
-                hadAtLeastOneSuccess = true;
-                lastSuccessfulAttemptData = res?.data;
-                successfulAttemptsCount++;
-                if (logAllSuccessfulAttempts) {
-                    const successfulAttemptLog = {
-                        attempt: `${currentAttempt}/${maxAttempts}`,
+                if ((!res.ok || (res.ok && performNextAttempt)) && logAllErrors) {
+                    const errorLog = {
                         timestamp: res.timestamp,
-                        data: res?.data,
+                        attempt: `${currentAttempt}/${maxAttempts}`,
+                        error: res?.error ??
+                            `${formatLogContext(executionContext)}stable-request: The response did not match your expectations! Response: ${safelyStringify(res?.data, maxSerializableChars)}`,
+                        isRetryable: res.isRetryable,
                         executionTime: res.executionTime
                     };
-                    successfulAttemptsList.push(successfulAttemptLog);
+                    errorLogs.push(errorLog);
                     try {
-                        await executeWithPersistence(handleSuccessfulAttemptData, {
+                        await executeWithPersistence(handleErrors, {
                             fn,
                             args,
-                            successfulAttemptData: successfulAttemptLog,
+                            errorLog,
                             maxSerializableChars,
-                            params: hookParams?.handleSuccessfulAttemptDataParams,
+                            params: hookParams?.handleErrorsParams,
                             preExecutionResult,
                             commonBuffer,
                             executionContext
                         }, statePersistence, executionContext || {}, commonBuffer);
                     }
                     catch (e) {
-                        console.error(`${formatLogContext(executionContext)}stable-request: Unable to report successful attempts due to issues with successful attempt data handler! Error message provided by your handleSuccessfulAttemptData: ${safelyStringify(e.message, maxSerializableChars)}`);
+                        console.error(`${formatLogContext(executionContext)}stable-request: Unable to report errors due to issues with error handler! Error message provided by your handleErrors: ${safelyStringify(e.message, maxSerializableChars)}`);
                     }
                 }
+                if (res.ok && !performNextAttempt) {
+                    hadAtLeastOneSuccess = true;
+                    lastSuccessfulAttemptData = res?.data;
+                    successfulAttemptsCount++;
+                    if (logAllSuccessfulAttempts) {
+                        const successfulAttemptLog = {
+                            attempt: `${currentAttempt}/${maxAttempts}`,
+                            timestamp: res.timestamp,
+                            data: res?.data,
+                            executionTime: res.executionTime
+                        };
+                        successfulAttemptsList.push(successfulAttemptLog);
+                        try {
+                            await executeWithPersistence(handleSuccessfulAttemptData, {
+                                fn,
+                                args,
+                                successfulAttemptData: successfulAttemptLog,
+                                maxSerializableChars,
+                                params: hookParams?.handleSuccessfulAttemptDataParams,
+                                preExecutionResult,
+                                commonBuffer,
+                                executionContext
+                            }, statePersistence, executionContext || {}, commonBuffer);
+                        }
+                        catch (e) {
+                            console.error(`${formatLogContext(executionContext)}stable-request: Unable to report successful attempts due to issues with successful attempt data handler! Error message provided by your handleSuccessfulAttemptData: ${safelyStringify(e.message, maxSerializableChars)}`);
+                        }
+                    }
+                }
+                if (performNextAttempt && res.isRetryable) {
+                    res.ok = false;
+                }
+                if (attempts > 0 &&
+                    ((!originalResOk && res.isRetryable) ||
+                        (originalResOk && performNextAttempt) ||
+                        performAllAttempts)) {
+                    await delay(getNewDelayTime(retryStrategy, wait, currentAttempt, jitter), maxAllowedWait);
+                }
+            } while (attempts > 0 &&
+                ((res.isRetryable && !res.ok) || performAllAttempts));
+            if (performAllAttempts && hadAtLeastOneSuccess) {
+                if (trialMode.enabled) {
+                    console.info(`${formatLogContext(executionContext)}stable-request: Final response (performAllAttempts mode):\n`, safelyStringify(lastSuccessfulAttemptData, maxSerializableChars));
+                }
+                return buildResult(true, returnResult ? lastSuccessfulAttemptData : true);
             }
-            if (performNextAttempt && res.isRetryable) {
-                res.ok = false;
-            }
-            if (attempts > 0 &&
-                ((!originalResOk && res.isRetryable) ||
-                    (originalResOk && performNextAttempt) ||
-                    performAllAttempts)) {
-                await delay(getNewDelayTime(retryStrategy, wait, currentAttempt, jitter), maxAllowedWait);
+            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 buildResult(true, returnResult ? (res?.data ?? lastSuccessfulAttemptData) : true);
             }
-        } while (attempts > 0 &&
-            ((res.isRetryable && !res.ok) || performAllAttempts));
-        if (performAllAttempts && hadAtLeastOneSuccess) {
-            if (trialMode.enabled) {
-                console.info(`${formatLogContext(executionContext)}stable-request: Final response (performAllAttempts mode):\n`, safelyStringify(lastSuccessfulAttemptData, maxSerializableChars));
+            else {
+                throw new Error(safelyStringify({
+                    error: res?.error,
+                    'Function': fn.name || 'anonymous',
+                    'Args': args,
+                }, maxSerializableChars));
             }
-            return buildResult(true, returnResult ? lastSuccessfulAttemptData : true);
         }
-        else if (res.ok) {
+        catch (e) {
             if (trialMode.enabled) {
-                const finalResponse = res?.data ?? lastSuccessfulAttemptData;
-                console.info(`${formatLogContext(executionContext)}stable-request: Final response:\n`, safelyStringify(finalResponse, maxSerializableChars));
+                console.error(`${formatLogContext(executionContext)}stable-request: Final error:\n`, e.message);
+            }
+            let errorAnalysisResult = false;
+            try {
+                errorAnalysisResult = await executeWithPersistence(finalErrorAnalyzer, {
+                    fn,
+                    args,
+                    error: e,
+                    trialMode,
+                    params: hookParams?.finalErrorAnalyzerParams,
+                    preExecutionResult,
+                    commonBuffer,
+                    executionContext
+                }, statePersistence, executionContext || {}, commonBuffer);
+            }
+            catch (errorAnalysisError) {
+                console.error(`${formatLogContext(executionContext)}stable-request: Unable to analyze the final error returned. Error message provided by your finalErrorAnalyzer: ${safelyStringify(errorAnalysisError.message, maxSerializableChars)}`);
+            }
+            if (!errorAnalysisResult) {
+                throw e;
+            }
+            else {
+                return buildResult(false, undefined, e.message || 'Function execution failed');
             }
-            return buildResult(true, returnResult ? (res?.data ?? lastSuccessfulAttemptData) : true);
+        }
+    };
+    try {
+        if (executionTimeout && executionTimeout > 0) {
+            return await executeWithTimeout(executeFunction(), executionTimeout, `${formatLogContext(executionContext)}stable-request: Function execution exceeded timeout of ${executionTimeout}ms`);
         }
         else {
-            throw new Error(safelyStringify({
-                error: res?.error,
-                'Function': fn.name || 'anonymous',
-                'Args': args,
-            }, maxSerializableChars));
+            return await executeFunction();
         }
     }
     catch (e) {
-        if (trialMode.enabled) {
-            console.error(`${formatLogContext(executionContext)}stable-request: Final error:\n`, e.message);
-        }
-        let errorAnalysisResult = false;
-        try {
-            errorAnalysisResult = await executeWithPersistence(finalErrorAnalyzer, {
-                fn,
-                args,
-                error: e,
-                trialMode,
-                params: hookParams?.finalErrorAnalyzerParams,
-                preExecutionResult,
-                commonBuffer,
-                executionContext
-            }, statePersistence, executionContext || {}, commonBuffer);
-        }
-        catch (errorAnalysisError) {
-            console.error(`${formatLogContext(executionContext)}stable-request: Unable to analyze the final error returned. Error message provided by your finalErrorAnalyzer: ${safelyStringify(errorAnalysisError.message, maxSerializableChars)}`);
-        }
-        if (!errorAnalysisResult) {
-            throw e;
-        }
-        else {
-            return buildResult(false, undefined, e.message || 'Function execution failed');
+        if (e instanceof TimeoutError) {
+            return buildResult(false, undefined, e.message);
         }
+        throw e;
     }
 }
 //# sourceMappingURL=stable-function.js.map