[ci skip] update hooks docs

docs/docs/hooks.md

@@ -4,31 +4,31 @@ Hooks (also known as callbacks or lifecycle events), are functions which are cal
 
 ```    
 (1) 
-  beforeBulkCreate(daos, fields, fn) 
-  beforeBulkDestroy(daos, fields, fn) 
-  beforeBulkUpdate(daos, fields, fn)
+  beforeBulkCreate(instances, options, fn) 
+  beforeBulkDestroy(instances, options, fn) 
+  beforeBulkUpdate(instances, options, fn)
 (2) 
-  beforeValidate(dao, fn)
+  beforeValidate(instance, options, fn)
 (-)
   validate
 (3) 
-  afterValidate(dao, fn)
+  afterValidate(instance, options, fn)
 (4) 
-  beforeCreate(dao, fn)
-  beforeDestroy(dao, fn)
-  beforeUpdate(dao, fn)
+  beforeCreate(instance, options, fn)
+  beforeDestroy(instance, options, fn)
+  beforeUpdate(instance, options, fn)
 (-) 
   create 
   destroy 
   update
 (5) 
-  afterCreate(dao, fn) 
-  afterDestroy(dao, fn)
-  afterUpdate(dao, fn) 
+  afterCreate(instance, options, fn) 
+  afterDestroy(instance, options, fn)
+  afterUpdate(instance, options, fn) 
 (6) 
-  afterBulkCreate(daos, fields, fn) 
-  afterBulkDestory(daos, fields, fn) 
-  afterBulkUpdate(daos, fields, fn)
+  afterBulkCreate(instances, options, fn) 
+  afterBulkDestory(instances, options, fn) 
+  afterBulkUpdate(instances, options, fn)
 ```
 
 ## Declaring Hooks
@@ -46,11 +46,11 @@ var User = sequelize.define('User', {
   }
 }, {
   hooks: {
-    beforeValidate: function(user, fn) {
+    beforeValidate: function(user, options, fn) {
       user.mood = 'happy'
       fn(null, user)
     },
-    afterValidate: function(user, fn) {
+    afterValidate: function(user, options, fn) {
       user.username = 'Toni'
       fn(null, user)
     }
@@ -66,12 +66,12 @@ var User = sequelize.define('User', {
   }
 })
  
-User.hook('beforeValidate', function(user, fn) {
+User.hook('beforeValidate', function(user, options, fn) {
   user.mood = 'happy'
   fn(null, user)
 })
  
-User.hook('afterValidate', function(user) {
+User.hook('afterValidate', function(user, options) {
   return sequelize.Promise.reject("I'm afraid I can't let you do that!")
 })
  
@@ -84,12 +84,12 @@ var User = sequelize.define('User', {
   }
 })
  
-User.beforeValidate(function(user) {
+User.beforeValidate(function(user, options) {
   user.mood = 'happy'
   return sequelize.Promise.resolve(user)
 })
  
-User.afterValidate(function(user, fn) {
+User.afterValidate(function(user, options, fn) {
   user.username = 'Toni'
   fn(null, user)
 })
@@ -108,18 +108,17 @@ afterCreate / afterUpdate / afterDestroy
 
 ```js
 // ...define ...
-User.beforeCreate(function(user, fn) {
+User.beforeCreate(function(user) {
   if (user.accessLevel > 10 && user.username !== "Boss") {
-    return fn("You can't grant this user an access level above 10!")
- }
- return fn()
+    throw new Error("You can't grant this user an access level above 10!")
+  }
 })
 ```
 
 This example will emit an error:
     
 ```js
-User.create({username: 'Not a Boss', accessLevel: 20}).error(function(err) {
+User.create({username: 'Not a Boss', accessLevel: 20}).catch(function(err) {
   console.log(err) // You can't grant this user an access level above 10!
 })
 ```
@@ -206,6 +205,29 @@ DELETE FROM `table` WHERE associatedIdentifiier = associatedIdentifier.primaryKe
 
 However, adding `hooks: true` explicitly tells Sequelize that optimization is not of your concern and will perform a `SELECT` on the associated objects and destroy each instance one by one in order to be able to call the hooks with the right parameters.
 
+## Promises and callbacks
+
+Sequelize will look at the function length of your hook callback to determine whether or not you're using callbacks or promises.
+
+```js
+// Will stall if the condition isn't met since the callback is never called
+User.beforeCreate(function(user, options, callback) {
+  if (user.accessLevel > 10 && user.username !== "Boss") {
+    return callback("You can't grant this user an access level above 10!");
+  }
+});
+
+// Will never stall since returning undefined will act as a resolved promise with an undefined value
+User.beforeCreate(function(user, options) {
+  if (user.accessLevel > 10 && user.username !== "Boss") {
+    return throw new Error("You can't grant this user an access level above 10!");
+  }
+  if (something) {
+    return Promise.reject();
+  }
+});
+```
+
 ## A Note About Transactions
 
 Note that many model operations in Sequelize allow you to specify a transaction in the options parameter of the method. If a transaction _is_ specified in the original call, it will be present in the options parameter passed to the hook function. For example, consider the following snippet:
@@ -214,7 +236,7 @@ Note that many model operations in Sequelize allow you to specify a transaction
 // Here we use the promise-style of async hooks rather than
 // the callback.
 User.hook('afterCreate', function(user, options) {
-  // 'trans' will be available in options.transaction
+  // 'transaction' will be available in options.transaction
  
   // This operation will be part of the same transaction as the 
   // original User.create call.
@@ -229,12 +251,12 @@ User.hook('afterCreate', function(user, options) {
 });
  
  
-sequelize.transaction(function(trans) {
+sequelize.transaction(function(t) {
   User.create({
     username: 'someguy',
     mood: 'happy'
   }, {
-    transaction: trans
+    transaction: t
   });
 });
 ```
@@ -245,4 +267,4 @@ If we had not included the transaction option in our call to `User.update` in th
 
 It is very important to recognize that sequelize may make use of transactions internally for certain operations such as `Model.findOrCreate`. If your hook functions execute read or write operations that rely on the object's presence in the database, or modify the object's stored values like the example in the preceding section, you should always specify `{ transaction: options.transaction }`.
 
-If the hook has been called in the process of a transacted operation, this makes sure that your dependent read/write is a part of that same transaction. If the hook is not transacted, you have simply specified `{ transaction: null }` and can expect the default behaviour.
+If the hook has been called in the process of a transacted operation, this makes sure that your dependent read/write is a part of that same transaction. If the hook is not transacted, you have simply specified `{ transaction: null }` and can expect the default behaviour.
\ No newline at end of file