Add convenience methods like .always()

[briancavalier]

Currently, when.js's promise provides .then(), so if you want to register the same callback to run whether the promise is resolved or rejected, you have to pass it explicitly as both the callback and errback to when() or .then(). Both jQuery Deferred, and Q's promises provide convenience methods for this.

Here's how you have to do it with when.js currently:

promise.then(callback, callback);
// or
when(promise, callback, callback);

That's not horrible, but this seems like a nice convenience:

promise.always(callback);
// or
when.always(promise, callback);

It might be interesting to provide both promise.always(callback) and when.always(promise, callback) so that when.always() can be used with other promise implementations. Also, since something like promise.always() is not part of the Promises/A spec, relying on it would mean tying your code to when.js's promise implementation. Using when.always(promise) is a bit more decoupled.

Seems like this also opens the door for a method that registers only a rejection handler. For example, to do that now:

promise.then(null, errback);
// or
when(promise, null, errback);

Which is kind of ugly, and might cause a "WTF". So, could provide something like:

promise.rejected(errback);
// or
when.rejected(promise, errback);

This seems like a much more limited use case to me, though.

[sifu]

an .addErrback() or .fail() (see eg. http://api.jquery.com/deferred.fail/) could be a nice addition. there is nothing you couldn't do with .then(), but i use it all the time to make code more readable.

[sifu]

oh and +1 for .always()

[briancavalier]

Hey @sifu, thanks for the feedback.

I do have a concern about .addErrback()/.fail(), and maybe it applies to .always() as well. Do you think there will be confusion between Promises/A semantics and jQuery Deferred semantics? For example:

var success, failed;
success = failed = function(val) {
    return val + 1;
};

function log(val) {
    console.log(val);
}

// First, jQuery Deferred
var d = $.Deferred();

// This prints 1 because jQuery Deferred isn't Promises/A
// then(), fail(), etc. return `this`, and all handlers receive 1
// no matter where in the "chain" they fall
d.then(success).fail(failed).fail(log);
d.reject(1);

// Now when.js
// Suppose when.js's promises support .fail() - would be similar for always()
d = when.defer();

// This prints 2 because of Promises/A forwarding
// then(), fail() return a new Promise that receives the result
// of the previous Promise
d.then(success).fail(failed).fail(log);
d.reject(1);

So, in the second example, some may feel that it reads as if you are registering the success and failed handlers with the same promise, but by Promises/A semantics, you really aren't. The deferred is rejected with the value 1, which is received by the first fail() handler, which returns a new result of val+1, which would be forwarded to the next fail() handler, thus logging 2.

Maybe it's just a documentation issue, but I do want to be very careful here not to introduce any APIs that might cause a lot of confusion (and possibly have to rip them out later!)

Thoughts?

[sifu]

i think i agree with your concerns.

my problem is, that i'm so used to the original deferreds API, because i use deferreds since about a decade (with twisted-python) and promises since about 1.5-2 years, that my thoughts on that matter are very biased.

btw. always thought the deferred methods .addCallback, .addErrback, addBoth, ... are way clearer than the promised equivalents like .then and all the rest.

i also think i withdraw my "+1" for .always( ) :)
i just figured out, that i use it quite often, but only for async tests inside qunit. and that one use-case is not enough to vote for it.

