Dynamically generate a DynamoDB data access layer from an .arc file


2013.0.52 years ago4 years agoMinified + gzip package size for @architect/data in KB



Build Status

Generate a DynamoDB data access layer from an .arc file. Automatically disambiguates testing (in memory) from deployment staging and production tables


An .arc file can define @tables and @indexes. Generated tables follow the format:

  • appname-staging-tablename
  • appname-production-tablename

For example, given the following .arc file:


  pplID *String

  pplID *String
  catID **String

  email *String

  name *String

If you've setup your package.json per the quickstart then running npm run create creates the following tables:

  • testapp-staging-ppl
  • testapp-production-ppl
  • testapp-staging-cats
  • testapp-production-cats

And running npm start will kick up a local Dynalite instance with these tables prepopulated. From here its up to you to connect to the database and interact with the tables on your local machine.

Connecting to DynamoDB

var db = require('@architect/data/db')

db.listTables({}, console.log)
// logs tables

Read the Testing Guide to learn about working with the local Dynalite instance in your tests

This same code will work in the staging and production Lambdas without modification.

Full documentation of the AWS SDK DynamoDB client can be found here.

Working with DocumentClient

The lower level Dynamo client is good for precise database control. Use it for listing, creating, modifying and destroying tables. For working with records DocumentClient provides a nicer interface.

var doc = require('@architect/data/doc')

  TableName: 'testapp-staging-notes', 
  Item: {
    noteID: 1, 
    body: 'hi'
}, console.log)
// record added to db and logs {noteID:1, body:'hi'}

doc.get({noteID:1}, console.log)
// logs {noteID:1, body:'hi'}

DocumentClient has comprehensive support for querying and mutating data.Full documentation for DocumentClient can be found here.

Convenience with @architect/data

This library bundles the db and doc connection scripts above. However it does require hard coding TableName which might not be desirable. So this module exports a single function for generating a static data access layer client that automatically resolves TableName based on NODE_ENV.

The client is a plain javscript object keyed by table name with methods from DyanamoDB.DocumentClient:

  • put
  • get
  • delete
  • query
  • scan
  • update

Example Usage


  accountID *String

  accountID *String
  postID **String

First we generate a client:

// reads node_modules/@architect/shared/.arc 
var data = require('@architect/data')

The app variable above looks like this:

  account: {put, get, delete, query, scan, update},
  posts: {put, get, delete, query, scan, update}

You can immediately start using the generated methods:

var data = require('@architect/data')

// create a post
await app.posts.put({
  accountID: 'fake-id',
  postID: 'fake-post-id',
  title: 'neato'

// read it back
let post = await app.posts.get({postID: 'fake-post-id'})

// update the record
await app.posts.update({
  Key: { 
    postID: 'fake-post-id' 
  UpdateExpression: 'set #title = :title', 
  ExpressionAttributeNames: {
    '#title' : 'title'
  ExpressionAttributeValues: {
    ':title' : 'super neato',

// destroy it
await app.posts.destroy({
  postID: 'fake-post-id'

Check the tests for a detailed example!

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.