Fireball

A lightweight model wrapper for DynamoDB with syntax that sucks less.

Getting Started

Install Fireball:

npm install fireball-db --save

Overview

Fireball, in its simplest form, is a wrapper around the AWS SDK DynamoDB Document Client. The primary purpose of this library is to create model object to reflect a single DynamoDB table. The model object provides many useful additions such as unique ID generation, cleaner parameter syntax and promise based functions.

Usage

Import fireball

fireball = require 'fireball-db'

Creating a model object

The model object is a wrapper around the DocumentClient that simplify the parameter syntax to most functions and will automatically add the TableName parameter as needed.

User = fireball.model 'SomeDynamoTable'

Creating a model with custom extensions

User = fireball.model 'SomeDynamoTable',

  find_by_email: (email) ->
    ...

User.find_by_email('[email protected]').then (users) ->
  ...

Promises

All functions of the model object return Promises.

Information on Promises

Querying a table

User = ...
User.query(
  expression: '#field = :value'
  names: {'#field': 'name'}
  values: {':value': 'fred'}
).then (users) ->
  ...

Querying a table with specific index

User = ...
User.query(
  expression: '#field = :value'
  names: {'#field': 'name'}
  values: {':value': 'fred'}
  IndexName: 'secondary_index'
).then (users) ->
  ...

Scanning a table

User = ...
User.scan(
  expression: '#field = :value'
  names: {'#field': 'name'}
  values: {':value': 'fred'}
).then (users) ->
  ...

Getting an item

User = ...
key = email: '[email protected]'
User.get(key).then (user) ->
  ...

Getting an item by identifier

Wrapper around get that will use the managed identifier key.

User = ...
User.for_id('12312312321').then (user) ->
  ...

Putting an item

User = ...
User.put(first: 'John', last: 'Doe', email: '[email protected]').then (user) ->
  ...

Putting an item with condition expression

User = ...
user_data = first: 'John', last: 'Doe', email: '[email protected]'
condition = expression: '#field = :value', names: {'#field': 'name'}, values: {':value': 'fred'}

User.put(user_data, condition).then (user) ->
  ...

Inserting an item

Wrapper around put that will automatically add an identifier field and ensure uniqueness.

User = ...
User.insert(first: 'John', last: 'Doe', email: '[email protected]').then (user) ->
  ...

Updating an item

User = ...
key = email: '[email protected]'
User.insert(key, first: 'John', last: 'Doe').then (user) ->
  ...

Deleting an item by key

User = ...
key = email: '[email protected]'
User.delete(key).then (user) ->
  ...

Deleting an item

User = ...
user = email: '[email protected]', name: 'someone', ...
User.delete(item).then (user) ->
  ...

Get all items for keys (batchGet)

User = ...
keys = [
  {email: '[email protected]'}
  {email: '[email protected]'}
  {email: '[email protected]'}
]
User.for_keys(keys).then (users) ->
  ...

Get all items for identifiers

User = ...
ids = [
  '12121'
  '12122'
  '12123'
]
User.for_ids(ids).then (users) ->
  ...

Putting multiple items (batchWrite)

User = ...
items = [
  {first: 'John', last: 'Doe', email: '[email protected]'}
  {first: 'Jane', last: 'Doe', email: '[email protected]'}
  {first: 'Sally', last: 'Doe', email: '[email protected]'}
]
User.put_all(items).then (users) ->
  ...

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.