@izara_project/izara-core-library-asynchronous-flow 1.0.15 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izara_project/izara-core-library-asynchronous-flow",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Shared asynchronous flow logic",
   "main": "index.js",
   "scripts": {

package/src/AsyncFlowSharedLib.js

@@ -28,6 +28,13 @@ const sqsSharedLib = require('@izara_project/izara-core-library-sqs');
 // External service interactions
 const { sqs } = require('@izara_project/izara-core-library-external-request');
 
+
+/**
+ * Create a field name for storing the unique-request id, with optional prefix.
+ * @param {string} prefix
+ * @param {string} [uniqueRequestIdFieldName='UniqueRequestId']
+ * @returns {string}
+ */
 function createFieldNameUniqueRequestId(
   prefix,
   uniqueRequestIdFieldName = 'UniqueRequestId'
@@ -35,6 +42,13 @@ function createFieldNameUniqueRequestId(
   return prefix + uniqueRequestIdFieldName;
 }
 
+/**
+ * Create a concatenated awaitingStepId from composite parts.
+ * @param {string} partitionKey
+ * @param {string|number} sortId
+ * @param {string} [prefix=""]
+ * @returns {string}
+ */
 function createConcatenatedAwaitingStepId(
   partitionKey,
   sortId,
@@ -43,6 +57,12 @@ function createConcatenatedAwaitingStepId(
   return prefix + partitionKey + "_" + sortId
 }
 
+/**
+ * Create a concatenated pendingStepId from parent/child ids.
+ * @param {string} parentId
+ * @param {string} childId
+ * @returns {string}
+ */
 function createConcatenatedPendingStepId(
   parentId,
   childId
@@ -50,6 +70,12 @@ function createConcatenatedPendingStepId(
   return parentId + "_" + childId
 }
 
+/**
+ * Create a simple awaitingStepId (prefix + partitionKey).
+ * @param {string} partitionKey
+ * @param {string} [prefix=""]
+ * @returns {string}
+ */
 function createAwaitingStepId(
   partitionKey,
   prefix = ""
@@ -57,6 +83,12 @@ function createAwaitingStepId(
   return prefix + partitionKey
 }
 
+/**
+ * Create a simple pendingStepId (prefix + identifierId).
+ * @param {string} identifierId
+ * @param {string} [prefix=""]
+ * @returns {string}
+ */
 function createPendingStepId(
   identifierId,
   prefix = ""
@@ -64,6 +96,14 @@ function createPendingStepId(
   return prefix + identifierId
 }
 
+/**
+ * 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.
+ * @param {string} pendingStepId
+ * @param {string} [prefix=""]
+ * @returns {string}
+ * @throws {NoRetryError} If the stripped value equals the prefix (invalid)
+ */
 function explodePendingStepId(
   pendingStepId,
   prefix = ""
@@ -84,20 +124,40 @@ function explodePendingStepId(
 }
 
 // copy from izara-core-library-trigger-cache
+/**
+ * Build the field name that stores "cache complete" marker.
+ * @param {string} [prefix='cache']
+ * @returns {string}
+ */
 function createFieldNameCacheComplete(prefix = 'cache') {
   return prefix + 'CacheComplete';
 }
+
+/**
+ * Build the field name that stores a cache "status".
+ * @param {string} [prefix='cache']
+ * @returns {string}
+ */
 function createFieldNameStatus(prefix = 'cache') {
   return prefix + 'Status';
 }
 
+
 //====================================== AwaitingMultipleSteps
 // AwaitingMultipleSteps is when a flow is awaiting multiple external flows before it can continue
 // One awaitingStepId can have multiple pendingStepIds that are awaiting it
 // One pendingStepId can have multiple awaitingStepIds it is awaiting
 // logic can prepend any prefix to awaitingStepId if want to be share one table and differentiate different external step ids
 
-//not yet used ?
+/**
+ * Create multiple awaiting records with optional per-record additional attributes.
+ * Writes to both "AwaitingMultipleSteps" and "AwaitingMultipleStepByPending".
+ * @async
+ * @param {IzContext} _izContext
+ * @param {AwaitingMultiInputRecord[]} records
+ * @param {string} pendingStepId
+ * @returns {Promise<void>}
+ */
 async function createAwaitingMultipleStepsWithAdditionalAttributes(
   _izContext,
   records, // array of object including properties: awaitingStepId / (optional) additionalAttributes
@@ -142,6 +202,15 @@ async function createAwaitingMultipleStepsWithAdditionalAttributes(
 
 }
 
+/**
+ * Create multiple awaiting records given an array of awaitingStepIds.
+ * Writes to both "AwaitingMultipleSteps" and "AwaitingMultipleStepByPending".
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string[]} records - array of awaitingStepIds
+ * @param {string} pendingStepId
+ * @returns {Promise<void>}
+ */
 async function createAwaitingMultipleSteps(
   _izContext,
   records, // array of awaitingStepIds
@@ -188,6 +257,13 @@ async function createAwaitingMultipleSteps(
 
 }
 
+/**
+ * Find all pendingStepIds that are waiting on a given awaitingStepId (multiple).
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @returns {Promise<string[]>}
+ */
 async function findPendingStepIdsAwaitingMultipleSteps(
   _izContext,
   awaitingStepId
@@ -210,6 +286,13 @@ async function findPendingStepIdsAwaitingMultipleSteps(
   return pendingStepIds
 }
 
+/**
+ * Return the raw items waiting on a given awaitingStepId (multiple).
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @returns {Promise<AwaitingMultipleStepsItem[]>}
+ */
 async function findPendingStepsAwaitingMultipleSteps(
   _izContext,
   awaitingStepId
@@ -226,6 +309,14 @@ async function findPendingStepsAwaitingMultipleSteps(
   return listPendingSteps.Items;
 }
 
+/**
+ * Fetch exactly one pending step for a given awaitingStepId (throws if not 1).
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @returns {Promise<AwaitingMultipleStepsItem>}
+ * @throws {NoRetryError} if there is not exactly one item
+ */
 async function findPendingStepAwaitingMultipleSteps(
   _izContext,
   awaitingStepId
@@ -251,6 +342,14 @@ async function findPendingStepAwaitingMultipleSteps(
 // Do NOT delete records in both tables (AwaitingMultipleSteps, AwaitingMultipleStepByPending) if AwaitingMultipleSteps is not yet finished
 // Delete records from both tables only when checkAllAwaitingStepsFinished = true
 // Example usage: flow validateCart lambda ProcessCartOrderFromTraversal
+/**
+ * Given a pendingStepId, return all awaiting steps (by the ByPending table).
+ * Use only after confirming all awaiting steps are finished, and clean up both tables accordingly.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} pendingStepId
+ * @returns {Promise<AwaitingMultipleStepByPendingItem[]>}
+ */
 async function findAwaitingMultipleStepByPending(
   _izContext,
   pendingStepId
@@ -272,6 +371,16 @@ async function findAwaitingMultipleStepByPending(
 // One awaitingStepId can have multiple pendingStepIds that are awaiting it
 // logic can prepend any prefix to awaitingStepId if want to be share one table and differentiate different external step ids
 
+/**
+ * Create a single AwaitingStep record, optionally attaching additional attributes and callingFlowConfig.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @param {string} pendingStepId
+ * @param {Attrs} [additionalAttributes={}]
+ * @param {Attrs} [callingFlowConfig={}]
+ * @returns {Promise<void>}
+ */
 async function createAwaitingStep(
   _izContext,
   awaitingStepId,
@@ -307,7 +416,13 @@ async function createAwaitingStep(
   );
 }
 
-
+/**
+ * Find all pendingStepIds that are waiting on a given awaitingStepId (single).
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @returns {Promise<string[]>}
+ */
 async function findPendingStepIdsAwaitingStep(
   _izContext,
   awaitingStepId
@@ -330,6 +445,13 @@ async function findPendingStepIdsAwaitingStep(
   return pendingStepIds
 }
 
+/**
+ * Return the raw items waiting on a given awaitingStepId (single).
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @returns {Promise<AwaitingStepItem[]>}
+ */
 async function findPendingStepsAwaitingStep(
   _izContext,
   awaitingStepId
@@ -346,6 +468,14 @@ async function findPendingStepsAwaitingStep(
   return listPendingSteps.Items;
 }
 
+/**
+ * Fetch exactly one pending step for a given awaitingStepId (throws if not 1).
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @returns {Promise<AwaitingStepItem>}
+ * @throws {NoRetryError} if there is not exactly one item
+ */
 async function findPendingStepAwaitingStep(
   _izContext,
   awaitingStepId
@@ -366,7 +496,15 @@ async function findPendingStepAwaitingStep(
   return listPendingSteps.Items[0];
 }
 
-//  for get callingFlow save in awaitingStpe and remove property callingFlow in awaitingStpe
+//  for get callingFlow save in awaitingStep and remove property callingFlow in awaitingStep
+/**
+ * Get one awaiting step by id and also extract (and remove) its callingFlowConfig (if present).
+ * Returns a tuple: [AwaitingStepItemWithoutCallingFlow, callingFlowConfig|null].
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @returns {Promise<[AwaitingStepItem, Attrs|null]>}
+ */
 async function findPendingStepAwaitingStepWithCallingFlow(
   _izContext,
   awaitingStepId,
@@ -379,7 +517,7 @@ async function findPendingStepAwaitingStepWithCallingFlow(
   );
 
   // callingFlowConfig.
-  // cleaning object awaitingStep not have callingFlowComfig after return.
+  // cleaning object awaitingStep not have callingFlowConfig after return.
   if (awaitingStep.hasOwnProperty("callingFlowConfig")) {
     callingFlowConfig = awaitingStep.callingFlowConfig
     delete awaitingStep.callingFlowConfig
@@ -389,6 +527,17 @@ async function findPendingStepAwaitingStepWithCallingFlow(
   return [awaitingStep, callingFlowConfig]
 }
 
+/**
+ * Mark current awaiting step as complete (in *_ByPending), then check if all awaiting steps are done.
+ * Returns true if all are finished; false otherwise.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} pendingStepId
+ * @param {string|null} [currentAwaitingStepId=null]
+ * @param {any[]} [errorsFound=[]]
+ * @param {Attrs} [additionalAttributes={}]
+ * @returns {Promise<boolean>}
+ */
 async function checkAllAwaitingStepsFinished(
   _izContext,
   pendingStepId,
@@ -407,8 +556,16 @@ async function checkAllAwaitingStepsFinished(
   return remaining;
 }
 
-
-
+/**
+ * Same as checkAllAwaitingStepsFinished but writes errors/additionalAttributes to the *_ByPending row.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} pendingStepId
+ * @param {string|null} [currentAwaitingStepId=null]
+ * @param {any[]} [errorsFound=[]]
+ * @param {Attrs} [additionalAttributes={}]
+ * @returns {Promise<boolean>}
+ */
 async function checkAllAwaitingStepsFinishedWithError(
   _izContext,
   pendingStepId,
@@ -445,12 +602,12 @@ async function checkAllAwaitingStepsFinishedWithError(
       pendingStepId: pendingStepId
     },
     {
-      limit: 50 // arbritrary limit so not pull too many results, need >2 because some others might be marked as "complete" = true
+      limit: 50 // arbitrary limit so not pull too many results, need >2 because some others might be marked as "complete" = true
     }
   );
   for (let idx = 0; idx < listPendingStepIds.Items.length; idx++) {
 
-    // if have error found return errorfound
+    // if have error found return errorsFound
     // wrap function
 
     if (currentAwaitingStepId && listPendingStepIds.Items[idx].awaitingStepId == currentAwaitingStepId) {
@@ -492,7 +649,7 @@ async function checkAllAwaitingStepsFinishedWithError(
   //   },
   //   {
   //     indexName: dynamodbSharedLib.tableName(tableName + 'Index'),
-  //     limit: 50 // arbritrary limit so not pull too many results, need >2 because some others might be marked as "complete" = true
+  //     limit: 50 // arbitrary limit so not pull too many results, need >2 because some others might be marked as "complete" = true
   //   }
   // );
   // for (let idx = 0; idx < listPendingStepIds.Items.length; idx++) {
@@ -509,8 +666,13 @@ async function checkAllAwaitingStepsFinishedWithError(
   // return true;
 }
 
-
-
+/**
+ * Remove all awaiting records for a given pendingStepId from both tables.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} pendingStepId
+ * @returns {Promise<boolean>} true if delete flow processed
+ */
 async function clearAllAwaitingSteps(
   _izContext,
   pendingStepId
@@ -559,7 +721,14 @@ async function clearAllAwaitingSteps(
   return true;
 }
 
-
+/**
+ * Remove a single AwaitingStep record (single dependency table).
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @param {string} pendingStepId
+ * @returns {Promise<void>}
+ */
 async function removeAwaitingStep(
   _izContext,
   awaitingStepId,
@@ -576,6 +745,16 @@ async function removeAwaitingStep(
   );
 }
 
+/**
+ * Remove items for AwaitingMultipleSteps and (conditionally) AwaitingMultipleStepByPending.
+ * If errorsFound is empty, delete from ByPending table as well.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @param {string} pendingStepId
+ * @param {any[]} [errorsFound=[]]
+ * @returns {Promise<void>}
+ */
 async function removeAwaitingMultipleStep(
   _izContext,
   awaitingStepId,
@@ -626,6 +805,17 @@ async function removeAwaitingMultipleStep(
 }
 
 // only works with AwaitingStep, does not work with AwaitingMultipleSteps, need to make new function that checks conditional pass? If pass delete from byPending table too
+/**
+ * Remove an AwaitingStep item only if its stored UniqueRequestId matches `checkUniqueRequestId`.
+ * Uses a conditional expression; will not error if the condition fails.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} awaitingStepId
+ * @param {string} pendingStepId
+ * @param {string} checkUniqueRequestId
+ * @param {string} [prefix=""] - Optional prefix for UniqueRequestId field name
+ * @returns {Promise<void>}
+ */
 async function removeAwaitingStepWithCheckUniqueRequestId(
   _izContext,
   awaitingStepId,
@@ -664,14 +854,8 @@ async function removeAwaitingStepWithCheckUniqueRequestId(
   );
 }
 
-
-
 //====================================== end AwaitingStep
 
-
-
-
-
 /**
  * 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
@@ -684,6 +868,27 @@ async function removeAwaitingStepWithCheckUniqueRequestId(
 
  * @returns [string] [returnStatus, existingRecord]
  */
+
+
+/**
+ * Coordinate unique-request processing over a record:
+ * - If no record: returns ["recordNotFound", {}]
+ * - If record exists but no uniqueRequestId: tries to set it via conditional update
+ * - If record has a different uniqueRequestId: returns ["stop", existingRecord]
+ * - If record has the same uniqueRequestId: returns ["process", existingRecord]
+ *
+ * Will loop up to 2 attempts to avoid races; throws on 3rd iteration.
+ *
+ * @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} [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
+ * @returns {Promise<[UniqueRequestStatus, Attrs]>}
+ * @throws {NoRetryError} If unable to set uniqueRequestId after 2 tries
+ */
 async function checkUniqueRequestProcessing(
   _izContext,
   tableName,
@@ -789,6 +994,17 @@ async function checkUniqueRequestProcessing(
 };
 
 // ----- Helper funtion, common use case in triggerFlow ---------
+/**
+ * Convenience wrapper around checkAndGetTimeCacheComplete.
+ * Returns [isSameOrUnset, uniqueRequestIdWhenComplete].
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} fullMainTableName - Fully resolved table name (not logical)
+ * @param {DynamoKey} keyValues
+ * @param {number|string} timeCacheComplete - Caller’s expected cache mark
+ * @param {string} prefix - Field prefix used in cache fields
+ * @returns {Promise<[boolean, string|undefined]>}
+ */
 async function checkTimeCacheComplete(
   _izContext,
   fullMainTableName,
@@ -805,6 +1021,20 @@ async function checkTimeCacheComplete(
   );
   return [returnValue, uniqueRequestId];
 }
+
+/**
+ * Read cache fields from a record and compare cacheComplete value to caller’s `timeCacheComplete`.
+ * If stored differs (and is present), returns [false, storedValue].
+ * Otherwise returns [true, storedValue, uniqueRequestId].
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} fullMainTableName - Fully resolved table name (not logical)
+ * @param {DynamoKey} keyValues
+ * @param {number|string} timeCacheComplete
+ * @param {string} prefix
+ * @returns {Promise<[boolean, any, string|undefined]>}
+ * @throws {NoRetryError} If record cannot be fetched
+ */
 async function checkAndGetTimeCacheComplete(
   _izContext,
   fullMainTableName,
@@ -857,6 +1087,16 @@ async function checkAndGetTimeCacheComplete(
 
 
 // ----- shared both stored cache and triggered cache, check uniqueRequestId changed ---------
+/**
+ * Ensure the cache object’s "uniqueRequestIdCompleteFieldName" equals the given checkUniqueRequestId.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} fullMainTableName
+ * @param {DynamoKey} keyValues
+ * @param {string} checkUniqueRequestId
+ * @param {string} uniqueRequestIdCompleteFieldName
+ * @returns {Promise<boolean>}
+ */
 async function checkCacheUniqueRequestId(
   _izContext,
   fullMainTableName,
@@ -880,10 +1120,6 @@ async function checkCacheUniqueRequestId(
 }
 
 
-
-
-
-
 // use shared findPendingStepIdsAwaitingStep
 // module.exports.findPendingStepIdsAwaitingStepM = async (
 //   _izContext,
@@ -909,8 +1145,6 @@ async function checkCacheUniqueRequestId(
 // }
 
 
-
-
 // use shared removeAwaitingStep
 // module.exports.removeAwaitingStep = async (
 //   _izContext,
@@ -936,6 +1170,17 @@ async function checkCacheUniqueRequestId(
 
 //====================================== end Multiple Lambda Invocations (Logic pagination of handling results)
 
+/**
+ * Validate and normalize a DynamoDB pagination startKey object.
+ * Ensures partitionKeyFieldName/sortKeyFieldName are alphanumeric/underscore/hyphen.
+ * If startKey is empty object, returns `null` for easier processing downstream.
+ * @param {IzContext} _izContext
+ * @param {Attrs|null|undefined} startKey
+ * @param {string} partitionKeyFieldName
+ * @param {string} sortKeyFieldName
+ * @returns {Attrs|null}
+ * @throws {NoRetryError} On invalid field names or malformed startKey
+ */
 function validateStartKeyParam(
   _izContext,
   startKey,
@@ -963,7 +1208,19 @@ function validateStartKeyParam(
   return startKey;
 }
 
-
+/**
+ * For paginated multi-invocation flows: validates the current invocation count,
+ * attaches the (optional) next startKey to the message, increments the count,
+ * 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} [passOnStartKey={}] - Optional startKey to pass along
+ * @param {number} numberInvocation - Current invocation count
+ * @param {string} queueName - Logical queue name resolvable via sqsSharedLib.sqsQueueUrl
+ * @returns {Promise<void>}
+ * @throws {NoRetryError} If `numberInvocation` exceeds internal safety limit
+ */
 async function validateMultipleInvocations(
   _izContext,
   messageProperty,