The short doc for .fail says:
Add handlers to be called when the Deferred object is rejected.
and the short doc for .catch is exactly the same:
Add handlers to be called when the Deferred object is rejected.
Source: http://api.jquery.com/category/deferred-object/
The arguments accepted by the two methods seem to be different, and the doc of
.catch states that .catch is an alias of .then(null, fn)
Are there cases where I should use .fail and others where I should use .catch?
Or ... if I only have one function ... are following commands interchangeable and they only exist for compatibility/historical reasons?
a) .fail(fn)
b) .catch(fn)
c) .then(null, fn)
I created a jsFiddle:
https://jsfiddle.net/sq3mh9j5/
If there is a difference, could you please provide some examples since I am new to jquery and not yet familiar with all promise terms.
Why does the doc of .catch does not reference the doc of .fail and clarify the difference/similarity?
Edit I found some notes in the 3.0 release notes that the behavior of .then changed. https://blog.jquery.com/2015/07/13/jquery-3-0-and-jquery-compat-3-0-alpha-versions-released/ Nevertheless I am still unsure when to use .fail and when to use .catch.
catch and fail are slightly different, in that catch will return a new (resolved) promise, whereas fail will return the original promise.
// This will only output "fail"
$.Deferred()
.reject(new Error("something went wrong"))
.fail(function() {
console.log("fail");
})
.then(function() {
console.log("then after fail");
})
// This will output "catch" and "then after catch"
$.Deferred()
.reject(new Error("something went wrong"))
.catch(function() {
console.log("catch");
})
.then(function() {
console.log("then after catch");
})
So I think the major difference is what you get out of each.
A catch allows you to run a single function.
A fail allows you to run a number of functions.
Other than that I concur with your findings. They are very similar.
I added an example code to showcase how fail will run both functions, and the catch will only run the one.
$.ajax({
url: "abc"
}).done(function (data) {
}).fail(function () {
alert("a");
}, function () {
alert("b");
})
.catch(function () {
alert("c");
}, function () {
alert("d");
});
If you run this you get 'a','b','c' and then 'd' doesn't run.
I hope this simple example showcases the difference.