dynogels

Dynogels is a [DynamoDB][5] data mapper for [node.js][1]. This project has been forked from Vogels and republished to npm under a different name.

Features

Simplified data modeling and mapping to DynamoDB types
Advanced chainable apis for query and scan operations
Data validation
Autogenerating UUIDs
Global Secondary Indexes
Local Secondary Indexes
Parallel Scans

Installation

npm install dynogels

Getting Started

First, you need to configure the [AWS SDK][2] with your credentials.

var dynogels = require('dynogels');
dynogels.AWS.config.loadFromPath('credentials.json');

When running on EC2 it's recommended to leverage EC2 IAM roles. If you have configured your instance to use IAM roles, Vogels will automatically select these credentials for use in your application, and you do not need to manually provide credentials in any other format.

var dynogels = require('dynogels');
dynogels.AWS.config.update({region: "REGION"}); // region must be set

You can also directly pass in your access key id, secret and region.

It's recommended not to hard-code credentials inside an application. Use this method only for small personal scripts or for testing purposes.

var dynogels = require('dynogels');
dynogels.AWS.config.update({accessKeyId: 'AKID', secretAccessKey: 'SECRET', region: "REGION"});

Currently the following region codes are available in Amazon:

| Code | Name | | -------------- | ------------------------ | | ap-northeast-1 | Asia Pacific (Tokyo) | | ap-southeast-1 | Asia Pacific (Singapore) | | ap-southeast-2 | Asia Pacific (Sydney) | | eu-central-1 | EU (Frankfurt) | | eu-west-1 | EU (Ireland) | | sa-east-1 | South America (Sao Paulo)| | us-east-1 | US East (N. Virginia) | | us-west-1 | US West (N. California) | | us-west-2 | US West (Oregon) |

Define a Model

Models are defined through the toplevel define method.

var Account = dynogels.define('Account', {
  hashKey : 'email',

  // add the timestamp attributes (updatedAt, createdAt)
  timestamps : true,

  schema : {
    email   : Joi.string().email(),
    name    : Joi.string(),
    age     : Joi.number(),
    roles   : dynogels.types.stringSet(),
    settings : {
      nickname      : Joi.string(),
      acceptedTerms : Joi.boolean().default(false)
    }
  }
});

Models can also be defined with hash and range keys.

var BlogPost = dynogels.define('BlogPost', {
  hashKey : 'email',
  rangeKey : ‘title’,
  schema : {
    email   : Joi.string().email(),
    title   : Joi.string(),
    content : Joi.binary(),
    tags   : dynogels.types.stringSet(),
  }
});

You can pass through validation options to Joi like so:

var BlogPost = dynogels.define('BlogPost', {
  hashKey : 'email',
  rangeKey : 'title',
  schema : {
    email   : Joi.string().email(),
    title   : Joi.string()
  },
  validation: {
    // allow properties not defined in the schema
    allowUnknown: true
  }
});

Create Tables for all defined models

dynogels.createTables(function(err) {
  if (err) {
    console.log('Error creating tables: ', err);
  } else {
    console.log('Tables have been created');
  }
});

When creating tables you can pass specific throughput settings or stream specification for any defined models.

dynogels.createTables({
  'BlogPost': {readCapacity: 5, writeCapacity: 10},
  'Account': {
    readCapacity: 20,
    writeCapacity: 4,
    streamSpecification: {
      streamEnabled: true,
      streamViewType: 'NEW_IMAGE'
    }
  }
}, function(err) {
  if (err) {
    console.log('Error creating tables: ', err);
  } else {
    console.log('Tables has been created');
  }
});

You can also pass operational options using the $dynogels key:

pollingInterval: When creating a table, Dynogels must poll the DynamoDB server to detect when table creation has completed. This option specifies the minimum poll interval, in milliseconds. (Default: 1000)

dynogels.createTables({
  $dynogels: { pollingInterval: 100 }
}, function(err) {
  if (err) {
    console.log('Error creating tables: ', err);
  } else {
    console.log('Tables has been created');
  }
});

Delete Table

BlogPost.deleteTable(function(err) {
  if (err) {
    console.log('Error deleting table: ', err);
  } else {
    console.log('Table has been deleted');
  }
});

Get Dynamo API Parameters

