Writing Promise-Using Specifications （日本語訳）

1. 序論

`~promise^em （ “約束” ）とは、［単独の非同期的な演算］の最終的な結果を表現する，~objである。それは，非同期的な関数からも返せるので、使用者は，演算が［成功した／失敗した］ときに~callされる~callbackを~queueすることのみならず、返された~promise~objを操作して，様々な~~分岐の可能性を開けるようになる。 ◎ A promise is an object that represents the eventual result of a single asynchronous operation. They can be returned from asynchronous functions, thus allowing consumers to not only queue up callbacks to be called when the operation succeeds or fails, but also to manipulate the returned promise object, opening up a variety of possibilities.

~promiseは、普及した~framework — Dojo, jQuery, YUI, Ember, Angular, WinJS, Q, その他 — を成す一部も含め，多くの~JS~library間で互いに競いながら~testされてきた。これは、遂には Promises/A+ ~community仕様【和訳】として完成され，ほとんどの~libraryはそれに適合している。今や、標準な `Promise$c ~classが~JS言語~仕様 `ECMASCRIPT$r に含まれている — 各種~web~platform~APIは、自身による非同期的な演算~用の~promiseを返せるようになっている。 ◎ Promises have been battle-tested in many JavaScript libraries, including as part of popular frameworks like Dojo, jQuery, YUI, Ember, Angular, WinJS, Q, and others. This culminated in the Promises/A+ community specification which most libraries conformed to. Now, a standard Promise class is included in the JavaScript specification, allowing web platform APIs to return promises for their asynchronous operations. [ECMASCRIPT]

~promiseは、今や，すべての［ “~one-and-done” 非同期的な演算］用の~web~platformにおける~paradigmである。これまでの仕様は、そのような演算~用に，互いに合致しない様々な仕組みを利用していた。これからは、この型のすべての非同期的な演算は，代わりに~promiseを返すように指定するべきである — ~web~platformに，非同期性のための統一化された~primitiveを与えるために。 ◎ Promises are now the web platform’s paradigm for all "one and done" asynchronous operations. Previously, specifications used a variety of mismatched mechanisms for such operations. Going forward, all asynchronous operations of this type should be specified to instead return promises, giving our platform a unified primitive for asynchronicity.

この文書は、以前まで，~promiseを操作するための用語をいくつか定義し，それらを利用する例を与えていたが、それらは，~Web~IDLに移動された。 `WEBIDL$r 【移動-先：操作／例】 ◎ This document previously defined a number of terms for manipulating promises, and gave examples for using them. Those have since moved to Web IDL. [WEBIDL]

同様に，この文書は、非同期的な~algoをとり巻く一般な細部を成す一部 — すなわち、［手続きを`並列的$に走らす／`~taskを~queueする$ ］こと — に関する助言を与えていた。それらは、今や，~HTMLの § 他の仕様における~event~loopの~~扱い方にある。 ◎ Similarly, this document used to give advice on some of the general subtleties around asynchronous algorithms, i.e. running steps in parallel and queuing tasks. Those are now in HTML’s "Dealing with the event loop from other specifications" section.

2. ~promiseをいつ利用するか

2.1. ~one-and-done演算

~promiseは、首に，［単独の非同期的な演算］を~~開始させる~methodから返されるものとして利用される。 ~promiseを返す関数は、通常の同期的な関数とは対照的に，非同期的な関数†と捉えるべきである — ここにはとても強い相似があることを念頭に置けば、そのような関数を書いたり, それを理由付けるのも容易になる。 ◎ The primary use case for promises is returning them from a method that kicks off a single asynchronous operation. One should think of promise-returning functions as asynchronous functions, in contrast to normal synchronous functions; there is a very strong analogy here, and keeping it in mind makes such functions easier to write and reason about.

【† より詳しく言うなら、非同期的な演算を “包装する” 関数 — すなわち、その演算を（非同期的に）遂行する “約束” を表現する~promise~objを（同期的に）返す関数。】

