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を返すことになる。 同期的な関数が “~nothing”（すなわち， `undefined^jv ）を返し得るのとちょうど同じく、非同期的な関数から返される~promiseも，~nothing（ `undefined^jv ）で充足し得る — この事例においては、~promiseの充足は，単純に非同期的な演算の完了を通達する。 【† より詳しく述べるなら、非同期的な演算を “包装する” 関数 — “その実行を約束する ~promise~objとして即時に（同期的に）返すような関数” の略記。】 ◎ 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:

• 非同期的な I/O 演算： ~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を利用していた。 これらは， 後述の付録 にて文書~化されているので、何が今や旧式と見なされているかについての~ideaを得られる。 今や、~platform~primitiveとして，~promiseがある — そのような~approachは最早~必要とされない。 ◎ Previously, web specifications used a large variety of differing patterns for asynchronous operations. We’ve documented these in an appendix below, so you can get an idea of what is now considered legacy. Now that we have promises as a platform primitive, such approaches are no longer necessary.

2.2. 一度限りの “~event”

~promiseは、すでに 充足された／却下された 後でも， 【まだ処理が終わっていないかのように，その結果が通達されるよう】 申込めるので、ある種の “~event” においては，とても有用になり得る。 一度だけ起こるものであって，作者が すでに生じた後にも その~statusを観測したいと欲することが多いとき、［ 充足されたのは，それが生じた時点とされる ］ような~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” の原型的な例として、~loadedかどうかを指示するものが挙げられる： 画像, ~font, あるいは文書などの資源でさえ、［［ 資源が全部的に~loadされたときに限り，充足される（あるいは，資源の~load時に~errorが~~生じたときは却下される） ］ような~promise ］を返すような， `loaded^c ~propertyを供し得る。 作者は常に、 `resource.loaded.then(onLoaded, onFailure)^c と記すことで，［ 資源の用意ができ次第，実行されることになる ］ような動作が~queueされる。 これは、［ 資源がすでに~loadされていたときでも， %onLoaded を実行する小taskを~queueする ］ように，働く。 対照的に，~event~modelでは、［ ~eventが発火された時点で，作者がまだ申込んでいない場合 ］には、その情報は失われる。 ◎ 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 an event model, 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>^c 要素があるとする。 それらは、 `src^c ~propertyを再設定することにより，再~loadさせられる — すなわち，それらの状態は、 `~loaded^i から `未load^i へ戻るようにも遷移し得る。 したがって、 `~loaded^i になることは，一度限りではない： 代わりに、画像は，実際には［ `~loaded^i, `未load^i の状態を往復する ］ような状態~machineを成す。 そのような局面においては、それぞれの画像に［ ~promiseを返す `loaded^c ~property ］を与えることが，依然として有用になる — それは、次回の［ `~loaded^i 状態へ移行する状態~遷移 ］を通達する（あるいは、画像がすでに `~loaded^i 状態にあるならば，充足される~promiseを返す）。 この~propertyは、画像が `~loaded^i 状態から `未load^i 状態へ戻るまでは、取得0される度に，同じ~promiseを返すべきである。 `未load^i 状態へ戻ったなら、次回の `~loaded^i への遷移を表現するような，新たな~promiseが作成される。 ◎ 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 property, 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. 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.

`~loaded^i へ遷移し得る資源のみならず、~platformにおいて これが有用になり得る，多くの場面がある — 例えば： `終止^i へ遷移し得る~animation ／ `処分済み^i へ遷移し得る高価な資源 ／ `未load^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 unloaded.

この~patternのちょっとした変種は、ある~classが［ 状態を遷移させるような~method ］を包含していて，その策定者が［ その状態~遷移が完了したときに，それを指示させたい ］と欲しているときに生じる。 その事例においては、［ その~methodが~promiseを返すようにする ］ことができる — その~classの~obj上の~propertyに指示させる代わりに。 `Streams API$ は、その `wait()^c ／ `close()^c ~methodに対し，この変種を利用する。 一般的に、~methodは動作~用に, ~propertyは情報的な状態~遷移~用に，利用されるべきである。 ◎ 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. The streams API uses this variant for its wait() and close() methods. In general, methods should be used for actions, and properties for informational state transitions.

終わりに、この~patternの使い過ぎに注意。 あらゆる状態~遷移に，対応する~promise~propertyが必要になるわけではない。 有用になるかどうかの指標には、次が挙げられる： ◎ 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:

• 作者は、ほぼ常に，その状態~遷移の次の~instanceに関心があり、遷移が生じる度に繰返し通知が必要になるのは，稀なとき。 例えば、作者は，画像~要素が再loadされる度に それを知りたいと望むことは稀にしかない — 通例的には、単純に，画像の初回の~load, 場合によっては その `src^c を再設定した後に生じる次回の~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 image element 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^c の用法で~~十分である。 ◎ 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はおそらく，正解ではない。 代わりに、開発~下にある `Streams API$ を利用したいと欲するであろう — それは、作者が，~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 under-development streams API, which allows authors to process and compose data streams incrementally, without buffering the entire contents of the stream into memory.

注記： すべての~dataが~memory内に~bufferされても懸念にならないような事例に対しては、便宜のため，Streams 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. 非同期的な~algo

この節は、主に仕様の書手~向けである。 ここでは、注釈文において，非同期的な~algo~flowを明白化するときの~vagariesについて扱う。 これについての背景は、 非同期性についての Anne 氏の~blog-post †を見よ。 【† 要約：非同期に実行される~algoの中で，不用意に大域的な~propertyを汚すと、並列的に実行されている JavaScript ~codeの信頼性を確保できなくなる。】 ◎ This section is primarily for spec writers, dealing with the vagaries of clearly manifesting asynchronous algorithm flow in prose. For more background on this subject, see Anne’s blog post on asynchronicity.

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

5.1. ~promiseの作成-法

【 内部ではすでに過去であっても， “解決される” ／ “却下される” と記しているのは、外部に対しては %resolve ／ %reject を通して非同期に（未来に）通達されることになるためである。 冗長に書くならば、 “解決されるのは確定しているが，まだ そのときに行う処理は呼出されていない” 等々の様になるであろう。 】

5.2. ~promiseの操作-法

( ~promise %p, 充足~値 %x ) が与えられている下における，句 %x で %p を 解決する とは、［［ %p の作成-時に格納済みの， %resolve 関数 ］に，引数 %x を渡して~callする ］ことを表す略記である。 ◎ "Resolve p with x" is shorthand for calling a previously-stored resolve function from creating p, with argument x.

( ~promise %p, 事由~値 %r ) が与えられている下における，句 %r で %p を `却下する@ とは、［［ %p の作成-時に格納済みの， %reject 関数 ］に，引数 %r を渡して~callする ］ことを表す略記である。 ◎ "Reject p with r" is shorthand for calling a previously-stored reject function from creating p, with argument r.

【 同じ “解決-”, “却下-” が、新たな~promiseを作成するときと，操作するときの両者に用いられてることに注意。 “%x で`解決される~promise$” は、 “`新たな~promise$ %p を作成してから， %x で %p を`解決-$した結果の %p” と同じものになるように見受けられる（が、確かめたわけではない）。 】

これらの略記が，`並列的$に走らせている~algoの中で利用されている場合、 %p に`関連する設定群~obj$の`担当の~event~loop$上に，格納済みの関数を~callする`~taskを~queueする$。 ◎ If the algorithm using these shorthands is running in parallel, the shorthands queue a task on p’s relevant settings object’s responsible event loop to call the stored function.

5.3. ~promiseに対する反応-法

return %p.then(() `射$ undefined);

return %p.then(%x 射 2 * %x);

5.4. 複数の~promiseの集成-法

この句の用法~例は `batchRequest( urls )^c 節 に見出せる。 ◎ An example usage of this phrase is found in §6.7 batchRequest ( urls ).

5.5. ~promise-call法

関数 %f が与えられた下で， %f(...%args) を ~promise-call したときの結果は、次で与えられる： ◎ The result of promise-calling f(...args) is:

• %f を~callして充足~値 %v が返されたならば ⇒ %v で`解決される~promise$ ◎ If the call returns a value v, the result of resolving v as a promise.
• %f を~callして例外 %e が投出されたならば ⇒ %e で`却下される~promise$ ◎ If the call throws an exception e, a promise rejected with e.

function promiseCall(%f, `...args^V) {
    try {
        return Promise.resolve(%f(`...args^V));
    } catch (%e) {
        return Promise.reject(%e);
    }
}

5.6. ~realmについての注記

