dynamodb-repository
DynamoDB repository for key-value indexed tables. Designed for Lambda use. Handles niceties like created and updated timestamps and default id creation.
Install
$ npm install @setho/dynamodb-repository --save
Usage
TypeScript/ES6
import { KeyValueRepository } from '@setho/dynamodb-repository';
const myRepo = new KeyValueRepository({
tableName: 'Items',
keyName: 'id',
idOptions: {
prefix: 'ITEM_',
},
documentClient,
});
JavaScript
const { KeyValueRepository } = require('@setho/dynamodb-repository');
const myRepo = new KeyValueRepository({
tableName: 'Items',
keyName: 'id',
idOptions: {
prefix: 'ITEM#',
},
documentClient,
});
Constructor
Use the optional idOptions
constructor parameter to set an optional prefix
to give your ids some human-readable context. The remainder of the key is a ULID, which is both unique and lexicographically sortable. See an explanation of and motivation for ULIDs here.
Create
- Requires action
dynamodb:PutItem
- Automatically adds a string key (this will overwrite any you may try to provide). Use constructor options to specify length and optional prefix.
- Automatically provides a
createdAt
and updatedAt
timestamp in ISO-8601 - Returns what was saved; does not mutate the item passed in.
const mySavedItem = await myRepo.create(myItem);
mySavedItem.id;
mySavedItem.createdAt;
mySavedItem.updatedAt;
Get by Key
- Requires action
dynamodb:GetItem
. - Throws
404
if item not found using http-errors.
const myItem = await myRepo.get(id);
Get Many
- Requires action
dynamodb:Scan
- Accepts optional parameter fields
limit
and cursor
- Returns object with
items
(Array) and cursor
(String)
items
will always be an array; if nothing found, it will be emptycursor
will be present if there are more items to fetch, otherwise it will be undefined
const allItems = [];
const getAllItems = async ({ limit, cursor = null }) => {
const getResult = await myRepo.getMany({ limit, cursor });
allItems.push(...getResult.items);
if (getResult.cursor) {
await getAllItems({ cursor: getResult.cursor });
}
};
await getAllItems();
Remove by Key
- Requires action
dynamodb:DeleteItem
await myRepo.remove(id);
Update
- Requires
dynamodb:UpdateItem
- Honors revision check; it will only update if the revision on disk is the one you are updating. Will return a
409
if the revision has changed underneath you. - Will perform a partial update if you don't pass in all properties. Think of this as a "patch" vs. a replacement update. The
key
and revision
properties are always required. - Returns the entire entity, including both new and unchanged properties
const person = await myRepo.create({
name: 'Joe',
age: 28,
favoriteColor: 'blue',
});
person.favoriteColor = 'teal';
const newPerson1 = await myRepo.update(person);
console.log(newPerson1.favoriteColor);
const partial = {
favoriteColor: 'aquamarine',
key: person.key,
revision: newPerson1.revision,
};
const newPerson2 = await myRepo.update(partial);
console.log(newPerson2.favoriteColor);
console.log(newPerson2.age);
// More Coming Soon...