dn

dynamo-node

DynamoDB mapper

Showing:

Popularity

Downloads/wk

82

GitHub Stars

14

Maintenance

Last Commit

3yrs ago

Contributors

1

Package

Dependencies

1

Size (min+gzip)

354.0KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

DynamoDB Mapper

Travis-ci

This DynamoDB Mapper for node.js aims to provide a simple and complete implementation to work with DynamoDB databases. You can easily select a table and start querying/writing data, from simple requests to conditional ones without prior knowledge.

Current features:

  • Expression Abstraction: Condition, Attribute values/names, Projections, Filters, KeyConditions
  • Conditional Requests: Add, update, delete and query conditionally
  • Attribute Functions: begins_with, contains, typeIs, in
  • Incrementing Decrementing
  • List, Set Append/Remove
  • Attribute Removal

Please note this repository is a work in progress. Contributions are welcome.

Requirements

Install package from npm or yarn

> npm install dynamo-node || yarn add dynamo-node

You can either set your AWS credentials as env variables or as a JSON file

// AWS credentials as JSON file
{
  "accessKeyId": "myKey",
  "secretAccessKey": "yourSecret",
}

Require module

const DynamoDB = require('dynamo-node')(region [, credit_path ]);
// e.g with json credentials
const DynamoDB = require('dynamo-node')('eu-central-1', './credits.json');
// e.g with env vars
process.env.DYNAMO_ENV = 'test';
const DynamoDB = require('dynamo-node')('eu-central-1');

Usage


Tables

Inits your table, or sets tablename for further creation

// "users" refers to the TableName we want to query from
const UserTable = DynamoDB.select('users');

Create

Attribute types association

SSSNNSBBSBOOLNULLLM
StringString SetNumberNumber SetBinaryBinary SetBooleanNullListMap
UserTable.createTable({
    KeySchema: [
        { AttributeName: "name", KeyType: "HASH"},  //Partition key
        { AttributeName: "uid", KeyType: "RANGE" }  //Sort key
    ],
    AttributeDefinitions: [
        { AttributeName: "uid", AttributeType: "N" },
        { AttributeName: "name", AttributeType: "S" }
    ],
    ProvisionedThroughput: {
        ReadCapacityUnits: 10,
        WriteCapacityUnits: 10
    }
});

Delete

UserTable.deleteTable();

Items

Add

UserTable.add({
  name: "abdu", // Primary Key
  participants: ["A", "B", "C", "D"],
  last: "D"
});

Get

UserTable.get({ name: "abdu" });

Update

// if "abdu" doesn't exist, it will be added (upsert)
UserTable.update({ name: "abdu" }, {
  friends: ["abdu", "chris"],
  points: 450,
});

// nested properties, assuming clothes is set and is of type Map
UserTable.update({ name: "abel" }, {
  'clothes.shirts': 10,
  'clothes.polos': 3
});

UserTable.update(key, attributes, 'OLD'); // returns item's pre-update state
UserTable.update(key, attributes, 'UPD'); // default, returns only updated attributes
UserTable.update(key, attributes, 'NEW'); // returns item's post-update state

Delete

UserTable.delete({ name: "abdu" });

Query

UserTable.query('name', '=', 'abdu');

// Using global secondary index
UserTable.useIndex('age-index').query('age', '=', 5);

Scan

Returns all items from table

// a very expensive task !
UserTable.scan();

Conditional Queries

Check if attribute exists

const newUser = { name: "abel", age: 34 };

UserTable.exists('name').add(newUser);
UserTable.exists( ['name', 'age'] ).add(newUser);

UserTable.notExists('name').add(newUser);
UserTable.notExists( ['name', 'age'] ).add(newUser);

Attribute comparison

const hector = { name: "hector" };

UserTable.add({ name: "hector", last_connection: 50, age: 10, friends: { nice: 0, bad: 10 } });

// Deletes it
UserTable
  .if('last_connection', '>', 30 )
  .if('last_connection', '<', 100)
  .if('age', '<>', 90) // different than
  .delete(hector);

// Updates it
UserTable
  .if('last_connection', '=', 50)
  .if('friends.bad', '>=', 0)
  .if('age', '<=', 10)
  .update(hector, { candy: 1 });

