dynamodb-doc

DynamoDB Document SDK

This SDK abstracts away the typing of attribute values in the low level SDK in order to provide a simpler developing experience. JS datatypes like string or number can be passed directly into DynamoDB requests and the wrapping will be handled for you; similarly for responses, datatypes will be unwrapped.

For those DynamoDB types that do not have direct mappings to JS datatypes, a wrapper Object is provided to handle type ambiguities (i.e. StrSet, NumSet, BinSet).

Lastly, a Condition Object is being introduced to simplify the use of the KeyCondition and Expected portion of the request params. Note: Condition Object serves to simplify previous api (NOT new expressions)

Getting Started

In order to instantiate the client, you still need the AWS JS SDK to store your region/credentials.

var AWS = require("aws-sdk");
var DOC = require("dynamodb-doc");

AWS.config.update({region: "us-west-1"});

var docClient = new DOC.DynamoDB();

Alternatively if you already have the existing DynamoDB Client, you can pass it in order to instantiate the client.

// assumes AWS.config is set up already
var awsClient = AWS.DynamoDB();
var docClient = new DOC.DynamoDB(awsClient);

After this, you can make requests and receive responses with JS datatypes!

JS datatypes that can be used in place of DynamoDB Datatypes:

Javascript	DynamoDB
string	S
number	N
boolean	BOOL
null	NULL
array	L
object	M

For Sets, the client will provide object for you:

docClient.Set(["a", "b", "c"], "S")

Refer to the Basic Usage and Nested DataTypes and More sections down below to see examples of the updated API.

In addition, the SDK also introduces a special kind of Object in order to simplify conditions.

docClient.Condition(key, operator, val1, val2)

Refer to the section down below on Condition Objects to see an example of the usage.

NOTE: To build the node js files for the browser yourself, run

npm install; uglifyjs lib/* | sed 's/\"use strict\";//' > dynamodb-doc.min.js
# sed portion is optional depending on your use case

For each example assume we have these variables available to us.

// Basic Client creation
AWS.config.update({ /* ...your config... */ });
docClient = new DOC.DynamoDB();

// Basic Callback
var pfunc = function(err, data) { 
    if (err) {
        console.log(err, err.stack);
    } else {
        console.log(data);
    }
}

Basic Usage:

// Basic Scalar Datatypes
var params = {};
params.TableName = "Users";
params.Item = {UserId : "John",
               Age    : 21,
               Pic    : docClient.StrToBin("someURI")};

docClient.putItem(params, pfunc);

params = {};
params.TableName = "Users";
params.Key = {UserId : "John"}

docClient.getItem(params, pfunc); 

/* Response
{Item: {UserId : "John",
       Age     : 21,
       Pic     : Bin}} 
*/

NOTE: StrToBin returns either a Buffer for NodeJS or Uint8Array for the browser.

Nested DataTypes and More:

var params = {};
params.TableName = "Shopping Cart";

// Compatible is a Map of Part to List of PartId's
// OnSale is a BOOL type
// Discount is a NULL type
params.Item = {PartId       : "CPU1",
               OnSale       : false,
               Discount     : null,
               Compatible   : {Motherboards : ["MB1", "MB2"],
                               RAM          : ["RAM1"]}};

docClient.putItem(params, pfunc);

params = {};
params.Key = {PartId : "CPU1"};
params.TableName = "Shopping Cart";

docClient.getItem(params, pfunc);

/*Response
{Item: {PartId : "CPU1",
        OnSale : false,
        Discount : null,
        Compatible : {Motherboards : ["MB1", "MB2"],
                      RAM          : ["RAM1"]}}};
*/

Condition Object:

var params = {};
params.TableName = "Houses";

// Note: This is a query on the Key Schema of the table.  
// For queries on secondary indexes, specify params.IndexName = "index-name"

// use an array of Condition Objects for multiple conditions
params.KeyConditions = [docClient.Condition("HouseId", "NOT_NULL"),
                        docClient.Condition("YearBuilt", "GT", 2000)];

// use a Condition Object for just a single condition
params.QueryFilter = docClient.Condition("Price", "BETWEEN", 0, 900000);

docClient.query(params, pfunc);

/*Reponse
{Count: 3,
Items: [ { HouseId   : "123 amzn way",
           YearBuilt : 2001,
           Price     : 450000},
         { HouseId   : "321 dynamo st",
           YearBuilt : 2012,
           Price     : 100000},
         { HouseId   : "213 JS ave",
           YearBuilt : 2014,
           Price     : 1}],
ScannedCount: 3}
*/

Expressions (NEW!!):

var params = {};
params.TableName = "SomeTable";
params.Key = {Some : "Key"};
    
// Use the #(variable) to substitute in place of attribute Names
// Use the :(variable) to subsitute in place of attribute Values
params.UpdateExpression = "set #a = :x + :y";
params.ConditionExpression = "#a < :MAX and Price = :correct";
params.ExpressionAttributeNames = {"#a" : "Description"};
params.ExpressionAttributeValues = {":x" : 20,
                                    ":y" : 45,
                                    ":MAX" : 100,
                                    ":correct" : "is right!!"};

docClient.updateItem(params, pfunc);