Skip to content

doc: improve documentation for safe Promise statics alternatives #43759

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nodejs-github-bot merged 3 commits into from
Jul 25, 2022
Merged

doc: improve documentation for safe Promise statics alternatives #43759

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2285f54
doc: improve documentation for safe `Promise` statics alternatives
aduh95 Jul 10, 2022
940d7e2
fixup! doc: improve documentation for safe `Promise` statics alternat…
aduh95 Jul 10, 2022
8ecae32
fixup! doc: improve documentation for safe `Promise` statics alternat…
aduh95 Jul 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion doc/contributing/primordials.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,13 +360,33 @@ Object.defineProperty(Object.prototype, Symbol.isConcatSpreadable, {
<code>%Promise.race%</code> iterate over an array</summary>

```js
const array = [promise];
const set = new SafeSet().add(promise);

// 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).
// 4. Lookup `then` property on `promise` (user-mutable if user-provided).
// 5. Lookup `then` property on `%Promise.prototype%` (user-mutable).
PromiseAll(array); // unsafe

PromiseAll(new SafeArrayIterator(array));
PromiseAll(new SafeArrayIterator(array)); // unsafe
Comment thread
aduh95 marked this conversation as resolved.
PromiseAll(set); // unsafe

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 +479,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 +514,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