イベント

[49] 約束を扱う場合、履行時の処理を記述するのは普通のことで基本ですが、拒絶時の処理は怠りがちです。 (例外が投げられた処理を怠りがちなのと同じです。)

真に異常で通常なら起こり得ない問題のため拒絶時の処理を敢えて省くこともあれば、失敗することもあるので拒絶時の処理を指定しなければならないのに漏れてしまった場合もあります。

どちらの場合でも、せめて開発者コンソールでは気づきたいですし、例外に対する erroronerror イベントのようにスクリプト側で検知したいこともあります。

[50] そのため、約束が拒絶されて処理されていないことを通知するイベントが用意されています。

[37] 約束が拒絶され、それが処理されないままの時は、 unhandledrejection イベントが大域オブジェクトで発火されます。

[47] このイベントは、例外における erroronerror イベントに相当するものです。

[53] このイベントは取消可能です。取消された場合、開発者コンソールには何も表示されません。取消されていない場合、拒絶について開発者コンソールに表示されます。

[38] unhandledrejection イベントが発火された後から処理が追加された場合には、 rejectionhandled イベントが大域オブジェクトで発火されます。 unhandledrejection イベントのイベントハンドラーで処理が追加された場合にはこのイベントは発火されませんが、それよりも後に処理が追加された場合に、発火されます。

[52]

unhandledrejection を発火するかどうかの判定は、約束が拒絶されてからわりとすぐに (マイクロタスク処理後に) 行われます。しかし約束をずっと保持しておいて、しばらく経ってから処理が追加される可能性は残ります。その場合に unhandledrejection イベントで把握できます。ただし unhandledrejection イベントが発火されることは保証されません。

[42] PromiseRejectionEvent インターフェイス >>5 は、 rejectionhandled/unhandledrejection イベントと共に用いられます。文書環境とワーカー環境に晒されています >>5。

[44] PromiseRejectionEvent インターフェイスは、他の Event インターフェイス同様のコンストラクターを持ちます >>5。初期化のための辞書は PromiseRejectionEventInit です >>5。

[43] PromiseRejectionEvent インターフェイスは、 Event インターフェイスを継承しています >>5。 PromiseRejectionEventInit 辞書は、 EventInit 辞書を継承しています >>5。

[34] PromiseRejectionEvent インターフェイスの promise IDL属性は、当該通知の約束を表すもので、任意の Promise を値として持つ読み取り専用属性です。取得器は本イベントオブジェクトについて指定された値を返さなければなりません。 >>5

[36] PromiseRejectionEvent インターフェイスの reason IDL属性は、当該約束の拒絶理由を表すもので、任意値を持つ読み取り専用属性です。取得器は本イベントオブジェクトについて指定された値を返さなければなりません。 >>5

[35] つまり、 catch で指定された関数が引数として受け取るであろう値となります。

処理

約束

[25] 約束は、内部スロット PromiseIsHandled を持ちます >>24。

[28] この値は、 Promise コンストラクターで偽に初期化されます。

[32] then や await で真に設定されます。

[64] ReadableStream や WritableStream の処理でも真に設定されることがあります。

[39] この値が偽の時に、 HostPromiseRejectionTracker が実行されます。

[55] HostPromiseRejectionTracker は、ホスト環境定義の内部操作として JavaScript の仕様書で定義されているものです >>54。

[56] この操作は、引数として約束と操作を与えられます >>54。 操作の値は、 rejectHostPromiseRejectionTracker または handleHostPromiseRejectionTracker のいずれかです >>54。

[59] 操作 rejectHostPromiseRejectionTracker は、約束約束がハンドラーの登録されていない状態で拒絶された時、実行されます >>54。

[62] Web では、次のようにしなければなりません >>5。

[21] 走っているスクリプトの設定群オブジェクトのこれから通知する拒絶された約束リストに、約束を追加します。

[51] この処理は拒絶時に PromiseIsHandled が偽の場合に、実行されます。拒絶は1回しか起こらないため、この処理も1回しか呼び出されません。 操作が handleHostPromiseRejectionTracker で呼び出された後にこちらの処理が呼び出されることもありません。

[60] 操作 handleHostPromiseRejectionTracker は、約束約束が拒絶されているところ、ハンドラーが初めて追加された時、実行されます >>54。

[20] Web では、次のようにしなければなりません >>5。

[22] 設定群オブジェクトを、走っているスクリプトの設定群オブジェクトに設定します。
[26] 設定群オブジェクトのこれから通知する拒絶された約束リストに約束が含まれている場合、
1. [27] 設定群オブジェクトのこれから通知する拒絶された約束リストから約束を削除します。
[29] それ以外で、設定群オブジェクトの未決拒絶された約束弱集合に約束が含まれている場合、
1. [30] 設定群オブジェクトの未決拒絶された約束弱集合から約束を削除します。
2. [31] タスクをキューに追加します。
  処理
  [33] イベントを発火します。
  対象イベント対象
  設定群オブジェクトの大域オブジェクト
  インターフェイスイベントインターフェイス
  PromiseRejectionEvent
  型イベント型
  rejectionhandled
  trusted
  真
  bubbles
  偽
  取消可能
  偽
  promise
  約束
  reason
  約束 の PromiseResult の値
  タスク源
  DOM操作タスク源

[63] この処理は then から呼び出されます。 PromiseIsHandled が偽の時に呼び出されますが、本処理の直後に真に設定されるため、本処理が呼び出されるのは高々1回です。本処理が呼び出されるのは既に拒絶されている場合のみですから、必ず操作 rejectHostPromiseRejectionTracker で1回呼び出された後になります。

