This article presents four different techniques to immutably update data structures in JavaScript:

Many of the code snippets are runnable and editable, and you are encouraged to experiment with them.

Functional programming techniques and design patterns are increasingly popular in JavaScript applications. Tools and frameworks such as RxJS, Redux, and React take inspiration from functional reactive programming, for example.

Among the many varied features of FP, the interrelated facets of purity, immutability, and persistent data structures yield benefits such as referential transparency and idempotence. To put it simply, avoiding mutation and side effects makes code easier to reason about and compose.

JavaScript is a multi-paradigm programming language. It allows for functional approaches, but without the convenience or guarantees found in some dedicated functional languages. Accordingly, a JS developer must take special care if they intend to update data without mutation. For example, a Redux reducer "must never mutate its arguments, perform side effects…, [or] call non-pure functions", but Redux itself provides no tools for adhering to those strictures.

This article will not focus on the benefits of immutability, but rather explore how it can be achieved in JS if desired.

Consider a function which increments the .counter property of an object:

Rather than modify the original object, we generate a new object with changed data. Note that an even more naive solution might recursively copy all the data in the original object. This is usually referred to as a deep clone, and doubles the amount of memory in use.

If we never intend to mutate the data in our base object, however, it can be safely shared with the new object, as demonstrated with the .bools property above. This structural sharing means that an immutable update can often re-use existing memory.

Unfortunately, the code above is brittle; it uses hard-coded property names even for data not being updated. The function is neither reusable for other object shapes nor easily maintainable.

Suppose we have some nested data as follows:

Perhaps we might want to give Wally a new pet rabbit of the form { name: 'Ears', type: 'rabbit' }. Give it a try; the dino value is in scope in the following editable code block. Unlike in most real-world applications, we have deeply frozen dino so you will know if you accidentally attempt to mutate it – an error will be thrown.

Did you manage to correctly generate a new dinosaur, without throwing any mutation-related errors? In an actual codebase, what is your confidence that you would have avoided those errors? Keep in mind that frequently, objects like this are not deeply frozen – they will silently accept mutation.

For this challenge, we had you add an object. What about updating a deeply-nested object, or deleting one? Feel free to experiment below, then read on for some review.

JavaScript primitives (undefined, null, boolean, number, string, and symbol values) are immutable by default, so you are already prevented from permanently altering primitive values themselves.

Of course, JavaScript does allow re-assignment of shared variables, which is not the same thing as mutation but which presents many of the same issues.

Try commuting the terms in the above expression to badDbl(x) + badInc(x) and re-running the code. Because of the statefulness inherent in re-binding the shared x variable, we get different results, betraying our expectation of how addition works.

Anything not of the primitive types listed above is considered an object in JS – including arrays and functions. A common beginner misunderstanding with JavaScript is that const declarations will prevent mutation. Not so; const only prevents re-assignment.

JavaScript does have the static method Object.freeze(obj) to prevent re-assigning properties. In strict mode, attempting to set a property on a frozen object throws a helpful error. Sadly, in non-strict mode the attempt is merely rejected silently. (Note that freeze itself mutates the object.)

Beware, however – freeze only prevents re-assigning top-level properties, and does not prevent mutating objects referenced in those properties. For that, you need a non-native "deep freeze" algorithm which recursively freezes objects.

Freezing objects could help reveal and debug errors by failing early (upon mutation attempt) rather than late (when an unanticipated state yields incorrect behavior), at least in strict mode. In practice however, freezing is not very common, perhaps because:

So, what tools does JS provide when hoping to avoid mutation? As primitives are already immutable, and functions are infrequently used as mutable data containers, in practice the question is how to generate new versions of Objects and Arrays. For those, we have several built-in methods.

As of ES2015, the spread ... operator has allowed for expanding iterable values into explicit arguments. When used inside new array or object literals, this permits copying the properties of existing values into the new value:

With objects in particular, this allows for easy updating of a top-level key:

In some environments, object spread syntax may not be supported, but Object.assign (also ES2015) may be available.

Spread makes it convenient to add new values to an array, add new key-value pairs to an object, or modify a key-value pair on an object. However, deletion of a key-value pair is not as straightforward. There are some tricks using destructuring but they are not convenient when working with nested objects.

When it comes to arrays, removing a specific element can be done via either filtering or sliceing:

While updating an array element can be accomplished with slice or map:

These methods work but are somewhat cumbersome and error-prone. And we are only dealing with shallow data; things become more difficult with nesting. Let's return to the original example from this article, adding a rabbit to Denver's friend Wally's list of pets. Here is one possible solution using vanilla JS:

This works, but it has some notable downsides:

Lenses are an approach to interacting with nested data that originate in Haskell, a lazy (and therefore of necessity pure) functional language with Hindley-Milner inferred static typing. In that language, they are remarkably flexible and general tools that work across myriad data types seamlessly.

Lenses and related tools are a deep topic, and in JavaScript we do not have the type restrictions that make lenses especially valuable in Haskell. However, the core idea is simple and useful enough that it makes an appearance in Ramda, a popular functional JS utility library.

Conceptually, a lens is a pair of functions:

In terms of implementation, a lens is actually a single function which performs either of the above duties depending on how it is used. A given lens function is not invoked directly on the source; instead, helper functions like view, set, and over are responsible for correctly wielding the lens.

