object-path-immutable
    TypeScript icon, indicating that this package has built-in type declarations

    4.1.2 • Public • Published

    build coverage downloads version deps devdeps

    object-path-immutable

    Tiny JS library to modify deep object properties without modifying the original object (immutability). Works great with React (especially when using setState()) and Redux (inside a reducer).

    This can be seen as a simpler and more intuitive alternative to the React Immutability Helpers and Immutable.js.

    Changelog

    View Changelog

    Install

    npm install object-path-immutable --save
    

    Quick usage

    The following, sets a property without modifying the original object. It will minimize the number of clones down the line. The resulting object is just a plain JS object literal, so be warned that it will not be protected against property mutations (like Immutable.js)

    const obj = {
      a: {
        b: 'c',
        c: ['d', 'f']
      }
    }
    
    const newObj = immutable.set(obj, 'a.b', 'f')
    // {
    //   a: {
    //     b: 'f',
    //     c: ['d', 'f']
    //   }
    // }
    
    // obj !== newObj
    // obj.a !== newObj.a
    // obj.a.b !== newObj.a.b
    
    // However:
    // obj.a.c === newObj.a.c

    Wrap mode

    You can also chain the api's and call value() at the end to retrieve the resulting object.

    const newObj = immutable.wrap(obj).set('a.b', 'f').del('a.c.0').value()

    API

    // Premises
    
    const obj = {
      a: {
        b: 'c',
        c: ['d', 'f']
      }
    }
    
    import * as immutable from 'object-path-immutable'

    set (initialObject, path, value)

    Changes an object property.

    • Path can be either a string or an array.
    const newObj1 = immutable.set(obj, 'a.b', 'f')
    const newObj2 = immutable.set(obj, ['a', 'b'], 'f')
    
    // {
    //   a: {
    //     b: 'f',
    //     c: ['d', 'f']
    //   }
    // }
    
    // Note that if the path is specified as a string, numbers are automatically interpreted as array indexes.
    
    const newObj = immutable.set(obj, 'a.c.1', 'fooo')
    // {
    //   a: {
    //     b: 'f',
    //     c: ['d', 'fooo']
    //   }
    // }

    update (initialObject, path, updater)

    Updates an object property.

    const obj = {
      a: {
        b: 1
      }
    }
    
    const newObj = immutable.update(obj, ['a', 'b'], v => v + 1)
    
    // {
    //   a: {
    //     b: 2,
    //   }
    // }

    push (initialObject, path, value)

    Push into a deep array (it will create intermediate objects/arrays if necessary).

    const newObj = immutable.push(obj, 'a.d', 'f')
    // {
    //   a: {
    //     b: 'f',
    //     c: ['d', 'f'],
    //     d: ['f']
    //   }
    // }

    del (initialObject, path)

    Deletes a property.

    const newObj = immutable.del(obj, 'a.c')
    // {
    //   a: {
    //     b: 'f'
    //   }
    // }

    Can also delete a deep array item using splice

    const newObj = immutable.del(obj, 'a.c.0')
    // {
    //   a: {
    //     b: 'f',
    //     c: ['f']
    //   }
    // }

    assign (initialObject, path, payload)

    Shallow copy properties.

    const newObj = immutable.assign(obj, 'a', { b: 'f', g: 'h' })
    // {
    //   a: {
    //     b: 'f',
    //     c: ['d, 'f'],
    //     g: 'h'
    //   }
    // }

    insert (initialObject, path, payload, position)

    Insert property at the specific array index.

    const newObj = immutable.insert(obj, 'a.c', 'k', 1)
    // var obj = {
    //   a: {
    //     b: 'c',
    //     c: ['d, 'k' 'f'],
    //   }
    // }

    merge (initialObject, path, value)

    Deep merge properties.

    const newObj = immutable.merge(obj, 'a.c', {b: 'd'})

    Getters (not available in wrap mode)

    get (object, path, defaultValue)

    Retrieve a deep object property. Imported from object-path for convenience.

    Equivalent library with side effects

    object-path

    Install

    npm i object-path-immutable

    DownloadsWeekly Downloads

    56,136

    Version

    4.1.2

    License

    MIT

    Unpacked Size

    65.1 kB

    Total Files

    13

    Last publish

    Collaborators

    • mariocasciaro