Dy-Alchemy

Simplification of Amazon DynamoDB interactions

Getting Started

npm i --save dy-alchemy

Model

This library comes with a basic object relational mapper (ORM) for interacting with Dynamodb objects in a consistent manner.

Initialization

const { Model } = require('dy-alchemy');

const model = new Model({
  modelName: 'model-name',
  tableName: 'dynamo-table-name',
  awsConfig: {},
  errorMap: {
    ItemNotFound: ({ id }) => { /* ... */ },
    ItemExists: ({ id }) => { /* ... */ }
  },
  callback: (/* {
    id, modelName, tableName, actionType
  } */) => { /* ... */ },
  primaryKeys: []
});
model.get(/* ... */);

Params

• modelName string: Name of model being accessed
• tableName string: Name of Dynamo Table associated with model
• schema { [string]: object }: Defined below
• awsConfig object: Optional hard coded config passed to aws-sdk
• errorMap object: Optional Key / Value map to allow custom errors
• callback function: Optional hook after successful actions, actionType may be one of ['get', 'create', 'update', 'delete']
• primaryKeys array<string>: Optional list of keys to automatically generate an id. If provided, keys are required on object created.

Schema

DataMapper style schema with support for defaultValue.

Example:

const schema = {
  id: {
    type: 'String',
    keyType: 'HASH'
  },
  isWatched: {
    type: 'Boolean',
    defaultValue: false
  }
};

Important: fields with defaultValue are assigned in application layer logic, and therefore should only be used in DynamoDB conditionals with caution.

Model Methods

All returning methods return unmarshalled dynamo data on success

• Get
• Create
• Update
• Delete

Get

Fetches model from Dynamo using Dynamodb::GetItem

modelName.get({ id, fields });

Params

• id string: Id of model to get
• fields array: Array of fields to request

Create

Creates object using Dynamodb::PutItem if not already exists

modelName.create({
  id, data, fields, conditions
});

Params

• id string: Id of model to create, must be unique. Must provide id or configure primaryKeys but not both.
• data object: Data to populate dynamo tuple. Important: id is injected into data
• fields array: Array of fields to request
• conditions array: Optional list of Amazon DynamoDB Expressions

Update

Do a partial update on object using Dynamodb::UpdateItem if object already exists

modelName.update({
  id, data, fields, conditions
});

Params

• id string: Id of model to update
• data object: Data to update
• fields array: Array of fields to request
• conditions array: Optional list of Amazon DynamoDB Expressions

Upsert

Upserts object using Dynamodb::PutItem

modelName.upsert({
  id, data, fields, conditions
});

Params

• id string: Id of model to upsert. Must provide id or configure primaryKeys but not both.
• data object: Data to populate dynamo tuple. Important: id is injected into data
• fields array: Array of fields to request
• conditions array: Optional list of Amazon DynamoDB Expressions

Delete

Delete an object using Dynamodb::DeleteItem

modelName.delete({ id, conditions });

Params

• id string: Id of model to delete
• conditions array: Optional list of Amazon DynamoDB Expressions

List

Query for a list of objects using Dynamodb::Query

modelName.list({ indexName, indexMap, fields });

Params

• indexName string: Name of index to query against
• indexMap { [string]: any }: Key / Value map of index attributes to match against
• fields array: Array of fields to request
• ascending boolean (true): Specify the order that data is returned (ascending/descending).
• limit number (20): Specify maximum number of items that are returned for a query.
• cursor string (null): Cursor to page through query results.

Lock Manager

Wrapper around dynamodb-lock-client with lazy initialization.

DynamoDb Table

Cloudformation information

DynamoLockTable:
  Type: AWS::DynamoDB::Table
  Properties:
    TableName: [[LOCK TABLE NAME HERE]]
    AttributeDefinitions:
      - AttributeName: id
        AttributeType: S
    KeySchema:
      - AttributeName: id
        KeyType: HASH
    ProvisionedThroughput:
      ReadCapacityUnits: 1
      WriteCapacityUnits: 1