DynamoDB Toolbox

Single Table Designs have never been this easy!

The DynamoDB Toolbox is a set of tools that makes it easy to work with Amazon DynamoDB and the DocumentClient. It's designed with Single Tables in mind, but works just as well with multiple tables. It lets you define your Entities (with typings and aliases) and map them to your DynamoDB tables. You can then generate the API parameters to put, get, delete, update, query, scan, batchGet, and batchWrite data by passing in JavaScript objects. The DynamoDB Toolbox will map aliases, validate and coerce types, and even write complex UpdateExpressions for you. 😉

Version 0.4 🙌

v0.4 is here and now supports "Type Inferencing" 😎. This is a new feature that infers types from your Entity definitions. There should be NO regressions from v0.3.5, but please submit an issue if you find one!

Feedback is welcome and much appreciated! (Huge thanks to @ThomasAribart for all his work on this 🙌)

Docs & Community

• Full Documentation
• GitHub Discussions

Quick Start

Install DynamoDB Toolbox:

1# npm
2npm i dynamodb-toolbox
3
4# yarn
5yarn add dynamodb-toolbox

Require or import Table and Entity from dynamodb-toolbox:

1import { Table, Entity } from 'dynamodb-toolbox'

Create a Table (with the DocumentClient):

1import DynamoDB from 'aws-sdk/clients/dynamodb'
2
3const DocumentClient = new DynamoDB.DocumentClient({
4  // Specify your client options as usual
5  convertEmptyValue: false
6})
7
8// Instantiate a table
9const MyTable = new Table({
10  // Specify table name (used by DynamoDB)
11  name: 'my-table',
12
13  // Define partition and sort keys
14  partitionKey: 'pk',
15  sortKey: 'sk',
16
17  // Add the DocumentClient
18  DocumentClient
19})

Create an Entity:

1const Customer = new Entity({
2  // Specify entity name
3  name: 'Customer',
4
5  // Define attributes
6  attributes: {
7    id: { partitionKey: true }, // flag as partitionKey
8    sk: { hidden: true, sortKey: true }, // flag as sortKey and mark hidden
9    age: { type: 'number' }, // set the attribute type
10    name: { type: 'string', map: 'data' }, // map 'name' to table attribute 'data'
11    emailVerified: { type: 'boolean', required: true }, // specify attribute as required
12    co: { alias: 'company' }, // alias table attribute 'co' to 'company'
13    status: ['sk', 0], // composite key mapping
14    date_added: ['sk', 1] // composite key mapping
15  },
16
17  // Assign it to our table
18  table: MyTable
19
20  // In Typescript, the "as const" statement is needed for type inference
21} as const)

Put an item:

1// Create an item (using table attribute names or aliases)
2const customer = {
3  id: 123,
4  age: 35,
5  name: 'Jane Smith',
6  emailVerified: true,
7  company: 'ACME',
8  status: 'active',
9  date_added: '2020-04-24'
10}
11
12// Use the 'put' method of Customer:
13await Customer.put(customer)

The item will be saved to DynamoDB like this:

1{
2  "pk": 123,
3  "sk": "active#2020-04-24",
4  "age": 35,
5  "data": "Jane Smith",
6  "emailVerified": true,
7  "co": "ACME",
8  // Attributes auto-generated by DynamoDB-Toolbox
9  "_et": "customer", // Entity name (required for parsing)
10  "_ct": "2021-01-01T00:00:00.000Z", // Item creation date (optional)
11  "_md": "2021-01-01T00:00:00.000Z" // Item last modification date (optional)
12}

You can then get the data:

1// Specify primary key
2const primaryKey = {
3  id: 123,
4  status: 'active',
5  date_added: '2020-04-24'
6}
7
8// Use the 'get' method of Customer
9const response = await Customer.get(primaryKey)

Since v0.4, the method inputs, options and response types are inferred from the Entity definition:

1await Customer.put({
2  id: 123,
3  // ❌ Sort key is required ("sk" or both "status" and "date_added")
4  age: 35,
5  name: ['Jane', 'Smith'], // ❌ name should be a string
6  emailVerified: undefined, // ❌ attribute is marked as required
7  company: 'ACME'
8})
9
10const { Item: customer } = await Customer.get({
11  id: 123,
12  status: 'active',
13  date_added: '2020-04-24' // ✅ Valid primary key
14})
15type Customer = typeof customer
16// 🙌 Type is equal to:
17type ExpectedCustomer =
18  | {
19      id: any
20      age?: number | undefined
21      name?: string | undefined
22      emailVerified: boolean
23      company?: any
24      status: any
25      date_added: any
26      entity: string
27      created: string
28      modified: string
29    }
30  | undefined

See Type Inference in the documentation for more details.

Features

• Table Schemas and DynamoDB Typings: Define your Table and Entity data models using a simple JavaScript object structure, assign DynamoDB data types, and optionally set defaults.
• Magic UpdateExpressions: Writing complex UpdateExpression strings is a major pain, especially if the input data changes the underlying clauses or requires dynamic (or nested) attributes. This library handles everything from simple SET clauses, to complex list and set manipulations, to defaulting values with smartly applied if_not_exists() to avoid overwriting data.
• Bidirectional Mapping and Aliasing: When building a single table design, you can define multiple entities that map to the same table. Each entity can reuse fields (like pk andsk) and map them to different aliases depending on the item type. Your data is automatically mapped correctly when reading and writing data.
• Composite Key Generation and Field Mapping: Doing some fancy data modeling with composite keys? Like setting your sortKey to [country]#[region]#[state]#[county]#[city]#[neighborhood] model hierarchies? DynamoDB Toolbox lets you map data to these composite keys which will both autogenerate the value and parse them into fields for you.
• Type Coercion and Validation: Automatically coerce values to strings, numbers and booleans to ensure consistent data types in your DynamoDB tables. Validate list, map, and set types against your data. Oh yeah, and sets are automatically handled for you. 😉
• Powerful Query Builder: Specify a partitionKey, and then easily configure your sortKey conditions, filters, and attribute projections to query your primary or secondary indexes. This library can even handle pagination with a simple .next() method.
• Simple Table Scans: Scan through your table or secondary indexes and add filters, projections, parallel scans and more. And don't forget the pagination support with .next().
• Filter and Condition Expression Builder: Build complex Filter and Condition expressions using a standardized array and object notation. No more appending strings!
• Projection Builder: Specify which attributes and paths should be returned for each entity type, and automatically filter the results.
• Secondary Index Support: Map your secondary indexes (GSIs and LSIs) to your table, and dynamically link your entity attributes.
• Batch Operations: Full support for batch operations with a simpler interface to work with multiple entities and tables.
• Transactions: Full support for transaction with a simpler interface to work with multiple entities and tables.
• Default Value Dependency Graphs: Create dynamic attribute defaults by chaining other dynamic attribute defaults together.
• TypeScript Support: v0.4 of this library provides strong typing support AND type inference 😍. Inferred type can still overriden with Overlays. Some Utility Types are also exposed. Additional work is still required to support schema validation & typings.

Additional References

• DocumentClient SDK Reference
• Best Practices for DynamoDB
• DynamoDB, explained.
• The DynamoDB Book

Contributions and Feedback

Contributions, ideas and bug reports are welcome and greatly appreciated. Please add issues for suggestions and bug reports or create a pull request. You can also contact me on Twitter: @jeremy_daly.