object-path-immutable

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

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

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.b !== newObj.b

// However:
// obj.c === newObj.c

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

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

API

// Premises

const obj = {
  a: {
    b: 'c',
    c: ['d', 'f']
  }
}

import 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']
//   }
// }

delete (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'],
//   }
// }

Equivalent library with side effects

object-path

Credits

• Mario Casciaro - Author