store

What is store?

The 'store' npm package is a simple and lightweight library for managing key-value pairs in the browser's local storage. It provides an easy-to-use API for setting, getting, and removing data from local storage, making it useful for persisting user preferences, session data, and other client-side information.

What are store's main functionalities?

Set a value

This feature allows you to store a key-value pair in the local storage. The 'set' method takes two arguments: the key and the value you want to store.

store.set('key', 'value');

Get a value

This feature allows you to retrieve a value from the local storage using its key. The 'get' method takes one argument: the key of the value you want to retrieve.

store.get('key');

Remove a value

This feature allows you to remove a key-value pair from the local storage. The 'remove' method takes one argument: the key of the value you want to remove.

store.remove('key');

Clear all values

This feature allows you to clear all key-value pairs from the local storage. The 'clear' method does not take any arguments.

store.clear();

Other packages similar to store

localforage

LocalForage is a fast and simple storage library for JavaScript. It improves the offline experience of your web app by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API. Compared to 'store', LocalForage supports larger data storage and asynchronous operations.

store2

Store2 is a versatile and powerful library for managing local storage, session storage, and cookies. It provides a unified API for all three storage types, making it more flexible than 'store'. Store2 also supports namespaces and advanced data manipulation methods.

idb-keyval

IDB-Keyval is a small library that provides a simple key-value store backed by IndexedDB. It offers a promise-based API for asynchronous operations, making it suitable for storing larger amounts of data compared to 'store'. IDB-Keyval is ideal for applications that require more robust storage solutions.

README

store.js

store.js exposes a simple API for cross browser local storage

// Store 'marcus' at 'username'
store.set('username', 'marcus')

// Get 'username'
store.get('username')

// Remove 'username'
store.remove('username')

// Clear all keys
store.clear()

// Store an object literal - store.js uses JSON.stringify under the hood
store.set('user', { name: 'marcus', likes: 'javascript' })

// Get the stored object - store.js uses JSON.parse under the hood
var user = store.get('user')
alert(user.name + ' likes ' + user.likes)

// Get all stored values
store.getAll().user.name == 'marcus'

// Loop over all stored values
store.forEach(function(key, val) {
	console.log(key, '==', val)
})

How does it work?

store.js uses localStorage when available, and falls back on the userData behavior in IE6 and IE7. No flash to slow down your page load. No cookies to fatten your network requests.

store.js depends on JSON for serialization to disk.

Installation

Just grab store.min.js or store+json2.min.js and include them with a script tag.

store.enabled flag

If your product depends on store.js, you must check the store.enabled flag first:

<script src="store.min.js"></script>
<script>
	init()
	function init() {
		if (!store.enabled) {
			alert('Local storage is not supported by your browser. Please disable "Private Mode", or upgrade to a modern browser.')
			return
		}
		var user = store.get('user')
		// ... and so on ...
	}
</script>

LocalStorage may sometimes appear to be available but throw an error when used. An example is Safari's private browsing mode. Other browsers allow the user to temporarily disable localStorage. Store.js detects these conditions and sets the store.enabled flag appropriately.

Screencast

Introductory Screencast to Store.js by Jack Franklin.

Contributors & Forks

Contributors: https://github.com/marcuswestin/store.js/graphs/contributors

Forks: https://github.com/marcuswestin/store.js/network/members

In node.js

store.js works as expected in node.js, assuming that global.localStorage has been set:

global.localStorage = require('localStorage')
var store = require('./store')
store.set('foo', 1)
console.log(store.get('foo'))

Supported browsers