You can get the raw parameters needed for the DynamoDB CreateTable API:

var parameters = BlogPost.dynamoCreateTableParams();
var dynamodb = new AWS.DynamoDB();
dynamodb.createTable(params, (err)=>{ ... });

Schema Types

Vogels provides the following schema types:

String
Number
StringSet
NumberSet
Boolean
Date
UUID
TimeUUID

UUID

UUIDs can be declared for any attributes, including hash and range keys. By Default, the uuid will be automatically generated when attempting to create the model in DynamoDB.

var Tweet = dynogels.define('Tweet', {
  hashKey : 'TweetID',
  timestamps : true,
  schema : {
    TweetID : dynogels.types.uuid(),
    content : Joi.string(),
  }
});

Data Validation

Dynogels automatically validates the model against the schema before attempting to save it, but you can also call the validate method to validate an object before saving it. This can be helpful for a handler to validate input.

var Tweet = dynogels.define('Tweet', {
  hashKey : 'TweetID',
  timestamps : true,
  schema : {
    TweetID : dynogels.types.uuid(),
    content : Joi.string(),
  }
});

const tweet = new Tweet({ content: 123 })
const fail_result = Tweet.validate(tweet)
console.log(fail_result.error.name) // ValidationError

tweet.set('content', 'This is the content')
const pass_result = Tweet.validate(tweet)
console.log(pass_result.error) // null

Configuration

You can configure dynogels to automatically add createdAt and updatedAt timestamp attributes when saving and updating a model. updatedAt will only be set when updating a record and will not be set on initial creation of the model.

var Account = dynogels.define('Account', {
  hashKey : 'email',

  // add the timestamp attributes (updatedAt, createdAt)
  timestamps : true,

  schema : {
    email : Joi.string().email(),
  }
});

If you want dynogels to handle timestamps, but only want some of them, or want your timestamps to be called something else, you can override each attribute individually:

var Account = dynogels.define('Account', {
  hashKey : 'email',

  // enable timestamps support
  timestamps : true,

  // I don't want createdAt
  createdAt: false,

  // I want updatedAt to actually be called updateTimestamp
  updatedAt: 'updateTimestamp'

  schema : {
    email : Joi.string().email(),
  }
});

You can override the table name the model will use.

var Event = dynogels.define('Event', {
  hashKey : 'name',
  schema : {
    name : Joi.string(),
    total : Joi.number()
  },

  tableName: 'deviceEvents'
});

if you set the tableName to a function, dynogels will use the result of the function as the active table to use. Useful for storing time series data.

var Event = dynogels.define('Event', {
  hashKey : 'name',
  schema : {
    name : Joi.string(),
    total : Joi.number()
  },

  // store monthly event data
  tableName: function () {
    var d = new Date();
    return ['events', d.getFullYear(), d.getMonth() + 1].join('_');
  }
});

After you've defined your model you can configure the table name to use. By default, the table name used will be the lowercased and pluralized version of the name you provided when defining the model.

Account.config({tableName: 'AccountsTable'});

You can also pass in a custom instance of the aws-sdk DynamoDB client

var dynamodb = new AWS.DynamoDB();
Account.config({dynamodb: dynamodb});

// or globally use custom DynamoDB instance
// all defined models will now use this driver
dynogels.dynamoDriver(dynamodb);

Saving Models to DynamoDB

With your models defined, we can start saving them to DynamoDB.

Account.create({email: 'foo@example.com', name: 'Foo Bar', age: 21}, function (err, acc) {
  console.log('created account in DynamoDB', acc.get('email'));
});

You can also first instantiate a model and then save it.

var acc = new Account({email: 'test@example.com', name: 'Test Example'});
acc.save(function (err) {
  console.log('created account in DynamoDB', acc.get('email'));
});

Saving models that require range and hashkeys are identical to ones with only hashkeys.

BlogPost.create({
  email: 'werner@example.com',
  title: 'Expanding the Cloud',
  content: 'Today, we are excited to announce the limited preview...'
  }, function (err, post) {
    console.log('created blog post', post.get('title'));
  });

Pass an array of items and they will be saved in parallel to DynamoDB.

var item1 = {email: 'foo1@example.c

Dynogels

Install / Use

README