例えば：通常の同期的な関数は、値を返すか，例外を投出する。相似的に，非同期的な関数は、［ある値により充足されるか, ある事由により却下される］ような~promiseを返すことになる。同期的な関数が “~nothing” （すなわち， `undefined^jv ）を返せるのとちょうど同じく、非同期的な関数から返される~promiseも，~nothing（ `undefined^jv ）で充足し得る — この事例においては、 ~promiseの充足は，単純に非同期的な演算の完了を通達する。 ◎ For example, normal synchronous functions can either return a value or throw an exception. Asynchronous functions will, analogously, return a promise, which can either be fulfilled with a value, or rejected with a reason. Just like a synchronous function that returns "nothing" (i.e. undefined), promises returned by asynchronous functions can be fulfilled with nothing (undefined); in this case the promise fulfillment simply signals completion of the asynchronous operation.

そのような非同期的な演算の例は、各種~web仕様にありふれている。 ~promiseの仕組みにより： ◎ Examples of such asynchronous operations abound throughout web specifications:

非同期的な入出力~演算 ⇒ ~storage~APIにより~dataを［読取る／書出す］~methodは、 ~promiseを返せるようになる。 ◎ Asynchronous I/O operations: methods to read or write from a storage API could return a promise.
非同期的な~network演算 ⇒ ~network越しに~dataを送受信する~methodは、 ~promiseを返せるようになる。 ◎ Asynchronous network operations: methods to send or receive data over the network could return a promise.
長くかかる算出 ⇒ 何かを算出するためにある程度時間を~~要する~methodは、結果~用の~promiseを返した上で，別の~thread上で働けるようになる。 ◎ Long-running computations: methods that take a while to compute something could do the work on another thread, returning a promise for the result.
利用者に~~入力を促すとき ⇒ 利用者に回答を依頼する~methodは、 ~promiseを返せるようになる。 ◎ User interface prompts: methods that ask the user for an answer could return a promise.

以前の~web仕様は、非同期的な演算~用に，多種多様な~patternを利用していた。これらは， § 旧来の非同期性~API にて文書化されているので、何を避けるべきかについて，~ideaを得られる。今や，~platform~primitiveとして~promiseがあるので、そのような~approachは，もはや必要yでない。 ◎ Previously, web specifications used a large variety of differing patterns for asynchronous operations. We’ve documented these in Appendix: legacy APIs for asynchronicity, so you can get an idea of what to avoid. Now that we have promises as a platform primitive, such approaches are no longer necessary.

2.2. 一度限りの “~event”

~promiseは、すでに［充足された／却下された］後でも，【まだ処理が終わっていないかのように，その結果が通達されるよう】申込めるので、ある種の “~event” においては，とても有用になり得る。一度だけ起こるものであって，作者がすでに生じた後にもその状態sを観測したいと求めることが多いとき、［充足されたのは，それが生じた時点とされる］ような~promiseを供することは，とても簡便な~APIを与える。 ◎ Because promises can be subscribed to even after they’ve already been fulfilled or rejected, they can be very useful for a certain class of "event." When something only happens once, and authors often want to observe the status of it after it’s already occurred, providing a promise that becomes fulfilled when that eventuality comes to pass gives a very convenient API.

そのような “~event” の原型的な例として、 ~load済みかどうかを指示するものが挙げられる：画像や~fontは — あるいは文書などの資源までもが — 資源が全部的に~loadされたときに限り，充足される（あるいは、 ~load時に~errorが~~生じたときは，却下される）~promiseを返すような， `loaded^c ~propを供することもできる。作者は常に、 `resource.loaded.then(onLoaded, onFailure)^c と記すことで，［資源の用意ができ次第，実行されることになる動作］が~queueされる。これは、［当の資源がすでに~load済みであったとしても， %onLoaded を実行する`小taskを~queueする$ ］ように働く。対照的に，伝統的な~event~model — `EventTarget$I のそれなど — では、［ ~eventが発火された時点で，作者がまだ申込んでいない【すなわち、それ用の~listenerは登録-済みでない】場合］には，その情報は失われる。 ◎ The prototypical example of such an "event" is a loaded indicator: a resource such as an image, font, or even document, could provide a loaded property that is a promise that becomes fulfilled only when the resource has fully loaded (or becomes rejected if there’s an error loading the resource). Then, authors can always queue up actions to be executed once the resource is ready by doing resource.loaded.then(onLoaded, onFailure). This will work even if the resource was loaded already, queueing a microtask to execute onLoaded. This is in contrast to a traditional event model, such as that of EventTarget, where if the author is not subscribed at the time the event fires, that information is lost.

