Added api refernece for promises, added a silent option to dao.save

docs/markdox.js

@@ -153,7 +153,9 @@ if (program.file) {
     {file:'lib/query-chainer.js', output: 'API-Reference-QueryChainer'},
     {file:'lib/emitters/custom-event-emitter.js', output: 'API-Reference-EventEmitter'},
     {file:'lib/hooks.js', output: 'API-Reference-Hooks'},
-    {file:'lib/associations/mixin.js', output: 'API-Reference-Associations'}
+    {file:'lib/associations/mixin.js', output: 'API-Reference-Associations'},
+    {file:'lib/promise.js', output: 'API-Reference-Promise'},
+    {file:'lib/transaction.js', output: 'API-Reference-Transaction'}
   ];
 }
 

lib/dao.js

@@ -398,6 +398,7 @@ module.exports = (function() {
    * @param {Array} [fields] An optional array of strings, representing database columns. If fields is provided, only those columns will be validation and saved.
    * @param {Object} [options]
    * @param {Object} [options.fields] An alternative way of setting which fields should be persisted
+   * @param {Boolean} [options.silent=false] If true, the updatedAt timestamp will not be updated. 
    * @param {Transaction} [options.transaction]
    *
    * @return {Promise}
@@ -426,14 +427,20 @@ module.exports = (function() {
       , updatedAtAttr  = this.Model._timestampAttributes.updatedAt
       , createdAtAttr  = this.Model._timestampAttributes.createdAt
 
-    if (options.fields) {
-      if (updatedAtAttr && options.fields.indexOf(updatedAtAttr) === -1) {
-        options.fields.push(updatedAtAttr)
-      }
+    if (updatedAtAttr && options.fields.indexOf(updatedAtAttr) === -1) {
+      options.fields.push(updatedAtAttr)
+    }
 
-      if (createdAtAttr && options.fields.indexOf(createdAtAttr) === -1 && this.isNewRecord === true) {
-        options.fields.push(createdAtAttr)
-      }
+    if (options.silent === true) {
+      // UpdateAtAttr might have been added as a result of Object.keys(Model.attributes). In that case we have to remove it again
+      Utils._.remove(options.fields, function (val) {
+        return val === updatedAtAttr
+      })
+      updatedAtAttr = false
+    }
+
+    if (this.isNewRecord === true && createdAtAttr && options.fields.indexOf(createdAtAttr) === -1) {
+      options.fields.push(createdAtAttr)
     }
 
     return self.hookValidate({

lib/emitters/custom-event-emitter.js

@@ -138,7 +138,7 @@ module.exports = (function() {
    * ```
    *
    * @param {function} onError
-   * @metohd error
+   * @method error
    * @alias fail
    * @alias failure
    * @return this

lib/promise.js

@@ -6,6 +6,14 @@ var util            = require("util")
   , INTERNAL        = function() {}
   , async           = require("bluebird/js/main/async.js")
 
+/**
+ * A slightly modified version of bluebird promises. This means that, on top of the methods below, you can also call all the methods listed on the link below.
+ *
+ * The main difference is that sequelize promises allows you to attach a listener that will be called with the generated SQL, each time a query is run.
+ * 
+ * @mixes https://github.com/petkaantonov/bluebird/blob/master/API.md
+ * @class Promise
+ */
 var SequelizePromise = function(resolver) {
   var self = this;
 
@@ -83,16 +91,12 @@ SequelizePromise.prototype._then = function (
     ret._setBoundTo(this._boundTo);
   }
 
-  /*
-   * Start of sequelize specific 
-   * Needed to transfer sql events accross .then() calls
-   */
+  // Start of sequelize specific 
+  // Needed to transfer sql events accross .then() calls
   if (this.proxySql && ret && ret.emit) {
     this.proxySql(ret);
   }
-  /*
-   * End of sequelize specific 
-   */
+  // End of sequelize specific 
 
   var callbackIndex = this._addCallbacks(didFulfill, didReject, didProgress, ret, receiver);
 
@@ -120,6 +124,12 @@ SequelizePromise.prototype._settlePromiseAt = function (index) {
   return Promise.prototype._settlePromiseAt.apply(this, arguments);
 };
 
+/**
+ * Listen for events, event emitter style. Mostly for backwards compat. with EventEmitter
+ * 
+ * @param {String} evt
+ * @param {Function} fct
+ */
 SequelizePromise.prototype.on = function(evt, fct) {
   if (evt === 'success') {
     this.then(fct);
@@ -134,6 +144,11 @@ SequelizePromise.prototype.on = function(evt, fct) {
   return this;
 }
 
+/**
+ * Emit an event from the emitter
+ * @param {string} type The type of event
+ * @param {any}    value(s)* All other arguments will be passed to the event listeners
+ */
 SequelizePromise.prototype.emit = function(evt) {
   var args = arguments.length > 1 ? Array.prototype.slice.call(arguments, 1) : [];
 
@@ -167,7 +182,6 @@ SequelizePromise.prototype.emit = function(evt) {
  * @alias ok
  * @return this
  */
-
 SequelizePromise.prototype.success =
 SequelizePromise.prototype.ok = function(fct) {
   if (fct.length > 1) {
@@ -187,12 +201,11 @@ SequelizePromise.prototype.ok = function(fct) {
  * ```
  *
  * @param {function} onError
- * @metohd error
+ * @method error
  * @alias fail
  * @alias failure
  * @return this
  */
-
 SequelizePromise.prototype.failure =
 SequelizePromise.prototype.fail =
 SequelizePromise.prototype.error = function(fct) {
@@ -239,9 +252,9 @@ SequelizePromise.prototype.sql = function(fct) {
 /**
  * Proxy every event of this promise to another one.
  *
- * @param  {SequelizePromise} The promise that should receive the events.
- * @param  {Object}       [options]
- * @param  {Array}        [options.events] An array of the events to proxy. Defaults to sql, error and success
+ * @param  {SequelizePromise} promise The promise that should receive the events.
+ * @param  {Object}           [options]
+ * @param  {Array}            [options.events] An array of the events to proxy. Defaults to sql, error and success
  * @return this
  */
 SequelizePromise.prototype.proxy = function(promise, options) {

lib/sequelize.js

@@ -2,7 +2,6 @@ var url                = require("url")
   , Path               = require("path")
   , Utils              = require("./utils")
   , DAOFactory         = require("./dao-factory")
-  , DAOValidator       = require("./dao-validator")
   , DataTypes          = require('./data-types')
   , DAOFactoryManager  = require("./dao-factory-manager")
   , QueryInterface     = require("./query-interface")
@@ -174,7 +173,14 @@ module.exports = (function() {
    * @property Utils
    * @see {Utils}
    */
-  Sequelize.Utils = Utils
+  Sequelize.prototype.Utils = Sequelize.Utils = Utils
+
+  /**
+   * A modified version of bluebird promises, that allows listening for sql events
+   * @property Promise
+   * @see {Promise}
+   */
+  Sequelize.prototype.Promise = Sequelize.Promise = Promise
 
   Sequelize.QueryTypes = QueryTypes
 
@@ -825,7 +831,5 @@ module.exports = (function() {
     }
   }
 
-  Sequelize.Promise = Promise
-
   return Sequelize
 })()

test/dao.test.js

@@ -849,6 +849,27 @@ describe(Support.getTestDialectTeaser("DAO"), function () {
       }, 1000)
     })
 
+    it('does not update timestamps when passing silent=true', function() {
+      this.clock = sinon.useFakeTimers(new Date().getTime());
+
+      var self = this
+      return this.User.create({ username: 'user' }).then(function (user) {
+        var updatedAt = user.updatedAt
+        
+        self.clock.tick(30000);
+
+        return user.updateAttributes({
+          username: 'userman'
+        }, {
+          silent: true
+        }).then(function () {
+          expect(user.updatedAt).to.equal(updatedAt)
+
+          self.clock.restore();
+        })
+      })
+    })
+
     it('updates with function and column value', function (done) {
       var self = this