すべての事例において、 Promise.resolve の `初期値@ の様な句を利用するときは、［［［ 指定されている関数（この場合は `resolve^c ） ］に結付けられている`~realm$† ］の中での初期値 ］を意味する。 例えば、 `window.f()^c が “`1^jv で`解決される~promise$” を返すものと指定されている場合： ◎ In all cases, when we use phrases like "the initial value of Promise.resolve," we mean the initial value within the realm associated to the function being specified. So for example, if window.f() is specified to return "a promise resolved with 1," then:

【† “~~領域” — 大雑把に言えば、［ 当の~codeが参照している, または作成した，~obj／関数 ］が “属する” ECMAScript 大域環境 】

assert(windowA.f().constructor === windowA.Promise);
assert(windowB.f().constructor === windowB.Promise);

/* 
関数が呼出されている~objの~realmは、効果を持たない
— 関数の~realmだけが，関係0する：
◎
The realm of the object the function is being invoked on has no effect;
the function’s realm is all that matters.
*/
assert(windowA.f.call(windowB).constructor === windowA.Promise);

/* 
次のものは、~promise構築子に対する変異も伝播することを意味する：
◎
This means mutations to the Promise constructor also propagate.
*/

windowA.Promise.prototype.foo = "bar";
assert(windowA.f().foo === "bar");
assert(windowB.f().foo === undefined);

/* 
`Promise.resolve^c の~algoは、~globalを診る代わりに，内在的な, 改変-不能な `~Promise0$ を利用するので、
名前 `Promise^l の~global~propertyを改変しても，返値には影響0しない
◎
But since the algorithm for Promise.resolve uses the un-modifiable %Promise% intrinsic, instead of consulting the global, modifying the global property named
"Promise" does not impact the return value.
*/
const %oldPromise = windowA.Promise;
windowA.Promise = () `射$ throw new Error(
    "開発者~codeは壊しますが，~platform~codeは壊しません。"
);
assert(windowA.f().constructor !== windowA.Promise);
assert(windowA.f().constructor === %oldPromise);

更なる情報については、 この www-tag ~thread を見よ — とりわけ返信を。 ◎ For more information, see this www-tag thread, especially the replies.

6.1. `delay( ms )^c

`delay^c は、 %ms ~ms内に充足されることになる，~promiseを返す関数である。 ~promiseの解決は，一~行の注釈文で記せる： ◎ delay is a function that returns a promise that will be fulfilled in ms milliseconds. It illustrates how simply you can resolve a promise, with one line of prose.

1. %ms ~LET ToNumber(%ms) ◎ Let ms be ToNumber(ms).
2. %ms ~LET ［ %ms ~EQ `NaN^jv ならば `+0^jv ／ ~ELSE_ { %ms, `+0^jv } の最大 ］ ◎ If ms is NaN, let ms be +0; otherwise let ms be the maximum of ms and +0.
3. %p ~LET 新たな~promise ◎ Let p be a new promise.

4. 次の手続きを`並列的$に走らせる： ◎ Run the following steps in parallel:

   1. %ms ~ms間 待機する ◎ Wait ms milliseconds.
   2. `undefined^jv で %p を`解決する$ ◎ Resolve p with undefined.
5. ~RET %p ◎ Return p.

JavaScript による等価な関数は，次の様になるであろう： ◎ The equivalent function in JavaScript would be

function delay(%ms) {
    %ms = Number(%ms);
    %ms = Number.isNaN(%ms) ? +0 : Math.max(%ms, +0);
    return new Promise(%resolve `射$ setTimeout(%resolve, %ms));
}

あるいは、指定された手続きに，より一対一に対応するように記すなら： ◎ or, in a more one-to-one correspondence with the specified steps,

function delay(%ms) {
    // 段 1, 2
    %ms = Number(%ms);
    %ms = Number.isNaN(%ms) ? +0 : Math.max(%ms, +0);

    // 段 3
    let %resolve;
    const %p = new Promise(%r 射 { %resolve = %r; });

    // 段 4
    setTimeout(() 射 %resolve(undefined), %ms);

    // 段 5
    return %p;
}

