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, returning the results as Promises.

Installation

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

or

$ yarn add 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 aws-sdk as a dev dependency so it is available locally when testing.

Usage

Configuration

You should create one client wrapper instance in a file that you then require where needed elsewhere in your service. If you do not need to configure the wrapper, you can create this basic file...

const clientWrapper = require("dynamodb-doc-client-wrapper");
module.exports = clientWrapper();

... and then require it as needed:

const dynamodbClient = require('./path/to/the/file/above')

// later in a function in this file...
const response = await dynamodbClient.query({
    TableName: 'MyTable',
    KeyConditionExpression: 'tagType = :tagType',
    ExpressionAttributeValues: { ':tagType': 'audience' },
    ProjectionExpression: 'id, label'
});

If you need to configure the wrapper, you can instead create a file similar to this one:

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

const config = process.env.IS_OFFLINE
  ? {
      connection: {
        region: "localhost",
        endpoint: "http://localhost:8000"
      }
    }
  : null;

module.exports = clientWrapper(config);

Note: in the above example, process.env.IS_OFFLINE gets set by the serverless-offline plugin.

All config options are optional. The allowed options are:

Name	Description	Default Value
connection	An AWS.DynamoDB.DocumentClient config object. Ignored if the documentClient option exists.	n/a
documentClient	Your own preconfigured AWS.DynamoDB.DocumentClient instance.	n/a
notFoundMsg	The message of the error thrown when a get or batchGet request returns a 404 response.	'[404] Entity Not Found'

API

Query

const response = await 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 response = await 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 response = await 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 response = await 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 response = await 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 by default is '[404] Entity Not Found'.

BatchGetBasic

const response = await 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 response = await 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 by default is '[404] Entity Not Found'.

TryGet

const response = await 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 response = await 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

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

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

BatchWrite

await 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

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

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

Update

await 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

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

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

License

MIT