Everything about the new array methods in JavaScript

Once again we’re going to talk about the main news in JavaScript! This time we’re going to talk about one of the coolest proposals around right now. Today it’s at stage 3, which means it’s going to be live soon!

If you don’t know how JavaScript works, in this video I explain a bit more about the process of releasing new JavaScript features, if you haven’t watched it yet, I strongly recommend it so you can better understand how everything works!

The problem#

As a lot of people have already found out the hard way, arrays and objects in JavaScript are passed by reference because they’re created and stored in the Heap (which I’m not going to explain here but this article gives you a good idea). Because of that, they’re created only once and passed to functions as a pointer to the original object.

So when we do some operation on them, for example, reversing an array with reverse(), we’ll always change the original array:

1
const arr = [1,2,3]
2
arr.reverse()
3
console.log(arr) // [3,2,1]

And this is the cause of many, many problems in most systems. Over time, we learned to use the object cloning method to create a copy of that array and make the change, for example:

1
const arr = [1,2,3]
2
const reversed = [...arr].reverse()
3
console.log(arr) // [1,2,3]
4
console.log(reversed) // [3,2,1]

When we use the spread operator [... what we’re doing is cloning the array element by element and applying the reverse method to this new array we got back.

And this is true for several other methods like splice and sort. Why don’t we change that?

The proposal#

The idea of this proposal is to add another 4 new methods for arrays:

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

These functions don’t need much explaining, but I’ll give you a basic idea about them so you understand what’s going on. The important part here is that all the functions are non destructive, meaning they don’t touch the original object, all of them return a new array with the modifications.

toReversed#

Does the same thing as our second example, meaning it reverses an array and gives back the reversed copy of that array, without modifying the original.

1
let x = [ 1, 2, 3 ];
2
let y = x.toReversed();
3

4
// [ 1, 2, 3 ], [ 3, 2, 1 ]
5
console.log(x, y);

toSorted#

Same as the previous one and its sort counterpart, this function sorts an array following a sorting function without modifying the original array, by default, the sorting function takes the array and sorts it numerically like this:

1
let x = [ 5, 3, 4, 2, 1 ];
2
let y = x.toSorted(); // [ 1, 2, 3, 4, 5 ]

But, just like sort it accepts a sorting function that follows a (a, b) => number signature where if:

• The return is >0, a comes after b
• The return is <0, a comes before b
• The return is 0, no change is made¹

1
let x = [
2
    { value: 0 },
3
    { value: 4 },
4
    { value: 2 },
5
    { value: 3 }
6
];
7

8
// y vai ser:
9
// [
10
//    { value: 0 },
11
//    { value: 2 },
12
//    { value: 3 },
13
//    { value: 4 }
14
// ]
15
let y = x.toSorted((a, b) => {
16
    return a.value - b.value
17
});

toSpliced#

The splice method is not the same as the slice method, while slice returns a subset of the original array in a new array, splice changes the array content in three ways:

• Adding items anywhere in the array
• Removing items anywhere in the array
• Replacing one item with another item anywhere in the array

The problem is that it also did that on the array it received, whereas this version returns a new copy.

The function keeps the same signature, only with the new return: (start, deleteCount, ...items) => Array, where:

• start is the position to start counting from, or where the pointer will begin
• deleteCount is the amount of items to remove starting at start
• ...items is an optional parameter that, if passed, tells the new value of position start after removing all the items in deleteCount²

1
let x = [ "Cachorro", "Gato", "Zebra", "Morcego", "Tigre", "Leão" ];
2

3
// y é [ "Cachorro", "Cobra", "Morcego", "Tigre", "Leão" ]
4
let y = x.toSpliced(1, 2, "Cobra");
5

6
// z é [ "Cachorro, "Tigre", "Leão" ]
7
let z = x.toSpliced(1, 3);

This example also shows really well why these functions are good. If we modified the array in the original array itself, we’d have to recreate x every single time

with#

This is a new function that simplifies the use of splice a bit when we only have to modify one element of the array, originally if we wanted to modify this array:

1
let x = [ "Cachorro", "Gato", "Zebra", "Morcego", "Tigre", "Leão" ];

To show “Cobra” instead of “Gato”, we’d have to do this with splice:

1
let y = x.toSpliced(1, 1, "Cobra");

With with we can do this:

1
// [ 'Cachorro', 'Cobra', 'Zebra', 'Morcego', 'Tigre', 'Leão' ]
2
x.with(1, "Cobra")

Essentially we’re saying: “Take array X, at position 1 and show it with this other value”.

Support#

Support isn’t implemented in all browsers yet, but you can use the polyfills available at TC39 to implement this functionality. If you’re using Node, you can use core-js to test it, your code would look something like this:

1
require('core-js/proposals/change-array-by-copy')
2

3
const sequencia = [1, 2, 3]
4
console.log(sequencia.toReversed()) // => [3, 2, 1]
5
console.log(sequencia) // => [1, 2, 3]
6

7
const desordenado = new Uint8Array([3, 1, 2])
8
console.log(desordenado.toSorted()) // => Uint8Array [1, 2, 3]
9
console.log(desordenado) // => Uint8Array [3, 1, 2]
10

11
const precisaDeCorrecao = [1, 1, 3]
12
console.log(precisaDeCorrecao.with(1, 2)) // => [1, 2, 3]
13
console.log(precisaDeCorrecao) // => [1, 1, 3]
14

15
const spliced = [1, 2, 3]
16
console.log(spliced.toSpliced(1, 1)) // => [1, 3]
17
console.log(spliced) // => [1, 2, 3]
18

19
let x = [ "Cachorro", "Gato", "Zebra", "Morcego", "Tigre", "Leão" ];
20
console.log(x.toSpliced(1,1,"Cobra"))
21
console.log(x.with(1, "Cobra"))

This functionality is expected to be released in the next version of ECMAScript, along with several super cool features I already talked about here.