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.

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)

1const obj = {
2  a: {
3    b: 'c',
4    c: ['d', 'f']
5  }
6}
7
8const newObj = immutable.set(obj, 'a.b', 'f')
9// {
10//   a: {
11//     b: 'f',
12//     c: ['d', 'f']
13//   }
14// }
15
16// obj !== newObj
17// obj.a !== newObj.a
18// obj.b !== newObj.b
19
20// However:
21// obj.c === newObj.c

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

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

API

1// Premises
2
3const obj = {
4  a: {
5    b: 'c',
6    c: ['d', 'f']
7  }
8}
9
10import immutable from 'object-path-immutable'

set (initialObject, path, value)

Changes an object property.

• Path can be either a string or an array.
• The value can be a function, allowing you to get the initial value of the property to do an update.

1const newObj1 = immutable.set(obj, 'a.b', 'f')
2const newObj2 = immutable.set(obj, ['a', 'b'], 'f')
3const newObj3 = immutable.set(obj, ['a', 'b'], v => 'f')
4
5// {
6//   a: {
7//     b: 'f',
8//     c: ['d', 'f']
9//   }
10// }
11
12// Note that if the path is specified as a string, numbers are automatically interpreted as array indexes.
13
14const newObj = immutable.set(obj, 'a.c.1', 'fooo')
15// {
16//   a: {
17//     b: 'f',
18//     c: ['d', 'fooo']
19//   }
20// }

push (initialObject, path, value)

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

1const newObj = immutable.push(obj, 'a.d', 'f')
2// {
3//   a: {
4//     b: 'f',
5//     c: ['d', 'f'],
6//     d: ['f']
7//   }
8// }

delete (initialObject, path)

Deletes a property.

1const newObj = immutable.del(obj, 'a.c')
2// {
3//   a: {
4//     b: 'f'
5//   }
6// }

Can also delete a deep array item using splice

1const newObj = immutable.del(obj, 'a.c.0')
2// {
3//   a: {
4//     b: 'f',
5//     c: ['f']
6//   }
7// }

assign (initialObject, path, payload)

Shallow copy properties.

1const newObj = immutable.assign(obj, 'a', { b: 'f', g: 'h' })
2// {
3//   a: {
4//     b: 'f',
5//     c: ['d, 'f'],
6//     g: 'h'
7//   }
8// }

Equivalent library with side effects

object-path

Credits

• Mario Casciaro - Author