diff --git a/index.bs b/index.bs index b735c85..ef5b825 100644 --- a/index.bs +++ b/index.bs @@ -13,6 +13,16 @@ Link Defaults: html (dfn) queue a task/browsing context/active document/in paral Ignored Vars: O, f, args, x, cb +
+spec:infra; type:dfn; text:list
+
+ +
+urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
+    text: PerformPromiseThen; url: #sec-performpromisethen; type: abstract-op
+    text: all(); for: Promise; url: #sec-promise.all; type: method
+
+

Introduction

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. @@ -151,13 +161,13 @@ Promises abstract away many of the details regarding notifying the developer abo However, in cases where you need to interface with developer code in more ways than can be mediated via the promise, you'll still need to queue a task. For example, you may want to fire an event, which can call into developer event handlers. Or you may need to perform a structured clone operation, which can trigger getters. If these things must be done inside the asynchronous portion of your algorithm, you need to specify that they are done via a queued task, and with a specific task queue. This nails down the exact time such developer-observable operations happen both in relation to other queued tasks, and to the microtask queue used by promises. -As an example, the following steps will return a promise resolved after ms milliseconds, but also fire an event named timerfinished on window: +As an example, the following steps will return a promise resolved after ms milliseconds, but also fire an event named timerfinished on an object |object|: 1. Let p be a new promise. 1. Run the following steps in parallel: 1. Wait ms milliseconds. 1. Resolve p with undefined. - 1. Queue a task to fire a simple event named timerfinished at the browsing context active document's Window object. + 1. Queue a task to fire a simple event named timerfinished at the |object|. 1. Return p.

Accepting Promises

@@ -249,9 +259,42 @@ If the algorithm using these shorthands is running in parallel, the short

Aggregating Promises

-The result of waiting for all of a collection of promises is a promise created by calling Promise.all(promiseArray), where promiseArray is that collection in array form and we use the initial value of Promise.all. - -This phrase is useful when you wish to perform multiple asynchronous operations in parallel that return promises, and then react to them all together. If all of the given promises fulfill, then the resulting promise will be fulfilled with an array corresponding to the fulfillment values. If any of them reject, then the resulting promise will be rejected with the first rejection reason to occur. +To wait for all of a list of promises |promises|, with success steps |successSteps| that take a list of JavaScript values and failure steps |failureSteps| that take a rejection reason JavaScript value, perform the following steps: + +1. Let |fullfilledCount| be 0. +1. Let |rejected| be false. +1. Let |rejectionHandler| be a built-in function that takes an argument |arg| and performs the following steps: + 1. If |rejected| is true, abort these steps. + 1. Set |rejected| to true. + 1. Perform |failureSteps| given |arg|. +1. Let |index| be 0. +1. Let |total| be |promises|'s [=list/size=]. +1. Let |result| be a list containing |total| null values. +1. [=list/For each=] |promise| of |promises|: + 1. Let |promiseIndex| be |index|. + 1. Let |fulfillmentHandler| be a built-in function that takes an argument |arg| performs the following steps: + 1. Set |result|[|promiseIndex|] to |arg|. + 1. Set |fullfilledCount| to |fullfilledCount| + 1. + 1. If |fullfilledCount| equals |total|, then perform |successSteps| given |result|. + 1. Perform PerformPromiseThen(|promise|, |fulfillmentHandler|, |rejectionHandler|). + 1. Set |index| to |index| + 1. + +This phrase is useful when you wish to aggregate the result of multiple promises, and react to them all together, in the same way that {{Promise/all()|Promise.all()}} functions for JavaScript code. + +To get a promise for waiting for all of a list of promises |promises|, with success steps |successSteps| that take a list of JavaScript values and optional failure steps |failureSteps| that take a rejection reason JavaScript value, perform the following steps: + +1. Let |promise| be a new promise. +1. If |failureSteps| were not given, let them be steps taking an argument |arg| that throw |arg|. +1. Let |successStepsWrapper| be the following steps, given |results|: + 1. Let |stepsResult| be the result of performing |successSteps| given |results|. If these steps threw an exception, reject |promise| with that exception. + 1. Resolve |promise| with |stepsResult|. +1. Let |failureStepsWrapper| be the following steps, given |reason|: + 1. Let |stepsResult| be the result of performing |failureSteps| given |reason|. If these steps threw an exception, reject |promise| with that exception. + 1. Resolve |promise| with |stepsResult|. +1. Wait for all of |promises|, given |successStepsWrapper| and |failureStepsWrapper|. +1. Return |promise|. + +This phrase is useful when you wish to aggregate the results of multiple promises, and then produce another promise from them. An example usage of this phrase is found in [[#example-batch-request]]. @@ -483,15 +526,15 @@ The following steps might be inserted toward the end of some algorithm for ready

batchRequest(urls)

-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. +Several places in [[SERVICE-WORKERS]] use get a promise to wait for all. batchRequest illustrates a simplified version of one of their uses. It takes as input a list 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. -1. Let responsePromises be a new empty list +1. Let responsePromises be a new empty list. 1. For each value url of urls, - 1. Let url be the result of converting url to a USVString. - 1. Let req be the result of creating a new Request passing url to the constructor. - 1. Let p be the result of calling fetch with req. + 1. Let url be the result of converting url to a {{USVString}}. + 1. Let req be the result of creating a new {{Request}} passing url to the constructor. + 1. Let p be the result of calling {{WindowOrWorkerGlobalScope/fetch()}} with req. 1. Add p to responsePromises. -1. Return the result of waiting for all of responsePromises. +1. Return the result of getting a promise to wait for all of responsePromises, given success steps that take |results| and returns the result of converting that list into a JavaScript Array.

WebIDL and Promises