6.2. `validateddelay( ms )^c

`validatedDelay^c 関数は、その引数を検証することになる点を除いて， `delay^c 関数 とほぼ同様である。 これは、どの非同期的な演算であれ、その開始~前に即時の失敗を通達させるために，却下される~promiseを利用する方法を示す： ◎ The validatedDelay function is much like the delay function, except it will validate its arguments. This shows how to use rejected promises to signal immediate failure before even starting any asynchronous operations.

1. %ms ~LET ToNumber(%ms) ◎ Let ms be ToNumber(ms).
2. ~IF［ %ms ~EQ `NaN^jv ］ ⇒ ~RET `TypeError^jv で`却下される~promise$ ◎ If ms is NaN, return a promise rejected with a TypeError.
3. ~IF［ %ms ~LT ~zero ］ ⇒ ~RET `RangeError^jv で`却下される~promise$ ◎ If ms is less than zero, return a promise rejected with a RangeError.
4. %p ~LET 新たな~promise ◎ Let p be a new promise.

5. 次の手続きを`並列的$に走らせる： ◎ Run the following steps in parallel:

   1. %ms ~ms間 待機する ◎ Wait ms milliseconds.
   2. `undefined^jv で %p を`解決する$ ◎ Resolve p with undefined.
6. ~RET %p ◎ Return p.

JavaScript による等価な関数は，次の様になるであろう： ◎ The equivalent function in JavaScript would be

function delay(%ms) {
    %ms = Number(%ms);

    if (Number.isNaN(%ms)) {
        return Promise.reject(new TypeError("Not a number."));
    }
    if (%ms < 0) {
        return Promise.reject(new RangeError("ms must be at least zero."));
    }

    return new Promise(%resolve `射$ setTimeout(%resolve, %ms));
}

6.3. `addDelay( promise, ms )^c

`addDelay^c は、引数 %promise が`決着-$してから，返される~promiseが`決着-$するまでの合間に 余分な %ms ~msの遅延を追加する関数である。 引数 %promise を`~promiseとして解決する$ことで、非~promise値や~thenableも %promise に渡せるようにしている所に注目。 ◎ addDelay is a function that adds an extra ms milliseconds of delay between promise settling and the returned promise settling. Notice how it resolves the incoming argument to a promise, so that you could pass it a non-promise value or a thenable.

1. %ms ~LET ToNumber(%ms) ◎ Let ms be ToNumber(ms).
2. %ms ~LET［ %ms ~EQ `NaN^jv ならば `+0^jv ／ ~ELSE_ { %ms, `+0^jv } の最大 ］ ◎ If ms is NaN, let ms be +0; otherwise let ms be the maximum of ms and +0.
3. %p ~LET `新たな~promise$ ◎ Let p be a new promise.
4. %resolvedToPromise ~LET %promise で`解決される~promise$ ◎ Let resolvedToPromise be the result of resolving promise to a promise.

5. 充足~値 %v による %resolvedToPromise の`充足-時$には、次の手続きを`並列的$に遂行する： ◎ Upon fulfillment of resolvedToPromise with value v, perform the following steps in parallel:

   1. %ms ~ms間 待機する ◎ Wait ms milliseconds.
   2. %v で %p を`解決する$ ◎ Resolve p with v.

6. 事由~値 %r による %resolvedToPromise の`却下-時$には、次の手続きを`並列的$に遂行する： ◎ Upon rejection of resolvedToPromise with reason r, perform the following steps in parallel:

   1. %ms ~ms間 待機する ◎ Wait ms milliseconds.
   2. %r で %p を`却下する$ ◎ Reject p with r.
7. ~RET %p ◎ Return p.

JavaScript による等価な関数は，次の様になるであろう： ◎ The equivalent function in JavaScript would be

