When should I use jQuery deferred's "then" method and when should I use the "pipe" method?

Since jQuery 1.8 .then behaves the same as .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

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 deferred.pipe() method.

The examples below might still be helpful to some.

They serve different purposes:

• .then() is to be used whenever you want to work with the result of the process, i.e. as the documentation says, when the deferred object is resolved or rejected. It is the same as using .done() or .fail().

• You'd use .pipe() to (pre)filter the result somehow. The return value of a callback to .pipe() will be passed as argument to the done and fail callbacks. It can also return another deferred object and the following callbacks will be registered on this deferred.

  That is not the case with .then() (or .done(), .fail()), the return values of the registered callbacks are just ignored.

So it is not that you use either .then() or .pipe(). You could use .pipe() for the same purposes as .then() but the converse does not hold.

Example 1

The result of some operation is an array of objects:

[{value: 2}, {value: 4}, {value: 6}]

and you want to compute the minimum and maximum of the values. Lets assume we use two done callbacks:

deferred.then(function(result) {
    // result = [{value: 2}, {value: 4}, {value: 6}]

    var values = [];
    for(var i = 0, len = result.length; i < len; i++) {
        values.push(result[i].value);
    }
    var min = Math.min.apply(Math, values);

   /* do something with "min" */

}).then(function(result) {
    // result = [{value: 2}, {value: 4}, {value: 6}]

    var values = [];
    for(var i = 0, len = result.length; i < len; i++) {
        values.push(result[i].value);
    }
    var max = Math.max.apply(Math, values);

   /* do something with "max" */ 

});

In both cases you have to iterate over the list and extract the value from each object.

Wouldn't it be better to somehow extract the values beforehand so that you don't have to do this in both callbacks individually? Yes! And that's what we can use .pipe() for:

deferred.pipe(function(result) {
    // result = [{value: 2}, {value: 4}, {value: 6}]

    var values = [];
    for(var i = 0, len = result.length; i < len; i++) {
        values.push(result[i].value);
    }
    return values; // [2, 4, 6]

}).then(function(result) {
    // result = [2, 4, 6]

    var min = Math.min.apply(Math, result);

    /* do something with "min" */

}).then(function(result) {
    // result = [2, 4, 6]

    var max = Math.max.apply(Math, result);

    /* do something with "max" */

});

Obviously this is a made up example and there are many different (maybe better) ways to solve this problem, but I hope it illustrates the point.

Example 2

Consider Ajax calls. Sometimes you want to initiate one Ajax call after a previous one completes. One way is to make the second call inside a done callback:

$.ajax(...).done(function() {
    // executed after first Ajax
    $.ajax(...).done(function() {
        // executed after second call
    });
});

Now lets assume you want to decouple your code and put these two Ajax calls inside a function:

function makeCalls() {
    // here we return the return value of `$.ajax().done()`, which
    // is the same deferred object as returned by `$.ajax()` alone

    return $.ajax(...).done(function() {
        // executed after first call
        $.ajax(...).done(function() {
            // executed after second call
        });
    });
}

You'd like to use the deferred object to allow other code which calls makeCalls to attach callbacks for the second Ajax call, but

makeCalls().done(function() {
    // this is executed after the first Ajax call
});

would not have the desired effect as the second call is made inside a done callback and not accessible from the outside.

The solution would be to use .pipe() instead:

function makeCalls() {
    // here we return the return value of `$.ajax().pipe()`, which is
    // a new deferred/promise object and connected to the one returned
    // by the callback passed to `pipe`

    return $.ajax(...).pipe(function() {
        // executed after first call
        return $.ajax(...).done(function() {
            // executed after second call
        });
    });
}

makeCalls().done(function() {
    // this is executed after the second Ajax call
});

By using .pipe() you can now make it possible to append callbacks to the "inner" Ajax call without exposing the actual flow/order of the calls.

In general, deferred objects provide an interesting way to decouple your code :)

There is no case where you MUST use then() over pipe(). You can always choose to ignore the value that pipe() will pass in. There might be a slight performance hit for using pipe -- but it is unlikely to matter.

So it might seem like you could simply always use pipe() in both cases. However, by using pipe(), you are communicating to other people reading your code (including yourself, six months from now) that there is some importance to the return value. If you're discarding it, you're violating this semantic construct.

It's like having a function that returns a value that is never used: confusing.

So use then() when you should, and pipe() when you should...

In fact it turns out that the difference between .then() and .pipe() has been deemed unnecessary and they have been made to be the same as of jQuery version 1.8.

From a comment by jaubourg in jQuery's bug tracker ticket #11010 "MAKE DEFERRED.THEN == DEFERRED.PIPE LIKE PROMISE/A":

In 1.8, we will remove the old then and replace it with current pipe. But the very sadening consequence is that we'll have to tell people to use the non-standard done, fail and progress, because the proposal doesn't provide simple, EFFICIENT, mean to just add a callback.

^{(emphassis mine)}