# deferred.pipe()

Categories: Deferred Object

## deferred.pipe( [doneFilter] [, failFilter] ) Returns: Promise

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

- #### version added: 1.6deferred.pipe( [doneFilter] [, failFilter] )

  doneFilter An optional function that is called when the Deferred is resolved.

  failFilter An optional function that is called when the Deferred is rejected.

- #### version added: 1.7deferred.pipe( [doneFilter] [, failFilter] [, progressFilter] )

  doneFilter An optional function that is called when the Deferred is resolved.

  failFilter An optional function that is called when the Deferred is rejected.

  progressFilter An optional function that is called when the Deferred is rejected.

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
    });