Attribute functions

beginsWith

  • matches a substring with the beggining of an attribute

// Updates user if nickname attribute begins with a 'm'
UserTable.where('nickname', 'beginsWith', 'm').update(momo, { nickname: "lol" });

contains

  • String: matches substring
  • List: matches element
// Updates user if nickname contains 'lol'
UserTable.where('nickname', 'contains', 'lol').update(momo, { fun: true });

// Updates user if 'homer' is in parents list
UserTable.where('parents', 'contains', 'homer').update(momo, { cool: true });

typeIs

  • matches attribute type

Please refer to "Attribute types association" section for the list of type attributes

// Updates user momo if his friends attribute is N (number)
UserTable.where('friends', 'typeIs', 'N').update(momo, { friends: 0 });

inList

  • matches attribute with provided array
// Gets user named 'abel' if he has a friend named 'abdu' or 'chris'
UserTable.inList('friends', [ 'abdu', 'chris' ]).query('name', '=', 'abel');

Attribute manipulation

Increment/Decrement attribute

const burger = { name: 'burger' };

FoodTable.add({ name: 'burger', sold: 0, sellers: [5,8], ingredients: { cheese: 2 } });

FoodTable.increment('sold', 10).update(burger); // { sold: 10 }
FoodTable.decrement('sold', 1).update(burger); // { sold: 9 }

FoodTable.increment('ingredients.cheese', 4).update(burger);
FoodTable.decrement('ingredients.cheese', 1).update(burger);

Remove attribute

FoodTable.removeAttribute(burger, [ 'ingredients.cheese' ]);
FoodTable.removeAttribute(burger, [ 'sold', 'ingredients' ]);
// burger is now { name: burger, sellers: [5,8] }

Add to/Remove from list attribute


// The provided array of VALUES will be appended to the attribute
FoodTable.addToList({ sellers: [9] }).update(burger) // { ..., sellers: [5, 8, 9] }

// This time we pass an array of INDEXES from which we want to delete
FoodTable.removeFromList({ sellers: [1] }).update(burger) // { ..., sellers: [5, 9] }

Batch Operations

// No need to provide a table name this time
const Batch = DynamoDB.select();
const batchGet = {
    'table1': {
        // 'name' is the primary key of table1
        Keys: { 'name': ['myItem', 'myItem2', 'myItem3', 'myItem4'] }
    },
    'table2': {
        // 'pid' is the primary key of table2
        Keys: { 'pid': [1101, 1110, 1010] }
    }
};
Batch.batchGet(batchGet);
const batchPut = {
    'table1': [ { name: 'a'}, { name: 'b' }, { name: 'c' }, { name: 'd' } ],
    'table2': [ { pid: 1 }, { pid: 2 }, { pid: 3 }, { pid: 4 } ],
};

Batch.batchPut(batchPut);
const batchDelete = {
    'table1': [ { name: 'b' }, { name: 'c' } ],
    'table2': [ { pid: 3 }, { pid: 4 } ],
};

Batch.batchDelete(batchDelete);

Projections

You can select which attributes you want back from the result when performing get, query or scan operations

Table.add({ id: 1, status: 2, a, b, c, d });
Table.add({ id: 2, status: 2, e, f, g, h });

// returns { Items: [{ id: 1 }], Count: 1, ... }
Table.project('id').query('id', '=', 1);

// returns { Items: [{ id: 1, status: 2 }, { id: 2, status: 2 }], ... }
Table.project(['id', 'status']).scan();

// returns { status: 2 }
Table.project(['status']).get({ id: 1 });

Return values

All methods return promises

// outputs "Abdu"
UserTable.get({ name: "abdu" })
    .then(item => console.log(item.name));

// outputs "26"
UserTable.update({ name: "abdu" }, { age: "26" })
    .then(item => console.log(item.age));

// both outputs "{}"
UserTable.delete({ name: "abdu" })
    .then(item => console.log(item));

UserTable.add({ name: "Chris", age: "65" })
    .then(item => console.log(item));


Test & Development

Tests are located in the ./tests folder

Run tests

> npm run test || yarn test

Environment

You need to set up a specific envvar to start development with dynamo-node and a local dynamo db

process.env.DYNAMO_ENV = 'test';

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial