Immutability – the idea that you should never work with “live” data, is slowly transforming the way that programmers work with objects, data and streams. From reducing hidden variables in functions to making database programming simpler to reducing the chance for difficult to find bugs to make its way into your code, immutability is becoming the quiet revolution in Javascript.

This particular piece is going to dig into what immutability actually means in programming (specifically in JavaScript, and even more specifically the React library). There’s more than a bit of theory here, but the goal is to illustrate why immutability – as a design pattern and a library – can make such a big difference in code.

Javascript’s Reference Problem

When most neophyte programmers are learning about functions, at some point they discover that objects can be passed as parameters. It’s perhaps at this point that the true nature of objects begin to manifest. An object can be passed by value, in which case, when you supply the object, the system creates a duplicate of that object, or it can be passed by reference. Passing by reference means that if you change the object within the function, you are actually modifying the original object, not a duplicate.

Javascript in general dispenses with passing by value for anything except for pre-existing data types such as strings – everything is passed by reference. This can have some interesting consequences. For instance, suppose that you have an array of colors within a variable, then use the invoke a function to an item to that list at the end.

function addItem(array,value){ array[array.length]=value; return array; }; var colors = ["red", "green", "blue", "orange","yellow","aqua"]; var extColors = addItem(colors,"black");

The problem with this is that if you look at both variables afterwards, you’ll discover that they contain the same list:

console.log(colors,extColors) // colors: ["red", "green", "blue", "orange", "yellow", "aqua", "black"] // extColors: ["red", "green", "blue", "orange", "yellow", "aqua", "black"]

More experienced programmers understand that, because the colors array was passed (implicitly) by reference, the original array was modified and then passed back. Indeed, in order for the function to pass back a distinct array, it’s necessary to create a copy of the existing array then modify that:

function addItem2(array,value){ var newArray = new Array[array]; newArray[newArray.length]=value; return newArray; }; This will create the expected result: var colors = ["red", "green", "blue", "orange","yellow","aqua"]; var extColors = addItem2(colors,"black"); console.log(colors,extendedColors) // colors: ["red", "green", "blue", "orange", "yellow", "aqua"] // extColors: ["red", "green", "blue", "orange", "yellow", "aqua", "black"]

The advantage to working by reference is that it avoids the allocation of a new object. However, there are some significant disadvantages to it, disadvantages that become more evident the more complex a project becomes. One of the biggest is that when you pass objects by reference into a function, you do not necessarily know what that function is going to do with your data. It could add additional data, remove data, rearrange information, perhaps even assign something altogether different. It’s like taking in a cat to the vet to get her claws clipped, only to get a St. Bernard (with clipped claws, mind you) when you pick her up.

This problem is frequently referred to as the hidden variables (or side effects) problem, and it can prove fiendishly difficult to debug when it happens, especially in this day and age of extended frameworks. Side-effect-free programming means that nothing can be passed by reference, and the result of a function should be free of previous references.

This approach to programming has some interesting implications. First, it means that such functions are considered composable – the output of one function can be used as the input of another, and any large action can be then broken down into a sequence of smaller functions.

Indeed, computer science identifies such programming as being functional (made up of composable functions) rather than imperative (command oriented). Javascript has been heavily influenced in the last year by concepts from functional languages such as Lisp, Scheme, Haskell, Miranda, and OCaml, as well as more recent languages such as Clojure and F#. Indeed, many of the more widely used EcmaScript 6 features, such as arrow functions, and destructuring, come directly from languages such as Haskell.

Immutables and Passing By Value

Because Javascript doesn’t have a “pass by value” parameter mode for objects, it’s necessary to circumvent the natural behavior of Javascript. To make this happen a number of libraries have sprung up around the notion of immutability, with the dominant one (and the one covered here) being immutable.js produced by the Facebook team.