2.3. より一般な状態~遷移

ある種の事例においては、 ~promiseは，［状態~遷移を通達するための一般な仕組み］として有用になり得る。この用法には微妙な所があるが、正しく行われたなら，使用者にとってとても使い勝手が良い~APIを供せる。 ◎ In certain cases, promises can be useful as a general mechanism for signaling state transitions. This usage is subtle, but can provide a very nice API for consumers when done correctly.

この~patternは、一度限りの “~event” 利用事例の一般~化と捉えられる。例えば、いくつかの `img$e 要素があるとする。それらは、 `src$a 属性を設定し直すことにより，~loadし直せる — すなわち，それらの状態は、 `~load済み^i から `未~load^i へ戻るようにも遷移し得る。したがって、 `~load済み^i になることは，一度限りではない — 代わりに、画像は，実際には［ `~load済み^i, `未~load^i ］の状態を~~往復するような状態~machineを成す。 ◎ One can think of this pattern as a generalization of the one-time "events" use case. For example, take img elements. By resetting their src attribute, they can be re-loaded; that is, they can transition back from a loaded state to an unloaded state. Thus becoming loaded is not a one-time occasion: instead, the image actually consists of a state machine that moves back and forth between loaded and unloaded states.

そのような局面であっても、各~画像に［ ~promiseを返す `loaded^c ~prop ］を与えることは，有用になる — それは、次回の［ `~load済み^i 状態へ移行する状態~遷移］を通達する（あるいは、当の画像はすでに `~load済み^i 状態にあるならば，充足される~promiseを返す）。この~propは、画像が `~load済み^i 状態から `未~load^i 状態へ戻るまでは、検索取得される度に，同じ~promiseを返すべきである。 `未~load^i 状態へ戻ったなら、 `次回の^em `~load済み^i への遷移を表現する，新たな~promiseが作成される。 ◎ In such a scenario, it is still useful to give images a promise-returning loaded property, which will signal the next state transition to a loaded state (or be already fulfilled if the image is already in a loaded state). This property should return the same promise every time it is retrieved, until the image moves backward from the loaded state into the unloaded state. Once that occurs, a new promise is created, representing the next transition to loaded.

`~load済み^i へ遷移し得る資源のみならず、 ~platformにおいてこれが有用になり得る，多くの場面がある — 例 ⇒＃ `完遂d^i へ遷移し得る~animation ／ `処分済み^i へ遷移し得る高価な資源／ `無効化-^i され得る~cache ◎ There are many places in the platform where this can be useful, not only for resources which can transition to loaded, but e.g. for animations that can transition to finished, or expensive resources that can transition to disposed, or caches that can become invalidated.

この~patternのちょっとした変種は、ある~classが［状態を遷移させる~method ］を包含していて，その策定者が［その状態~遷移が完了したとき，そのことを指示する］よう求めるときに生じる。その事例においては、当の~methodが~promiseを返すようにすることができる — 当の~classの~obj上の~propで指示する代わりに。 `Streams^cite は、何箇所かでこの変種を利用する — 例： `writer.close()$c ~method。一般に、［ ~methodは動作~用／ ~propは情報的な状態~遷移~用］に利用するべきである。 ◎ A slight variant of this pattern occurs when your class contains a method that causes a state transition, and you want to indicate when that state transition completes. In that case you can return a promise from the method, instead of keeping it as a property on your object. Streams uses this variant in several places, e.g. the writer.close() method. In general, methods should be used for actions, and properties for informational state transitions.

終わりに、この~patternの使い過ぎに注意。あらゆる状態~遷移に，対応する~promise~propが必要になるわけではない。有用になるかどうかの指標には、次が挙げられる： ◎ To close, we must caution against over-using this pattern. Not every state transition needs a corresponding promise-property. Indicators that it might be useful include:

作者の関心事は、ほぼ常に，［状態~遷移の`次回の^em~instance ］であり、遷移が生じる度に繰返し通知が必要になるのは，稀なとき。例えば、作者は［ `img$e が~loadし直される度にそれを知るよう望む］ことは稀にしかない — 通例的には、［単純に，画像の初回の~load／場合によっては，その `src$a を設定し直した後に生じる次回の~load ］に限られる。 ◎ Authors are almost always interested in the next instance of that state transition, and rarely need recurring notification every time it occurs. For example, rarely do authors care to know every time an img is reloaded; usually they simply care about the initial load of the image, or possibly the next one that occurs after resetting its src.
作者の関心事は、多くの場合，すでに生じた遷移に反応することであるとき。例えば、作者は，画像が［ ~loadされたとき／あるいは，すでに~load済みならアリな限り早く］に何らかの~codeを走らすよう求めることが多い。 ◎ Authors are often interested in reacting to transitions that have already occurred. For example, authors often want to run some code once an image is loaded; if the image is already loaded, they want to run the code as soon as possible.

