* This method is like {@link array.difference} except that it uses <code>comparator</code> to compare elements of the former array to <code>values</code>.
* @function
* @memberof array
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {...Array} values The arrays of values to exclude.
* @param {Function} [comparator] The comparator invoked per element.
* @see {@link https://lodash.com/docs#differenceWith|lodash.differenceWith} for more information.
* @since 1.0.0
*/
const differenceWith = convert(_differenceWith)
export { differenceWith }
+
import { differenceWith as _differenceWith } from'lodash'
import { convert } from'immutadot'
/**
* This method is like {@link array.difference} except that it uses <code>comparator</code> to compare elements of the former array to <code>values</code>.
* @function
* @memberof array
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {...Array} values The arrays of values to exclude.
* @param {Function} [comparator] The comparator invoked per element.
* This method is like {@link array.intersection} except that it uses <code>comparator</code> to compare elements of the former array to <code>arrays</code>.
* @function
* @memberof array
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {...Array} [arrays] The arrays to inspect.
* @param {Function} [comparator] The comparator invoked per element.
import { intersectionWith as _intersectionWith } from'lodash'
import { convert } from'immutadot'
/**
* This method is like {@link array.intersection} except that it uses <code>comparator</code> to compare elements of the former array to <code>arrays</code>.
* @function
* @memberof array
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {...Array} [arrays] The arrays to inspect.
* @param {Function} [comparator] The comparator invoked per element.
We are still writing the documentation, you can already find out about the updated API and our new package immutadot-lodash.
-
If you would like to try out 1.0 before its official release, install it with :
-
yarn add immutadot@next
or
-
npm install immutadot@next
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. immutadâ—Źt uses the dot notation to address this issue.
-
Interoperability
immutadâ—Źt 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
immutadâ—Źt comes with a large set of built-in utilities, mostly based on ES2015+. You can also find a package called immutadot-lodash with some of lodash's utilities. You haven't found what you're looking for? Do it yourself with the convert feature.
-
Learning curve
If you are already familiar with ES2015+ and lodash then you should be able to use immutadâ—Źt quickly.
We reused a simple benchmark originally made by mweststrate for immer.
-It updates 10.000 items out of list of 100.000 todos items, these tests were ran with Node 8.4.0 on an Intel® Core™ i7-6560U CPU @ 2.20GHz:
-
Update todos list
- âś“ with mutation (2ms)
- âś“ with deep cloning, then mutation (689ms)
- âś“ with ES2015 destructuring (42ms)
- âś“ with immutable (w/o conversion to plain JS objects) (50ms)
- âś“ with immutable (w/ conversion to plain JS objects) (1011ms)
- âś“ with immer (proxy implementation w/o autofreeze) (259ms)
- âś“ with immutadâ—Źt (77ms)
When applying operations on a path immutadâ—Źt tries to create the minimum of objects or arrays needed to guarantee your data structure to be immutable.
-
Documentation
Latest API documentation for our different packages are available here:
Looking for older versions API documentation? Links are available here.
+
Migrating from 0.x versions
If you were using a version of immutadâ—Źt previous to 1.0, check out the migrating guide.
+
Performances
A simple benchmark (freely inspired from one made by mweststrate for immer) reveals that immutadâ—Źt shows good results compared to other libraries.
+
:warning: The following results should be taken with caution, they may vary depending on the hardware, the JavaScript engine, and the kind of operations performed. This particular test updates 10% out of a list of todos items, and was ran with Node 9.3.0 on an Intel® Core™ i7-6560U CPU @ 2.20GHz.
+
Update small todos list (1000 items):
+ ES2015 destructuring: ~16961ops/s (0.06ms/op) on 50000ops
+ immutable 3.8.2 (w/o conversion to plain JS objects): ~6538ops/s (0.15ms/op) on 50000ops
+ immutable 3.8.2 (w/ conversion to plain JS objects): ~106ops/s (9.43ms/op) on 3195ops
+ immer 0.8.1 (proxy implementation w/o autofreeze): ~2191ops/s (0.46ms/op) on 50000ops
+ immer 0.8.1 (ES5 implementation w/o autofreeze): ~494ops/s (2.02ms/op) on 14827ops
+ immutadâ—Źt 1.0.0: ~2431ops/s (0.41ms/op) on 50000ops
+Update medium todos list (10000 items):
+ ES2015 destructuring: ~1781ops/s (0.56ms/op) on 5000ops
+ immutable 3.8.2 (w/o conversion to plain JS objects): ~587ops/s (1.70ms/op) on 5000ops
+ immutable 3.8.2 (w/ conversion to plain JS objects): ~10ops/s (100.80ms/op) on 299ops
+ immer 0.8.1 (proxy implementation w/o autofreeze): ~185ops/s (5.42ms/op) on 5000ops
+ immer 0.8.1 (ES5 implementation w/o autofreeze): ~47ops/s (21.21ms/op) on 1415ops
+ immutadâ—Źt 1.0.0: ~245ops/s (4.08ms/op) on 5000ops
+Update large todos list (100000 items):
+ ES2015 destructuring: ~116ops/s (8.61ms/op) on 500ops
+ immutable 3.8.2 (w/o conversion to plain JS objects): ~56ops/s (17.95ms/op) on 500ops
+ immutable 3.8.2 (w/ conversion to plain JS objects): ~1ops/s (1052.45ms/op) on 29ops
+ immer 0.8.1 (proxy implementation w/o autofreeze): ~21ops/s (47.81ms/op) on 500ops
+ immer 0.8.1 (ES5 implementation w/o autofreeze): ~4ops/s (275.59ms/op) on 110ops
+ immutadâ—Źt 1.0.0: ~23ops/s (44.15ms/op) on 500ops
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. immutadâ—Źt uses the dot notation to address this issue.
+
Interoperability
immutadâ—Źt 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
immutadâ—Źt comes with a large set of built-in utilities, mostly based on ES2015+. You can also find a package called immutadot-lodash with some of lodash's utilities. You haven't found what you're looking for? Do it yourself with the convert feature.
+
Learning curve
If you are already familiar with ES2015+ and lodash then you should be able to use immutadâ—Źt quickly.
Contributing
We want contributing to immutadâ—Źt to be fun, enjoyable, and educational for anyone, and everyone.
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.
* Replaces by an object assigning own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to <code>undefined</code>.<br >
* Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.
* @function
* @memberof object
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {...Object} [sources] The source objects.
* Replaces by an object assigning own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to <code>undefined</code>.<br >
* Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.
* @function
* @memberof object
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {...Object} [sources] The source objects.
* Replaces by an object with the same values as the former object and values generated by running each own enumerable string keyed property of the former object thru <code>iteratee</code>.
* The iteratee is invoked with three arguments: (value, key, object).
* @function
* @memberof object
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {function} [iteratee={@link https://lodash.com/docs#identity|lodash.identity}] The function invoked per iteration.
* @see {@link https://lodash.com/docs#mapKeys|lodash.mapKeys} for more information.
* @since 1.0.0
*/
const mapKeys = convert(_mapKeys)
export { mapKeys }
+
import { mapKeys as _mapKeys } from'lodash'
import { convert } from'immutadot'
/**
* Replaces by an object with the same values as the former object and values generated by running each own enumerable string keyed property of the former object thru <code>iteratee</code>.
* The iteratee is invoked with three arguments: (value, key, object).
* @function
* @memberof object
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {function} [iteratee={@link https://lodash.com/docs#identity|lodash.identity}] The function invoked per iteration.
* Replaces by an object with the same keys as the former object and values generated by running each own enumerable string keyed property of object thru <code>iteratee</code>.
* The iteratee is invoked with three arguments: (value, key, object).
* @function
* @memberof object
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {function} [iteratee={@link https://lodash.com/docs#identity|lodash.identity}] The function invoked per iteration.
* @see {@link https://lodash.com/docs#mapValues|lodash.mapValues} for more information.
* @since 1.0.0
*/
const mapValues = convert(_mapValues)
export { mapValues }
+
import { mapValues as _mapValues } from'lodash'
import { convert } from'immutadot'
/**
* Replaces by an object with the same keys as the former object and values generated by running each own enumerable string keyed property of object thru <code>iteratee</code>.
* The iteratee is invoked with three arguments: (value, key, object).
* @function
* @memberof object
* @param {Object} object The object to modify.
* @param {Array|string} path The path of the property to set.
* @param {function} [iteratee={@link https://lodash.com/docs#identity|lodash.identity}] The function invoked per iteration.
+ Creates a function that will successively call all functions contained in args.
+Each function is called with the result of the previous one.
+Non functions args are tolerated and will be ignored.
+
- Successively calls fns.
-Each function is called with the result of the previous one.
-Falsey functions (null, undefined and false) are tolerated and will be skipped.
-
We are still writing the documentation, you can already find out about the updated API and our new package immutadot-lodash.
-
If you would like to try out 1.0 before its official release, install it with :
-
yarn add immutadot@next
or
-
npm install immutadot@next
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. immutadâ—Źt uses the dot notation to address this issue.
-
Interoperability
immutadâ—Źt 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
immutadâ—Źt comes with a large set of built-in utilities, mostly based on ES2015+. You can also find a package called immutadot-lodash with some of lodash's utilities. You haven't found what you're looking for? Do it yourself with the convert feature.
-
Learning curve
If you are already familiar with ES2015+ and lodash then you should be able to use immutadâ—Źt quickly.
We reused a simple benchmark originally made by mweststrate for immer.
-It updates 10.000 items out of list of 100.000 todos items, these tests were ran with Node 8.4.0 on an Intel® Core™ i7-6560U CPU @ 2.20GHz:
-
Update todos list
- âś“ with mutation (2ms)
- âś“ with deep cloning, then mutation (689ms)
- âś“ with ES2015 destructuring (42ms)
- âś“ with immutable (w/o conversion to plain JS objects) (50ms)
- âś“ with immutable (w/ conversion to plain JS objects) (1011ms)
- âś“ with immer (proxy implementation w/o autofreeze) (259ms)
- âś“ with immutadâ—Źt (77ms)
When applying operations on a path immutadâ—Źt tries to create the minimum of objects or arrays needed to guarantee your data structure to be immutable.
-
Documentation
Latest API documentation for our different packages are available here:
Looking for older versions API documentation? Links are available here.
+
Migrating from 0.x versions
If you were using a version of immutadâ—Źt previous to 1.0, check out the migrating guide.
+
Performances
A simple benchmark (freely inspired from one made by mweststrate for immer) reveals that immutadâ—Źt shows good results compared to other libraries.
+
:warning: The following results should be taken with caution, they may vary depending on the hardware, the JavaScript engine, and the kind of operations performed. This particular test updates 10% out of a list of todos items, and was ran with Node 9.3.0 on an Intel® Core™ i7-6560U CPU @ 2.20GHz.
+
Update small todos list (1000 items):
+ ES2015 destructuring: ~16961ops/s (0.06ms/op) on 50000ops
+ immutable 3.8.2 (w/o conversion to plain JS objects): ~6538ops/s (0.15ms/op) on 50000ops
+ immutable 3.8.2 (w/ conversion to plain JS objects): ~106ops/s (9.43ms/op) on 3195ops
+ immer 0.8.1 (proxy implementation w/o autofreeze): ~2191ops/s (0.46ms/op) on 50000ops
+ immer 0.8.1 (ES5 implementation w/o autofreeze): ~494ops/s (2.02ms/op) on 14827ops
+ immutadâ—Źt 1.0.0: ~2431ops/s (0.41ms/op) on 50000ops
+Update medium todos list (10000 items):
+ ES2015 destructuring: ~1781ops/s (0.56ms/op) on 5000ops
+ immutable 3.8.2 (w/o conversion to plain JS objects): ~587ops/s (1.70ms/op) on 5000ops
+ immutable 3.8.2 (w/ conversion to plain JS objects): ~10ops/s (100.80ms/op) on 299ops
+ immer 0.8.1 (proxy implementation w/o autofreeze): ~185ops/s (5.42ms/op) on 5000ops
+ immer 0.8.1 (ES5 implementation w/o autofreeze): ~47ops/s (21.21ms/op) on 1415ops
+ immutadâ—Źt 1.0.0: ~245ops/s (4.08ms/op) on 5000ops
+Update large todos list (100000 items):
+ ES2015 destructuring: ~116ops/s (8.61ms/op) on 500ops
+ immutable 3.8.2 (w/o conversion to plain JS objects): ~56ops/s (17.95ms/op) on 500ops
+ immutable 3.8.2 (w/ conversion to plain JS objects): ~1ops/s (1052.45ms/op) on 29ops
+ immer 0.8.1 (proxy implementation w/o autofreeze): ~21ops/s (47.81ms/op) on 500ops
+ immer 0.8.1 (ES5 implementation w/o autofreeze): ~4ops/s (275.59ms/op) on 110ops
+ immutadâ—Źt 1.0.0: ~23ops/s (44.15ms/op) on 500ops
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. immutadâ—Źt uses the dot notation to address this issue.
+
Interoperability
immutadâ—Źt 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
immutadâ—Źt comes with a large set of built-in utilities, mostly based on ES2015+. You can also find a package called immutadot-lodash with some of lodash's utilities. You haven't found what you're looking for? Do it yourself with the convert feature.
+
Learning curve
If you are already familiar with ES2015+ and lodash then you should be able to use immutadâ—Źt quickly.
Contributing
We want contributing to immutadâ—Źt to be fun, enjoyable, and educational for anyone, and everyone.
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.
- Converts arg to a path represented as an array of keys.
-arg may be a string, in which case it will be parsed.
-It may also be an Array, in which case a copy of the array with values converted to path keys will be returned.
-If arg is neither a string nor an Array, its string representation will be parsed.
-
