Array.prototype.toSpliced()

Introduction to ECMAScript 14 Array.prototype.toSpliced()

Array.prototype.toSpliced() is a new array method introduced in ECMAScript 14, providing an immutable way to perform splice operations on arrays. Unlike the traditional splice() method, toSpliced() does not modify the original array but instead returns a new array, making it particularly useful in functional programming and immutable data scenarios.

Syntax and Parameters

The syntax for the toSpliced() method is as follows:

array.toSpliced(start, deleteCount, item1, item2, ..., itemN)

Parameter descriptions:

• start: Specifies the starting position for modification (0-based index)
• deleteCount (optional): The number of elements to remove
• item1, item2, ..., itemN (optional): Elements to add to the array

Differences from splice()

The traditional splice() method modifies the original array directly, while toSpliced() leaves the original array unchanged:

const arr = [1, 2, 3, 4, 5];

// Using splice() - modifies the original array
const spliced = arr.splice(1, 2, 'a', 'b');
console.log(arr); // [1, 'a', 'b', 4, 5]
console.log(spliced); // [2, 3]

// Using toSpliced() - does not modify the original array
const newArr = arr.toSpliced(1, 2, 'a', 'b');
console.log(arr); // [1, 2, 3, 4, 5] (remains unchanged)
console.log(newArr); // [1, 'a', 'b', 4, 5]

Use Cases

1. Immutable Data Operations

toSpliced() is highly useful in scenarios requiring immutable data, such as React or Redux:

function reducer(state, action) {
  switch (action.type) {
    case 'UPDATE_ITEM':
      return {
        ...state,
        items: state.items.toSpliced(action.index, 1, action.newItem)
      };
    default:
      return state;
  }
}

2. Partial Array Replacement

Easily replace a portion of an array:

const colors = ['red', 'green', 'blue', 'yellow'];
const newColors = colors.toSpliced(1, 2, 'purple', 'orange');
// ['red', 'purple', 'orange', 'yellow']

3. Removing Elements

Remove elements without adding any:

const numbers = [1, 2, 3, 4, 5];
const withoutMiddle = numbers.toSpliced(1, 3);
// [1, 5]

4. Inserting Elements

Add elements without removing any (set deleteCount to 0):

const letters = ['a', 'b', 'c'];
const extended = letters.toSpliced(1, 0, 'x', 'y');
// ['a', 'x', 'y', 'b', 'c']

Edge Case Handling

1. Negative Indices

Supports negative indices, counting from the end of the array:

const arr = [1, 2, 3, 4, 5];
const result = arr.toSpliced(-2, 1, 'a');
// [1, 2, 3, 'a', 5]

2. Start Index Exceeding Array Length

When start exceeds the array length, the operation starts from the end:

const arr = [1, 2, 3];
const result = arr.toSpliced(10, 1, 'a');
// [1, 2, 3, 'a']

3. deleteCount Exceeding Range

If deleteCount is greater than the number of elements from start, all remaining elements are removed:

const arr = [1, 2, 3, 4, 5];
const result = arr.toSpliced(2, 10, 'a', 'b');
// [1, 2, 'a', 'b']

Performance Considerations

While toSpliced() offers the convenience of immutable operations, it requires creating a new array, which may incur performance overhead when dealing with large arrays. For performance-sensitive scenarios, other optimization approaches may be necessary.

Integration with Other New Methods

toSpliced() can be used alongside other ECMAScript immutable array methods:

const products = [
  { id: 1, name: 'Laptop', price: 999 },
  { id: 2, name: 'Phone', price: 699 },
  { id: 3, name: 'Tablet', price: 399 }
];

// Update the second product and sort
const updated = products
  .toSpliced(1, 1, { id: 2, name: 'Smartphone', price: 799 })
  .toSorted((a, b) => a.price - b.price);

Browser Compatibility

As a new feature in ECMAScript 14, polyfills or transpilation may currently be required for older browsers. The following polyfill can be used:

if (!Array.prototype.toSpliced) {
  Array.prototype.toSpliced = function(start, deleteCount, ...items) {
    const copy = [...this];
    copy.splice(start, deleteCount, ...items);
    return copy;
  };
}

Practical Examples

1. Shopping Cart Operations

class ShoppingCart {
  constructor(items = []) {
    this.items = items;
  }

  addItem(index, item) {
    return new ShoppingCart(this.items.toSpliced(index, 0, item));
  }

  removeItem(index) {
    return new ShoppingCart(this.items.toSpliced(index, 1));
  }

  updateItem(index, newItem) {
    return new ShoppingCart(this.items.toSpliced(index, 1, newItem));
  }
}

2. Table Data Editing

function updateTableRow(rows, rowIndex, newData) {
  return rows.toSpliced(rowIndex, 1, {
    ...rows[rowIndex],
    ...newData
  });
}

3. History Management

class History {
  constructor(records = []) {
    this.records = records;
  }

  addRecord(record) {
    return new History(this.records.toSpliced(this.records.length, 0, record));
  }

  undo() {
    return new History(this.records.toSpliced(-1, 1));
  }
}

Comparison with Spread Operator

While similar effects can be achieved using the spread operator, toSpliced() offers clearer semantics:

// Using spread operator
const arr = [1, 2, 3, 4, 5];
const newArr = [...arr.slice(0, 1), 'a', 'b', ...arr.slice(3)];

// Using toSpliced()
const newArr = arr.toSpliced(1, 2, 'a', 'b');

Type System Support

In TypeScript, toSpliced() maintains correct type inference:

const numbers: number[] = [1, 2, 3, 4];
const mixed = numbers.toSpliced(1, 2, 'a', 'b');
// Type is (number | string)[]