DynaMaestro

DynaMaestro was developed to provide an easier way to access a DynamoDB. A lot of the functions use chaining methods to hide away the AWS specific ideology.

Installation

npm install dynamaestro

Documentation

Setup

• config

Items

• putItem
• batchWriteItems
• getItem
• batchGetItems
• query
• scan
• updateItem
• deleteItem

Tables

• createTable
• listTables
• describeTable
• deleteTable

Utilities

• whenTableExists
• whenTableDoesntExist

Setup

Config

Connnects to the database with supplied credentials and region.

Arguments

• credentials - an object with AWS credentials
• region - the region string you would like to use

Example

var dynamaestro = require("dynamaestro");
 
var config = {
    credentials: {
        "accessKeyId" : "XXXXXXXXXXXXXXXXX",
        "secretAccessKey" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    region : "us-west-1"
};
 
var ddb = new dynamaestro(config);

---

Items

putItem()

putItem() is a chained function with table(), item(), and execute() chains. putItem() is used to create a single item from an object. This function will handle all of the types currently(as of January 2015) available for AWS.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to scan
• item(item)
  • item - the item object you would like to place on the table
• allowOverwrite()
  • by default, putItem will not overwrite an item as it is better to update, but this override will allow you to use putItem like update.
• execute(callback)
  • callback - returned function with error and response

Example

 
var now = new Date();
 
var testItem = {
    user : "username",
    created : now.getTime(),
    item_id : uuid.v4()
};
 
ddb.putItem()
    .table("testing3")
    .item(testItem)
    .execute(function(error, response) {
        ////handle(error, response);
    });

---

batchWriteItems()

batchWriteItems() is a chained function with table(), put(), del(), where(), and execute(). batchWriteItems() is used to create and delete multiple items in one call.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to get an item from.
• put(item)
  • item - the item object that you would like to put on the table.
• del()
  • No arguments, must be followed by one .where(...) for HASH, and another .where(...) for a HASH AND RANGE.
• where(key, value, nextHash)
  • key - the key you would like to get
  • value - the value of that key
  • nextHash - (true | false) Lets the function know to move on to another HASH or HASH/RANGE set.
• execute(callback)
  • callback - function with error and response

Example

var now = new Date();
 
var testItem = {
    user: "username",
    item_id: "1234-b34c-998e",
    created: now.getTime()
};
 
ddb.batchWriteItems()
    .table("tableOne")
    .delete()
    .where("user", "bob")
    .where("item_id", "e313659e-c8ce-4e0c-8fc7-bf01fe514c05")
    .delete()
    .where("user", "boudrd", true)
    .where("item_id", "1fe8a751-7324-4642-8df9-d3a8a4595639")
    .put(testItem)
    .table("tableTwo")
    .put(testItem)
    .execute(function(error, response) {
        //handle(error, response);
    });

---

getItem()

getItem() is a chained function with table(), where(), select(), and execute() chains. getItem() is used get a specific item based off a HASH key, and optionally a RANGE key.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to get an item from.
• where(key, value)
  • key - the key you would like to get query by
  • value - the value of that key
• select(atrributes)
  • attributes - Optional: array of attributes you would like returned
• execute(callback)
  • callback - function with error and response

Examples

by HASH & RANGE:

ddb.getItem()
    .table("testing2")
    .where("user", "boudrd")
    .where("item_id", "592c7ec9-4835-4c88-9b5f-c09fe11ebf97")
    .execute(function(error, response) {
        //handle(error, response);
    });

by HASH only:

ddb.getItem()
    .table("testing2")
    .where("item_id", "592c7ec9-4835-4c88-9b5f-c09fe11ebf97")
    .execute(function(error, response) {
        //handle(error, response);
    });

---

batchGetItems()

batchGetItems() is a chained function with table(), where(), select(), and execute() chains. getItem() is used get a specific item based off a HASH key, and optionally a RANGE key.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to scan
• where(key, value, nextHash)
  • key - the key you would like to get query by
  • value - the value of that key
  • nextHash - (true | false) Lets the function know to move on to another HASH or HASH/RANGE set.
• select(atrributes)
  • attributes - Optional: array of attributes you would like returned
• execute(callback)
  • callback - function with error and response

Example

ddb.batchGetItems()
    .table("table1")
    .where("user", "username")
    .where("item_id", "018654bf-2a10-4b08-918c-f21b0ca3c204")
    .where("user", "username", true)
    .where("item_id", "23bb7b66-1801-4164-83c0-2a8259261905")
    .select(["user", "item_id"])
    .table("table2")
    .where("user", "username")
    .where("item_id", "1211f8fe-2567-44b6-83f0-f82650376a89")
    .execute(function(error, response) {
        //handle(error, response);
    });

---

query()

query() is a chained function with table(), globalIndex(), where(), select(), and execute() chains. query() is used get a group of items based off a HASH key. You can also specify a global index to query off a different index.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to scan
• globalIndex(indexName)
  • indexName - optional: name of the global index you would like to query
• where(key, operator, value)
  • key - the key you would like to get query by
  • operator - the comparison operator that you would like to compare the key and value.
    • Available Operators: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH
    • Note: not all attributes available all the time
  • value - the value of that key
• select(atrributes)
  • attributes - optional: array of attributes you would like returned
• execute(callback)
  • callback - function with error and response

Examples

Standard query off HASH:

ddb.query()
    .table("testing3")
    .where("user", "EQ", "username")
    .execute(function(error, response) {
        //handle(error, response);
    });

Global Index query:

ddb.query()
    .table("testing3")
    .globalIndex("indexName")
    .where("user", "EQ", "username")
    .where("created", "BETWEEN", ["1422048000000","1422049000000"])
    .execute(function(error, response) {
        //handle(error, response);
    });

---

scan()

Scan is a chained function with table(), select(), and execute() chains. Scan is used get the items of an entire database. Better to avoid using scan wherever possible, and to use query instead.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to scan
• select(atrributes)
  • attributes - Optional: array of attributes you would like returned
• execute(callback)
  • callback - function with error and response

Example

ddb.scan()
    .table("testing2")
    .select(["user","item_id"])
    .execute(function(error, response) {
        //handle(error, response);
    });

---

updateItem()

updateItem() is a chained function with table(), where(), put(), increment(), delete(), and execute() chains. updateItem() is used to update a specific item. You can put new keys, put existing keys, increment numbers and delete existing keys.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to scan
• where(key, value)
  • key - the key you would like to get query by
  • value - the value of that key
• put(key, value)
  • key - the key you would like to update
  • value - the value of that key
• increment(key, value)
  • key - the key you would like to increment
  • value - the value that you would like to increment key by
• delete(key)
  • key - the key you would like to delete
• execute(callback)
  • callback - function with error and response

Examples

by HASH only:

ddb.updateItem()
    .table("testing3")
    .where("id", "someId")
    .put("updated", now.getTime())
    .put("good", "stuff")
    .increment("numberOfThings", 50)
    .delete("someKey")
    .execute(function(error, response) {
        //handle(error, response);
    });

by HASH & RANGE:

ddb.updateItem()
    .table("testing3")
    .where("user", "username")
    .where("item_id", "uniqueID")
    .put("updated", now.getTime())
    .put("good", "stuff")
    .increment("numberOfThings", 50)
    .delete("someKey")
    .execute(function(error, response) {
        //handle(error, response);
    });

---

deleteItem()

deleteItem() is a chained function with table(), where(), and execute(). deleteItem() is used to delete a specific item.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to scan
• where(key, value)
  • key - the key you would like to delete an item in
  • value - the value of that key
• execute(callback)
  • callback - function with error and response

Examples

by HASH only:

ddb.deleteItem()
    .table("testing3")
    .where("id", "someId")
    .execute(function(error, response) {
        //handle(error, response);
    });

by HASH & RANGE:

ddb.deleteItem()
    .table("testing3")
    .where("user", "username")
    .where("item_id", "9d3063b8-2822-4bc7-a3ca-9af2ba8f1032")
    .execute(function(error, response) {
        //handle(error, response);
    });

---

Tables

createTable()

createTable() is a chained function with table(), key(), provision(), and execute(). createTable() is used to programatically create a table.

Chained Methods

• table(tableName)
  • tableName - the name of the table that you'd like to create
• key(type, value, keyType, indexType, indexName)
  • type - (string | number)
  • value - name of the key
  • keyType - (hash | range) Hash keys are mandatory, Range keys are optional.
  • indexType - optional: (global | local)
  • indexName - optional: Name of global or local index
• provision(readCapacity, writeCapacity, indexType, indexName)
  • readCapacity - Provisioned throughput capacity you want to reserve for reads.
  • writeCapacity - Provisioned throughput capacity you want to reserve for writes.
  • indexType - optional: (global | local)
  • indexName - optional: Name of global or local index
• execute(callback)
  • callback - function returned with error and response

Example

ddb.createTable()
    .table("tableName")
    .key("string", "user", "hash")
    .key("string", "itemId", "range")
    .provision(5,5)
    .key("string", "user", "hash", "global", "byUserByDate")
    .key("string", "created", "range", "global", "byUserByDate")
    .provision(10, 10, "global", "byUserByDate")
    .key("string", "user", "hash", "local", "byUserByCount")
    .key("string", "count", "range", "local", "byUserByCount")
    .provision(5, 5)
    .execute(function(error, response) {
        //handle(error, response);
    });

---

listTables(callback)

listTables() will return an array of table names.

Arguments

• callback - returned function with error and response

Example

ddb.listTables(function(error, response) {
    //handle(error, response);
});

---

describeTable(tableName, callback)

describeTable() is used to gather data about a table. Great for helping to determine IF a table exists. If you need to create a table, you can check to see if the table exists before you create it.

Arguments

• tableName - name of the table you want more information about
• callback - returned function with error and response

Example

ddb.describeTable("testing3", function(error, response) {
    if(error && error.code === "ResourceNotFoundException") {
        // table doesn't exist
    } else {
        // table does exist
    }
});

---

deleteTable(tableName, callback)

deleteTable() is used to delete a table.

Arguments

• tableName - name of the table you would like to delete
• callback - returned function with error and response

Example

ddb.deleteTable("tableName", function(error, response) {
    //handle(error, response);
});

Utilities

whenTableExists(tableName, callback)

whenTableExists() is used to determine when (NOT IF) a table exists. This is useful to wait to do something to a table that you've just created. The function polls your database 20 times, checking every 25 seconds to see if the table exists yet.

Arguments

• tableName - name of the table you are waiting for to exist
• callback - returned function with error and response

Example

ddb.whenTableExists("testing3", function(error, response) {
    //handle(error, response);
});

---

whenTableDoesntExist(tableName, callback)

whenTableDoesntExist() is used to determine when (NOT IF) a table no longer exists. This is useful to wait to do something to a table that you've just deleted. The function polls your database 20 times, checking every 25 seconds to see if the table still exists.

Arguments

• tableName - name of the table you are waiting for to not exist
• callback - returned function with error and response

Example

ddb.whenTableDoesntExist("testing3", function(error, response) {
    //handle(error, response);
});

---