@izara_project/izara-core-library-asynchronous-flow 1.0.39 → 1.0.40

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.39",
+  "version": "1.0.40",
   "description": "Shared asynchronous flow logic",
   "type": "module",
   "main": "index.js",

package/src/asyncFlowSharedLib.js

@@ -28,13 +28,20 @@ import { sqs } from '@izara_project/izara-core-library-external-request';
 
 import { identifierUuid } from '@izara_project/izara-shared-core';
 
+function createAwaitingStepId(partitionKey, prefix = '') {
+  return prefix + partitionKey;
+}
+function createPendingStepId(identifierId, prefix = '') {
+  return prefix + identifierId;
+}
+
 /**
  * Create a field name for storing the unique-request id, with optional prefix.
  * @param {string} prefix
  * @param {string} [uniqueRequestIdFieldName='UniqueRequestId']
  * @returns {string}
  */
-export function createFieldNameUniqueRequestId(
+function createFieldNameUniqueRequestId(
   prefix,
   uniqueRequestIdFieldName = 'UniqueRequestId'
 ) {
@@ -48,11 +55,7 @@ export function createFieldNameUniqueRequestId(
  * @param {string} [prefix=""]
  * @returns {string}
  */
-export function createConcatenatedAwaitingStepId(
-  partitionKey,
-  sortId,
-  prefix = ''
-) {
+function createConcatenatedAwaitingStepId(partitionKey, sortId, prefix = '') {
   return prefix + partitionKey + '_' + sortId;
 }
 
@@ -62,7 +65,7 @@ export function createConcatenatedAwaitingStepId(
  * @param {string} childId
  * @returns {string}
  */
-export function createConcatenatedPendingStepId(parentId, childId) {
+function createConcatenatedPendingStepId(parentId, childId) {
   return parentId + '_' + childId;
 }
 
@@ -72,7 +75,7 @@ export function createConcatenatedPendingStepId(parentId, childId) {
  * @param {string} [prefix=''] - The prefix to prepend to the parent Ids.
  * @returns {string} The parent Flow Id created.
  */
-export function createParentFlowId(prefix = '') {
+function createParentFlowId(prefix = '') {
   return (prefix ? `${prefix}_` : '') + identifierUuid();
 }
 
@@ -84,7 +87,7 @@ export function createParentFlowId(prefix = '') {
  * @returns {string}
  * @throws {NoRetryError} If the stripped value equals the prefix (invalid)
  */
-export function explodePendingStepId(pendingStepId, prefix = '') {
+function explodePendingStepId(pendingStepId, prefix = '') {
   if (!pendingStepId) throw new NoRetryError('pendingStepId is required');
   if (!prefix) return pendingStepId;
 
@@ -129,7 +132,7 @@ export function explodePendingStepId(pendingStepId, prefix = '') {
  * @returns {Promise<[UniqueRequestStatus, Attrs]>}
  * @throws {NoRetryError} If unable to set uniqueRequestId after 2 tries
  */
-export async function checkUniqueRequestProcessing(
+async function checkUniqueRequestProcessing(
   _izContext,
   tableName,
   primaryKey,
@@ -232,7 +235,7 @@ export async function checkUniqueRequestProcessing(
  * @param {string} prefix - Field prefix used in cache fields
  * @returns {Promise<[boolean, string|undefined]>}
  */
-export async function checkTimeCacheComplete(
+async function checkTimeCacheComplete(
   _izContext,
   fullMainTableName,
   keyValues,
@@ -277,7 +280,7 @@ export async function checkTimeCacheComplete(
  * @returns {Promise<[boolean, any, string|undefined]>}
  * @throws {NoRetryError} If record cannot be fetched
  */
-export async function checkAndGetTimeCacheComplete(
+async function checkAndGetTimeCacheComplete(
   _izContext,
   fullMainTableName,
   keyValues,
@@ -351,7 +354,7 @@ export async function checkAndGetTimeCacheComplete(
  * @param {string} uniqueRequestIdCompleteFieldName
  * @returns {Promise<boolean>}
  */
-export async function checkCacheUniqueRequestId(
+async function checkCacheUniqueRequestId(
   _izContext,
   fullMainTableName,
   keyValues,
@@ -381,7 +384,7 @@ export async function checkCacheUniqueRequestId(
  * @returns {Attrs|null}
  * @throws {NoRetryError} On invalid field names or malformed startKey
  */
-export function validateStartKeyParam(
+function validateStartKeyParam(
   _izContext,
   startKey,
   partitionKeyFieldName,
@@ -431,7 +434,7 @@ export function validateStartKeyParam(
  * @returns {Promise<void>}
  * @throws {NoRetryError} If `numberInvocation` exceeds internal safety limit
  */
-export async function validateMultipleInvocations(
+async function validateMultipleInvocations(
   _izContext,
   messageProperty,
   passOnStartKey = {},
@@ -477,3 +480,19 @@ export async function validateMultipleInvocations(
     throw err;
   }
 }
+
+export {
+  createAwaitingStepId,
+  createPendingStepId,
+  createFieldNameUniqueRequestId,
+  createConcatenatedAwaitingStepId,
+  createConcatenatedPendingStepId,
+  createParentFlowId,
+  explodePendingStepId,
+  checkUniqueRequestProcessing,
+  checkTimeCacheComplete,
+  checkAndGetTimeCacheComplete,
+  checkCacheUniqueRequestId,
+  validateStartKeyParam,
+  validateMultipleInvocations
+};

package/src/awaitingMultipleSteps.js

@@ -92,6 +92,22 @@ async function _queryAwaitingStepsByPendingStepId(_izContext, pendingStepId) {
 // One awaitingStepId can have multiple pendingStepIds awaiting it.
 // One pendingStepId can have multiple awaitingStepIds awaiting it.
 
+/**
+ * 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 {Array<object>} [records=[]] - Array of step items containing awaitingStepId and optional attributes.
+ * @param {object} [options={}] - Optional configurations.
+ * @param {string} [options.prefix=''] - Prefix to prepend to pendingStepId.
+ * @param {object} [options.additionalAttributes={}] - Additional attributes to associate with each pending step record.
+ * @param {object} [options.publishConfig=null] - SQS/SNS publish configuration if starting external tasks.
+ * @param {Array<object>} options.publishConfig.messages - Messages to publish.
+ * @param {object} options.publishConfig.flowType - Flow schema/service metadata.
+ * @param {string} options.publishConfig.flowType.flowTag - Tag identifying the flow.
+ * @param {string} options.publishConfig.flowType.serviceTag - Tag identifying the service.
+ * @returns {Promise<string|undefined>} The awaitingStepId of the first mapped record.
+ */
 export async function createAwaitingMultipleSteps(
   _izContext,
   pendingStepId,
@@ -158,10 +174,19 @@ export async function createAwaitingMultipleSteps(
 
   await _putAwaitingMultipleStepRecords(
     _izContext,
-    finalRecords.map(({ awaitingStepId, additionalAttributes: itemAttrs }) => ({
-      awaitingStepId,
-      additionalAttributes: itemAttrs
-    })),
+    finalRecords.map(({ awaitingStepId, additionalAttributes: itemAttrs }) => {
+      const hasItemAttrs = itemAttrs && Object.keys(itemAttrs).length > 0;
+      const hasOptAttrs =
+        additionalAttributes && Object.keys(additionalAttributes).length > 0;
+
+      return {
+        awaitingStepId,
+        additionalAttributes:
+          hasItemAttrs || hasOptAttrs
+            ? { ...additionalAttributes, ...itemAttrs }
+            : undefined
+      };
+    }),
     finalPendingStepId,
     {
       complete: false,
@@ -190,6 +215,15 @@ export async function createAwaitingMultipleSteps(
   return finalRecords[0]?.awaitingStepId;
 }
 
+/**
+ * Update an awaiting multiple step record in the Steps 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 {object} data - Attributes to update.
+ * @returns {Promise<object>} The updated data with awaitingStepId merged.
+ */
 export async function updateAwaitingMultipleStep(
   _izContext,
   awaitingStepId,
@@ -216,6 +250,13 @@ export async function updateAwaitingMultipleStep(
   return { ...data, awaitingStepId };
 }
 
+/**
+ * Query and return the first pending step item that matches the given 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.
+ */
 export async function findPendingStepAwaitingMultipleSteps(
   _izContext,
   awaitingStepId
@@ -232,6 +273,13 @@ export async function findPendingStepAwaitingMultipleSteps(
   return items[0];
 }
 
+/**
+ * Query and return all pending step items matching the given awaitingStepId.
+ * @async
+ * @param {IzContext} _izContext - The Izara context.
+ * @param {string} awaitingStepId - The ID of the awaiting step.
+ * @returns {Promise<Array<object>>} List of matching items.
+ */
 export async function findPendingStepsAwaitingMultipleSteps(
   _izContext,
   awaitingStepId
@@ -239,6 +287,13 @@ export async function findPendingStepsAwaitingMultipleSteps(
   return _queryPendingStepsByAwaitingStepId(_izContext, awaitingStepId);
 }
 
+/**
+ * Retrieve the pendingStepId of the first step matching the given 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.
+ */
 export async function findPendingStepIdAwaitingMultipleSteps(
   _izContext,
   awaitingStepId
@@ -250,6 +305,13 @@ export async function findPendingStepIdAwaitingMultipleSteps(
   return items[0]?.pendingStepId;
 }
 
+/**
+ * Query and return all awaiting steps matching the given pendingStepId from byPending index table.
+ * @async
+ * @param {IzContext} _izContext - The Izara context.
+ * @param {string} pendingStepId - The ID of the pending step.
+ * @returns {Promise<Array<object>>} List of matching items.
+ */
 export async function findAwaitingMultipleStepByPending(
   _izContext,
   pendingStepId
@@ -257,13 +319,26 @@ export async function findAwaitingMultipleStepByPending(
   return _queryAwaitingStepsByPendingStepId(_izContext, pendingStepId);
 }
 
+/**
+ * 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.
+ * @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.
+ */
 export async function checkAllAwaitingStepsFinishedWithReturnParams(
   _izContext,
   pendingStepId,
   currentAwaitingStepId = null,
   errorsFound = [],
   returnValues = {},
-  settings = { checkIsAllError: true }
+  settings = { checkIsAllError: false }
 ) {
   _izContext.logger.debug(
     '[Lib:checkAllAwaitingStepsFinishedWithReturnParams] Input parameters',
@@ -346,6 +421,13 @@ export async function checkAllAwaitingStepsFinishedWithReturnParams(
   };
 }
 
+/**
+ * Clean up/delete all awaiting multiple steps records associated with the pendingStepId from both tables.
+ * @async
+ * @param {IzContext} _izContext - The Izara context.
+ * @param {string} pendingStepId - The ID of the pending step.
+ * @returns {Promise<boolean>} True if operations completed successfully.
+ */
 export async function clearAllAwaitingSteps(_izContext, pendingStepId) {
   _izContext.logger.debug('[Lib:clearAllAwaitingSteps] Input parameters', {
     pendingStepId
@@ -382,6 +464,15 @@ export async function clearAllAwaitingSteps(_izContext, pendingStepId) {
   return true;
 }
 
+/**
+ * Delete a specific awaiting step from Steps table (and optionally from byPending table if no errors found).
+ * @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.
+ * @returns {Promise<void>}
+ */
 export async function removeAwaitingMultipleStep(
   _izContext,
   awaitingStepId,

package/src/awaitingStep.js

@@ -47,6 +47,16 @@ async function _findSinglePendingStep(_izContext, awaitingStepId) {
 // 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.
+ * @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 {object} [callingFlowConfig={}] - Calling flow configuration.
+ * @returns {Promise<void>}
+ */
 export async function createAwaitingStep(
   _izContext,
   awaitingStepId,
@@ -80,10 +90,27 @@ export async function createAwaitingStep(
   );
 }
 
+/**
+ * Query and return the single pending step item that matches the 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.
+ */
 export async function findPendingStep(_izContext, awaitingStepId) {
  return _findSinglePendingStep(_izContext, awaitingStepId);
 }
 
+/**
+ * Delete a specific awaiting step record from AwaitingStep 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.
+ * @returns {Promise<void>}
+ * @throws {NoRetryError} If awaitingStepId or pendingStepId is missing.
+ */
 export async function removeAwaitingStep(
   _izContext,
   awaitingStepId,
@@ -105,6 +132,17 @@ export async function removeAwaitingStep(
   );
 }
 
+/**
+ * Delete an awaiting step record from AwaitingStep table, conditional on uniqueRequestId.
+ * @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 {string} checkUniqueRequestId - The uniqueRequestId to check.
+ * @param {string} [prefix=''] - Prefix for uniqueRequestId field name.
+ * @returns {Promise<void>}
+ * @throws {NoRetryError} If required arguments are missing.
+ */
 export async function removeAwaitingStepWithCheckUniqueRequestId(
   _izContext,
   awaitingStepId,