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.
Note: See the instructions here for migrating from Version 1 to Version 2 of this library.
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
You should create one client wrapper instance in a file that you then require as needed elsewhere in your service. If you do not need to configure the wrapper, you can create this basic file...
const clientWrapper = ;moduleexports = ;
... and then require it wherever like so:
const dynamodbClient = // later in a function in this file...const response = await dynamodbClient;
Sometimes you need to configure the wrapper. One reason would be if you are using Dynamodb with the serverless framework and the serverless-offline plugin. You can achieve this like so:
const clientWrapper = ; const config = processenvIS_OFFLINE ? connection: region: "localhost" endpoint: "http://localhost:8000" : null; moduleexports = ;
Note: in the above example, process.env.IS_OFFLINE
gets set by the serverless-offline plugin.
Alternatively you can use serverless-dynamodb-client, which creates a properly configured DocumentClient
instance. You can create and use that instance like so:
const dynamodb = ; const dynamodbClient = documentClient: dynamodbdoc; moduleexports = dynamodbClient;
Configuration Options
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; // 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; // 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; // 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; // 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; // 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; // 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; // 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; // 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; // 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;
This is a simple pass-through wrapper around the
AWS.DynamoDB.DocumentClient.put
method.
BatchWrite
await clientWrapper
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
This is a simple pass-through wrapper around the
AWS.DynamoDB.DocumentClient.batchWrite
method.
Update
await clientWrapper;
This is a simple pass-through wrapper around the
AWS.DynamoDB.DocumentClient.update
method.
Delete
await clientWrapper;
This is a simple pass-through wrapper around the
AWS.DynamoDB.DocumentClient.delete
method.