it is a shame that jQuery opted for a non-standards API. since jQuery is so common, their API will be the one most javascript programmers will get familiar with. :(

[briancavalier]

Thanks, really appreciate all the feedback so far, @sifu.

This is a tough issue, for sure--trying to provide convenience while avoiding confusion, and I totally agree that jQuery's choices (and popularity) make it even tougher. The really unfortunate thing about jQuery Deferred, IMHO, is that they chose to look like Promises/A, but not act like it, i.e. typeof $.Deferred().then == 'function', so you can't rely on the feature test.

I think we need more discussion/thinking on this issue before we know what is best. I'll keep the issue open until we decide something, but we probably won't implement anything any time soon.

[sifu]

btw. i don't know if you know the reasoning behing jquerys .pipe() vs .then():

they had concerns, that always returning a new promise from .then() would be a performance problem. and they talked to the dojo guys about how to resolve that problem and figured that a new method .pipe() would be the best solution. thats also the reason, why they introduced this method one version later.

imho a better way would have been to do it the other way around. provide a method, that doesn't return a new promise (which you can opt in to use if you have performance issues), but implement .then() like it is supposed to be.

[briancavalier]

I had heard that once before, but can't remember where. Pretty interesting. I know jQuery has their own goals and priorities, so I can certainly appreciate that performance might be a top priority. But, yeah, I do agree that "doing it the other way around" may have been a better approach, at least from the perspective of being friendly to Promises/A.

I think (hope) the fact that when.js assimilates jQuery Deferred now gives jQuery devs a good option if they want Promises/A. They can use $.Deferred if they want, but then can call when() if they want to guarantee forwarding. They can also return when($.Deferred()) if they want to be nice and return compliant promises from an API.

We've been using when.js as a part of wire.js (https://github.com/briancavalier/wire), and also in application-level code, on a big project (300+ AMD modules) for the past year, and we haven't yet had any perf problems that we could attribute to promises. I don't have any hard numbers, but I feel like the performance is at least good enough that application code will probably be more of a perf hit than promises.

[briancavalier]

I think I'm back to feeling like .always() and .fail() might be a good thing. It seems like calling .fail(...).fail(...), like in my example above, might be pretty rare. I can't think of when I've ever done that. A problem that might trick devs more often might be something like this:

when(computeResult(),
    handleResult,
    handleFailure);

In this case, if computeResult() fails, then we're ok--handleFailure will be called. However, if handleResult fails, handleFailure will not be called since promises guarantee that either the callback or errback will be called, but never both. It's basically equivalent to this try/catch, which makes the situation a bit more obvious:

var result;
try {
    result = computeResult();
} catch (e) {
    handleFailure(e);
}

handleSuccess(result);

So, if when.js provides a .fail(), it might be provide a more intuitive way of dealing with that situation:

when(computeResult(),
    handleResult)
    .fail(handleFailure);

In that case, because of forwarding, handleFailure will be called when either computeResult or handleResult throws or rejects. Of course, you can do that with just .then(), but it's uglier, imho:

when(computeResult(),
    handleResult)
    .then(null, handleFailure);

I'm still torn, but it seems like the right thing to do is to pick the scenarios that are most likely to cause headaches, and provide nice ways of dealing with those, and then let documentation handle other, less-likely scenarios (like .fail().fail()).

Any thoughts?

[sifu]

huch, i just realize, that i never thought much about, if handleFailure gets called in case handleResult has an error (when you add both to .then at once). i almost never attach both, and always have a single error handler at the bottom of my promise chain.
but on the first glance one definitely might think the handleFailure would be called.

so a .fail() would make more people use success and error handler separately and therefore avoid the issue.

and i can't recall a single scenario, where i wanted to construct something to the liking of .fail().fail().

i again have to say, that i preferred .addCallback .addErrback, back in the twisted-python days :) why didn't promises continued to use this naming convention... :/

btw 300+ modules sound big. wow! what does the app do?
and i also never had an performance issue related to promises/deferreds.

[briancavalier]

Coincidentally, I just got tripped up by this, and had to end up writing some code that looks like:

when(doStuff(), doOtherStuff /*, cleanup */) // don't call cleanup here, since doOtherStuff may fail!
    .then(cleanup, cleanup);

It'd sure would have been nice to write that like this:

when(doStuff(), doOtherStuff)
    .always(cleanup);

I'm curious about addCallback and addErrback. Do you feel like they are more intuitive solely because of their names, or because they promote writing code like:

promise.addCallback(handleSuccess);
promise.addErrback(handleFailed);

Do Twisted's Deferreds/Promises support chaining and forwarding? If you have pointers to some good examples or tutorials, I'd love to take a look and get a feel for how Twisted's Deferreds work.

The 300+ module app was one that @unscriptable and I worked on together starting back in November 2010. The company is LifeIMAGE, and they do cloud-based medical image sharing. The app was their front-end for uploading, viewing, managing, and securely sharing medical images in a workflow across doctors, hospitals, etc. It was highly visual and interactive, so most of the modules were Views that had sub-modules for their HTML template, CSS, JS view controller, and i18n. Cool stuff, and a really fun project.

[sifu]

i prefere addCallback / addErrback because of both,

and twisteds deferreds work differently to promises in that they don't return a new deferred/promise like .then does, but the state is passed on to the next callback/errback, so the effect is similar and easier.

i don't use twisted anymore, but i think http://twistedmatrix.com/documents/current/core/howto/defer.html is still the best explanation.

[briancavalier]

Very interesting, and thanks for the link--I'll definitely take a look.

[briancavalier]

Very good read about twisted deferreds! Thanks again for the link.

I'm putting this back on the table for 1.1.0, now that I think the benefits outweigh the drawbacks, and the use cases where always() is helpful seem to be more likely than ones that might get you into trouble.