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

package/src/awaitingMultipleSteps.js

@@ -0,0 +1,560 @@
+/*
+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/>.
+*/
+
+import { NoRetryError } from '@izara_project/izara-core-library-core';
+import dynamodbSharedLib from '@izara_project/izara-core-library-dynamodb';
+
+//====================================== 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>}
+ */
+export 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,
+        dynamodbSharedLib.tableName(_izContext, 'AwaitingMultipleSteps'),
+        attributesWhenCreate
+      )
+    );
+    promiseArray.push(
+      dynamodbSharedLib.putItem(
+        _izContext,
+        dynamodbSharedLib.tableName(
+          _izContext,
+          'AwaitingMultipleStepByPending'
+        ),
+        {
+          pendingStepId: pendingStepId,
+          awaitingStepId: record.awaitingStepId,
+          timestamp: Date.now()
+        }
+      )
+    );
+  }
+
+  await Promise.all(promiseArray);
+}
+
+/**
+ * Batch initializes multiple pending steps in DynamoDB.
+ * Records status in both the primary tracking table and the pending-relation table.
+ * * @async
+ * @param {Object} _izContext - The system context providing logger and shared utilities.
+ * @param {Array<Object>} records - Array of step objects to be initialized.
+ * @param {string} records[].awaitingStepId - The unique identifier for the specific step.
+ * @param {Object} [records[].additionalAttributes] - Optional metadata to store with the step.
+ * @param {string} pendingStepId - The parent ID linking all related steps together.
+ * @returns {Promise<void>}
+ */
+export async function initAwaitingStepsWithAttrs(
+  _izContext,
+  records,
+  pendingStepId
+) {
+  _izContext.logger.debug('Lib:initAwaitingStepsWithAttrs', {
+    records,
+    pendingStepId
+  });
+
+  const timestamp = Date.now();
+  const promiseArray = [];
+
+  for (const record of records) {
+    promiseArray.push(
+      dynamodbSharedLib.putItem(
+        _izContext,
+        dynamodbSharedLib.tableName(_izContext, 'AwaitingMultipleSteps'),
+        {
+          awaitingStepId: record.awaitingStepId,
+          pendingStepId,
+          timestamp
+        }
+      )
+    );
+    promiseArray.push(
+      dynamodbSharedLib.putItem(
+        _izContext,
+        dynamodbSharedLib.tableName(
+          _izContext,
+          'AwaitingMultipleStepByPending'
+        ),
+        {
+          pendingStepId,
+          awaitingStepId: record.awaitingStepId,
+          timestamp,
+          ...record.additionalAttributes
+        }
+      )
+    );
+  }
+
+  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>}
+ */
+export async function createAwaitingMultipleSteps(
+  _izContext,
+  records, // array of awaitingStepIds
+  pendingStepId
+) {
+  _izContext.logger.debug('Lib:createAwaitingMultipleSteps', {
+    records: records,
+    pendingStepId: pendingStepId
+  });
+
+  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,
+        dynamodbSharedLib.tableName(_izContext, 'AwaitingMultipleSteps'),
+        attributesWhenCreate
+      )
+    );
+
+    _izContext.logger.debug('putItem:AwaitingMultipleStepByPending', {
+      awaitingStepId: attributesWhenCreate.awaitingStepId
+    });
+    promiseArray.push(
+      dynamodbSharedLib.putItem(
+        _izContext,
+        dynamodbSharedLib.tableName(
+          _izContext,
+          'AwaitingMultipleStepByPending'
+        ),
+        attributesWhenCreate
+      )
+    );
+  }
+  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[]>}
+ */
+export async function findPendingStepIdsAwaitingMultipleSteps(
+  _izContext,
+  awaitingStepId
+) {
+  let pendingStepIds = [];
+
+  let listPendingStepIds = await dynamodbSharedLib.query(
+    _izContext,
+    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[]>}
+ */
+export async function findPendingStepsAwaitingMultipleSteps(
+  _izContext,
+  awaitingStepId
+) {
+  let listPendingSteps = await dynamodbSharedLib.query(
+    _izContext,
+    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
+ */
+export async function findPendingStepAwaitingMultipleSteps(
+  _izContext,
+  awaitingStepId
+) {
+  let listPendingSteps = await dynamodbSharedLib.query(
+    _izContext,
+    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[]>}
+ */
+export async function findAwaitingMultipleStepByPending(
+  _izContext,
+  pendingStepId
+) {
+  let listAwaitingSteps = await dynamodbSharedLib.query(
+    _izContext,
+    dynamodbSharedLib.tableName(_izContext, 'AwaitingMultipleStepByPending'),
+    {
+      pendingStepId: pendingStepId
+    }
+  );
+  _izContext.logger.debug(
+    'Record of AwaitingMultipleStepByPending',
+    listAwaitingSteps
+  );
+  return listAwaitingSteps.Items;
+}
+
+/**
+ * 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>}
+ */
+export 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,
+      dynamodbSharedLib.tableName(_izContext, 'AwaitingMultipleStepByPending'),
+      {
+        pendingStepId: pendingStepId,
+        awaitingStepId: currentAwaitingStepId
+      },
+      {
+        complete: true,
+        errorsFound: errorsFound,
+        ...additionalAttributes
+      }
+    );
+  }
+  let listPendingStepIds = await dynamodbSharedLib.query(
+    _izContext,
+    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
+}
+
+/**
+ * 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
+ */
+export async function clearAllAwaitingSteps(_izContext, pendingStepId) {
+  // ----- query items from GSI table
+  let listPendingStepIds = await dynamodbSharedLib.query(
+    _izContext,
+    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,
+        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,
+        dynamodbSharedLib.tableName(
+          _izContext,
+          'AwaitingMultipleStepByPending'
+        ),
+        {
+          pendingStepId: listPendingStepIds.Items[idx].pendingStepId,
+          awaitingStepId: listPendingStepIds.Items[idx].awaitingStepId
+        }
+      )
+    );
+  }
+
+  await Promise.all(promiseArray);
+
+  return true;
+}
+
+/**
+ * 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>}
+ */
+export 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,
+      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,
+        dynamodbSharedLib.tableName(
+          _izContext,
+          'AwaitingMultipleStepByPending'
+        ),
+        keyValuesForByPending
+      )
+    );
+  }
+  await Promise.all(promiseArray);
+}
+
+/**
+ * Checks if all awaiting steps for a pending step are complete after marking the current one as complete.
+ * If all steps are finished, it returns `true` and an object containing the `additionalAttributes` from each of the completed steps, keyed by their `awaitingStepId`.
+ * If any other step is not yet complete, it returns `[false, null]`.
+ * @async
+ * @param {IzContext} _izContext
+ * @param {string} pendingStepId
+ * @param {string|null} [currentAwaitingStepId=null] - The step that has just finished.
+ * @param {any[]} [errorsFound=[]]
+ * @param {Attrs} [additionalAttributes={}]
+ * @returns {Promise<[boolean, Record<string, any>|null]>} A tuple indicating completion status and the collected attributes, or null if not all steps are complete.
+ */
+export async function syncAndCheckStepsCompletion(
+  _izContext,
+  pendingStepId,
+  currentAwaitingStepId = null,
+  errorsFound = [],
+  additionalAttributes = {}
+) {
+  _izContext.logger.debug(
+    'Lib:checkAllAwaitingMultipleStepsFinishedWithErrorAndReturnAdditionalAttributes',
+    {
+      pendingStepId,
+      currentAwaitingStepId,
+      errorsFound,
+      additionalAttributes
+    }
+  );
+
+  if (currentAwaitingStepId) {
+    await dynamodbSharedLib.updateItem(
+      _izContext,
+      dynamodbSharedLib.tableName(_izContext, 'AwaitingMultipleStepByPending'),
+      { pendingStepId, awaitingStepId: currentAwaitingStepId },
+      {
+        complete: true,
+        errorsFound,
+        ...additionalAttributes
+      }
+    );
+  }
+
+  const awaitingStepItems = await dynamodbSharedLib.query(
+    _izContext,
+    dynamodbSharedLib.tableName(_izContext, 'AwaitingMultipleStepByPending'),
+    { pendingStepId },
+    {
+      limit: 50 // arbitrary limit so not pull too many results, need >2 because some others might be marked as "complete" = true
+    }
+  );
+
+  const collectedAttributes = {};
+  for (const item of awaitingStepItems.Items) {
+    // For any step OTHER than the one we just completed, if it's not marked as complete,
+    // then the overall process is not finished.
+    if (item.awaitingStepId !== currentAwaitingStepId && !item.complete) {
+      return [false, null];
+    }
+
+    // If the step is complete (which all should be if we reach this point),
+    // collect its attributes if they exist.
+    if (item.additionalAttributes) {
+      collectedAttributes[item.awaitingStepId] = item.additionalAttributes;
+    }
+  }
+
+  // If the loop completes, it means all steps were finished.
+  return [true, collectedAttributes];
+}