# web-storage-object

> API providing 2 way binding of JavaScript objects to browser WebStorage

Latest version **1.0.5** (published 2019-02-09) · MIT license · 0 weekly downloads

## Install

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

## 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 | 1.0.5 |
| Published | 2019-02-09 |
| First published | 2018-07-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 29.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Ante Baric |
| Maintainers | capjavert |
| Keywords | webstorage, localstorage, sessionstorage, persistence |

## Links

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

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 1.0.5 (latest) — 2019-02-09
- 1.0.3 — 2018-08-02
- 1.0.2 — 2018-07-30
- 1.0.0 — 2018-07-29

## README

# WebStorage object API
API providing 2 way binding of JavaScript objects to browser WebStorage
API consists of two mechanisms, each is used to bind and persist any JavaScript object to specific WebStorage type:
- LocalStorageObject -> localStorage
- SessionStorageObject -> sessionStorage

## Getting started
Include with script tag:
```
<script src="dist/web-storage-object.min.js"></script>
```
or if you prefer NPM:
```
npm install web-storage-object
```
and include as:
```
import {LocalStorageObject, SessionStorageObject} from 'web-storage-object'
```

## Examples
### Basic usage
Given the simple object representing our data we can use the API like this:
```
var heroModel = {
  name: 'Ogox',
  weapon: 'Axe',
  horse: true,
  armor: {
    head: 'Steel Helmet',
    body: 'Rags',
    boots: 'Wraps'
  }
}
var ogox = new LocalStorageObject(heroModel, 'ogox')
```
Now if you check localStorage inside dev tools of your browser you will see:

![Chrome DevTools showcase](https://i.imgur.com/8A3r8Nl.png "Chrome DevTools")

Now if we modify any ogox ~~weapon~~ property, lets say like this:
```
ogox.weapon = 'Heavy Axe'
```
The changes will be automatically persistant and changed inside localStorage. You can check your dev tools again. Also if you do:
```
console.log(ogox)
console.log(ogox.weapon)
```
As you can see it behaves just as any other object except with help of JavaScript Proxy object changes are saved and fetched from WebStorage.

### Use sessionStorage
To use sessionStorage call the SessionStorageObject constructor.
```
var ogox = new SessionStorageObject(heroModel, 'ogox')
```

### Nested objects
It also works out of the box with nested object properties like:
```
ogox.armor.body = 'Heavy Armor' // updates property inside browser storage
```

### Just like any JavaScript object
You can define new properties just like with any JS object:
```
ogox.armor.hands = 'Shoulder Plates'
ogox.level = 42
```

### It also supports arrays and key => value syntax
```
ogox.items = [
  'carrot',
  'spoon',
  'rotten meat'
]
console.log(ogox.items[1]) // prints 'spoon' to console
```

### Handling data already written inside browser storage
Let's say you already have some data for the given key saved to storage and you just want to load that. You can do it like this:
```
var ogox = new LocalStorageObject({}, 'ogox', false) // overwrite flag set to false
```
If overwrite flag is set to false and no data exists in Storage then in this case constructor would return empty LocalStorageObject object.

### Delete properties
You can use delete operator to delete properties, this will delete property and sync webStorage:
```
delete ogox.armor.hands
delete ogox.level
```

## Build your own
You can use files inside /dist folder or build your own.
```
$ git clone https://github.com/capJavert/web-storage-object.git
$ web-storage-object
$ npm install
```
Build scripts are:
```
$ npm run build
```
or minified version:
```
$ npm run build_prod
```

## TODO
* ~~Nested objects support~~
* ~~Array support~~ - Solved by adding nested object support, JS arrays are objects with special behaviour and Proxy handles them the same way
* ~~Nested Array support~~ - Solved with previous point
* ~~abstract to WebStorageObject and provide SessionStorageObject and LocalStorageObject~~
* ~~Add support for delete operator~~
* ~~Add support for Object.hasOwnProperty~~

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