@izara_project/izara-core-library-dynamodb 1.0.18 → 1.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izara_project/izara-core-library-dynamodb",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Connecting with AWS DynamoDB Resource",
   "main": "index.js",
   "scripts": {
@@ -14,41 +14,18 @@
   "license": "AGPL-3.0-or-later",
   "homepage": "https://bitbucket.org/izara-core-libraries/izara-core-library-dynamodb/src/master/README.md",
   "devDependencies": {
-    "jest": "^30.4.1"
+    "jest": "^30.4.2"
   },
   "jest": {
     "testEnvironment": "node"
   },
   "type": "module",
   "peerDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.0.0",
-    "@aws-sdk/lib-dynamodb": "^3.0.0",
-    "@aws-sdk/util-dynamodb": "^3.0.0",
-    "@izara_project/izara-core-library-core": "^1.0.28",
-    "lodash": "^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@aws-sdk/client-dynamodb": {
-      "optional": false
-    },
-    "@aws-sdk/lib-dynamodb": {
-      "optional": false
-    },
-    "@aws-sdk/util-dynamodb": {
-      "optional": false
-    },
-    "@izara_project/izara-core-library-core": {
-      "optional": false
-    },
-    "lodash": {
-      "optional": true
-    }
-  },
-  "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.1045.0",
     "@aws-sdk/lib-dynamodb": "^3.1045.0",
     "@aws-sdk/util-dynamodb": "^3.996.2",
-    "@izara_project/izara-core-library-core": "^1.0.32",
-    "lodash": "^4.18.1"
-  }
+    "@izara_project/izara-core-library-core": "^1.0.28"
+  },
+  "peerDependenciesMeta": {},
+  "dependencies": {}
 }

package/src/DynamoDBSharedLib.js

@@ -19,8 +19,6 @@ import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import { DynamoDB } from '@aws-sdk/client-dynamodb';
 import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
 
-import cloneDeep from 'lodash/cloneDeep';
-
 // External Izara project imports
 import { NoRetryError } from '@izara_project/izara-core-library-core';
 // import { getServiceNameWithCache } = require('@izara_project/izara-core-library-service-schemas').serviceConfig;
