modli-dynamodb

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 Binci npm install binci -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' }
  }
});

Or you can add a composite key global secondary index like so:

model.add({
  name: 'logs',
  version: 1,
  autoCreate: true,
  indexes: [
    { keytype: 'hash', value: 'id', type: 'N' },
    { keytype: 'range', value: 'createdAt', type: 'S' },
    { keytype: 'secondary', values: [
      { keytype: 'hash', value: 'login', type: 'S' },
      { keytype: 'range', value: 'createdAt', type: 'S' }
      ] }
  ],
  schema: {
    id: { type: 'number' },
    login: { type: 'string' },
    createdAt: { type: 'string' }
  }
});

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: '[e-mail]'}})
  .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: '[e-mail]'}})
  .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', () => {
  /*...*/
})

Binci and Scripts

The system utilizes Binci for running tasks in containers. The below tasks will be executed in containers via binci {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 binci 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.