# object-state-storage

> Local state storage for javascript apps

Latest version **3.3.1** (published 2017-12-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install object-state-storage
pnpm add object-state-storage
yarn add object-state-storage
bun add object-state-storage
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.3.1 |
| Published | 2017-12-03 |
| First published | 2016-06-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Vadim K. |
| Maintainers | vadirn |
| Keywords | state, storage |

## Links

- npm: https://www.npmjs.com/package/object-state-storage
- Repository: https://github.com/vadirn/object-state-storage
- Homepage: https://github.com/vadirn/object-state-storage#readme
- Issues: https://github.com/vadirn/object-state-storage/issues
- npm.io page: https://npm.io/package/object-state-storage

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

- 3.3.1 (latest) — 2017-12-03
- 3.3.0 — 2017-10-22
- 3.2.1 — 2017-10-18
- 3.2.0 — 2017-09-28
- 3.1.0 — 2017-06-20
- 2.0.6 — 2017-03-16
- 2.0.5 — 2017-03-13
- 2.0.4 — 2017-03-12
- 2.0.3 — 2017-03-11
- 2.0.2 — 2016-12-18
- 2.0.1 — 2016-12-05
- 2.0.0 — 2016-12-03
- 1.0.4 — 2016-09-13
- 1.0.1 — 2016-08-19
- 1.0.0 — 2016-08-19
- … 4 more at https://npm.io/package/object-state-storage/versions

## README

**Object State Storage** is a tiny state container written in es6.

Install with `npm install --save object-state-storage` or `yarn add object-state-storage`. Note that no compiled version is provided. So if you are using webpack and babel, you might want to explicitly include object-state-storage in babel-loader rule.

## API
- `const store = new ObjectStateStorage([initialState: Object])` - create new storage with optional initial state.
- `const unsubscribe = store.subscribe(listener: (currentState, prevState, label) => {})` - subscribe to state changes, returns unsubscribe function. `label` might be useful for debugging.
- `store.setState(modifier: Object or ([currentState]) => Object, [label])` - recursively merges current state and modifier object. If modifier is a function, it might take currentState as an argument and return an Object, that is going to be merged into current state. Merge function can be reused: `import { merge } from 'object-state-storage'`. If modification results in null or undefined, nothing happens and subscribers are not called.
- `store.resetState(newState: Object or ([currentState]) => Object, [label])` - replaces current state with provided newState Object. If newState is a function, it might take currentState as an argument and return an Object, that is going to replace current state. If modification results in null or undefined, nothing happens and subscribers are not called.
- `store.state` - returns cloned state. Clone function is available via `import { clone } from 'object-state-storage'`

## Example

```javascript
import ObjectStateStorage from 'object-state-storage';
import { merge, clone } from 'object-state-storage';

// create a storage unit with initial value { foo: 'bar' }
const store = new ObjectStateStorage({ foo: 'bar' });

// subscribe to store updates
const unsubscribe = store.subscribe((curState, prevState) => {
  // log previous state and current state
  console.log(curState, prevState);
  // unsubscribe
  unsubscribe();
});

// update the state (merges current state and provided object)
// expect to see in console { foo: 'bar' } and { foo: 'bar', bar: 'foo' }
store.setState({ bar: 'foo' });

// log current state after store was updated
// expect the following object to be in console.log
// {
//   foo: 'bar',
//   bar: 'foo',
// }
console.log(store.state);

// resets the state (replaces current state and provided object)
store.resetState({ foobar: 'foobar' });

// expect to see { foobar: 'foobar' } in console
console.log(store.state);

// immutable merge, used in setState:
const mergeExample = { foo: 'bar' };
const mergeResult = merge(mergeExample, { bar: 'foo' });

// expect { foo: 'bar' }
console.log(mergeExample);
// expect { foo: 'bar', bar: 'foo' }
console.log(mergeResult);

// clone:
const cloneExample = { foo: 'bar' };
const cloneResult = clone(cloneExample);
cloneExample.bar = 'foo';

// expect { foo: 'bar', bar: 'foo' }
console.log(cloneExample);
// expect { foo: 'bar' }
console.log(cloneResult);

```

## Note

I've previously written, that this state container is based on Redux, but without reducers and other related things. After reading comments to [this publication](https://news.ycombinator.com/item?id=15519059) on hacker news I decided that it might be a bit misleading.

This library is not a replacement for Redux, but can be a good alternative if you can live without benefits of message-passing system and you don't want to repeat everything three times, an action type constant, the action type creator function, and the reducer ([reference tweet](https://twitter.com/modernserf/status/884882364379385858)).

More links on understanding Redux:
- [What’s So Great About Redux?](https://medium.freecodecamp.org/whats-so-great-about-redux-ac16f1cc0f8b)
- [Redux Pros, Cons, and Limitations](https://storify.com/acemarke/redux-pros-cons-and-limitations)
- [https://twitter.com/modernserf/status/886426115874717697](https://twitter.com/modernserf/status/886426115874717697)
- [Idiomatic Redux: The Tao of Redux, Part 1 - Implementation and Intent](http://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-1/)
- [Idiomatic Redux: The Tao of Redux, Part 2 - Practice and Philosophy](http://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-2/)

When using object-state-storage with React it's better to put business logic into separate functions (actions) and only modify store state there (to inject those in components, you might want to use something like [components-di](https://github.com/vadirn/components-di)). Actions combine reducers and action creators (redux) into a single function. I guess testing actions might be treated as integration tests, as they are not pure functions and have side-effects.

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