3. ~promiseを利用すべきでないとき

~promiseは、多種の非同期的な演算に対し，広範に適用-可能であるが、非同期性のためであっても，依然として適切でない状況はある。 ◎ Although promises are widely applicable to asynchronous operations of many sorts, there are still situations where they are not appropriate, even for asynchronicity.

3.1. 繰返し生じる~event

複数回~生じ得るようなどの~eventも、 ~promiseの “~one-and-done” ~modelに対する良い候補にはならない。 ~promiseに対し、代わりに一連の~eventを表現するような，単独の非同期的な演算は無い。ここでは、従来の `EventTarget$I の用法で~~十分である。 ◎ Any event that can occur more than once is not a good candidate for the "one and done" model of promises. There is no single asynchronous operation for the promise to represent, but instead a series of events. Conventional EventTarget usage is just fine here.

3.2. ~streaming~data

~dataが増分的に生産され得るもので，その量は巨大になり得る場合、 ~promiseは，おそらく正解ではない。代わりに、 `ReadableStream$I ~classを利用するよう求めるであろう — それは、 ~data~streamを［その内容~全体を~memory内に~bufferすることなく処理して，増分的に組上げる］ことを作者に許容する。 ◎ If the amount of data involved is potentially large, and could be produced incrementally, promises are probably not the right solution. Instead, you’ll want to use the ReadableStream class, which allows authors to process and compose data streams incrementally, without buffering the entire contents of the stream into memory.

注記：すべての~dataが~memory内に~bufferされても懸念にならない事例では、便利~用に， `Streams^cite ~APIの傍系として~promise~APIを供せる場合もあるが、あくまで補助的な役割にとどまるであろう。 ◎ Note that in some cases, you could provide a promise API alongside a streaming API, as a convenience for those cases when buffering all the data into memory is not a concern. But this would be a supporting, not primary, role.

4. ~API設計の指導

仕様の~APIにおいて~promiseを［利用する／受容する］ことには、少数の微妙な側面がある。ここでは、よくある質問や状況に取組む。 ◎ There are a few subtle aspects of using or accepting promises in your API. Here we attempt to address commonly-encountered questions and situations.

4.1. ~error

4.1.1. ~promiseを返す関数は常に~promiseを返さなければナラナイ

~promiseを返す関数は、どの状況下であっても，常に~promiseを返さなければナラナイ — 結果が同期的に可用であっても，入力が妥当でないことを同期的に検出し得るとしても、この情報は，統一的な~channelを通して通信される必要がある。開発者が，次のように書いたなら： ◎ Promise-returning functions must always return a promise, under all circumstances. Even if the result is available synchronously, or the inputs can be detected as invalid synchronously, this information needs to be communicated through a uniform channel so that a developer can be sure that by doing

promiseFunction()
  .then(%onSuccess)
  .catch(%onFailure);

すべての［成功／~error ］が取扱われるようにするため。 ◎ they are handling all successes and all errors.

特に，~promiseを返す関数は、決して，~errorを同期的に投出するべきでない — そうすると、その使用者に~error取扱い~logicの重複を強いることになるので： catch (%e) { ... } ~block内に一つ, %p.catch(%e => { ... }) ~block内にもう一つ。引数を検証する際に~errorになったときでも、すべての~errorは，［却下される~promiseを返す］ことにより通達するべきである。 ◎ In particular, promise-returning functions should never synchronously throw errors, since that would force duplicate error-handling logic on the consumer: once in a catch (e) { ... } block, and once in a p.catch(e => { ... }) block. Even argument validation errors are not OK. Instead, all errors should be signaled by returning rejected promises.

~Web~IDLに基づく仕様においては、当の`演算$を`~promise型$を返すものとして宣言しておけば，この~~原則は自動的に守られる。［そのような`演算$／ ~Web~IDL~levelの型~変換／ `多重定義~解決$ ］により投出される例外は、いずれも，自動的に［却下される~promise ］に変換される。 `WEBIDL$r ◎ For Web IDL-based specs, this is taken care of automatically if you declare your operations to return a promise type. Any exceptions thrown by such operations, or by the Web IDL-level type conversions and overload resolution, are automatically converted into rejections. [WEBIDL]

