jQuery Deferred pipe() Method

What You’ll Learn

The pipe() method filters and transforms values in a jQuery Deferred chain. Return a new value or another promise from doneFilter to pass results to the next step. This tutorial covers syntax, five examples, comparisons with done() and then(), and why pipe() is deprecated in jQuery 3+.

Introduction

Async workflows often need more than a single callback. After one task finishes, you may transform its result, start another request, or map errors before the UI updates. jQuery’s pipe() method builds that pipeline — each filter function receives the previous outcome and returns what the next link should receive.

In jQuery 3+, then() replaces pipe() with Promises/A+-compatible behavior. Understanding pipe() still helps when reading legacy code and when migrating chains to then().

Understanding the pipe() Method

pipe() returns a new promise-like object wired to filter callbacks. When the source Deferred resolves, jQuery calls doneFilter with the resolved values. Whatever the filter returns — a plain value, a new Deferred, or a thrown error — determines how the piped chain continues.

Optional failFilter handles rejections; optional progressFilter handles notify() progress events. Unlike done(), which ignores return values, pipe() is designed for value transformation.

📝 Syntax

General form of deferred.pipe:

deferred.pipe( doneFilter [, failFilter [, progressFilter ] ] )

Parameters

• doneFilter — runs on resolve; return value or promise becomes the next chain input.
• failFilter — optional; runs on reject for error mapping or recovery.
• progressFilter — optional; runs on progress (notify()) events.

Return value

• Returns a new promise object representing the filtered chain — attach further pipe(), then(), done(), or fail() to it.

Modern equivalent (jQuery 3+)

// Legacy
dfd.pipe(function (value) {
  return value * 2;
});

// Preferred in jQuery 3+
dfd.then(function (value) {
  return value * 2;
});

Examples Gallery

Each example shows how pipe() transforms or chains Deferred results. Use the Try-it links to run them interactively.

const dfd = $.Deferred();

dfd.resolve(5);

dfd.pipe(function (n) {
  return n * 10;
}).done(function (result) {
  console.log(result);  // 50
});

50

function fetchUserId() {
  const d = $.Deferred();
  setTimeout(function () { d.resolve({ id: 42 }); }, 300);
  return d.promise();
}

function fetchProfile(userId) {
  const d = $.Deferred();
  setTimeout(function () {
    d.resolve({ userId: userId, name: "Alex" });
  }, 300);
  return d.promise();
}

fetchUserId().pipe(function (data) {
  return fetchProfile(data.id);
}).done(function (profile) {
  console.log(profile.name);  // Alex
});

Alex

const dfd = $.Deferred();
dfd.resolve('{"score": 88}');

dfd.pipe(function (jsonText) {
  const parsed = JSON.parse(jsonText);
  const next = $.Deferred();
  setTimeout(function () {
    next.resolve({ score: parsed.score, grade: "B+" });
  }, 200);
  return next.promise();
}).done(function (report) {
  console.log(report.grade);  // B+
});

B+

const dfd = $.Deferred();
dfd.reject("Network timeout");

dfd.pipe(null, function (reason) {
  return "Recovered: " + reason;
}).done(function (message) {
  console.log(message);
}).fail(function () {
  console.log("Still rejected");
});

Recovered: Network timeout

const dfd = $.Deferred();
dfd.resolve(3);

// Legacy (deprecated in jQuery 3.0+)
dfd.pipe(function (n) {
  return n + 7;
}).done(function (legacy) {
  console.log("pipe:", legacy);  // 10
});

// Modern equivalent
$.Deferred().resolve(3).then(function (n) {
  return n + 7;
}).then(function (modern) {
  console.log("then:", modern);  // 10
});

pipe: 10
then: 10

🚀 Use Cases

• Sequential AJAX — load an ID, then fetch details based on that ID in one chain.
• Data transformation — parse JSON, normalize fields, or compute derived values between steps.
• Conditional branching — return different promises from a filter based on intermediate results.
• Error recovery — map failures to fallback values with failFilter.
• Legacy maintenance — read and gradually migrate existing pipe() chains to then().

📝 Notes

• pipe() is deprecated since jQuery 3.0 — use then() for new code.
• Returning a value from done() does not affect the chain; use pipe() or then() for transforms.
• Throwing inside a filter rejects the piped chain — same as returning a rejected promise.
• Pass jQuery.noop or null to skip a filter slot when you only need fail or progress handling.
• Always add fail() or catch() at the end of chains for user-facing error handling.

💡 Best Practices