Repository files navigation

NoteThis proposal is'finished' and has been merged into the ECMAScript spec.PR

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

This proposal is currently atStage 4.

• Candidate spec text

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

• Jordan Harband
• Justin Ridgewell
• Sergey Rubanov

This proposal introduces the following function properties toArray.prototype:

• Array.prototype.toReversed() -> Array
• Array.prototype.toSorted(compareFn) -> Array
• Array.prototype.toSpliced(start, deleteCount, ...items) -> Array
• Array.prototype.with(index, value) -> Array

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

toReversed,toSorted, andwith will also be added to TypedArrays:

• TypedArray.prototype.toReversed() -> TypedArray
• TypedArray.prototype.toSorted(compareFn) -> TypedArray
• TypedArray.prototype.with(index, value) -> TypedArray

These methods will then be available on subclasses ofTypedArray. i.e. the following:

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

constsequence=[1,2,3];sequence.toReversed();// => [3, 2, 1]sequence;// => [1, 2, 3]constoutOfOrder=newUint8Array([3,1,2]);outOfOrder.toSorted();// => Uint8Array [1, 2, 3]outOfOrder;// => Uint8Array [3, 1, 2]constcorrectionNeeded=[1,1,3];correctionNeeded.with(1,2);// => [1, 2, 3]correctionNeeded;// => [1, 1, 3]

TheTuple.prototype introduces these functions as a way to deal with the immutable aspect of the Tuples inRecord & 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.

While this proposal is derived fromRecord & 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 onTuple.prototype.

• Firefox/SpiderMonkey, shipping unflagged sinceFirefox 115

• Safari/JavaScriptCore, shipping unflagged sinceSafari Tech Preview 146

• Chrome/V8, shipping unflagged since Chrome 110

• Ladybird/LibJS, shipping unflagged

• core-js

  • change-array-by-copy

• es-shims:

  • array.prototype.tosorted
  • array.prototype.toreversed
  • array.prototype.tospliced
  • array.prototype.with

• ./polyfill.js (minimalist reference implementation)