easy-dynamodb

An easy-to-use wrapper around the AWS DynamoDB SDK

Usage no npm install needed!

<script type="module">
  import easyDynamodb from 'https://cdn.skypack.dev/easy-dynamodb';
</script>

README

easy-dynamodb

As its name implies, easy-dynamodb is a package meant to make working with DynamoDB easier and more productive - less time spent reading heavy API documentation, less lines of code, and less mistakes.

Table of Contents

  1. Features
  2. Getting Started
  3. Promises And Callbacks
  4. API Reference
  5. Tables
  6. Items
  7. Constants
  8. The Future
  9. Integration Tests
  10. Changelog

Features

Everything the AWS DynamoDB SDK can do, easy-dynamodb can do -- only more easily. Here are some of the key features that easy-dynamodb offers:

  • Both promises and callbacks -- you get to choose
  • Simplified API -- you should be spending much less time going through documentation to understand what needs to get passed into functions
  • Constants for many of the strings the AWS SDK uses
  • Simplified return values -- no more clunky conversions, just get your data
  • Transparent treatment of cases where multiple calls to DynamoDB must be made (e.g. when listTables returns a large number of tables)

For more information on the underlying SDK, please refer to the AWS DynamoDB SDK docs.

Getting Started

In order to use easy-dynamodb, you first need to add it as a dependency of your Node project

npm install --save easy-dynamodb

You are now ready to write some code!

var EasyDynamoDB = require('easy-dynamodb');

var easyDynamoDb = new EasyDynamoDB(/* Configuration */);
easyDynamoDb.createTable(/* Parameters */);

Promises and Callbacks

With easy-dynamodb, you can freely use promises or callbacks wherever makes the most sense to you. Every function supports both with no added effort on your part. Simply provide a callback if you would like to use one, otherwise the function will return a promise you can use to run your next instruction.

If you like promises:

easyDynamoDb.createTable(/* Parameters */)
.then(function (data) {
    console.log('We got data: ' + data);
})
.fail(function (err) {
    console.log('Uh oh: ' + err);
});

If you like callbacks:

easyDynamoDb.createTable(/* Parameters */, function (err, data) {
    if (err) {
        console.log('Uh oh: ' + err);
    } else {
        console.log('We got data: ' + data);
    }
});

API Reference

This document uses promises in its examples, but remember that you can use both promises and callbacks interchangeably.

Tables

changeProvisionedThroughput(tableName, readThroughput, writeThroughput [,callback])

Modifies the provisioned read/write throughput on a table.

easyDynamoDb.changeProvisionedThroughput('myTableName', 5, 6)
    .then(function() {
        console.log('Table throughput updated');
    });

__Returns__See AWS docs for information on return values.

createTable (parameters [,callback])

Creates a table in DynamoDB. See AWS docs for information on expected parameters and return values.

easyDynamoDb.createTable(/* Parameters */)
    .then(function(data) {
        console.log('Returned: ' + data);
    });

deleteTable (tableName [,callback])

Deletes a table from DynamoDB.

easyDynamoDb.deleteTable('myTableName')
    .then(function(data) {
        console.log('Returned: ' + data);
    });

Returns: See AWS docs for information on return values.

