Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

object-path-immutable

mariocasciaro187.9kMIT4.1.2TypeScript support: included

Modify deep object properties without modifying the original object (immutability). Works great with React and Redux.

deep, path, access, get, property, dot, prop, object, obj, notation, segment, value, nested, key, immutable, immutability, react, redux, state

readme

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

changelog

Changelog

4.0

  • Breaking change: the previous default export is now called wrap()
  • Possible breaking change: object-path-immutable now uses ES modules which means if you are in an ESM environment you will have to use named exports.

3.0

  • Possible breaking change merge not does not accept options anymore
  • Removed dependency on deepmerge

2.0

  • Possible breaking change The library now has dependencies and is building with Rollup, therefore the UMD entry point is now dist/object-path-immutable. If you are using this object-path-immutable with Node or another module bundler, this change should not affect you.
  • Added merge function

1.0

  • Breaking change: The way the library handles empty paths has changed. Before this change,all the methods were returning the original object. The new behavior is as follows.
    • set(src, path, value): value is returned
    • update(src, path, updater): value will be passed to updater() and the result returned
    • set(src, path, ...values): values will be concatenated to src if src is an array, otherwise values will be returned
    • insert(src, path, value, at): if src is an array then it will be cloned and value will be inserted at at, otherwise [value] will be returned
    • del(src, path): returns undefined
    • assign(src, path, target): Target is assigned to a clone of src and returned