🛅 A simplified localStorage API that just works
Clone or download
bevacqua Merge pull request #6 from apechimp/master
Look for key, not 'key'
Latest commit b9725b0 Apr 28, 2015
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist Autogenerated pre-deployment commit Mar 16, 2015
.editorconfig initial commit Jan 7, 2015
.gitignore initial commit Jan 7, 2015
.jshintignore add jshint dotfiles Jan 7, 2015
.jshintrc add jshint dotfiles Jan 7, 2015
bower.json v1.4.1 Mar 16, 2015
changelog.markdown fix weird corner-case Mar 16, 2015
license initial commit Jan 7, 2015
local-storage.js fix weird corner-case Mar 16, 2015
package.json Autogenerated pre-deployment commit Mar 16, 2015
readme.markdown updated docs Mar 3, 2015
stub.js Look for key, not 'key' Apr 28, 2015
tracking.js fix parsing issue Jan 7, 2015

readme.markdown

local-storage

A simplified localStorage API that just works

Install

Using npm

npm install local-storage --save

Using bower

bower 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
var ls = require('local-storage');

ls('foo');
// <- null

ls('foo', 'bar');
// <- true

ls('foo');
// <- '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
var ls = require('local-storage');

ls('foo', 'bar');
// <- true

ls.get('foo');
// <- '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 an error was thrown by the browser when trying to persist the value. Failure typically means a QuotaExceededError was thrown.

Example
var ls = require('local-storage');

ls.set('foo', 'bar');
// <- true

ls.get('foo');
// <- 'bar'

ls.remove(key)

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

Example
var ls = require('local-storage');

ls.set('foo', 'bar');
// <- true

ls.remove('foo');
// <- true

ls.clear()

Clears local storage.

Example
var ls = require('local-storage');

ls.set('foo', 'bar');
ls.set('baz', 'tar');
ls.clear();

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.

var ls = require('local-storage');

ls.on('foo', storage);
ls.set('foo', 'bar');

function storage (value) {
  console.log('some other tab changed "foo" to ' + value);
}

ls.off(key, fn)

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

Example
var ls = require('local-storage');

ls.on('foo', storage);
ls.off('foo', storage);

function storage (value) {
  console.log('some other tab changed "foo" to ' + value);
}

License

MIT