4.1.2. 却下~事由は `Error^c ~instanceでなければナラナイ

~promiseの却下~事由は、常に~JS `Error$c 型の~instanceになるべきである — 同期的に投出される例外は，常に `Error$c 型の~instanceになるべきであることと，ちょうど同じく。このことは、一般に，`組込みの~JS~error型$か `DOMException$I を利用することを意味する。 ◎ Promise rejection reasons should always be instances of the JavaScript Error type, just like synchronously-thrown exceptions should always be instances of Error. This generally means using either one of the built-in JavaScript error types, or using DOMException.

4.1.3. 例外的な状況には却下を利用しなければナラナイ

正確に何を以って “例外的” と見なすかは，議論になるのが常だが、 ~API仕様において~promiseを却下することにする前に，常に自問するべきである：この関数が同期的であったとするとき、この状況下で期待されるのは［例外が投出されること, （ `null^jv, `false^jv, `undefined^jv の様な）失敗~値が返されること］どちらなのか？［当の~APIの使用者にとって，どの挙動がより有用になるか］について考するべきである。不確かなときは、［当の~APIが同期的であったとするとき，開発者たちは例外が投出されることを期待するかどうか］を考するべきである。 ◎ What exactly you consider "exceptional" is up for debate, as always. But, you should always ask, before rejecting a promise: if this function was synchronous, would I expect a thrown exception under this circumstance? Or perhaps a failure value (like null, false, or undefined)? You should think about which behavior is more useful for consumers of your API. If you’re not sure, pretend your API is synchronous and then think if your developers would expect a thrown exception.

却下が~~適切になる事例には、次が挙げられる： ◎ Good cases for rejections include:

