@izara_project/izara-core-library-asynchronous-flow 1.0.20 → 1.0.22

package/src/AsyncFlowSharedLib.js

@@ -1,1311 +0,0 @@
-/*
-Copyright (C) 2021 Sven Mason <http://izara.io>
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as
-published by the Free Software Foundation, either version 3 of the
-License, or (at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
-*/
-
-'use strict';
-
-// Core libraries
-import { NoRetryError } from '@izara_project/izara-core-library-core';
-import Logger from '@izara_project/izara-core-library-logger';
-
-// Data and service interaction libraries
-import dynamodbSharedLib from '@izara_project/izara-core-library-dynamodb';
-import sqsSharedLib from '@izara_project/izara-core-library-sqs';
-
-// External service interactions
-import { sqs } from '@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'
-) {
-  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,
-  prefix = ""
-) {
-  return prefix + partitionKey + "_" + sortId
-}
-
-/**
- * Create a concatenated pendingStepId from parent/child ids.
- * @param {string} parentId
- * @param {string} childId
- * @returns {string}
- */
-function createConcatenatedPendingStepId(
-  parentId,
-  childId
-) {
-  return parentId + "_" + childId
-}
-
-/**
- * Create a simple awaitingStepId (prefix + partitionKey).
- * @param {string} partitionKey
- * @param {string} [prefix=""]
- * @returns {string}
- */
-function createAwaitingStepId(
-  partitionKey,
-  prefix = ""
-) {
-  return prefix + partitionKey
-}
-
-/**
- * Create a simple pendingStepId (prefix + identifierId).
- * @param {string} identifierId
- * @param {string} [prefix=""]
- * @returns {string}
- */
-function createPendingStepId(
-  identifierId,
-  prefix = ""
-) {
-  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 = ""
-) {
-  if (prefix === "") {
-    return pendingStepId;
-  } else {
-    let identifierId = pendingStepId.slice(prefix.length)
-    // ** validate identifierId == prefix
-    if (identifierId == prefix) {
-      throw new NoRetryError("IdentifierId should not be like prefix.");
-    }
-
-    Logger.debug("return explode:", identifierId);
-    return identifierId;
-  }
-
-}
-
-// 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
-
-/**
- * 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
-  pendingStepId
-) {
-  _izContext.logger.debug("Lib:createAwaitingMultipleStepsWithAdditionalAttributes", {
-    records: records,
-    pendingStepId: pendingStepId
-  });
-  let promiseArray = []
-
-  for (let record of records) {
-
-    let attributesWhenCreate = {
-      awaitingStepId: record.awaitingStepId,
-      pendingStepId: pendingStepId,
-      timestamp: Date.now(),
-      ...record.additionalAttributes
-    }
-
-    promiseArray.push(
-      dynamodbSharedLib.putItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleSteps"),
-        attributesWhenCreate
-      )
-    );
-    promiseArray.push(
-      dynamodbSharedLib.putItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-        {
-          pendingStepId: pendingStepId,
-          awaitingStepId: record.awaitingStepId,
-          timestamp: Date.now(),
-        }
-      ));
-
-  }
-
-  await Promise.all(promiseArray);
-
-}
-
-/**
- * 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
-  pendingStepId
-) {
-  _izContext.logger.debug("Lib:createAwaitingMultipleSteps", {
-    records: records,
-    pendingStepId: pendingStepId
-  });
-
-  // // 0001 ORG.
-  let promiseArray = []
-
-  for (let record of records) {
-
-    let attributesWhenCreate = {
-      awaitingStepId: record,
-      pendingStepId: pendingStepId,
-      timestamp: Date.now()
-    }
-    _izContext.logger.debug("putItem:AwaitingMultipleSteps +++++++", { awaitingStepId: attributesWhenCreate.awaitingStepId })
-    promiseArray.push(
-      dynamodbSharedLib.putItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleSteps"),
-        attributesWhenCreate
-      )
-    );
-
-
-    _izContext.logger.debug("putItem:AwaitingMultipleStepByPending", { awaitingStepId: attributesWhenCreate.awaitingStepId })
-    promiseArray.push(
-      dynamodbSharedLib.putItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-        attributesWhenCreate
-      )
-    );
-
-    _izContext.logger.debug("check 0")
-
-  }
-  await Promise.all(promiseArray);
-
-}
-
-/**
- * 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
-) {
-
-  let pendingStepIds = [];
-
-  let listPendingStepIds = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleSteps"),
-    {
-      awaitingStepId: awaitingStepId
-    }
-  );
-
-  for (let idx = 0; idx < listPendingStepIds.Items.length; idx++) {
-    pendingStepIds.push(listPendingStepIds.Items[idx].pendingStepId)
-  }
-
-  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
-) {
-
-  let listPendingSteps = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleSteps"),
-    {
-      awaitingStepId: awaitingStepId
-    }
-  );
-  _izContext.logger.debug("Record of awaitingStepId", listPendingSteps);
-  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
-) {
-
-  let listPendingSteps = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleSteps"),
-    {
-      awaitingStepId: awaitingStepId
-    }
-  );
-  _izContext.logger.debug("Record of awaitingStepId", listPendingSteps)
-
-  if (listPendingSteps.Items.length !== 1) {
-    throw new NoRetryError("listPendingSteps not equals 1")
-  };
-  return listPendingSteps.Items[0];
-}
-
-// Use case:
-// Use only after checkAllAwaitingStepsFinished
-// 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
-) {
-
-  let listAwitingSteps = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-    {
-      pendingStepId: pendingStepId
-    }
-  );
-  _izContext.logger.debug("Record of AwaitingMultipleStepByPending", listAwitingSteps);
-  return listAwitingSteps.Items;
-}
-
-//====================================== AwaitingStep //======================================
-// AwaitingStep is when a flow is awaiting one external flow, and will continue it's flow once that one external flow is complete
-// 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,
-  pendingStepId,
-  additionalAttributes = {}, // save in top level
-  callingFlowConfig = {} // optional
-) {
-  console.log("Lib createAwaitingStep:", {
-    awaitingStepId,
-    pendingStepId,
-    additionalAttributes,
-    callingFlowConfig
-  });
-
-  let attributesWhenCreate = {
-    awaitingStepId: awaitingStepId,
-    pendingStepId: pendingStepId,
-    timestamp: Date.now(),
-    uniqueRequestId: _izContext.uniqueRequestId,
-  }
-  // loop if not empty
-  for (let additionalAttribute in additionalAttributes) {
-    attributesWhenCreate[additionalAttribute] = additionalAttributes[additionalAttribute] // each  additionalAttributes
-  }
-  if (Object.keys(callingFlowConfig).length > 0) {
-    Object.assign(attributesWhenCreate, { callingFlowConfig })
-  };
-
-  await dynamodbSharedLib.putItem(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingStep"),
-    attributesWhenCreate
-  );
-}
-
-/**
- * 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
-) {
-
-  let pendingStepIds = [];
-
-  let listPendingStepIds = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingStep"),
-    {
-      awaitingStepId: awaitingStepId
-    }
-  );
-
-  for (let idx = 0; idx < listPendingStepIds.Items.length; idx++) {
-    pendingStepIds.push(listPendingStepIds.Items[idx].pendingStepId)
-  }
-
-  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
-) {
-
-  let listPendingSteps = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingStep"),
-    {
-      awaitingStepId: awaitingStepId
-    }
-  );
-  _izContext.logger.debug("Record of awaitingStepId", listPendingSteps);
-  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
-) {
-
-  let listPendingSteps = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingStep"),
-    {
-      awaitingStepId: awaitingStepId
-    }
-  );
-  _izContext.logger.debug("Record of awaitingStepId", listPendingSteps)
-
-  if (listPendingSteps.Items.length !== 1) {
-    throw new NoRetryError("listPendingSteps not equals 1")
-  };
-  return listPendingSteps.Items[0];
-}
-
-//  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,
-) {
-
-  let callingFlowConfig = null;
-  let awaitingStep = await findPendingStepAwaitingStep(
-    _izContext,
-    awaitingStepId
-  );
-
-  // callingFlowConfig.
-  // cleaning object awaitingStep not have callingFlowConfig after return.
-  if (awaitingStep.hasOwnProperty("callingFlowConfig")) {
-    callingFlowConfig = awaitingStep.callingFlowConfig
-    delete awaitingStep.callingFlowConfig
-    console.log("after delete awaitingStep", awaitingStep);
-  };
-
-  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,
-  currentAwaitingStepId = null,
-  errorsFound = [],
-  additionalAttributes = {}
-) {
-
-  let remaining = await checkAllAwaitingStepsFinishedWithError(
-    _izContext,
-    pendingStepId,
-    currentAwaitingStepId,
-    errorsFound,
-    additionalAttributes
-  );
-  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,
-  currentAwaitingStepId = null,
-  errorsFound = [],
-  additionalAttributes = {}
-) {
-  _izContext.logger.debug("Lib:checkAllAwaitingStepsFinishedWithError", {
-    pendingStepId: pendingStepId,
-    currentAwaitingStepId: currentAwaitingStepId,
-    errorsFound: errorsFound
-  });
-
-  if (currentAwaitingStepId) {
-    await dynamodbSharedLib.updateItem(
-      _izContext,
-      await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-      {
-        pendingStepId: pendingStepId,
-        awaitingStepId: currentAwaitingStepId
-      },
-      {
-        complete: true,
-        errorsFound: errorsFound,
-        ...additionalAttributes
-      },
-    );
-
-  }
-  let listPendingStepIds = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-    {
-      pendingStepId: pendingStepId
-    },
-    {
-      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 errorsFound
-    // wrap function
-
-    if (currentAwaitingStepId && listPendingStepIds.Items[idx].awaitingStepId == currentAwaitingStepId) {
-      continue;
-    }
-    // if any record found not set to complete then there are steps not yet finished
-    if (!listPendingStepIds.Items[idx].complete) {
-      return false;
-    }
-  }
-
-  return true; // all passed
-
-
-  // // mark currentAwaitingStepId as complete, this is done to protect against race condition in between checking all complete
-  // // and then removing the record, we need to let other requests know this record is complete and need to do this before
-  // // querying all remaining records, otherwise if have only two remaining requests they might both show as records remaining
-  // // (seeing each other) and not continue flow, then each deletes their record and no records remain to trigger next step.
-  // // can result in race condition where multiple requests see all records finished, code has to account for this, but should already do so for idempotence
-  // // add query that updates the currentAwaitingStepId to have attribute "complete" = true
-  // if (currentAwaitingStepId) {
-  //   await dynamodbSharedLib.updateItem(
-  //     _izContext,
-  //     dynamodbSharedLib.tableName(tableName),
-  //     {
-  //       awaitingStepId: currentAwaitingStepId,
-  //       pendingStepId: pendingStepId
-  //     },
-  //     {
-  //       complete: true
-  //     },
-  //   )
-  // }
-  // let listPendingStepIds = await dynamodbSharedLib.query(
-  //   _izContext,
-  //   dynamodbSharedLib.tableName(tableName),
-  //   {
-  //     pendingStepId: pendingStepId
-  //   },
-  //   {
-  //     indexName: dynamodbSharedLib.tableName(tableName + 'Index'),
-  //     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 (currentAwaitingStepId && listPendingStepIds.Items[idx].awaitingStepId == currentAwaitingStepId) {
-  //     continue;
-  //   }
-  //   // if any record found not set to complete then there are steps not yet finished
-  //   if (!listPendingStepIds.Items[idx].complete) {
-  //     return false;
-  //   }
-  // }
-
-  // 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
-) {
-  // ----- query items from GSI table
-  let listPendingStepIds = await dynamodbSharedLib.query(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-    {
-      pendingStepId: pendingStepId
-    },
-  );
-  _izContext.logger.debug('listPendingStepIds', listPendingStepIds);
-
-  let promiseArray = []
-
-  for (let idx = 0; idx < listPendingStepIds.Items.length; idx++) {
-
-    _izContext.logger.debug(`delete item in dynamodb AwaitingMultipleSteps`)
-    promiseArray.push(
-      dynamodbSharedLib.deleteItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleSteps"),
-        {
-          awaitingStepId: listPendingStepIds.Items[idx].awaitingStepId,
-          pendingStepId: listPendingStepIds.Items[idx].pendingStepId
-        }
-      )
-    );
-
-    _izContext.logger.debug(`delete item in dynamodb AwaitingMultipleStepByPending`)
-    promiseArray.push(
-      dynamodbSharedLib.deleteItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-        {
-          pendingStepId: listPendingStepIds.Items[idx].pendingStepId,
-          awaitingStepId: listPendingStepIds.Items[idx].awaitingStepId
-        }
-      )
-    );
-  }
-
-  await Promise.all(promiseArray);
-
-  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,
-  pendingStepId
-) {
-
-  await dynamodbSharedLib.deleteItem(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingStep"),
-    {
-      awaitingStepId: awaitingStepId,
-      pendingStepId: pendingStepId
-    }
-  );
-}
-
-/**
- * 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,
-  pendingStepId,
-  errorsFound = []
-) {
-  _izContext.logger.debug("Lib:removeAwaitingMultipleStep", {
-    awaitingStepId: awaitingStepId,
-    pendingStepId: pendingStepId
-  })
-
-  let promiseArray = []
-
-
-  let keyValues = {
-    awaitingStepId: awaitingStepId,
-    pendingStepId: pendingStepId
-  }
-
-  let keyValuesForByPending = {
-    pendingStepId: pendingStepId,
-    awaitingStepId: awaitingStepId
-  }
-  _izContext.logger.debug('deleting ... ', {
-    keyValues,
-    keyValuesForByPending
-  });
-
-  _izContext.logger.debug(`delete item in dynamodb AwaitingMultipleSteps ==> awaitingStepId:${keyValues.awaitingStepId}`)
-  promiseArray.push(
-    dynamodbSharedLib.deleteItem(
-      _izContext,
-      await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleSteps"),
-      keyValues
-    ));
-
-  if (errorsFound.length == 0) {
-    _izContext.logger.debug(`delete item in dynamodb AwaitingMultipleStepByPending ==> awaitingStepId:${keyValues.awaitingStepId}`)
-    promiseArray.push(
-      dynamodbSharedLib.deleteItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, "AwaitingMultipleStepByPending"),
-        keyValuesForByPending
-      ));
-  }
-  await Promise.all(promiseArray);
-
-}
-
-// 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,
-  pendingStepId,
-  checkUniqueRequestId,
-  prefix = ""
-) {
-
-  // if logicalElements add queryElements.logicalElements
-  // set condition uniqueRequestId match with exists
-  const queryElementsCondition = {
-    additionalAttributes: {
-      checkUniqueRequestId: checkUniqueRequestId,
-    },
-    logicalElements: [
-      {
-        type: "logical",
-        comparison: "equals",
-        lhsAttribute: createFieldNameUniqueRequestId(prefix),
-        rhsReference: "checkUniqueRequestId"
-      },
-    ]
-  }
-
-  await dynamodbSharedLib.deleteItem(
-    _izContext,
-    await dynamodbSharedLib.tableName(_izContext, "AwaitingStep"),
-    {
-      awaitingStepId: awaitingStepId,
-      pendingStepId: pendingStepId
-    },
-    queryElementsCondition,
-    {
-      errorOnConditionalExpNotPass: false
-    }
-  );
-}
-
-//====================================== 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
- * status: "process"|"stop"|"recordNotFound"
-
- * if unable to set uniqueRequestId (because other thread updated it) throw NoRetryError
- * conditional update existingRecord set uniqueRequestId = _izContext.uniqueRequestId
- * conditional check uniqueRequestId still not exist in case another thread added
- * if conditional not pass "continue" and try again
-
- * @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,
-  primaryKey,
-  prefix = '',
-  overwriteUniqueRequestId = null,
-  uniqueRequestIdFieldName = "UniqueRequestId" // if set will check/add this fieldname with _izContext.uniqueRequestId value
-) {
-  try {
-
-    _izContext.logger.debug('current uniqueRequestId:', _izContext.uniqueRequestId)
-
-    let uniqueRequestId = _izContext.uniqueRequestId;
-    if (overwriteUniqueRequestId) {
-      uniqueRequestId = overwriteUniqueRequestId;
-    }
-
-    // add prefix
-    uniqueRequestIdFieldName = createFieldNameUniqueRequestId(
-      prefix,
-      uniqueRequestIdFieldName
-    );
-
-    //loop 3 times incase status changes, on 3rd iteration throw error (so checks 2 times)
-    for (let i = 1; i <= 3; i++) {
-      if (i == 3) {
-        throw new NoRetryError(`unable to set uniqueRequestId in table ${tableName}, record`, primaryKey);
-      }
-      //* get record from dynamo
-      let existingRecord = await dynamodbSharedLib.getItem(
-        _izContext,
-        await dynamodbSharedLib.tableName(_izContext, tableName),
-        primaryKey,
-      )
-      _izContext.logger.debug('existingRecord:', existingRecord);
-
-      let returnStatus = "process";
-
-      if (!existingRecord) {
-        // return ["recordNotFound", null]; // cannot return null, js cannot found object and throw error and dont know where it is?
-        return ["recordNotFound", {}];
-
-      } else if (!existingRecord[uniqueRequestIdFieldName]) {
-        // uniqueRequestId not yet exist
-
-        let updateAttributes = [
-          {
-            attributeName: uniqueRequestIdFieldName,
-            action: "set",
-            value: _izContext.uniqueRequestId,
-          },
-        ]
-        //* conditional check uniqueRequestId still not exist in case another thread added
-        const queryElementsWhenUpdate = {
-          logicalElements: [
-            {
-              type: "function",
-              function: "attribute_not_exists",
-              attribute: uniqueRequestIdFieldName,
-            }
-          ],
-          returnValues: 'ALL_NEW'
-        }
-        // // ----- main query ---------
-        let updateRecord = null;
-        try {
-          updateRecord = await dynamodbSharedLib.updateItem(
-            _izContext,
-            await dynamodbSharedLib.tableName(_izContext, tableName),
-            primaryKey,
-            updateAttributes,
-            queryElementsWhenUpdate,
-            { complexAttributes: true }, // force to complex
-          )
-
-          return [returnStatus, updateRecord];
-        } catch (err) { // catch error when put and handle errors.
-          _izContext.logger.debug('updateItem storedCache expired err', err);
-          if (err.name == 'ConditionalCheckFailedException') {
-            continue;
-          } else { // e.g. ProvisionedThroughputExceededException
-            // throw new Error('Unhandled Error when putItem', err) // TT, if throw will stop
-            throw (err) // TT, if throw will stop
-          }
-        } //end catch err
-
-      } else if (existingRecord[uniqueRequestIdFieldName] !== uniqueRequestId) {
-
-        // when another request/uniqueRequestId need to stop process
-        return ["stop", existingRecord];
-
-      } else if (existingRecord[uniqueRequestIdFieldName] == uniqueRequestId) {
-
-        // if existingRecord[uniqueRequestIdFieldName] == uniqueRequestId then return "process
-        return [returnStatus, existingRecord];
-
-      }
-
-    } // end loop 2 times
-    //should never get here
-    throw new NoRetryError('unexpected logic flow in checkUniqueRequestProcessing');
-
-  } catch (err) {
-    _izContext.logger.error('ERROR checkUniqueRequestProcessing:', err)
-    throw (err)
-  }
-};
-
-// ----- 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,
-  keyValues,
-  timeCacheComplete,
-  prefix
-) {
-  let [returnValue, newTimeCacheComplete, uniqueRequestId] = await checkAndGetTimeCacheComplete(
-    _izContext,
-    fullMainTableName,
-    keyValues,
-    timeCacheComplete,
-    prefix
-  );
-  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,
-  keyValues,
-  timeCacheComplete,
-  prefix
-) {
-  _izContext.logger.debug('event checkTimeCacheComplete', {
-    fullMainTableName: fullMainTableName,
-    keyValues: keyValues,
-    timeCacheComplete: timeCacheComplete,
-    prefix: prefix
-  });
-
-  let uniqueRequestIdFieldName = createFieldNameUniqueRequestId('cache');
-  let cacheCompleteFieldName = createFieldNameCacheComplete(prefix);
-  let statusFieldName = createFieldNameStatus(prefix);
-
-  let getTimeCacheComplete = await dynamodbSharedLib.getItem(
-    _izContext,
-    fullMainTableName,
-    keyValues
-  )
-  _izContext.logger.debug(`getTimeCacheComplete from ${fullMainTableName}: `, getTimeCacheComplete);
-
-  if (!getTimeCacheComplete) {
-    throw new NoRetryError(`cannot getTimeCacheComplete from ${fullMainTableName}`);
-  }
-
-  // check if exist and match with initail create not changing in flow.
-  // if (!getTimeCacheComplete[uniqueRequestIdFieldName]
-  //   // || !getTimeCacheComplete[cacheCompleteFieldName]
-  //   || (getTimeCacheComplete[cacheCompleteFieldName]
-  //     && getTimeCacheComplete[cacheCompleteFieldName] !== timeCacheComplete
-  //     && getTimeCacheComplete[statusFieldName] != "complete")
-  // ) {
-  //   return [false, getTimeCacheComplete[cacheCompleteFieldName]];
-  // } else {
-  //   return [true, getTimeCacheComplete[cacheCompleteFieldName], getTimeCacheComplete[uniqueRequestIdFieldName]];
-  // }
-
-  if (getTimeCacheComplete[cacheCompleteFieldName]
-    && getTimeCacheComplete[cacheCompleteFieldName] !== timeCacheComplete
-  ) {
-    return [false, getTimeCacheComplete[cacheCompleteFieldName]];
-  } else {
-    return [true, getTimeCacheComplete[cacheCompleteFieldName], getTimeCacheComplete[uniqueRequestIdFieldName]];
-  }
-}
-
-
-// ----- 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,
-  keyValues,
-  checkUniqueRequestId,
-  uniqueRequestIdCompleteFieldName
-) {
-
-  let cacheObject = await dynamodbSharedLib.getItem(
-    _izContext,
-    fullMainTableName,
-    keyValues
-  )
-  _izContext.logger.debug('cacheObject', cacheObject);
-
-  if (!cacheObject[uniqueRequestIdCompleteFieldName] || cacheObject[uniqueRequestIdCompleteFieldName] !== checkUniqueRequestId) {
-    return false
-  } else {
-    return true
-  }
-}
-
-
-// use shared findPendingStepIdsAwaitingStep
-// module.exports.findPendingStepIdsAwaitingStepM = async (
-//   _izContext,
-//   awaitingStepId,
-//   tableName = "AwaitingMultipleSteps"
-// ) => {
-
-//   let pendingStepIds = [];
-
-//   let listPendingStepIds = await dynamodbSharedLib.query(
-//     _izContext,
-//     dynamodbSharedLib.tableName(tableName),
-//     {
-//       awaitingStepId: awaitingStepId
-//     }
-//   );
-
-//   for (let idx = 0; idx < listPendingStepIds.Items.length; idx++) {
-//     pendingStepIds.push(listPendingStepIds.Items[idx].pendingStepId)
-//   }
-
-//   return pendingStepIds
-// }
-
-
-// use shared removeAwaitingStep
-// module.exports.removeAwaitingStep = async (
-//   _izContext,
-//   awaitingStepId,
-//   pendingStepId,
-//   tableName = "AwaitingMultipleSteps"
-// ) => {
-
-//   await dynamodbSharedLib.deleteItem(
-//     _izContext,
-//     dynamodbSharedLib.tableName(tableName),
-//     {
-//       awaitingStepId: awaitingStepId,
-//       pendingStepId: pendingStepId
-//     }
-//   );
-// }
-
-
-//====================================== end AwaitingMultipleSteps
-
-
-
-//====================================== 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,
-  partitionKeyFieldName,
-  sortKeyFieldName
-) {
-  const stringNotEmptyRegex = /^[A-Za-z0-9_-]+$/;
-
-  if (
-    !partitionKeyFieldName || !sortKeyFieldName
-    || !stringNotEmptyRegex.test(partitionKeyFieldName)
-    || !stringNotEmptyRegex.test(sortKeyFieldName)
-  ) {
-    throw new NoRetryError("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");
-    }
-  } else {
-    startKey = null; // if empty set to null so lib functions process correctly
-  }
-
-  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,
-  passOnStartKey = {},
-  numberInvocation,
-  queueName
-) {
-  _izContext.logger.debug("Lib:validateMultipleInvocations", {
-    messageProperty: messageProperty,
-    passOnStartKey: passOnStartKey,
-    numberInvocation: numberInvocation,
-    queueName: queueName
-  });
-  try {
-    const maxProcessInvocationCountImport = 20
-    if (numberInvocation >= maxProcessInvocationCountImport) {
-      _izContext.logger.error("numberInvocation exceeds maxProcessInvocationCountImport limit");
-      throw new NoRetryError("numberInvocation exceeds maxProcessInvocationCountImport limit");
-    };
-
-    if (passOnStartKey) {
-      messageProperty["startKey"] = passOnStartKey
-    };
-    messageProperty["numberInvocation"] = numberInvocation;
-
-    let messageReInvokeFunction = {
-      MessageBody: JSON.stringify(
-        messageProperty
-      ),
-      QueueUrl: await sqsSharedLib.sqsQueueUrl(_izContext, queueName)
-    };
-    _izContext.logger.debug(`Send mesage to Dsq:${queueName} `, messageReInvokeFunction);
-    await sqs.sendMessage(_izContext, messageReInvokeFunction);
-
-
-  } catch (err) {
-    throw (err)
-  }
-}
-
-export default {
-  // Helper functions
-  createFieldNameUniqueRequestId,
-  createConcatenatedAwaitingStepId,
-  createConcatenatedPendingStepId,
-  createAwaitingStepId,
-  createPendingStepId,
-  explodePendingStepId,
-  createFieldNameCacheComplete,
-  createFieldNameStatus,
-
-  // AwaitingMultipleSteps functions
-  createAwaitingMultipleStepsWithAdditionalAttributes,
-  createAwaitingMultipleSteps,
-  checkAllAwaitingStepsFinishedWithError,
-  checkAllAwaitingStepsFinished,
-  clearAllAwaitingSteps,
-  removeAwaitingMultipleStep,
-  findPendingStepIdsAwaitingMultipleSteps,
-  findPendingStepsAwaitingMultipleSteps,
-  findPendingStepAwaitingMultipleSteps,
-  findAwaitingMultipleStepByPending,
-
-  // AwaitingStep functions
-  createAwaitingStep,
-  findPendingStepIdsAwaitingStep,
-  findPendingStepAwaitingStep,
-  findPendingStepsAwaitingStep,
-  findPendingStepAwaitingStepWithCallingFlow,
-  removeAwaitingStep,
-  removeAwaitingStepWithCheckUniqueRequestId,
-
-  // Unique Request Processing functions
-  checkUniqueRequestProcessing,
-
-  // Cache functions
-  checkTimeCacheComplete,
-  checkAndGetTimeCacheComplete,
-  checkCacheUniqueRequestId,
-
-  // Validation functions
-  validateStartKeyParam,
-  validateMultipleInvocations
-};