Revision 937555 of Promise.prototype.catch()

Revision slug: Web/JavaScript/Reference/Global_Objects/Promise/catch
Revision title: Promise.prototype.catch()
Revision id: 937555
Created: Oct 20, 2015, 9:18:43 AM
Creator: Brettz9
Is current revision? No
Comment add Promise.reject to example as well as indicate subsequent onRejected not firing

Tags:

Revision Content

The catch() method returns a Promise and deals with rejected cases only. It behaves the same as calling {{jsxref("Promise.then", "Promise.prototype.then(undefined, onRejected)")}}.

Syntax

p.catch(onRejected);

p.catch(function(reason) {
   // rejection
});

Parameters

onRejected: A {{jsxref("Function")}} called when the Promise is rejected. This function has one argument, the rejection reason.

Description

The catch method can be useful for error handling in your promise composition.

Examples

Using the `catch` method

var p1 = new Promise(function(resolve, reject) {
  resolve('Success');
});

p1.then(function(value) {
  console.log(value); // "Success!"
  throw 'oh, no!';
}).catch(function(e) {
  console.log(e); // "oh, no!"
}).then(function(e){
  console.log('after a catch the chain is restored');
}, function () {
  console.log('Not fired due to the catch');
});

// The following behaves the same as above
p1.then(function(value) {
  console.log(value); // "Success!"
  return Promise.reject('oh, no!');
}).catch(function(e) {
  console.log(e); // "oh, no!"
}).then(function(e){
  console.log('after a catch the chain is restored');
}, function () {
  console.log('Not fired due to the catch');
});

Specifications

Specification	Status	Comment
{{SpecName('ES6', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}}	{{Spec2('ES6')}}	Initial definition in an ECMA standard.
{{SpecName('ESDraft', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}}	{{Spec2('ESDraft')}}

Browser compatibility

Feature	Chrome	Firefox (Gecko)	Internet Explorer	Opera	Safari
Basic support	32	{{CompatGeckoDesktop(29.0)}}	{{CompatNo}}	19	7.1

Feature	Android	Firefox Mobile (Gecko)	IE Mobile	Opera Mobile	Safari Mobile	Chrome for Android
Basic support	{{CompatNo}}	{{CompatGeckoMobile(29.0)}}	{{CompatNo}}	{{CompatNo}}	8	32

{{ EmbedCompatTable("web_javascript_reference_global_objects_promi04de7") }}

Revision Source

<div>{{JSRef}}</div>

<p>The <strong>catch()</strong> method returns a <code>Promise</code> and deals with rejected cases only. It behaves the same as calling {{jsxref("Promise.then", "Promise.prototype.then(undefined, onRejected)")}}.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">
<var>p.catch(onRejected)</var>;

p.catch(function(reason) {
   // rejection
});
</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
 <dt>onRejected</dt>
 <dd>A {{jsxref("Function")}} called when the <code>Promise</code> is rejected. This function has one argument, the rejection <code>reason</code>.</dd>
</dl>

<h2 id="Description">Description</h2>

<p>The <code>catch</code> method can be useful for error handling in your promise composition.</p>

<h2 id="Examples">Examples</h2>

<h3 id="Using_the_catch_method">Using the <code>catch</code> method</h3>

<pre class="brush: js">
var p1 = new Promise(function(resolve, reject) {
&nbsp; resolve('Success');
});

p1.then(function(value) {
&nbsp; console.log(value); // "Success!"
&nbsp; throw 'oh, no!';
}).catch(function(e) {
&nbsp; console.log(e); // "oh, no!"
}).then(function(e){
&nbsp; console.log('after a catch the chain is restored');
}, function () {
&nbsp; console.log('Not fired due to the catch');
});

// The following behaves the same as above
p1.then(function(value) {
&nbsp; console.log(value); // "Success!"
  return Promise.reject('oh, no!');
}).catch(function(e) {
 &nbsp;console.log(e); // "oh, no!"
}).then(function(e){
&nbsp; console.log('after a catch the chain is restored');
}, function () {
&nbsp; console.log('Not fired due to the catch');
});

</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td>Initial definition in an ECMA standard.</td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>32</td>
   <td>{{CompatGeckoDesktop(29.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>19</td>
   <td>7.1</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatGeckoMobile(29.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>8</td>
   <td>32</td>
  </tr>
 </tbody>
</table>
</div>

<p>{{ EmbedCompatTable("web_javascript_reference_global_objects_promi04de7") }}</p>

<h2 id="See_also">See also</h2>

<ul>
 <li>{{jsxref("Promise")}}</li>
 <li>{{jsxref("Promise.prototype.then()")}}</li>
</ul>

Revert to this revision