From 2285f54df1b7cd4e44c6f428f41db0848e7fe30c Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 10 Jul 2022 16:22:44 +0200
Subject: [PATCH 1/3] doc: improve documentation for safe `Promise` statics
alternatives
---
doc/contributing/primordials.md | 32 +++++++++++++++++++++++++++++++-
1 file changed, 31 insertions(+), 1 deletion(-)
diff --git a/doc/contributing/primordials.md b/doc/contributing/primordials.md
index e93d224495a53f..964ca518350c73 100644
--- a/doc/contributing/primordials.md
+++ b/doc/contributing/primordials.md
@@ -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).
+// 3. Lookup `then` property on `promise` (user-mutable if user-provided).
+// 3. Lookup `then` property on `%Promise.prototype%` (user-mutable).
PromiseAll(array); // unsafe
-PromiseAll(new SafeArrayIterator(array));
+PromiseAll(new SafeArrayIterator(array)); // unsafe
+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>
@@ -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`).
@@ -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
From 940d7e296dead9488101c35e00de05e85fcefe61 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 10 Jul 2022 17:04:09 +0200
Subject: [PATCH 2/3] fixup! doc: improve documentation for safe `Promise`
statics alternatives
Co-authored-by: Feng Yu <F3n67u@outlook.com>
---
doc/contributing/primordials.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/contributing/primordials.md b/doc/contributing/primordials.md
index 964ca518350c73..17f88225081613 100644
--- a/doc/contributing/primordials.md
+++ b/doc/contributing/primordials.md
@@ -366,8 +366,8 @@ 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).
-// 3. Lookup `then` property on `promise` (user-mutable if user-provided).
-// 3. Lookup `then` property on `%Promise.prototype%` (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)); // unsafe
From 8ecae32d90cc61de7b86acdc6a50b6d2a53170d1 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 10 Jul 2022 17:35:05 +0200
Subject: [PATCH 3/3] fixup! doc: improve documentation for safe `Promise`
statics alternatives
---
doc/contributing/primordials.md | 13 ++++++++-----
1 file changed, 8 insertions(+), 5 deletions(-)
diff --git a/doc/contributing/primordials.md b/doc/contributing/primordials.md
index 17f88225081613..7980bd79b3b272 100644
--- a/doc/contributing/primordials.md
+++ b/doc/contributing/primordials.md
@@ -360,17 +360,20 @@ 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).
+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(array); // unsafe
-
PromiseAll(new SafeArrayIterator(array)); // unsafe
+
PromiseAll(set); // unsafe
SafePromiseAll(array); // safe