［ ~storageへの書込み／~networkからの読取り］の様な入出力~演算に失敗したとき。 ◎ A failed I/O operation, like writing to storage or reading from the network.
要請された~taskを完了することは不可能なとき — 例えば ⇒ 当の演算が `accessUsersContacts()^c 【 “利用者の連絡先情報に~accessする” 】であって，利用者がその許可を否認した場合、何かで却下される~promiseを返すべきである。 ◎ When it will be impossible to complete the requested task: for example if the operation is accessUsersContacts() and the user denies permission, then it should return a rejected promise.
非同期的な演算を試みている間に，内部的に何かが壊れているような状況 — 例えば ⇒＃開発者から妥当でない~dataが渡された／当の環境は，この演算~用には妥当でない状態にある ◎ Any situation where something is internally broken while attempting an asynchronous operation: for example if the developer passes in invalid data, or the environment is in an invalid state for this operation.

却下が~~不適切になる事例には、次が挙げられる： ◎ Bad uses of rejections include:

非同期的に依頼された値を見出せなかったとき — 例えば ⇒ 【“非同期的な map” %asyncMap があったとして，】 %asyncMap.get(%key) は、 %key 用の~entryが無いときは， `undefined^jv で充足される【！for】~promiseを返すべきである。同様に， %asyncMap.has(%key) は、 `false^jv で充足される【！for】~promiseを返すべきである。 %key の不在は，例外的ではなかろうから、却下される~promiseを返すのは，拙い選択になろう。 ◎ When a value is asked for asynchronously and is not found: for example asyncMap.get("key") should return a promise for undefined when there is no entry for "key", and similarly asyncMap.has("key") should return a promise for false. The absence of "key" would be unexceptional, and so a rejected promise would be a poor choice.
当の演算は何かを問うものであり, その回答が否定的になるとき — 例えば ⇒ 当の演算が `hasPermissionToAccessUsersContacts()^c 【“利用者の連絡先情報への~accessは許可されているか？”】であって，利用者が許可を否認した場合、却下するのでなく， `false^jv で充足される~promiseを返すべきである。 ◎ When the operation is phrased as a question, and the answer is negative: for example if the operation is hasPermissionToAccessUsersContacts() and the user has denied permission, then it should return a promise fulfilled with false; it should not reject.

審判が必要yな事例には、次が挙げられる： ◎ Cases where a judgement call will be necessary include:

問いなのか請求なのか，より多義的な~API — 例えば ⇒ 当の演算が `requestUsersContacts()^c 【“連絡先情報の~~入力を要請する”】であって，利用者が許可を否認したときは、次のどちらを返すこともあり得る ⇒＃ `null^jv で充足される~promise／利用者が許可を否認したことを言明する~errorで却下される~promise ◎ APIs that are more ambiguous about being a question versus a demand: for example requestUsersContacts() could return a promise fulfilled with null if the user denies permission, or it could return a promise rejected with an error stating that the user denied permission.

4.2. ~promiseの受容-法

4.2.1. ~promise引数は解決されるべきである

一般に、引数として~promiseが期待される所では、 ~thenable 【 `then^c ~methodを備える~obj】も非~promise値も許容されるべきである — 引数を利用する前に，`~promiseとして解決する^emことにより。 `決して^em，次を行うべきでない：

入力の値に対する型~検出
~promiseと他の値との間の`多重定義$
~promiseを`共用体~型$内に置くこと

◎ In general, when an argument is expected to be a promise, you should also allow thenables and non-promise values by resolving the argument to a promise before using it. You should never do a type-detection on the incoming value, or overload between promises and other values, or put promises in a union type.

~Web~IDLを利用する仕様においては、これは，~Web~IDLの`~promise型$により自動的に~careされる。 ◎ In Web IDL-using specs, this is automatically taken care of by the Promise<T> type.

それが意味する所を~JS~codeで見るため、次の関数を考える — それは、所与の~promiseに %ms ~msの遅延を追加する： ◎ To see what it means in JavaScript code, consider the following function, which adds a delay of ms milliseconds to a promise:

function addDelay(%promise, %ms) {
    return Promise.resolve(%promise).then(%v =>
        new Promise(%resolve =>
            setTimeout(() => %resolve(%v), %ms);
        )
    );
}

var %p1 = addDelay(doAsyncOperation(), 500);
var %p2 = addDelay("value", 1000);

この例においては、 %p1 は，［［ `doAsyncOperation()^c から返される %promise ］が充足されてから 500 ~ms後に，その演算の値で充足される］ことになる（あるいは、 %promise が却下され次第，却下されることになる）。また，~~入力された引数は~promiseとして解決されるので、この関数は，文字列 `value^l を渡したときにも働ける： %p2 は、1000 ~ms後に， `value^l で充足されることになる。このような仕方で、本質的に，引数を［値に対し即時に充足される~promise ］として扱っている。 ◎ In this example, p1 will be fulfilled 500 ms after the promise returned by doAsyncOperation() fulfills, with that operation’s value. (Or p1 will reject as soon as that promise rejects.) And, since we resolve the incoming argument to a promise, the function can also work when you pass it the string "value": p2 will be fulfilled with "value" after 1000 ms. In this way, we essentially treat it as an immediately-fulfilled promise for that value.

