store.js README

The project's README from github.com/marcuswestin/store.js. As one markdown file: README.md.

Store.js

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

Circle CI npm version npm

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
  2. Supported Browsers
  3. Plugins
  4. Builds
  5. Storages

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

store.js (marcuswestin/store.js)

Searching Database…

14K ·GitHub
Store.js
这是什么？Store.js 是一个 JavaScript 库，用于在浏览器里做键值存储，兼容所有浏览器。它从 2010 年就存在了，在 cnn.com、dailymotion.com 等数以万计的网站上投入生产使用。
这是我要引入前端代码的库，还是一个独立的应用？它是一个小型 JavaScript 库，给你一个 store 对象，提供 get/set/remove/each 方法在客户端保存数据——不需要服务器，没有界面，只是浏览器存储之上的一套 API。
怎么把它加到项目里？用 npm 安装，或者下载某个预构建的 min.js 文件，用 script 标签加载。之后直接调用 store.set 和 store.get 就行了。
除了这个脚本，我还需要别的东西吗——jQuery、构建工具、账号？不需要，只要有浏览器就行：它是单一独立脚本，没有任何依赖，同样的 API 在 Node 下也能用。
我实际能存多少数据？受后端限制：localStorage 大约 2MB，sessionStorage 大约 5MB，cookie 只有 4KB。README 建议控制在 100 万字符以内；如果还需要支持 Safari 无痕模式，则控制在 3.2 万字符以内。
这个库是经过实战检验的，还算实验性质的？经过实战检验：从 2010 年至今，已在包括 cnn.com 和 dailymotion.com 在内的数以万计的网站上投入生产运行。
它到底能在哪些浏览器里用？基本上全都能用：在 IE6+、iOS 8+、Android 4+、Firefox 4+、Chrome 27+、Safari 5+、Opera 11+ 以及 Node 上都测试过。legacy 构建支持 IE6/IE7，modern 构建则为现代浏览器做了精简。
我的数据实际存在哪里，刷新页面后还在吗？存在浏览器本身。它会挑选可用的最佳后端——localStorage、sessionStorage、cookie（用于 Safari 无痕模式）或内存兜底——并自动回退到第一个可用的存储方式。只有内存兜底在刷新后会丢数据。
除了基本的 get 和 set，这些插件还能做什么？一些额外功能：expire（值在指定时间过期）、events 和 observe（存储的值变化时收到通知）、defaults、push、shift、assign 等操作、update，以及导出所有已存数据的 dump。everything 构建把所有这些都打包在一起。
我该选哪个构建版本？只支持现代浏览器用 store.modern.min.js；还要支持 IE6/IE7 和 Firefox 4 用 store.legacy.min.js；想要内置全部插件和存储方式用 store.everything.min.js；需要与 store.js v1 代码完全向后兼容用 store.v1-backcompat.min.js。
我能自己写插件或存储后端吗？可以。插件是一个函数，它返回一个被合并进 store 的对象；被覆盖的函数还能通过 superfn 参数调用原函数。README 把 defaults、expire 和 events 列为示例。存储后端也是类似的对象，memoryStorage 和 localStorage 是很好的模板。
What are similar projects?ultrastorage, lowdb, jquery, localForage, protobuf.js, redux-persist, Respond, markdown-it
Which topics is it in?key-value-store, localstorage, cross-browser, serialization, plugins, storage, json, browser, utility, npm, frontend, nodejs
Creator
marcuswestin
Size
0.6 MB
Stars
14K
Updated
CommitFeb 25
Age
16y
Commits · 90 Days