Skip to content
Modify deep object properties without modifying the original object (immutability). Works great with React and Redux.
JavaScript
Branch: master
Clone or download
Latest commit ef686f0 Sep 26, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cjs Fixes and improvements after the conversion to ESM Sep 20, 2019
esm
src Fixes and improvements after the conversion to ESM Sep 20, 2019
test Fixes and improvements after the conversion to ESM Sep 20, 2019
umd Fixes and improvements after the conversion to ESM Sep 20, 2019
.gitignore Replace instanbul with nyc Jun 27, 2019
.travis.yml Replace instanbul with nyc Jun 27, 2019
CHANGELOG.md
LICENSE
README.md Update Readme with the new wrap function Sep 20, 2019
object-path-immutable.d.ts (#35) Typescript definitions incorrectly list default export Sep 26, 2019
package-lock.json 4.0.2 Sep 26, 2019
package.json 4.0.2 Sep 26, 2019
rollup.config.js Fix styling issue Sep 20, 2019

README.md

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.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.wrap(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']
//   }
// }

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'})

Equivalent library with side effects

object-path

You can’t perform that action at this time.