JavaScript splice Returns an Empty Array: Get the Edited Result

Separate the removed elements from the edited array#

MDN’s splice reference defines the return value as the deleted elements. That makes return array.splice(index, 0, item) the wrong return expression for an insertion helper that promises the completed array.

For a helper intended to mutate its input, use two statements: array.splice(index, 0, item); return array;. All existing references to that array observe the edit. Changing the return statement does not undo the mutation.

For a helper intended to leave its input intact, return array.toSpliced(index, 0, item). The toSpliced reference describes its return as the new edited array. Check that the target runtime supports this method. The fixture also checks a copy-first alternative: const copy = array.slice();, splice the copy, then return the copy.

Verify both sides of each call#

Save the following as splice-check.mjs and run node splice-check.mjs. These assertions were executed during article preparation on October 26, 2026, with Node.js 24.13.0 on macOS. They use ordinary dense arrays and require no packages.

1
import assert from 'node:assert/strict';
2

3
const rows = [
4
  ['insert', [1, 0, 'X'], [], ['A', 'X', 'B', 'C']],
5
  ['replace', [1, 1, 'X'], ['B'], ['A', 'X', 'C']],
6
  ['omitted count', [1], ['B', 'C'], ['A']],
7
  ['undefined count', [1, undefined, 'X'], [], ['A', 'X', 'B', 'C']],
8
  ['replace tail', [1, Infinity, 'X'], ['B', 'C'], ['A', 'X']],
9
  ['past end', [99, 1], [], ['A', 'B', 'C']],
10
  ['no arguments', [], [], ['A', 'B', 'C']],
11
  ['undefined start', [undefined], ['A', 'B', 'C'], []],
12
];
13
for (const [label, args, expectedRemoved, expectedAfter] of rows) {
14
  const array = ['A', 'B', 'C'];
15
  const alias = array;
16
  const removed = array.splice(...args);
17
  assert.deepEqual(removed, expectedRemoved);
18
  assert.deepEqual(array, expectedAfter);
19
  assert.equal(alias, array);
20
  assert.notEqual(removed, array);
21
  console.log(`${label}: removed=${JSON.stringify(removed)} after=${JSON.stringify(array)}`);
22
}
23

24
const original = ['A', 'B', 'C'];
25
const next = original.toSpliced(1, 0, 'X');
26
assert.deepEqual(original, ['A', 'B', 'C']);
27
assert.deepEqual(next, ['A', 'X', 'B', 'C']);
28
assert.notEqual(next, original);
29
const copy = original.slice();
30
assert.deepEqual(copy.splice(1, 0, 'X'), []);
31
assert.deepEqual(copy, next);
32
assert.deepEqual(original, ['A', 'B', 'C']);
33
console.log('copy paths: original unchanged; edited arrays match');
34

35
const record = { done: false };
36
const records = [record];
37
const edited = records.toSpliced(1, 0, { done: true });
38
assert.equal(edited[0], records[0]);
39
edited[0].done = true;
40
assert.equal(records[0].done, true);
41
console.log('shallow copy: retained object reference is shared');

Expected output:

1
insert: removed=[] after=["A","X","B","C"]
2
replace: removed=["B"] after=["A","X","C"]
3
omitted count: removed=["B","C"] after=["A"]
4
undefined count: removed=[] after=["A","X","B","C"]
5
replace tail: removed=["B","C"] after=["A","X"]
6
past end: removed=[] after=["A","B","C"]
7
no arguments: removed=[] after=["A","B","C"]
8
undefined start: removed=["A","B","C"] after=[]
9
copy paths: original unchanged; edited arrays match
10
shallow copy: retained object reference is shared

The insertion and past-end rows both return [], but only the insertion row changes the elements. The replacement row returns ['B'], while the edited array contains 'X' at that position. Each iteration asserts that the returned array is a different object from the array being edited.

The alias assertion verifies that splice() keeps the original array identity. It does not produce a replacement array for references elsewhere in the program. If a caller needs to retain the old contents, copy before mutating.

Preserve argument presence when wrapping splice#

The ECMAScript splice algorithm distinguishes a missing argument from an argument whose value is undefined. The fixture makes that boundary visible:

• splice(1) removes the remaining tail.
• splice(1, undefined, 'X') inserts without removing the tail.
• splice(1, Infinity, 'X') replaces the remaining tail with 'X'.
• splice() removes nothing, while splice(undefined) removes everything in this input.

This matters in a wrapper that always forwards a second argument. Calling a wrapper with only start does not preserve native one-argument behavior if the wrapper calls array.splice(start, count) with an undefined count. Either require an explicit count in the wrapper’s API or forward the original argument list when native omission semantics are intended. The fixture uses argument arrays and spread specifically to preserve that difference.

For insertion-only code, pass 0 explicitly. It communicates the intended removal count and avoids relying on a missing parameter to mean something it does not.

A new array can still share its objects#

The final assertion changes edited[0].done and observes the change through records[0]. The outer arrays differ, but the retained record is the same object. Choosing toSpliced() solves the outer-array mutation problem; it does not promise independent nested data. The separate nested object copying guide explains why copying a container does not recursively copy its contents.

These examples do not test browser engines, framework state updates, sparse arrays, subclasses, getters, or proxies. In particular, the copy-first path is checked for dense arrays here; it is not presented as a complete polyfill for toSpliced().

Choose what the caller should receive before changing the code: removed elements, the same edited array, or a new edited array. Then assert both the returned value and the original contents so an empty removal list cannot hide a successful insertion.

References:

• MDN: Array.prototype.splice
• MDN: Array.prototype.toSpliced
• ECMAScript: Array.prototype.splice