環境設定群オブジェクト

[4] 環境設定群オブジェクトは、これから通知する拒絶された約束リストabout-to-be-notified rejected promises listを持ちます >>2。約束が拒絶され、処理が追加されていない場合、このリストに約束が追加されていきます。処理が追加されると、このリストから約束は削除されます。最終的に残った約束について、 unhandledrejection イベントが発火されます。

[3] 環境設定群オブジェクトは、未決拒絶された約束弱集合outstanding rejected promises weak setを持ちます >>2。この弱集合からその構成要素への参照は、強参照であってはなりません >>2。実装はサイズを制限しても構いません (例えば溢れるなら古いものを削除して構いません) >>2。 unhandledrejection イベントが発火された約束は、イベントハンドラーでも処理が追加されないままの場合、このリストに追加されます。処理が追加された時、このリストに約束が含まれていれば、 rejectionhandled イベントが発火されます。

[6] 環境設定群オブジェクト設定群オブジェクトの拒絶された約束について通知notify about rejected promisesは、次のようにしなければなりません >>5。

[7] リストを、設定群オブジェクトのこれから通知する拒絶された約束リストの複製に設定します。
[9] リストが空なら、ここで停止します。
[8] 設定群オブジェクトのこれから通知する拒絶された約束リストを、空にします。
[10] 次のようなタスクをタスクキューに追加します。
[11] タスク
タスク源
?
処理
[12] リスト内の各約束 p について、
[13] p の PromiseIsHandled が真なら、次の約束に進みます。
[14] 新しいイベントイベントを発火します。
[15] イベント
イベント型
unhandledrejection
インターフェイス
PromiseRejectionEvent
trusted
真
bubbles
偽
取消可能
真
promise
p
reason
p の PromiseResult の値
対象
設定群オブジェクトの大域オブジェクト
[16] 結果を、イベントの取消が真なら「取り扱われたhandled」、偽なら「取り扱われなかったnot handled」に設定します。エラーの報告も参照。
[19] 結果が「取り扱われなかった」の場合、
[23] 拒絶について開発者コンソールに報告して構いません。
[17] p の PromiseIsHandled が偽なら、
[18] 設定群オブジェクトの未決拒絶された約束弱集合に p を追加します。

[48] この処理は、マイクロタスクチェックポイントを行う処理から呼び出されます。

歴史

[43] IRC logs: freenode / #whatwg / 20140912 ( (2014-09-13 11:03:22 +09:00 版)) http://krijnhoetmer.nl/irc-logs/whatwg/20140912#l-688

[44] [whatwg] An API for unhandled promise rejections ( (Domenic Denicola 著, 2014-09-13 03:34:23 +09:00 版)) http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Sep/0024.html

[57] domenic/unhandled-rejections-browser-spec (2015-06-18 08:21:28 +09:00 版) https://github.com/domenic/unhandled-rejections-browser-spec

[58] 1179244 – Dispatch events for promises with unhandled rejections (2015-07-02 10:30:56 +09:00 版) https://bugzilla.mozilla.org/show_bug.cgi?id=1179244

[61] Bug 150358 – Support for promise rejection events (2015-10-21 11:24:26 +09:00 版) https://bugs.webkit.org/show_bug.cgi?id=150358

[1] Add promise rejection tracking events · whatwg/html@61ccc05 (2015-12-03 22:55:13 +09:00 版) https://github.com/whatwg/html/commit/61ccc05b7437ba947390928f9e526da49550fed0

[40] Rewrite script execution on top of ES · whatwg/html@4891d18 (2015-12-22 23:56:19 +09:00 版) https://github.com/whatwg/html/commit/4891d18aaf2df1d40aa61f467a5a10cfc19dd85d

[41] Restore definition of "Reject" lost in 079cbb861a99e9e857a3f2a169c0be… · heycam/webidl@326291e (2016-02-16 11:03:14 +09:00 版) https://github.com/heycam/webidl/commit/326291e58cf0b6e3677edb8c62682e41acaf7faf

[45] Sync with recent changes to the JS spec's job queue · whatwg/html@5af258f (2016-03-24 21:47:31 +09:00 版) https://github.com/whatwg/html/commit/5af258f33e3e2f55eb30e611cb7aee625a8bd16a

[46] Clarify settings object, realm, and global relationships · whatwg/html@0866f1b (2016-03-28 00:31:04 +09:00 版) https://github.com/whatwg/html/commit/0866f1b3f4b4ea5a99a30909e9bbe557dea0b460

[65] Fix writable stream writer manual usage example (domenic著, 2018-02-01 02:50:02 +09:00) https://github.com/whatwg/streams/commit/3dffaaa475840161ee05d1d1e0c931046361239d

[66] Use the DOM manipulation task source for promise-related events (CYBAI著, 2019-03-30 00:46:38 +09:00) https://github.com/whatwg/html/commit/d0feee54f85f60617811f2ea32a115e34233e606

[67] "Notify about rejected promises" is missing a task source · Issue #3731 · whatwg/html (2019-08-23 14:33:13 +09:00) https://github.com/whatwg/html/issues/3731

[68] Use DOM manipulation task source for promise related events by CYBAI · Pull Request #4462 · whatwg/html (2019-08-23 14:33:45 +09:00) https://github.com/whatwg/html/pull/4462

[69] Add reference to DOM manipulation task source for unhandled promise r… by KiChjang · Pull Request #3844 · whatwg/html (2019-08-23 14:34:14 +09:00) https://github.com/whatwg/html/pull/3844