README

simple dynamo

This is meant to simplify dynamodb access.

It wraps the document client in promises, and has a helper if you are using cloudformation to track build/destroy of your dynamo resources.

It's a thin wrapper, but it's boilerplate I kept having to write, so this should save everyone a little time.

installation

Install in your project:

npm i @konsumer/simpledynamo

usage

config & provisioning

Cloudformation is a nice way to provision your resources, and there is a helper function fromCloudFormation(table, stack) to set the table-name.

Setup a cloudformation.yml description of your databases. Here is an example with id PK, here is more info. Another common thing I setup a lot here are GlobalSecondaryIndexes.

AWSTemplateFormatVersion: 2010-09-09
Description: My Stuff
Resources:
  MyStuff:
    Type: 'AWS::DynamoDB::Table'
    DeletionPolicy: Delete
    Properties:
      AttributeDefinitions:
        - AttributeName: id
          AttributeType: "S"
      KeySchema:
        - AttributeName: id
          KeyType: HASH
      ProvisionedThroughput:
        ReadCapacityUnits: 1
        WriteCapacityUnits: 1

Now you can add these scripts to your package.json:

{
  "setup": "aws cloudformation create-stack --region us-west-2 --stack-name dev --template-body file://cloudformation.yml",
  "update": "aws cloudformation update-stack --region us-west-2 --stack-name dev --template-body file://cloudformation.yml",
  "destroy": "aws cloudformation delete-stack --region us-west-2 --stack-name dev"
}

Make sure you have setup aws-cli and have your credentials in ~/.aws. You can also use AWS environment variables. This will be the default AWS settings. If you need to configure it in code, in some other way, you can also run something like this:

const AWS = require('aws-sdk')
AWS.config.update({
  region: DYNAMO_REGION,
  accessKeyId: DYNAMO_ACCESS_KEY_ID,
  secretAccessKey: DYNAMO_SECRET_ACCESS_KEY
})

But it's much simpler to use env-vars or standard config, and not configure it at all.

code

After it's setup, it pretty simple to use:

const SimpleDynamo = require('@konsumer/simpledynamo')

// do any other config you need to, like above, but defaults should be fine, if everything is setup right.

// use in async functions for nice simple API
async function main() {
  const stuff = new SimpleDynamo()

  // names come from above cloudformation examples: table, stack
  await stuff.fromCloudFormation('MyStuff', 'dev')

  // scans are bad mmk?
  const things = await stuff.scan()
  console.log(things)
}
main()

There are some additional helpers and improvements to document client , like update is object-based, and everything returns a reasonable record of the change you made:

const updatedItem = await things.update({
  id: 'eWRhpRV' // REQUIRED: it uses this to find the record
  name: "Cool Guy"
})

For query and scan you can add all to the params, to have it loop over the returned pages:

const allTheThings = await things.scan({ all: true })

TODO

make keys work more dynamically
auto-generate query more like update
return LastEvaluatedKey in scan & query, so it can be looped over (for full scan)

Usage no npm install needed!