Skip to content

Commit

Permalink
doc: improve documentation for safe Promise statics alternatives
Browse files Browse the repository at this point in the history
PR-URL: #43759
Refs: #43728
Reviewed-By: Feng Yu <[email protected]>
  • Loading branch information
aduh95 authored and danielleadams committed Jul 26, 2022
1 parent 9435fbf commit c789c0f
Showing 1 changed file with 35 additions and 2 deletions.
37 changes: 35 additions & 2 deletions doc/contributing/primordials.md
Original file line number Diff line number Diff line change
Expand Up @@ -363,10 +363,33 @@ Object.defineProperty(Object.prototype, Symbol.isConcatSpreadable, {
// 1. Lookup @@iterator property on `array` (user-mutable if user-provided).
// 2. Lookup @@iterator property on %Array.prototype% (user-mutable).
// 3. Lookup `next` property on %ArrayIteratorPrototype% (user-mutable).
PromiseAll(array); // unsafe
PromiseAll([]); // unsafe

PromiseAll(new SafeArrayIterator([])); // safe

const array = [promise];
const set = new SafeSet().add(promise);
// When running one of these functions on a non-empty iterable, it will also:
// 4. Lookup `then` property on `promise` (user-mutable if user-provided).
// 5. Lookup `then` property on `%Promise.prototype%` (user-mutable).
PromiseAll(new SafeArrayIterator(array)); // unsafe

PromiseAll(set); // unsafe

PromiseAll(new SafeArrayIterator(array));
SafePromiseAll(array); // safe

// Some key differences between `SafePromise[...]` and `Promise[...]` methods:

// 1. SafePromiseAll, SafePromiseAllSettled, SafePromiseAny, and SafePromiseRace
// support passing a mapperFunction as second argument.
SafePromiseAll(ArrayPrototypeMap(array, someFunction));
SafePromiseAll(array, someFunction); // Same as the above, but more efficient.

// 2. SafePromiseAll, SafePromiseAllSettled, SafePromiseAny, and SafePromiseRace
// only support arrays, not iterables. Use ArrayFrom to convert an iterable
// to an array.
SafePromiseAll(set); // ignores set content.
SafePromiseAll(ArrayFrom(set)); // safe
```

</details>
Expand Down Expand Up @@ -459,6 +482,7 @@ original methods:
* It expects an array (or array-like object) instead of an iterable.
* It wraps each promise in `SafePromise` objects and wraps the result in a new
`Promise` instance – which may come with a performance penalty.
* It accepts a `mapperFunction` as second argument.
* Because it doesn't look up `then` property, it may not be the right tool to
handle user-provided promises (which may be instances of a subclass of
`Promise`).
Expand Down Expand Up @@ -493,6 +517,15 @@ PromisePrototypeThen(
process.on('exit', () => console.log(thenBlockExecuted)); // true
```

A common pattern is to map on the array of `Promise`s to apply some
transformations, in that case it can be more efficient to pass a second argument
rather than invoking `%Array.prototype.map%`.

```js
SafePromiseAll(ArrayPrototypeMap(array, someFunction));
SafePromiseAll(array, someFunction); // Same as the above, but more efficient.
```

</details>

### (Async) Generator functions
Expand Down

0 comments on commit c789c0f

Please sign in to comment.