Baseline DynamoDB

Baseline DynamoDB is an optimized utility library that simplifies standard DynamoDB operations. It's focused towards multi table designed applications, and aims to provide a set of functions that are tailored to the specific use cases of these applications.

Features

• Simplified Item Operations: CRUD with less boilerplate code.
• Advanced Querying: Easily use sort key conditions, including begins_with and between, to filter queries.
• Batch Operations: Automatically handles chunking for batch get, batch create, and batch delete operations.
• Lightweight

Table of Contents

• Installation
• Quick Start
  • Establishing a Connection
  • Creating an item
  • Getting a single item
  • Updating an item
  • Deleting an item
  • Retrieving all items
  • Querying items
• Extended Usages
  • Batch Get
  • Batch Create
  • Batch Delete
  • Query Range
  • Query Range Between
  • Create, Update, Delete Conditions
  • Limit
  • Projection Expressions
• Utility Functions
  • Unmarshalling
  • Marshalling
• Error Handling
• Environment Variables
  • Serverless Offline

Installation

1npm install @baselinejs/dynamodb

1yarn add @baselinejs/dynamodb

1pnpm install @baselinejs/dynamodb

Quick Start

Establishing a Connection

First create a connection to your DynamoDB table.

Must specify a region.

Natively handles both local and deployed environments. See Environment Variables for more information.

1const dynamo = getDynamodbConnection({
2  region: 'us-east-1',
3});

Creating an item

Add a new item to your table, providing the previously created connection.

1const user = await putItem<User>({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  item: { userId: '123', email: 'example@example.com', name: 'Alice' },
5});

Getting a single item

Get a single item from your table.

1const user = await getItem<User>({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  key: {
5    userId: '123',
6  },
7});

Updating an item

Update an item in your table.

Key properties will be automatically removed from fields to prevent attribute errors.

1const updatedUser = await updateItem<User>({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  key: {
5    userId: '123',
6  },
7  fields: {
8    name: 'Bob',
9  },
10});

Deleting an item

Delete an item from your table.

1const deletedUser = await deleteItem({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  key: {
5    userId: '123',
6  },
7});

Retrieving all items

Fetch all items from a table.

1const allUsers = await getAllItems<User>({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4});

Querying items

Query items from an index.

1const users = await queryItems<User>({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  keyName: 'email',
5  keyValue: 'example@example.com',
6  indexName: 'email-index',
7});

Extended Usages

Batch Get

Batch get items from a table Automatically handles splitting the keys into chunks of 100.

Returned item order is not necessarily the same as the input order.

1const users = await batchGetItems<User>({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  keys: [{ userId: '123' }, { userId: '456' }],
5});

Batch Create

Batch create items into a table. Automatically handles splitting the items into chunks of 25.

1const users = await batchPutItems<User>({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  items: [
5    { userId: '123', name: 'Alice' },
6    { userId: '456', name: 'Bob' },
7  ],
8});

Batch Delete

Batch delete items from a table. Automatically handles splitting the keys into chunks of 25.

1const isDeleted = await batchDeleteItems({
2  dynamoDb: dynamo,
3  table: 'user-table-staging',
4  keys: [{ userId: '123' }, { userId: '456' }],
5});

Query Range

Query items from a table with a range key.

1const userPurchases = await queryItemsRange<Purchase>({
2  dynamoDb: dynamo,
3  table: 'purchase-table-staging',
4  keyName: 'userId',
5  keyValue: '123',
6  rangeKeyName: 'createdAt',
7  rangeKeyValue: '2022',
8  // Fuzzy search will use a begins_with condition
9  fuzzy: true,
10  indexName: 'userId-createdAt-index',
11});

Equivalent query using queryItems

1const userPurchases = await queryItems<Purchase>({
2  dynamoDb: dynamo,
3  table: 'purchase-table-staging',
4  keyName: 'userId',
5  keyValue: '123',
6  indexName: 'userId-createdAt-index',
7  rangeCondition: {
8    operator: 'BeginsWith',
9    field: 'createdAt',
10    value: '2022',
11  },
12});

