Promises for operation hooks

[bajtos]

• Allow the observer functions passed to ModelBaseClass.observe to return a promise instead of calling the callback.
• Support both promise and callback styles in ModelBaseClass.notifyObserversOf.

Related: strongloop/strong-remoting#179 and #447
Connect strongloop/loopback#418

/to @raymondfeng Please review.
/cc @partap This patch provides the infrastructure needed for promise support, it's based on my comments in your PR. My plan is to land this PR first, so that you can use this infrastructure in your PR.

[raymondfeng]

LGTM

[ritch]

@bajtos are you updating the docs / examples (atleast creating examples) for this?

[bajtos]

@ritch Good catch, I added a task to strongloop/loopback#418 to update docs & examples once we have all pieces in place.

[ctcampb3]

@bajtos, I see that Using promises says you can use promises with Operation hooks. But I'm missing where the example is. It took me a few days to figure out that you don't need to return next() in the promise chain. Is there any way we could have an example out there so others don't go through the same struggle? Returning next caused the Operation hooks to be called twice.

[bajtos]

@ctcampb3 I am sorry to hear that you lost so much time trying to figure this out :( Perhaps the following example would be a good one to update?
https://github.com/strongloop/loopback-example-app-logic#define-a-model-operation-hook

BTW I think we have a similar problem in remoting hooks too, see strongloop/strong-remoting#406 (comment) and strongloop/strong-remoting#406 (comment). It may be possible to improve our code to detect the situation where next was called and a promise was returned too and warn the user.

[ctcampb3]

@bajtos , I think those issues look pretty similar. For the example I thought it might be good to have it on the Using promises page under the LoopBack support for promises section. Having an example with a warning here would make it more clear.
Something generic like:

When returning a Promise instead of a callback the callback function should not be called at all. For example:

MyModel.observe('before save', function filterProperties(ctx, next) {
  // Resolving with a callback
  next();
});
MyModel.observe('before save', function filterProperties(ctx, next) {
  // Resolving with a promise
  return Promise.resolve();
});

[bajtos]

@ctcampb3 makes sense. Would you mind contributing this doc improvement yourself? See this page to get you started: http://loopback.io/doc/en/contrib/doc-contrib.html Please mention my handle in the pull request to make sure I notice it.