immutadot logo

A JavaScript library to deal with nested immutable structures.

push({ nested: { prop: [1, 2] } }, 'nested.prop', 3, 4)
// → { nested: { prop: [1, 2, 3, 4] } }

pickBy({ nested: [{ a: 1, b: 2, c: 3, d: 4 }, { e: 6 }] }, 'nested.0', v => v < 3)
// → { nested: [{ a: 1, b: 2 }, { e: 6 }] }

immutadot gives you a short and meaningful syntax to apply operations on immutable structures.

npm version Try on RunKit

CircleCI codecov

Immutability

In the last few years one of our biggest challenge has been to find an efficient way to detect changes in our data to determine when to re-render our interfaces.

An immutable object is an object that cannot be changed once created. It brings several benefits1:

  • Data changes detection made simple (Shallow comparison)
  • Memoization
  • Improve rendering performances
  • Explicit data changes
  • Avoid side effects

Our approach

Concise

ES2015+ new features are great to deal with arrays and objects. As data structures expand, the code you write to make data immutable gets bigger and less readable. immutadot uses the dot notation to address this issue.

Interoperability

immutadot uses plain JavaScript objects so you can access your data using standard ways. Moreover, it lets you freely enjoy your favorite libraries.

Exhaustive and yet extensible

immutadot comes with a large set of built-in utilities, mostly based on lodash. You haven't found what you're looking for? Do it yourself with the convert feature.

Learning curve

If you are already familiar with lodash and ES2015+ then you should be able to use immutadot quickly.

Installation

immutadot is available on npm repository.

using yarn:

$ yarn add immutadot

using npm:

$ npm install immutadot

or you can directly download sources.

Usage

in browser:

  import { push } from 'immutadot'

  push({ nested: { prop: [1, 2] } }, 'nested.prop', 3, 4)
  // → { nested: { prop: [1, 2, 3, 4] } }

in node:

  const { push } = require('immutadot')

  push({ nested: { prop: [1, 2] } }, 'nested.prop', 3, 4)
  // → { nested: { prop: [1, 2, 3, 4] } }

Feel free to try immutadot on runkit.

Documentation

The full list of immutadot's features is available in our documentation.

Contributing

We want contributing to immutadot to be fun, enjoyable, and educational for anyone, and everyone.

Code of Conduct

In the interest of fostering an open and welcoming environment, we have adopted a Code of Conduct that we expect project participants to commit to. Please read the full text so that you can understand what behavior will and will not be tolerated.

Contributing guide

If you are interested in contributing to immutadot, please read our contributing guide to learn more about how to suggest bugfixes and improvements.

License

immutadot is MIT licensed.

Notes

  • 1: You can find more informations about immutability and its benefits in the following article http://reactkungfu.com/2015/08/pros-and-cons-of-using-immutability-with-react-js/