From dd559c7f1bb88e703e03b6023722771dc970edc8 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 29 May 2022 09:43:52 +0200
Subject: [PATCH] doc: add note regarding `%Array.prototype.concat%` in
 `primordials.md`

PR-URL: https://github.com/nodejs/node/pull/43166
Reviewed-By: LiviaMedeiros <livia@cirno.name>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
---
 doc/contributing/primordials.md | 55 +++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/doc/contributing/primordials.md b/doc/contributing/primordials.md
index a847852ed7f3e4..9a081418981808 100644
--- a/doc/contributing/primordials.md
+++ b/doc/contributing/primordials.md
@@ -269,6 +269,61 @@ ReflectApply(func, null, array);
 
 <details>
 
+<summary><code>%Array.prototype.concat%</code> looks up
+         <code>@@isConcatSpreadable</code> property of the passed
+         arguments and the <code>this</code> value.</summary>
+
+```js
+{
+  // Unsafe code example:
+  // 1. Lookup @@isConcatSpreadable property on `array` (user-mutable if
+  //    user-provided).
+  // 2. Lookup @@isConcatSpreadable property on `%Array.prototype%
+  //    (user-mutable).
+  // 2. Lookup @@isConcatSpreadable property on `%Object.prototype%
+  //    (user-mutable).
+  const array = [];
+  ArrayPrototypeConcat(array);
+}
+```
+
+```js
+// User-land
+Object.defineProperty(Object.prototype, Symbol.isConcatSpreadable, {
+  get() {
+    this.push(5);
+    return true;
+  },
+});
+
+// Core
+{
+  // Using ArrayPrototypeConcat does not produce the expected result:
+  const a = [1, 2];
+  const b = [3, 4];
+  console.log(ArrayPrototypeConcat(a, b)); // [1, 2, 5, 3, 4, 5]
+}
+{
+  // Concatenating two arrays can be achieved safely, e.g.:
+  const a = [1, 2];
+  const b = [3, 4];
+  // Using %Array.prototype.push% and `SafeArrayIterator` to get the expected
+  // outcome:
+  const concatArray = [];
+  ArrayPrototypePush(concatArray, ...new SafeArrayIterator(a),
+                     ...new SafeArrayIterator(b));
+  console.log(concatArray); // [1, 2, 3, 4]
+
+  // Or using `ArrayPrototypePushApply` if it's OK to mutate the first array:
+  ArrayPrototypePushApply(a, b);
+  console.log(a); // [1, 2, 3, 4]
+}
+```
+
+</details>
+
+<details>
+
 <summary><code>%Object.fromEntries%</code> iterate over an array</summary>
 
 ```js