This is a community fork
We are planning to merge it back if AWS allows it. Meanwhile, enjoy:
- SDK v3 support
To install:
npm install aws-community-fork/dynamodb-data-mapper
Amazon DynamoDB DataMapper For JavaScript
This repository hosts several packages that collectively make up an object to document mapper for JavaScript applications using Amazon DynamoDB.
Getting started
The @awslabs-community-fork/dynamodb-data-mapper package provides
a simple way to persist and load an application's domain objects to and from
Amazon DynamoDB. When used together with the decorators provided by the
@awslabs-community-fork/dynamodb-data-mapper-annotations package,
you can describe the relationship between a class and its representation in
DynamoDB by adding a few decorators:
import {
attribute,
hashKey,
rangeKey,
table,
} from '@awslabs-community-fork/dynamodb-data-mapper-annotations';
@table('table_name')
class MyDomainObject {
@hashKey()
id: string;
@rangeKey({defaultProvider: () => new Date()})
createdAt: Date;
@attribute()
completed?: boolean;
}With domain classes defined, you can interact with records in DynamoDB via an
instance of DataMapper:
import {DataMapper} from '@awslabs-community-fork/dynamodb-data-mapper';
import DynamoDB = require('aws-sdk/clients/dynamodb');
const mapper = new DataMapper({
client: new DynamoDB({region: 'us-west-2'}), // the SDK client used to execute operations
tableNamePrefix: 'dev_' // optionally, you can provide a table prefix to keep your dev and prod tables separate
});Supported operations
Using the mapper object and MyDomainObject class defined above, you can
perform the following operations:
put
Creates (or overwrites) an item in the table
const toSave = Object.assign(new MyDomainObject, {id: 'foo'});
mapper.put(toSave).then(objectSaved => {
// the record has been saved
});
get
Retrieves an item from DynamoDB
mapper.get(Object.assign(new MyDomainObject, {id: 'foo', createdAt: new Date(946684800000)}))
.then(myItem => {
// the item was found
})
.catch(err => {
// the item was not found
})NB: The promise returned by the mapper will be rejected with an
ItemNotFoundException if the item sought is not found.
update
Updates an item in the table
const myItem = await mapper.get(Object.assign(
new MyDomainObject,
{id: 'foo', createdAt: new Date(946684800000)}
));
myItem.completed = true;
await mapper.update(myItem);
delete
Removes an item from the table
await mapper.delete(Object.assign(
new MyDomainObject,
{id: 'foo', createdAt: new Date(946684800000)}
));
scan
Lists the items in a table or index
for await (const item of mapper.scan(MyDomainObject)) {
// individual items will be yielded as the scan is performed
}
// Optionally, scan an index instead of the table:
for await (const item of mapper.scan(MyDomainObject, {indexName: 'myIndex'})) {
// individual items will be yielded as the scan is performed
}
query
Finds a specific item (or range of items) in a table or index
for await (const foo of mapper.query(MyDomainObject, {id: 'foo'})) {
// individual items with a hash key of "foo" will be yielded as the query is performed
}Batch operations
The mapper also supports batch operations. Under the hood, the batch will
automatically be split into chunks that fall within DynamoDB's limits (25 for
batchPut and batchDelete, 100 for batchGet). The items can belong to any
number of tables, and exponential backoff for unprocessed items is handled
automatically.
batchPut
Creates (or overwrites) multiple items in the table
const toSave = [
Object.assign(new MyDomainObject, {id: 'foo', completed: false}),
Object.assign(new MyDomainObject, {id: 'bar', completed: false})
];
for await (const persisted of mapper.batchPut(toSave)) {
// items will be yielded as they are successfully written
}
batchGet
Fetches multiple items from the table
const toGet = [
Object.assign(new MyDomainObject, {id: 'foo', createdAt: new Date(946684800000)}),
Object.assign(new MyDomainObject, {id: 'bar', createdAt: new Date(946684800001)})
];
for await (const found of mapper.batchGet(toGet)) {
// items will be yielded as they are successfully retrieved
}NB: Only items that exist in the table will be retrieved. If a key is not found, it will be omitted from the result.
batchDelete
Removes multiple items from the table
const toRemove = [
Object.assign(new MyDomainObject, {id: 'foo', createdAt: new Date(946684800000)}),
Object.assign(new MyDomainObject, {id: 'bar', createdAt: new Date(946684800001)})
];
for await (const found of mapper.batchDelete(toRemove)) {
// items will be yielded as they are successfully removed
}Operations with Expressions
Aplication example
import {
AttributePath,
FunctionExpression,
UpdateExpression,
} from '@awslabs-community-fork/dynamodb-expressions';
const expr = new UpdateExpression();
// given the anotation bellow
@table('tableName')
class MyRecord {
@hashKey()
email?: string;
@attribute()
passwordHash?: string;
@attribute()
passwordSalt?: string;
@attribute()
verified?: boolean;
@attribute()
verifyToken?: string;
}
// you make a mapper operation as follows
const aRecord = Object.assign(new MyRecord(), {
email,
passwordHash: password,
passwordSalt: salt,
verified: false,
verifyToken: token,
});
mapper.put(aRecord, {
condition: new FunctionExpression('attribute_not_exists', new AttributePath('email')
}).then( /* result handler */ );Table lifecycle operations
createTable
Creates a table for the mapped class and waits for it to be initialized:
mapper.createTable(MyDomainObject, {readCapacityUnits: 5, writeCapacityUnits: 5})
.then(() => {
// the table has been provisioned and is ready for use!
})
ensureTableExists
Like createTable, but only creates the table if it doesn't already exist:
mapper.ensureTableExists(MyDomainObject, {readCapacityUnits: 5, writeCapacityUnits: 5})
.then(() => {
// the table has been provisioned and is ready for use!
})
deleteTable
Deletes the table for the mapped class and waits for it to be removed:
await mapper.deleteTable(MyDomainObject)
ensureTableNotExists
Like deleteTable, but only deletes the table if it exists:
await mapper.ensureTableNotExists(MyDomainObject)Constituent packages
The DataMapper is developed as a monorepo using lerna.
More detailed documentation about the mapper's constituent packages is available
by viewing those packages directly.
