Update: This question is now out of date as the documentation is accurate and up to date.
I’ve been exploring the jQuery Deferred/Promise API for a bit and I’m very confused about the differences between
then() philosophically and in the jQuery documentation. I’ve found that pipe() is just an alias for then() as of jQuery 1.8.
From jQuery source:
// Keep pipe for back-compat promise.pipe = promise.then;
Yet the documentation is completely different for
then() as they supposedly have entirely different uses.
Description: Add handlers to be called when the Deferred object is resolved or rejected.
Description: Utility method to filter and/or chain Deferreds.
I understand that historically they had slightly different behavior, but in the entirety of the documentation for pipe or the documentation for then, it doesn’t even say that these two functions do the exact same thing now.
So, here’s my two part question:
- Why does the documentation between
then()differ as of jQuery 1.8?
- Why does
then()return a new deferred object? This behavior is completely undocumented (the docs just say it returns a Deferred, not that it’s a new one). I understand that it has utility in doing so (namely to implement all of
pipe()‘s features), but philosophically why is it the case? It’s unnecessary given the description of
then()(to attach handlers).
I’ll even go so far as to say the
then() docs are misleading and inaccurate:
Since deferred.then returns the deferred object, other methods of the deferred object can be chained to this one, including additional .then() methods.
Maybe it’s just vague, but it implies it returns the deferred object you called
then() on for chaining, when in reality it returns an entirely new object….
Seems the documentation is simply wrong/out of date! So that answers why the documentation makes no mention of them being the same thing. However, my second question still stands. Is the reason
then() returns a new deferred simply so that it and
pipe() can be made equivalent?
Practice As Follows
The documentation update for jQuery 1.8 is not online yet.
According to this recent blog post:
We’re in the process of updating the API documentation for all the
changes to 1.8, but for now you can refer back to the changelog in the
jQuery 1.8 announcement to see what’s changed.
then() returns a new
Deferred because it is equivalent to
pipe() now. I’m pretty confident the documentation update will clarify this soon.
Further update for completeness: The documentation was recently updated and now says for pipe():
Deprecation Notice: As of jQuery 1.8, the
deferred.pipe()method is deprecated. The
deferred.then()method, which replaces it, should
be used instead.
And for then():
Prior to jQuery 1.8, the arguments could be a function or an array of functions.
As of jQuery 1.8, the
deferred.then()method returns a new promise that can filter the status and values of a deferred through a
function, replacing the now-deprecated
failFilterfunctions filter the original deferred’s
resolved / rejected status and values. The
filters any calls to the original deferred’s
methods. These filter functions can return a new value to be passed
along to the promise’s
.fail()callbacks, or they can
return another observable object (Deferred, Promise, etc) which will
pass its resolved / rejected status and values to the promise’s
callbacks. If the filter function used is
null, or not specified,
the promise will be resolved or rejected with the same values as the