@izara_project/izara-core-library-asynchronous-flow 1.0.42 → 1.0.44

package/package.json

@@ -3,7 +3,7 @@
   "author": "Sven Mason <thebarbariansven@gmail.com>",
   "license": "AGPL-3.0-or-later",
   "homepage": "https://bitbucket.org/izara-core-libraries/izara-core-library-asynchronous-flow#readme",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "description": "Shared asynchronous flow logic",
   "type": "module",
   "main": "index.js",
@@ -16,9 +16,9 @@
   },
   "devDependencies": {
     "@izara_project/izara-core-library-core": "^1.0.32",
-    "@izara_project/izara-core-library-dynamodb": "^1.0.20",
+    "@izara_project/izara-core-library-dynamodb": "^1.0.21",
     "@izara_project/izara-core-library-external-request": "^1.0.30",
-    "@izara_project/izara-core-library-logger": "^1.0.9",
+    "@izara_project/izara-core-library-logger": "^1.0.11",
     "@izara_project/izara-core-library-sns": "^1.0.8",
     "@izara_project/izara-core-library-sqs": "^1.0.7",
     "@izara_project/izara-shared-core": "^1.0.13"
@@ -30,6 +30,7 @@
     "@izara_project/izara-core-library-logger": "^1.0.9",
     "@izara_project/izara-core-library-sns": "^1.0.8",
     "@izara_project/izara-core-library-sqs": "^1.0.7",
-    "@izara_project/izara-shared-core": "^1.0.12"
+    "@izara_project/izara-shared-core": "^1.0.12",
+    "ws": "^8.16.0"
   }
 }

package/src/asyncFlowSharedLib.js

@@ -36,20 +36,25 @@ import { identifierUuid } from '@izara_project/izara-shared-core';
  * @returns {string}
  */
 function _joinPrefixAndId(id, prefix = '') {
-  if (!prefix) return id;
+  if (!prefix) {
+    return id;
+  }
+
+  let cleanPrefix = prefix;
+  if (prefix.endsWith('_')) {
+    cleanPrefix = prefix.slice(0, -1);
+  }
 
-  const cleanPrefix = prefix.endsWith('_') ? prefix.slice(0, -1) : prefix;
-  const cleanId = id.startsWith('_') ? id.slice(1) : id;
+  let cleanId = id;
+  if (id.startsWith('_')) {
+    cleanId = id.slice(1);
+  }
 
   return `${cleanPrefix}_${cleanId}`;
 }
 
 /**
  * Create awaitingStepId by concatenating prefix and partitionKey.
- * If prefix ends with an underscore, it's removed before concatenation.
- * If partitionKey starts with an underscore, it's removed before concatenation.
- * This ensures a clean "PREFIX_PARTITIONKEY" format without double underscores.
- *
  * @param {string} partitionKey
  * @param {string} [prefix='']
  * @returns {string}
@@ -60,10 +65,6 @@ function createAwaitingStepId(partitionKey, prefix = '') {
 
 /**
  * Create pendingStepId by concatenating prefix and identifierId.
- * If prefix ends with an underscore, it's removed before concatenation.
- * If identifierId starts with an underscore, it's removed before concatenation.
- * This ensures a clean "PREFIX_IDENTIFIER" format without double underscores.
- *
  * @param {string} identifierId
  * @param {string} [prefix='']
  * @returns {string}
@@ -73,7 +74,7 @@ function createPendingStepId(identifierId, prefix = '') {
 }
 
 /**
- * Create a field name for storing the unique-request id, with optional prefix.
+ * Create field name for storing unique-request id, with optional prefix.
  * @param {string} prefix
  * @param {string} [uniqueRequestIdFieldName='UniqueRequestId']
  * @returns {string}
@@ -117,26 +118,29 @@ function createParentFlowId(prefix = '') {
 }
 
 /**
- * Remove the known prefix from a pendingStepId and validate it is not equal to the prefix.
- * If prefix is empty, the original ID is returned.
+ * Remove known prefix from pendingStepId and validate not equal to prefix.
  * @param {string} pendingStepId
  * @param {string} [prefix=""]
  * @returns {string}
- * @throws {NoRetryError} If the stripped value equals the prefix (invalid)
+ * @throws {NoRetryError} If stripped value equals prefix (invalid)
  */
 function explodePendingStepId(pendingStepId, prefix = '') {
-  if (!pendingStepId) throw new NoRetryError('pendingStepId is required');
-  if (!prefix) return pendingStepId;
+  if (!pendingStepId) {
+    throw new NoRetryError('pendingStepId is required');
+  }
+  if (!prefix) {
+    return pendingStepId;
+  }
 
-  const identifierId = pendingStepId.slice(prefix.length);
-  if (identifierId === prefix)
+  const identifierId = pendingStepId.slice(prefix.length + 1);
+  if (identifierId === prefix) {
     throw new NoRetryError('IdentifierId should not be like prefix.');
+  }
 
-  Logger.debug('return explode:', identifierId);
+  Logger.debug('return explode:', { identifierId });
   return identifierId;
 }
 
