dynamodb-doc-client-wrapper

dynamodb-doc-client-wrapper

A wrapper around the AWS DynamoDB DocumentClient class that handles building complete result sets from the query, scan and batchGet methods.

Install

$ npm install --save dynamodb-doc-client-wrapper

You also need to have the aws-sdk package available as a peer dependency. When running AWS Lambda functions on AWS, that package is already installed; you can install it as a dev dependency so it is available locally when testing.

Usage

Query

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.query({
    TableName: 'MyTable',
    KeyConditionExpression: 'tagType = :tagType',
    ExpressionAttributeValues: { ':tagType': 'audience' },
    ProjectionExpression: 'id, label'
});

// response is a list of db items.

The response will have all matching items, even if the query had to be done in multiple takes because of the limit on total response size in DynamoDB.

QueryBasic

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.queryBasic({
    TableName: 'MyTable',
    KeyConditionExpression: 'tagType = :tagType',
    ExpressionAttributeValues: { ':tagType': 'audience' },
    ProjectionExpression: 'id, label'
});

// response is the raw DynamoDB client response

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.query method, for when you want access to the entire response object and you will manage getting all the results yourself.

Scan

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.scan({
    TableName: 'MyTable',
    ProjectionExpression: 'id, label'
});

// response is a list of db items.

The response will have all matching items, even if the scan had to be done in multiple takes because of the limit on total response size in DynamoDB.

ScanBasic

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.scanBasic({
    TableName: 'MyTable',
    ProjectionExpression: 'id, label'
});

// response is the raw DynamoDB client response

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.scan method, for when you want access to the entire response object and you will manage getting all the results yourself.

BatchGet

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.batchGet({
    RequestItems: {
        'Table1': {
            Keys: [{ id: 1 }, { id: 2 }]
        },
        'Table2': {
            Keys: [{ id: 3 }, { id: 4 }]
        }
    }
});

// response is an object with the results for each table in it, e.g.:
//
// {
//     Responses: {
//         'Table1': [
//             { id: 1, name: 'a' },
//             { id: 2, name: 'b' }
//         ],
//         'Table2': [
//             { id: 3, name: 'c' },
//             { id: 4, name: 'd' }
//         ]
//     }
// }

All items will be retrieved, even if the number of items to be retrieved exceeds the DynamoDB limit of 100 items, or if the limit on total response size in DynamoDB was exceeded.

An exception is thrown if any requested db item was not found. The exception message is '[404] Entity Not Found'.

BatchGetBasic

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.batchGetBasic({
    RequestItems: {
        'Table1': {
            Keys: [{ id: 1 }, { id: 2 }]
        }
    }
});

// response is the raw DynamoDB client response

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.batchGet method, for when you want access to the entire response object and you will manage getting all the results yourself.

Get

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.get({
    TableName: 'MyTable',
    Index: { id: 1 }
});

// response is the item, e.g. { id: 1, name: 'a' }

An exception is thrown if the requested db item was not found. The exception message is '[404] Entity Not Found'.

TryGet

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.tryGet({
    TableName: 'MyTable',
    Index: { id: 1 }
});

// response is the item, e.g. { id: 1, name: 'a' },
// or null if the item does not exist in the db.

If the requested db item was not found then null is returned.

GetBasic

const clientWrapper = require('dynamodb-doc-client-wrapper');

const response = yield clientWrapper.getBasic({
    TableName: 'MyTable',
    Index: { id: 1 }
});

// response is the raw response, e.g., { Item: { id: 1, name: 'a' } }

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.get method, for when you want access to the entire response object.

Put

const clientWrapper = require('dynamodb-doc-client-wrapper');

yield clientWrapper.put({
    TableName: 'MyTable',
    Item: { id: 1, name: 'a' }
});

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.put method.

BatchWrite

const clientWrapper = require('dynamodb-doc-client-wrapper');

yield clientWrapper.batchWrite({
    RequestItems: {
        'Table1': [
            { DeleteRequest: { Key: { id: 1 } } }
        ]
    }
})

This method ultimately invokes the AWS.DynamoDB.DocumentClient.batchWrite method, but it takes care of batching up the writes so that a single request does not exceed the DynamoDB limits, and it resubmits unprocessed writes.

BatchWriteBasic

const clientWrapper = require('dynamodb-doc-client-wrapper');

yield clientWrapper.batchWriteBasic({
    RequestItems: {
        'Table1': [
            { DeleteRequest: { Key: { id: 1 } } }
        ]
    }
})

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.batchWrite method.

Update

const clientWrapper = require('dynamodb-doc-client-wrapper');

yield clientWrapper.update({
    TableName: 'Table',
    Key: { HashKey : 'hashkey' },
    UpdateExpression: 'set #a = :x + :y',
});

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.update method.

Delete

const clientWrapper = require('dynamodb-doc-client-wrapper');

yield clientWrapper.delete({
    TableName: 'MyTable',
    Index: { id: 1 }
});

This is a simple pass-through wrapper around the AWS.DynamoDB.DocumentClient.delete method.

License

MIT