Query Range Between

Query items from a table with a range key between two values.

1const userPurchases = await queryItemsRangeBetween<Purchase>({
2  dynamoDb: dynamo,
3  table: 'purchase-table-staging',
4  keyName: 'userId',
5  keyValue: '123',
6  rangeKeyName: 'createdAt',
7  rangeKeyValueMin: '2022-01-01T00:00:00.000Z',
8  rangeKeyValueMax: '2023-01-01T00:00:00.000Z',
9  indexName: 'userId-createdAt-index',
10});

Equivalent query using queryItems

1const userPurchases = await queryItems<Purchase>({
2  dynamoDb: dynamo,
3  table: 'purchase-table-staging',
4  keyName: 'userId',
5  keyValue: '123',
6  indexName: 'userId-createdAt-index',
7  rangeCondition: {
8    operator: 'Between',
9    field: 'createdAt',
10    value: '2022-01-01T00:00:00.000Z',
11    betweenSecondValue: '2023-01-01T00:00:00.000Z',
12  },
13});

Create, Update, Delete Conditions

A conditions array can be provided to the putItem, updateItem, and deleteItem functions to specify conditions that must be met for the operation to succeed.

Conditions are combined with AND.

1try {
2  const user = await putItem<User>({
3    dynamoDb: dynamo,
4    table: 'user-table-staging',
5    item: { userId: '123', email: 'example2@example.com', name: 'Alice' },
6    conditions: [
7      {
8        // Only create if this userId does not already exist
9        operator: 'AttributeNotExists',
10        field: 'userId',
11      },
12    ],
13  });
14} catch (error) {
15  if (error.name === 'ConditionalCheckFailedException') {
16    // error.Item contains the item that already exists with the specified userId
17  }
18}

Limit

You can limit the number of items returned by specifying the limit parameter. This applies to the query functions as well as the getAllItems function.

The function will handle pagination internally up until the limit is reached.

1const userPurchases = await queryItems<Purchase>({
2  dynamoDb: dynamo,
3  table: 'purchase-table-staging',
4  keyName: 'userId',
5  keyValue: '123',
6  limit: 10,
7});

Projection Expressions

Projection expressions are used to limit the attributes returned from a query to only the specified fields.

To maintain type safety, you can specify the fields you want to return using the second generic type parameter.

1const userPurchases = await queryItems<Purchase, 'userId' | 'createdAt'>({
2  dynamoDb: dynamo,
3  table: 'purchase-table-staging',
4  keyName: 'userId',
5  keyValue: '123',
6  projectionExpression: ['userId', 'createdAt'],
7});

Utility Functions

Unmarshalling

Unmarshalling is used to convert a DynamoDB record into a JavaScript object.

This is useful when using dynamodb streams, as the new and old images are returned as DynamoDB records that need to be unmarshalled.

1const user = unmarshallItem<User>(record.dynamodb?.NewImage);

Marshalling

Marshalling is used to convert a JavaScript object into a DynamoDB record.

1const user = {
2  userId: '123',
3  email: 'example@example.com',
4  name: 'Alice',
5};
6const marshalledUser = marshallItem(user);

Error Handling

Errors are not caught internally but are instead propagated up to the calling code.

To handle these errors effectively, wrap function calls in try-catch blocks in your application. This allows for custom error handling strategies, such as logging errors or retrying failed operations.

Environment Variables

Serverless Offline

IS_OFFLINE

Will be "true" in your handlers when using serverless-offline. When "true" will use values appropriate to work with DynamoDB Local.

region: "localhost",
endpoint: "http://localhost:8000",

FORCE_ONLINE

Set to "true" to override the IS_OFFLINE environment variable and use a deployed DynamoDB instance.