Nebulous Pumpkin Moons

    with-mutations

    1.0.1 • Public • Published

    A simple function to mutate basic JavaScript variables in an immutable fashion

    npm version Build Status

    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

    Install

    npm i with-mutations

    DownloadsWeekly Downloads

    0

    Version

    1.0.1

    License

    MIT

    Last publish

    Collaborators

    • jharris4