Immutability implies changelessness (“mutate”, of course, means “to change”). A variable that is completely immutable, however, is pretty useless, as you couldn’t assign a value to it in the first place. Here, the distinction is that, once you have assigned a certain object value to that variable, you cannot remove information … you can only add to it. What’s more, what gets returned is a distinct object.

For instance (assuming you’ve added the appropriate library), the immutable List object gives you similar functionality to the Array object:

var list = Immutable.List(["red","green","blue"]) console.log(list); // List [ "red", "green", "blue" ] var list2 = list.push("yellow"); console.log(list2); // List [ "red", "green", "blue", "yellow" ] var popped = list.last(); var list3 = list.pop() console.log(list3 , popped); // List [ "red", "green"], "blue"

Note that while List.push() has a similar effect to what Array.push() does (though it returns a new list), List.pop() returns a new list copying the old one, but removing the last item. This means that you need to retrieve the end of the list first (the thing being popped off) before calling the list.pop() function.

The Immutable.js library incorporates a number of related data structures – Lists, Sets, Maps, Ordered Maps, Stacks, Ranges, Sequences (Seq), Records and Iterables, along with the abstract Collection structure that underlies the others. Most of these have been optimized to provide the minimum necessary storage for the types. For instance, you can set a range (a sequence of consecutive numbers) to have an infinite number of items. These range object doesn’t actually store this (for obvious reasons), but instead provides an iterator function that produces new items with the appropriate value when needed.

It should be noted that ES6 does not have native immutables, though classes can be built that provide this functionality. Whether immutables will make it into a subsequent version of Javascript natively is still being determined.

React’s Immutables and Efficient Processing

One of the key benefits of MVC frameworks is the concept of data binding – a variable (or data in general) is bound by a user interface controller to a specific presentation view. By changing the data you change the view and vice versa. While React is not a full MVC (it only handles the view layer), internally React maintains a virtual DOM that is optimized to determine whether a given subcomponent needs to be refreshed. Put another way, React doesn’t bind user interface controls directly, but instead re-renders subcomponents when its internal model changes.

As such, immutability can play a major role in React – and in fact can vastly improve performance there. To understand why, a couple of diagrams can prove useful:

Diagram 1. React components with mutable deep source JSON.

In Diagram 1, a React component updates up to three levels deep. Each “node” is a DOM node that is created in memory, then compared to what is already there. If the calculated DOM output is the same as what’s there, that node is not updated, but any child components still must go through this same process. This means that, here, React has to look at 12 of 15 nodes, and change roughly half, avoiding the final three only because the data for generating the need is a leaf and hence either changed or unchanged for all children.

The key to making this happen is the shouldComponentUpdate() method of the React class, which returns true if the component needs to be updated and false otherwise. The React base class has it’s own sCU() function, but by writing a new one you overwrite this for those components where such comparisons take place.

React.createClass({ propTypes: { value: React.PropTypes.string.isRequired }, render: function() { return <div>{this.props.value}</div>; } shouldComponentUpdate: function(nextProps, nextState) { return this.props.value !== nextProps.value; } });

Diagram 2. React component with immutable data.

In the case where data structures are guaranteed immutable, there are two comparisons – the first is, as above, whether the pre-rendered DOM structures have changed, while the latter indicates whether the source data itself has changed. Once React has a guarantee that a deep source data structure is the same all the way down, then this can shortcut the need to check every node.

This means that, in the above case, rather than needing to check 80% of the nodes, you only need to check 45%, and only need to change 4. The can result in huge performance differences, especially for complex renders.

var someRecord = Immutable.Record({ foo: null }); var y = x.set('foo', 'baz'); x === y; // false React.createClass({ propTypes: { value: React.PropTypes.string.isRequired }, render: function() { return <div>{this.props.value}</div>; } shouldComponentUpdate: function(nextProps, nextState) { return this.state !== nextProps.value; } });

Immutability makes this process a little more difficult in some respects, though easier in others. In a mutable framework, you need to place observers on variables in order to determine when a specific value has changed, then you have to navigate to the view to modify just that particular value. This means that you end up with a great number of dependencies, that often have an adverse impact upon performance.