4.2.2. ~promiseを返す関数として開発者から給された関数は “~promise-callされる” べきである

仕様の策定者は、［［ ~promiseを返す関数を期待しているもの【引数など】］に対し，開発者から給された %関数］に対しては， %関数が［ ~thenableや非~promise値を返す／例外を投出する］ことも許容するべきである。また、これらすべての事例に対し，［ %関数がそれに相似的な~promiseを返した］かのように扱うべきである。これは、［ `Promise.resolve()^c を利用したかのように，返された値を~promiseに変換する／ `Promise.reject()^c を利用したかのように，投出された例外を~catchして~promiseに変換する］ことにより行われるベキである。これは、関数を “~promise-callする” と呼ばれる。 ◎ If the developer supplies you with a function that you expect to return a promise, you should also allow it to return a thenable or non-promise value, or even throw an exception, and treat all these cases as if they had returned an analogous promise. This should be done by converting the returned value to a promise, as if by using Promise.resolve(), and catching thrown exceptions and converting those into a promise as if by using Promise.reject(). We call this "promise-calling" the function.

これの目的は、非同期的な形でも，同期的な形による［成功／失敗］と同じ反応が得られるようにすることにある。 ◎ The purpose of this is to allow us to have the same reaction to synchronous forms of success and failure that we would to asynchronous forms.

~Web~IDLを利用する仕様においては、［開発者~関数を`~callback関数$として宣言して，それを`呼出す$ ］ようにすれば，このことは自動的に~careされる。 ◎ In Web IDL-using specifications, this is automatically taken care of if you declare the developer function as a callback function and then invoke it.

付録：旧来の非同期性~API

~web~platform~APIには、 ~promiseの到来より前に書かれたものも数多くある — それらは、自前の場当的な仕方で，非同期的な演算の［完了／失敗］を通達している。これらには、次に挙げるものが含まれる： ◎ Many web platform APIs were written before the advent of promises, and thus came up with their own ad-hoc ways of signaling asynchronous operation completion or failure. These include:

`IndexedDB^cite のいくつかの~methodは、［ `onsuccess$c, `onerror$c ］~event~handler属性を伴う `IDBRequest$I ~objを返す。 `INDEXEDDB$r ◎ IndexedDB returning IDBRequest objects, with their onsuccess and onerror event handler attributes. [INDEXEDDB]
`File API: Directories and System^cite のいくつかの~methodは、 ~parameterに種々の［ %successCallback ／ %errorCallback ］をとる。 `FILE-SYSTEM-API$r ◎ File API: Directories and System’s methods taking various successCallback and errorCallback parameters. [FILE-SYSTEM-API]
`Notifications^cite の `requestPermission(deprecatedCallback)$c 演算は、自身の~callbackを `granted^l ／ `denied^l で~callする。（それ以来、これは~promiseも返すよう更新され，~callbackは省略可能にされた。） `NOTIFICATIONS$r ◎ Notifications’s requestPermission(deprecatedCallback) operation, which calls its callback with "granted" or "denied". (This has since been updated to also return a promise, making the callback optional.) [NOTIFICATIONS]
`XMLHttpRequest^cite の `send()$c ~methodは、複数回にわたり `onreadystatechange$c を誘発し， ~objの各種~propを状態s情報で更新する — ~~最終的な状態~遷移の［成功／失敗］を正確aに検出するためには、その情報に諮らなければならない。 `XHR$r ◎ XMLHttpRequest’s send() method, which triggers onreadystatechange multiple times and updates properties of the object with status information which must be consulted in order to accurately detect success or failure of the ultimate state transition. [XHR]

【仕様の策定者は、】これらに類似な何かが少しでも見出されるなら、それは~~止めて，代わりに~promiseを利用すること。 ◎ If you find yourself doing something even remotely similar to these, stop, and instead use promises.

◎要約

この文書は、 ~promiseを［作成する／受容する／操作する］ような仕様を書くための指導を与える。 ◎ This document gives guidance on how to write specifications that create, accept, or manipulate promises.