PromiseRejectionEvent.PromiseRejectionEvent()

The PromiseRejectionEvent() constructor returns a newly created PromiseRejectionEvent, which represents events fired when a JavaScript Promise is rejected. With promise rejection events, it becomes possible to detect and report promises which fail and whose failures go unnoticed. It also becomes easier to write a global handler for errors.

There are two types of PromiseRejectionEvent: unhandledrejection is sent by the JavaScript runtime when a promise is rejected but the rejection goes unhandled. A recipient of unhandledrejection sends a rejectionhandled event if it handles the rejection, so the system knows to stop treating the rejection as unhandled.

Syntax

PromiseRejectionEvent = PromiseRejectionEvent(type, options);

Parameters

The PromiseRejectionEvent() constructor also inherits parameters from Event().

type
A string representing the name of the type of the PromiseRejectionEvent. This is case-sensitive and should be one of "rejectionhandled" or "unhandledrejection", to match the event names of the possible (non-synthetic) PromiseRejectionEvent events that user agents can actually fire).
options
An Object specifying details about the rejection which occurred:
promise
The Promise that was rejected.
reason
Any value or Object which represents the reason the promise was rejected. This can be anything from a numeric error code to an error DOMString to an object which contains detailed information describing the situation resulting in the promise being rejected.

Return value

A new PromiseRejectionEvent configured as specified by the parameters.

Examples

This example creates a new unhandledrejection event for the promise myPromise with the reason being the string "My house is on fire". The reason could just as easily be a number, or even an object with detailed information including the home address, how serious the fire is, and the phone number of an emergency contact who should be notified.

var myRejectionEvent = new PromiseRejectionEvent('unhandledrejection', {
  promise : myPromise,
  reason : 'My house is on fire'
});

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'the PromiseRejectionEvent interface' in that specification.
Living Standard Initial definition.

Browser compatibility

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support49 ? No1 2 No No No
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support ? No ? No1 2 No No ?

1. Firefox doesn't yet send the unhandledrejection or understand rejectionhandled events. Completing the implementation will be addressed in bug 1362272.

2. This feature is behind the dom.promise_rejection_events.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

See also

Document Tags and Contributors

Contributors to this page: sideshowbarker, fscholz, Sheppy, chrisdavidmills
Last updated by: sideshowbarker,