DynamoDB library for simple and optimized way to use AWS DynamoDB
npm install @baselinejs/dynamodbBaseline 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.
- 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
- 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
``sh`
npm install @baselinejs/dynamodb
`sh`
yarn add @baselinejs/dynamodb
`sh`
pnpm install @baselinejs/dynamodb
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.
`ts`
const dynamo = getDynamodbConnection({
region: 'us-east-1',
});
Add a new item to your table, providing the previously created connection.
`ts`
const user = await putItem
dynamoDb: dynamo,
table: 'user-table-staging',
item: { userId: '123', email: 'example@example.com', name: 'Alice' },
});
Get a single item from your table.
`ts`
const user = await getItem
dynamoDb: dynamo,
table: 'user-table-staging',
key: {
userId: '123',
},
});
Update an item in your table.
Key properties will be automatically removed from fields to prevent attribute errors.
`ts`
const updatedUser = await updateItem
dynamoDb: dynamo,
table: 'user-table-staging',
key: {
userId: '123',
},
fields: {
name: 'Bob',
},
});
Delete an item from your table.
`ts`
const deletedUser = await deleteItem({
dynamoDb: dynamo,
table: 'user-table-staging',
key: {
userId: '123',
},
});
Fetch all items from a table.
`ts`
const allUsers = await getAllItems
dynamoDb: dynamo,
table: 'user-table-staging',
});
Query items from an index.
`ts`
const users = await queryItems
dynamoDb: dynamo,
table: 'user-table-staging',
keyName: 'email',
keyValue: 'example@example.com',
indexName: 'email-index',
});
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.
`ts`
const users = await batchGetItems
dynamoDb: dynamo,
table: 'user-table-staging',
keys: [{ userId: '123' }, { userId: '456' }],
});
Batch create items into a table.
Automatically handles splitting the items into chunks of 25.
`ts`
const users = await batchPutItems
dynamoDb: dynamo,
table: 'user-table-staging',
items: [
{ userId: '123', name: 'Alice' },
{ userId: '456', name: 'Bob' },
],
});
Batch delete items from a table.
Automatically handles splitting the keys into chunks of 25.
`ts`
const isDeleted = await batchDeleteItems({
dynamoDb: dynamo,
table: 'user-table-staging',
keys: [{ userId: '123' }, { userId: '456' }],
});
Query items from a table with a range key.
`ts`
const userPurchases = await queryItemsRange
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
rangeKeyName: 'createdAt',
rangeKeyValue: '2022',
// Fuzzy search will use a begins_with condition
fuzzy: true,
indexName: 'userId-createdAt-index',
});
Equivalent query using queryItems
`ts`
const userPurchases = await queryItems
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
indexName: 'userId-createdAt-index',
rangeCondition: {
operator: 'BeginsWith',
field: 'createdAt',
value: '2022',
},
});
Query items from a table with a range key between two values.
`ts`
const userPurchases = await queryItemsRangeBetween
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
rangeKeyName: 'createdAt',
rangeKeyValueMin: '2022-01-01T00:00:00.000Z',
rangeKeyValueMax: '2023-01-01T00:00:00.000Z',
indexName: 'userId-createdAt-index',
});
Equivalent query using queryItems
`ts`
const userPurchases = await queryItems
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
indexName: 'userId-createdAt-index',
rangeCondition: {
operator: 'Between',
field: 'createdAt',
value: '2022-01-01T00:00:00.000Z',
betweenSecondValue: '2023-01-01T00:00:00.000Z',
},
});
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.
`ts`
try {
const user = await putItem
dynamoDb: dynamo,
table: 'user-table-staging',
item: { userId: '123', email: 'example2@example.com', name: 'Alice' },
conditions: [
{
// Only create if this userId does not already exist
operator: 'AttributeNotExists',
field: 'userId',
},
],
});
} catch (error) {
if (error.name === 'ConditionalCheckFailedException') {
// error.Item contains the item that already exists with the specified userId
}
}
You can limit the number of items returned by specifying the limit parameter.query
This applies to the functions as well as the getAllItems function.
The function will handle pagination internally up until the limit is reached.
`ts`
const userPurchases = await queryItems
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
limit: 10,
});
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.
`ts`
const userPurchases = await queryItems
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
projectionExpression: ['userId', 'createdAt'],
});
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.
`ts`
const user = unmarshallItem
Marshalling is used to convert a JavaScript object into a DynamoDB record.
`ts`
const user = {
userId: '123',
email: 'example@example.com',
name: 'Alice',
};
const marshalledUser = marshallItem(user);
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.
IS_OFFLINE
Will be "true" in your handlers when using serverless-offline."true"
When 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.