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.
All Immutable.js Tutorials in this Series
This is just one tutorial in this in-depth series of Immutable.js tutorials. Here are the others, which all contain a wealth of information and examples (and all in JavaScript!).
Introduction
Lists
- The Foolproof Guide to Creating Lists
- Get, Set and Delete data from an Immutable List
- Merging Lists Finally Explained
Maps
- Every Way to Create an Immutable.js Map
- Get, Set, Delete and Update data from an Immutable Map
- 6 Ways to Merge Maps in Immutable.js
Sean Levy
Possible to get a PDF copy of this entire document?
regards
Sean
Mike Evans
Hmmm, not a bad idea. Give me a week or so and I’ll see what I can do.