# object-path-immutable

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

Latest version **4.1.2** (published 2021-09-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install object-path-immutable
pnpm add object-path-immutable
yarn add object-path-immutable
bun add object-path-immutable
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.2 |
| Published | 2021-09-16 |
| First published | 2015-12-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=0.10.0 |
| Dependencies | 2 |
| Unpacked size | 63.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 411 |
| Author | Mario Casciaro |
| Maintainers | mariocasciaro |
| Keywords | deep, path, access, get, property, dot, prop, object, obj, notation, segment, value, nested, key, immutable, immutability, react, redux, state |

## Links

- npm: https://www.npmjs.com/package/object-path-immutable
- Repository: https://github.com/mariocasciaro/object-path-immutable
- Issues: https://github.com/mariocasciaro/object-path-immutable/issues
- npm.io page: https://npm.io/package/object-path-immutable

## Dependencies (2)

- [object-path](https://npm.io/package/object-path.md) ^0.11.8
- [is-plain-object](https://npm.io/package/is-plain-object.md) ^5.0.0

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 4.1.2 (latest) — 2021-09-16
- 4.1.1 — 2020-10-20
- 4.1.0 — 2020-01-27
- 4.0.2 — 2019-09-26
- 4.0.1 — 2019-09-20
- 4.0.0 — 2019-09-20
- 3.1.1 — 2019-06-27
- 3.1.0 — 2019-06-27
- 3.0.2 — 2019-03-19
- 3.0.0 — 2018-06-21
- 2.0.0 — 2018-06-21
- 1.0.3 — 2018-06-19
- 1.0.2 — 2018-05-08
- 1.0.1 — 2018-02-08
- 1.0.0 — 2018-02-08
- … 8 more at https://npm.io/package/object-path-immutable/versions

## README

[![build](https://img.shields.io/travis/mariocasciaro/object-path-immutable.svg?style=flat-square)](https://travis-ci.org/mariocasciaro/object-path-immutable)
[![coverage](https://img.shields.io/coveralls/mariocasciaro/object-path-immutable.svg?style=flat-square)](https://coveralls.io/r/mariocasciaro/object-path-immutable)
[![downloads](https://img.shields.io/npm/dm/object-path-immutable.svg?style=flat-square)](https://www.npmjs.com/package/object-path-immutable)
[![version](https://img.shields.io/npm/v/object-path-immutable.svg?style=flat-square)](https://www.npmjs.com/package/object-path-immutable)
[![deps](https://img.shields.io/david/mariocasciaro/object-path-immutable.svg?style=flat-square)](https://david-dm.org/mariocasciaro/object-path-immutable)
[![devdeps](https://img.shields.io/david/dev/mariocasciaro/object-path-immutable.svg?style=flat-square)](https://david-dm.org/mariocasciaro/object-path-immutable#info=devDependencies)

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](CHANGELOG.md)

## 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`)

```javascript
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.

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

## API

```javascript
// 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.

```javascript
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.

```javascript
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).

```javascript
const newObj = immutable.push(obj, 'a.d', 'f')
// {
//   a: {
//     b: 'f',
//     c: ['d', 'f'],
//     d: ['f']
//   }
// }
```

#### del (initialObject, path)

Deletes a property.

```javascript
const newObj = immutable.del(obj, 'a.c')
// {
//   a: {
//     b: 'f'
//   }
// }
```

Can also delete a deep array item using splice

```javascript
const newObj = immutable.del(obj, 'a.c.0')
// {
//   a: {
//     b: 'f',
//     c: ['f']
//   }
// }
```

#### assign (initialObject, path, payload)

Shallow copy properties.

```javascript
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.

```javascript
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.

```javascript
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](https://github.com/mariocasciaro/object-path) for convenience.

## Equivalent library with side effects

[object-path](https://github.com/mariocasciaro/object-path)

---
_Source: https://npm.io/package/object-path-immutable · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._