function addDelay(%promise, %ms) {
    %ms = Number(%ms);
    %ms = Number.isNaN(%ms) ? +0 : Math.max(%ms, +0);

    let %resolve, %reject;
    const %p = new Promise((%r, %rr) `射$ { %resolve = %r; %reject = %rr; });

    const resolvedToPromise = Promise.resolve(%promise);
    resolvedToPromise.then(
        %v 射 setTimeout(() 射 %resolve(%v), %ms),
        %r 射 setTimeout(() 射 %reject(%r), %ms)
    );

    return %p;
}

6.4. `resource.open ( resourcePath, openingOperation )^c

`resource.open^c は、［ その働きのほとんどは，渡された関数 %openingOperation の実行-が占める ］が、しかる~~後，［ この演算の結果を反映するように `resource^c の~propertyたちを更新する ］ような，~methodである。 これは、［ Streams 仕様にて用いられている一部の技法 ］の，単純化された~versionである。 この~methodは、別の関数を `~promise-call$ する方法, その理由について説明0するために~~導入したものである。 ◎ resource.open is a method that executes the passed function openingOperation to do most of its work, but then updates the resource’s properties to reflect the result of this operation. It is a simplified version of some of the techniques used in the streams specification. The method is meant to illustrate how and why you might promise-call another function.

1. %resourcePath ~LET ToString(%resourcePath) ◎ Let resourcePath be ToString(resourcePath).
2. %openingPromise ~LET %openingOperation(%resourcePath) を`~promise-call$した結果 ◎ Let openingPromise be the result of promise-calling openingOperation(resourcePath).

3. ~RET 次の~handlerで %openingPromise を`変形した$結果： ◎ Return the result of transforming openingPromise with:

   • ［ `this.status^c ~SET `opened^l ］にするような，充足~handler。 ◎ A fulfillment handler that sets this.status to "opened".
   • 引数 %r を伴って~callされたときに［ `this.status^c ~SET `errored^l； `this.error^c ~SET %r ］にするような，却下~handler。 ◎ A rejection handler that, when called with argument r, set this.status to "errored" and this.error to r.

上に定義された `promiseCall^c 関数 を利用すれば、JavaScript による等価な関数は，次の様になるであろう： ◎ The equivalent function in JavaScript would be

resource.open = function (%resourcePath, %openingOperation) {
    %resourcePath = String(%resourcePath);

    return promiseCall(%openingOperation, %resourcePath).then(
        %v `射$ {
            this.status = "opened";
        },
        %r 射 {
            this.status = "errored";
            this.error = %r;
        }
    );
};

◎ using the promiseCall function defined above.

resource.open(%synchronouslyOpenTheResource).then(%doSomethingElse);

6.5. %environment`.ready^c

ある “環境” を表現する `Environment^c ~obj %environment の `ready^c ~methodは、環境の何らかの部分 — 例えば，~DOM文書 — が “~ready（準備済み）” になったときに，それを通達する~propertyであるとする。 ここでは、その環境における非同時性について~~定式化する方法を説明0する： ◎ environment.ready is a property that signals when some part of some environment becomes "ready," e.g. a DOM document. It illustrates how to encode environmental asynchronicity.

• どの `Environment^c ~objも，［ 新たな~promiseに初期化される， [[ready]] 内部slot ］を有するようにする。 %environment の `ready^c 取得子が~callされたときは、この `Environment^c ~objの [[ready]] 内部slotの値が返されるとする。 ◎ Let every Environment object have a [[ready]] internal slot, initialized with a new promise. When the getter for environment.ready is called, return the value of this Environment object’s [[ready]] internal slot.

• 次の各~段が `Environment^c ~objを~readyにするような，ある~algoの末尾側に挿入されることになるであろう： ◎ The following steps might be inserted toward the end of some algorithm for readying Environment objects:

  • 当の環境が成功裡に~readyになったときは ⇒ `undefined^jv で［ `Environment^c ~obj の [[ready]] ~promise ］を`解決する$ ◎ If the environment becomes ready successfully, resolve this Environment object’s [[ready]] promise with undefined.
  • 当の環境が~readyになるのに失敗したときは ⇒ ［ ~load失敗を説明する `Error^jv ~instance ］で［ `Environment^c ~obj の [[ready]] ~promise ］を`却下する$ ◎ If the environment fails to become ready, reject this Environment object’s [[ready]] promise with an Error instance explaining the load failure.

6.6. `addBookmark()^c

`addBookmark^c は、［ 現在の~web頁を~bookmarkとして追加する ］ことを利用者に要請する，関数である。 これは、 何度も行われる設計~作業 から取り出されたものであり、 環境上の非同時性を，現実にありそうな局面として解ってもらうと伴に、即時の却下についても説明0するものである。 ◎ addBookmark is a function that requests that the user add the current web page as a bookmark. It’s drawn from some iterative design work and illustrates a more real-world scenario of appealing to environmental asynchrony, as well as immediate rejections.

1. ~IF［ この~methodは、明示的な利用者~動作の結果として，呼出された ］のではない ⇒ ~RET ［ 名前 `SecurityError^l の新たな `DOMException$c ］で`却下される~promise$ ◎ If this method was not invoked as a result of explicit user action, return a promise rejected with a new DOMException whose name is "SecurityError".

