PromiseRejectionEvent.promise — Eigenschaft · JavaScript-Referenz

Signatur

PromiseRejectionEvent.promise

Beschreibung

Die schreibgeschützte Eigenschaft promise des Interfaces PromiseRejectionEvent verweist auf genau das Promise-Objekt, das abgelehnt wurde. Das Ereignis wird global auf window (oder im Worker auf self) ausgelöst, und zwar als unhandledrejection, wenn ein Promise ohne Ablehnungs-Handler abgelehnt wird. Hängt man später doch noch einen Handler an, folgt rejectionhandled.

Gebraucht wird die Eigenschaft vor allem für globales Fehler-Monitoring: Man kann das betroffene Promise nachträglich behandeln (zum Beispiel .catch() anhängen), es als Schlüssel in einer Map oder WeakMap speichern oder abgleichen, welche zuvor gemeldete Ablehnung später doch noch behandelt wurde. Den eigentlichen Ablehnungsgrund bekommt man über die Schwester-Eigenschaft reason, nicht über promise.

Da promise das Original-Objekt ist, lässt es sich per Identität (===) vergleichen. So kann man die Ereignisse unhandledrejection und rejectionhandled einander eindeutig zuordnen.

Rückgabewert

Typ

Promise<any>

Beschreibung

Das JavaScript-Promise, das abgelehnt wurde und das Ereignis ausgelöst hat. Der Wert ist schreibgeschützt.

Beispiele

Unbehandelte Ablehnungen global protokollieren

window.addEventListener('unhandledrejection', (event) => {
  console.log('Abgelehntes Promise:', event.promise);
  console.log('Grund:', event.reason.message);
});

// Promise ohne catch-Handler
Promise.reject(new Error('Server nicht erreichbar'));

Abgelehntes Promise: Promise {<rejected>: Error: Server nicht erreichbar} Grund: Server nicht erreichbar

unhandledrejection und rejectionhandled einander zuordnen

const offen = new Map();

window.addEventListener('unhandledrejection', (event) => {
  offen.set(event.promise, event.reason);
  console.log('Offene Ablehnungen:', offen.size);
});

window.addEventListener('rejectionhandled', (event) => {
  // Identitätsvergleich über das Promise-Objekt
  if (offen.delete(event.promise)) {
    console.log('Nachträglich behandelt, offen:', offen.size);
  }
});

const p = Promise.reject(new Error('Timeout'));

// Handler erst später anhängen
setTimeout(() => p.catch(() => {}), 1000);

Offene Ablehnungen: 1 Nachträglich behandelt, offen: 0

Promise nachträglich behandeln und Standardmeldung unterdrücken

window.onunhandledrejection = (event) => {
  event.preventDefault(); // keine Konsolen-Fehlermeldung des Browsers
  event.promise.catch((err) => {
    console.warn('Abgefangen:', err.message);
  });
};

fetch('https://ungueltige-domain.invalid/api');

Abgefangen: Failed to fetch

Ereignis manuell erzeugen (z. B. für Tests)

const p = Promise.reject(new Error('Test'));
p.catch(() => {}); // echte Ablehnung stillschweigend behandeln

const event = new PromiseRejectionEvent('unhandledrejection', {
  promise: p,
  reason: new Error('Test')
});

console.log(event.promise === p);

true

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an event.promise hat keine Wirkung. Im Strict Mode löst sie einen TypeError aus.
promise enthält nicht den Fehlergrund. Den liefert event.reason.
Wer Promises als Schlüssel in einer Map ablegt, hält sie im Speicher fest. Bei vielen Ablehnungen besser eine WeakMap verwenden oder die Einträge aktiv aufräumen.
Ein .catch() im unhandledrejection-Handler behandelt das Promise zwar, die Standardmeldung in der Konsole bleibt aber stehen. Die lässt sich nur mit event.preventDefault() unterdrücken.
Im Konstruktor new PromiseRejectionEvent() ist promise im Init-Objekt Pflicht. Fehlt es, wird ein TypeError geworfen.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workern (über self). Firefox unterstützt die Ereignisse erst ab Version 69. Node.js kennt dieses Interface nicht und nutzt stattdessen process.on('unhandledRejection', (reason, promise) => …).

Siehe auch

Promise Promise.prototype.catch() DeviceOrientationEvent.absolute PromiseRejectionEvent.reason HIDConnectionEvent.device