• Tested in iOS 4+
• Tested in Firefox 3.5
• Tested in Firefox 3.6
• Tested in Firefox 4.0+
• Support dropped for Firefox < 3.5 (see notes below)
• Tested in Chrome 5
• Tested in Chrome 6
• Tested in Chrome 7
• Tested in Chrome 8
• Tested in Chrome 10
• Tested in Chrome 11+
• Tested in Safari 4
• Tested in Safari 5
• Tested in IE6
• Tested in IE7
• Tested in IE8
• Tested in IE9
• Tested in IE10
• Tested in Opera 10
• Tested in Opera 11
• Tested in Opera 12
• Tested in Node.js v0.10.4 (with https://github.com/coolaj86/node-localStorage 1.0.2)

Private mode Store.js may not work while browsing in private mode. This is as it should be. Check the store.enabled flag before relying on store.js.

Saucelabs.com rocks Extensive browser testing of store.js is possible thanks to Saucelabs.com. Check them out, they're awesome.

Firefox 3.0 & 2.0: Support for FF 2 & 3 was dropped in v1.3.6. If you require support for ancient versions of FF, use v1.3.5 of store.js.

Important note: In IE6 and IE7, many special characters are not allowed in the keys used to store any key/value pair. With @mferretti's help, there's a suitable workaround which replaces most forbidden characters with "___".

Storage limits

• IE6 & IE7: 1MB total, but 128kb per "path" or "document" (see http://msdn.microsoft.com/en-us/library/ms531424(v=vs.85).aspx)
• See http://dev-test.nemikor.com/web-storage/support-test/ for a list of limits per browser

Unsupported browsers

• Firefox 1.0: no means (beside cookies and flash)
• Safari 2: no means (beside cookies and flash)
• Safari 3: no synchronous api (has asynch sqlite api, but store.js is synch)
• Opera 9: don't know if there is synchronous api for storing data locally
• Firefox 1.5: don't know if there is synchronous api for storing data locally
• Microsoft IIS & IE7: With meta tag & "charset=iso-8859-1", things stop working. See issue #47.

Some notes on serialization

localStorage, when used without store.js, calls toString on all stored values. This means that you can't conveniently store and retrieve numbers, objects or arrays:

localStorage.myage = 24
localStorage.myage !== 24
localStorage.myage === '24'

localStorage.user = { name: 'marcus', likes: 'javascript' }
localStorage.user === "[object Object]"

localStorage.tags = ['javascript', 'localStorage', 'store.js']
localStorage.tags.length === 32
localStorage.tags === "javascript,localStorage,store.js"

What we want (and get with store.js) is

store.set('myage', 24)
store.get('myage') === 24

store.set('user', { name: 'marcus', likes: 'javascript' })
alert("Hi my name is " + store.get('user').name + "!")

store.set('tags', ['javascript', 'localStorage', 'store.js'])
alert("We've got " + store.get('tags').length + " tags here")

The native serialization engine of javascript is JSON. Rather than leaving it up to you to serialize and deserialize your values, store.js uses JSON.stringify() and JSON.parse() on each call to store.set() and store.get(), respectively.

Some browsers do not have native support for JSON. For those browsers you should include JSON2.js (non-minified copy is included in this repo).

No sessionStorage/auto-expiration?

No. I believe there is no way to provide sessionStorage semantics cross browser. However, it is trivial to expire values on read on top of store.js:

var storeWithExpiration = {
	set: function(key, val, exp) {
		store.set(key, { val:val, exp:exp, time:new Date().getTime() })
	},
	get: function(key) {
		var info = store.get(key)
		if (!info) { return null }
		if (new Date().getTime() - info.time > info.exp) { return null }
		return info.val
	}
}
storeWithExpiration.set('foo', 'bar', 1000)
setTimeout(function() { console.log(storeWithExpiration.get('foo')) }, 500) // -> "bar"
setTimeout(function() { console.log(storeWithExpiration.get('foo')) }, 1500) // -> null

Testing

For a browser: Go to http://marcuswestin.github.io/store.js/test.html to test the latest version of store.js.

For a browser, locally: do npm install node-static && ./node_modules/node-static/bin/cli.js and go to http://localhost:8080

(Note that test.html must be served over http:// or https://. This is because localStore does not work in some browsers when using the file:// protocol.)

For Nodejs: do npm install . localStorage && node test-node.js