seamless-immutable vs immer vs immutability-helper
State Management and Immutability in JavaScript
seamless-immutableimmerimmutability-helperSimilar Packages:

State Management and Immutability in JavaScript

State management libraries in JavaScript help developers manage and maintain the state of an application in a predictable way. They provide tools and patterns for updating, reading, and synchronizing state across different parts of an application, making it easier to build complex user interfaces, handle asynchronous data, and ensure that the UI reflects the current state of the application. These libraries often implement concepts like immutability, time travel debugging, and centralized state storage to improve the reliability and maintainability of the code. immer is a popular library that allows developers to work with immutable state in a more intuitive way by using a mutable-like syntax, while immutability-helper provides a simple and efficient way to update nested immutable data structures using a concise and declarative API. seamless-immutable is a lightweight library that creates deeply immutable objects and arrays, ensuring that the original data cannot be modified, which helps prevent accidental mutations and makes the code more predictable.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
seamless-immutable388,2675,351-548 years agoBSD-3-Clause
immer028,902913 kB48a month agoMIT
immutability-helper05,261-66 years agoMIT

Feature Comparison: seamless-immutable vs immer vs immutability-helper

Immutability Model

  • seamless-immutable:

    seamless-immutable creates deeply immutable objects and arrays by recursively freezing the data. Once an object is made seamless-immutable, it cannot be changed, ensuring that all levels of the structure are protected from mutations.

  • immer:

    immer uses a proxy-based approach to allow mutable-like updates while keeping the original state immutable. This means you can write code that looks like it modifies the state directly, but immer tracks the changes and produces a new immutable state object.

  • immutability-helper:

    immutability-helper provides a declarative way to update nested immutable data using a simple syntax. It allows you to specify the changes you want to make at any level of the object, and it handles creating the new immutable structure for you.

Ease of Use

  • seamless-immutable:

    seamless-immutable is very easy to use for creating immutable data. However, since it does not provide any tools for updating the data, developers need to be mindful of how they handle state changes.

  • immer:

    immer is easy to use, especially for developers who are familiar with mutable programming. Its API allows for intuitive state updates without needing to understand the complexities of immutability.

  • immutability-helper:

    immutability-helper has a simple and straightforward API that makes it easy to update nested data structures. Its declarative nature helps keep the code clean and understandable.

Performance

  • seamless-immutable:

    seamless-immutable is very fast for creating immutable objects, but since it creates a new copy of the data structure for every update, it is important to use it judiciously in performance-sensitive applications.

  • immer:

    immer is efficient for most use cases, but its proxy-based approach can introduce some overhead, especially for very large objects or frequent updates. However, the trade-off is often worth it for the clarity it brings to state management.

  • immutability-helper:

    immutability-helper is lightweight and performs well for updating nested data structures. It is designed to be efficient, but performance can vary depending on the complexity of the updates being made.

Mutability Control

  • seamless-immutable:

    seamless-immutable enforces strict immutability by making the entire object and its properties read-only, preventing any form of mutation.

  • immer:

    immer allows for controlled mutability within the produce function, giving developers the flexibility to write code that feels mutable while maintaining immutability at the data structure level.

  • immutability-helper:

    immutability-helper does not allow mutability; it enforces immutability by creating new copies of the data structure based on the specified changes.

Code Example

  • seamless-immutable:

    Example of creating immutable objects with seamless-immutable:

    import seamless from 'seamless-immutable';
    
    const immutableObj = seamless({ name: 'Alice', age: 25 });
    const immutableArr = seamless([1, 2, 3]);
    
    console.log(immutableObj.name); // Alice
    console.log(immutableArr[0]); // 1
    
    // Attempting to mutate will fail silently (in strict mode) or throw an error
    immutableObj.name = 'Bob'; // No error, but the change is ignored
    immutableArr[0] = 10; // No error, but the change is ignored
    
    console.log(immutableObj.name); // Alice
    console.log(immutableArr[0]); // 1
    
  • immer:

    Example of using immer for state updates:

    import produce from 'immer';
    
    const initialState = { count: 0, user: { name: 'Alice' } };
    
    const nextState = produce(initialState, draft => {
      draft.count += 1; // Mutating the draft
      draft.user.name = 'Bob'; // Mutating nested property
    });
    
    console.log(nextState); // { count: 1, user: { name: 'Bob' } }
    console.log(initialState); // { count: 0, user: { name: 'Alice' } }
    
  • immutability-helper:

    Example of using immutability-helper for nested updates:

    import update from 'immutability-helper';
    
    const initialState = { count: 0, user: { name: 'Alice', age: 25 } };
    
    const nextState = update(initialState, {
      count: { $set: initialState.count + 1 }, // Update count
      user: { name: { $set: 'Bob' }, age: { $set: 26 } }, // Update nested properties
    });
    
    console.log(nextState); // { count: 1, user: { name: 'Bob', age: 26 } }
    console.log(initialState); // { count: 0, user: { name: 'Alice', age: 25 } }
    

