Array.prototype.with() とは
`Array.prototype.with()` は、非破壊的に配列の要素を置き換えるためのメソッドです。非破壊的とは、元の配列を変更せずに新しい配列を返すということです。`arr` に対して `with()` を実行しても、`arr` は変更されず、新しい配列のコピーが返されます。
Array.prototype.with() は、非破壊的に配列の要素を置き換えるためのメソッドです。非破壊的とは、元の配列を変更せずに新しい配列を返すということです。下記の例のように、arr に対して with() を実行しても、arr は変更されず、新しい配列のコピーが返されます。
const arr = [1, 2, 3]
// index が 1 の要素を 4 に置き換える
const newArr = arr.with(1, 4)
console.log(arr) // [1, 2, 3]
console.log(newArr) // [1, 4, 3]Array.prototype.with() は Change Array by copy と呼ばれるプロポーサルで提案されたメソッドに 1 つです。Change Array by copy は配列のメソッドに非破壊のメソッドを追加するものです。他にも Array.prototype.srot() の非破壊版である Array.prototype.toSorted() などが提案されています。
このプロポーサルは ECMAScript 2023 に取り込まれています。既に Node.js 20.0.0 で実装されていて使用できます。最新の実装状況は Can I use で確認できます。
使い方
Array.prototype.with() は、第 1 引数に置き換える要素のインデックス、第 2 引数に置き換える値を受け取ります。
arr.with(index, value)概要でも説明したとおり、with() は非破壊的なメソッドであり、元の配列を変更せずに新しい配列を返します。次のようにメソッドチェインのような使い方もできます。
const arr1 = ['a', 'b', 'c']
const arr2 = arr.with(0, 'A').with(1, 'B').with(2, 'C')
console.log(arr1) // ['a', 'b', 'c']
console.log(arr2) // ['A', 'B', 'C']相対的なインデックス
Array.prototype.with() は、Arrya.prototype.at() のように第 1 引数に相対的なインデックスを指定することもできます。相対的なインデックスとは、配列の末尾からのインデックスのことです。例えば、-1 は配列の末尾の要素を指します。
const arr = ['apple', 'banana', 'orange']
const newArr = arr.with(-1, 'grape')
console.log(arr) // ['apple', 'banana', 'orange']
console.log(newArr) // ['apple', 'banana', 'grape']例外
第 1 引数の配列のインデックスが範囲外の場合、RangeError が発生します。
const arr = [1, 2, 3]
arr.with(3, 3)
// Uncaught RangeError: Invalid index : 3TypedArray
Array.prototype.with() TypedArray のサブクラスでも使用できます。
const arr = new Uint8Array([1, 2, 3])
const newArr = arr.with(1, 4)
console.log(arr) // Uint8Array(3) [1, 2, 3]
console.log(newArr) // Uint8Array(3) [1, 4, 3]
