Promise を利用する仕様の書き方 — Writing Promise-Using Specifications

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.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.1. ~error

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

4.2. ~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);