How to Choose: seamless-immutable vs immer vs immutability-helper

  • seamless-immutable:

    Choose seamless-immutable if you want a minimalistic library that creates completely immutable objects and arrays. It is best for scenarios where you need to ensure that data cannot be changed at all, providing a strong guarantee against mutations.

  • immer:

    Choose immer if you want to work with immutable state in a more natural way, using a mutable-like syntax while still ensuring immutability under the hood. It is particularly useful for complex state updates where you want to avoid the boilerplate of manually creating new copies of nested objects.

  • immutability-helper:

    Choose immutability-helper if you need a lightweight and straightforward solution for updating nested immutable data structures. It is ideal for projects where you want to keep the code simple and readable while still adhering to immutability principles.

README for seamless-immutable

seamless-immutable

Immutable JS data structures which are backwards-compatible with normal Arrays and Objects.

Use them in for loops, pass them to functions expecting vanilla JavaScript data structures, etc.

var array = Immutable(["totally", "immutable", {hammer: "Can’t Touch This"}]);

array[1] = "I'm going to mutate you!"
array[1] // "immutable"

array[2].hammer = "hm, surely I can mutate this nested object..."
array[2].hammer // "Can’t Touch This"

for (var index in array) { console.log(array[index]); }
// "totally"
// "immutable"
// { hammer: 'Can’t Touch This' }

JSON.stringify(array) // '["totally","immutable",{"hammer":"Can’t Touch This"}]'

This level of backwards compatibility requires ECMAScript 5 features like Object.defineProperty and Object.freeze to exist and work correctly, which limits the browsers that can use this library to the ones shown in the test results below. (tl;dr IE9+)

build status NPM version coverage status

Performance

Whenever you deeply clone large nested objects, it should typically go much faster with Immutable data structures. This is because the library reuses the existing nested objects rather than instantiating new ones.

In the development build, objects are frozen. (Note that Safari is relatively slow to iterate over frozen objects.) The development build also overrides unsupported methods (methods that ordinarily mutate the underlying data structure) to throw helpful exceptions.

The production (minified) build does neither of these, which significantly improves performance.

