# json-storage

> A wrapper for storage engines which use the W3C Storage API

Latest version **2.1.2** (published 2018-07-31) · 0 weekly downloads

## Install

```sh
npm install json-storage
pnpm add json-storage
yarn add json-storage
bun add json-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 | 2.1.2 |
| Published | 2018-07-31 |
| First published | 2011-09-07 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= v0.2.0 |
| Dependencies | 0 |
| Unpacked size | 9.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | AJ ONeal |
| Maintainers | coolaj86 |
| Keywords | dom, storage, json, w3c, localStorage, sessionStorage, globalStorage, Storage |

## Links

- npm: https://www.npmjs.com/package/json-storage
- Repository: https://git.coolaj86.com/coolaj86/json-storage.js
- npm.io page: https://npm.io/package/json-storage

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.1.2 (latest) — 2018-07-31
- 2.1.1 — 2014-02-24
- 2.1.0 — 2014-02-24
- 2.0.1 — 2014-02-03
- 2.0.0 — 2014-01-26
- 1.1.3 — 2013-03-06
- 1.1.2 — 2012-03-03
- 1.1.1 — 2012-03-03
- 1.1.0 — 2012-03-02
- 1.0.1 — 2011-09-07

## README

JsonStorage
====

A light, sensible abstraction for DOMStorage (such as localStorage).

Installation
===

Bower (Browser)

```bash
bower install json-storage
# or
wget https://git.coolaj86.com/coolaj86/json-storage.js/raw/branch/master/json-storage.js
```

Node.JS (Server)

```bash
npm install -S localStorage json-storage
```

Usage
===

Made for Node.js and Bower (browser-side).

```javascript
var localStorage = require('localStorage')
  , JsonStorage = require('json-storage').JsonStorage
  , store = JsonStorage.create(localStorage, 'my-widget-namespace', { stringify: true })
  , myValue = {
        foo: "bar"
      , baz: "quux"
    }
  ;

store.set('myKey', myValue);
myValue = store.get('myKey');
```

NOTE: When using with Node and the `localStorage` module,
you may wish to pass the `{ stringify: false }` option to prevent double stringification.

API
===

  * `JsonStorage.create(DOMStorage, namespace, opts)`
    * `DOMStorage` should be globalStorage, sessionStorage, or localStorage. Defaults to window.localStorage if set to `null`.
    * `namespace` is optional string which allows multiple non-conflicting storage containers. For example you could pass two widgets different storage containers and not worry about naming conflicts:
      * `Gizmos.create(JsonStorage.create(null, 'my-gizmos'))`
      * `Gadgets.create(JsonStorage.create(null, 'my-gadgets'))`
      * Namespacing can be turned off by explicitly setting `false`
        * `Gadgets.create(JsonStorage.create(null, false))`
    * `opts`
      * `stringify` set to `false` in `node` to avoid double stringifying
  * `store.get(key)`
  * `store.set(key, value)`
  * `store.remove(key)`
  * `store.clear()`
  * `store.keys()`
  * `store.size()`
  * `store.toJSON()`
  * `JSON.stringify(store)`

**NOTE**: You cannot omit optional parameters. Use `null` if you want accepts the defaults for some things and provide a values for others. For example: `JsonStorage.create(null, null, { stringify: false })`

JSON / DOMStorage Conversion Gotchas
===

These notes do not reflect a bugs or defects in this library,
they're simply to inform you of a few 'gotchas' inherent in JSON / DOMStorage conversion.

99.999% of the time these gotchas shouldn't effect you in any way.
If they do, you're probably doing something wrong in the first place.


### `undefined` vs `null`

It is not valid to set `undefined` in JSON. So setting a key to `undefined` will remove it from the store.

This means that `store.set('x')` is the same as `store.remove('x')`.

To save `undefined`, use `null` instead.


Note that both values that exist as `null` and values that don't exist at all will return `null`.

```javascript
store.set('existing-key', null);
null === store.get('existing-key');
null === store.get('non-existant-key');
```


### `null` vs `"null"`

The special case of `null` as `"null"`, aka `"\"null\""`:

`null`, and `"null"` both parse as `null` the "object", instead of one being the string (which would be `"\"null\""`).

Objects containing `null`, however, parse as expected `{ "foo": null, "bar": "null" }` will parse as `foo` being `null` but `bar` being `"null"`, much unlike the value `"null"` being parsed on its own.

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