@@ -41,13 +39,13 @@ const dynamodb = DynamoDBDocument.from(new DynamoDB(), {
 // const dynamodb = require('@izara_project/izara-core-library-external-request').dynamodb
 
 /**
- * create table name
- * @param {Object} _izContext
- * @param {string} tableName  - suffix tablename
- * @param {string} serviceTag
- * @returns {string} full tablename
+ * Constructs the full DynamoDB table name based on the service tag, environment stage, and table suffix.
+ *
+ * @param {Object} _izContext - The Izara context object containing logger, correlation IDs, and request details.
+ * @param {string} tableName - The base name or suffix of the DynamoDB table.
+ * @param {string} [serviceTag=null] - Optional service tag to override the default environment service tag (`process.env.iz_serviceTag`).
+ * @returns {string} The fully constructed table name.
  */
-
 function tableName(_izContext, tableName, serviceTag = null) {
   if (!serviceTag) {
     return process.env.iz_serviceTag + process.env.iz_stage + tableName;
@@ -57,10 +55,12 @@ function tableName(_izContext, tableName, serviceTag = null) {
 }
 
 /**
- * Creates a string set element for use with documentClient
- * @param {string[]} stringSet
+ * Creates a DynamoDB String Set from an array of strings.
+ * Used for formatting arrays into a Set structure compatible with DynamoDB DocumentClient.
  *
- * @returns {string} String formatted as a string set for Dynamo
+ * @param {string[]} stringSetArray - An array of strings to be converted into a Set.
+ * @returns {Set<string>} A JavaScript Set containing the string values.
+ * @throws {Error} If the Set cannot be created.
  */
 function arrayToStringSet(stringSetArray) {
   try {
@@ -77,19 +77,36 @@ function arrayToStringSet(stringSetArray) {
 }
 
 /**
- * Marshalls StringSet from dynamo get/query into an array
- * @param {Object} stringSet
+ * Converts a DynamoDB StringSet object retrieved from Get or Query operations into a standard JavaScript array.
+ * Performs a deep clone to ensure the returned array does not mutate the original object.
  *
- * @returns {string[]}
+ * @param {Object} stringSet - The DynamoDB StringSet object containing a `values` property.
+ * @param {string[]} stringSet.values - The array of string values inside the DynamoDB StringSet.
+ * @returns {string[]} An array of strings extracted from the StringSet.
  */
 function stringSetToArray(stringSet) {
-  return cloneDeep(stringSet.values);
+  return structuredClone(stringSet.values);
 }
 
+/**
+ * Removes undefined values from a given attributes object using DynamoDB's marshall and unmarshall utility.
+ *
+ * @param {Object} attributes - The attributes object to be processed.
+ * @returns {Object} A new object with all undefined values removed, compatible with DynamoDB item structure.
+ */
 function removeUndefined(attributes) {
   return unmarshall(marshall(attributes, { removeUndefinedValues: true }));
 }
 
+/**
+ * Extracts and cleans correlation ID values from the Izara context object.
+ * Removes any undefined properties before returning.
+ *
+ * @param {Object} _izContext - The Izara context object.
+ * @param {string} _izContext.awsRequestId - The AWS request ID.
+ * @param {Object} _izContext.correlationIds - The correlation IDs manager.
+ * @returns {Object} An object containing the extracted `awsRequestId` and `xCorrelationId` properties.
+ */
 function correlationIdValues(_izContext) {
   return removeUndefined({
     awsRequestId: _izContext.awsRequestId,
@@ -98,6 +115,17 @@ function correlationIdValues(_izContext) {
 }
 
 // ----- Helper function for reformConditionExpression
+
+/**
+ * Validates and extracts the value of a specific logical side (e.g., left-hand side or right-hand side)
+ * for a DynamoDB condition expression. It checks that only one property format is set per side and prepends
+ * appropriate prefixes (e.g., `:` for references).
+ *
+ * @param {Object} logicalElement - The logical element object containing the condition details.
+ * @param {string} prefixSide - The prefix identifying the side to check (e.g., 'lhs', 'rhs', 'betweenStart').
+ * @returns {string|number} The validated value or reference string for the expression.
+ * @throws {NoRetryError} If the side logic is missing, duplicated, or uses an unsupported reference type.
+ */
 function validateSideHand(logicalElement, prefixSide) {
   // helper function
   // _izContext.logger.debug('logicalElement in prefixSide', prefixSide);
@@ -146,6 +174,17 @@ function validateSideHand(logicalElement, prefixSide) {
 } // end validateSideHand
 
 // ----- Helper function for query dynamodb
+
+/**
+ * Helper function to reform query elements into a DynamoDB ConditionExpression and ExpressionAttributeValues.
+ * It processes logical elements recursively to build the condition string and maps additional attributes to expression values.
+ *
+ * @param {Object} _izContext - The Izara context object.
+ * @param {Object} queryElements - The elements specifying the query conditions.
+ * @param {Object[]} [queryElements.logicalElements] - Array of logical condition definitions.
+ * @param {Object} [queryElements.additionalAttributes] - Key-value pairs to be added to ExpressionAttributeValues.
+ * @returns {[string|undefined, Object|null]} An array where the first element is the constructed `ConditionExpression` string, and the second is the `ExpressionAttributeValues` object.
+ */
 function reformConditionExpression(_izContext, queryElements) {
   // _izContext.logger.debug('queryElements', queryElements);
   // ----- add ConditionExpression to payload if queryElements has prop logicalElements
@@ -176,10 +215,14 @@ function reformConditionExpression(_izContext, queryElements) {
 }
 
 /**
- * Process a combination logical elements to conditionalExpression
- * @param {object[]} logicalElements
+ * Recursively processes an array of logical elements to construct a DynamoDB ConditionalExpression string.
+ * Supports logical comparisons (equals, between, etc.), logical operators (and, or), functions (begins_with, attribute_exists), and nested grouping.
  *
- * @returns {string} conditionalExpression
+ * @param {Object} _izContext - The Izara context object containing the logger.
+ * @param {Object[]} logicalElements - An array of objects defining the logical conditions and operators.
+ * @param {number} level - The current recursion depth level to prevent infinite recursion.
+ * @returns {string|null} The constructed conditional expression string, or null if the elements array is empty.
+ * @throws {NoRetryError|Error} If validation fails, syntax is incorrect, or maximum recursion depth is exceeded.
  */
 function processLogicalElements(_izContext, logicalElements, level) {
   /*
@@ -393,15 +436,17 @@ function processLogicalElements(_izContext, logicalElements, level) {
 } // module processLogicalElements
 
 /**
- * Executes a GetItem query to DynamoDB
- * @param {string} tableName
- * @param {object} keyValues
- * @param {object} [queryElements={}] // eg returned only some attributes (ProjectionExpression)
- * @param {object} [settings={}]
- * @param {boolean} [settings.errorOnNoRecordFound=false]
- * @param {boolean} [settings.retryOnErrorNoRecordFound=false]
+ * Executes a GetItem operation on DynamoDB to retrieve a single record.
  *
- * @returns {object} single record return value from the query, or Null if none found
+ * @param {Object} _izContext - The Izara context object containing the logger and tracing info.
+ * @param {string} tableName - The name of the DynamoDB table to read from.
+ * @param {Object} keyValues - The primary key (partition key and optional sort key) of the item to retrieve.
+ * @param {Object} [queryElements={}] - Additional query options (e.g., ProjectionExpression features). Note: GSI/LSI are not supported for getItem.
+ * @param {Object} [settings={}] - Additional behavior settings for the operation.
+ * @param {boolean} [settings.errorOnNoRecordFound=false] - If true, throws an error when no item is found instead of returning null.
+ * @param {boolean} [settings.retryOnErrorNoRecordFound=false] - If true and errorOnNoRecordFound is also true, throws a retryable Error instead of a NoRetryError.
+ * @returns {Promise<Object|null>} A promise that resolves to the retrieved item object, or null if no record is found (and errorOnNoRecordFound is false).
+ * @throws {Error|NoRetryError} If the database operation fails or if no record is found and errorOnNoRecordFound is true.
  */
 async function getItem(
   _izContext,
@@ -476,22 +521,42 @@ async function getItem(
   }
 } // end module getItem
 
+// /**
+//  * Executes a Query on DynamoDB
+//  * @param {string} tableName
+//  * @param {object} partitionKeyValue                         - partitionKey
+//  * @param {object} [queryElements={}]
+//  * @param {object} queryElements.sortKeyCondition            - comparisons and between
+//  * @param {string[]} queryElements.projectionExpression      - return specific attribute, array of string attribute names.
+//  * @param {string} queryElements.select                      - return specific item eg. ALL_ATTRIBUTES | COUNT
+//  * @param {number} queryElements.limit                       - integer of limit item per pagequery
+//  * @param {object} queryElements.exclusiveStartKey           - partitionKey and sortKey
+//  * @param {string} queryElements.indexName                   - global secondary index name
+//  * @param {string} queryElements.descending                  - ScanIndexForward be false
+//  * @param {object} [settings={}]
+//  * @param {numeric} [settings.numPagesToRequest=1] // not sure will use? Script will automatically request multiple pages of results
+//  *
+//  * @returns {object[], object} array of records from .Items in query result, and queryInfo object with properties such as LastEvaluatedKey
+//  */
 /**
- * Executes a Query on DynamoDB
- * @param {string} tableName
- * @param {object} partitionKeyValue                         - partitionKey
- * @param {object} [queryElements={}]
- * @param {object} queryElements.sortKeyCondition            - comparisons and between
- * @param {string[]} queryElements.projectionExpression      - return specific attribute, array of string attribute names.
- * @param {string} queryElements.select                      - return specific item eg. ALL_ATTRIBUTES | COUNT
- * @param {number} queryElements.limit                       - integer of limit item per pagequery
- * @param {object} queryElements.exclusiveStartKey           - partitionKey and sortKey
- * @param {string} queryElements.indexName                   - global secondary index name
- * @param {string} queryElements.descending                  - ScanIndexForward be false
- * @param {object} [settings={}]
- * @param {numeric} [settings.numPagesToRequest=1] // not sure will use? Script will automatically request multiple pages of results
+ * Executes a Query operation on DynamoDB to retrieve one or multiple records based on partition and sort key conditions.
+ * Supports pagination, indexing, and specific attribute projection.
  *
- * @returns {object[], object} array of records from .Items in query result, and queryInfo object with properties such as LastEvaluatedKey
+ * @param {Object} _izContext - The Izara context object containing the logger and tracing info.
+ * @param {string} tableName - The name of the DynamoDB table to query.
+ * @param {Object} partitionKeyValue - An object containing a single key-value pair representing the partition key.
+ * @param {Object} [queryElements={}] - Elements to configure the query such as conditions, limits, and projections.
+ * @param {Object} [queryElements.sortKeyCondition] - Condition for the sort key, requiring `name`, `comparison`, and `value` (or `betweenStartValue`/`betweenEndValue`).
+ * @param {string[]} [queryElements.projectionExpression] - Array of attribute names to return (cannot be used with `select` unless `select` is 'SPECIFIC_ATTRIBUTES').
+ * @param {string} [queryElements.select] - Type of data to return (e.g., 'ALL_ATTRIBUTES', 'COUNT', 'SPECIFIC_ATTRIBUTES').
+ * @param {number} [queryElements.limit] - Maximum number of items to evaluate per page query.
+ * @param {Object} [queryElements.exclusiveStartKey] - Pagination token corresponding to `LastEvaluatedKey` from a previous query.
+ * @param {string} [queryElements.indexName] - The name of a Global Secondary Index (GSI) or Local Secondary Index (LSI) to query.
+ * @param {boolean} [queryElements.descending] - If true, reverses the sort order (sets `ScanIndexForward` to false).
+ * @param {Object} [settings={}] - Additional execution settings.
+ * @param {number} [settings.numPagesToRequest=1] - The maximum number of pages to auto-fetch. If > 1, it will paginate automatically until the limit or data ends.
+ * @returns {Promise<Object>} A promise that resolves to the DynamoDB query response object, typically containing `Items`, `Count`, `ScannedCount`, and `LastEvaluatedKey`.
+ * @throws {NoRetryError|Error} If query configuration is invalid, limits are exceeded, or the database operation fails.
  */
 async function query(
   _izContext,
@@ -792,20 +857,31 @@ async function query(
   }
 }
 
+// /**
+//  * Executes a Query on DynamoDB and get only Items
+//  * @param {string} tableName
+//  * @param {object} partitionKeyValue                         - partitionKey
+//  * @param {object} [queryElements={}]
+//  * @param {object} queryElements.sortKeyCondition            - comparisons and between
+//  * @param {string[]} queryElements.projectionExpression      - return specific attribute, array of string attribute names.
+//  * @param {string} queryElements.select                      - return specific item eg. ALL_ATTRIBUTES | COUNT
+//  * @param {number} queryElements.limit                       - integer of limit item per pagequery
+//  * @param {object} queryElements.exclusiveStartKey           - partitionKey and sortKey
+//  * @param {object} [settings={}]
+//  * @param {numeric} [settings.numPagesToRequest=1] // not sure will use? Script will automatically request multiple pages of results
+//  *
+//  * @returns {object[], object} array of records from .Items in query result, and queryInfo object with properties such as LastEvaluatedKey
+//  */
 /**
- * Executes a Query on DynamoDB and get only Items
- * @param {string} tableName
- * @param {object} partitionKeyValue                         - partitionKey
- * @param {object} [queryElements={}]
- * @param {object} queryElements.sortKeyCondition            - comparisons and between
- * @param {string[]} queryElements.projectionExpression      - return specific attribute, array of string attribute names.
- * @param {string} queryElements.select                      - return specific item eg. ALL_ATTRIBUTES | COUNT
- * @param {number} queryElements.limit                       - integer of limit item per pagequery
- * @param {object} queryElements.exclusiveStartKey           - partitionKey and sortKey
- * @param {object} [settings={}]
- * @param {numeric} [settings.numPagesToRequest=1] // not sure will use? Script will automatically request multiple pages of results
+ * Executes a Query operation on DynamoDB and returns only the array of `Items`.
+ * Acts as a wrapper around the `query` function for convenience when pagination metadata isn't needed.
  *
- * @returns {object[], object} array of records from .Items in query result, and queryInfo object with properties such as LastEvaluatedKey
+ * @param {Object} _izContext - The Izara context object containing the logger.
+ * @param {string} tableName - The name of the DynamoDB table to query.
+ * @param {Object} partitionKeyValue - An object containing a single key-value pair for the partition key.
+ * @param {Object} [queryElements={}] - Elements to configure the query (conditions, limits, projections).
+ * @param {Object} [settings={}] - Additional execution settings (e.g., auto-pagination `numPagesToRequest`).
+ * @returns {Promise<Object[]>} A promise that resolves to an array of the retrieved item objects.
  */
 async function queryResults(
   _izContext,
@@ -824,25 +900,45 @@ async function queryResults(
   return queryResults.Items;
 }
 
+// /**
+//  * Executes a Scan operation on DynamoDB
+//  * Scans the entire table or a secondary index with optional filters.
+//  * NOTE: Scan operations are expensive and should be used sparingly.
+//  *
+//  * @param {object} _izContext                                - Izara context object for logging
+//  * @param {string} tableName                                 - Name of the DynamoDB table
+//  * @param {object} [queryElements={}]                        - Optional query parameters
+//  * @param {object[]} queryElements.logicalElements           - Filter conditions (uses FilterExpression)
+//  * @param {object} queryElements.additionalAttributes        - Additional attribute values for filters
+//  * @param {string[]} queryElements.projectionExpression      - Array of attribute names to return
+//  * @param {string} queryElements.select                      - Return mode: ALL_ATTRIBUTES | COUNT | SPECIFIC_ATTRIBUTES
+//  * @param {number} queryElements.limit                       - Maximum items per page
+//  * @param {object} queryElements.exclusiveStartKey           - Pagination start key
+//  * @param {string} queryElements.indexName                   - Global secondary index name
+//  * @param {object} [settings={}]                             - Operation settings
+//  * @param {number} [settings.numPagesToRequest=1]            - Number of pages to auto-paginate (default: 1)
+//  *
+//  * @returns {Promise<object>} Object containing Items, Count, ScannedCount, and LastEvaluatedKey
+//  */
 /**
- * Executes a Scan operation on DynamoDB
- * Scans the entire table or a secondary index with optional filters.
- * NOTE: Scan operations are expensive and should be used sparingly.
- *
- * @param {object} _izContext                                - Izara context object for logging
- * @param {string} tableName                                 - Name of the DynamoDB table
- * @param {object} [queryElements={}]                        - Optional query parameters
- * @param {object[]} queryElements.logicalElements           - Filter conditions (uses FilterExpression)
- * @param {object} queryElements.additionalAttributes        - Additional attribute values for filters
- * @param {string[]} queryElements.projectionExpression      - Array of attribute names to return
- * @param {string} queryElements.select                      - Return mode: ALL_ATTRIBUTES | COUNT | SPECIFIC_ATTRIBUTES
- * @param {number} queryElements.limit                       - Maximum items per page
- * @param {object} queryElements.exclusiveStartKey           - Pagination start key
- * @param {string} queryElements.indexName                   - Global secondary index name
- * @param {object} [settings={}]                             - Operation settings
- * @param {number} [settings.numPagesToRequest=1]            - Number of pages to auto-paginate (default: 1)
+ * Executes a Scan operation on DynamoDB to evaluate all items in a table or secondary index.
+ * Allows applying optional filters using `logicalElements`.
+ * NOTE: Scan operations are computationally expensive and should be used sparingly.
  *
- * @returns {Promise<object>} Object containing Items, Count, ScannedCount, and LastEvaluatedKey
+ * @param {Object} _izContext - The Izara context object containing the logger.
+ * @param {string} tableName - The name of the DynamoDB table to scan.
+ * @param {Object} [queryElements={}] - Optional query parameters for filtering, limiting, and projecting.
+ * @param {Object[]} [queryElements.logicalElements] - Filter conditions mapped to `FilterExpression`.
+ * @param {Object} [queryElements.additionalAttributes] - Additional attribute values required for the filter conditions.
+ * @param {string[]} [queryElements.projectionExpression] - Array of specific attribute names to return.
+ * @param {string} [queryElements.select] - Type of data to return (e.g., 'ALL_ATTRIBUTES', 'COUNT').
+ * @param {number} [queryElements.limit] - Maximum number of items to evaluate per page.
+ * @param {Object} [queryElements.exclusiveStartKey] - Pagination token (`LastEvaluatedKey`) to resume scanning.
+ * @param {string} [queryElements.indexName] - Name of a Global Secondary Index (GSI) to scan.
+ * @param {Object} [settings={}] - Additional operation settings.
+ * @param {number} [settings.numPagesToRequest=1] - Number of pages to auto-paginate before returning.
+ * @returns {Promise<Object>} A promise resolving to an object containing `Items`, `Count`, `ScannedCount`, and `LastEvaluatedKey`.
+ * @throws {NoRetryError|Error} If configuration is invalid or execution fails.
  */
 async function scan(_izContext, tableName, queryElements = {}, settings = {}) {
   try {
@@ -1008,14 +1104,14 @@ async function scan(_izContext, tableName, queryElements = {}, settings = {}) {
 }
 
 /**
- * Executes a Scan on DynamoDB and returns only Items
- * @param {object} _izContext                                - Izara context object
- * @param {string} tableName                                 - Name of the DynamoDB table
- * @param {object} [queryElements={}]                        - Optional query parameters
- * @param {object} [settings={}]                             - Operation settings
- * @param {number} [settings.numPagesToRequest=1]            - Number of pages to request
+ * Executes a Scan operation on DynamoDB and returns only the array of `Items`.
+ * Acts as a wrapper around the `scan` function for convenience when pagination metadata isn't needed.
  *
- * @returns {Promise<object[]>} Array of items from scan result
+ * @param {Object} _izContext - The Izara context object containing the logger.
+ * @param {string} tableName - The name of the DynamoDB table to scan.
+ * @param {Object} [queryElements={}] - Optional parameters for filtering and projection.
+ * @param {Object} [settings={}] - Operation settings, including auto-pagination rules.
+ * @returns {Promise<Object[]>} A promise resolving to an array of the retrieved item objects.
  */
 async function scanResults(
   _izContext,
@@ -1033,22 +1129,24 @@ async function scanResults(
 }
 
 /**
- * Executes a PutItem query on DynamoDB
- * @param {string} tableName
- * @param {object} attributes
- * @param {object} [queryElements={}]
- * @param {object} queryElements.additionalAttributes //attributes needed for the queery but not saved to the Item, eg used in conditional expressions
- * @param {object[]} queryElements.logicalElements
- * @param {string} queryElements.returnValues
- * @param {object} [settings={}]
- * @param {boolean} settings.errorOnConditionalExpNotPass=false] // if set then an error will be thrown, otherwise function returns with no error
- * @param {boolean} [settings.retryOnErrorConditionalExpNotPass=false]
- * @param {boolean} [settings.complexAttributes=false] // default FALSE
- * @param {boolean} [settings.returnQuery=false] // default FALSE
+ * Executes a PutItem operation on DynamoDB to create or replace an item.
+ * Supports basic and complex attribute formatting, string sets, and conditional expressions.
  *
- * @returns {} .. maybe nothing
+ * @param {Object} _izContext - The Izara context object containing the logger.
+ * @param {string} tableName - The name of the DynamoDB table.
+ * @param {Object|Array} attributes - The item attributes to store. If `settings.complexAttributes` is true, this must be an array of objects describing actions and values.
+ * @param {Object} [queryElements={}] - Additional query options (e.g., conditional expressions).
+ * @param {Object} [queryElements.additionalAttributes] - Attributes needed for the query but not saved to the Item (used in conditional expressions).
+ * @param {Object[]} [queryElements.logicalElements] - Array of logical elements mapped to `ConditionExpression`.
+ * @param {string} [queryElements.returnValues] - Values to return (e.g., 'NONE', 'ALL_OLD').
+ * @param {Object} [settings={}] - Additional behavior settings for the operation.
+ * @param {boolean} [settings.errorOnConditionalExpNotPass=false] - If true, throws an error when a conditional expression fails.
+ * @param {boolean} [settings.retryOnErrorConditionalExpNotPass=false] - If true and a condition fails, throws a retryable Error instead of NoRetryError.
+ * @param {boolean} [settings.complexAttributes=false] - If true, processes `attributes` as an array of complex directives (e.g., handles string sets automatically).
+ * @param {boolean} [settings.returnQuery=false] - If true, returns the payload immediately without sending it to DynamoDB.
+ * @returns {Promise<Object|void>} A promise resolving to the return values (if `ReturnValues` != 'NONE'), the payload (if `returnQuery` is true), or void.
+ * @throws {NoRetryError|Error} If attributes are invalid, a conditional expression fails, or a database error occurs.
  */
-
 async function putItem(
   _izContext,
   tableName,
@@ -1677,18 +1775,22 @@ async function updateItem(
 }
 
 /**
- * Executes a DeleteItem query on DynamoDB
- * @param {string} tableName
- * @param {object} keyValues
- * @param {[object]} queryElements
- * @param {object} [queryElements.additionalAttributes]
- * @param {object} [queryElements.logicalElements]
- * @param {object} [queryElements.returnValues]
- * @param {object} settings
- * @param {numeric} [settings.errorOnConditionalExpNotPass=false] // if set then an error will be thrown, otherwise function returns with no error
- * @param {numeric} [settings.retryOnErrorConditionalExpNotPass=false]
+ * Executes a DeleteItem operation on DynamoDB.
+ * Supports conditional deletions and returning the old item's attributes.
  *
- * @returns {} .. maybe nothing
+ * @param {Object} _izContext - The Izara context object containing the logger.
+ * @param {string} tableName - The name of the DynamoDB table.
+ * @param {Object} keyValues - The primary key (partition key and optional sort key) of the item to delete.
+ * @param {Object} [queryElements={}] - Additional query options (e.g., conditional expressions).
+ * @param {Object} [queryElements.additionalAttributes] - Attributes needed for the conditional expression but not saved to the Item.
+ * @param {Object[]} [queryElements.logicalElements] - Array of logical elements mapped to `ConditionExpression`.
+ * @param {string} [queryElements.returnValues] - Values to return (e.g., 'NONE', 'ALL_OLD').
+ * @param {Object} [settings={}] - Additional behavior settings.
+ * @param {boolean} [settings.errorOnConditionalExpNotPass=false] - If true, throws an error when a conditional expression fails.
+ * @param {boolean} [settings.retryOnErrorConditionalExpNotPass=false] - If true and a condition fails, throws a retryable Error instead of NoRetryError.
+ * @param {boolean} [settings.returnQuery=false] - If true, returns the payload immediately without sending it to DynamoDB.
+ * @returns {Promise<Object|void>} A promise resolving to the return values (if `ReturnValues` != 'NONE'), the payload (if `returnQuery` is true), or void.
+ * @throws {NoRetryError|Error} If a conditional expression fails, or a database error occurs.
  */
 async function deleteItem(
   _izContext,
@@ -1777,6 +1879,17 @@ async function deleteItem(
 
 // ----------- helper function -----------
 
+/**
+ * Helper function to generate logical elements and additional attributes for a ConditionExpression
+ * that checks if a string set exists and matches the old record's string set.
+ *
+ * @param {Object} _izContext - The Izara context object containing the logger.
+ * @param {Object} oldRecord - The existing DynamoDB item used to compare against.
+ * @param {string} stringSetAttName - The attribute name of the string set.
+ * @param {Object} [additionalAttributes={}] - Existing additional attributes object to append to.
+ * @param {Object[]} [logicalElements=[]] - Existing logical elements array to append to.
+ * @returns {[Object, Object[]]} An array containing the updated `additionalAttributes` and `logicalElements`.
+ */
 function QueryElementConditionalCheckStringSetEquals(
   _izContext,
   oldRecord, // filterMain
@@ -1838,7 +1951,15 @@ function QueryElementConditionalCheckStringSetEquals(
 } // end QueryElementConditionalCheckStringSetEquals
 
 //----  Helper fucntion -----
-// module.exports.generateExistLogicalElements = (keyValues) => {
+
+/**
+ * Helper function to generate an array of logical elements asserting that specified attributes
+ * either exist or do not exist in the DynamoDB table.
+ *
+ * @param {Object} attributes - An object containing the attribute keys to check.
+ * @param {boolean} [existed=false] - If true, asserts `attribute_exists`; otherwise asserts `attribute_not_exists`.
+ * @returns {Object[]} An array of logical elements combined with 'AND' operators.
+ */
 function generateNotExistLogicalElements(attributes, existed = false) {
   if (!existed) {
     existed = 'attribute_not_exists';
@@ -1864,6 +1985,14 @@ function generateNotExistLogicalElements(attributes, existed = false) {
   return logicalElements;
 }
 
+/**
+ * Helper function to refactor simple key-value attributes into an array of complex attribute directives
+ * (specifically enforcing the 'SET' action) for `updateItem` or `putItem`.
+ *
+ * @param {Object} attributes - A simple key-value map of attributes to update.
+ * @param {boolean} [forPutQuery=false] - If true, refrains from enforcing the `action: 'set'` property required by updates.
+ * @returns {Object[]} An array of attribute directive objects.
+ */
 function refractorAttributesToComplex(attributes, forPutQuery = false) {
   // only for SET update
   let returnAttributes = new Array();
@@ -2006,7 +2135,6 @@ async function transactWriteItems(_izContext, writeItems) {
 }
 
 // this.transactWriteItems()
-
 /* NOTE for batchWriteItems cannot perform multiple operations. you cannot put and delete the same item in the same BatchWriteItem request.
   Item  not exceed more than 25 requests in the batch, and not batch exceeds 400 KB.The total request size exceeds 16 MB
   action: PutItem | DeleteItem
@@ -2014,6 +2142,19 @@ async function transactWriteItems(_izContext, writeItems) {
   REF: https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#batchWriteItem-property
 */
 
+/**
+ * Executes a batch of delete operations on DynamoDB, automatically chunking requests
+ * into groups of 25 (the maximum allowed by AWS DynamoDB batchWriteItem).
+ *
+ * @param {Object} _izContext - The Izara context object containing the logger and tracing info.
+ * @param {string} tableName - The target DynamoDB table name.
+ * @param {Object[]} writeItems - An array of items to delete.
+ * @param {Object} keyFieldName - Configuration specifying the partition and sort key names.
+ * @param {string} keyFieldName.partitionKeyFieldName - The partition key property name in `writeItems`.
+ * @param {string} [keyFieldName.sortKeyFieldName] - The sort key property name in `writeItems`.
+ * @returns {Promise<void>} A promise that resolves when all batch operations complete successfully.
+ * @throws {Error|string} If the batch deletion process fails.
+ */
 async function batchDeleteItems(
   _izContext,
   tableName,
@@ -2073,9 +2214,44 @@ async function batchDeleteItems(
   _izContext.logger.info('----- finish all batchDeleteItems -----');
 }
 
-/*https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#batchWriteItem-property
-  NOTE: Cannot use complex settings inside PutRequest
-*/
+/**
+ * Executes a batch of put operations to DynamoDB, automatically chunking requests
+ * into groups of 25 (the maximum allowed by AWS DynamoDB batchWriteItem).
+ *
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#batchWriteItem-property
+ *
+ * @description
+ * **Note:** Cannot use complex settings inside PutRequest.
+ *
+ * After completing the DynamoDB query, this function collects capacity units via
+ * `captureCapacityUsed` and stores them in `_izContext.resourceUse`.
+ * Middleware will capture this and send it to the ResourceUse Service later.
+ *
+ * @param {Object} _izContext - The application context object, containing logger and resource tracking.
+ * @param {string} tableNameData - The target DynamoDB table name (or data used to resolve it).
+ * @param {Object[]} writeItems - An array of item objects to be written to the database.
+ * @param {Object} writeItems[].attributes - The core attributes/fields to insert into DynamoDB.
+ * @param {Object} [writeItems[].queryElements] - Optional query elements for validation or processing.
+ * @param {Object} [writeItems[].settings] - Optional item-specific settings (complex settings will be ignored).
+ * @param {Object} [settings] - Settings for the overall batchWriteItem command (e.g., ReturnConsumedCapacity).
+ *
+ * @throws {Error} Throws an error if the batch put process fails.
+ * @returns {Promise<void>} Resolves when all items are successfully written to DynamoDB.
+ *
+ * @example
+ * const items = [
+ *   {
+ *     attributes: {
+ *       configKey: 'configKey_1',
+ *       configTag: 'configTag_2',
+ *       configValue: 'configValue_3'
+ *     },
+ *     queryElements: {},
+ *     settings: {}
+ *   }
+ * ];
+ * await batchPutItems(_izContext, 'MyTable', items, { ReturnConsumedCapacity: 'TOTAL' });
+ */
 async function batchPutItems(
   _izContext,
   tableNameData,
@@ -2154,20 +2330,21 @@ async function batchPutItems(
       );
     } // end loop
   } catch (err) {
-    throw ('Error:baatchPutItems', err);
+    throw ('Error:batchPutItems', err);
   }
 }
 
 /**
+ * Captures and accumulates DynamoDB consumed capacity metrics after a query operation.
+ * The collected metrics are stored in `_izContext.resourceUse` for later reporting by middleware.
+ * Supports both single objects and arrays of capacity records (e.g., from `transactWrite`).
  *
- * @param {object} _izContext
- * @param {object | array} capacityUsed normally is object but when call transectionWrite will return array of object
- * @param {string} capacityStatus status of query , read | write
- * @param {string} queryOperation can be,  get | query | delete | put | transectionWrite
- *
- * Call this function when finish query dynamodb
- * This function will collect capacity units and store in _izContext.resourceUse
- * Middleware will capture resourceUse and send to ResourceUse Service later
+ * @param {Object} _izContext - The Izara context object containing the resource tracker (`resourceUse`).
+ * @param {Object|Object[]} capacityUsed - The `ConsumedCapacity` object or array of objects returned by DynamoDB.
+ * @param {string} capacityStatus - The category of the operation capacity ('read' or 'write').
+ * @param {string} queryOperation - The specific DynamoDB operation performed (e.g., 'get', 'query', 'delete', 'put', 'transactionWrite', 'scan').
+ * @returns {Promise<void>} Resolves when the capacity tracking completes.
+ * @throws {NoRetryError} If `capacityStatus` is not 'read' or 'write'.
  */
 async function captureCapacityUsed(
   _izContext,