Why should I use immutablejs over object.freeze?

I don't think you understood what immutablejs offers. It's not a library which just turns your objects immutable, it's a library around working with immutable values.

Without simply repeating their docs and mission statement, I'll state two things it provides:

1. Types. They implemented (immutable) infinite ranges, stacks, ordered sets, lists, ...

2. All of their types are implemented as Persistent Data Structures.

I lied, here's a quote of their mission statement:

Immutable data cannot be changed once created, leading to much simpler application development, no defensive copying, and enabling advanced memoization and change detection techniques with simple logic. Persistent data presents a mutative API which does not update the data in-place, but instead always yields new updated data.

I urge you to read the articles and videos they link to and more about Persistent Data Structures (since they're the thing immutablejs is about), but I'll summarise in a sentence or so:

Let's imagine you're writing a game and you have a player which sits on a 2d plane. Here, for instance, is Bob:

var player = {  name: 'Bob',  favouriteColor: 'moldy mustard',  x: 4,  y: 10};

Since you drank the FP koolaid you want to freeze the player (brrr! hope Bob got a sweater):

var player = Object.freeze({    name: 'Bob',    ...});

And now enter your game loop. On every tick the player's position is changed. We can't just update the player object since it's frozen, so we copy it over:

function movePlayer(player, newX, newY) {    return Object.freeze(Object.assign({}, player, { x: newX, y: newY }));}

That's fine and dandy, but notice how much useless copying we're making: On every tick, we create a new object, iterate over one of our objects and then assign some new values on top of them. On every tick, on every one of your objects. That's quite a mouthful.

Immutable wraps this up for you:

var player = Immutable.Map({    name: 'Bob',    ...});function movePlayer(player, newX, newY) {    return player.set('x', newX).set('y', newY);}

And through the ﾉ*✧ﾟ magic ✧ﾟ*ヽ of persistent data structures they promise to do the least amount of operations possible.

There is also the difference of mindsets. When working with "a plain old [frozen] javascript object" the default actions on the part of everything is to assume mutability, and you have to work the extra mile to achieve meaningful immutability (that's to say immutability which acknowledges that state exists). That's part of the reason freeze exists: When you try to do otherwise, things panic. With Immutablejs immutability is, of course, the default assumption and it has a nice API on top of it.

That's not to say all's pink and rosy with cherry on top. Of course, everything has its downsides, and you shouldn't cram Immutable everywhere just because you can. Sometimes, just freezeing an object is Good Enough. Heck, most of the time that's more than enough. It's a useful library which has its niche, just don't get carried away with the hype.

According to my benchmarks, immutable.js is optimized for write operations, faster than Object.assign(), however, it is slower for read operations. So the descision depends the type of your application and its read/write ratio. Following are the summary of the benchmarks results:

-- MutableTotal elapsed = 103 ms = 50 ms (read) + 53 ms (write).-- Immutable (Object.assign)Total elapsed = 2199 ms = 50 ms (read) + 2149 ms (write).-- Immutable (immutable.js)Total elapsed = 1690 ms = 638 ms (read) + 1052 ms (write).-- Immutable (seamless-immutable)Total elapsed = 91333 ms = 31 ms (read) + 91302 ms (write).-- Immutable (immutable-assign (created by me))Total elapsed = 2223 ms = 50 ms (read) + 2173 ms (write).

Ideally, you should profile your application before introducing any performance optimization, however, immutability is one of those design decision must be decided early. When you start using immutable.js, you need to use it throughout your entire application to get the performance benefits, because interop with plain JS objects using fromJS() and toJS() is very costly.

PS: Just found out that deep freeze'ed array (1000 elements) become very slow to update, about 50 times slower, therefore you should only use deep freeze in development mode only. Benchmarks results:

-- Immutable (Object.assign) + deep freezeTotal elapsed = 45903 ms = 96 ms (read) + 45807 ms (write).

Both of them don't make the object deeply immutable.

However, using Object.freeze you'll have to create the new instances of the object / array by yourself, and they won't have structural sharing. So every change which will require deeply copying everything, and the old collection will be garbage collected.

immutablejs on the other hand will manage the collections, and when something changes, the new instance will use the parts of the old instance that haven't changed, so less copying and garbage collecting.