dynamaestro

v0.9.1

Published

4 years ago

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.

0High
0Medium
0Low

doostin

dynamodb dynamo aws

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

Tables

Utilities

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);
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

DynaMaestro

Installation

Documentation

Setup

Items

Tables

Utilities

Setup

Config

Items

putItem()

batchWriteItems()

getItem()

batchGetItems()

query()

scan()

updateItem()

deleteItem()

Tables

createTable()

listTables(callback)

describeTable(tableName, callback)

deleteTable(tableName, callback)

Utilities

whenTableExists(tableName, callback)

whenTableDoesntExist(tableName, callback)