├── .gitignore ├── index.js ├── .jshintrc ├── test ├── .jshintrc ├── test-query.js ├── test-schema.js └── test-model.js ├── HISTORY.md ├── package.json ├── LICENSE ├── lib ├── query.js ├── schema.js └── model.js └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | temp 3 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | exports.Schema = require('./lib/schema'); 2 | exports.Model = require('./lib/model'); 3 | exports.Query = require('./lib/query'); 4 | -------------------------------------------------------------------------------- /.jshintrc: -------------------------------------------------------------------------------- 1 | { 2 | "predef": [], 3 | "browser": false, 4 | "node": true, 5 | "curly": false, 6 | "strict": false, 7 | "expr": true, 8 | "unused": "vars" 9 | } 10 | -------------------------------------------------------------------------------- /test/.jshintrc: -------------------------------------------------------------------------------- 1 | { 2 | "predef": ["describe", "it"], 3 | "browser": false, 4 | "node": true, 5 | "curly": false, 6 | "strict": false, 7 | "expr": true, 8 | "unused": "vars" 9 | } 10 | -------------------------------------------------------------------------------- /HISTORY.md: -------------------------------------------------------------------------------- 1 | 0.0.2 / October 24 2013 2 | ======================= 3 | 4 | * Model: added automatic table creation 5 | * Model: putItem can now return a mapped item 6 | 7 | 0.0.1 / October 23 2013 8 | ======================= 9 | 10 | * initial release 11 | * incomplete features 12 | * incomplete documentation 13 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "dynamodb-model", 3 | "version": "0.0.2", 4 | "author": { 5 | "name": "Nicolas Mercier", 6 | "email": "nicolas@extrabacon.net" 7 | }, 8 | "description": "Elegant DynamoDB object modeling influenced from MongoDB and the Mongoose API", 9 | "keywords": [ 10 | "dynamo", 11 | "dynamodb", 12 | "aws", 13 | "orm", 14 | "mapping" 15 | ], 16 | "dependencies": { 17 | "async": "*", 18 | "aws-sdk": "*" 19 | }, 20 | "devDependencies": { 21 | "mocha": "*", 22 | "chai": "*" 23 | }, 24 | "scripts": { 25 | "test": "mocha -R spec" 26 | }, 27 | "repository": { 28 | "type": "git", 29 | "url": "http://github.com/extrabacon/dynamodb-model" 30 | }, 31 | "homepage": "http://github.com/extrabacon/dynamodb-model", 32 | "bugs": "http://github.com/extrabacon/dynamodb-model/issues", 33 | "engines": { 34 | "node": ">=0.10" 35 | } 36 | } 37 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2013, Nicolas Mercier 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /lib/query.js: -------------------------------------------------------------------------------- 1 | var DynamoQuery = function (mode, schema, model, params) { 2 | 3 | var lastEvaluatedKey; 4 | var execute = model.dynamodb[mode].bind(model.dynamodb); 5 | this.hasMoreData = true; 6 | 7 | DynamoQuery.prototype.select = function() { 8 | if (arguments.length > 0) { 9 | params.AttributesToGet = Array.prototype.slice.call(arguments, 0); 10 | params.Select = 'SPECIFIC_ATTRIBUTES'; 11 | } else { 12 | params.Select = 'ALL_ATTRIBUTES'; 13 | } 14 | return this; 15 | }; 16 | 17 | DynamoQuery.prototype.returnConsumedCapacity = function(enabled) { 18 | if (typeof enabled === 'undefined') enabled = true; 19 | params.ReturnConsumedCapacity = enabled; 20 | return this; 21 | }; 22 | 23 | DynamoQuery.prototype.limit = function(count) { 24 | params.Limit = count; 25 | return this; 26 | }; 27 | 28 | DynamoQuery.prototype.count = function(callback) { 29 | params.Select = 'COUNT'; 30 | if (callback) return this.exec(callback); 31 | return this; 32 | }; 33 | 34 | DynamoQuery.prototype.next = function(callback) { 35 | if (this.hasMoreData) { 36 | params.ExclusiveStartKey = lastEvaluatedKey; 37 | } else { 38 | throw new Error('there is no more data to retrieve, last execution did not yield a LastEvaluatedKey'); 39 | } 40 | if (callback) return this.exec(callback); 41 | return this; 42 | }; 43 | 44 | DynamoQuery.prototype.exec = function(callback) { 45 | if (!callback) throw new Error('callback required'); 46 | var query = this; 47 | model.ensureActiveTable(function (err) { 48 | if (err) return callback(err); 49 | execute(params, function (err, response) { 50 | if (err) return callback(err); 51 | var items = response.Items.map(schema.mapFromDb.bind(schema)); 52 | lastEvaluatedKey = response.LastEvaluatedKey; 53 | query.hasMoreData = lastEvaluatedKey !== null; 54 | callback(null, items, response); 55 | }); 56 | }); 57 | return this; 58 | }; 59 | 60 | if (mode === 'scan') { 61 | DynamoQuery.prototype.scan = function(callback) { 62 | throw new Error('not yet supported'); 63 | }; 64 | } 65 | 66 | }; 67 | 68 | module.exports = DynamoQuery; 69 | -------------------------------------------------------------------------------- /test/test-query.js: -------------------------------------------------------------------------------- 1 | var DynamoSchema = require('..').Schema; 2 | var DynamoModel = require('..').Model; 3 | var chai = require('chai'); 4 | var expect = chai.expect; 5 | 6 | describe('DynamoQuery', function () { 7 | 8 | // a sample schema for all our tests 9 | var schema = new DynamoSchema({ 10 | id: { 11 | type: String, 12 | key: true 13 | }, 14 | range: { 15 | type: Number, 16 | key: 'range' 17 | }, 18 | attribute1: String, 19 | attribute2: Number 20 | }); 21 | 22 | it('should execute with "exec"', function () { 23 | var model = new DynamoModel('my-table', schema); 24 | model.dynamodb.query = function (params, callback) { 25 | expect(params).to.have.property('TableName', 'my-table'); 26 | expect(params).to.have.property('KeyConditions'); 27 | }; 28 | var query = model.query({ id: 'text' }); 29 | query.exec(); 30 | }); 31 | 32 | it('should allow the selection of fields to return with "select"', function () { 33 | var model = new DynamoModel('my-table', schema); 34 | model.dynamodb.query = function (params, callback) { 35 | expect(params).to.have.property('Select', 'SPECIFIC_ATTRIBUTES'); 36 | expect(params).to.have.property('AttributesToGet'); 37 | expect(params.AttributesToGet).to.have.length(3); 38 | expect(params.AttributesToGet).to.contain('field1'); 39 | expect(params.AttributesToGet).to.contain('field2'); 40 | expect(params.AttributesToGet).to.contain('field3'); 41 | }; 42 | var query = model.query({ id: 'text' }); 43 | query.select('field1', 'field2', 'field3').exec(); 44 | }); 45 | 46 | it('should return the consumed capacity with "returnConsumedCapacity"', function () { 47 | var model = new DynamoModel('my-table', schema); 48 | model.dynamodb.query = function (params, callback) { 49 | expect(params).to.have.property('ReturnConsumedCapacity', true); 50 | }; 51 | var query = model.query({ id: 'text' }); 52 | query.returnConsumedCapacity().exec(); 53 | }); 54 | 55 | it('should limit the number of items with "limit"', function () { 56 | var model = new DynamoModel('my-table', schema); 57 | model.dynamodb.query = function (params, callback) { 58 | expect(params).to.have.property('Limit', 10); 59 | }; 60 | var query = model.query({ id: 'text' }); 61 | query.limit(10).exec(); 62 | }); 63 | 64 | it('should count number of items with "count"', function () { 65 | var model = new DynamoModel('my-table', schema); 66 | model.dynamodb.query = function (params, callback) { 67 | expect(params).to.have.property('Select', 'COUNT'); 68 | }; 69 | var query = model.query({ id: 'text' }); 70 | query.count().exec(); 71 | }); 72 | 73 | it('should allow paging with "next"', function () { 74 | var model = new DynamoModel('my-table', schema); 75 | var count = 0; 76 | model.dynamodb.query = function (params, callback) { 77 | // simulate 3 pages of data 78 | if (++count < 3) { 79 | callback(null, { Items: [], LastEvaluatedKey: 'last_key' }); 80 | } else { 81 | callback(null, { Items: [], LastEvaluatedKey: null }); 82 | } 83 | }; 84 | var query = model.query({ id: 'text' }); 85 | expect(query.hasMoreData).to.be.true; 86 | query.exec(function (err, items, response) { 87 | // got page 1 88 | expect(query.hasMoreData).to.be.true; 89 | query.next(function (err, items, response) { 90 | // got page 2 91 | expect(query.hasMoreData).to.be.true; 92 | query.next(function (err, items, response) { 93 | // got page 3 94 | expect(query.hasMoreData).to.be.false; 95 | expect(function () { query.next(function () {}); }).to.throw(/no more data to retrieve/); 96 | }); 97 | }); 98 | }); 99 | }); 100 | 101 | }); 102 | -------------------------------------------------------------------------------- /lib/schema.js: -------------------------------------------------------------------------------- 1 | var DynamoSchema = function (schema) { 2 | 3 | this.keys = {}; 4 | this.indexes = {}; 5 | this.attributes = {}; 6 | this.mappers = {}; 7 | this.defaults = {}; 8 | 9 | for (var key in schema) { 10 | var fieldType = schema[key]; 11 | this.mappers[key] = resolve(key, fieldType) || DynamoSchema.mappers.default; 12 | this.attributes[key] = this.mappers[key].dynamoDbType || 'S'; 13 | 14 | if (fieldType.key) { 15 | if (fieldType.key === true || fieldType.key === 'hash') { 16 | this.keys[key] = 'HASH'; 17 | } else if (fieldType.key === 'range') { 18 | this.keys[key] = 'RANGE'; 19 | } 20 | } else if (fieldType.index) { 21 | // TODO: indexes 22 | } 23 | 24 | if (fieldType.default) { 25 | this.defaults[key] = fieldType.default; 26 | } 27 | } 28 | 29 | function resolve(fieldName, fieldType) { 30 | if (!Array.isArray(fieldType) && typeof fieldType === 'object') { 31 | if (Object.keys(fieldType).length === 0) { 32 | // empty object "{}", suppose a JSON type 33 | fieldType = 'JSON'; 34 | } else { 35 | if (fieldType.mapFromDb && fieldType.mapToDb) { 36 | return fieldType; 37 | } else if (fieldType.type) { 38 | fieldType = fieldType.type; 39 | } else { 40 | throw new Error('DynamoSchema is unable to map field "' + fieldName + '": missing data type'); 41 | } 42 | } 43 | } 44 | 45 | if (Array.isArray(fieldType) && fieldType.length > 0) { 46 | fieldType = fieldType[0]; 47 | return DynamoSchema.mappers.Array[fieldType.name]; 48 | } else { 49 | if (typeof fieldType === 'function') { 50 | fieldType = fieldType.name; 51 | } 52 | return DynamoSchema.mappers[fieldType]; 53 | } 54 | 55 | throw new Error('DynamoSchema is unable to map field "' + fieldName + '": no mapper can handle this data type'); 56 | } 57 | 58 | DynamoSchema.prototype.mapFromDb = function(doc) { 59 | if (!doc) return null; 60 | var mappedDoc = {}; 61 | for (var key in this.mappers) { 62 | var mapper = this.mappers[key]; 63 | if (mapper) { 64 | var val = doc[key]; 65 | if (val) { 66 | mappedDoc[key] = mapper.mapFromDb(val); 67 | } else if (this.defaults.hasOwnProperty(key)) { 68 | if (typeof this.defaults[key] === 'function') { 69 | mappedDoc[key] = this.defaults[key].call(this, doc); 70 | } else { 71 | mappedDoc[key] = this.defaults[key]; 72 | } 73 | 74 | } else { 75 | mappedDoc[key] = null; 76 | } 77 | } 78 | } 79 | return mappedDoc; 80 | }; 81 | 82 | DynamoSchema.prototype.mapToDb = function(doc) { 83 | if (!doc) return null; 84 | var mappedDoc = {}; 85 | for (var key in doc) { 86 | if (this.mappers.hasOwnProperty(key)) { 87 | mappedDoc[key] = this.mappers[key].mapToDb(doc[key]); 88 | } 89 | } 90 | return mappedDoc; 91 | }; 92 | 93 | }; 94 | 95 | DynamoSchema.mappers = { 96 | default: { 97 | dynamoDbType: 'S', 98 | mapFromDb: function (val) { 99 | return val.S || val.N || val.B || val.SS || val.NS || val.BS; 100 | }, 101 | mapToDb: function (val) { 102 | return { S: String(val) }; 103 | } 104 | }, 105 | 'String': { 106 | dynamoDbType: 'S', 107 | mapFromDb: function (val) { 108 | return val.S; 109 | }, 110 | mapToDb: function (val) { 111 | return { S: String(val) }; 112 | } 113 | }, 114 | 'Number': { 115 | dynamoDbType: 'N', 116 | mapFromDb: function (val) { 117 | return +val.N; 118 | }, 119 | mapToDb: function (val) { 120 | return { N: String(val) }; 121 | } 122 | }, 123 | 'Buffer': { 124 | dynamoDbType: 'B', 125 | mapFromDb: function (value) { 126 | return new Buffer(String(value.B), 'base64'); 127 | }, 128 | mapToDb: function (value) { 129 | return { B: value.toString('base64') }; 130 | } 131 | }, 132 | 'Boolean': { 133 | dynamoDbType: 'S', 134 | mapFromDb: function (value) { 135 | return value.S === 'Y' ? true : value.S === 'N' ? false : undefined; 136 | }, 137 | mapToDb: function (value) { 138 | return { S: value ? 'Y' : 'N' }; 139 | } 140 | }, 141 | 'Date': { 142 | dynamoDbType: 'N', 143 | mapFromDb: function (value) { 144 | return new Date(Number(value.N)); 145 | }, 146 | mapToDb: function (value) { 147 | return { N: String(value.getTime()) }; 148 | } 149 | }, 150 | 'JSON': { 151 | dynamoDbType: 'S', 152 | mapFromDb: function (value) { 153 | return JSON.parse(value.S); 154 | }, 155 | mapToDb: function (value) { 156 | return { S: JSON.stringify(value) }; 157 | } 158 | }, 159 | 'Array': { 160 | 'String': { 161 | dynamoDbType: 'SS', 162 | mapFromDb: function (value) { 163 | return value.SS; 164 | }, 165 | mapToDb: function (value) { 166 | return { SS: value }; 167 | } 168 | }, 169 | 'Number': { 170 | dynamoDbType: 'NS', 171 | mapFromDb: function (value) { 172 | return value.NS.map(Number); 173 | }, 174 | mapToDb: function (value) { 175 | return { NS: value.map(String) }; 176 | } 177 | }, 178 | 'Buffer': { 179 | dynamoDbType: 'BS', 180 | mapFromDb: function (value) { 181 | return value.BS.map(function (str) { 182 | return new Buffer(str, 'base64'); 183 | }); 184 | }, 185 | mapToDb: function (value) { 186 | return { BS: value.map(function (buf) { 187 | return buf.toString('base64'); 188 | }) }; 189 | } 190 | } 191 | } 192 | }; 193 | 194 | module.exports = DynamoSchema; 195 | -------------------------------------------------------------------------------- /test/test-schema.js: -------------------------------------------------------------------------------- 1 | var DynamoSchema = require('..').Schema; 2 | var chai = require('chai'); 3 | var expect = chai.expect; 4 | 5 | describe('DynamoSchema', function () { 6 | 7 | it('should map simple schemas', function () { 8 | var schema = new DynamoSchema({ 9 | id: String, 10 | value: Number 11 | }); 12 | expect(Object.keys(schema.attributes)).to.have.length(2); 13 | expect(schema.mappers.id.dynamoDbType).to.equal('S'); 14 | expect(schema.mappers.value.dynamoDbType).to.equal('N'); 15 | }); 16 | 17 | it('should map strings', function () { 18 | var schema = new DynamoSchema({ text: String }); 19 | expect(schema.mappers.text).to.equal(DynamoSchema.mappers.String); 20 | 21 | var doc = { text: 'hello' }; 22 | var outboundDoc = schema.mapToDb(doc); 23 | expect(outboundDoc).to.have.property('text'); 24 | expect(outboundDoc.text).to.have.property('S', 'hello'); 25 | 26 | var inboundDoc = schema.mapFromDb(outboundDoc); 27 | expect(inboundDoc).to.have.property('text', 'hello'); 28 | }); 29 | 30 | it('should map numbers', function () { 31 | var schema = new DynamoSchema({ number: Number }); 32 | expect(schema.mappers.number).to.equal(DynamoSchema.mappers.Number); 33 | 34 | var doc = { number: 123.45 }; 35 | var outboundDoc = schema.mapToDb(doc); 36 | expect(outboundDoc).to.have.property('number'); 37 | expect(outboundDoc.number).to.have.property('N', '123.45'); 38 | 39 | var inboundDoc = schema.mapFromDb(outboundDoc); 40 | expect(inboundDoc).to.have.property('number', 123.45); 41 | }); 42 | 43 | it('should map booleans', function () { 44 | var schema = new DynamoSchema({ toggleOn: Boolean, toggleOff: Boolean }); 45 | expect(schema.mappers.toggleOn).to.equal(DynamoSchema.mappers.Boolean); 46 | expect(schema.mappers.toggleOff).to.equal(DynamoSchema.mappers.Boolean); 47 | 48 | var doc = { toggleOn: true, toggleOff: false }; 49 | var outboundDoc = schema.mapToDb(doc); 50 | expect(outboundDoc).to.have.property('toggleOn'); 51 | expect(outboundDoc).to.have.property('toggleOff'); 52 | expect(outboundDoc.toggleOn).to.have.property('S', 'Y'); 53 | expect(outboundDoc.toggleOff).to.have.property('S', 'N'); 54 | 55 | var inboundDoc = schema.mapFromDb(outboundDoc); 56 | expect(inboundDoc).to.have.property('toggleOn', true); 57 | expect(inboundDoc).to.have.property('toggleOff', false); 58 | }); 59 | 60 | it('should map dates', function () { 61 | var schema = new DynamoSchema({ date: Date }); 62 | expect(schema.mappers.date).to.equal(DynamoSchema.mappers.Date); 63 | 64 | var now = new Date(Date.now()); 65 | var doc = { date: now }; 66 | var outboundDoc = schema.mapToDb(doc); 67 | expect(outboundDoc).to.have.property('date'); 68 | expect(outboundDoc.date).to.have.property('N', String(+now)); 69 | 70 | var inboundDoc = schema.mapFromDb(outboundDoc); 71 | expect(inboundDoc).to.have.property('date'); 72 | expect(+inboundDoc.date).to.equal(+now); 73 | }); 74 | 75 | it('should map JSON', function () { 76 | var schema = new DynamoSchema({ subdocument: {} }); 77 | expect(schema.mappers.subdocument).to.equal(DynamoSchema.mappers.JSON); 78 | 79 | var doc = { subdocument: { a: 1, b: 2, c: 3 } }; 80 | var outboundDoc = schema.mapToDb(doc); 81 | expect(outboundDoc).to.have.property('subdocument'); 82 | expect(outboundDoc.subdocument).to.have.property('S'); 83 | 84 | var inboundDoc = schema.mapFromDb(outboundDoc); 85 | expect(inboundDoc).to.have.property('subdocument'); 86 | expect(inboundDoc.subdocument).to.have.property('a', 1); 87 | expect(inboundDoc.subdocument).to.have.property('b', 2); 88 | expect(inboundDoc.subdocument).to.have.property('c', 3); 89 | }); 90 | 91 | it('should map buffers', function () { 92 | var schema = new DynamoSchema({ binaryData: Buffer }); 93 | expect(schema.mappers.binaryData).to.equal(DynamoSchema.mappers.Buffer); 94 | 95 | var buffer = new Buffer('hello world'); 96 | var doc = { binaryData: buffer }; 97 | var outboundDoc = schema.mapToDb(doc); 98 | expect(outboundDoc).to.have.property('binaryData'); 99 | expect(outboundDoc.binaryData).to.have.property('B', buffer.toString('base64')); 100 | 101 | var inboundDoc = schema.mapFromDb(outboundDoc); 102 | expect(inboundDoc).to.have.property('binaryData'); 103 | expect(inboundDoc.binaryData.toString('utf8')).to.equal('hello world'); 104 | }); 105 | 106 | it('should map arrays of strings', function () { 107 | var schema = new DynamoSchema({ lines: [String] }); 108 | expect(schema.mappers.lines).to.equal(DynamoSchema.mappers.Array.String); 109 | 110 | var doc = { lines: ['hello', 'world', '!'] }; 111 | var outboundDoc = schema.mapToDb(doc); 112 | expect(outboundDoc).to.have.property('lines'); 113 | expect(outboundDoc.lines).to.have.property('SS'); 114 | expect(outboundDoc.lines.SS).to.be.an.Array; 115 | expect(outboundDoc.lines.SS).to.have.length(3); 116 | 117 | var inboundDoc = schema.mapFromDb(outboundDoc); 118 | expect(inboundDoc).to.have.property('lines'); 119 | expect(inboundDoc.lines).to.be.an.Array; 120 | expect(inboundDoc.lines).to.have.length(3); 121 | }); 122 | 123 | it('should map arrays of numbers', function () { 124 | var schema = new DynamoSchema({ amounts: [Number] }); 125 | expect(schema.mappers.amounts).to.equal(DynamoSchema.mappers.Array.Number); 126 | 127 | var doc = { amounts: [0, 1, 2] }; 128 | var outboundDoc = schema.mapToDb(doc); 129 | expect(outboundDoc).to.have.property('amounts'); 130 | expect(outboundDoc.amounts).to.have.property('NS'); 131 | expect(outboundDoc.amounts.NS).to.be.an.Array; 132 | expect(outboundDoc.amounts.NS).to.have.length(3); 133 | 134 | var inboundDoc = schema.mapFromDb(outboundDoc); 135 | expect(inboundDoc).to.have.property('amounts'); 136 | expect(inboundDoc.amounts).to.be.an.Array; 137 | expect(inboundDoc.amounts).to.have.length(3); 138 | }); 139 | 140 | it('should map arrays of buffers', function () { 141 | var schema = new DynamoSchema({ data: [Buffer] }); 142 | expect(schema.mappers.data).to.equal(DynamoSchema.mappers.Array.Buffer); 143 | 144 | var doc = { data: [new Buffer('abc'), new Buffer('123'), new Buffer('_~|')] }; 145 | var outboundDoc = schema.mapToDb(doc); 146 | expect(outboundDoc).to.have.property('data'); 147 | expect(outboundDoc.data).to.have.property('BS'); 148 | expect(outboundDoc.data.BS).to.be.an.Array; 149 | expect(outboundDoc.data.BS).to.have.length(3); 150 | 151 | var inboundDoc = schema.mapFromDb(outboundDoc); 152 | expect(inboundDoc).to.have.property('data'); 153 | expect(inboundDoc.data).to.be.an.Array; 154 | expect(inboundDoc.data).to.have.length(3); 155 | }); 156 | 157 | it('should map with custom mappers', function () { 158 | var schema = new DynamoSchema({ 159 | customField: { 160 | mapFromDb: function (val) { 161 | return 'fromDB'; 162 | }, 163 | mapToDb: function (val) { 164 | return 'toDB'; 165 | } 166 | } 167 | }); 168 | 169 | var doc = { customField: true }; 170 | var outboundDoc = schema.mapToDb(doc); 171 | expect(outboundDoc).to.have.property('customField', 'toDB'); 172 | 173 | var inboundDoc = schema.mapFromDb(outboundDoc); 174 | expect(inboundDoc).to.have.property('customField', 'fromDB'); 175 | }); 176 | 177 | it('should map keys', function () { 178 | var schema = new DynamoSchema({ 179 | id: { 180 | type: String, 181 | key: true 182 | }, 183 | hash: { 184 | type: String, 185 | key: 'hash' 186 | }, 187 | range: { 188 | type: String, 189 | key: 'range' 190 | }, 191 | value: Number 192 | }); 193 | expect(Object.keys(schema.keys)).to.have.length(3); 194 | expect(Object.keys(schema.attributes)).to.have.length(4); 195 | expect(schema.keys.id).to.equal('HASH'); 196 | expect(schema.keys.hash).to.equal('HASH'); 197 | expect(schema.keys.range).to.equal('RANGE'); 198 | }); 199 | 200 | it('should map with default values as fallback', function () { 201 | var schema = new DynamoSchema({ 202 | no_default: String, 203 | with_static_default: { 204 | type: String, 205 | default: 'hello world' 206 | }, 207 | with_dynamic_default: { 208 | type: Number, 209 | default: function () { return Date.now(); } 210 | } 211 | }); 212 | expect(schema.defaults).to.have.property('with_static_default', 'hello world'); 213 | expect(schema.defaults).to.have.property('with_dynamic_default'); 214 | var outboundDoc = schema.mapFromDb({}); 215 | expect(outboundDoc).to.have.property('no_default', null); 216 | expect(outboundDoc).to.have.property('with_static_default', 'hello world'); 217 | expect(outboundDoc).to.have.property('with_dynamic_default'); 218 | expect(outboundDoc.with_dynamic_default).to.be.a.Number; 219 | }); 220 | 221 | }); 222 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # dynamodb-model 2 | 3 | A simple and lightweight object mapper for Amazon DynamoDB, influenced by MongoDB and the Mongoose API. This library allows mapping of DynamoDB tables to Javascript objects using schemas while providing a comfortable high-level API for maximum productivity. It also enables a smooth transition to DynamoDB if you already know MongoDB or Mongoose. 4 | 5 | ## Objectives 6 | 7 | + Support for the full DynamoDB feature set 8 | + Models use the official AWS SDK module 9 | + Independent schemas, free of dependencies 10 | + Automatic table creation 11 | + Transparent support for MongoDB operators, such as "$gt", "$set" or "$inc" 12 | + API conventions based on [Mongoose](https://github.com/LearnBoost/mongoose) 13 | + Good documentation 14 | + Good unit test coverage 15 | + Fast and lightweight 16 | 17 | ## Installation 18 | 19 | ```bash 20 | npm install dynamodb-model 21 | ``` 22 | 23 | To run the tests: 24 | 25 | ```bash 26 | npm test 27 | ``` 28 | 29 | ## Documentation 30 | 31 | ### Defining a schema to describe a DynamoDB table 32 | 33 | A schema describes attributes, keys, and indexes for a DynamoDB table. A schema instance allows mapping of Javascript objects to DynamoDB items and vice-versa. 34 | 35 | ```javascript 36 | var DynamoDBModel = require('dynamodb-model'); 37 | 38 | var productSchema = new DynamoDBModel.Schema({ 39 | productId: { 40 | type: Number, 41 | key: 'hash' // indicates a Hash key 42 | }, 43 | sku: String, 44 | inStock: Boolean, // will be stored as a "Y" or "N" string 45 | properties: {}, // will be converted to a JSON string 46 | created: Date // will be converted to a number with Date.getTime 47 | }); 48 | ``` 49 | 50 | #### Schema Types 51 | 52 | Schemas support the following data types native to DynamoDB: 53 | 54 | * String 55 | * Number 56 | * Blob (via Node.js [Buffer](http://nodejs.org/api/buffer.html)) 57 | * Array of strings 58 | * Array of numbers 59 | * Array of blobs (buffers) 60 | 61 | In addition, schemas also support the following data types with some transformations: 62 | 63 | * Boolean (as a "Y" or "N" string) 64 | * Date (via `Date.getTime` as a number) 65 | * JSON or objects (via `JSON.stringify` and `JSON.parse`), defined using an empty object `{}` 66 | 67 | It is also possible to implement you own mapping if necessary: 68 | 69 | ```javascript 70 | var DynamoDBModel = require('dynamodb-model'); 71 | 72 | var schema = new DynamoDBModel.Schema({ 73 | ... 74 | customField: { 75 | dynamoDbType: 'S', // the native DynamoDB type, either S, N, B, SS, NS or BS 76 | mapFromDb: function(value) { 77 | /* your implementation */ 78 | }, 79 | mapToDb: function(value) { 80 | /* your implementation, must return a string */ 81 | } 82 | } 83 | }); 84 | ``` 85 | 86 | #### Keys 87 | 88 | To specify a Hash or Range key, define a `key` attribute on the field. 89 | 90 | * Set to `"hash"` to specify a **Hash** key 91 | * Set to `"range"` to specify a **Range** key 92 | 93 | #### Local Secondary Indexes 94 | 95 | Local secondary indexes are not yet supported. 96 | 97 | #### Default values 98 | 99 | The specify a default value, use `default` to specify a static value or a function returning a value. 100 | 101 | ```javascript 102 | var DynamoDBModel = require('dynamodb-model'); 103 | 104 | var schema = new DynamoDBModel.Schema({ 105 | ... 106 | active: { 107 | type: Boolean, 108 | default: true 109 | } 110 | }); 111 | ``` 112 | 113 | Default values replace missing attributes when reading items from DynamoDB. 114 | 115 | #### Mapping objects manually 116 | 117 | Schemas are independent from the AWS SDK and can be used with any other DynamoDB client. To map an object to a DynamoDB structure manually, use `schema.mapToDb`. Likewise, to map a DynamoDB structure to an object, use `schema.mapFromDb`. 118 | 119 | ```javascript 120 | var DynamoDBModel = require('dynamodb-model'); 121 | 122 | var schema = new DynamoDBModel.Schema({ 123 | id: { 124 | type: Number, 125 | key: 'hash' 126 | }, 127 | message: String 128 | }); 129 | 130 | schema.mapToDb({ id: 1, message: 'some text' }); 131 | // returns { id: { N: '1' }, message: { 'S': 'some text' } }; 132 | 133 | schema.mapFromDb({ id: { N: '1' }, message: { 'S': 'some text' } }); 134 | // returns { id: 1, message: 'some text' }; 135 | ``` 136 | 137 | ### Using a model to interact with a DynamoDB table 138 | 139 | The `Model` class provides the high-level API you use to interact with the table, such as reading and writing data. The model class uses the official AWS SDK which already implement most of the best practices, such as automatic retries on a "HTTP 400: Capacity Exceeded" error. 140 | 141 | Models also create the table automatically if required. There is no need to validate table existence or the "active" status. Operations performed while the table is not ready are queued until the table becomes active. 142 | 143 | ```javascript 144 | var DynamoDBModel = require('dynamodb-model'); 145 | 146 | var productSchema = new DynamoDBModel.Schema({ 147 | productId: { 148 | type: Number, 149 | key: 'hash' 150 | }, 151 | sku: String, 152 | inStock: Boolean, 153 | properties: {}, 154 | created: Date 155 | }); 156 | 157 | // create a model using the name of the DynamoDB table and a schema 158 | var productTable = new DynamoDBModel.Model('dynamo-products', productSchema); 159 | 160 | // the model provides methods for all DynamoDB operations 161 | // no need to check for table status, we can start using it right away 162 | productTable.putItem(/* ... */); 163 | productTable.getItem(/* ... */); 164 | productTable.updateItem(/* ... */); 165 | productTable.deleteItem(/* ... */); 166 | 167 | // but some of them return intermediate objects in order to provide a better API 168 | var query = productTable.query(/* ... */); 169 | query.select(/* ... */).limit(100).exec(callback); 170 | ``` 171 | 172 | #### About AWS connectivity and credentials 173 | 174 | The `dynamodb-model` module uses the official AWS SDK module for low-level operations. To properly connect to your DynamoDB table, make sure you configure the AWS SDK first. More details on the official AWS website [here](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/configuring.html). 175 | 176 | ```javascript 177 | var AWS = require('aws-sdk'); 178 | 179 | // setup region and credentials 180 | AWS.config.update({ 181 | accessKeyId: /* Your acess key */, 182 | secretAccessKey: /* Your secret key */, 183 | region: 'us-east-1' 184 | }); 185 | 186 | // specify the API version (optional) 187 | AWS.config.apiVersions = { 188 | dynamodb: '2012-08-10' 189 | }; 190 | ``` 191 | 192 | Additionally, if you need to specify options for the `AWS.DynamoDB` constructor, pass them to the `Model` constructor like this: 193 | 194 | ```javascript 195 | var myTable = new DynamoDBModel.Model(tableName, schema, { 196 | maxRetries: 1000, 197 | sslEnabled: true 198 | }); 199 | ``` 200 | 201 | #### About table status 202 | 203 | When creating a model instance, a `describeTable` call is immediately performed to check for table existence. If the table does not exist, a `createTable` call follows immediately. 204 | 205 | If the table is not yet active (table status is not `"ACTIVE"`), all operations are queued and will not be executed until the table is ready. When the table becomes active, operations from the queue are executed in sequential order. This means that you can create a model instance and start writing data immediately, even if the table does not exist. 206 | 207 | If you wish to wait for the table to become available before performing an action, use the `waitForActiveTable` method, which invokes `describeTable` repeatedly until the status switches to `"ACTIVE"`. 208 | 209 | **WARNING:** the queue is not durable and should not be used in a production environment, since changes will be lost if the application terminates before the table becomes active. Instead, create your table beforehand, or use the `waitForActiveTable` method to make sure the table is ready. 210 | 211 | #### Model.batchGetItem 212 | 213 | This method is not yet implemented. 214 | 215 | [AWS Documentation for BatchGetItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html) 216 | 217 | #### Model.batchWriteItem 218 | 219 | This method is not yet implemented. 220 | 221 | [AWS Documentation for BatchWriteItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html) 222 | 223 | #### Model.createTable(options, callback) 224 | 225 | Creates the DynamoDB table represented by the schema and returns the AWS service response. 226 | 227 | + options: attributes to add to the AWS.Request instance (optional) 228 | + callback: the callback function to invoke with the AWS response (optional) 229 | 230 | ```javascript 231 | var myTable = new DynamoDBModel.Model(tableName, schema); 232 | myTable.createTable(function (err, response) { 233 | // table creation started 234 | }) 235 | ``` 236 | 237 | Note: table creation in DynamoDB is asynchronous. The table is not ready until its status property is set to "ACTIVE". If you need to wait for the table to become active, use the `waitForActiveTable` method. 238 | 239 | [AWS Documentation for CreateTable](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CreateTable.html) 240 | 241 | #### Model.deleteItem(key, options, callback) 242 | 243 | Deletes a single item in a table by primary key and returns the AWS service response. 244 | 245 | + key: an object representing the primary key of the item to remove 246 | + options: attributes to add to the AWS.Request instance (optional) 247 | + callback: the callback function to invoke with the AWS response (optional) 248 | 249 | ```javascript 250 | var myTable = new DynamoDBModel.Model(tableName, schema); 251 | myTable.deleteItem({ id: 1 }, function (err, response) { 252 | // item removed 253 | }) 254 | ``` 255 | 256 | [AWS Documentation for DeleteItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html) 257 | 258 | Note: conditional deletes are not yet implemented. 259 | 260 | #### Model.deleteTable(options, callback) 261 | 262 | Removes the table represented by the schema, as well as all items in the table, then returns the AWS service response. 263 | 264 | + options: attributes to add to the AWS.Request instance (optional) 265 | + callback: the callback function to invoke with the AWS response 266 | 267 | ```javascript 268 | var myTable = new DynamoDBModel.Model(tableName, schema); 269 | myTable.deleteTable(function (err, response) { 270 | // table removal started 271 | }) 272 | ``` 273 | 274 | [AWS Documentation for DeleteTable](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteTable.html) 275 | 276 | #### Model.describeTable(options, callback) 277 | 278 | Returns information about the table represented by the schema, including the current status of the table, when it was created, the primary key schema, and any indexes on the table. The table description is the AWS service response. 279 | 280 | + options: attributes to add to the AWS.Request instance (optional) 281 | + callback: the callback function to invoke with the AWS response 282 | 283 | ```javascript 284 | var myTable = new DynamoDBModel.Model(tableName, schema); 285 | myTable.describeTable(function (err, response) { 286 | // response contains the table description, see AWS docs for more details 287 | }) 288 | ``` 289 | 290 | #### Model.waitForActiveTable(pollingInterval, callback) 291 | 292 | Invokes `describeTable` repeatedly until the table status is `"ACTIVE"`. 293 | 294 | + pollingInterval: the delay in milliseconds between each invocation of `describeTable` (optional, default value is 3000) 295 | + callback: the callback function to invoke with the AWS response from `describeTable` (optional) 296 | 297 | ```javascript 298 | var myTable = new DynamoDBModel.Model(tableName, schema); 299 | var pollingInterval = 5000; // 5 seconds 300 | myTable.waitForActiveTable(pollingInterval, function (err, response) { 301 | // response contains the table description, with an "ACTIVE" status 302 | }) 303 | ``` 304 | 305 | #### Model.getItem(key, options, callback) 306 | 307 | Retrieves a specific item based on its primary key, returning the mapped item as well as the AWS service response. 308 | 309 | + key: an object representing the primary key of the item to retrieve 310 | + options: attributes to add to the AWS.Request instance (optional) 311 | + callback: the callback function to invoke with the AWS response 312 | 313 | ```javascript 314 | var myTable = new DynamoDBModel.Model(tableName, schema); 315 | myTable.getItem({ id: 1 }, function (err, item, response) { 316 | // item represents the DynamoDB item mapped to an object using the schema 317 | }) 318 | ``` 319 | 320 | [AWS Documentation for GetItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) 321 | 322 | #### Model.listTables(options, callback) 323 | 324 | This method is not yet implemented. 325 | 326 | + options: attributes to add to the AWS.Request instance (optional) 327 | + callback: the callback function to invoke with the AWS response 328 | 329 | [AWS Documentation for ListTables](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ListTables.html) 330 | 331 | #### Model.putItem(item, options, callback) 332 | 333 | TBD 334 | 335 | [AWS Documentation for PutItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html) 336 | 337 | #### Model.query 338 | 339 | TBD 340 | 341 | [AWS Documentation for Query](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) 342 | 343 | #### Model.scan 344 | 345 | TBD 346 | 347 | [AWS Documentation for Scan](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html) 348 | 349 | #### Model.updateItem 350 | 351 | TBD 352 | 353 | [AWS Documentation for UpdateItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) 354 | 355 | #### Model.updateTable 356 | 357 | TBD 358 | 359 | [AWS Documentation for UpdateTable](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateTable.html) 360 | 361 | ### Reading results with DynamoDBModel.Query 362 | 363 | TBD 364 | 365 | ## Stability 366 | 367 | This is the initial release of `dynamodb-model` and should not be considered production-ready yet. Some features are also missing (see TODO section). 368 | 369 | ## TODO 370 | 371 | * Complete documentation 372 | * Implement local secondary indexes 373 | * Implement `BatchGetItem` operation 374 | * Implement `BatchWriteItem` operation 375 | * Add conditional support for `DeleteItem` operation 376 | * Add parallel support for `Scan` operation 377 | * Improve API to be closer to Mongoose, using aliases for common methods 378 | * Check for table key changes, which are unsupported by DynamoDB 379 | 380 | ## Compatibility 381 | 382 | + Tested with Node 0.10.x 383 | + Tested on Mac OS X 10.8 384 | 385 | ## Dependencies 386 | 387 | + [async](http://github.com/caolan/async) 388 | + [aws-sdk](http://github.com/aws/aws-sdk-js) 389 | 390 | ## License 391 | 392 | The MIT License (MIT) 393 | 394 | Copyright (c) 2013, Nicolas Mercier 395 | 396 | Permission is hereby granted, free of charge, to any person obtaining a copy 397 | of this software and associated documentation files (the "Software"), to deal 398 | in the Software without restriction, including without limitation the rights 399 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 400 | copies of the Software, and to permit persons to whom the Software is 401 | furnished to do so, subject to the following conditions: 402 | 403 | The above copyright notice and this permission notice shall be included in 404 | all copies or substantial portions of the Software. 405 | 406 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 407 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 408 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 409 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 410 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 411 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 412 | THE SOFTWARE. 413 | -------------------------------------------------------------------------------- /lib/model.js: -------------------------------------------------------------------------------- 1 | var async = require('async'); 2 | // var AWS = require('aws-sdk'); 3 | var DynamoQuery = require('./query'); 4 | 5 | function mapToArray(source, fn) { 6 | var result = []; 7 | for (var key in source) { 8 | result.push(fn(key, source[key], source)); 9 | } 10 | return result; 11 | } 12 | 13 | function mapToObject(source, fn) { 14 | var result = {}; 15 | for (var key in source) { 16 | var r = fn(key, source[key], source); 17 | for (var resultKey in r) { 18 | result[resultKey] = r[resultKey]; 19 | } 20 | } 21 | return result; 22 | } 23 | 24 | function pairs(source) { 25 | var result = []; 26 | for (var key in source) { 27 | result.push([key, source[key]]); 28 | } 29 | return result; 30 | } 31 | 32 | var DynamoModel = function (tableName, schema, options) { 33 | 34 | if (!tableName) throw new Error('tableName is required'); 35 | if (!schema) throw new Error('schema is required'); 36 | 37 | var instance = this; 38 | var tableStatus = 'undefined'; 39 | var tableStatusPendingCallbacks = []; 40 | 41 | options = options || {}; 42 | this.dynamodb = new AWS.DynamoDB(options); 43 | this.consistentRead = false; 44 | this.defaultThroughput = { 45 | ReadCapacityUnits: 10, 46 | WriteCapacityUnits: 5 47 | }; 48 | 49 | this.tableName = tableName; 50 | this.schema = schema; 51 | this.options = options; 52 | 53 | modelInstances[tableName] = this; 54 | 55 | // a default callback making sure errors are not lost 56 | function defaultCallback(err) { 57 | if (err) throw err; 58 | } 59 | 60 | DynamoModel.prototype.getItem = function (key, options, callback) { 61 | if (!key) throw new Error('key is required'); 62 | if (typeof options === 'function') { 63 | callback = options; 64 | options = {}; 65 | } 66 | callback = callback || defaultCallback; 67 | 68 | var params = options || {}; 69 | params.TableName = this.tableName; 70 | params.Key = this.schema.mapToDb(key); 71 | if (this.consistentRead) params.ConsistentRead = true; 72 | var privateSchema = this.schema; 73 | 74 | this.ensureActiveTable(function (err) { 75 | if (err) return callback(err); 76 | return instance.dynamodb.getItem(params, function (err, response) { 77 | if (err) return callback(err); 78 | return callback(null, privateSchema.mapFromDb(response.Item), response); 79 | }); 80 | }); 81 | }; 82 | 83 | DynamoModel.prototype.putItem = function (item, options, callback) { 84 | if (!item) throw new Error('item is required'); 85 | if (typeof options === 'function') { 86 | callback = options; 87 | options = {}; 88 | } 89 | callback = callback || defaultCallback; 90 | 91 | var params = options || {}; 92 | params.TableName = this.tableName; 93 | params.Item = this.schema.mapToDb(item); 94 | var privateSchema = this.schema; 95 | 96 | this.ensureActiveTable(function (err) { 97 | if (err) return callback(err); 98 | instance.dynamodb.putItem(params, function (err, response) { 99 | if (err) return callback(err); 100 | callback(null, privateSchema.mapFromDb(response.Attributes), response); 101 | }); 102 | }); 103 | }; 104 | 105 | DynamoModel.prototype.updateItem = function (key, updates, options, callback) { 106 | if (!key) throw new Error('key is required'); 107 | if (!updates) throw new Error('updates is required'); 108 | if (typeof options === 'function') { 109 | callback = options; 110 | options = {}; 111 | } 112 | callback = callback || defaultCallback; 113 | 114 | var params = options || {}; 115 | params.TableName = this.tableName; 116 | params.Key = this.schema.mapToDb(key); 117 | params.AttributeUpdates = this.parseUpdates(updates); 118 | 119 | this.ensureActiveTable(function (err) { 120 | if (err) return callback(err); 121 | instance.dynamodb.updateItem(params, callback); 122 | }); 123 | }; 124 | 125 | DynamoModel.prototype.deleteItem = function (key, options, callback) { 126 | if (!key) throw new Error('key is required'); 127 | if (typeof options === 'function') { 128 | callback = options; 129 | options = {}; 130 | } 131 | callback = callback || defaultCallback; 132 | 133 | var params = options || {}; 134 | params.TableName = this.tableName; 135 | params.Key = this.schema.mapToDb(key); 136 | 137 | this.ensureActiveTable(function (err) { 138 | if (err) return callback(err); 139 | instance.dynamodb.deleteItem(params, callback); 140 | }); 141 | }; 142 | 143 | DynamoModel.prototype.query = function (key, options, callback) { 144 | if (!key) throw new Error('key is required'); 145 | if (typeof options === 'function') { 146 | callback = options; 147 | options = {}; 148 | } 149 | 150 | var params = options || {}; 151 | params.TableName = this.tableName; 152 | params.KeyConditions = this.parseConditions(key); 153 | if (this.consistentRead) params.ConsistentRead = true; 154 | 155 | var query = new DynamoQuery('query', this.schema, this, params); 156 | if (callback) return query.exec(callback); 157 | return query; 158 | }; 159 | 160 | DynamoModel.prototype.scan = function (filter, options, callback) { 161 | if (typeof filter === 'function') { 162 | callback = filter; 163 | options = {}; 164 | filter = null; 165 | } 166 | if (typeof options === 'function') { 167 | callback = options; 168 | options = {}; 169 | } 170 | 171 | var params = options || {}; 172 | params.TableName = this.tableName; 173 | if (filter) { 174 | params.ScanFilter = this.parseConditions(filter); 175 | } 176 | 177 | var query = new DynamoQuery('scan', this.schema, this, params); 178 | if (callback) return query.exec(callback); 179 | return query; 180 | }; 181 | 182 | DynamoModel.prototype.describeTable = function (options, callback) { 183 | if (typeof options === 'function') { 184 | callback = options; 185 | options = {}; 186 | } 187 | 188 | var params = options || {}; 189 | params.TableName = this.tableName; 190 | return this.dynamodb.describeTable(params, callback); 191 | }; 192 | 193 | DynamoModel.prototype.createTable = function(options, callback) { 194 | if (typeof options === 'function') { 195 | callback = options; 196 | options = {}; 197 | } 198 | 199 | var privateSchema = this.schema; 200 | var params = options || {}; 201 | params.TableName = this.tableName; 202 | params.KeySchema = mapToArray(this.schema.keys, function (name, val) { 203 | return { AttributeName: name, KeyType: val }; 204 | }); 205 | params.AttributeDefinitions = mapToArray(this.schema.keys, function (name, val) { 206 | return { AttributeName: name, AttributeType: privateSchema.attributes[name] }; 207 | }); 208 | params.ProvisionedThroughput = params.ProvisionedThroughput || this.defaultThroughput; 209 | 210 | return this.dynamodb.createTable(params, callback); 211 | }; 212 | 213 | DynamoModel.prototype.updateTable = function (options, callback) { 214 | if (typeof options === 'function') { 215 | callback = options; 216 | options = {}; 217 | } 218 | 219 | var params = options || {}; 220 | params.TableName = this.tableName; 221 | params.ProvisionedThroughput = params.ProvisionedThroughput || this.defaultThroughput; 222 | return this.dynamodb.updateTable(params, callback); 223 | }; 224 | 225 | DynamoModel.prototype.deleteTable = function (options, callback) { 226 | var params = options || {}; 227 | params.TableName = this.tableName; 228 | return this.dynamodb.deleteTable(params, callback); 229 | }; 230 | 231 | DynamoModel.prototype.ensureActiveTable = function (callback) { 232 | if (tableStatus === 'undefined') { 233 | tableStatus = 'querying'; 234 | if (callback) tableStatusPendingCallbacks.push(callback); 235 | this.waitForActiveTable(function (err, response) { 236 | tableStatus = { error: err, response: response }; 237 | // fire all pending callbacks 238 | for (var i = 0; i < tableStatusPendingCallbacks.length; i++) { 239 | tableStatusPendingCallbacks[i](err); 240 | } 241 | tableStatusPendingCallbacks = []; 242 | }); 243 | } else if (tableStatus === 'querying' && callback) { 244 | // already querying table status, add callback to queue 245 | tableStatusPendingCallbacks.push(callback); 246 | } else { 247 | return callback(tableStatus.error); 248 | } 249 | }; 250 | 251 | DynamoModel.prototype.waitForActiveTable = function (pollingTimeout, callback) { 252 | if (typeof pollingTimeout === 'function') { 253 | callback = pollingTimeout; 254 | pollingTimeout = null; 255 | } 256 | callback = callback || function () {}; 257 | pollingTimeout = pollingTimeout || 3000; 258 | 259 | async.waterfall([ 260 | function getTableDescription(callback) { 261 | instance.describeTable(function (err, response) { 262 | if (err) { 263 | if (err.code === 'ResourceNotFoundException') { 264 | // table does not exist, create it now 265 | instance.createTable(function (err, response) { 266 | if (err) return callback(err); 267 | callback(null, response.TableDescription); 268 | }); 269 | } else { 270 | return callback(err); 271 | } 272 | } else { 273 | callback(null, response.Table); 274 | } 275 | }); 276 | }, 277 | function pollUntilActive(tableDescription, callback) { 278 | async.until(function () { 279 | return tableDescription.TableStatus === 'ACTIVE'; 280 | }, function (callback) { 281 | setTimeout(function () { 282 | instance.describeTable(function (err, response) { 283 | if (err) return callback(err); 284 | tableDescription = response.Table; 285 | callback(); 286 | }); 287 | }, pollingTimeout); 288 | }, function (err) { 289 | if (err) return callback(err); 290 | callback(null, tableDescription); 291 | }); 292 | } 293 | ], callback); 294 | }; 295 | 296 | DynamoModel.prototype.parseConditions = function(conditions) { 297 | var inst = this; 298 | var result = {}; 299 | 300 | pairs(conditions).forEach(function (pair) { 301 | 302 | var key = pair[0]; 303 | var value = pair[1]; 304 | var operator = 'EQ'; 305 | 306 | if (typeof value === 'object') { 307 | var val = pairs(value); 308 | if (val.length === 1) { 309 | operator = val[0][0]; 310 | value = val[0][1]; 311 | } 312 | } 313 | 314 | if (operator === '$gt') { 315 | operator = 'GT'; 316 | } else if (operator === '$gte') { 317 | operator = 'GE'; 318 | } else if (operator === '$lt') { 319 | operator = 'LT'; 320 | } else if (operator === '$lte') { 321 | operator = 'LE'; 322 | } else if (operator === '$begins') { 323 | operator = 'BEGINS_WITH'; 324 | } else if (operator === '$between') { 325 | operator = 'BETWEEN'; 326 | } else if (/^\$/.test(operator)) { 327 | throw new Error('conditional operator "' + operator + '" is not supported'); 328 | } 329 | 330 | console.log(operator + ', ' + key + ', ' + value); 331 | 332 | var values = []; 333 | 334 | if (operator === 'BETWEEN') { 335 | if (!(Array.isArray(value) && value.length === 2)) { 336 | throw new Error('BETWEEN operator must have an array of two elements as the comparison value'); 337 | } 338 | values.push(inst.schema.mappers[key].mapToDb(value[0])); 339 | values.push(inst.schema.mappers[key].mapToDb(value[1])); 340 | } else if (Array.isArray(value)) { 341 | throw new Error('this operator does not support array values'); 342 | } else { 343 | values.push(inst.schema.mappers[key].mapToDb(value)); 344 | } 345 | 346 | result[key] = { 347 | AttributeValueList: values, 348 | ComparisonOperator: operator 349 | }; 350 | 351 | }); 352 | return result; 353 | } 354 | 355 | DynamoModel.prototype.parseUpdates = function(updates) { 356 | var inst = this; 357 | 358 | return mapToObject(updates, function (key, value) { 359 | 360 | var result = {}; 361 | var mapper; 362 | 363 | // look for a MongoDB-like operator and translate to its DynamoDB equivalent 364 | if (/^\$/.test(key)) { 365 | var action; 366 | if (key === '$set') action = 'PUT'; 367 | if (key === '$unset') action = 'DELETE'; 368 | if (key === '$inc') action = 'ADD'; 369 | if (!action) { 370 | throw new Error('update operator "' + key + '" is not supported'); 371 | } 372 | pairs(value).forEach(function (pair) { 373 | if (!inst.schema.mappers.hasOwnProperty(pair[0])) { 374 | throw new Error('unknown field: ' + pair[0]); 375 | } 376 | mapper = inst.schema.mappers[pair[0]]; 377 | if (action == 'DELETE') { 378 | result[pair[0]] = { 379 | Action: action 380 | }; 381 | } else { 382 | result[pair[0]] = { 383 | Action: action, 384 | Value: mapper.mapToDb(pair[1]) 385 | }; 386 | } 387 | }); 388 | 389 | return result; 390 | } 391 | 392 | if (!inst.schema.mappers.hasOwnProperty(key)) { 393 | throw new Error('unknown field: ' + key); 394 | } 395 | mapper = inst.schema.mappers[key]; 396 | 397 | if (typeof value === 'object' && typeof value.getTime != 'function' && !(value instanceof Array)) { 398 | var val = pairs(value); 399 | if (val.length === 1) { 400 | result[key] = { 401 | Action: val[0][0], 402 | Value: mapper.mapToDb(val[0][1]) 403 | }; 404 | } else { 405 | result[key] = { 406 | Action: 'PUT', 407 | Value: inst.schema.mappers[key].mapToDb(value) 408 | }; 409 | } 410 | } else { 411 | result[key] = { 412 | Action: 'PUT', 413 | Value: inst.schema.mappers[key].mapToDb(value) 414 | }; 415 | } 416 | return result; 417 | }); 418 | } 419 | 420 | // make sure the table is available as soon as possible 421 | this.ensureActiveTable(); 422 | 423 | }; 424 | 425 | module.exports = DynamoModel; 426 | -------------------------------------------------------------------------------- /test/test-model.js: -------------------------------------------------------------------------------- 1 | var DynamoSchema = require('..').Schema; 2 | var DynamoModel = require('..').Model; 3 | var DynamoQuery = require('..').Query; 4 | var chai = require('chai'); 5 | var expect = chai.expect; 6 | 7 | describe('DynamoModel', function () { 8 | 9 | // a sample schema for all our tests 10 | var schema = new DynamoSchema({ 11 | id: { 12 | type: String, 13 | key: true 14 | }, 15 | range: { 16 | type: Number, 17 | key: 'range' 18 | }, 19 | attribute1: String, 20 | attribute2: Number 21 | }); 22 | 23 | describe('SDK method', function () { 24 | 25 | describe('GetItem', function () { 26 | it('should provide required parameters', function () { 27 | var model = new DynamoModel('my-table', schema); 28 | model.dynamodb.getItem = function (params, callback) { 29 | expect(params).to.have.property('TableName', 'my-table'); 30 | expect(params).to.have.property('Key'); 31 | expect(params.Key).to.have.property('id'); 32 | expect(params.Key.id).to.have.property('S', 'test'); 33 | }; 34 | model.getItem({ id: 'test' }); 35 | }); 36 | it('should allow custom parameters', function () { 37 | var model = new DynamoModel('my-table', schema); 38 | model.dynamodb.getItem = function (params, callback) { 39 | expect(params).to.have.property('CustomParameter', 'value'); 40 | }; 41 | model.getItem({ id: 'test' }, { CustomParameter: 'value' }); 42 | }); 43 | it('should map resulting item', function () { 44 | var model = new DynamoModel('my-table', schema); 45 | model.dynamodb.getItem = function (params, callback) { 46 | callback(null, { 47 | Item: schema.mapToDb({ id: 'test', range: 1 }) 48 | }); 49 | }; 50 | model.getItem({ id: 'test' }, function (err, item) { 51 | expect(item).to.have.property('id', 'test'); 52 | expect(item).to.have.property('range', 1); 53 | }); 54 | }); 55 | it('should throw if missing key', function () { 56 | var model = new DynamoModel('my-table', schema); 57 | expect(function () { 58 | model.getItem(); 59 | }).to.throw('key is required'); 60 | }); 61 | }); 62 | 63 | describe('PutItem', function () { 64 | it('should provide required parameters', function () { 65 | var model = new DynamoModel('my-table', schema); 66 | model.dynamodb.putItem = function (params, callback) { 67 | expect(params).to.have.property('TableName', 'my-table'); 68 | expect(params).to.have.property('Item'); 69 | expect(params.Item).to.have.property('id'); 70 | expect(params.Item.id).to.have.property('S', 'test'); 71 | }; 72 | model.putItem({ id: 'test' }); 73 | }); 74 | it('should allow custom parameters', function () { 75 | var model = new DynamoModel('my-table', schema); 76 | model.dynamodb.putItem = function (params, callback) { 77 | expect(params).to.have.property('CustomParameter', 'value'); 78 | }; 79 | model.putItem({ id: 'test' }, { CustomParameter: 'value' }); 80 | }); 81 | it('should throw if missing item', function () { 82 | var model = new DynamoModel('my-table', schema); 83 | expect(function () { 84 | model.putItem(); 85 | }).to.throw('item is required'); 86 | }); 87 | }); 88 | 89 | describe('UpdateItem', function () { 90 | it('should provide required parameters', function () { 91 | var model = new DynamoModel('my-table', schema); 92 | model.dynamodb.updateItem = function (params, callback) { 93 | expect(params).to.have.property('TableName', 'my-table'); 94 | expect(params).to.have.property('Key'); 95 | expect(params.Key).to.have.property('id'); 96 | expect(params.Key.id).to.have.property('S', 'test'); 97 | expect(params.Key).to.have.property('range'); 98 | expect(params.Key.range).to.have.property('N', '1'); 99 | expect(params).to.have.property('AttributeUpdates'); 100 | expect(params.AttributeUpdates).to.have.property('attribute1'); 101 | expect(params.AttributeUpdates.attribute1).to.have.property('Action', 'PUT'); 102 | expect(params.AttributeUpdates.attribute1).to.have.property('Value'); 103 | expect(params.AttributeUpdates.attribute1.Value).to.have.property('S', 'abc'); 104 | }; 105 | model.updateItem({ id: 'test', range: 1 }, { attribute1: 'abc' }); 106 | }); 107 | it('should allow custom parameters', function () { 108 | var model = new DynamoModel('my-table', schema); 109 | model.dynamodb.updateItem = function (params, callback) { 110 | expect(params).to.have.property('CustomParameter', 'value'); 111 | }; 112 | model.updateItem({}, {}, { CustomParameter: 'value' }); 113 | }); 114 | it('should throw if missing key', function () { 115 | var model = new DynamoModel('my-table', schema); 116 | expect(function () { 117 | model.updateItem(); 118 | }).to.throw('key is required'); 119 | }); 120 | it('should throw if missing updates', function () { 121 | var model = new DynamoModel('my-table', schema); 122 | expect(function () { 123 | model.updateItem({}); 124 | }).to.throw('updates is required'); 125 | }); 126 | }); 127 | 128 | describe('DeleteItem', function () { 129 | it('should provide required parameters', function () { 130 | var model = new DynamoModel('my-table', schema); 131 | model.dynamodb.deleteItem = function (params, callback) { 132 | expect(params).to.have.property('TableName', 'my-table'); 133 | expect(params).to.have.property('Key'); 134 | expect(params.Key).to.have.property('id'); 135 | expect(params.Key.id).to.have.property('S', 'test'); 136 | }; 137 | model.deleteItem({ id: 'test', range: 1 }, { attribute1: 'abc' }); 138 | }); 139 | it('should allow custom parameters', function () { 140 | var model = new DynamoModel('my-table', schema); 141 | model.dynamodb.deleteItem = function (params, callback) { 142 | expect(params).to.have.property('CustomParameter', 'value'); 143 | }; 144 | model.deleteItem({}, { CustomParameter: 'value' }); 145 | }); 146 | it('should throw if missing key', function () { 147 | var model = new DynamoModel('my-table', schema); 148 | expect(function () { 149 | model.deleteItem(); 150 | }).to.throw('key is required'); 151 | }); 152 | }); 153 | 154 | describe('Query', function () { 155 | it('should provide required parameters', function () { 156 | var model = new DynamoModel('my-table', schema); 157 | model.dynamodb.query = function (params, callback) { 158 | expect(params).to.have.property('TableName', 'my-table'); 159 | expect(params).to.have.property('KeyConditions'); 160 | expect(params.KeyConditions).to.have.property('id'); 161 | expect(params.KeyConditions.id).to.have.property('S', 'test'); 162 | }; 163 | model.query({ id: 'test', range: 1 }); 164 | }); 165 | it('should allow custom parameters', function () { 166 | var model = new DynamoModel('my-table', schema); 167 | model.dynamodb.query = function (params, callback) { 168 | expect(params).to.have.property('CustomParameter', 'value'); 169 | }; 170 | model.query({}, { CustomParameter: 'value' }); 171 | }); 172 | it('should throw if missing key', function () { 173 | var model = new DynamoModel('my-table', schema); 174 | expect(function () { 175 | model.query(); 176 | }).to.throw('key is required'); 177 | }); 178 | it('should return a Query instance', function () { 179 | var model = new DynamoModel('my-table', schema); 180 | var query = model.query({ id: 'test', range: 1 }); 181 | expect(query).to.be.an.instanceOf(DynamoQuery); 182 | }); 183 | }); 184 | 185 | describe('Scan', function () { 186 | it('should provide required parameters', function () { 187 | var model = new DynamoModel('my-table', schema); 188 | model.dynamodb.scan = function (params, callback) { 189 | expect(params).to.have.property('TableName', 'my-table'); 190 | expect(params).to.have.property('KeyConditions'); 191 | expect(params.KeyConditions).to.have.property('id'); 192 | expect(params.KeyConditions.id).to.have.property('S', 'test'); 193 | }; 194 | model.scan({ id: 'test', range: 1 }, { attribute1: 'abc' }); 195 | }); 196 | it('should allow custom parameters', function () { 197 | var model = new DynamoModel('my-table', schema); 198 | model.dynamodb.scan = function (params, callback) { 199 | expect(params).to.have.property('CustomParameter', 'value'); 200 | }; 201 | model.scan({}, { CustomParameter: 'value' }); 202 | }); 203 | }); 204 | 205 | describe('DescribeTable', function () { 206 | it('should provide required parameters', function () { 207 | var model = new DynamoModel('my-table', schema); 208 | model.dynamodb.describeTable = function (params, callback) { 209 | expect(params).to.have.property('TableName', 'my-table'); 210 | }; 211 | model.describeTable(); 212 | }); 213 | }); 214 | 215 | describe('CreateTable', function () { 216 | it('should provide required parameters', function () { 217 | var model = new DynamoModel('my-table', schema); 218 | model.dynamodb.createTable = function (params, callback) { 219 | expect(params).to.have.property('TableName', 'my-table'); 220 | expect(params).to.have.property('KeySchema'); 221 | expect(params.KeySchema).to.have.length(2); 222 | expect(params.KeySchema[0]).to.have.property('AttributeName', 'id'); 223 | expect(params.KeySchema[0]).to.have.property('KeyType', 'HASH'); 224 | expect(params.KeySchema[1]).to.have.property('AttributeName', 'range'); 225 | expect(params.KeySchema[1]).to.have.property('KeyType', 'RANGE'); 226 | expect(params).to.have.property('AttributeDefinitions'); 227 | expect(params.AttributeDefinitions).to.have.length(2); 228 | expect(params.AttributeDefinitions[0]).to.have.property('AttributeName', 'id'); 229 | expect(params.AttributeDefinitions[0]).to.have.property('AttributeType', 'S'); 230 | expect(params.AttributeDefinitions[1]).to.have.property('AttributeName', 'range'); 231 | expect(params.AttributeDefinitions[1]).to.have.property('AttributeType', 'N'); 232 | expect(params).to.have.property('ProvisionedThroughput'); 233 | expect(params.ProvisionedThroughput).to.have.property('ReadCapacityUnits', 234 | model.defaultThroughput.ReadCapacityUnits); 235 | expect(params.ProvisionedThroughput).to.have.property('WriteCapacityUnits', 236 | model.defaultThroughput.WriteCapacityUnits); 237 | }; 238 | model.createTable(); 239 | }); 240 | it('should allow custom parameters', function () { 241 | var model = new DynamoModel('my-table', schema); 242 | model.dynamodb.createTable = function (params, callback) { 243 | expect(params).to.have.property('CustomParameter', 'value'); 244 | }; 245 | model.createTable({ CustomParameter: 'value' }); 246 | }); 247 | it('should honor model.defaultThroughput ', function () { 248 | var model = new DynamoModel('my-table', schema); 249 | model.defaultThroughput = { ReadCapacityUnits: 999, WriteCapacityUnits: 999 }; 250 | model.dynamodb.createTable = function (params, callback) { 251 | expect(params.ProvisionedThroughput).to.have.property('ReadCapacityUnits', 999); 252 | expect(params.ProvisionedThroughput).to.have.property('WriteCapacityUnits', 999); 253 | }; 254 | model.createTable({ CustomParameter: 'value' }); 255 | }); 256 | }); 257 | 258 | describe('UpdateTable', function () { 259 | it('should provide required parameters', function () { 260 | var model = new DynamoModel('my-table', schema); 261 | model.dynamodb.updateTable = function (params, callback) { 262 | expect(params).to.have.property('TableName', 'my-table'); 263 | expect(params).to.have.property('ProvisionedThroughput'); 264 | }; 265 | model.updateTable(); 266 | }); 267 | it('should allow custom parameters', function () { 268 | var model = new DynamoModel('my-table', schema); 269 | model.dynamodb.updateTable = function (params, callback) { 270 | expect(params).to.have.property('CustomParameter', 'value'); 271 | }; 272 | model.updateTable({ CustomParameter: 'value' }); 273 | }); 274 | }); 275 | 276 | describe('DeleteTable', function () { 277 | it('should provide required parameters', function () { 278 | var model = new DynamoModel('my-table', schema); 279 | model.dynamodb.deleteTable = function (params, callback) { 280 | expect(params).to.have.property('TableName', 'my-table'); 281 | }; 282 | model.deleteTable(); 283 | }); 284 | it('should allow custom parameters', function () { 285 | var model = new DynamoModel('my-table', schema); 286 | model.dynamodb.deleteTable = function (params, callback) { 287 | expect(params).to.have.property('CustomParameter', 'value'); 288 | }; 289 | model.deleteTable({ CustomParameter: 'value' }); 290 | }); 291 | }); 292 | 293 | }); 294 | 295 | describe('Update operators', function () { 296 | var model = new DynamoModel('my-table', schema); 297 | it('should map plain values to the PUT operator', function () { 298 | var updates = model.parseUpdates({ attribute1: 'value'}); 299 | expect(updates).to.have.property('attribute1'); 300 | expect(updates.attribute1).to.have.property('Action', 'PUT'); 301 | expect(updates.attribute1).to.have.property('Value'); 302 | expect(updates.attribute1.Value).to.have.property('S', 'value'); 303 | }); 304 | it('should map values with native operators', function () { 305 | var updates = model.parseUpdates({ attribute2: { ADD: 1 } }); 306 | expect(updates).to.have.property('attribute2'); 307 | expect(updates.attribute2).to.have.property('Action', 'ADD'); 308 | expect(updates.attribute2).to.have.property('Value'); 309 | expect(updates.attribute2.Value).to.have.property('N', '1'); 310 | }); 311 | it('should map values with MongoDB-like operators', function () { 312 | var updates = model.parseUpdates({ $inc: { attribute2: 1 } }); 313 | expect(updates).to.have.property('attribute2'); 314 | expect(updates.attribute2).to.have.property('Action', 'ADD'); 315 | expect(updates.attribute2).to.have.property('Value'); 316 | expect(updates.attribute2.Value).to.have.property('N', '1'); 317 | }); 318 | it('should throw when using unsupported MongoDB operators', function () { 319 | expect(function () { 320 | model.parseUpdates({ $rename: { attribute1: 'attributeA' } }); 321 | }).to.throw(/not supported/); 322 | }); 323 | }); 324 | 325 | describe('Conditional operators', function () { 326 | var model = new DynamoModel('my-table', schema); 327 | it('should map plain values to the EQ operator', function () { 328 | var conditions = model.parseConditions({ id: 'abc'}); 329 | expect(conditions).to.have.property('id'); 330 | expect(conditions.id).to.have.property('AttributeValueList'); 331 | expect(conditions.id.AttributeValueList).to.have.length(1); 332 | expect(conditions.id.AttributeValueList[0]).to.have.property('S', 'abc'); 333 | expect(conditions.id).to.have.property('ComparisonOperator', 'EQ'); 334 | }); 335 | it('should map values with native operators', function () { 336 | var conditions = model.parseConditions({ range: { GT: 1 }}); 337 | expect(conditions).to.have.property('range'); 338 | expect(conditions.range).to.have.property('AttributeValueList'); 339 | expect(conditions.range.AttributeValueList).to.have.length(1); 340 | expect(conditions.range.AttributeValueList[0]).to.have.property('N', '1'); 341 | expect(conditions.range).to.have.property('ComparisonOperator', 'GT'); 342 | }); 343 | it('should map values with MongoDB-like operators', function () { 344 | var conditions = model.parseConditions({ range: { $gte: 1 }}); 345 | expect(conditions).to.have.property('range'); 346 | expect(conditions.range).to.have.property('AttributeValueList'); 347 | expect(conditions.range.AttributeValueList).to.have.length(1); 348 | expect(conditions.range.AttributeValueList[0]).to.have.property('N', '1'); 349 | expect(conditions.range).to.have.property('ComparisonOperator', 'GE'); 350 | }); 351 | it('should throw when using unsupported MongoDB operators', function () { 352 | expect(function () { 353 | model.parseConditions({ range: { $ne: 1 }}); 354 | }).to.throw(/not supported/); 355 | }); 356 | it('should map values with the BETWEEN operator', function () { 357 | var conditions = model.parseConditions({ range: { $between: [1, 10] }}); 358 | expect(conditions).to.have.property('range'); 359 | expect(conditions.range).to.have.property('AttributeValueList'); 360 | expect(conditions.range.AttributeValueList).to.have.length(2); 361 | expect(conditions.range.AttributeValueList[0]).to.have.property('N', '1'); 362 | expect(conditions.range.AttributeValueList[1]).to.have.property('N', '10'); 363 | expect(conditions.range).to.have.property('ComparisonOperator', 'BETWEEN'); 364 | }); 365 | }); 366 | 367 | 368 | 369 | }); 370 | --------------------------------------------------------------------------------