With immutability, on the other hand, you do not need to know precisely what changed. This means that when you update a specific instance in your model at any point, you are changing the whole instance. By binding to the instance rather than a specific value in that instance, the component in question would then just update the visual appearance of the whole component. This can make for a slightly less granular design, but has no hidden variables, and more to the point becomes recursively composable – you only modify things that are specifically in the context of the component, not the framework that the component is in. You also have the advantage of being able to archive the old state in toto for that component, possibly associating it with a time stamp. This makes “undos” much easier.

Using React, you can add support for immutables by requiring the “react-addons-update.js” library from the React site.

The following shows how such immutables may be changed in React, with the update() function handling the process of creating a new immutable from an existing one.

App.data = obj = {a: 10, b: 7}; var newObj = update(obj, {b: {$apply: (x)=> x * x}}); save(newObj); App.data = newObj; App.render();

The notation {$apply: (x) => x*x} is an example of a command, and includes $apply, $set, $push, $unshift, $splice and $merge, the dominant mutation commands. More information about immutables in React can be found at https://facebook.github.io/react/docs/update.html.

An Immutable React Example: Image Viewer

One of the best ways of understanding immutables is to see a working example. The following is a React component that allows users to enter in URLS of pictures, see a preview, then add this to an image carousel of thumbnails. When you click on a thumbnail, the larger image is displayed, as shown below.

JS Bin on jsbin.com

While the application is a comparatively simple one, it does illustrate one way that React makes use of immutable data structures. The code for the image viewer can be seen below:

/* This retrieves the List and Map structure from the React + Extensions library, and identifies these as being immutable objects. Note that these use the immutable.js data structures not the new Map and List ES6 core classes. This means that changing a map or list will always create a copy of that structure rather than a reference to the original structure. */ var { List, Map } = Immutable; /* The React component in the render() method can define both inline styles (by passing javascript objects as shown here, and CSS classes (by using the className property). These largely handle the layout of the component. */

var styles = { imgStyle:{ maxWidth:"250px", maxHeight:"250px" }, itemStyle:{ maxWidth:"250px", maxHeight:"250x", backgroundColor:"black" }, containerStyle:{ display:"inline-block", maxWidth:"270px", maxHeight:"600px", overflowY:"auto", border:"inset 2px gray", backgroundColor:"black" }, timestampStyle:{ color:"white" }, widgetStyle:{ display:"block", verticalAlign:"top" }, displayWidgetStyle:{ display:"inline-block", verticalAlign:"top" }, displayImageStyle:{ maxWidth:"800px", maxHeight:"800px" }, };

