SYNOPSIS
A light weight, async/await abstraction for DynamoDB.
USAGE
AS A LIBRARY
npm install mindpointgroup/raziel
AS A CLI
npm install mindpointgroup/raziel -g
CONSTRUCTOR
Create a constructor and configure it.
const Database = require('dynamodb')
const db = new Database({ region: 'us-west-2' })
TABLES
Create or open a table. The optional options object may include...
const options = {
encrypted: true || false,
streaming: 'NEW_IMAGE' || 'OLD_IMAGE' || 'NEW_AND_OLD_IMAGES' || 'KEYS_ONLY',
createIfNotExists: true || false,
ttl: true || false
}
const { err, table } = await db.open('foo', options)
PUT
Put a key/value.
const { err } = await table.put(['a', 'a'], { foo: 100 })
A key is input as an array. The first item in the array is the
partition
and the rest of the items are eventually concatenated
to form the range
. The partition
is like a grouping
of keys.
Keys are sorted lexicographically and can be queried or looked up.
You can optionally provide more arguments that will be used as attributes.
const attr1 = { test: { S: 'Foo' } }
const { err } = await table.put(['a', 'a'], value, attr1)
TTL
An object literal can be provided as the second positional argument.
This is where a TTL
(time to live) value can be specified. When
specified, the item will be deleted from the database if the duration
specified is less than the current time.
For example the following put
operation will add an item to the
database which will be removed after 1 second
.
const { err } = await table.put(['a', 'a'], { ttl: '+1s' }, { foo: 100 })
See this repo for ttl units of measure.
GET
Get a key/value
const { err, value } = await table.get(['a', 'b'])
assert(value === { foo: 100 })
GET MULTIPLE VALUES AT ONCE
Specify an array of keys as the first argument to the get
method.
If a requested item does not exist, it is not returned in the result. Requests for nonexistent items consume the minimum read capacity units according to the type of read (this is how the Dynamodb aws-sdk works).
Gets are limited to 100 keys at a time (specified in the aws api).
const { err, data } = await table.get([['a', 'a'], ['a', 'b']])
assert.deepEqual(data[0].key, ['a', 'a'])
assert.deepEqual(data[0].value, { foo: 100 })
DEL
Delete a key/value
const { err } = await table.del(['a', 'b'])
BATCH
Put and or delete multiple key/values. Use an array of objects. With type
and
key
. If the type
is put
, you must specify value
and you can also provide
other attributes (like the put
method).
const ops = [
{ type: 'put', key: ['a', 'a'], value: { foo: 100 } },
{ type: 'put', key: ['a', 'b'], value: { bar: 200 } },
{ type: 'put', key: ['b', 'a'], value: { baz: 300 }, someOtherAttribute: 1 },
{ type: 'del', key: ['a', 'c'] }
]
const { err } = await table.batch(ops)
QUERY
Get a range of keys and their values. This produces an iterator with a next method that is awaitable.
If the previous batch command was executed, there there were only three records in the database. Two events would be emitted by the following query.
const params = {
key: ['a']
}
const iterator = table.query(params)
for await (const { key, value } of iterator) {
console.log(key, value)
}
ADVANCED QUERIES
const iterator = table.query(
`hkey = "z" AND begins_with(rkey, "a")`,
`x = "b"`
)
In the above example, the first argument is the KeyConditionExpression
,
and the second argument is the FilterExpression
. You don't need to
specify the [ExpressionAttributeValues
][eav] since thats already parsed out
for you. Values are contained in double quotes and you can mitigate reserved
words using an octothorpe (#
).
LEGACY NODE VERSIONS
In node versions less than 10.1.x
const iterator = table.query({ key: ['a'] })
while (true) {
const { err, key, value, done } = await iterator.next()
if (done) break // only true when there is no more data
}
Working with local DynamoDB
If you would like to use DynamoDB Local you will want to set the following environment variables.
LOCAL_DYNAMO=true
LOCAL_DYNAMO_PORT=8000
LOCAL_DYNAMO_PORT
is optional and defaults to 8000 which is the default port.
NOTE: This does not validate that a proper DynamoDB process is listenting on
8000
(or specified port).
Testing
Local Testing
npm run test
CircleCI Emulator (require the circleci CLI to be installed)
circleci local execute --job node-lambda -e AWS_ACCESS_KEY_ID=ABCDEF -e AWS_SECRET_ACCESS_KEY=GHIJKL
circleci local execute --job node-v8 -e AWS_ACCESS_KEY_ID=ABCDEF -e AWS_SECRET_ACCESS_KEY=GHIJKL
circleci local execute --job node-v10 -e AWS_ACCESS_KEY_ID=ABCDEF -e AWS_SECRET_ACCESS_KEY=GHIJKL
[eva]:https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-ExpressionAttributeValues) or the [ExpressionAttributeNames
](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-ExpressionAttributeNames