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
