store2

What is store2?

The store2 npm package is a simple, lightweight JavaScript library for cross-browser local storage with a simple but powerful API. It provides an easy way to store, retrieve, and manage data in the browser's local storage and session storage, with additional features such as namespacing and cross-tab communication.

What are store2's main functionalities?

Basic storage operations

Perform basic local storage operations such as setting, getting, removing, and clearing all items.

{"set": "store.set('user', {name: 'Marcus'})", "get": "store.get('user')", "remove": "store.remove('user')", "clearAll": "store.clearAll()"}

Namespacing

Create a namespace to group related data and perform operations within that namespace.

{"createNamespace": "var userStore = store.namespace('user')", "namespaceSet": "userStore.set('info', {name: 'Marcus'})", "namespaceGet": "userStore.get('info')"}

Cross-tab communication

Enable cross-tab communication by setting a flag that will trigger the storage event listener when data is changed.

{"setListen": "store.set('user', {name: 'Marcus'}, true)", "onStorage": "window.addEventListener('storage', function(e) { console.log('storage changed', e.key); })"}

Additional storage methods

Use additional methods to retrieve all stored items, iterate over them, or perform a transactional operation on a stored object.

{"getAll": "store.getAll()", "each": "store.each(function(value, key) { console.log(key, '==', value); })", "transact": "store.transact('user', function(user) { user.visits = (user.visits || 0) + 1; })"}

Other packages similar to store2

js-cookie

js-cookie is a simple, lightweight JavaScript API for handling browser cookies. It allows you to create, read, and delete cookies with ease. While store2 focuses on local and session storage, js-cookie is specifically designed for cookie storage, which can be useful for storing data that needs to be sent to the server on each request.

redux-persist

redux-persist is a library allowing to save a Redux store state in a persistent storage and rehydrate it on app start. It is more specialized than store2 as it is designed to work with Redux applications, providing a seamless way to persist and rehydrate the Redux state tree.

README

store.js

A much more developer-friendly API for localStorage and sessionStorage and friends. The API is rich and extensible, yet simple to use. It supports JSON, namespacing and more.

Getting Started

Download the production version or the development version.

In your web page:

<script src="jquery.js"></script>
<script src="dist/store.min.js"></script>
<script>
store('greeting', 'hello world!');
</script>

Documentation

The main store function handles set, get, setAll, getAll and clear actions; respectively, these are called like so:

store(key, data);
store(key);
store({key: data, key2: data2});
store();
store(false);

There are also more explicit and versatile functions available:

store.set(key, data[, overwrite=true]);
store.setAll(data[, overwrite=true]);
store.get(key[, alt]);
store.getAll();
store.remove(key);
store.has(key);
store.key(index);
store.keys();
store.each(fn[, end]);
store.size();
store.clear();
store.clearAll();

Passing in false for the optional overwrite parameters will cause "set" actions to be skipped if the storage already has a value for that key. All "set" action methods return the previous value for that key, by default. If overwrite is false and there is a previous value, the unused new value will be returned.

All of the above functions are acting upon simple localStorage (aka "local"). Using sessionStorage merely requires calling functions on store.session:

store.session("addMeTo", "sessionStorage");
store.local({lots: 'of', data: 'altogether'});// store.local === store :)

All the specific get, set, etc. functions are available on both store.session and store.local, as well as any other storage facility registered via store.area(name, customStorageObject) by an extension, where customStorageObject must implement the Storage interface.

If you want to put stored data from different pages or areas of your site into separate namespaces, the store.namespace is your friend:

var cart = store.namespace('cart');
cart('total', 23.25);// stores in localStorage as 'cart.total'
console.log(store('cart.total') == cart('total'));// logs true
console.log(store.cart.getAll());// logs {total: 23.25}
cart.session('group', 'toys');// stores in sessionStorage as 'cart.group'

The namespace provides the same exact API as "store" but silently adds/removes the namespace prefix as needed. It also makes the namespace accessible directly via store.namespace (e.g. 'store.cart') as long as it does not conflict with an existing part of the store API.

The 'namespace' function is one of two "extra" functions that are also part of the "store API":

store.namespace(prefix[, noSession=true]);// returns a new store API that prefixes all key-based functions
store.isFake();// is this storage persistent? (e.g. is this old IE?) 

If localStorage or sessionStorage are unavailable, they will be faked to prevent errors, but data stored will NOT persist beyond the life of the current document/page. Look for the store.old.js extension to create persistent backing for the store API in older browsers.

Extensions & Experiments

Documentation on these is yet to be written, but several are available in the src folder already. Some even have tests in the repo already. All have their current status in the comments. Help developing these is welcome, of course.

Release History

(Nothing yet)