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.
- Features
- Getting Started
- Promises And Callbacks
- API Reference
- Tables
- Items
- Constants
- The Future
- Integration Tests
- Changelog
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.
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 */);
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);
}
});
This document uses promises in its examples, but remember that you can use both promises and callbacks interchangeably.
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.
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);
});
Deletes a table from DynamoDB.
easyDynamoDb.deleteTable('myTableName')
.then(function(data) {
console.log('Returned: ' + data);
});
Returns: See AWS docs for information on return values.
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.
Describe a table in DynamoDB.
easyDynamoDb.describeTable('myTableName')
.then(function(data) {
console.log('Returned: ' + data);
});
Returns: See AWS docs for information on return values.
List all tables in DynamoDB.
easyDynamoDb.listTables()
.then(function(data) {
console.log('Returned: ' + data);
});
Waits for a table to be in the given state.
easyDynamoDb.waitFor('myTableName', EasyDynamoDB.WaitForStates.TABLE_EXISTS)
.then(function() {
console.log('Table is ready!')
});
Easy-dynamodb provides constants for many of the strings the AWS SDK uses to help you maintain cleaner code and better programming habits.
- STRING
- NUMBER
- BINARY
easyDynamoDb.createTable(
{
AttributeDefinitions:
[
{
AttributeName: 'myHashKey',
AttributeType: EasyDynamoDB.AttributeTypes.STRING
},
{
AttributeName: 'myRangeKey',
AttributeType: EasyDynamoDB.AttributeTypes.NUMBER
}
]
// Other parameters...
}
- HASH
- RANGE
easyDynamoDb.createTable(
{
KeySchema:
[
{
AttributeName: 'myHashKey',
KeyType: EasyDynamoDB.KeyTypes.HASH
},
{
AttributeName: 'myRangeKey',
KeyType: EasyDynamoDB.KeyTypes.RANGE
}
]
// Other parameters...
}
- ALL
- KEYS_ONLY
- INCLUDE
easyDynamoDb.createTable({
GlobalSecondaryIndexes: [{
Projection: {
ProjectionType: EasyDynamoDB.ProjectionTypes.ALL
}
}]
// Other parameters...
});
- ACTIVE
- CREATING
- UPDATING
- DELETING
- NONE
- ALL_OLD
- UPDATED_OLD
- ALL_NEW
- UPDATED_NEW
easyDynamoDb.getItem(
{
ReturnValues: EasyDynamoDB.ReturnValues.ALL_OLD
// Other parameters...
});
- TABLE_EXISTS
- TABLE_NOT_EXISTS
easyDynamoDb.waitFor(
EasyDynamoDB.WaitForStates.TABLE_EXISTS,
{
TableName: 'myTable
}
);
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
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 object -
describeTable
,waitFor
anddeleteTable
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.
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
Initial release.
Features:
- All DynamoDB functionality from the AWS SDK can be used with callbacks or with promises.