When you mutate data, you change it. If data is immutable, you can't change it.

Immutability is native to some programming languages. But why is changing data bad, and how does one write software with data that never changes?

When you first learned how to program, one of the earliest concepts that you were taught was the variable. A variable is something that's used to store a value, so of course it's important! When you create a variable and assign its initial value, it feels like you're creating new data. This is because you are creating new data.

Then, later on in your code, you assign a new value to your variable. It's a variable, so naturally it varies. This might also seem like you're creating new data, which you are; if you assign the value 5 to your variable, then that's a new value that didn't exist before. Here's the catch: you're also destroying data. What if your variable had a value of 2 before you assigned it 5?

This might not seem like a big deal. Isn't a variable supposed to store whatever value you assign to it? Yes, variables work perfectly fine that way. They do exactly what we ask them to do. So, the problem isn't strictly that variables can change their values. Rather, it's a human limitation—we can't reason our way through the huge number of variable changes that happen in our code. This leads to some scary bugs.

Imagine that you're trying to bake a loaf of bread. Nothing fancy, just a plain loaf. You don't even need to look at the recipe—it's just a handful of ingredients, and you've memorized the steps. Now suppose that one or two of your ingredients have been changed without your knowledge. You still follow the steps, and the end result still looks like bread, but then your family eats it. One family member says something tastes off, another doesn't seem to notice anything, while yet another heads straight for the washroom.

These are just some of many possible scenarios that could have played out, and the problems all stemmed from the ingredients used. In other words, because the ingredients were allowed to change, they did change. Consider the game Telephone. In this game, there is a line of people and a message is whispered to the first person in the line. The same message is whispered (allegedly) to the next person, and so on, until the message reaches the last person who then says the message out loud. The ending message is almost never the same as the starting message. Once again, the message changes because it's allowed to change.

When writing software, you're no different from the person making bread using incorrect ingredients or the Telephone game player relaying an incorrect message. The end result is a scary type of bug. If you mess up your bread, can you pinpoint exactly what went wrong? Can you identify the Telephone game players who broke the message? Your variables change because they can. You've written code to make the variables change, and sometimes everything works exactly as you want it to. But when something goes wrong, it's very difficult to figure out what went wrong.

If data isn't supposed to change, just how are we supposed to get anything done? How do we move the state of an application along from one state to the next if our data is immutable? The answer is that every operation that you perform on immutable data creates new immutable data. These are called persistent changes, because the original data is persisted. The new data that's created as a result of running the operation contains the changes. When we call an operation on this new data, it returns new data, and so on.

What are we supposed to do with the old data when we make a persistent change that results in new data? The answer is – it depends. Sometimes, you'll just replace the old data with the new data. Yes, the variable is changed, but it's replaced with an entirely new reference. This means that something that is still referencing the old data is never affected by your persistent changes.

Different JavaScript libraries each have their own approach to deal with certain things. For example, React relies on JSX—an XML dialect embedded in JavaScript for declaring user interface components. Lodash exposes lots of little functions, some of which can be chained together to simplify complex code. The idea behind Immutable.js is to expose a small number of collection classes as its API. How does it work?

A collection in JavaScript refers to anything that can be iterated over, for example, when using a for..of loop. In practice, this means arrays and objects. Arrays and objects are collections of values; the only difference between them is how you look up values. An array is an indexed collection, because you use a numerical index to lookup a value. An object is a keyed collection, because you use a key string to lookup a value.

The issue with these primitive JavaScript collection types is that they can change; that is, they're not immutable. The collections exposed by Immutable.js feel a lot like native arrays and objects. In fact, you can take an array or an object and use it to construct an Immutable.js collection. You can also turn an Immutable.js collection into a JavaScript array or object.

This is the extent of the Immutable.js API. You use collection classes to hold your immutable data. To use this immutable data, you call methods on these collections, which is at the very heart of the Immutable.js API.

Let's say that you have an Immutable.js collection: coll1. Then, you call a method to insert a new value into the collection: push('newValue'). This is what a persistent change looks like: coll1 persists and push() returns a new collection that includes the new value.

Not all collection methods are mutative. For example, if you want to filter a collection so that only items that pass a given criteria are returned, you would call the filter() method. This would result in a new collection, just like adding a new item would result in a new collection. The difference is that filter() isn't a persistent change—it's part of a sequence transformation.

Think of a sequence transformation as an Instagram filter. You have the original collection: the picture. Then, you have a filter() transformation, which takes the original picture data and rearranges some of the pixel data. You want to be able to see the results of the filter, but you don't want to change the original. The filter is just a view of the original.

Immutable data doesn't just sit inside of a constant. Somehow, your applications need to make use of this data. These are called side-effects. A side-effect is something that is effected by immutable data, such as rendering data on the screen in a user interface or writing data to a file. By contrast, operations performed on immutable collections are either persistent changes or sequence transformations, both of which result in new collections. These operations don't have any side-effects; they just result in new data being created. Another term used for functions that don't cause side-effects is pure functions.

With Immutable.js, you start with a collection of immutable data and work your way toward some sort of side-effect. In functional programming, it's generally best to avoid side-effects due to the problems they cause. But side-effects are unavoidable. Without them, your software cannot interact with its environment. By chaining together Immutable.js collection methods, you can write clean and concise code that transforms immutable data into something that you need—something that a side-effect can use.

