Change Array by copy

Provides additional methods to Array.prototype to enable changes on an array by returning a new copy of it with the change.

Status

This proposal is currently at Stage 1.

• Candidate spec text
• Candidate polyfill

Champions

• Robin Ricard (Bloomberg)
• Ashley Claymore (Bloomberg)

Overview

This proposal introduces the following function properties to Array.prototype:

• Array.prototype.withFilled(value, start, end) -> Array
• Array.prototype.withCopiedWithin(copiedTarget, start, end) -> Array
• Array.prototype.withPopped() -> Array
• Array.prototype.withPushed(values...) -> Array
• Array.prototype.withReversed() -> Array
• Array.prototype.withShifted() -> Array
• Array.prototype.withSorted(compareFn) -> Array
• Array.prototype.withSpliced(start, deleteCount, ...items) -> Array
• Array.prototype.withUnshifted(...values) -> Array
• Array.prototype.withAt(index, value) -> Array

All of those methods keep the target Array untouched and returns a copy of it with the change performed instead.

They will also be added to TypedArrays:

• TypedArray.prototype.withFilled(value, start, end) -> TypedArray
• TypedArray.prototype.withCopiedWithin(copiedTarget, start, end) -> TypedArray
• TypedArray.prototype.withPopped() -> TypedArray
• TypedArray.prototype.withPushed(values...) -> TypedArray
• TypedArray.prototype.withReversed() -> TypedArray
• TypedArray.prototype.withShifted() -> TypedArray
• TypedArray.prototype.withSorted(compareFn) -> TypedArray
• TypedArray.prototype.withSpliced(start, deleteCount, ...items) -> TypedArray
• TypedArray.prototype.withUnshifted(...values) -> TypedArray
• TypedArray.prototype.withAt(index, value) -> TypedArray

These methods will then be avaliable on subclasses of TypedArray. i.e. the following:

• Int8Array
• Uint8Array
• Uint8ClampedArray
• Int16Array
• Uint16Array
• Int32Array
• Uint32Array
• Float32Array
• Float64Array
• BigInt64Array
• BigUint64Array

Example

const sequence = [1, 2, 3];
sequence.withReversed(); // => [3, 2, 1]
sequence; // => [1, 2, 3]

const outOfOrder = new Uint8Array([3, 1, 2]);
outOfOrder.withSorted(); // => Uint8Array [1, 2, 3]
outOfOrder; // => Uint8Array [3, 1, 2]

const correctionNeeded = [1, 1, 3];
correctionNeeded.withAt(1, 2); // => [1, 2, 3]
correctionNeeded; // => [1, 1, 3]

Motivation

The Tuple.prototype introduces those functions as a way to deal with the immutable aspect of the Tuples in Record & Tuple. While Arrays are not immutable by nature, this style of programming can be beneficial to users dealing with frozen arrays for instance.

This proposal notably makes it easier to write code able to deal with Arrays and Tuples interchangeably.

Relationship with Record & Tuple

While this proposal is derived from Record & Tuple, it should progress independently.

If web compatibility prescribes it, property names defined in this proposal are going to be changed. Those changes should be reflected on Tuple.prototype.