-// copy from izara-core-library-trigger-cache
 /**
  * Checks if record has uniqueRequestId set, if not set to this requests uniqueRequestId and continue to process
  * if already set check if matches this request uniqueRequestId, if yes continue to process, if not then stop processing
@@ -161,11 +165,11 @@ function explodePendingStepId(pendingStepId, prefix = '') {
  *
  * @async
  * @param {IzContext} _izContext
- * @param {string} tableName - Logical table name known by dynamodbSharedLib.tableName
- * @param {DynamoKey} primaryKey - Primary key for the target record
+ * @param {string} tableName - Logical table name
+ * @param {DynamoKey} primaryKey - Primary key for target record
  * @param {string} [prefix=''] - Optional field-name prefix
- * @param {string|null} [overwriteUniqueRequestId=null] - If provided, use this as the "current" unique request id
- * @param {string} [uniqueRequestIdFieldName="UniqueRequestId"] - Base field name before prefix
+ * @param {string|null} [overwriteUniqueRequestId=null] - Overwrite ID
+ * @param {string} [uniqueRequestIdFieldName="UniqueRequestId"] - Base name
  * @returns {Promise<[UniqueRequestStatus, Attrs]>}
  * @throws {NoRetryError} If unable to set uniqueRequestId after 2 tries
  */
