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
- Features
- Getting Started
- Promises And Callbacks
- API Reference
- Tables
- Items
- Constants
- The Future
- Integration Tests
- 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
andDeleteItem
no longer return AttributeValues as part of their main response element ("Attributes"/"Item"). They now get un-marshalled back to a regular JS objectdescribeTable
,waitFor
anddeleteTable
have been simplified to use a table name string rather than an objectlistTables
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
tolistTables
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.