Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

storess

marcuswestin7MIT2.0.12

A localStorage wrapper for all browsers without using cookies or flash. Uses localStorage, globalStorage, and userData behavior under the hood

readme

Store.js

Build Status npm version npm

  1. Version 2.0
    • What's new?
  2. Basic Usage
  3. Supported Browsers
  4. Plugins
  5. Builds
  6. Storages

Version 2.0

Store.js has been around since 2010 (first commit! HN discussion!), and is live on tens of thousands of websites - like cnn.com!

For many years v1.x provided basic cross-browser persistent storage, and over time more and more people started asking for additional functionality.

Store.js version 2 is a full revamp with pluggable storage (it will automatically fall back to one that works in every scenario by default), pluggable extra functionality (like expirations, default values, common array/object operations, etc), and fully cross-browser automatic testing using saucelabs.com.

Basic Usage

All you need to know to get started:

API

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

// 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

Using npm:

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

Using script tag (first download one of the builds):

<!-- 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

All of them, pretty much :)

To support all browsers (including IE 6, IE 7, Firefox 4, etc.), use require('store') (alias for require('store/dist/store.legacy')) or store.legacy.min.js.

To save some kilobytes but still support all modern browsers, use require('store/dist/store.modern') or store.modern.min.js instead.

List of supported browsers

Plugins

Plugins provide additional common functionality that some users might need:

List of all Plugins

Using Plugins

With npm:

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

If you're using script tags, you can either use store.everything.min.js (which has all plugins built-in), or clone this repo to add or modify a build and run make build.

Write your own plugin

A store.js plugin is a function that returns an object that gets added to the store. If any of the plugin functions overrides existing functions, the plugin function can still call the original function using the first argument (super_fn).

// 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']

Let me know if you need more info on writing plugins. For the moment I recommend taking a look at the current plugins. Good example plugins are plugins/defaults, plugins/expire and plugins/events.

Builds

Choose which build is right for you!

List of default builds

Make your own Build

If you're using npm you can create 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

Store.js will pick the best available storage, and automatically falls back to the first available storage that works:

List of all Storages

Storages limits

Each storage has different limits, restrictions and overflow behavior on different browser. For example, Android has has a 4.57M localStorage limit in 4.0, a 2.49M limit in 4.1, and a 4.98M limit in 4.2... Yeah.

To simplify things we provide these recommendations to ensure cross browser behavior:

Storage Targets Recommendations More info
all All browsers Store < 1 million characters (Except Safari Private mode)
all All & Private mode Store < 32 thousand characters (Including Safari Private mode)
localStorage Modern browsers Max 2mb (~1M chars) limits, android
sessionStorage Modern browsers Max 5mb (~2M chars) limits
cookieStorage Safari Private mode Max 4kb (~2K chars) limits
userDataStorage IE5, IE6 & IE7 Max 64kb (~32K chars) limits
globalStorage Firefox 2-5 Max 5mb (~2M chars) limits
memoryStorage All browsers, fallback Does not persist across pages!

Write your own Storage

Chances are you won't ever need another storage. But if you do...

See storages/ for examples. Two good examples are memoryStorage and localStorage.

Basically, you just need an object that looks like this:

// 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)

changelog

v2.0.0

  • New pluggable architecture!
  • New storages: localStorage, cookieStorage, memoryStorage, sessionStorage, oldFF-globalStorage, oldIE-userDataStorage.
  • New plugins: defaults, dump, events, expire, json2, observe, operations, update, v1-backcompat.
  • New builds: everything, legacy, modern, v1-backcompat, minimal (17k, 13k, 12k, 6k respectively)

v1.3.20

  • Fully automated test framework
  • Fix infinite loop in IE

v1.3.19

  • Use umdjs to export store.js (#116, #111, #96, #91, #78, ...)
  • Make compatible with "use strict" mode (#111)
  • Fix store.clear in legacy-IE code path (#103)
  • Roadmap for v1.4.x and v2.x.x

v1.3.17

  • Add store.has
  • Add store.get default value, e.g store.get('foo', 1)
  • Fix IE strict mode compatability issue (#105)
  • Added store.version

v1.3.16

  • Improve environment/module.exports detection (#88, github.com/benrudolph)

v1.3.15

v1.3.14

  • Makefile
  • Fix old-IE getAll/forEach, actually this time. I think

v1.3.12

  • Fix old-IE forEach again. Hrm...

v1.3.11

  • Fix old-IE forEach

v1.3.10

  • Add store.forEach
  • Add bower.json (sign, I know, yet another package file to maintain)
  • Add MIT license header

v1.3.9

  • Make store.js work in Node.js (using any working localStorage shim for Node.js)

v1.3.8

  • Fix closing </iframe> tag for IE7 (GH issue #68)

v1.3.7

  • Fix store.getAll for IE6

v1.3.6

v1.3.5

  • Now store.set returns the set value: store.set(key, value) == value
  • Values previously set with localStorage directly are now parsed handler by store.js: localStorage['foo'] = 1; assert(store.get('foo') == 1)

v1.3.4

  • Add store.enabled
  • Deprecate store.disabled
  • Add link to Jack Franklin's screencast

v1.3.3

  • Fix IE keys beginning with numeric characters (nice find @pauldwaite)

v1.3.2

  • Implement store.getAll() (patch by @blq)

v1.3.0

  • Use uglify.js for minifying store.min.js and store+json.min.js
  • Add build script

v1.2.0

  • Remove same-path restrictions in IE6/7! (Thanks @mjpizz!)
  • Support CommonJS and AMD module systems (Thanks @pereckerdal!)
  • Fix: store.set('foo', undefined); store.get('foo') no longer throws (Thanks @buger!)

v1.1.1

  • Publish in npm as "store" rather than "store.js"
  • Add commonjs export for require support
  • Add supported browsers Chrome 6-11, Firefox 4.0

v1.1.0

  • First versioned version.
  • API: store.set, store.get, store.remove, store.clear, store.transact
  • Minified versions are included: store.min.js for store.js only, and store+json2.min.js for store.js and json2.js

TODO

  • Get around IE6/7 per-directory restrition. @lrbabe/@louis_remi had the idea of putting the store.js API in an anonymous iframe a la https://github.com/meebo/embed-code and see what directory restriction that would fall under