modli/dynamodb repository overview

⁠Modli - DynamoDB Adapter

This module provides adapter for the DynamoDB⁠ datasource for integration with Modli⁠.

⁠Installation

npm install modli-dynamodb --save

⁠Working Locally

IMPORTANT: For testing (with linked services) to run correctly you must have docker⁠ and DevLab npm install devlab -g installed.

⁠Usage

Configure your adapter and model

import { model, adapter, use } from 'modli';
import dynamodb from 'modli-dynamodb';

// Set your configuration
let dynamoConfig = {
  region: 'us-east-1',                // Your specific AWS Region
  endpoint: 'http://localhost:8000',  // Optional value to specify an end point
  accessKeyId: process.env.AWS_ACCESS_KEY_ID || '123456789',
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '123456789'
};

Add an instance of the model where the autoCreate flag is used to determine if helpers.checkCreateTable() should automatically create the table from the model.

Use indexes to define a hash key, range key or global secondary indexes as desired.

The optional index key projectionType can specify a projection type of 'ALL', 'KEYS_ONLY' or 'INCLUDE'. Please note that the use of 'INCLUDE' also requires the index key nonKeyAttributes as an array of keys to include in the projection.

Both projectionType and nonKeyAttributes are optional values and the projection type will default to 'ALL' in their absence.

model.add({
  name: 'roles',
  version: 1,
  autoCreate: true,
  indexes: [
    { keytype: 'hash', value: 'id', type: 'N'},
    { keytype: 'secondary', value: 'login', type: 'S', projectionType: 'INCLUDE', nonKeyAttributes: ['age']}
  ],
  schema: {
    id: { type: 'string' },
    name: { type: 'string' },
    age: { type: 'number' }
  }
});

Add the adapter with the previously defined config object structure:

adapter.add({
  name: 'dynamoAdapter',
  source: dynamodb,
  config: dynamoConfig
});

You can now use the adapter with the model with:

const testDynamo = use('roles', 'dynamoAdapter');

⁠Methods

⁠list

Gets a list of all active tables

testDynamo.list()
  .then(/*...*/)
  .catch(/*...*/);

⁠scan

Perform a full unfiltered scan of a table with an optional dynamo scan-level filter that doesn't rely on secondary indexes. Optional filters are constructed in a way that correlates to dynamo filter conditionals. In addition, optionally pass a limit and lastKey, which could be used to support pagination.

testDynamo.scan()
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.scan({email: {eq: '[email protected]'}})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.scan({accounts: {contains: 'someuser'}})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.scan({firstName: { in: ['Ben', 'Tom']}})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.scan({age: { between: [18, 26]}})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.scan({accounts: {contains: 'someuser'}, email: {eq: '[email protected]'}})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.scan(undefined, {limit: 10})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.scan({age: { between: [18, 26]}}, {limit: 25, lastKey: 'somekey'})
  .then(/*...*/)
  .catch(/*...*/);

⁠createTable

Pass through method that uses explicit dynamo creation params to create a table

testDynamo.createTable(dynamoParams)
  .then(/*...*/)
  .catch(/*...*/);

⁠createTableFromModel

Performs a deterministic create based on the specified schema. Will construct the creation query without additional input.

testDynamo.createTableFromModel()
  .then(/*...*/)
  .catch(/*...*/);

⁠deleteTable

Deletes a table by specified object containing hash / value pair

testDynamo.deleteTable({TableName: 'myTable'})
  .then(/*...*/)
  .catch(/*...*/);

⁠create

Creates a new entry in the table specified in the schema

testDynamo.create({HASH:Value, SomeIndex: OtherValue})
  .then(/*...*/)
  .catch(/*...*/);

⁠read

Performs a deterministic read on a table by hash / value pair OR secondary index / value pair

testDynamo.read({HASH: SomeValue})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.read({SOMEINDEX: SomeOtherValue})
  .then(/*...*/)
  .catch(/*...*/);

⁠readPaginate

Performs a read on a table expecting a global secondary index that accepts a limit and lastKey, which could be used to support pagination.

testDynamo.readPaginate({SOMEINDEX: SomeValue}, {limit: 10})
  .then(/*...*/)
  .catch(/*...*/);

testDynamo.readPaginate({SOMEINDEX: SomeValue}, {limit: 25, lastKey: 'SomeKey'})
  .then(/*...*/)
  .catch(/*...*/);

⁠getItemByHash

Performs a read on a table expecting a HASH / Value pair

testDynamo.getItemByHash({SOMEHASH: SomeValue})
  .then(/*...*/)
  .catch(/*...*/);

⁠getItemById

Performs a read on a table expecting a global secondary index

testDynamo.getItemById({SOMEINDEX: SomeValue})
  .then(/*...*/)
  .catch(/*...*/);

⁠getItemsInArray

Calls batchGetItem using a Hash identifier

testDynamo.getItemsInArray('HASHNAME', [1,2,3,4])
  .then(/*...*/)
  .catch(/*...*/);

⁠update

Updates a row in the table by HASH / Value pair and JSON Object specifying new values

testDynamo.update({HASH: 'SomeValue'}, { /* update object */ })
  .then(/*...*/)
  .catch(/*...*/);

⁠patch

Partial updates a row in the table by HASH / Value pair and JSON Object specifying new values

testDynamo.patch({HASH: 'SomeValue'}, { /* partial update object */ })
  .then(/*...*/)
  .catch(/*...*/);

⁠delete

Deletes a row from the table by HASH / Value pair

testDynamo.delete({HASH: 'SomeValue'})
  .then(/*...*/)
  .catch(/*...*/);

⁠extend

Extends the adapter to allow custom methods

testDynamo.extend('methodName', () => {
  /*...*/
})

⁠DevLab and Scripts

The system utilizes DevLab for running tasks in containers. The below tasks will be executed in containers via lab {task-name}:

• clean will remove the /node_modules, /build and /coverage directories
• install will install dependencies
• lint will lint all files in /src and /test
• build will transpile ES2015 code in /src to /build
• mocha will run all spec files in /test/src recursively
• test will run both lint and cover
• cover will run code coverage on all tests in /test/src recursively

⁠Testing

Running lab mocha will run the tests.

⁠License

Modli-DynamoDB is licensed under the MIT license. Please see LICENSE.txt for full details.

⁠Credits

Modli-DynamoDB was designed and created at TechnologyAdvice⁠.