# boxes

> Reactive state containers for js apps

Latest version **0.44.0** (published 2020-05-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install boxes
pnpm add boxes
yarn add boxes
bun add boxes
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.44.0 |
| Published | 2020-05-13 |
| First published | 2016-02-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 23.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Jacobo Tabernero - https://github.com/jacoborus |
| Maintainers | jacoborus |
| Keywords | reactive, state, containers |

## Links

- npm: https://www.npmjs.com/package/boxes
- Repository: https://github.com/jacoborus/boxes
- Issues: https://github.com/jacoborus/boxes/issues
- npm.io page: https://npm.io/package/boxes

## Dependencies (1)

- [weak-emitter](https://npm.io/package/weak-emitter.md) 5.2.1

## Alternatives

- [@reckona/mreact-store](https://npm.io/package/@reckona/mreact-store.md) — 976 weekly downloads
- [regular-state](https://npm.io/package/regular-state.md) — 410 weekly downloads
- [@pacote/flux-actions](https://npm.io/package/@pacote/flux-actions.md) — 65 weekly downloads
- [@pilotlab/lux-debug](https://npm.io/package/@pilotlab/lux-debug.md) — 39 weekly downloads
- [vue-persist-state](https://npm.io/package/vue-persist-state.md) — 19 weekly downloads

## Recent versions

- 0.44.0 (latest) — 2020-05-13
- 0.43.0 — 2020-05-13
- 0.42.0 — 2020-05-12
- 0.41.0 — 2020-04-15
- 0.40.0 — 2020-04-13
- 0.39.0 — 2020-04-10
- 0.38.0 — 2020-04-09
- 0.37.0 — 2020-03-23
- 0.36.0 — 2020-03-22
- 0.35.0 — 2020-03-22
- 0.34.0 — 2020-03-22
- 0.33.0 — 2020-03-22
- 0.32.0 — 2020-02-26
- 0.30.1 — 2020-02-21
- 0.30.0 — 2020-02-18
- … 47 more at https://npm.io/package/boxes/versions

## README

Boxes
=====

(Work in progress)

Reactive state containers focused on DOM performance

```js
import { getBox, on } from 'Boxes'

const origin = {
  a: 1
}

const box = getBox(origin)
box // { a: 1 }
box === origin // false

on(box, 'a', (...change) => console.log(change))
box.a = 'hello'
// logs: [{ a: 'hello' }, 'a', 'set', 1, 'hello']
```

## API

- getBox
- on
- off

### on(box, prop, handler)

Adds `handler` to box

```js
const box = getBox({ a: 1 })
const handler = (...change) => console.log(change)
boxes.on(box, 'a', handler)

box.a = 'hello'
// logs: [{ a: 'hello' }, 'a', 'set', 1, 'hello']
```

It also works with dot notation:

```js
const box = getBox({ o: { a: 1  } })
const handler = (...change) => console.log(change)
boxes.on(box, 'o.a', handler)

box.o.a = 'hello'
['set', 'a', 1, 'hello', { a: 'hello' }]

box.o = { a: 'bye' }
// logs: [{ a: 'bye' }, 'a', 'set', 'hello', 'bye']
```

### off(box, prop, handler)

Removes `handler` from the box

```js
boxes.off(box, 'propName', action)
```


## Emitter

Boxes will emit the changes made in the observed objects.

### Change signatures:

Generic signature: `[box, property, changeType, oldValue, newValue]`

Object:

- set:
  - signature: `[box, property, 'set', oldValue, newValue]`
  - on: literal assignation, Object.assign, ...
- delete:
  - signature: `[box, property, 'delete', oldValue, undefined]`
  - on: delete operator

Array:

- set:
  - signature: `[box, property, 'set', oldValue, newValue]`
  - on: copyWithin, fill, splice and literal assignation
- delete:
  - signature: `[box, property, 'delete', oldValue, undefined]`
  - on: delete operator
- insert:
  - signature: `[box, property, 'insert', undefined, newValue]`
  - on: push, splice, unshift
- remove:
  - signature: `[box, property, 'remove', oldValue, undefined]`
  - on: pop, shift, splice
- swap:
  - signature: `[box, property, 'swap', oldValue, newValue]`
  - on: reverse , sort
- length:
  - signature: `[box, firstIndexChanged || undefined, 'length',  oldLength, newLength]`
  - on: pop, push, shift, splice, unshift
  - `firstIndexChanged` will be passed only on shift, splice and unshift
    because on pop and push no index will change

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