Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Array.prototype.toSpliced: a changed copy without mutation

toSpliced returns a new array after removing and inserting selected positions while leaving the receiver unchanged.

Version: ECMAScript 2023; example target: Node.js 24.22.2

Syntax

array.toSpliced(start, skipCount?, ...items)

array.toSpliced(start, skipCount?, ...items) is the copying counterpart of splice(): it creates a new ordinary Array, skips a selected range, inserts items, and leaves array unchanged. A negative start counts from the end; a position beyond the length means the end. With start present, omitted skipCount removes the tail, explicit undefined means zero, and other values are clamped to the available range.

The result is the entire changed copy, not an array of removed elements. It is shallow, always dense, and does not consult Symbol.species: receiver holes become own properties whose value is undefined. A call with no arguments returns a dense copy.

The method was standardized in ECMAScript 2023 and is generic for array-like values. A null or undefined receiver throws TypeError; an excessive computed length produces TypeError or RangeError, while conversion, getter, and proxy trap failures propagate.

Examples

const source = ["build", "test", "deploy"];
const changed = source.toSpliced(1, 1, "lint", "test");
console.log(changed.join(","));
console.log(source.join(","));
console.log(source.toSpliced(-1).join(","));
console.log(source.toSpliced(1, undefined, "docs").join(","));

const dense = [1, , 3].toSpliced(1, 0, 2);
console.log(dense.length, 0 in dense, 1 in dense, 2 in dense, 3 in dense);
console.log(dense[0], dense[1], String(dense[2]), dense[3]);

Result

build,lint,test,deploy
build,test,deploy
build,test
build,docs,test,deploy
4 true true true true
1 2 undefined 3

Sources