# boxed-immutable

> Immutable proxy wrapper with exception free access to nested properties and auto-instantiation of intermediate containers when nested properties are defined

Latest version **0.8.10** (published 2020-04-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install boxed-immutable
pnpm add boxed-immutable
yarn add boxed-immutable
bun add boxed-immutable
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.8.10 |
| Published | 2020-04-05 |
| First published | 2018-04-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 210.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Vladimir Schneider |
| Maintainers | vsch |
| Keywords | immutable, min-object-delta, auto-vivification |

## Links

- npm: https://www.npmjs.com/package/boxed-immutable
- Repository: https://github.com/vsch/boxed-immutable
- Issues: https://github.com/vsch/boxed-immutable/issues
- npm.io page: https://npm.io/package/boxed-immutable

## Dependencies (7)

- [boxed-out](https://npm.io/package/boxed-out.md) ^0.1.8
- [for-each-break](https://npm.io/package/for-each-break.md) ^0.2.6
- [obj-each-break](https://npm.io/package/obj-each-break.md) ^0.1.14
- [lodash.isstring](https://npm.io/package/lodash.isstring.md) ^4.0.1
- [util-type-funcs](https://npm.io/package/util-type-funcs.md) ^0.2.12
- [util-string-wrap](https://npm.io/package/util-string-wrap.md) ^0.1.6
- [lodash.isfunction](https://npm.io/package/lodash.isfunction.md) ^3.0.9

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

- 0.8.10 (latest) — 2020-04-05
- 0.8.8 — 2020-04-05
- 0.8.6 — 2019-07-11
- 0.8.4 — 2019-03-05
- 0.8.2 — 2018-05-15
- 0.8.0 — 2018-05-14
- 0.7.2 — 2018-05-13
- 0.7.0 — 2018-05-13
- 0.5.8 — 2018-05-10
- 0.5.6 — 2018-05-09
- 0.5.4 — 2018-05-09
- 0.5.2 — 2018-05-09
- 0.5.0 — 2018-04-20
- 0.4.2 — 2018-04-15
- 0.4.0 — 2018-04-13
- … 14 more at https://npm.io/package/boxed-immutable/versions

## README

# boxed-immutable

[![experimental](https://badges.github.io/stability-badges/dist/experimental.svg)](https://github.com/badges/stability-badges)

:warning: Version 0.8.0 factored out boxed state implementation to its own module
[`boxed-state`](https://github.com/vsch/boxed-state/blob/master/README.md) with all exports not
implemented by `boxed-immutable` removed. All previous references need to be changed to specific
module name for the implementation.

:warning: Version 0.7.0 factored out implementation into separate modules and removed exports
for all except: `boxed-out` module implementing `boxOut` function. The rest need to be imported
from their corresponding modules:
[`util-string-wrap`](https://github.com/vsch/util-string-wrap/blob/master/README.md),
[`util-type-funcs`](https://github.com/vsch/util-type-funcs/blob/master/README.md),
[`for-each-break`](https://github.com/vsch/for-each-break/blob/master/README.md) or
[`obj-each-break`](https://github.com/vsch/obj-each-break/blob/master/README.md).

The API is evolving and will still change as its idiosyncrasies and limitations are discovered
in use. The **boxed-in** proxy is fairly stable but may add new magic properties and eventually
retire unused or little use properties. **boxed-out** proxy gained iteration helpers to mimic
ones available for arrays.

Immutable proxy wrapper with auto-vivification of intermediate objects/arrays with syntactic
sugar to keep access/modification to deeply nested properties looking almost the same as plain
object property access. Flexible data transforms to massage or validate the data on boxed state
creation or on property changes: [Transforms](../../wiki/Transforms)

1. Create a boxed-immutable object proxy from any value, including `undefined` then access
   and/or modify its direct and nested properties, without concern to whether intermediate
   values are objects/arrays or whether they exist. The final result will either reflect the
   value of an actual property or be undefined if any intermediate properties were undefined or
   invalid.

2. Modify any direct or nested properties without affecting the original object/array. It will
   be shallow copied on first modification of any property. All further modifications will be
   done on the copy.

3. Get the full modified array/object or just the changed properties to pass to state updater
   such as [Redux] `dispatch()` or [React] component's `setState()`.

## Install

Use [npm](https://npmjs.com/) to install.

```sh
npm install boxed-immutable --save
```

## Usage

[![NPM](https://nodei.co/npm/boxed-immutable.png)](https://www.npmjs.com/package/boxed-immutable)

The concept behind this module is to create a protective box around a value: to box it.

For values inside the box, all properties return a proxy that does the job of keeping immutable
originals intact, track modified properties, auto-vivify containers when properties are set and
provide magic properties.

Any value can be boxed, traversed several levels deep into its property tree and at any point
take that property value out of the box. All access from this point on to the property and its
nested properties is on regular JavaScript object properties. If any intermediate property
access was invalid, the value of the unboxed property will be `undefined`.

Some code to show how it all comes together. Each example will be a continuation of the code in
the previous example, unless it starts with the `require('boxed-immutable')`

```javascript
const _$ = require('boxed-immutable').box;

let state = {
    isLoaded: false,
    isLoading: false,
    appSettings: {
        title: "The Title",
    }
};

let state_$ = _$(state);
let dashboardName = "overview";
let showDashboard;
let title;

showDashboard = state_$.appSettings.dashboards[dashboardName].showDashboard(); // result is undefined
title = state_$.appSettings.title(); // result is "The Title"
```

Modifying properties is even easier because they can be set without unboxing. It might seem
easier just to bang away on the unboxed state object but then you will not get immutability
barrier, same value optimization, `TypeError` and `ReferenceError` protection and parent
container instantiation. The following is a no-op:

```javascript
state_$.isLoaded = false;
```

On the other hand the next line will cause the proxy to make a shallow copy of the boxed value
and then set its `isLoading` property to `true`.

```javascript
state_$.isLoading = true; // this will shallow copy the underlying object and set its property
```

Now for some fun examples that would not work with JavaScript objects:

```javascript
state_$.appSettings.dashboards[dashboardName].showDashboard = true;
state_$.appSettings.dashboards[dashboardName].dashboardTitle = "Overview";

let newState = state_$;
```

At this point `newState` will be the same as if you did:

```javascript
let newState = {
    isLoaded: false,
    isLoading: true,
    appSettings: {
        title: "The Title",
        dashboards: {
            overview: {
                showDashboard: true,
                dashboardTitle: "Overview",
            },
        },
    },
};
```

The rest of this file was moved to the wiki for greater leg room, [boxed-immutable wiki](../../wiki)

## License

MIT, see [LICENSE.md](https://github.com/vsch/boxed-immutable/blob/master/LICENSE.md) for
details.

[React]: https://reactjs.org
[Redux]: https://redux.js.org

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