Guide to Storage

There are multiple ways of storing persistent client-side data in a browser, but they're abstracted away by the storage module. This module is intended for storing small to medium-sized strings.

The storage module is backed by localStorage. It should not be used for more than a megabyte of data, and should not be used in performance-critical code paths. It is up to the implementing module to appropriately cache values and handle large blobs of data that are not appropriate for localStorage.

You should prefer using the storage module over accessing localStorage directly for a few reasons: storage could use cookies in the future if needed, there are potential errors that can be thrown in certain browsers that storage will abstract away, and other potential pitfalls that are steamrollered over.

API

storage.clear()

This method, when called, will clear localStorage for the application's origin.

storage.getItem()

storage.getItem(key)

Fetches an item stored with the key key.

storage.setItem()

storage.setItem(key, value)

Sets value to an item in storage with the key key. If key already exists, it will be overwritten.

storage.removeItem()

storage.removeItem(key)

Removes an item from storage with the key key.

Notes

Safari

In Safari's private browsing mode, localStorage access is not permitted. Instead, the storage module will fall back on an in-memory data store. This data will not be persisted between sessions.

Indexing

Unlike localStorage, the storage module cannot be indexed. For example:

// GOOD
localStorage.getItem('foo')
require('storage').getItem('foo')

// BAD
localStorage['foo'] = 'bar'
require('storage')['foo'] = 'bar'

Indexing the storage module directly will not work.

Keys

Keys in the storage module are automatically versioned. Keys are formatted in the pattern <version>::<key>, where <version> is the value of settings.storage_version. The storage_version setting should be updated any time the structure of stored data is changed.