2. ~IF［ 文書の［ mode of operation† ］ ~EQ standalone†† ］ ⇒ ~RET ［ 名前 `NotSupported^l の新たな `DOMException$c ］で`却下される~promise$ ◎ If the document’s mode of operation is standalone, return a promise rejected with a new DOMException whose name is "NotSupported".

   【† display mode, ††standalone ？】
3. %promise ~LET 新たな~promise ◎ Let promise be a new promise.
4. %info ~LET ［ ~web~appの~metadata ］を得た結果 ◎ Let info be the result of getting a web application’s metadata.

5. 次の手続きを`並列的$に走らせる： ◎ Run the following steps in parallel:

   1. %info を用いて, ~UAに特有の方式で，［ 末端利用者が~bookmarkを追加したいと欲するかどうか，選択する ］ことを許容する ◎ Using info, and in a manner that is user-agent specific, allow the end user to make a choice as to whether they want to add the bookmark.

      1. ~IF［ 末端利用者は ~bookmarkの追加-要請を中止した（利用者が~escapeキーを叩いた, “~cancel” ~buttonを押したなど） ］ ⇒ ［ 名前 `AbortError^l の新たな `DOMException$c ］で %promise を`却下する$ ◎ If the end-user aborts the request to add the bookmark (e.g., they hit escape, or press a "cancel" button), reject promise with a new DOMException whose name is "AbortError".
      2. ~ELSE ⇒ `undefined^jv で %promise を`解決する$ ◎ Otherwise, resolve promise with undefined.
6. ~RET %promise ◎ Return promise.

6.7. `batchRequest( urls )^c

`SERVICE-WORKERS$r では、何箇所かで “`すべてを待機する$” が利用されている。 `batchRequest^c †は、その種のある利用を単純化した~versionを説明0する。 それは、一連の~URLを入力にとり，各~URLを~fetchして作成された `Response$c ~objからなる配列に対する~promiseを返す。 いずれかの~fetchが失敗した場合には、その失敗で`却下される~promise$を返す。 ◎ Several places in [SERVICE-WORKERS] use waiting for all. batchRequest illustrates a simplified version of one of their uses. It takes as input an iterable of URLs, and returns a promise for an array of Response objects created by fetching the corresponding URL. If any of the fetches fail, it will return a promise rejected with that failure.

【† `batchRequest^c は、現在の仕様には無い。 おそらく、別名の~method（ `addAll^c ？）に置き換えられている。 】

1. %応答~promiseたち ~LET 新たな空~list ◎ Let responsePromises be a new empty list

2. %urls 内の~EACH ( 値 %url ) に対し： ◎ For each value url of urls,

   1. %url ~LET %url を `USVString$c に変換した結果 ◎ Let url be the result of converting url to a USVString.
   2. %req ~LET 新たな `Request$c を，その構築子に %url を渡して作成した結果 ◎ Let req be the result of creating a new Request passing url to the constructor.
   3. %p ~LET %req を引数に `fetch()$c を~callした結果 ◎ Let p be the result of calling fetch with req.
   4. %応答~promiseたち に %p を追加する ◎ Add p to responsePromises.
3. ~RET %応答~promise~list の`すべてを待機-$した結果 ◎ Return the result of waiting for all of responsePromises.

7.1. ~PromiseT 型の返値

すべての WebIDL 返値と同様、返値として~PromiseT 型を宣言することは、~algoの値を返す実際の段には，影響0しない。 それは単純に書式上のものであり、［ ~promiseでない何か, または WebIDL %T 型でない充足~値による~promise ］を返すように仕様を書くことは、不正になる。 ◎ Like all WebIDL return values, declaring a return value of type Promise<T> has no impact on the algorithm’s actual return steps. It is simply a form of documentation, and if you return something that is not a promise or is a promise with a fulfillment value that is not of WebIDL-type T, then you have written incorrect documentation into your spec.

しかしながら、［ ~methodや~accessorを，~promiseを返すように宣言する ］ことには、一つの重要な影響0がある： それは、［ さもなければ — 例えば，型~変換に失敗した結果として — 投出されるような例外が、必ず~catchされ，却下される~promiseに転換される ］ようにする（ WebIDL の “演算” 節 の “If O has a return type that is a promise type …” 【“〜の返値~型が~promise型であるならば…”】 の所, および その文書~~全体に散らばる，それに類する句を見よ）。 これにより、少なくとも例外については、［ ~promiseを返す関数は，常に~promiseを返すべきである ］原則は，自動的に守られることになる。 ◎ However, declaring that your method or accessor returns a promise does have one important impact: it ensures that any exceptions that it would otherwise throw, e.g. as a result of failed type conversions, are caught and turned into rejected promises. (See the "Operations" section, "If O has a return type that is a promise type …", and similar phrases scattered throughout the document.) This automatically takes care of the advice in §4.1.1 Promise-Returning Functions Should Always Return Promises, at least for exceptions.

7.2. ~PromiseT 型の~parameter

WebIDL ~methodの~parameterが ~PromiseT 型として宣言されているとき、その~parameterとして渡された どの引数も自動的に`~promiseとして解決され$、 ~promise引数は解決されるべきである 原則は守られることになる。 ◎ When a parameter of a WebIDL method is declared as Promise<T>, it will automatically resolve any arguments passed in that position. This will take care of the "Promise Arguments Should Be Resolved" advice above.

