deferred.then()

Categories: Deferred Object

deferred.then( doneFilter [, failFilter ] [, progressFilter ] )Returns: Promise

Description: Add handlers to be called when the Deferred object is resolved, rejected, or still in progress.

Prior to jQuery 1.8, the arguments could be a function or an array of functions.

For all signatures, the arguments can be null if no callback of that type is desired. Alternatively, use .done(), .fail() or .progress() to set only one type of callback without filtering status or values.

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 doneFilter and failFilter functions filter the original deferred's resolved / rejected status and values. The progressFilter function filters any calls to the original deferred's notify or notifyWith methods. These filter functions can return a new value to be passed along to the promise's .done() or .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 original.

Callbacks are executed in the order they were added. Since deferred.then returns a Promise, other methods of the Promise object can be chained to this one, including additional .then() methods.

Examples:

Since the jQuery.get method returns a jqXHR object, which is derived from a Deferred object, we can attach handlers using the .then method.

1
2
3
4
5
6
7
 
$.get( "test.php" ).then(
  function() {
    alert( "$.get succeeded" );
  }, function() {
    alert( "$.get failed!" );
  }
);

Filter the resolve value:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>deferred.then demo</title>
  <script src="https://code.jquery.com/jquery-3.7.1.js"></script>
</head>
<body>
 
<button>Filter Resolve</button>
<p></p>
 
<script>
var filterResolve = function() {
  var defer = $.Deferred(),
    filtered = defer.then(function( value ) {
      return value * 2;
    });
 
  defer.resolve( 5 );
  filtered.done(function( value ) {
    $( "p" ).html( "Value is ( 2*5 = ) 10: " + value );
  });
};
 
$( "button" ).on( "click", filterResolve );
</script>
 
</body>
</html>

Demo:

Filter reject value:

1
2
3
4
5
6
7
8
9
 
var defer = $.Deferred(),
  filtered = defer.then( null, function( value ) {
    return value * 3;
  });
 
defer.reject( 6 );
filtered.fail(function( value ) {
  alert( "Value is ( 3*6 = ) 18: " + value );
});

Chain tasks:

1
2
3
4
5
6
7
8
 
var request = $.ajax( url, { dataType: "json" } ),
  chained = request.then(function( data ) {
    return $.ajax( url2, { data: { user: data.userId } } );
  });
 
chained.done(function( data ) {
  // data retrieved from url2 as provided by the first request
});