deleteGlobalSecondaryIndex (tableName, indexName [,callback]

Removes a global secondary index from a table.

easyDynamoDb.deleteGlobalSecondaryIndex('myTableName', 'myIndexName')
    .then(function () {
        console.log('Deleted global secondary index');
    });

__Returns__See AWS docs for information on return values.

describeTable (tableName [,callback])

Describe a table in DynamoDB.

easyDynamoDb.describeTable('myTableName')
    .then(function(data) {
        console.log('Returned: ' + data);
    });

Returns: See AWS docs for information on return values.

listTables ([callback])

List all tables in DynamoDB.

easyDynamoDb.listTables()
    .then(function(data) {
        console.log('Returned: ' + data);
    });

waitFor(tableName, state [,callback])

Waits for a table to be in the given state.

easyDynamoDb.waitFor('myTableName', EasyDynamoDB.WaitForStates.TABLE_EXISTS)
    .then(function() {
        console.log('Table is ready!')
    });

Items

Constants

Easy-dynamodb provides constants for many of the strings the AWS SDK uses to help you maintain cleaner code and better programming habits.

AttributeTypes

  • STRING
  • NUMBER
  • BINARY
easyDynamoDb.createTable(
{
    AttributeDefinitions:
    [
        {
            AttributeName: 'myHashKey',
            AttributeType: EasyDynamoDB.AttributeTypes.STRING
        },
        {
            AttributeName: 'myRangeKey',
            AttributeType: EasyDynamoDB.AttributeTypes.NUMBER
        }
    ]
    // Other parameters...
}

KeyTypes

  • HASH
  • RANGE
easyDynamoDb.createTable(
{
    KeySchema: 
    [
        {
             AttributeName: 'myHashKey',
             KeyType: EasyDynamoDB.KeyTypes.HASH
         },
         {
             AttributeName: 'myRangeKey',
             KeyType: EasyDynamoDB.KeyTypes.RANGE
         }
     ]
     // Other parameters...
}

ProjectionTypes

  • ALL
  • KEYS_ONLY
  • INCLUDE
easyDynamoDb.createTable({               
    GlobalSecondaryIndexes: [{                   
        Projection: {
            ProjectionType: EasyDynamoDB.ProjectionTypes.ALL
        }
    }]
    // Other parameters...
});

TableStatuses

  • ACTIVE
  • CREATING
  • UPDATING
  • DELETING
ReturnValues
  • NONE
  • ALL_OLD
  • UPDATED_OLD
  • ALL_NEW
  • UPDATED_NEW
easyDynamoDb.getItem(
{
    ReturnValues: EasyDynamoDB.ReturnValues.ALL_OLD
    // Other parameters...
});
WaitForStates
  • TABLE_EXISTS
  • TABLE_NOT_EXISTS
easyDynamoDb.waitFor(
    EasyDynamoDB.WaitForStates.TABLE_EXISTS,
    {
        TableName: 'myTable
    }
);

Integration Tests

If for some reason you would like to run the easy-dynamodb integration tests, check out the project and run npm install to get all the required dependencies. Then, create a file called automation.config under the test folder containing the configuration parameters you would normally pass to the EasyDynamoDB object. A basic example would be:

{
  "accessKeyId": "abc123",
  "secretAccessKey": "abc1234567890",
  "region": "us-west-2"
}

Then simply,

cd test/integration
mocha

Changelog

0.0.3 - Not Released Yet

Features:

  • PutItem, GetItem, UpdateItem and DeleteItem no longer return AttributeValues as part of their main response element ("Attributes"/"Item"). They now get un-marshalled back to a regular JS object
  • describeTable, waitFor and deleteTable have been simplified to use a table name string rather than an object
  • listTables now simply returns an array of table names, instead of an object
  • Split updateTable into more specific functions [WIP]
  • Adding some constants for AWS SDK strings

Misc:

  • PutItem, GetItem, UpdateItem and DeleteItem now produce errors if you call them without the bare minimum Key or Item object as part of your params
  • Major update to documentation. Hopefully not too heavy.

0.0.2 - July 25, 2015

Features:

  • PutItem, GetItem, UpdateItem and DeleteItem no longer require AttributeValues to be specified for their keys parameters. They now get marshalled to the correct format automatically.

Bug fixes:

  • Rename listTable to listTables and call correct underlying function
  • waitFor now calls correct underlying function
  • Fix context binding when calling underlying SDK to prevent "undefined is not a function" errors

0.0.1 - July 24, 2015

Initial release.

Features:

  • All DynamoDB functionality from the AWS SDK can be used with callbacks or with promises.