@segment/store

2020-01-13

@segment/store

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

Store.js

Cross-browser storage for all use cases, used across the web.

Circle CInpm versionnpm

Store.js has been around since 2010 (first commit, v1 release). It is used in production on tens of thousands of websites, such as cnn.com, dailymotion.com, & many more.

Store.js provides basic key/value storage functionality (get/set/remove/each) as well as a rich set of plug-in storages and extra functionality.

  1. Basic Usage
    • All you need to get started
    • API
    • Installation
  2. Supported Browsers
    • All of them, pretty much :)
    • List of supported browsers
  3. Plugins
    • Additional common functionality
    • List of all Plugins
    • Using Plugins
    • Write your own Plugin
  4. Builds
    • Choose which build is right for you
    • List of default Builds
    • Make your own Build
  5. Storages
    • Storages provide underlying persistence
    • List of all Storages
    • Storages limits
    • Write your own Storage

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:

npm i store
// 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>
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.jsinstead.

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

StorageTargetsRecommendationsMore info
allAll browsersStore < 1 million characters(Except Safari Private mode)
allAll & Private modeStore < 32 thousand characters(Including Safari Private mode)
localStorageModern browsersMax 2mb (~1M chars)limits, android
sessionStorageModern browsersMax 5mb (~2M chars)limits
cookieStorageSafari Private modeMax 4kb (~2K chars)limits
userDataStorageIE5, IE6 & IE7Max 64kb (~32K chars)limits
globalStorageFirefox 2-5Max 5mb (~2M chars)limits
memoryStorageAll browsers, fallbackDoes 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 memoryStorageand 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)

以上是 @segment/store 的使用教程帮助文档。


上一篇:@segment/is-meta
下一篇:@segment/canonical
相关教程
关注微信

扫码加入 JavaScript 社区

相关文章
暂无相关文章

首次访问,需要验证
微信扫码,关注即可
(仅需验证一次)

欢迎加入 JavaScript 社区

号内回复关键字:

回到顶部