Immutable.js: The Foolproof Guide to Creating Lists

An Immutable List is similar to a JavaScript array, but different enough to catch you out if you don’t create a List correctly. Here are all the different ways to create a List, using arrays, objects, and everything else.

Create an empty List

// Empty List:
const list = Immutable.List();

// Output:
list;

Create a populated List of data

List() vs List.of()

You can create a List of data using either the List() constructor, or the List.of() method, depending on the type of data you’re using to create the List:

• List.of() – use when creating a List from non-iterable data (e.g. a set of function arguments, a JavaScript object, or a string you want interpreted as a whole string);
• List() – use when creating a List from iterable data (e.g. an array, or an Immutable Iterable object (List, Map, Set, etc.), or a string that you want interpreted as a series of characters).

Important: a JavaScript string is an iterable object, so if you create a List of strings using List("string"), you’ll actually get a List of characters (['s', 't', 'r', 'i', 'n', 'g']). To make Immutable interpret a string as a non-iterable value, use List.of("string") instead. See the examples below.

Create a new List from…

…a JavaScript Array

// Create a new List from a JavaScript array
const avengersArray = ['ironMan', 'captainAmerica'];
const avengersList = Immutable.List(avengersArray);

// Output:
avengersList;

…a nested JavaScript Array

Immutable’s List constructors only create a List from a the top level of an Array. This means that a nested array will be turned into an Immutable List of arrays, whereas you might prefer a List of Lists.

To ensure all nested arrays are converted to Immutable Lists, use the Immutable.fromJS() function:

// Create a deeply nested List from a deeply nested Array
// Get a value from a deeply nested List
const avengers = [
  'ironMan', // index [0]
  ['captainAmerica', // index [1][0]
   ['blackWidow', // index [1][1][0]
    ['theHulk'] // index [1][1][1][0]
   ]
  ]
];

const avengersList = Immutable.fromJS(avengers);

// get the array containing 'theHulk' and test if it's a List
Immutable.List.isList(avengersList.getIn([1, 1, 1]));

To show the difference between Immutable.fromJS(avengers) and Immutable.List(avengers), try changing fromJS to List in the example above and you’ll see the result returned as false. This is because the deeply nested array that contains ‘theHulk’ is still an array, and not an Immutable List.

Golden Rule: If you want everything to be converted to Immutable, use fromJS(). If you want your nested Arrays to remain Arrays, use List() or List.of().

…a JavaScript Object

When creating a List from a JavaScript object, remember that the List acts like a JavaScript array, and so will treat the entire object as a single item. Accordingly, your new List will only have one item – the JavaScript object.

You’ll need to use the List.of() function to create the List, as without it, Immutable will expect to be given an iterable, and an object is not an iterable:

// New List from existing JavaScript object
const avengers = {
  ironMan: 'Tony Stark',
  captainAmerica: 'Steve Rogers'
};

const avengersList = Immutable.List.of(avengers);
avengersList;

…a set of function arguments

To create an Immutable List of values that are passed in as a list of function arguments, use List.of().

// Create a new List using function arguments

const avengersList = Immutable.List.of(
   'ironMan', 'captainAmerica', 'blackWidow'
);

// Output:
avengersList;

…a JavaScript iterator

ES6 iterators are objects that define an iterable behaviour – that is, they implement the ES6 @@iterator method, and define what values are looped over in a for..of loop (among other things).

There are currently five built-in iterators in ES6:

• String
• Array
• TypedArray
• Map
• Set

You can also create your own iterable, should you wish (see MDN’s Iterable page for more details).

Any ES6 iterable object, either built-in or user-defined, can be used to create a new Immutable List. For example:

// New List from existing JavaScript iterator (Array.map example)
const avengersArray = ['ironMan', 'captainAmerica'];
const avengersList = Immutable.List(
   avengersArray.map(item => 'We love ' + item)
);

// Output:
avengersList;

…an Immutable List

Here’s how to create a new List from an existing List:

// New List from existing List
const avengersList = Immutable.List(['ironMan', 'captainAmerica']);
const newAvengersList = Immutable.List(avengersList);

// Output:
newAvengersList;

…an Immutable Map

An Immutable Map derives from the Immutable Iterable class, and so can be used to create a List using the List() constructor

// New List from Immutable Map
const avengers = Immutable.Map({
  ironMan: 'Tony Stark',
  captainAmerica: 'Steve Rogers'
});

const avengersList = Immutable.List(avengers);
avengersList;

…other Immutable types

You can create a new List with any Immutable object, including:

• List
• Map
• OrderedMap
• Set
• OrderedSet
• Stack
• Record

As these all derive from Immutable’s Iterable class, you use the List constructor (List()) to create your List from each type, rather than the List.of() method.

Getting and Setting List Data

Now that you’ve created a List, how do you get items from it, and add new items into it? Is that even possible with an Immutable List? That’s the focus of the next post in this series, which gives you all the examples you’ll ever need to get, set and update data in an Immutable.js List.