local-storage

A simplified localStorage API that just works

Install

Using npm

1npm install local-storage --save

Using bower

1bower install localstorage --save

API

The API is a simplified way to interact with all things localStorage. Note that when localStorage is unsupported in the current browser, a fallback to an in-memory store is used transparently.

For that reason, consider that local-storage values might evaporate across page views.

ls(key, value?)

If a value argument is provided, acts as ls.set. When value isn't provided, acts as ls.get.

Example

1var ls = require('local-storage');
2
3ls('foo');
4// <- null
5
6ls('foo', 'bar');
7// <- true
8
9ls('foo');
10// <- 'bar'

ls.get(key)

Returns value under key in local storage. Equivalent to ls(key). Internally parses the value from JSON before returning it.

Example

1var ls = require('local-storage');
2
3ls('foo', 'bar');
4// <- true
5
6ls.get('foo');
7// <- 'bar'

ls.set(key, value)

Persists value under key in local storage. Equivalent to ls(key, value). Internally converts the value to JSON.

Returns whether the action succeeded; otherwise, an error was thrown by the browser when trying to persist the value. Failure typically means a QuotaExceededError was thrown.

Example

1var ls = require('local-storage');
2
3ls.set('foo', 'bar');
4// <- true
5
6ls.get('foo');
7// <- 'bar'

ls.remove(key)

Removes key from local storage. Returns true if the property was successfully deleted, and false otherwise.

Example

1var ls = require('local-storage');
2
3ls.set('foo', 'bar');
4// <- true
5
6ls.remove('foo');
7// <- true

ls.clear()

Clears local storage.

Example

1var ls = require('local-storage');
2
3ls.set('foo', 'bar');
4ls.set('baz', 'tar');
5ls.clear();

ls.backend(store?)

If a store argument is provided, it sets the backend storage engine. Otherwise it returns the current backend.

Example

1var ls = require('local-storage');
2
3ls.backend(sessionStorage);
4ls.set('baz', 'tar');
5/* close the tab, then reopen */
6ls.get('baz');

ls.on(key, fn)

Listen for changes persisted against key on other tabs. Triggers fn when a change occurs, passing the following arguments.

• value: the current value for key in local storage, parsed from the persisted JSON
• old: the old value for key in local storage, parsed from the persisted JSON
• url: the url for the tab where the modification came from

Example

Open a page with the following snippet in multiple tabs. The storage event will trigger on all tabs except for the one that persisted the change.

1var ls = require('local-storage');
2
3ls.on('foo', storage);
4ls.set('foo', 'bar');
5
6function storage (value) {
7  console.log('some other tab changed "foo" to ' + value);
8}

ls.off(key, fn)

Removes a listener previously attached with ls.on(key, fn).

Example

1var ls = require('local-storage');
2
3ls.on('foo', storage);
4ls.off('foo', storage);
5
6function storage (value) {
7  console.log('some other tab changed "foo" to ' + value);
8}

Typescript

Example

1import ls, {get,set} from "local-storage";
2
3set<number>('foo',5);
4get<number>('foo');
5
6interface IFoo{
7  bar: string;
8}
9
10ls<IFoo>('foo');

Example

1import * as ls from "local-storage";
2
3ls.set<number>('foo',5);
4ls.get<number>('foo');
5

License

MIT