new PromiseRejectionEvent() — Methode · JavaScript-Referenz

Signatur

new PromiseRejectionEvent(type, options)

Beschreibung

Mit dem Konstruktor PromiseRejectionEvent() erzeugst du ein Ereignisobjekt, wie es der Browser selbst bei den globalen Ereignissen unhandledrejection und rejectionhandled verwendet. Es enthält die betroffene Promise (promise) und den Ablehnungsgrund (reason).

Normalerweise musst du den Konstruktor nicht selbst aufrufen, weil die JavaScript-Umgebung diese Ereignisse automatisch auslöst. Nützlich ist er vor allem, um Fehlerbehandlungs-Code zu testen: Du kannst ein künstliches Ereignis erzeugen und per dispatchEvent() an window oder einen eigenen EventTarget senden, ohne eine echte unbehandelte Ablehnung auszulösen.

Das Objekt erbt von Event. Deshalb akzeptiert das Optionsobjekt neben promise und reason auch die üblichen Felder bubbles, cancelable und composed. Damit event.preventDefault() wirkt (z. B. um die Konsolenwarnung zu unterdrücken), muss cancelable: true gesetzt sein.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, typischerweise `"unhandledrejection"` oder `"rejectionhandled"`. Groß-/Kleinschreibung wird beachtet.
$options Pflicht	Object		Wörterbuch mit Ereignisdaten. Pflicht: `promise`; optional `reason` sowie die Felder aus `EventInit`.
$options.promise Pflicht	Promise		Die abgelehnte Promise. Fehlt sie, wirft der Konstruktor einen `TypeError`.
$options.reason	any	undefined	Ablehnungsgrund, meist ein `Error`-Objekt. Wird als `event.reason` bereitgestellt.
$options.bubbles	boolean	false	Ob das Ereignis im DOM nach oben weitergereicht wird.
$options.cancelable	boolean	false	Ob `preventDefault()` das Ereignis abbrechen kann.
$options.composed	boolean	false	Ob das Ereignis Shadow-DOM-Grenzen überschreitet.

Rückgabewert

Typ

PromiseRejectionEvent

Beschreibung

Ein neues PromiseRejectionEvent mit den schreibgeschützten Eigenschaften promise und reason.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const promise = Promise.reject(new Error('Netzwerkfehler'));
promise.catch(() => {}); // echte Warnung vermeiden

const event = new PromiseRejectionEvent('unhandledrejection', {
  promise,
  reason: new Error('Netzwerkfehler'),
  cancelable: true
});

console.log(event.type);
console.log(event.reason.message);
console.log(event.promise === promise);

unhandledrejection Netzwerkfehler true

Globalen Fehler-Handler testen

const logged = [];

window.addEventListener('unhandledrejection', (event) => {
  logged.push(event.reason?.message ?? String(event.reason));
  event.preventDefault(); // Standard-Konsolenausgabe unterdrücken
});

const p = Promise.reject(new Error('Test-Ablehnung'));
p.catch(() => {});

const fake = new PromiseRejectionEvent('unhandledrejection', {
  promise: p,
  reason: new Error('Test-Ablehnung'),
  cancelable: true
});

const notCancelled = window.dispatchEvent(fake);
console.log(logged, notCancelled, fake.defaultPrevented);

["Test-Ablehnung"] false true

Eigener EventTarget als Fehlerbus

const errorBus = new EventTarget();

errorBus.addEventListener('rejectionhandled', ({ reason }) => {
  console.log('Nachträglich behandelt:', reason);
});

const p = Promise.reject('Timeout');
p.catch(() => {});

errorBus.dispatchEvent(
  new PromiseRejectionEvent('rejectionhandled', { promise: p, reason: 'Timeout' })
);

Nachträglich behandelt: Timeout

// Wichtig · Fallstricke

Pflichtfeld promise: new PromiseRejectionEvent('unhandledrejection', {}) wirft einen TypeError. In älteren Firefox-Versionen war die Angabe noch optional.
Wenn du in Beispielen Promise.reject() nutzt, hänge ein .catch(() => {}) an. Sonst löst der Browser zusätzlich ein echtes unhandledrejection aus.
Selbst ausgelöste Ereignisse haben isTrusted === false. Die Standardaktion des Browsers (Konsolenmeldung) wird dadurch nicht ausgelöst.
preventDefault() wirkt nur, wenn cancelable: true gesetzt ist.
reason kann jeden Typ haben, auch undefined oder einen String. Greife deshalb defensiv zu, z. B. mit event.reason?.message.
Node.js stellt diesen Konstruktor nicht bereit und nutzt stattdessen process.on('unhandledRejection'). Deno unterstützt ihn.

Siehe auch

Promise.reject() new Event() new DeviceOrientationEvent() new HIDConnectionEvent() new MIDIConnectionEvent()