@izara_project/izara-core-library-dynamodb 1.0.14 → 1.0.16

package/README.md

@@ -1,15 +1,67 @@
 # izara-core-library-dynamodb
 
-# update version
-- commit code first
-npm version patch || npm version minor || npm version major
+A comprehensive DynamoDB utility library for the Izara project, providing simplified interfaces for common DynamoDB operations including scan, query, put, update, and delete operations.
 
-# can also push to repo ..
+## Installation
+
+```bash
+npm install @izara_project/izara-core-library-dynamodb
+```
+
+## Usage
+
+```javascript
+import dynamoDBSharedLib from '@izara_project/izara-core-library-dynamodb';
+```
+
+## Documentation
+
+Detailed documentation for each operation can be found in the `src/doc/` directory:
+
+- **[Scan Operation](doc/scan.md)** - Complete guide with 21 use cases for scanning DynamoDB tables
+
+## Available Operations
+
+- `scan` / `scanResults` - Scan entire table or index with filters
+- `query` / `queryResults` - Query items by partition key
+- `getItem` - Retrieve a single item by key
+- `putItem` - Create or replace an item
+- `updateItem` - Update existing item attributes
+- `deleteItem` - Delete an item
+- `batchPutItems` - Batch write items
+- `batchDeleteItems` - Batch delete items
+- `transactWriteItems` - Transactional writes
+
+---
+
+
+## Publishing
+
+### Update Version
+Commit code first:
+```bash
+git add .
+git commit -m "Your commit message"
+```
+
+Update version:
+```bash
+npm version patch   # Bug fixes
+npm version minor   # New features
+npm version major   # Breaking changes
+```
+
+### Push to Repository
+```bash
 git push
-# make sure commits look correct
+```
 
-# push to npm
+### Publish to NPM
+```bash
 npm publish
+```
 
-# update project that uses this package
+### Update in Projects
+```bash
 npm update @izara_project/izara-core-library-dynamodb
+```

package/doc/scan.md

