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

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

package/src/asyncFlowSharedLib.js

@@ -28,13 +28,57 @@ import { sqs } from '@izara_project/izara-core-library-external-request';
 
 import { identifierUuid } from '@izara_project/izara-shared-core';
 
+/**
+ * Helper to safely join a prefix and an ID with a single underscore.
+ * Ensures no duplicate underscores between them.
+ * @param {string} id
+ * @param {string} [prefix='']
+ * @returns {string}
+ */
+function _joinPrefixAndId(id, prefix = '') {
+  if (!prefix) return id;
+
+  const cleanPrefix = prefix.endsWith('_') ? prefix.slice(0, -1) : prefix;
+  const cleanId = id.startsWith('_') ? id.slice(1) : id;
+
+  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}
+ */
+function createAwaitingStepId(partitionKey, prefix = '') {
+  return _joinPrefixAndId(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}
+ */
+function createPendingStepId(identifierId, prefix = '') {
+  return _joinPrefixAndId(identifierId, prefix);
+}
+
 /**
  * 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 +92,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 +102,7 @@ export function createConcatenatedAwaitingStepId(
  * @param {string} childId
  * @returns {string}
  */
-export function createConcatenatedPendingStepId(parentId, childId) {
+function createConcatenatedPendingStepId(parentId, childId) {
   return parentId + '_' + childId;
 }
 
@@ -72,8 +112,8 @@ 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 = '') {
-  return (prefix ? `${prefix}_` : '') + identifierUuid();
+function createParentFlowId(prefix = '') {
+  return _joinPrefixAndId(identifierUuid(), prefix);
 }
 
 /**
@@ -84,7 +124,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 +169,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 +272,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 +317,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 +391,7 @@ export async function checkAndGetTimeCacheComplete(
  * @param {string} uniqueRequestIdCompleteFieldName
  * @returns {Promise<boolean>}
  */
-export async function checkCacheUniqueRequestId(
+async function checkCacheUniqueRequestId(
   _izContext,
   fullMainTableName,
   keyValues,
@@ -381,7 +421,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 +471,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 +517,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

@@ -19,7 +19,10 @@ import dynamodbSharedLib from '@izara_project/izara-core-library-dynamodb';
 import { sns } from '@izara_project/izara-core-library-external-request';
 import snsSharedLib from '@izara_project/izara-core-library-sns';
 
-import { createParentFlowId } from './asyncFlowSharedLib.js';
+import {
+  createParentFlowId,
+  createPendingStepId
+} from './asyncFlowSharedLib.js';
 
 function _assertPendingStepId(pendingStepId) {
   if (!pendingStepId) {
@@ -92,36 +95,45 @@ 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.
+ * @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 {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.
+ */
 export async function createAwaitingMultipleSteps(
   _izContext,
   pendingStepId,
   records = [],
   options = {}
 ) {
-  const {
-    prefix = '',
-    additionalAttributes = {},
-    publishConfig = null
-  } = options;
+  const { prefix = '', additionalAttributes = {}, flowType = null } = options;
 
   _izContext.logger.debug('[Lib:AsyncFlow:createAwaitingMultipleSteps] Input', {
     pendingStepId,
     options
   });
 
-  const formattedPrefix = prefix
-    ? prefix.endsWith('_')
-      ? prefix
-      : `${prefix}_`
-    : '';
-  const finalPendingStepId =
-    formattedPrefix && !pendingStepId.startsWith(formattedPrefix)
-      ? formattedPrefix + pendingStepId
-      : pendingStepId;
+  const finalPendingStepId = createPendingStepId(pendingStepId, prefix);
+
+  const hasFlowPublish = flowType || records.some(r => r.flowType);
 
   let finalRecords = records;
 
-  if (finalRecords.length === 0 && !publishConfig) {
+  if (finalRecords.length === 0 && !hasFlowPublish) {
     finalRecords = [
       {
         awaitingStepId: createParentFlowId(prefix),
@@ -130,38 +142,47 @@ export async function createAwaitingMultipleSteps(
     ];
   }
 
-  if (publishConfig) {
-    const { messages, flowType = {} } = publishConfig;
-    const { flowTag, serviceTag } = flowType;
-
-    if (!Array.isArray(messages)) {
-      throw new NoRetryError('messages must be an array');
-    }
+  if (hasFlowPublish) {
+    finalRecords = records.map(record => {
+      const recordFlowType = record.flowType || flowType;
 
-    if (!flowTag || !serviceTag) {
-      throw new NoRetryError('flowType must both flowTag serviceTag');
-    }
-
-    finalRecords = messages.map(message => {
-      const parentFlowId = createParentFlowId(prefix);
+      if (!recordFlowType || !recordFlowType.flowTag || !recordFlowType.serviceTag) {
+        throw new NoRetryError('record.flowType must have both flowTag and serviceTag');
+      }
 
+      const awaitingStepId =
+        record.awaitingStepId || createParentFlowId(prefix);
       return {
-        awaitingStepId: parentFlowId,
+        awaitingStepId,
         additionalAttributes,
         message: {
-          ...message,
-          parentFlowId
-        }
+          ...record.message,
+          parentFlowId: awaitingStepId
+        },
+        topicArn: snsSharedLib.snsTopicArnByFlowSchema(
+          _izContext,
+          recordFlowType.flowTag,
+          recordFlowType.serviceTag
+        )
       };
     });
   }
 
   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,
@@ -169,19 +190,12 @@ export async function createAwaitingMultipleSteps(
     }
   );
 
-  if (publishConfig) {
-    const topicArn = snsSharedLib.snsTopicArnByFlowSchema(
-      _izContext,
-      publishConfig.flowType.flowTag,
-      publishConfig.flowType.serviceTag
-    );
-
+  if (hasFlowPublish) {
     await Promise.all(
-      finalRecords.map(({ message }) =>
+      finalRecords.map(({ message, topicArn }) =>
         sns.publishAsync(_izContext, {
           TopicArn: `${topicArn}_In`,
-          Message: JSON.stringify(message),
-          MessageAttributes: {}
+          Message: JSON.stringify(message)
         })
       )
     );
@@ -190,6 +204,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 +239,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 +262,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 +276,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 +294,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 +308,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 +410,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 +453,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,