with-mutations
v1.0.1
Published
a lightweight function for treating simple javascript variables as immutable
Downloads
1
Maintainers
Readme
A simple function to mutate basic JavaScript variables in an immutable fashion
This package provides a getWithMutations(oldValue, newValue)
function that returns the oldValue
when the values are equal, or returns the newValue
when the values are different.
It operates recursively on objects or arrays, preserving nested value equality whenever possible.
Installation
Install the plugin with npm:
$ npm install --save with-mutations
Basic Usage
Mutating two equal values:
import getWithMutations from 'with-mutations';
const oldValue = { a: 1 };
const newValue = { a: 1 };
const result = getWithMutations(oldValue, newValue);
console.log(result === oldValue); // true
console.log(result === newValue); // false
Mutating two different values with some overlap:
import getWithMutations from 'with-mutations';
const oldValue = [ { a: 1 }, { b: 1 } ];
const newValue = [ { a: 1 }, { b: 2 } ];
const result = getWithMutations(oldValue, newValue);
console.log(result === oldValue); // false
console.log(result === newValue); // false
console.log(result[0] === oldValue[0]); // true
console.log(result[1] === oldValue[1]); // false
console.log(result[0] === newValue[0]); // false
console.log(result[1] === newValue[1]); // true
Custom mutatators
The getWithMutations
function takes an optional third argument which is the custom mutator.
The customMutator
should be a function which takes the oldValue and newValue as arguments and returns the result.
Note that the custom mutator is only executed if all of the following are true:
- Neither of the values are null or undefined
- The values are not identical references or primitive values
- The values are not both arrays or objects
import getWithMutations from 'with-mutations';
const oldValue = () => { };
const newValue = () => { };
oldValue.prop = 'a';
newValue.prop = 'a';
const customMutator = (oldValue, newValue) => oldValue.prop === newValue.prop ? oldValue : newValue;
const result = getWithMutations(oldValue, newValue, customMutator)
console.log(result === oldValue); // true
console.log(result === newValue); // false