/* This is the Component class creator, used to build the <component> object */ var Component = React.createClass({ /* This sets up the default data object that holds the state for the application. Note that the Map here is an immutable object, so rather than setting the values internally, this becomes the state that then becomes copied when the application starts, and new states are created by mutating these copies and making them the working data copy within the React system. In this case, items is an (empty) immutable list, url is the working url, and index is the selected item from the list. */ getInitialState() { return { data: Map({ items: List(), url: "",timestamp:"",index:-1 }) } }, /* The render is shown every time there is a mutation event upon the initial state object. This creates a comparison DOM against what React already holds, and only if the resulting pre-rendered DOM is different from the existing DOM does React render that portion. Again it's also worth noting that render() makes use of React's HTML-like structure, which looks similar to HTML but has different conventions with regard to how output is bound to properties or the state variables initially defined in the getInitialState() method. Also note the use of ES6/2015 style arrow statements, designed to emulate anonymous functions for callbacks. The 'data' variable echoes the current "state" as it evolves from the initial conditions. */ render() { var data = this.state.data; return ( <div> <div style={styles.widgetStyle}> <input type="text" onChange={this.handleURLChange} value={data.get('url')}/> <button onClick={this.handleAddItemClick}>Add Item</button> </div> <div> <div style={styles.containerStyle}> {data.get('items').map((item,index) => <div style={styles.itemStyle}> <div><img src={item.url} style={styles.imgStyle} onClick={this.handleThumbClick} data-index={index}/></div> <div style={styles.timestampStyle}>{item.index}: {item.timestamp}</div> </div> )} </div> <div style={styles.displayWidgetStyle}> <img src={data.get('url')} style={styles.displayImageStyle}/> </div> </div> </div> ); }, /* The handle URLChange function updates the "working" URL of the images from the input box, and when rendered, will change the view image. Note that each of receives a specialized "super-event" object from React that can be used to get information appropriate to the event type. These are not Javascript events, though they contain the information from such events, but are used in part to pass information back to the React framework. */ handleURLChange(evt){ var newValue = var activeIndex = evt.currentTarget.value console.log(newValue); this.setState(({data}) => ({ data: data.update('url',v=>newValue) })); }, /* When the thumbnails in the carousel are clicked, this reads the index property from the assigned data-index property and from that uses this to compute which url is used for the large image. The setState function here then updates this URL and creates a new state object, replacing the old. */ handleThumbClick(evt){ var activeIndex = evt.currentTarget.dataset.index; var url = this.state.data.get('items').get(activeIndex).url; this.setState(({data}) => ({ data: data.update('url',v=>url) })); }, /* The handleAddItemClick function increments the active index by one, then creates an object consisting of the new url, index and a timestamp and puts it onto the list. Again, because of the use of immutables, these operations are more optimal for updating. The unshift function is similar to the push() function on an array, except that it places the object into the beginning of a list rather than the end. This means that the last item entered will always be at the top of the list. */ handleAddItemClick() { this.setState(({data}) => ({ data: data.update('index',v=>v+1) })); this.setState(({data}) => ({ data: data.update('items', list => list.unshift({ index:data.get('index'),url:data.get('url'),timestamp:(new Date()).toLocaleString()})) })); } }); /* This then kicks of the process of rendering the (anonymously named) <Component element to take up the entire document. Setting it to a subordinate container element will render it just in that element, not replaceing the whole page content. */ React.render(<Component />, document.body);

The results of this code can be seen and explored with at https://output.jsbin.com/zonihem.

The Benefits of Immutables

Preventing corruption by ensuring that existing data can’t be overwritten is one area where immutables provide useful. There are others. One such, as a design principle, comes in separating the data of an object from its operations. This may seem more than a little counterintuitive. After all, isn’t one of the biggest benefits of object oriented programming the fact that you can in fact encapsulate (or bundle) data together with its operations?

The answer may surprise you. Object oriented programming arose at a time when most applications were stand-alone, and the number of objects in play were typically fairly small. The benefit of retaining state was also fairly small for many of these objects, so you could effectively update the state of an object by overwriting the previous state, without worrying about retaining previous information.

That began to change as applications began to span tiers. Increasingly, data structures have resided in documents, either JSON or (less commonly) XML, located on servers. In this case the Javascript acts like a function to modify the document as a unit, then update this back to the server.

This idea of treating data contextually – not just single values but essentially all of the local information about a given entity – has a profound impact on development. Most information is not atomic – you seldom change a street address without changing city, state and zipcode. In an immutable world, this entity becomes, in essence, a key part of a transaction, and the transaction is only committed once the information it contains is complete and internally consistent. As such, working on copies of things only makes sense, and functions should then be seen as things that can change the entity as a whole.

Immutables carry this concept into the core of coding, reminding you as the coder that you are working not on individual properties (or even records) but objects as a whole. As such the use of immutability prevents incomplete (or improper) transactions, enables better code pipelines and prevents unexpected side effects that can add significantly to the debugging cycle cost and time.

Kurt Cagle (kurt.cagle@gmail.com) is an author, information architect and Javascript programmer. He is available for Javascript, node, MarkLogic and semantic software development.