@@ -178,7 +182,7 @@ async function checkUniqueRequestProcessing(
   uniqueRequestIdFieldName = 'UniqueRequestId' // if set will check/add this fieldname with _izContext.uniqueRequestId value
 ) {
   _izContext.logger.debug(
-    '[Lib:AsyncFlow:checkUniqueRequestProcessing] Input: ',
+    '[Lib:AsyncFlow:checkUniqueRequestProcessing] Input:',
     {
       _izContext,
       tableName,
@@ -194,13 +198,15 @@ async function checkUniqueRequestProcessing(
   }
 
   try {
-    _izContext.logger.debug(
-      'current uniqueRequestId:',
-      _izContext.uniqueRequestId
-    );
+    _izContext.logger.debug('[Lib:checkUniqueRequestProcessing] reqId', {
+      uniqueRequestId: _izContext.uniqueRequestId
+    });
+
+    let uniqueRequestId = overwriteUniqueRequestId;
+    if (!uniqueRequestId) {
+      uniqueRequestId = _izContext.uniqueRequestId;
+    }
 
-    const uniqueRequestId =
-      overwriteUniqueRequestId || _izContext.uniqueRequestId;
     uniqueRequestIdFieldName = createFieldNameUniqueRequestId(
       prefix,
       uniqueRequestIdFieldName
@@ -213,11 +219,17 @@ async function checkUniqueRequestProcessing(
         primaryKey
       );
 
-      if (!existingRecord) return ['recordNotFound', {}];
+      if (!existingRecord) {
+        return ['recordNotFound', {}];
+      }
 
       const currentReqId = existingRecord[uniqueRequestIdFieldName];
-      if (currentReqId === uniqueRequestId) return ['process', existingRecord];
-      if (currentReqId) return ['stop', existingRecord];
+      if (currentReqId === uniqueRequestId) {
+        return ['process', existingRecord];
+      }
+      if (currentReqId) {
+        return ['stop', existingRecord];
+      }
 
       try {
         const updateRecord = await dynamodbSharedLib.updateItem(
@@ -245,17 +257,22 @@ async function checkUniqueRequestProcessing(
         );
         return ['process', updateRecord];
       } catch (err) {
-        if (err.name === 'ConditionalCheckFailedException') continue;
+        if (err.name === 'ConditionalCheckFailedException') {
+          continue;
+        }
         throw err;
       }
     }
 
     throw new NoRetryError(
-      `unable to set uniqueRequestId in table ${tableName}, record`,
-      primaryKey
+      `unable to set uniqueRequestId in table ${tableName}`,
+      { primaryKey }
     );
   } catch (err) {
-    _izContext.logger.error('ERROR checkUniqueRequestProcessing:', err);
+    _izContext.logger.error(
+      '[Lib:checkUniqueRequestProcessing] Error',
+      { err }
+    );
     throw err;
   }
 }
@@ -266,9 +283,9 @@ async function checkUniqueRequestProcessing(
  * Returns [isSameOrUnset, uniqueRequestIdWhenComplete].
  * @async
  * @param {IzContext} _izContext
- * @param {string} fullMainTableName - Fully resolved table name (not logical)
+ * @param {string} fullMainTableName - Fully resolved table name
  * @param {DynamoKey} keyValues
- * @param {number|string} timeCacheComplete - Caller’s expected cache mark
+ * @param {number|string} timeCacheComplete - Expected cache mark
  * @param {string} prefix - Field prefix used in cache fields
  * @returns {Promise<[boolean, string|undefined]>}
  */
@@ -279,7 +296,7 @@ async function checkTimeCacheComplete(
   timeCacheComplete,
   prefix
 ) {
-  _izContext.logger.debug('[Lib:AsyncFlow:checkTimeCacheComplete] Input: ', {
+  _izContext.logger.debug('[Lib:AsyncFlow:checkTimeCacheComplete] Input:', {
     _izContext,
     fullMainTableName,
     keyValues,
@@ -289,11 +306,12 @@ async function checkTimeCacheComplete(
 
   if (!fullMainTableName || !keyValues || !timeCacheComplete || !prefix) {
     throw new NoRetryError(
-      'fullMainTableName, keyValues, timeCacheComplete and prefix are required'
+      'fullMainTableName, keyValues, timeCacheComplete' +
+      ' and prefix are required'
     );
   }
 
-  let [returnValue, newTimeCacheComplete, uniqueRequestId] =
+  const [returnValue, , uniqueRequestId] =
     await checkAndGetTimeCacheComplete(
       _izContext,
       fullMainTableName,
@@ -310,7 +328,7 @@ async function checkTimeCacheComplete(
  * Otherwise returns [true, storedValue, uniqueRequestId].
  * @async
  * @param {IzContext} _izContext
- * @param {string} fullMainTableName - Fully resolved table name (not logical)
+ * @param {string} fullMainTableName - Fully resolved table name
  * @param {DynamoKey} keyValues
  * @param {number|string} timeCacheComplete
  * @param {string} prefix
@@ -325,27 +343,26 @@ async function checkAndGetTimeCacheComplete(
   prefix
 ) {
   _izContext.logger.debug(
-    '[Lib:AsyncFlow:checkAndGetTimeCacheComplete] Input: ',
+    '[Lib:AsyncFlow:checkAndGetTimeCacheComplete] Input:',
     {
-      fullMainTableName: fullMainTableName,
-      keyValues: keyValues,
-      timeCacheComplete: timeCacheComplete,
-      prefix: prefix
+      fullMainTableName,
+      keyValues,
+      timeCacheComplete,
+      prefix
     }
   );
 
   const uniqueRequestIdFieldName = createFieldNameUniqueRequestId('cache');
   const cacheCompleteFieldName = prefix + 'CacheComplete';
-  const statusFieldName = prefix + 'Status';
 
-  let getTimeCacheComplete = await dynamodbSharedLib.getItem(
+  const getTimeCacheComplete = await dynamodbSharedLib.getItem(
     _izContext,
     fullMainTableName,
     keyValues
   );
   _izContext.logger.debug(
-    `getTimeCacheComplete from ${fullMainTableName}: `,
-    getTimeCacheComplete
+    `[Lib:checkAndGetTimeCacheComplete] ${fullMainTableName}`,
+    { getTimeCacheComplete }
   );
 
   if (!getTimeCacheComplete) {
@@ -371,13 +388,13 @@ async function checkAndGetTimeCacheComplete(
     getTimeCacheComplete[cacheCompleteFieldName] !== timeCacheComplete
   ) {
     return [false, getTimeCacheComplete[cacheCompleteFieldName]];
-  } else {
-    return [
-      true,
-      getTimeCacheComplete[cacheCompleteFieldName],
-      getTimeCacheComplete[uniqueRequestIdFieldName]
-    ];
   }
+
+  return [
+    true,
+    getTimeCacheComplete[cacheCompleteFieldName],
+    getTimeCacheComplete[uniqueRequestIdFieldName]
+  ];
 }
 
 // ----- shared both stored cache and triggered cache, check uniqueRequestId changed ---------
@@ -403,9 +420,13 @@ async function checkCacheUniqueRequestId(
     fullMainTableName,
     keyValues
   );
-  _izContext.logger.debug('cacheObject', cacheObject);
+  _izContext.logger.debug('[Lib:checkCacheUniqueRequestId] Output', {
+    cacheObject
+  });
 
-  return cacheObject[uniqueRequestIdCompleteFieldName] === checkUniqueRequestId;
+  return (
+    cacheObject[uniqueRequestIdCompleteFieldName] === checkUniqueRequestId
+  );
 }
 
 //====================================== end Multiple Lambda Invocations (Logic pagination of handling results)
@@ -427,7 +448,7 @@ function validateStartKeyParam(
   partitionKeyFieldName,
   sortKeyFieldName
 ) {
-  _izContext.logger.debug('[Lib:AsyncFlow:validateStartKeyParam] Input: ', {
+  _izContext.logger.debug('[Lib:AsyncFlow:validateStartKeyParam] Input:', {
     startKey,
     partitionKeyFieldName,
     sortKeyFieldName
@@ -442,14 +463,16 @@ function validateStartKeyParam(
     !stringNotEmptyRegex.test(sortKeyFieldName)
   ) {
     throw new NoRetryError(
-      'validateStartKeyParam: Invalid partitionKeyFieldName or sortKeyFieldName'
+      'validateStartKeyParam:' +
+      ' Invalid partitionKeyFieldName or sortKeyFieldName'
     );
   }
 
   if (startKey && Object.keys(startKey).length !== 0) {
     if (!startKey[partitionKeyFieldName] || !startKey[sortKeyFieldName]) {
       throw new NoRetryError(
-        'validateStartKeyParam: Invalid startKey, missing partitionKeyFieldName or sortKeyFieldName'
+        'validateStartKeyParam: Invalid startKey,' +
+        ' missing partitionKeyFieldName or sortKeyFieldName'
       );
     }
     return startKey;
@@ -464,12 +487,12 @@ function validateStartKeyParam(
  * and re-enqueues the message to the specified SQS queue.
  * @async
  * @param {IzContext} _izContext
- * @param {Attrs} messageProperty - The message body object to re-dispatch
+ * @param {Attrs} messageProperty - Message body object to re-dispatch
  * @param {Attrs} [passOnStartKey={}] - Optional startKey to pass along
  * @param {number} numberInvocation - Current invocation count
- * @param {string} queueName - Logical queue name resolvable via sqsSharedLib.sqsQueueUrl
+ * @param {string} queueName - Logical queue name
  * @returns {Promise<void>}
- * @throws {NoRetryError} If `numberInvocation` exceeds internal safety limit
+ * @throws {NoRetryError} If numberInvocation exceeds safety limit
  */
 async function validateMultipleInvocations(
   _izContext,
@@ -479,12 +502,12 @@ async function validateMultipleInvocations(
   queueName
 ) {
   _izContext.logger.debug(
-    '[Lib:AsyncFlow:validateMultipleInvocations] Input: ',
+    '[Lib:AsyncFlow:validateMultipleInvocations] Input:',
     {
-      messageProperty: messageProperty,
-      passOnStartKey: passOnStartKey,
-      numberInvocation: numberInvocation,
-      queueName: queueName
+      messageProperty,
+      passOnStartKey,
+      numberInvocation,
+      queueName
     }
   );
 
@@ -509,11 +532,15 @@ async function validateMultipleInvocations(
       QueueUrl: await sqsSharedLib.sqsQueueUrl(_izContext, queueName)
     };
     _izContext.logger.debug(
-      `Send message to Dsq:${queueName} `,
-      messageReInvokeFunction
+      `[Lib:validateMultipleInvocations] Send message to Dsq:${queueName}`,
+      { messageReInvokeFunction }
     );
     await sqs.sendMessage(_izContext, messageReInvokeFunction);
   } catch (err) {
+    _izContext.logger.error(
+      '[Lib:validateMultipleInvocations] Error',
+      { err }
+    );
     throw err;
   }
 }

package/src/awaitingMultipleSteps.js

@@ -21,7 +21,8 @@ import snsSharedLib from '@izara_project/izara-core-library-sns';
 
 import {
   createParentFlowId,
-  createPendingStepId
+  createPendingStepId,
+  createAwaitingStepId
 } from './asyncFlowSharedLib.js';
 
 function _assertPendingStepId(pendingStepId) {
@@ -49,13 +50,17 @@ async function _putAwaitingMultipleStepRecords(
     records.flatMap(({ awaitingStepId, additionalAttributes }) => {
       const keys = { awaitingStepId, pendingStepId };
 
+      const itemPending = {
+        ...keys,
+        ...sharedAttributes
+      };
+      if (additionalAttributes) {
+        itemPending.additionalAttributes = additionalAttributes;
+      }
+
       return [
         dynamodbSharedLib.putItem(_izContext, tableSteps, keys),
-        dynamodbSharedLib.putItem(_izContext, tablePending, {
-          ...keys,
-          ...sharedAttributes,
-          ...(additionalAttributes && { additionalAttributes })
-        })
+        dynamodbSharedLib.putItem(_izContext, tablePending, itemPending)
       ];
     })
   );
@@ -96,23 +101,24 @@ async function _queryAwaitingStepsByPendingStepId(_izContext, pendingStepId) {
 // One pendingStepId can have multiple awaitingStepIds awaiting it.
 
 /**
- * Create awaiting multiple step records to block a flow until multiple steps complete.
+ * Create awaiting multiple step records to block a flow
+ * until multiple steps complete.
  * @async
  * @param {IzContext} _izContext - The Izara context.
- * @param {string} pendingStepId - The ID of the pending step that is waiting.
+ * @param {string} pendingStepId - The ID of pending step.
  * @param {Array<object>} [records=[]] - Array of step items.
- * @param {string} [records[].awaitingStepId] - Optional ID of the awaiting step. If not provided, a random UUID will be generated.
- * @param {object} [records[].message] - Optional message payload to publish if flowType is provided.
- * @param {object} [records[].flowType] - Optional flowType override for this specific step record.
- * @param {string} records[].flowType.flowTag - Tag identifying the flow.
- * @param {string} records[].flowType.serviceTag - Tag identifying the service.
+ * @param {string} [records[].awaitingStepId] - Awaiting step ID.
+ * @param {object} [records[].message] - Message payload to publish.
+ * @param {object} [records[].flowType] - FlowType override.
+ * @param {string} records[].flowType.flowTag - Tag identifying flow.
+ * @param {string} records[].flowType.serviceTag - Tag identifying service.
  * @param {object} [options={}] - Optional configurations.
- * @param {string} [options.prefix=''] - Prefix to prepend to pendingStepId.
- * @param {object} [options.additionalAttributes={}] - Default additional attributes to associate with each pending step record.
- * @param {object|null} [options.flowType=null] - Default flow schema/service metadata if starting external tasks.
- * @param {string} [options.flowType.flowTag] - Tag identifying the default flow.
- * @param {string} [options.flowType.serviceTag] - Tag identifying the default service.
- * @returns {Promise<string|undefined>} The awaitingStepId of the first mapped record.
+ * @param {string} [options.prefix=''] - Prefix for pendingStepId.
+ * @param {object} [options.additionalAttributes={}] - Default attributes.
+ * @param {object|null} [options.flowType=null] - Default flow schema.
+ * @param {string} [options.flowType.flowTag] - Default flow tag.
+ * @param {string} [options.flowType.serviceTag] - Default service tag.
+ * @returns {Promise<string|null>} The awaitingStepId of first record.
  */
 export async function createAwaitingMultipleSteps(
   _izContext,
@@ -157,7 +163,9 @@ export async function createAwaitingMultipleSteps(
       }
 
       const awaitingStepId =
-        record.awaitingStepId || createParentFlowId(prefix);
+        createAwaitingStepId(record.awaitingStepId, prefix) ||
+        createParentFlowId(prefix);
+
       return {
         awaitingStepId,
         additionalAttributes,
@@ -174,21 +182,27 @@ export async function createAwaitingMultipleSteps(
     });
   }
 
-  await _putAwaitingMultipleStepRecords(
-    _izContext,
-    finalRecords.map(({ awaitingStepId, additionalAttributes: itemAttrs }) => {
+  const mappedStepRecords = finalRecords.map(
+    ({ awaitingStepId, additionalAttributes: itemAttrs }) => {
       const hasItemAttrs = itemAttrs && Object.keys(itemAttrs).length > 0;
       const hasOptAttrs =
         additionalAttributes && Object.keys(additionalAttributes).length > 0;
 
+      let mergedAttributes = null;
+      if (hasItemAttrs || hasOptAttrs) {
+        mergedAttributes = { ...additionalAttributes, ...itemAttrs };
+      }
+
       return {
         awaitingStepId,
-        additionalAttributes:
-          hasItemAttrs || hasOptAttrs
-            ? { ...additionalAttributes, ...itemAttrs }
-            : undefined
+        additionalAttributes: mergedAttributes
       };
-    }),
+    }
+  );
+
+  await _putAwaitingMultipleStepRecords(
+    _izContext,
+    mappedStepRecords,
     finalPendingStepId,
     {
       complete: false,
@@ -198,16 +212,19 @@ export async function createAwaitingMultipleSteps(
 
   if (hasFlowPublish) {
     await Promise.all(
-      finalRecords.map(({ message, topicArn }) =>
-        sns.publishAsync(_izContext, {
+      finalRecords.map(async ({ message, topicArn }) => {
+        await sns.publishAsync(_izContext, {
           TopicArn: `${topicArn}_In`,
           Message: JSON.stringify(message)
-        })
-      )
+        });
+      })
     );
   }
 
-  return finalRecords[0]?.awaitingStepId;
+  if (finalRecords[0] && finalRecords[0].awaitingStepId) {
+    return finalRecords[0].awaitingStepId;
+  }
+  return null;
 }
 
 /**
@@ -246,11 +263,11 @@ export async function updateAwaitingMultipleStep(
 }
 
 /**
- * Query and return the first pending step item that matches the given awaitingStepId.
+ * Query and return the first pending step item that matches awaitingStepId.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} awaitingStepId - The ID of the awaiting step.
- * @returns {Promise<object|undefined>} The found item or undefined.
+ * @returns {Promise<object|null>} The found item or null.
  */
 export async function findPendingStepAwaitingMultipleSteps(
   _izContext,
@@ -265,11 +282,14 @@ export async function findPendingStepAwaitingMultipleSteps(
     awaitingStepId
   );
 
-  return items[0];
+  if (items && items.length > 0) {
+    return items[0];
+  }
+  return null;
 }
 
 /**
- * Query and return all pending step items matching the given awaitingStepId.
+ * Query and return all pending step items matching awaitingStepId.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} awaitingStepId - The ID of the awaiting step.
@@ -283,11 +303,11 @@ export async function findPendingStepsAwaitingMultipleSteps(
 }
 
 /**
- * Retrieve the pendingStepId of the first step matching the given awaitingStepId.
+ * Retrieve pendingStepId of first step matching awaitingStepId.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} awaitingStepId - The ID of the awaiting step.
- * @returns {Promise<string|undefined>} The pendingStepId of the first item found.
+ * @returns {Promise<string|null>} pendingStepId of first item found or null.
  */
 export async function findPendingStepIdAwaitingMultipleSteps(
   _izContext,
@@ -297,11 +317,14 @@ export async function findPendingStepIdAwaitingMultipleSteps(
     _izContext,
     awaitingStepId
   );
-  return items[0]?.pendingStepId;
+  if (items && items[0] && items[0].pendingStepId) {
+    return items[0].pendingStepId;
+  }
+  return null;
 }
 
 /**
- * Query and return all awaiting steps matching the given pendingStepId from byPending index table.
+ * Query and return all awaiting steps matching pendingStepId.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} pendingStepId - The ID of the pending step.
@@ -315,22 +338,21 @@ export async function findAwaitingMultipleStepByPending(
 }
 
 /**
- * Check if all awaiting steps for a pendingStepId are completed. If a current awaitingStepId
- * is provided, it updates its status to complete and returns values/errors.
+ * Check if all awaiting steps for a pendingStepId are completed.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} pendingStepId - The ID of the pending step.
- * @param {string|null} [currentAwaitingStepId=null] - The ID of the current awaiting step that completed.
- * @param {Array<any>} [errorsFound=[]] - Errors collected from the current step.
- * @param {object} [returnValues={}] - Values returned from the current step.
- * @param {object} [settings={ checkIsAllError: false }] - Execution settings.
- * @param {boolean} [settings.checkIsAllError=false] - Whether to verify if all steps failed.
- * @returns {Promise<object>} Status object containing isComplete, collectedAttributes, collectedErrors, returnValues, additionalAttributes, etc.
+ * @param {string|null} [currentAwaitingStepId=null] - Completed step ID.
+ * @param {Array<any>} [errorsFound=[]] - Errors collected from current step.
+ * @param {object} [returnValues={}] - Values returned from current step.
+ * @param {object} [settings={ checkIsAllError: false }] - Settings.
+ * @param {boolean} [settings.checkIsAllError=false] - Verify all failed.
+ * @returns {Promise<object>} Status object containing completion details.
  */
 export async function checkAllAwaitingStepsFinishedWithReturnParams(
   _izContext,
   pendingStepId,
-  currentAwaitingStepId = null,
+  currentAwaitingStepId,
   errorsFound = [],
   returnValues = {},
   settings = { checkIsAllError: false }
@@ -370,24 +392,29 @@ export async function checkAllAwaitingStepsFinishedWithReturnParams(
 
   _izContext.logger.debug(
     '[Lib:checkAllAwaitingStepsFinishedWithReturnParams] awaitingStepItems',
-    awaitingStepItems
+    { awaitingStepItems }
   );
 
   const hasIncomplete = awaitingStepItems.some(
     item => item.awaitingStepId !== currentAwaitingStepId && !item.complete
   );
 
+  let defaultAttrs = null;
+  if (awaitingStepItems[0] && awaitingStepItems[0].additionalAttributes) {
+    defaultAttrs = awaitingStepItems[0].additionalAttributes;
+  }
+
   if (hasIncomplete) {
     return {
       isComplete: false,
-      collectedAttributes: null,
+      collectedReturnValueByAwaitingStepId: null,
       collectedErrors: [],
       returnValues: null,
-      additionalAttributes: awaitingStepItems[0]?.additionalAttributes || null
+      additionalAttributes: defaultAttrs
     };
   }
 
-  const collectedAttributes = {};
+  const collectedReturnValueByAwaitingStepId = {};
   let sharedReturnValues = null;
 
   for (const item of awaitingStepItems) {
@@ -395,30 +422,42 @@ export async function checkAllAwaitingStepsFinishedWithReturnParams(
       continue;
     }
 
-    collectedAttributes[item.awaitingStepId] = item.returnValues;
-    sharedReturnValues ??= item.returnValues;
+    collectedReturnValueByAwaitingStepId[item.awaitingStepId] =
+      item.returnValues;
+    if (sharedReturnValues === null) {
+      sharedReturnValues = item.returnValues;
+    }
   }
 
-  const collectedErrors = awaitingStepItems.flatMap(item =>
-    item.errorsFound?.length > 0
-      ? [`Error found in step ${item.awaitingStepId}`, ...item.errorsFound]
-      : []
-  );
+  const collectedErrors = [];
+  for (const item of awaitingStepItems) {
+    if (item.errorsFound && item.errorsFound.length > 0) {
+      collectedErrors.push(
+        `Error found in step ${item.awaitingStepId}`,
+        ...item.errorsFound
+      );
+    }
+  }
 
-  return {
+  const result = {
     isComplete: true,
-    collectedAttributes,
+    collectedReturnValueByAwaitingStepId,
     collectedErrors,
     returnValues: sharedReturnValues,
-    additionalAttributes: awaitingStepItems[0]?.additionalAttributes || null,
-    ...(settings.checkIsAllError && {
-      isAllError: awaitingStepItems.every(item => item.errorsFound?.length > 0)
-    })
+    additionalAttributes: defaultAttrs
   };
+
+  if (settings.checkIsAllError) {
+    result.isAllError = awaitingStepItems.every(
+      item => item.errorsFound && item.errorsFound.length > 0
+    );
+  }
+
+  return result;
 }
 
 /**
- * Clean up/delete all awaiting multiple steps records associated with the pendingStepId from both tables.
+ * Clean up/delete all awaiting multiple steps records for pendingStepId.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} pendingStepId - The ID of the pending step.
@@ -429,7 +468,7 @@ export async function clearAllAwaitingSteps(_izContext, pendingStepId) {
     pendingStepId
   });
 
-  const listPendingStepIds = await _queryAwaitingStepsByPendingStepId(
+  const awaitingStepItems = await _queryAwaitingStepsByPendingStepId(
     _izContext,
     pendingStepId
   );
@@ -443,7 +482,7 @@ export async function clearAllAwaitingSteps(_izContext, pendingStepId) {
   );
 
   await Promise.all(
-    listPendingStepIds.flatMap(
+    awaitingStepItems.flatMap(
       ({ awaitingStepId, pendingStepId: itemPendingStepId }) => [
         dynamodbSharedLib.deleteItem(_izContext, tableSteps, {
           awaitingStepId,
@@ -461,12 +500,12 @@ export async function clearAllAwaitingSteps(_izContext, pendingStepId) {
 }
 
 /**
- * Delete a specific awaiting step from Steps table (and optionally from byPending table if no errors found).
+ * Delete a specific awaiting step from Steps table (and byPending table).
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} awaitingStepId - The ID of the awaiting step.
  * @param {string} pendingStepId - The ID of the pending step.
- * @param {Array<any>} [errorsFound=[]] - List of errors. If empty, the record is removed from byPending too.
+ * @param {Array<any>} [errorsFound=[]] - List of errors.
  * @returns {Promise<void>}
  */
 export async function removeAwaitingMultipleStep(
@@ -483,7 +522,8 @@ export async function removeAwaitingMultipleStep(
 
   if (!awaitingStepId || !pendingStepId) {
     throw new NoRetryError(
-      '[Lib:removeAwaitingMultipleStep] awaitingStepId or pendingStepId required'
+      '[Lib:removeAwaitingMultipleStep]' +
+      ' awaitingStepId or pendingStepId required'
     );
   }
 

package/src/awaitingStep.js

@@ -44,16 +44,18 @@ async function _findSinglePendingStep(_izContext, awaitingStepId) {
 //======================================
 // AwaitingStep
 //======================================
-// AwaitingStep flow awaiting one external flow, will continue its flow once one external flow completes.
+// AwaitingStep flow awaiting one external flow, will continue its flow once
+// one external flow completes.
 // One awaitingStepId can have multiple pendingStepIds awaiting it.
 
 /**
- * Create a single awaiting step record to block a flow until a specific external flow step completes.
+ * Create a single awaiting step record to block a flow until a specific
+ * external flow step completes.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} awaitingStepId - The ID of the awaiting step.
- * @param {string} pendingStepId - The ID of the pending step that is waiting.
- * @param {object} [additionalAttributes={}] - Additional attributes to save with the record.
+ * @param {string} pendingStepId - The ID of pending step that is waiting.
+ * @param {object} [additionalAttributes={}] - Attributes to save.
  * @param {object} [callingFlowConfig={}] - Calling flow configuration.
  * @returns {Promise<void>}
  */
@@ -91,15 +93,15 @@ export async function createAwaitingStep(
 }
 
 /**
- * Query and return the single pending step item that matches the given awaitingStepId.
+ * Query and return single pending step item matching given awaitingStepId.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} awaitingStepId - The ID of the awaiting step.
  * @returns {Promise<object>} The found pending step record.
- * @throws {NoRetryError} If awaitingStepId is missing or if not exactly one record is found.
+ * @throws {NoRetryError} If missing or if not exactly one record found.
  */
 export async function findPendingStep(_izContext, awaitingStepId) {
- return _findSinglePendingStep(_izContext, awaitingStepId);
+  return _findSinglePendingStep(_izContext, awaitingStepId);
 }
 
 /**
@@ -122,7 +124,7 @@ export async function removeAwaitingStep(
   });
 
   if (!awaitingStepId || !pendingStepId) {
-    throw new NoRetryError('awaitingStepId pendingStepId required');
+    throw new NoRetryError('awaitingStepId, pendingStepId required');
   }
 
   await dynamodbSharedLib.deleteItem(
@@ -133,7 +135,7 @@ export async function removeAwaitingStep(
 }
 
 /**
- * Delete an awaiting step record from AwaitingStep table, conditional on uniqueRequestId.
+ * Delete awaiting step record from AwaitingStep table by uniqueRequestId.
  * @async
  * @param {IzContext} _izContext - The Izara context.
  * @param {string} awaitingStepId - The ID of the awaiting step.
@@ -157,7 +159,7 @@ export async function removeAwaitingStepWithCheckUniqueRequestId(
 
   if (!awaitingStepId || !pendingStepId || !checkUniqueRequestId) {
     throw new NoRetryError(
-      'awaitingStepId, pendingStepId checkUniqueRequestId required'
+      'awaitingStepId, pendingStepId, checkUniqueRequestId required'
     );
   }