altdynamo

A helper module to handle AWS.DynamoDB.DocumentClient.

Install

Install with npm:

$ npm install --save altdynamo

Usage

Put item to table

const {ParamsBuilder,DocClient} = require('altdynamo');
const aws = require('aws-sdk');
const doc = new aws.DynamoDB.DocumentClient({
    accessKeyId: 'my-key',
    secretAccessKey: 'my-secret',
    region: 'my-region',
    apiVersion: '2012-08-10'
});


// #1. use when creating only params with ParamsBuilder
const pb = new ParamsBuilder();
const params = pb.table('test')
    .item({
        testKey: 'foo',
        itemType: 'bar',
        created: Date.now()
    }).params;
    
doc.put(params).promise()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });


// #2. use when executing together with DocClient
const docClient = new DocClient(doc);
docClient.table('test')
    .item({
        testKey: 'foo',
        itemType: 'bar',
        created: Date.now()
    })
    .executePut()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });

Get item from table

const {ParamsBuilder,DocClient} = require('altdynamo');
const aws = require('aws-sdk');
const doc = new aws.DynamoDB.DocumentClient({
    accessKeyId: 'my-key',
    secretAccessKey: 'my-secret',
    region: 'my-region',
    apiVersion: '2012-08-10'
});


// #1. use when creating only params with ParamsBuilder
const pb = new ParamsBuilder();
const params = pb.table('test')
    .key({
        testKey: 'foo',
        itemType: 'bar'
    }).params;
    
doc.get(params).promise()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });


// #2. use when executing together with DocClient
const docClient = new DocClient(doc);
docClient.table('test')
    .key({
        testKey: 'foo',
        itemType: 'bar'
    })
    .executeGet()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });

Update item to table

const {ParamsBuilder,DocClient} = require('altdynamo');
const aws = require('aws-sdk');
const doc = new aws.DynamoDB.DocumentClient({
    accessKeyId: 'my-key',
    secretAccessKey: 'my-secret',
    region: 'my-region',
    apiVersion: '2012-08-10'
});


// #1. use when creating only params with ParamsBuilder
const pb = new ParamsBuilder();
const params = pb.table('test')
    .key({
        testKey: 'foo',
        itemType: 'bar'
    })
    .update({
        updated: Date.now()
    }).params;
    
doc.update(params).promise()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });


// #2. use when executing together with DocClient
const docClient = new DocClient(doc);
docClient.table('test')
    .key({
        testKey: 'foo',
        itemType: 'bar'
    })
    .update({
        updated: Date.now()
    })
    .executeUpdate()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });

Query items from table

const {ParamsBuilder,DocClient} = require('altdynamo');
const aws = require('aws-sdk');
const doc = new aws.DynamoDB.DocumentClient({
    accessKeyId: 'my-key',
    secretAccessKey: 'my-secret',
    region: 'my-region',
    apiVersion: '2012-08-10'
});


// #1. use when creating only params with ParamsBuilder
const pb = new ParamsBuilder();
const params = pb.table('test')
    .eq('testKey','foo')
    .toKeyCondition().params;
    
doc.query(params).promise()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });


// #2. use when executing together with DocClient
const docClient = new DocClient(doc);
docClient.table('test')
    .eq('testKey','foo')
    .toKeyCondition()
    .executeQuery()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });

Delete item to table

const {ParamsBuilder,DocClient} = require('altdynamo');
const aws = require('aws-sdk');
const doc = new aws.DynamoDB.DocumentClient({
    accessKeyId: 'my-key',
    secretAccessKey: 'my-secret',
    region: 'my-region',
    apiVersion: '2012-08-10'
});


// #1. use when creating only params with ParamsBuilder
const pb = new ParamsBuilder();
const params = pb.table('test')
    .key({
        testKey: 'foo',
        itemType: 'bar'
    }).params;
    
doc.delete(params).promise()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });


// #2. use when executing together with DocClient
const docClient = new DocClient(doc);
docClient.table('test')
    .key({
        testKey: 'foo',
        itemType: 'bar'
    })
    .executeDelete()
    .then(data=>{
        console.log(data);
    })
    .catch(err=> {
        console.log(err);
    });

API Reference

class ParamsBuilder

constructor() ⇒ ParamsBuilder
to initiate an instance of the ParamsBuilder.

clear() ⇒ ParamsBuilder
to initialize all values of .params except .params.TableName.

table(name) ⇒ ParamsBuilder
to set .params.TableName by the name argument.

addExpressionToken(txt) ⇒ ParamsBuilder
to add txt argument to .expressionTokens[]. (It is forbidden to use reserved words or direct values in the Expression of DocumentClient. Therefore, it is recommended to add tokens through other methods that automatically convert name and value to ExpressionAttributeName and ExpressionAttributeValue rather than adding the token directly to this method.)

toCondition() ⇒ ParamsBuilder
to set .params.ConditionExpression by joining all tokens of .expressionTokens[]. and all tokens of .expressionTokens[] are cleared.

toKeyCondition() ⇒ ParamsBuilder
to set .params.KeyConditionExpression by joining all tokens of .expressionTokens[]. and all tokens of .expressionTokens[] are cleared.

toFilter() ⇒ ParamsBuilder
to set .params.FilterExpression by joining all tokens of .expressionTokens[]. and all tokens of .expressionTokens[] are cleared.

and() ⇒ ParamsBuilder
to add 'AND' token to .expressionTokens[].

or() ⇒ ParamsBuilder
to add 'OR' token to .expressionTokens[].

not() ⇒ ParamsBuilder
to add 'NOT' token to .expressionTokens[].