@@ -0,0 +1,614 @@
+# Scan Operation
+
+The `scan` operation scans the entire table or a secondary index with optional filters. **Note: Scan operations are expensive and should be used sparingly.**
+
+## Function Signature
+
+```javascript
+async function scan(
+  _izContext,
+  tableName,
+  queryElements = {},
+  settings = {}
+)
+```
+
+## Parameters
+
+- `_izContext` - Izara context object for logging
+- `tableName` - Name of the DynamoDB table
+- `queryElements` - Optional query parameters:
+  - `logicalElements` - Filter conditions (uses FilterExpression)
+  - `additionalAttributes` - Additional attribute values for filters
+  - `projectionExpression` - Array of attribute names to return
+  - `select` - Return mode: `ALL_ATTRIBUTES | COUNT | SPECIFIC_ATTRIBUTES`
+  - `limit` - Maximum items per page
+  - `exclusiveStartKey` - Pagination start key
+  - `indexName` - Global secondary index name
+- `settings` - Operation settings:
+  - `numPagesToRequest` - Number of pages to auto-paginate (default: 1)
+
+## Use Cases
+
+### 1. Basic Scan - No Filters
+
+Scan all items in the table without any filters.
+
+```javascript
+const _izContext = { logger: console };
+const tableName = 'config';
+
+const queryElements = {};
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+console.log('All items:', result.Items);
+```
+
+### 2. Scan with Filter Condition (Equals)
+
+Filter items where `configValue` equals `'production'`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    envValue: 'production'
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'configValue',
+      rhsReference: 'envValue'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 3. Scan with Not Equals Filter
+
+Filter items where `status` is not equal to `'disabled'`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    disabledStatus: 'disabled'
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'notEquals',
+      lhsAttribute: 'status',
+      rhsReference: 'disabledStatus'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 4. Scan with Multiple Conditions (AND)
+
+Filter items where `environment` equals `'staging'` AND `priority` equals `'high'`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    envType: 'staging',
+    priorityLevel: 'high'
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'environment',
+      rhsReference: 'envType'
+    },
+    {
+      type: 'logicalOperator',
+      operator: 'and'
+    },
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'priority',
+      rhsReference: 'priorityLevel'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 5. Scan with OR Condition
+
+Filter items where `configKey` equals `'database'` OR `configKey` equals `'cache'`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    dbKey: 'database',
+    cacheKey: 'cache'
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'configKey',
+      rhsReference: 'dbKey'
+    },
+    {
+      type: 'logicalOperator',
+      operator: 'or'
+    },
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'configKey',
+      rhsReference: 'cacheKey'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 6. Scan with Greater Than Comparison
+
+Filter items where `version` is greater than `2`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    minVersion: 2
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'greaterThan',
+      lhsAttribute: 'version',
+      rhsReference: 'minVersion'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 7. Scan with Less Than Comparison
+
+Filter items where `retryCount` is less than `5`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    maxRetries: 5
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'lessThan',
+      lhsAttribute: 'retryCount',
+      rhsReference: 'maxRetries'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 8. Scan with Between Comparison
+
+Filter items where `timestamp` is between two values.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    startTime: 1640000000000,
+    endTime: 1650000000000
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'between',
+      lhsAttribute: 'timestamp',
+      betweenStartReference: 'startTime',
+      betweenEndReference: 'endTime'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 9. Scan with Function - attribute_exists
+
+Filter items where the `description` attribute exists.
+
+```javascript
+const queryElements = {
+  logicalElements: [
+    {
+      type: 'function',
+      function: 'attribute_exists',
+      attribute: 'description'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 10. Scan with Function - attribute_not_exists
+
+Filter items where the `deprecatedAt` attribute does not exist.
+
+```javascript
+const queryElements = {
+  logicalElements: [
+    {
+      type: 'function',
+      function: 'attribute_not_exists',
+      attribute: 'deprecatedAt'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 11. Scan with Function - begins_with
+
+Filter items where `configTag` begins with `'prod-'`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    tagPrefix: 'prod-'
+  },
+  logicalElements: [
+    {
+      type: 'function',
+      function: 'begins_with',
+      attribute: 'configTag',
+      substrReference: 'tagPrefix'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 12. Scan with Projection Expression
+
+Return only specific attributes: `configKey`, `configTag`, and `configValue`.
+
+```javascript
+const queryElements = {
+  projectionExpression: ['configKey', 'configTag', 'configValue']
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 13. Scan with Select - SPECIFIC_ATTRIBUTES
+
+Use projection with select mode for specific attributes.
+
+```javascript
+const queryElements = {
+  projectionExpression: ['configKey', 'configValue'],
+  select: 'SPECIFIC_ATTRIBUTES'
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 14. Scan with Select - COUNT
+
+Get count of items without returning the actual items.
+
+```javascript
+const queryElements = {
+  select: 'COUNT'
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+console.log('Total items:', result.Count);
+```
+
+### 15. Scan with Filter and Projection
+
+Filter items where `isActive` equals `true` and return only specific attributes.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    activeStatus: true
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'isActive',
+      rhsReference: 'activeStatus'
+    }
+  ],
+  projectionExpression: ['configKey', 'configTag', 'lastModified'],
+  select: 'SPECIFIC_ATTRIBUTES'
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 16. Scan with Limit
+
+Limit the number of items per page to 10.
+
+```javascript
+const queryElements = {
+  limit: 10
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 17. Scan with Pagination
+
+Request multiple pages of results (e.g., 3 pages).
+
+```javascript
+const queryElements = {
+  limit: 25
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 3 }
+);
+```
+
+### 18. Scan with Pagination Token (ExclusiveStartKey)
+
+Continue scanning from the last evaluated key.
+
+```javascript
+const queryElements = {
+  limit: 20,
+  exclusiveStartKey: {
+    configKey: 'lastConfigKey',
+    configTag: 'lastConfigTag'
+  }
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+// Use result.LastEvaluatedKey for next page
+```
+
+### 19. Scan with Global Secondary Index (GSI)
+
+Scan using a global secondary index.
+
+```javascript
+const queryElements = {
+  indexName: 'StatusIndex',
+  additionalAttributes: {
+    activeValue: 'active'
+  },
+  logicalElements: [
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'status',
+      rhsReference: 'activeValue'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 20. Scan with Complex Group Condition
+
+Filter using grouped conditions: `(environment = 'prod' OR environment = 'staging') AND status = 'enabled'`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    prodEnv: 'prod',
+    stagingEnv: 'staging',
+    enabledStatus: 'enabled'
+  },
+  logicalElements: [
+    {
+      type: 'group',
+      elements: [
+        {
+          type: 'logical',
+          comparison: 'equals',
+          lhsAttribute: 'environment',
+          rhsReference: 'prodEnv'
+        },
+        {
+          type: 'logicalOperator',
+          operator: 'or'
+        },
+        {
+          type: 'logical',
+          comparison: 'equals',
+          lhsAttribute: 'environment',
+          rhsReference: 'stagingEnv'
+        }
+      ]
+    },
+    {
+      type: 'logicalOperator',
+      operator: 'and'
+    },
+    {
+      type: 'logical',
+      comparison: 'equals',
+      lhsAttribute: 'status',
+      rhsReference: 'enabledStatus'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+### 21. Scan with Multiple Functions
+
+Filter items where `configKey` exists AND `configTag` begins with `'v2-'`.
+
+```javascript
+const queryElements = {
+  additionalAttributes: {
+    versionPrefix: 'v2-'
+  },
+  logicalElements: [
+    {
+      type: 'function',
+      function: 'attribute_exists',
+      attribute: 'configKey'
+    },
+    {
+      type: 'logicalOperator',
+      operator: 'and'
+    },
+    {
+      type: 'function',
+      function: 'begins_with',
+      attribute: 'configTag',
+      substrReference: 'versionPrefix'
+    }
+  ]
+};
+
+const result = await dynamoDBSharedLib.scan(
+  _izContext,
+  tableName,
+  queryElements,
+  { numPagesToRequest: 1 }
+);
+```
+
+## Return Value
+
+The `scan` function returns an object containing:
+- `Items` - Array of items returned from the scan
+- `Count` - Number of items in the response
+- `ScannedCount` - Number of items evaluated (before filter)
+- `LastEvaluatedKey` - Key to use for pagination (if more items exist)
+- `ConsumedCapacity` - Information about capacity consumed
+
+## Using scanResults
+
+For convenience, use `scanResults` to get only the Items array:
+
+```javascript
+const items = await dynamoDBSharedLib.scanResults(
+  _izContext,
+  tableName,
+  queryElements,
+  settings
+);
+// Returns only the Items array
+```

package/index.js

@@ -15,9 +15,9 @@ 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';
-
 // Re-export everything from DynamoDBSharedLib
 import dynamoDBSharedLib from './src/DynamoDBSharedLib.js';
 
-export default dynamoDBSharedLib;
+export default {
+  
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izara_project/izara-core-library-dynamodb",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Connecting with AWS DynamoDB Resource",
   "main": "index.js",
   "scripts": {
@@ -14,17 +14,41 @@
   "license": "AGPL-3.0-or-later",
   "homepage": "https://bitbucket.org/izara-core-libraries/izara-core-library-dynamodb/src/master/README.md",
   "devDependencies": {
-    "jest": "^30.2.0"
+    "jest": "^30.4.0"
   },
   "jest": {
     "testEnvironment": "node"
   },
   "type": "module",
-  "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.932.0",
-    "@aws-sdk/lib-dynamodb": "^3.932.0",
-    "@aws-sdk/util-dynamodb": "^3.932.0",
+  "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.clonedeep": "^4.5.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.clonedeep": {
+      "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.clonedeep": "^4.5.0"
   }
 }

package/src/DynamoDBSharedLib.js

@@ -15,8 +15,6 @@ 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';
-
 import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import { DynamoDB } from '@aws-sdk/client-dynamodb';
 import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
@@ -826,6 +824,214 @@ 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
+ */
+async function scan(_izContext, tableName, queryElements = {}, settings = {}) {
+  try {
+    // ------------ Build payload ---------------
+    let payload = {
+      TableName: tableName, // required
+      ReturnConsumedCapacity: 'TOTAL' // NONE(default) | TOTAL | INDEXES
+    };
+
+    // ---- FilterExpression : Add filter conditions using logicalElements ----
+    const [filterExpression, expressionAttributeValues] =
+      reformConditionExpression(_izContext, queryElements);
+    if (filterExpression) {
+      payload.FilterExpression = filterExpression;
+    }
+    console.log('filterExpression', filterExpression);
+    console.log('expressionAttributeValues', expressionAttributeValues);
+
+    if (expressionAttributeValues) {
+      payload.ExpressionAttributeValues = expressionAttributeValues;
+    }
+
+    // NOTE: we need to choose projectionExpression or select, not both (except SPECIFIC_ATTRIBUTES)
+    if (
+      queryElements.projectionExpression &&
+      queryElements.select &&
+      queryElements.select != 'SPECIFIC_ATTRIBUTES'
+    ) {
+      throw new NoRetryError(
+        'invalid setting, choose projectionExpression or select, or set projectionExpression with select is "SPECIFIC_ATTRIBUTES" '
+      );
+    }
+
+    // ---- projectionExpression : Return specific attributes ----
+    if (
+      queryElements.projectionExpression &&
+      Array.isArray(queryElements.projectionExpression) &&
+      queryElements.projectionExpression.length !== 0
+    ) {
+      payload.ProjectionExpression =
+        queryElements.projectionExpression.join(', ');
+    }
+
+    // ---- select : Return mode ----
+    if (queryElements.select) {
+      queryElements.select = queryElements.select.toUpperCase();
+      if (
+        queryElements.select == 'ALL_ATTRIBUTES' ||
+        queryElements.select == 'ALL_PROJECTED_ATTRIBUTES' ||
+        queryElements.select == 'COUNT' ||
+        queryElements.select == 'SPECIFIC_ATTRIBUTES'
+      ) {
+        payload.Select = queryElements.select;
+      } else {
+        throw new NoRetryError(
+          'select invalid, should be "ALL_ATTRIBUTES" | "ALL_PROJECTED_ATTRIBUTES" | "COUNT" | "SPECIFIC_ATTRIBUTES".'
+        );
+      }
+    }
+
+    // ---- exclusiveStartKey : Pagination ----
+    if (queryElements.exclusiveStartKey) {
+      payload.ExclusiveStartKey = queryElements.exclusiveStartKey;
+    }
+
+    // ---- indexName : Global secondary index (GSI) ----
+    if (queryElements.indexName) {
+      payload.IndexName = queryElements.indexName;
+    }
+
+    // ---- Limit : Items per page ----
+    if (queryElements.limit) {
+      if (typeof queryElements.limit !== 'number' || queryElements.limit < 1) {
+        throw new NoRetryError('limit incorrectly formatted');
+      }
+      payload.Limit = Math.floor(queryElements.limit);
+    }
+
+    _izContext.logger.debug('payload before scan', payload);
+
+    // ---- Execute scan with pagination handling ----
+    if (
+      !settings.hasOwnProperty('numPagesToRequest') ||
+      settings.numPagesToRequest == 1
+    ) {
+      // Single page scan
+      _izContext.logger.debug('CASE: numPagesToRequest = 1');
+
+      const returnValue = await dynamodb.scan(payload);
+      _izContext.logger.debug('scan status: ', returnValue['$metadata']);
+      await captureCapacityUsed(
+        _izContext,
+        returnValue.ConsumedCapacity,
+        'read',
+        'scan'
+      );
+      return returnValue; // return in DynamoDB syntax
+    } else {
+      // Multi-page scan
+      _izContext.logger.debug('CASE: numPagesToRequest > 1');
+
+      const getAllData = async payload => {
+        const _getAllData = async (payload, startKey) => {
+          if (startKey) {
+            payload.ExclusiveStartKey = startKey;
+          }
+          scanPage++;
+          let data = await dynamodb.scan(payload); // ---- main scan
+          _izContext.logger.debug('scan status: ', data['$metadata']);
+          await captureCapacityUsed(
+            _izContext,
+            data.ConsumedCapacity,
+            'read',
+            'scan'
+          );
+          return data;
+        };
+
+        // --- declare variables for scan
+        let lastEvaluatedKey = null;
+        let lastEvaluatedKeyReturnValue = null;
+        let rows = [];
+        let scanPage = 0;
+        let count = 0;
+        let scannedCount = 0;
+
+        do {
+          const result = await _getAllData(payload, lastEvaluatedKey);
+
+          // ---- handle response
+          count += result.Count;
+          scannedCount += result.ScannedCount;
+          lastEvaluatedKey = result.LastEvaluatedKey;
+          lastEvaluatedKeyReturnValue = result.LastEvaluatedKey;
+
+          if (result.hasOwnProperty('Items')) {
+            rows = rows.concat(result.Items);
+          }
+          if (scanPage >= settings.numPagesToRequest) {
+            lastEvaluatedKey = null; // exit loop
+          }
+
+          if (scanPage === 1000) {
+            throw new NoRetryError(
+              'too many paginated database results, 1000 limit reached, stopped execution in dynamodb.scan'
+            );
+          }
+        } while (lastEvaluatedKey);
+
+        return {
+          Items: rows,
+          Count: count,
+          ScannedCount: scannedCount,
+          LastEvaluatedKey: lastEvaluatedKeyReturnValue
+        };
+      };
+      return await getAllData(payload);
+    }
+  } catch (err) {
+    _izContext.logger.warn('warning', err);
+    throw new Error('Unhandled Error, scan: ', err);
+  }
+}
+
+/**
+ * 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
+ *
+ * @returns {Promise<object[]>} Array of items from scan result
+ */
+async function scanResults(
+  _izContext,
+  tableName,
+  queryElements = {},
+  settings = {}
+) {
+  const scanResults = await scan(
+    _izContext,
+    tableName,
+    queryElements,
+    settings
+  );
+  return scanResults.Items;
+}
+
 /**
  * Executes a PutItem query on DynamoDB
  * @param {string} tableName
@@ -2010,7 +2216,7 @@ async function captureCapacityUsed(
 }
 
 // Consolidated exports
-export default {
+export {
   // Table name functions
   tableName,
 
@@ -2025,6 +2231,8 @@ export default {
   getItem,
   query,
   queryResults,
+  scan,
+  scanResults,
   putItem,
   updateItem,
   deleteItem,