# deferred.pipe()

## deferred.pipe ( doneFilter, failFilter ) Returns: Promise version added: 1.6

- doneFilter
  Type: Function
  An optional function that is called when the Deferred is resolved.

- failFilter
  Type: Function
  An optional function that is called when the Deferred is rejected.

## deferred.pipe ( doneFilter, failFilter, progressFilter ) Returns: Promise version added: 1.7

- doneFilter
  Type: Function
  An optional function that is called when the Deferred is resolved.

- failFilter
  Type: Function
  An optional function that is called when the Deferred is rejected.

- progressFilter
  Type: Function
  An optional function that is called when progress notifications are sent to the Deferred.

Description: Utility method to filter and/or chain Deferreds.

Deprecation Notice:As of jQuery 1.8, the deferred.pipe() method is deprecated. The `deferred.then()` method, which replaces it, should be used instead.

The `deferred.pipe()` method returns a new promise that filters the status and values of a deferred through a function. The `doneFilter` and `failFilter` functions filter the original deferred's resolved / rejected status and values. As of jQuery 1.7, the method also accepts a `progressFilter` function to filter 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 piped 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 piped promise's callbacks. If the filter function used is `null`, or not specified, the piped promise will be resolved or rejected with the same values as the original.

## Examples:

#### Example: Filter resolve value:

    var defer = $.Deferred(),
      filtered = defer.pipe(function( value ) {
        return value * 2;
      });

    defer.resolve( 5 );
    filtered.done(function( value ) {
      alert( "Value is ( 2*5 = ) 10: " + value );
    });

#### Example: Filter reject value:

    var defer = $.Deferred(),
      filtered = defer.pipe( null, function( value ) {
        return value * 3;
      });

    defer.reject( 6 );
    filtered.fail(function( value ) {
      alert( "Value is ( 3*6 = ) 18: " + value );
    });

#### Example: Chain tasks:

    var request = $.ajax( url, { dataType: "json" } ),
      chained = request.pipe(function( data ) {
        return $.ajax( url2, { data: { user: data.userId } } );
      });

    chained.done(function( data ) {
      // data retrieved from url2 as provided by the first request
    });