Add 'finally' support to promises

[tomwidmer]

Currently it's awkward to write cleanup code that should be called when a promise completes, regardless of the result of the promise, and which passes on the existing result of the promise (e.g. resolved value, error or cancel reason). For example, https://github.com/kriskowal/q has a similar feature in the 'fin' function.

The workaround is to repeat the code. e.g.

var newPromise = promise.then({
  success:function(result) { 
    mycleanupfunc();
    return result;
  },
  failure:function(error) {
    mycleanupfunc();
    throw error;
  },
  cancel:function(reason) {
    mycleanupfunc();
    // any other way to propogate cancellation?
    var deferred = new Deft.promise.Deferred();
    deferred.cancel(reason);
    return deferred.getPromise();
  });

The ideal would be:

var newPromise = promise.fin(mycleanupfunc);

or a similar method name (such as cleanup). If the finally function throws, that should replace the existing promise result with that error (the same way that finally clauses generally work).

[johnyanarella]

Hey Tom,

The next release (v0.9) of Deft JS incorporates a number of changes to the Promises API.

• The Promises API now conforms to the Promises/A+ specification, a newer specification that irons out some of the previous areas of ambiguity to ensure interoperability between Promise implementations
  • onFulfilled and onRejected handlers are now guaranteed to be called in a future turn of the event loop (eliminating an entire class of runtime errors in applications that did not anticipate that these handlers were sometimes called immediately).
  • Deft JS's Promises now pass the Promises/A+ Test Suite v1.3.1.
• Improved handling of empty Arrays in the Promise aggregate utility methods (all(), any(), map(), reduce(), etc.) (See #74)
• Improved error handling and notification for all Promise utility methods.
• Promise API now has complete unit test coverage.
• Promise.done() was added to allow developers to avoid silent rejections by rethrowing unhandled rejections - similar to Q.done() (See #83)
• The previous overly verbose logging implementation was replaced with a log() method that can be used anywhere in a Promise chain to log detail relevant to the developer (See #61)

There are some breaking changes (the last such changes to the Promise API anticipated on our way to v1.0):

• Cancel handlers have been removed
  • cancellation is now a rejection (aka failure) with a CancellationError, which allows for propagation and recovery
• Progress handler registration and propagation logic were rewritten to support progress value transformation
• Deferred and Promise API redundancies have been eliminated
  • ex. deferred.then() is now accomplished via deferred.promise.then()

and, to the specific concern you raised in this issue:

• Promise.always() was rewritten to eliminate unintended side-effects and provide 'finally'-like functionality (See #84).

I believe the new Promise.always() implementation addresses your requirements:

• called regardless of whether the originating Promise's resolves or rejects
• propagates the originating resolution or rejection value, ignoring any return value from the handler passed to always()
  • propagates any error thrown by the handler passed to always()

Hope that helps! Please let us know if you encounter any issues with the new Promise API. We appreciated your previous bug reports, they helped us improve the Promise API as described above.

[johnyanarella]

I should note that a preview of v0.9 (including all of the Promise features mentioned above) is available in the master branch right now.

[tomwidmer]

Great, thanks - I should have checked the latest updates first since I was aware you've been enhancing promises recently.

[johnyanarella]

Not a problem. Let me know if you find any other potential gaps in the API.