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

package/package.json

@@ -3,34 +3,25 @@
   "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.38",
+  "version": "1.0.40",
   "description": "Shared asynchronous flow logic",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./index.js"
   },
-  "scripts": {
-    "test": "jest"
-  },
   "repository": {
     "type": "git",
     "url": "git+ssh://git@bitbucket.org/izara-core-libraries/izara-core-library-asynchronous-flow.git"
   },
-  "jest": {
-    "testEnvironment": "node"
-  },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.1077.0",
     "@izara_project/izara-core-library-core": "^1.0.32",
     "@izara_project/izara-core-library-dynamodb": "^1.0.20",
     "@izara_project/izara-core-library-external-request": "^1.0.30",
     "@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.13",
-    "jest": "^30.4.2",
-    "ws": "^8.21.0"
+    "@izara_project/izara-shared-core": "^1.0.13"
   },
   "peerDependencies": {
     "@izara_project/izara-core-library-core": "^1.0.32",
@@ -40,6 +31,5 @@
     "@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"
-  },
-  "peerDependenciesMeta": {}
+  }
 }

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,37 +65,17 @@ export function createConcatenatedAwaitingStepId(
  * @param {string} childId
  * @returns {string}
  */
-export function createConcatenatedPendingStepId(parentId, childId) {
+function createConcatenatedPendingStepId(parentId, childId) {
   return parentId + '_' + childId;
 }
 
-/**
- * Create a simple awaitingStepId (prefix + partitionKey).
- * @param {string} partitionKey
- * @param {string} [prefix=""]
- * @returns {string}
- */
-export function createAwaitingStepId(partitionKey, prefix = '') {
-  return prefix + partitionKey;
-}
-
-/**
- * Create a simple pendingStepId (prefix + identifierId).
- * @param {string} identifierId
- * @param {string} [prefix=""]
- * @returns {string}
- */
-export function createPendingStepId(identifierId, prefix = '') {
-  return prefix + identifierId;
-}
-
 /**
  * Create parent Flow Id.
  * @async
  * @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();
 }
 
@@ -104,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;
 
@@ -117,24 +100,6 @@ export function explodePendingStepId(pendingStepId, prefix = '') {
 }
 
 // copy from izara-core-library-trigger-cache
-/**
- * Build the field name that stores "cache complete" marker.
- * @param {string} [prefix='cache']
- * @returns {string}
- */
-export function createFieldNameCacheComplete(prefix = 'cache') {
-  return prefix + 'CacheComplete';
-}
-
-/**
- * Build the field name that stores a cache "status".
- * @param {string} [prefix='cache']
- * @returns {string}
- */
-export function createFieldNameStatus(prefix = 'cache') {
-  return prefix + 'Status';
-}
-
 /**
  * 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
@@ -167,7 +132,7 @@ export function createFieldNameStatus(prefix = 'cache') {
  * @returns {Promise<[UniqueRequestStatus, Attrs]>}
  * @throws {NoRetryError} If unable to set uniqueRequestId after 2 tries
  */
-export async function checkUniqueRequestProcessing(
+async function checkUniqueRequestProcessing(
   _izContext,
   tableName,
   primaryKey,
@@ -270,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,
@@ -315,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,
@@ -333,8 +298,8 @@ export async function checkAndGetTimeCacheComplete(
   );
 
   const uniqueRequestIdFieldName = createFieldNameUniqueRequestId('cache');
-  const cacheCompleteFieldName = createFieldNameCacheComplete(prefix);
-  const statusFieldName = createFieldNameStatus(prefix);
+  const cacheCompleteFieldName = prefix + 'CacheComplete';
+  const statusFieldName = prefix + 'Status';
 
   let getTimeCacheComplete = await dynamodbSharedLib.getItem(
     _izContext,
@@ -389,7 +354,7 @@ export async function checkAndGetTimeCacheComplete(
  * @param {string} uniqueRequestIdCompleteFieldName
  * @returns {Promise<boolean>}
  */
-export async function checkCacheUniqueRequestId(
+async function checkCacheUniqueRequestId(
   _izContext,
   fullMainTableName,
   keyValues,
@@ -419,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,
@@ -469,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 = {},
@@ -515,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,
@@ -109,7 +125,11 @@ export async function createAwaitingMultipleSteps(
     options
   });
 
-  const formattedPrefix = prefix ? (prefix.endsWith('_') ? prefix : `${prefix}_`) : '';
+  const formattedPrefix = prefix
+    ? prefix.endsWith('_')
+      ? prefix
+      : `${prefix}_`
+    : '';
   const finalPendingStepId =
     formattedPrefix && !pendingStepId.startsWith(formattedPrefix)
       ? formattedPrefix + pendingStepId
@@ -154,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,
@@ -186,44 +215,48 @@ export async function createAwaitingMultipleSteps(
   return finalRecords[0]?.awaitingStepId;
 }
 
-export async function createAwaitingMultipleStepsWithAdditionalAttributes(
-  _izContext,
-  records,
-  pendingStepId
-) {
-  return createAwaitingMultipleSteps(_izContext, pendingStepId, records);
-}
-
-export async function createAwaitingMultipleStep(
+/**
+ * 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,
   pendingStepId,
-  prefix = '',
-  additionalAttributes = {}
+  data
 ) {
-  return createAwaitingMultipleSteps(_izContext, pendingStepId, [], {
-    prefix,
-    additionalAttributes
-  });
-}
+  const tableSteps = dynamodbSharedLib.tableName(
+    _izContext,
+    'AwaitingMultipleSteps'
+  );
 
-export async function createAwaitingMultipleStepsWithAdditionalAttributesAndPublish(
-  _izContext,
-  messages,
-  prefix = '',
-  flowType = {},
-  additionalAttributes = {},
-  pendingStepId
-) {
-  return createAwaitingMultipleSteps(_izContext, pendingStepId, [], {
-    prefix,
-    additionalAttributes,
-    publishConfig: {
-      messages,
-      flowType
-    }
+  await dynamodbSharedLib.updateItem(
+    _izContext,
+    tableSteps,
+    { awaitingStepId, pendingStepId },
+    data
+  );
+
+  _izContext.logger.debug('[Lib:updateAwaitingMultipleStep] Output', {
+    awaitingStepId,
+    data
   });
+
+  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
@@ -240,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
@@ -247,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
@@ -258,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
@@ -265,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',
@@ -354,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
@@ -390,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,28 +90,27 @@ export async function createAwaitingStep(
   );
 }
 
-export async function findPendingStepIdAwaitingStep(
-  _izContext,
-  awaitingStepId
-) {
-  const item = await _findSinglePendingStep(_izContext, awaitingStepId);
-  return item.pendingStepId;
-}
-
+/**
+ * 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);
-}
-
-export async function findPendingStepAwaitingStepWithCallingFlow(
-  _izContext,
-  awaitingStepId
-) {
-  const awaitingStep = await findPendingStep(_izContext, awaitingStepId);
-  const { callingFlowConfig = null, ...restAwaitingStep } = awaitingStep;
-
-  return [restAwaitingStep, callingFlowConfig];
+ 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,
@@ -123,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,