GithubHelp home page GithubHelp logo

willium / store.js Goto Github PK

View Code? Open in Web Editor NEW

This project forked from marcuswestin/store.js

0.0 0.0 0.0 359 KB

Cross-browser storage for all use cases • Used across the web • See below for v2.0 news!

License: MIT License

Makefile 0.53% JavaScript 99.47%

store.js's Introduction

Store.js

  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 persistant 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 IE6, IE7, Firefox 4, etc), use require('store/dist/legacy') or store.legacy.min.js.

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

List of supported browsers

Plugins

Plugins provide additional common functionality that some people need, but not everyone:

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 on 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, but 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-engine')
var storages = [
	require('store/storages/localStorage'),
	require('../../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 added storage that works:

List of all Storages

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() { ... }
}
store.addStorage(storage)

store.js's People

Contributors

afc163 avatar aimwhy avatar alias-mac avatar benrudolph avatar blq avatar christophehurpeau avatar deepred5 avatar gregwebs avatar jackfranklin avatar jakobud avatar kappuccino avatar lfac-pt avatar m19c avatar marcuswestin avatar matthewmueller avatar mjpizz avatar mortonfox avatar mosch avatar paladox avatar per-gron avatar popomore avatar rmg avatar robinator avatar ryankirkman avatar stevenblack avatar tombyrer avatar tschaub avatar whitehat101 avatar xuefeng-zhu avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.