@jupiterone/dynamodb-dao

dynamodb-dao

This project contains code for a DynamoDbDao class that can be used for creating, querying, updating, and deleting from DynamoDB table. Unlike tools like dynamoose, DynamoDbDao is a lower level wrapper and aims not to abstract away too many of the DynamoDB implementation details.

Also, this module leverages TypeScript type declarations so that, when possible, methods arguments and return values are strictly typed.

Examples

Constructor:

import AWS from 'aws-sdk';
import DynamoDbDao from '@jupiterone/dynamodb-dao';

const dynamodb = new AWS.DynamoDB({
  apiVersion: '2012-08-10'
});

const documentClient = new AWS.DynamoDB.DocumentClient({
  service: dynamodb
});

// The type declaration of for the documents that we are storing
interface MyDocument {
  id: string;
  accountId: string;
  name: string;
  total?: number;
}

// Key schema should have one or two properties which correspond to
// hash key and range key.
//
// NOTE: a range key is optional and depends
// on how your DynamoDB table is configured.
interface MyDocumentKeySchema {
  // hash key
  accountId: string;

  // range key
  id: string;
}

const myDocumentDao = new DynamoDbDao<MyDocument, MyDocumentKeySchema>({
  tableName: 'my-documents',
  documentClient
});

Get query:

const myDocument = await myDocumentDao.get({ id, accountId });

Paginated query:

const { items, lastKey } = await myDocumentDao.query({
  index: 'NameIndex',
  keyConditionExpression: 'accountId = :accountId',
  startAt: cursor /* `cursor` is a previously returned `lastKey` */,
  scanIndexForward: true,
  attributeValues: {
    ':accountId': accountId,
  },
});

Count query:

const count = await myDocumentDao.count({
  index: 'NameIndex',
  keyConditionExpression: 'accountId = :accountId',
  attributeValues: {
    ':accountId': input.accountId,
  },
});

Put:

await myDocumentDao.put({
  id: 'something',
  accountId: 'abc'
  name: 'blah'
});

Delete:

await myDocumentDao.delete({ id, accountId });

Incrementing/Decrementing

NOTE: This should only be used where overcounting and undercounting can be tolerated. See the DynamoDB atomic counter documentation for more information.

If a property does not already exist, the initial value is assigned 0 and incremented/decremented from 0.

// `total` will have the value `5`
const { total } = await myDocumentDao.incr(
  // The key
  {
    id: 'abc',
    accountId: 'def',
  },
  // The `number` property to increment
  'total',
  // The number to increment by. Defaults to 1.
  5,
);

// `total` will have the value `-5`
const { total } = await myDocumentDao.decr(
  // The key
  {
    id: '123',
    accountId: 'def',
  },
  // The `number` property to increment
  'total',
  // The number to decrement by. Defaults to 1.
  5,
);

Optimistic Locking with Version Numbers

For callers who wish to enable an optimistic locking strategy there are two available toggles:

1. Provide the attribute you wish to be used to store the version number. This will enable optimistic locking on the following operations: put, update, and delete.

   Writes for documents that do not have a version number attribute will initialize the version number to 1. All subsequent writes will need to provide the current version number. If an out-of-date version number is supplied, an error will be thrown.

   Example of Dao constructed with optimistic locking enabled.

   const dao = new DynamoDbDao<DataModel, KeySchema>({
     tableName,
     documentClient,
     optimisticLockingAttribute: 'version',
   });
   

2. If you wish to ignore optimistic locking for a save operation, specify ignoreOptimisticLocking: true in the options on your put, update, or delete.

NOTE: Optimistic locking is NOT supported for batchWrite or batchPut operations. Consuming those APIs for data models that do have optimistic locking enabled may clobber your version data and could produce undesirable effects for other callers.

This was modeled after the Java Dynamo client implementation.

Developing

The test setup requires that docker-compose be installed. To run the tests, first open one terminal and start the local DynamoDB docker container by running:

yarn start:containers

In a second terminal run:

yarn test

To stop containers:

yarn stop:containers