WebIDL ~PromiseT 型の引数が得られたなら、 WebIDL による “~promiseが決着したときの手続きを遂行する” ~algoを利用できる。 これは、上の `充足-時$には…／`却下-時$には… の略記~句とよく似るが、 “充足-時には” の手続きを走らす前に，［ ~promiseの充足~値を WebIDL 型 %T に変換する ］段も追加されている。 加えて、仕様の~algoが［ 前者／後者の手続きを走らせて導出される，~promise ］を返すようにもする。 型~変換に失敗した場合、~algoは［ それを失敗させた~error ］で却下される~promiseを返すようにする。 ◎ If you have a WebIDL Promise<T> argument, you can use the WebIDL perform some steps once a promise is settled algorithm. This is much like our upon fulfillment … and upon rejection … shorthand phrases above, but it will add an additional step of converting the promise’s fulfillment value to the WebIDL type T before running any upon-fulfillment steps. Additionally it causes your algorithm to return a promise derived from running those steps. If the type conversion fails, your algorithm will return a promise rejected with the error causing that failure.

ここでの %T は、 充足~値の WebIDL 型を指すことに注意。 更には、 WebIDL の “~promiseが`決着-$したときの手続きを遂行する” ~algoを利用する場合にのみ，影響0するものであり、他の仕方で~promiseを利用する場合（別の関数を通して それを渡すなど）は，そうならない。 型が何でもよければ、 `Promise<any>^c 型を~parameterに利用することを勧める。 ◎ Note that the T here refers to a WebIDL type for the fulfillment value. Furthermore, it only has impact if you use the WebIDL "perform some steps …" algorithm, and not if you use the promise in other ways (such as passing it along to another function). If that is not relevant, we advise using Promise<any> for parameters.

// 妥当でない WebIDL
void f(Promise<DOMString> %x);
void f(DOMString %y);

7.3. ~promiseを返す開発者~関数

WebIDL においては、`~callback関数$として宣言することにより（または、稀な事例では`~callback~interface$を介して）、 JavaScript 関数を~~引数にとれるようになる。 それは後に、 WebIDL 値の~listを~~引数に 呼出される。 ◎ In WebIDL, you consume JavaScript functions by declaring them as WebIDL callback functions (or, in rare cases, via callback interfaces) and later invoking them with a list of WebIDL values.

WebIDL の仕組みを利用して JavaScript 関数を~callすることにした場合、呼出~algoにおいては、自動的に返値を［ ~promiseとして解決する, あるいは 例外が投出されたなら却下される~promiseに変換する ］ことになり、［ ~promiseを返す関数として開発者から給された関数は “~promise-callされる” べきである ］原則は，自動的に守られることになる。 ◎ If you use WebIDL’s mechanisms for calling JavaScript functions, the invocation algorithm will automatically resolve return values and convert thrown exceptions into rejected promises. This automatically takes care of the advice in §4.3.2 Developer-Supplied Promise-Returning Functions Should Be "Promise-Called".

7.4. 例

interface ProtectedResource {
  Promise<void> requestAccess();
  // ...
};

interface Quoter {
  Promise<DOMString> getInterestingQuote();
};

interface StateMachine {
  readonly attribute Promise<void> loaded;

  Promise<void> load();
};

interface Waiter {
  void waitUntil(Promise<any> %promise);
};

callback Promise<DOMString> ResourceLoader();

interface ResourceConsumer {
  void loadAndConsumeResource(ResourceLoader %loader);
};