@izara_project/izara-core-library-dynamodb 1.0.13 → 1.0.15

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izara_project/izara-core-library-dynamodb",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Connecting with AWS DynamoDB Resource",
   "main": "index.js",
   "scripts": {