Merge branch 'master' into milestones/2.0.0

changelog.md

@@ -84,6 +84,7 @@
 - [FEATURE] Support for join tables. [#877](https://github.com/sequelize/sequelize/pull/877). Thanks to janmeier.
 - [FEATURE] Support for join tables. [#877](https://github.com/sequelize/sequelize/pull/877). Thanks to janmeier.
 - [FEATURE] Support for hooks. [#894](https://github.com/sequelize/sequelize/pull/894). Thanks to durango.
 - [FEATURE] Support for hooks. [#894](https://github.com/sequelize/sequelize/pull/894). Thanks to durango.
 - [FEATURE] Support for literals and casts. [#950](https://github.com/sequelize/sequelize/pull/950). Thanks to durango.
 - [FEATURE] Support for literals and casts. [#950](https://github.com/sequelize/sequelize/pull/950). Thanks to durango.
+- [FEATURE] Model#findOrBuild. [#960](https://github.com/sequelize/sequelize/pull/960). Thanks to durango.
 - [REFACTORING] hasMany now uses a single SQL statement when creating and destroying associations, instead of removing each association seperately [690](https://github.com/sequelize/sequelize/pull/690). Inspired by [#104](https://github.com/sequelize/sequelize/issues/104). janmeier
 - [REFACTORING] hasMany now uses a single SQL statement when creating and destroying associations, instead of removing each association seperately [690](https://github.com/sequelize/sequelize/pull/690). Inspired by [#104](https://github.com/sequelize/sequelize/issues/104). janmeier
 - [REFACTORING] Consistent handling of offset across dialects. Offset is now always applied, and limit is set to max table size of not limit is given [#725](https://github.com/sequelize/sequelize/pull/725). janmeier
 - [REFACTORING] Consistent handling of offset across dialects. Offset is now always applied, and limit is set to max table size of not limit is given [#725](https://github.com/sequelize/sequelize/pull/725). janmeier
 - [REFACTORING] Moved Jasmine to Buster and then Buster to Mocha + Chai. sdepold and durango
 - [REFACTORING] Moved Jasmine to Buster and then Buster to Mocha + Chai. sdepold and durango

lib/dao-factory.js

@@ -531,6 +531,39 @@ module.exports = (function() {
     return this.build(values).save(fields)
     return this.build(values).save(fields)
   }
   }
 
 
+  DAOFactory.prototype.findOrInitialize = DAOFactory.prototype.findOrBuild = function (params, defaults) {
+    var self          = this
+      , defaultKeys   = Object.keys(defaults || {})
+      , defaultLength = defaultKeys.length
+
+    return new Utils.CustomEventEmitter(function (emitter) {
+      self.find({
+        where: params
+      }).success(function (instance) {
+        if (instance === null) {
+          var i = 0
+
+          for (i = 0; i < defaultLength; i++) {
+            params[defaultKeys[i]] = defaults[defaultKeys[i]]
+          }
+
+          var build = self.build(params)
+
+          build.hookValidate({skip: Object.keys(params)}).success(function (instance) {
+            emitter.emit('success', build, true)
+          })
+          .error(function (error) {
+            emitter.emit('error', error)
+          })
+        } else {
+          emitter.emit('success', instance, false)
+        }
+      }).error(function (error) {
+        emitter.emit('error', error)
+      })
+    }).run()
+  }
+
   DAOFactory.prototype.findOrCreate = function (params, defaults) {
   DAOFactory.prototype.findOrCreate = function (params, defaults) {
     var self = this;
     var self = this;
 
 

test/dao-factory.test.js

@@ -328,6 +328,61 @@ describe(Support.getTestDialectTeaser("DAOFactory"), function () {
     })
     })
   })
   })
 
 
+  describe('findOrInitialize', function() {
+    describe('returns an instance if it already exists', function() {
+      it('with a single find field', function (done) {
+        var self = this
+
+        this.User.create({ username: 'Username' }).success(function (user) {
+          self.User.findOrInitialize({
+            username: user.username
+          }).success(function (_user, initialized) {
+            expect(_user.id).to.equal(user.id)
+            expect(_user.username).to.equal('Username')
+            expect(initialized).to.be.false
+            done()
+          })
+        })
+      })
+
+      it('with multiple find fields', function(done) {
+        var self = this
+
+        this.User.create({ username: 'Username', data: 'data' }).success(function (user) {
+          self.User.findOrInitialize({
+            username: user.username,
+            data: user.data
+          }).success(function (_user, initialized) {
+            expect(_user.id).to.equal(user.id)
+            expect(_user.username).to.equal('Username')
+            expect(_user.data).to.equal('data')
+            expect(initialized).to.be.false
+            done()
+          })
+        })
+      })
+
+      it('builds a new instance with default value.', function(done) {
+        var data = {
+            username: 'Username'
+          },
+          default_values = {
+            data: 'ThisIsData'
+          }
+
+        this.User.findOrInitialize(data, default_values).success(function(user, initialized) {
+          expect(user.id).to.be.null
+          expect(user.username).to.equal('Username')
+          expect(user.data).to.equal('ThisIsData')
+          expect(initialized).to.be.true
+          expect(user.isNewRecord).to.be.true
+          expect(user.isDirty).to.be.true
+          done()
+        })
+      })
+    })
+  })
+
   describe('findOrCreate', function () {
   describe('findOrCreate', function () {
     it("Returns instance if already existent. Single find field.", function(done) {
     it("Returns instance if already existent. Single find field.", function(done) {
       var self = this,
       var self = this,