Because lenses are individual functions, they can be directly composed together to form new lenses (an example of the combinator pattern).

Most commonly with Ramda, one will not write a lens from scratch but use methods like lensIndex and lensProp to generate correct lenses.

The set and over methods generate new data with the desired updates, but like Object/Array spread, the new values also share any non-updated references with the old values.

All of this is well and good, but what about nested data? For that, standard right-to-left function composition can stitch together multiple lenses.

Compared to our Object/Array spread + map technique, the above is far more concise, declarative, easy, and foolproof. But it gets even easier; composing together lenses to focus on a nested property chain is common, so Ramda provides a convenient lensPath function.

You can use this lens with view and over as well, of course – try for yourself. Ultimately, our final solution has been condensed down to two easy-to-read lines – one constructing the lens from a path, another using the lens to immutably set a deeply-nested property in some data.

Lenses, being vanilla composable functions with multiple capabilities (read/update/set), are a highly functional solution with all the attendant tricks that implies: partial application, higher-order usage, first-class portability, dynamic behavior etc. However, while Ramda's lens functions make it easy to view, set, and map nested properties, deleting is a little more indirect; you must map over a parent prop using vanilla JS removal techniques:

The basic instantiation and usage of lenses via a library like Ramda may be simple enough, but users should be aware that lenses and other "optics"* have some advanced uses and important gotchas. For example, lens-like functions which violate the lens laws can result in odd edge cases.

Some developers may prefer a more idiomatic approach to immutable updates in JS which doesn't involve importing a larger suite of tools or learning a new API. Michael Westrate's library Immer is purpose-built for just that.

Immer's clever trick is to change what ordinarily-mutating actions mean – intercepting assignment (=), unsafe methods (push), and other cases – in a form of metaprogramming. Specifically, it uses the Proxy constructor to create a "draft" version of your original object. You can mangle this draft at will, even mutating deeply-nested references directly. Instead of allowing those changes to actually occur, Immer transforms them into an aggregate immutable update on the original object.

Immer's core function, produce, has the following signature:

As the final console.log above shows, Immer is using structural sharing just like our manual spread and Ramda lens solutions. The advantages include:

While Immer is very slick, it is ultimately doing the same Object.assign / spread / map type operations as our previous solutions. So while Immer benefits from structural sharing, some updates on large data may be slow (O(n) to copy an array, for example). Also, by default Immer only works on (certain properties of) plain arrays and objects, not other built-ins such as Map and Set. For other pitfalls, consult the docs.

The three approaches we have examined so far all focus on essentially the same data structures – nested Objects and Arrays. Native methods, lenses, and immer all "play well with others" in the sense that other libraries and codebases will generally provide and expect such data types.

One disadvantage of those structures, however, is that they were not purposefully designed with immutable updates in mind. To add an item to an array, you have to create a copy of the array with all other elements – an O(n) operation. If you fail to take special care, you can call a native method like sort without realizing it mutates the original data structure.

An alternative approach is to switch to a purely functional data structure (PDF link), or at least a data structure with efficient immutable update operations. Such data structures would expose an API of only pure operations, reducing the chance of error.

Facebook's library Immutable takes advantage of such structures. While they are implemented in vanilla JavaScript, the details are hidden from the user, who now interacts with classes such as List and Map (distinct from the ES2015 class of the same name). For large amounts of data, these entities are now much quicker to modify; for example, Map's set and get functions have O(log32 n) time complexity, and List's push and pop methods are O(1) despite returning a new updated list.

Immutable is a large library with multiple classes, each of which has many methods. We will demonstrate just a small corner of that library, beginning with converting some typical JS data to a nested series of Maps and Lists.

Some advantages are not directly demonstrated, but worth pointing out:

At the end, if some other library or framework requires a plain JS object or array, we can use .toJS() to convert it back.

Performance and safety are the primary reasons to favor using immutable, but as always there are tradeoffs to consider.

Each of the approaches examined has pros and cons, as is often the case in programming. Thankfully, they are not mutually exclusive. For example, Brian Lonsdorf demonstrates using Ramda lenses to blend native objects/arrays with Immutable.js maps/lists in his article Lenses with Immutable.js. Similarly, one might use array spread inside a function passed to Ramda over, or inside a call to Immer's produce function. Knowing multiple approaches allows you to reach for the abstraction that fits your use case.

Prof. Dierk König brings up another technique for immutable data: store your data as functions.

The Vireo combinator (as it is named in Raymond Smullyan's famous book, To Mock a Mockingbird) is defined in JavaScript as follows:

When vireo is applied twice (to two separate pieces of data), it returns a final function which has closed over both data points. The result is conceptually a pair of numbers, stored as a function closure. To access to the stored numbers, a final function argument is provided:

Note that with this example, there is no way to actually modify the values once the pair is generated – the closure acts as a form of privileged data. How can we "update" such a pair? We make a new function which defers to old function:

To make this easier, we could write helper functions for getting, setting, and mapping…

Storing data through closures, and creating new functions which defer to old functions, can scale up to more complex data and also be made more idiomatic in JS; this is a large enough topic for its own article, however. If this approach intrigues you, Sandy Maquire's Thinking with Types illustrates a clever method (in Haskell) of encoding Tic-Tac-Toe boards as functions from coordinates to data. Experiment with a JS version below!