# perfect-immutable

> Library to provide immutable methods (like immutable set similar to lodash's _.set) on standard JS objects

Latest version **3.0.0** (published 2021-06-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install perfect-immutable
pnpm add perfect-immutable
yarn add perfect-immutable
bun add perfect-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 | 3.0.0 |
| Published | 2021-06-05 |
| First published | 2017-12-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 558.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Łukasz Pluszczewski |
| Maintainers | dyoda |
| Keywords | immutable, javascript, plain-object |

## Links

- npm: https://www.npmjs.com/package/perfect-immutable
- Repository: https://github.com/Lukasz-pluszczewski/perfect-immutable
- Issues: https://github.com/Lukasz-pluszczewski/perfect-immutable/issues
- npm.io page: https://npm.io/package/perfect-immutable

## Dependencies (1)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21

## Alternatives

- [@lexical/table](https://npm.io/package/@lexical/table.md) — 3.0M weekly downloads
- [mantine-datatable](https://npm.io/package/mantine-datatable.md) — 98.2K weekly downloads
- [react-native-collapsible-tab-view](https://npm.io/package/react-native-collapsible-tab-view.md) — 70.6K weekly downloads
- [@handsontable/vue3](https://npm.io/package/@handsontable/vue3.md) — 16.1K weekly downloads
- [vuewordcloud](https://npm.io/package/vuewordcloud.md) — 7.2K weekly downloads

## Recent versions

- 3.0.0 (latest) — 2021-06-05
- 3.0.0-rc.4 — 2021-06-05
- 3.0.0-rc.3 — 2021-06-05
- 3.0.0-rc.2 — 2021-06-05
- 3.0.0-rc.1 — 2021-06-05
- 3.0.0-rc.0 — 2021-06-05
- 2.0.2 — 2019-01-13
- 2.0.1 — 2018-12-08
- 2.0.0 — 2018-12-06
- 1.5.0 — 2018-01-28
- 1.4.2 — 2018-01-22
- 1.4.1 — 2018-01-21
- 1.4.0 — 2018-01-19
- 1.3.0 — 2017-12-15
- 1.2.0 — 2017-12-14
- … 3 more at https://npm.io/package/perfect-immutable/versions

## README

# perfect-immutable
> Library to provide immutable methods (like immutable set similar to lodash's _.set) on standard JS objects

[![CircleCI](https://circleci.com/gh/Lukasz-pluszczewski/perfect-immutable.svg?style=svg)](https://circleci.com/gh/Lukasz-pluszczewski/perfect-immutable)
[![codecov](https://codecov.io/gh/Lukasz-pluszczewski/perfect-immutable/branch/master/graph/badge.svg?token=C9X4HFFPVO)](https://codecov.io/gh/Lukasz-pluszczewski/perfect-immutable)

You're smart. You avoid mutating objects in your application. But you don't want to install big Immutable.js library and you don't want to refactor all your objects. Now you can have benefits of Immutable.js on normal JavaScript objects! Look for [real life exampes](docs/EXAMPLES.md).

## Getting started
##### Install library
`npm i perfect-immutable --save`

##### Import functions you need
```javascript
import { set, splice, push, pop, shift, unshift, sort, reverse, filter, immutableDelete } from 'perfect-immutable';
import immutable from 'perfect-immutable'; // immutable object has all above methods
```
or, for functional programming friendly, auto-carried, predicate-first functions
```javascript
import { set, splice, push, pop, shift, unshift, sort, reverse, filter, immutableDelete } from 'perfect-immutable/fp';
import immutable from 'perfect-immutable/fp'; // immutable object has all above methods
```

## Docs
- [API](docs/API.md)
- [Examples](docs/EXAMPLES.md)
- [FP examples](docs/EXAMPLESFP.md)
- [Changelog](docs/CHANGELOG.md)

## Credits
1. stringToPath function (used e.g. in set method) is based on lodash's function with the same name (also used in `_.set()`)
2. immutable array functions (like splice) were created by [Vincent Billey](https://vincent.billey.me/)
3. [Brainhub](https://brainhub.eu/) created [eslint config](https://github.com/adam-golab/eslint-config-brainhub) used in this repo

## FAQ
#### Why this exists?
There are a lot of Immutable.js-like libraries, but they all force you to use immutable specific objects (like Map) and you cannot use their methods on normal JavaScript objects. That's not a problem when you're starting new project and decide to use e.g. Immutable.js but what if the app is already there, and you want immutable tools?

#### Are there good alternatives?
- [immutability-helper](https://github.com/kolodny/immutability-helper) - Library based on react-addons-update, that solve exactly the same problem but with mongodb-like syntax instead of lodash or Immutable.js-like syntax. Definitely worth giving it a try. However, this library provides you with different syntax and allows you to use all helper methods (like immutable push) separately with more functional approach.

#### I found a bug! What should I do?
There are at least 3 options:
1. Add an issue, write test(s) for bug you found, write fix that will make your test(s) pass, submit pull request
2. Add an issue, write test(s) for bug you found, submit pull request with you test(s)
3. Add an issue

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