We generally recommend to use the "development" build that enforces immutability (and this is the default in Node.js). Only switch to the production build when you encounter performance problems. (See #50 for how to do that in Node or using a build tool - essentially do explicitely refer to the production build.)

Intentional Abstraction Leaks

By popular demand, functions, errors, dates, and React components are treated as immutable even though technically they can be mutated. (It turns out that trying to make these immutable leads to more bad things than good.) If you call Immutable() on any of these, be forewarned: they will not actually be immutable!

Add-ons

seamless-immutable is tightly focused on the mechanics of turning existing JavaScript data structures into immutable variants. Additional packages are available to build on this capability and enable additional programming models:

LibraryDescription
CursorCompact Cursor Library built on top of the excellent seamless-immutable. Cursors can be used to manage transitions and manipulations of immutable structures in an application.
MergersA collection of mergers for use with seamless-immutable. Also includes documentation about custom mergers, with examples, for writing your own.

API Overview

Immutable() returns a backwards-compatible immutable representation of whatever you pass it, so feel free to pass it absolutely anything that can be serialized as JSON. (As is the case with JSON, objects containing circular references are not allowed. Functions are allowed, unlike in JSON, but they will not be touched.)

Since numbers, strings, undefined, and null are all immutable to begin with, the only unusual things it returns are Immutable Arrays and Immutable Objects. These have the same ES5 methods you’re used to seeing on them, but with these important differences:

  1. All the methods that would normally mutate the data structures instead throw ImmutableError.
  2. All the methods that return a relevant value now return an immutable equivalent of that value.
  3. Attempting to reassign values to their elements (e.g. foo[5] = bar) will not work. Browsers other than Internet Explorer will throw a TypeError if use strict is enabled, and in all other cases it will fail silently.
  4. A few additional methods have been added for convenience.

For example:

Immutable([3, 1, 4]).sort()
// This will throw an ImmutableError, because sort() is a mutating method.

Immutable([1, 2, 3]).concat([10, 9, 8]).sort()
// This will also throw ImmutableError, because an Immutable Array's methods
// (including concat()) are guaranteed to return other immutable values.

[1, 2, 3].concat(Immutable([6, 5, 4])).sort()
// This will succeed, and will yield a sorted mutable array containing
// [1, 2, 3, 4, 5, 6], because a vanilla array's concat() method has
// no knowledge of Immutable.

var obj = Immutable({all: "your base", are: {belong: "to them"}});
Immutable.merge(obj, {are: {belong: "to us"}})
// This will return the following:
// Immutable({all: "your base", are: {belong: "to us"}})

Static or instance syntax

Seamless-immutable supports both static and instance syntaxes:

var Immutable = require("seamless-immutable").static;
var obj = {};

Immutable.setIn(obj, ['key'], data)
var Immutable = require("seamless-immutable");
var obj = {};

obj.setIn(['key'], data)

Although the later is shorter and is the current default, it can lead to collisions and some users may dislike polluting object properties when it comes to debugging. As such the first syntax is recommended, but both are supported.

Immutable.from

If your linter cringes with the use of Immutable without a preceding new (e.g. ESLint's new-cap rule), use Immutable.from:

Immutable.from([1, 2, 3]);
// is functionally the same as calling:
Immutable([1, 2, 3])

Immutable Array

Like a regular Array, but immutable! You can construct these by passing an array to Immutable():

Immutable([1, 2, 3])
// An immutable array containing 1, 2, and 3.

Beyond the usual Array fare, the following methods have been added.

flatMap

var array = Immutable(["here", "we", "go"]);
Immutable.flatMap(array, function(str) {
  return [str, str, str];
});
// returns Immutable(["here", "here", "here", "we", "we", "we", "go", "go", "go"])

var array = Immutable(["drop the numbers!", 3, 2, 1, 0, null, undefined]);
Immutable.flatMap(array, function(value) {
  if (typeof value === "number") {
    return [];
  } else {
    return value;
  }
});
// returns Immutable(["drop the numbers!", null, undefined])

Effectively performs a map over the elements in the array, except that whenever the provided iterator function returns an Array, that Array's elements are each added to the final result.

asObject

var array = Immutable(["hey", "you"]);
Immutable.asObject(array, function(str) {
  return [str, str.toUpperCase()];
});
// returns Immutable({hey: "HEY", you: "YOU"})

Effectively performs a map over the elements in the array, expecting that the iterator function will return an array of two elements - the first representing a key, the other a value. Then returns an Immutable Object constructed of those keys and values.

You can also call .asObject without passing an iterator, in which case it will proceed assuming the Array is already organized as desired.

asMutable

var array = Immutable(["hello", "world"]);
var mutableArray = Immutable.asMutable(array);

mutableArray.push("!!!");

mutableArray // ["hello", "world", "!!!"]

Returns a mutable copy of the array. For a deeply mutable copy, in which any instances of Immutable contained in nested data structures within the array have been converted back to mutable data structures, call Immutable.asMutable(obj, {deep: true}) instead.

isImmutable

var array = Immutable(["hello", "world"]);
var mutableArray = ["hello", "world"];

Immutable.isImmutable(array)
// returns true

Immutable.isImmutable(mutableArray)
// returns false

Returns whether an object is immutable or not.

Immutable Object

Like a regular Object, but immutable! You can construct these by passing an object to Immutable().

Immutable({foo: "bar"})
// An immutable object containing the key "foo" and the value "bar".

To construct an Immutable Object with a custom prototype, simply specify the prototype in options (while useful for preserving prototypes, please note that custom mutator methods will not work as the object will be immutable):

function Square(length) { this.length = length };
Square.prototype.area = function() { return Math.pow(this.length, 2) };

Immutable(new Square(2), {prototype: Square.prototype}).area();
// An immutable object, with prototype Square,
// containing the key "length" and method `area()` returning 4

Beyond the usual Object fare, the following methods have been added.

Stack overflow protection

Currently you can't construct Immutable from an object with circular references. To protect from ugly stack overflows, we provide a simple protection during development. We stop at a suspiciously deep stack level and show an error message.

If your objects are deep, but not circular, you can increase this level from default 64. For example:

Immutable(deepObject, null, 256);

This check is not performed in the production build.

merge

var obj = Immutable({status: "good", hypothesis: "plausible", errors: 0});
Immutable.merge(obj, {status: "funky", hypothesis: "confirmed"});
// returns Immutable({status: "funky", hypothesis: "confirmed", errors: 0})

var obj = Immutable({status: "bad", errors: 37});
Immutable.merge(obj, [
  {status: "funky", errors: 1}, {status: "groovy", errors: 2}, {status: "sweet"}]);
// returns Immutable({status: "sweet", errors: 2})
// because passing an Array is shorthand for
// invoking a separate merge for each object in turn.

Returns an Immutable Object containing the properties and values of both this object and the provided object, prioritizing the provided object's values whenever the same key is present in both objects.

Multiple objects can be provided in an Array in which case more merge invocations will be performed using each provided object in turn.

A third argument can be provided to configure the merge. It should be an object with any of the following fields:

{
  deep: true, // perform a deep merge
  merger: yourCustomMerger // supply a custom merger
}

You can find examples and documentation about custom mergers here.

replace

var obj1 = Immutable({a: {b: 'test'}, c: 'test'});
var obj2 = Immutable.replace(obj1, {a: {b: 'test'}}, {deep: true});
// returns Immutable({a: {b: 'test'}});
obj1 === obj2
// returns false
obj1.a === obj2.a
// returns true because child .a objects were identical

Returns an Immutable Object containing the properties and values of the second object only. With deep merge, all child objects are checked for equality and the original immutable object is returned when possible.

A second argument can be provided to perform a deep merge: {deep: true}.

set

var obj = Immutable({type: "parrot", subtype: "Norwegian Blue", status: "alive"});
Immutable.set(obj, "status", "dead");
// returns Immutable({type: "parrot", subtype: "Norwegian Blue", status: "dead"})

Returns an Immutable Object with a single property set to the provided value. Basically a more straightforward way of saying

var obj = Immutable({type: "parrot", subtype: "Norwegian Blue", status: "alive"});
Immutable.merge(obj, {status: "dead"});

(and more convenient with non-literal keys unless you have ES6 [computed_property_names]).

A second argument can be provided to perform a deep compare: {deep: true}.

setIn

Like set, but accepts a nested path to the property.

var obj = Immutable({type: {main: "parrot", sub: "Norwegian Blue"}, status: "alive"});
Immutable.setIn(obj, ["type", "sub"], "Norwegian Ridgeback");
// returns Immutable({type: {main: "parrot", sub: "Norwegian Ridgeback"}, status: "alive"})

A second argument can be provided to perform a deep compare: {deep: true}.

getIn

Returns the value at the given path. A default value can be provided as a second argument.

var obj = Immutable({type: {main: "parrot", subtype: "Norwegian Blue"}, status: "alive"});
Immutable.getIn(obj, ["type", "subtype"]);
// returns "Norwegian Blue"
Immutable.getIn(obj, ["type", "class"], "Aves");
// returns "Aves"

update

Returns an Immutable Object with a single property updated using the provided updater function.

function inc (x) { return x + 1 }
var obj = Immutable({foo: 1});
Immutable.update(obj, "foo", inc);
// returns Immutable({foo: 2})

All additional arguments will be passed to the updater function.

function add (x, y) { return x + y }
var obj = Immutable({foo: 1});
Immutable.update(obj, "foo", add, 10);
// returns Immutable({foo: 11})

updateIn

Like update, but accepts a nested path to the property.

function add (x, y) { return x + y }
var obj = Immutable({foo: {bar: 1}});
Immutable.updateIn(obj, ["foo", "bar"], add, 10);
// returns Immutable({foo: {bar: 11}})

without

var obj = Immutable({the: "forests", will: "echo", with: "laughter"});
Immutable.without(obj, "with");
// returns Immutable({the: "forests", will: "echo"})

var obj = Immutable({the: "forests", will: "echo", with: "laughter"});
Immutable.without(obj, ["will", "with"]);
// returns Immutable({the: "forests"})

var obj = Immutable({the: "forests", will: "echo", with: "laughter"});
Immutable.without(obj, "will", "with");
// returns Immutable({the: "forests"})

var obj = Immutable({the: "forests", will: "echo", with: "laughter"});
Immutable.without(obj, (value, key) => key === "the" || value === "echo");
// returns Immutable({with: "laughter"})

Returns an Immutable Object excluding the given keys or keys/values satisfying the given predicate from the existing object.

Multiple keys can be provided, either in an Array or as extra arguments.

asMutable

var obj = Immutable({when: "the", levee: "breaks"});
var mutableObject = Immutable.asMutable(obj);

mutableObject.have = "no place to go";

mutableObject // {when: "the", levee: "breaks", have: "no place to go"}

Returns a mutable copy of the object. For a deeply mutable copy, in which any instances of Immutable contained in nested data structures within the object have been converted back to mutable data structures, call Immutable.asMutable(obj, {deep: true}) instead.

Releases

7.1.4

Fixed bug with custom mergers treating all non-truthy values as undefined (#244).

7.1.3

Treat Blob instances as immutable. Use Array.isArray over instanceof.

7.1.2

Treat Error instances as immutable.

7.1.1

Fix .npmignore

7.1.0

Add getIn and assumption that Promises are immutable.

7.0.0

Add Immutable.static as the preferred API. Default to development build in webpack.

6.3.0

Adds optional deep compare for .set, .setIn and .replace

6.2.0

Adds static alternatives to methods, e.g. Immutable.setIn

6.1.4

Fixes bug with deep merge() on an array argument.

6.1.3

Fixes bug with setting a new object on an existing leaf array.

6.1.2

Fixes bug where on some systems arrays are treated as plain objects.

6.1.1

without now handles numeric keys the same way as string keys.

6.1.0

Alias Immutable.from() to Immutable() for linters.

6.0.1

React components are now considered immutable.

6.0.0

Add cycle detection.

5.2.0

Add update and updateIn.

5.1.1

Immutable(Object.create(null)) now works as expected.

5.1.0

Add predicate support to without()

5.0.1

Fix missing dev/prod builds for 5.0.0

5.0.0

In development build, freeze Dates and ban mutating methods. (Note: dev and prod builds were mistakenly not generated for this, so to get this functionality in those builds, use 5.0.1)

4.1.1

Make setIn more null safe.

4.1.0

Adds set and setIn

4.0.1

Now when you require("seamless-immutable"), you get the development build by default.

4.0.0

main now points to src/seamless-immutable.js so you can more easily build with envify yourself.

3.0.0

Add support for optional prototyping.

2.4.2

Calling .asMutable({deep: true}) on an Immutable data structure with a nested Date no longer throws an exception.

2.4.1

Arrays with nonstandard prototypes no longer throw exceptions when passed to Immutable.

2.4.0

Custom mergers now check for reference equality and abort early if there is no more work needed, allowing improved performance.

2.3.2

Fixes a bug where indices passed into iterators for flatMap and asObject were strings instead of numbers.

2.3.1

Fixes an IE and Firefox bug related to cloning Dates while preserving their prototypes.

2.3.0

Dates now retain their prototypes, the same way Arrays do.

2.2.0

Adds a minified production build with no freezing or defensive unsupported methods, for a ~2x performance boost.

2.1.0

Adds optional merger function to #merge.

2.0.2

Bugfix: #merge with {deep: true} no longer attempts (unsuccessfully) to deeply merge arrays as though they were regular objects.

2.0.1

Minor documentation typo fix.

2.0.0

Breaking API change: #merge now takes exactly one or exactly two arguments. The second is optional and allows specifying deep: true.

1.3.0

Don't bother returning a new value from #merge if no changes would result.

1.2.0

Make error message for invalid #asObject less fancy, resulting in a performance improvement.

1.1.0

Adds #asMutable

1.0.0

Initial stable release

Development

Run npm install -g grunt-cli, npm install and then grunt to build and test it.