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.
А сколько данных реально можно сохранить?Действуют ограничения самого хранилища: около 2 МБ в localStorage, 5 МБ в sessionStorage и всего 4 КБ в cookies. В README советуют держаться ниже 1 млн символов, а если нужен и режим приватного просмотра в Safari — ниже 32 тысяч.
Это проверенное решение или всё ещё экспериментальное?Проверенное: библиотека существует с 2010 года и работает в продакшене на десятках тысяч сайтов, включая cnn.com и dailymotion.com.
В каких браузерах это реально работает?Практически во всех: тестировалось на IE6+, iOS 8+, Android 4+, Firefox 4+, Chrome 27+, Safari 5+, Opera 11+, плюс Node. Для IE6/IE7 есть legacy-сборка, а modern-сборка облегчена под современные браузеры.
Где на самом деле хранятся мои данные и переживут ли они перезагрузку страницы?В самом браузере. Библиотека выбирает лучшее доступное хранилище — localStorage, sessionStorage, cookies (для приватного режима Safari) или запасной вариант в памяти — и автоматически переключается на первое, которое работает. Данные теряются при перезагрузке только у запасного хранилища в памяти.
Что добавляют плагины к базовым get и set?Дополнительные возможности: expire (значение устаревает в заданный момент), events и observe (уведомления об изменении сохранённых значений), defaults, операции вроде push, shift и assign, update, а также выгрузка всех сохранённых значений. Сборка everything включает их все.
Какую сборку выбрать?store.modern.min.js — только для современных браузеров, store.legacy.min.js — если нужна ещё и поддержка IE6/IE7 и Firefox 4, store.everything.min.js — если хочется все плагины и хранилища сразу, а store.v1-backcompat.min.js — для полной обратной совместимости с кодом на store.js v1.
Могу ли я написать свой плагин или своё хранилище?Да. Плагин — это функция, которая возвращает объект, добавляемый к store, а переопределённые функции могут вызывать оригинал через аргумент superfn; в README в качестве примеров указаны defaults, expire и events. Хранилища устроены похожим образом — как объекты, и good шаблонами служат 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