open() ⇒ ParamsBuilder
to add '(' token to .expressionTokens[].

close() ⇒ ParamsBuilder
to add ')' token to .expressionTokens[].

eq(name,value) ⇒ ParamsBuilder
to add ':name = #value' token to .expressionTokens[].

ne(name,value) ⇒ ParamsBuilder
to add ':name <> #value' token to .expressionTokens[].

lt(name,value) ⇒ ParamsBuilder
to add ':name < #value' token to .expressionTokens[].

le(name,value) ⇒ ParamsBuilder
to add ':name <= #value' token to .expressionTokens[].

gt(name,value) ⇒ ParamsBuilder
to add ':name > #value' token to .expressionTokens[].

ge(name,value) ⇒ ParamsBuilder
to add ':name >= #value' token to .expressionTokens[].

begins(name,value) ⇒ ParamsBuilder
to add 'BEGINS_WITH (:name, #value)' token to .expressionTokens[].

notBegins(name,value) ⇒ ParamsBuilder
to add 'NOT BEGINS_WITH (:name, #value)' token to .expressionTokens[].

between(name,value1,value2) ⇒ ParamsBuilder
to add ':name BETWEEN #value1 AND #value2' token to .expressionTokens[].

notBetween(name,value1,value2) ⇒ ParamsBuilder
to add 'NOT :name BETWEEN #value1 AND #value2' token to .expressionTokens[].

exists(name) ⇒ ParamsBuilder
to add 'ATTRIBUTE_EXISTS (:name)' token to .expressionTokens[].

notExists(name) ⇒ ParamsBuilder
to add 'ATTRIBUTE_NOT_EXISTS (:name)' token to .expressionTokens[].

type(name,value) ⇒ ParamsBuilder
to add 'ATTRIBUTE_TYPE (:name,#value)' token to .expressionTokens[].

notType(name,value) ⇒ ParamsBuilder
to add 'NOT ATTRIBUTE_TYPE (:name,#value)' token to .expressionTokens[].

contains(name,value) ⇒ ParamsBuilder
to add 'CONTAINS (:name,#value)' token to .expressionTokens[].

notContains(name,value) ⇒ ParamsBuilder
to add 'NOT CONTAINS (:name,#value)' token to .expressionTokens[].

in(name,[value1,value2,...]) ⇒ ParamsBuilder
to add ':name IN (#value1,#value2,...)' token to .expressionTokens[].

notIn(name,[value1,value2,...]) ⇒ ParamsBuilder
to add 'NOT :name IN (#value1,#value2,...)' token to .expressionTokens[].

size(name,operator,value) ⇒ ParamsBuilder
to add 'SIZE (:name) operator #value' token to .expressionTokens[]. (operator should be one of '=','<>','<','<=','>', '>=')

index(name) ⇒ ParamsBuilder
to set .params.IndexName by the name argument.

key(obj) ⇒ ParamsBuilder
to set .params.Key by the obj argument.

item(obj) ⇒ ParamsBuilder
to set .params.Item by the obj argument.

update({name1:value1,name2:value2,...}, action='SET') ⇒ ParamsBuilder
to set .params.UpdateExpression by the obj argument converted to 'action :name1 = #value1, :name2 = #value2,...'. (action should be one of 'SET','ADD','REMOVE','DELETE'. 'SET' is default)

limit(num) ⇒ ParamsBuilder
to set .params.Limit by the num argument.

projection('name1,name2,...') ⇒ ParamsBuilder
to set .params.ProjectionExpression by the commaed names argument converted to ':name1, :name2,...'.

consumedCapacity(which) ⇒ ParamsBuilder
to set .params.ReturnComsumedCapacity by the which argument. (which should be one of 'TOTAL','INDEXES','NOT')

returnValues(which) ⇒ ParamsBuilder
to set .params.ReturnValues by the which argument. (which should be one of 'ALL_OLD','ALL_NEW','UPDATED_OLD','UPDATED_NEW')

class DocClient extends ParamsBuilder

constructor(doc) ⇒ DocClient
to initiate an instance of the DocClient. A aws.DynamoDB.DocumentClient instance is required.

executePut() ⇒ Promise
to execute the put method of the DocumentClient with .params of this. It will return a Promise when called with no argument.

executePut(callback) ⇒ DocClient
to execute the put method of the DocumentClient with .params of this. It will return the DocClient when called with a callback function.

executeGet() ⇒ Promise
to execute the get method of the DocumentClient with .params of this. It will return a Promise when called with no argument.

executeGet(callback) ⇒ DocClient
to execute the get method of the DocumentClient with .params of this. It will return the DocClient when called with a callback function.

executeUpdate() ⇒ Promise
to execute the update method of the DocumentClient with .params of this. It will return a Promise when called with no argument.

executeUpdate(callback) ⇒ DocClient
to execute the update method of the DocumentClient with .params of this. It will return the DocClient when called with a callback function.

executeDelete() ⇒ Promise
to execute the delete method of the DocumentClient with .params of this. It will return a Promise when called with no argument.

executeDelete(callback) ⇒ DocClient
to execute the delete method of the DocumentClient with .params of this. It will return the DocClient when called with a callback function.

executeQuery() ⇒ Promise
to execute the query method of the DocumentClient with .params of this. It will return a Promise when called with no argument.

executeQuery(callback) ⇒ DocClient
to execute the query method of the DocumentClient with .params of this. It will return the DocClient when called with a callback function.

License

Copyright © 2018, Seunghwan Noh. Released under the MIT License.

This is a module made more easily inspired by dynomo-node. The basic idea owes to @abdullahzn who created the dynamo-node.