json-storage.js/README.md

96 lines
2.6 KiB
Markdown
Raw Normal View History

2012-03-02 18:51:58 +00:00
JsonStorage
====
2012-03-02 18:53:23 +00:00
A light, sensible abstraction for DOMStorage (such as localStorage).
2011-08-28 02:44:20 +00:00
Installation
===
Bower (Browser)
2011-08-28 02:44:20 +00:00
```bash
bower install json-storage
# or
wget https://raw2.github.com/coolaj86/json-storage-js/master/lib/json-storage.js
```
2011-08-28 02:44:20 +00:00
Node.JS (Server)
```bash
npm install localStorage json-storage
```
2011-08-28 02:44:20 +00:00
Usage
===
Made for Node.js and Bower (browser-side).
var localStorage = require('localStorage')
, JsonStorage = require('json-storage').JsonStorage
, store = JsonStorage.create(localStorage, 'my-widget-namespace', { stringify: false })
, myValue = {
foo: "bar"
, baz: "quux"
}
;
2012-03-02 18:35:53 +00:00
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
===
2012-03-02 18:51:58 +00:00
* `JsonStorage.create(DOMStorage, namespace)`
2012-03-02 18:35:53 +00:00
* `DOMStorage` should be globalStorage, sessionStorage, or localStorage
* `namespace` is optional string which allows multiple non-conflicting storage containers
2012-03-02 18:51:58 +00:00
* `store.get(key)`
* `store.set(key, value)`
* `store.remove(key)`
* `store.clear()`
* `store.keys()`
* `store.size()`
* `store.toJSON()`
2012-03-02 18:35:53 +00:00
* `JSON.stringify(store)`
Upgrading from localStorage and 1.0.x to 1.1.x
===
1.1.x automatically attempts to upgrade your DOMStorage to use namespaces in backwards-compatible way.
However, you can prevent this behaviour:
localStorage.getItem('_json-storage-namespaced_', true);
null vs undefined in JSON
===
2011-08-28 02:44:20 +00:00
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.
2012-03-02 18:35:53 +00:00
It is not valid to set `undefined` in JSON. So setting a key to `undefined` will remove it from the store.
2011-08-28 02:44:20 +00:00
2012-03-02 18:35:53 +00:00
This means that `store.set('x')` is the same as `store.remove('x')`.
2011-08-28 02:44:20 +00:00
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`.
2012-03-02 18:35:53 +00:00
store.set('existing-key', null);
null === store.get('existing-key');
null === store.get('non-existant-key');
2011-08-28 02:44:20 +00:00
The special case of `null` as `"null"`, aka `"\"null\""`:
2011-08-28 02:44:20 +00:00
`null`, and `"null"` both parse as `null` the "object", instead of one being the string (which would be `"\"null\""`).
2012-03-02 18:35:53 +00:00
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.