React and Flux have popularized the concept of unidirectional data flow as the fundamental concept that drives web application architecture. A unidirectional data flow is exactly what it sounds like—data that flows in one direction. It's a simple idea, but it's an important mindset to adopt when thinking about immutable data.

The best way to visualize unidirectional data flow is in a top-down fashion. Data starts in one state at the top, changes state as it flows downward, ending with a side-effect that does something with the data. When this is enforced as a property of the architecture, side-effects are predictable. We can easily trace the starting point of data, through the transformations it makes, ending with the visible side-effect.

When we don't enforce a unidirectional data flow, it's difficult to trace cause and effect. This is the main reason that Facebook started promoting the concept with the creation of Flux—to prevent components from changing state at will and passing the changed state on to another component. For example, let's say that you aren't using immutable data, and that one component changes its state in response to an event. Then some other component that references this state renders itself, causing its state to change as a result of the first change. These are nothing more than uncontrolled side-effects.

Immutable.js is a low-level library compared to the ideas of Flux or a UI component library such as React. Even if you're not using either of these, you can still leverage Immutable.js to build a unidirectional architecture.

One approach to handling data that changes is to observe it. This means using some mechanism to attach a listener callback function that's called whenever the data changes. For example, you could have data that models a user interface component, and when that data changes, you would render the component so that it reflects the changed data.

To set up subscriptions like this will require data that can change, which we don't want. Since we're working with immutable data that never changes, subscriptions are a dead end. This means that you have to rethink your approach for notifying components about the state of your data. The rule of thumb with immutable architectures is that only new data is passed around when things change.

Let's revisit the visualization of data flowing from top to bottom, ending with a side-effect. Along the way, we're either changing the state of data with persistent changes, or we're shaping the data that we need using sequence transformations. From the beginning to the end of this flow, we're only creating new data.

The chained Immutable.js collection method calls result in new data—every time. This means that if we make a mistake and accidentally try to use data in a way that falls outside of the unidirectional flow that we're following, Immutable.js will protect us from ourselves. When this happens, the result is often a broken application that doesn't work. This is better than a half-working application that has mutability bugs hidden deep inside of it.

For example, suppose that we call set() on an immutable map to set a value, expecting that simply calling this method would be enough to change the state of the map. But since the set() method is a persistent change, it doesn't change the map—it creates and returns a new map. So while we weren't expecting this behavior, it's better than accidentally changing the state of something.

Side-effects in code that uses mutable data are implicit. Immutable.js, on the other hand, promotes explicit side-effects by placing them at the end of a method call chain. This makes the side-effects in your code easy to spot, and easy to reason our way through the sequence of transformations and persistent changes that lead up to the side-effect occurring.

Implicit side-effects are problematic because we don't have any meaningful way to track them. For example, you change some data that results in four function calls being made. Do any of them have side-effects? Two of them? All of them? Do the side-effects cascade into other side-effects? We're creating too much work for our brains to handle here.

The trick with Immutable.js is to make explicit the things that matter when you're reading code. This means quickly figuring out what caused a given side-effect to occur. On the other hand, you can't make everything explicit otherwise you'd have a mountain of code to sift through. The implicitness of Immutable.js comes with piecing together data by gluing it together using chaining—there's a lot going on behind the scenes that you don't need to think about.

Immutable.js isn't the only library out there that does what it does. While it is unique in its approach to handling immutable data, it's never a bad idea to compare one library with another. What, exactly, are we comparing it with, though?

There's no point in comparing a library such as Immutable.js with something that has no notion of functional programming or immutability. For instance, Angular is a framework for building applications, and observing changes in state is a core pattern. This is something that Immutable.js doesn't do. Comparing Immutable.js with something such as React doesn't make much sense either. Despite the fact that React honors concepts such as avoiding side-effects, we wouldn't be comparing apples with apples, as they do different things at different levels of abstraction.

Some criteria that you would use to compare Immutable.js with other libraries include the following:

• Is it a low-level library?
• Does it support the notion of immutability?
• Does it have the concept of collections?
• How large is the API compared with that of Immutable.js?
• How efficiently can it handle immutable data?

Lodash is a popular utility library that does a lot of the same things as Immutable.js. It supports the notion of immutability and avoids side-effects. It also supports the concept of collections. Its approach to efficiency is different from what Immutable.js does, but it's there. It might have a larger API than Immutable.js, but it's not that much larger.

The two libraries differ greatly in their overall approach and design, but they're comparable in the aspects that matter. Learning Lodash before switching to Immutable.js isn't a total loss and vice versa. You won't know which libraries work best for you until you write code that uses them.

We'll start writing Immutable.js code in a moment.

This chapter introduced you to the conceptual foundation of Immutable.js. Immutable data is how we prevent unwanted side-effects. With Immutable.js collections, everything results in new data. This includes changing the collection somehow—these are called persistent changes. It also includes shaping the data in order to do something with it—these are called sequence transformations.

The typical Immutable.js pattern involves chaining collection method calls together—the persistent changes and sequence transformations—ending with a side-effect.

In the next chapter, we'll write some code that creates Immutable.js collections.