store

1. Version 2.0

- What's new?

1. Basic Usage

- All you need to get started
- [API](#user-content-api)
- [Installation](#user-content-installation)

1. Supported Browsers

- All of them, pretty much :)
- [List of supported browsers](#user-content-list-of-supported-browsers)

1. Plugins

- Additional common functionality
- [List of all Plugins](#user-content-list-of-all-plugins)
- [Using Plugins](#user-content-using-plugins)
- [Write your own Plugin](#user-content-write-your-own-plugin)

1. Builds

- Choose which build is right for you
- [List of default Builds](#user-content-list-of-default-builds)
- [Make your own Build](#user-content-make-your-own-build)

1. Storages

- Storages provide underlying persistence
- [List of all Storages](#user-content-list-of-all-storages)
- [Storages limits](#user-content-storages-limits)
- [Write your own Storage](#user-content-write-your-own-storage)

Version 2.0

Basic Usage

API

// Store current user
store.set('user', { name:'Marcus' })

// Get current user
store.get('user')

// Remove current user
store.remove('user')

// Clear all keys
store.clearAll()

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

Installation

// Example store.js usage with npm
var store = require('store')
store.set('user', { name:'Marcus' })
store.get('user').name == 'Marcus'

<!-- Example store.js usage with script tag -->
<script src="path/to/my/store.legacy.min.js"></script>
<script>
var store = require('store')
store.set('user', { name:'Marcus' })
store.get('user').name == 'Marcus'
</script>

Supported Browsers

List of supported browsers

• Tested on IE6+
• Tested on iOS 8+
• Tested on Android 4+
• Tested on Firefox 4+
• Tested on Chrome 27+
• Tested on Safari 5+
• Tested on Opera 11+
• Tested on Node (with https://github.com/coolaj86/node-localStorage)

Plugins

List of all Plugins

• all.js: All the plugins in one handy place.
• defaults.js: Declare default values. Example usage
• dump.js: Dump all stored values. Example usage
• events.js: Get notified when stored values change. Example usage
• expire.js: Expire stored values at a given time. Example usage
• observe.js: Observe stored values and their changes. Example usage
• operations.js: Useful operations like push, shift & assign. Example usage
• update.js: Update a stored object, or create it if null. Example usage
• v1-backcompat.js: Full backwards compatibility with store.js v1. Example usage

Using Plugins

// Example plugin usage:
var expirePlugin = require('store/plugins/expire')
store.addPlugin(expirePlugin)

Write your own plugin

// Example plugin that stores a version history of every value
var versionHistoryPlugin = function() {
	var historyStore = this.namespace('history')
	return {
		set: function(super_fn, key, value) {
			var history = historyStore.get(key) || []
			history.push(value)
			historyStore.set(key, history)
			return super_fn()
		},
		getHistory: function(key) {
			return historyStore.get(key)
		}
	}
}
store.addPlugin(versionHistoryPlugin)
store.set('foo', 'bar 1')
store.set('foo', 'bar 2')
store.getHistory('foo') == ['bar 1', 'bar 2']

Builds

List of default builds

• store.everything.min.js: All the plugins, all the storages. Source
• store.legacy.min.js: Full support for all tested browsers. Add plugins separately. Source
• store.modern.min.js: Full support for all modern browsers. Add plugins separately. Source
• store.v1-backcompat.min.js: Full backwards compatibility with store.js v1. Source

Make your own Build

// Example custom build usage:
var engine = require('store/src/store-engine')
var storages = [
	require('store/storages/localStorage'),
	require('store/storages/cookieStorage')
]
var plugins = [
	require('store/plugins/defaults'),
	require('store/plugins/expire')
]
var store = engine.createStore(storages, plugins)
store.set('foo', 'bar', new Date().getTime() + 3000) // Using expire plugin to expire in 3 seconds

Storages

List of all Storages

• all.js All the storages in one handy place.
• localStorage.js Store values in localStorage. Great for all modern browsers.
• sessionStorage.js Store values in sessionStorage.
• cookieStorage.js Store values in cookies. Useful for Safari Private mode.
• memoryStorage.js Store values in memory. Great fallback to ensure store functionality at all times.
• oldFF-globalStorage.js Store values in globalStorage. Only useful for legacy Firefox 3+.
• oldIE-userDataStorage.js Store values in userData. Only useful for legacy IE 6+.

Storages limits

Write your own Storage

// Example custom storage
var storage = {
	name: 'myStorage',
	read: function(key) { ... },
	write: function(key, value) { ... },
	each: function(fn) { ... },
	remove: function(key) { ... },
	clearAll: function() { ... }
}
var store = require('store').createStore(storage)