Storer
Storer is a storage library that extendes functionality of LocalStorage and SessionStorage. It is completly written in ECMAScript 6 and ready to use in current Javascript language (UMD), so you can use in both ways.
Setter methods are prepared for listen to function callbacks, Promises and, if you want to include it, EventEmitter2 listeners.
Creating a new instance of Storer, automatically will be created a new entry in Local/Session storage using the key you choose in instance options. Every new Storer instance will be a new entry in Local/Session storage, so this namespace will be your root of data. Storer handles itself to manage the data inside using Objects, Arrays, etc. Also, Storer is exposed to window in window.Storer
ready to use in any place.
Installation
$ npm install storer
and in your js
// ES6; // ES5var Storer = ;
or you can simply grab storer.min.js
file and load it in the <head>
tag of yout html.
How to use it
You can create a new instance of Storer class or directly use Storer's static methods
// creating a new instanceconst storer = 'myStore';storer;storer; // calling static method "set"Storer;
Paths
Every method accepts a path as the key to search, so, for example, you can:
// creating a new instanceconst storer = 'myStore';storer
When the value of your namespace is an object, you can access to a property by a path.
- Nested entries with a dot
.
- Array entries with brackets and its index
[x]
Expiration
It's possible to add an expiration time to an Storer instance. Simply add to its options a expiration
property an a number as value (number in milliseconds). Storer will manage it internally in multiple ways, setting a timeOut for each Storer instance, and checking for expired entries in Storage on window load and beforeunload.
In addition, Storer has some methods to manage this functionality like setExpired, removeExpired, isExpired and clearExpireds. Checkout the Expiration API.
API
Storer
Storer class variable. If is used without creating a new instance, you can call set, remove and create methods
// calling static method "set", where 'foo' will be the namespaceStorer; // calling static method "remove", where 'foo' will be the namespaceStorer; // calling static method "create". It will create a new instance o Storerconst storer = Storer;
new Storer( namespace | { options } )
Arguments expected are namespace and type. You can pass it as String options or Object.
- namespace: Store namespace
- options: Object that can contain:
- namespace: Store namespace
- type: Storage type. (local | session)
- expiration: Time to be expired for the entry in milliseconds (number)
// options as stringconst storer = 'myStore'; // options as objectconst storer = namespace: 'foo' type: 'session' expiration: 4000;
set( (value | key, value | path, value), callback( error | value ) )
Set a new at the specific key/path or fill the namespace with a value
- value: Any value type (string | number | boolean | object | array)
- key, value: Search specific key in namespace entry and, if found it, fill it with value
- path, value: Search following the path specific entry and, if found it, fill it with value
- callback: If callback function is present, will be invoked after setting the value
// Fill namespace with a valuestorer;storer; // Search the key and fill it with the valuestorer; // Search following the path and fill it with the valuestorer;
If path's value is an array, you can determine wich index to update or push the new value
// Update the index 1 with the valuestorer; // Push the value to the new last indexstorer; // If index to insert to is higher than array length, Storer manage ir and push it correctlystorer;
If callback function is present, will be invoked. Promise callbacks will always be invoked
// callbackstorer; // Push the value to the new last indexstorer
And finally, you can listen to EventEmitter to wait the updating of the value
// listen tostorage
remove( key | path, successCallback )
Set a new at the specific key/path or fill the namespace with a value
- key: Search specific key in namespace entry and, if found it, remove the value
- path: Search following the path specific entry and, if found it, remove the value
- successCallback: callback function invoked when it reaches the end
// Remove by keystorer; // Remove by pathstorer; // Success callbackstorer; // Success Promisestorer
Also, you can listen to EventEmitter to wait the updating of the value
// listen tostorage
get( key | path )
Get the value of a key or path
- key: Search specific key in namespace entry and, if found it, get the value
- path: Search following the path specific entry and, if found it, get the value
// search by keystorage // search by pathstorage
You can pass multiple params to get multiple value in an array
// multiple keys/pathsstorage // Array of four values
pick( key | path )
Get the key/value pair of a key or path
- key: Search specific key in namespace entry and, if found it, get the key/value pair
- path: Search following the path specific entry and, if found it, get the key/value pair
// search by keystorage // { foo:'bar' } // search by pathstorage // { name:'bar' }
You can pass multiple params to get multiple value in an array
// multiple keys/pathsstorage // Array of four key/value pairs
has( key | path )
Check if a key or path exists in namespace
- key: Search specific key in namespace entry and, if found it, return true
- path: Search following the path specific entry and, if found it, return true
// search by keystorage // true // search by pathstorage // true
You can pass multiple params to get multiple value in an array. To return true, every argument has to exist in namespace
// multiple keys/pathsstorage;
keys()
Get all the keys in namespace. Return an array of keys.
// get all keysstorage
loop( iteratorCallback | successCallback )
Iterate through store returning key/value pairs
- iteratorCallback: callback function of every iteration
- successCallback: callback function invoked when it reaches the end
// loop with callbacksstorage
Also, you can get success moment with Promise
// loop with callbacksstorage
reset( value, type )
Reset namespace with the value. If value is missing, reset with an empty object.
- value: value to replace the namespace content
- type: Storage type to reset the namespace (local | session | undefined) If undefined, will use actually using storage
// reset with an empty objectstorage; // reset and replace namespace with the new contentstorage; // reset and replace namespace with the new content in SessionStoragestorage; // listen to reset eventstorage
clear( type )
Remove namespace entry of storage, choosing between "local" & "session"
- type: Storage type to reset the namespace (local | session | undefined) If undefined, will use actually using storage
// reset with an empty objectstorageclear; // reset and replace namespace with the new content in SessionStoragestorage; // listen to clear eventstorage
all()
Get all content of namespace
// get all contentstorageall;
switchStore( type )
Switch storage type choosing between "local" & "session". After execute this method, all methods will be used in the corresponding storage type.
- type: Storage type to reset the namespace (local | session)
// reset with an empty objectstorage; // listen to clear eventstorage
toSession()
Switch storage type to SessionStorage.
// switch to sessionstorage;
toLocal()
Switch storage type to LocalStorage.
// switch to localstorage;
destroy()
Destroy namespace on both Local and Session Storage. Also removes memory vars.
// Destroystorage; // listen to destroy event. Will be invoked before destroy.storage
Expiration API
setExpired( expiration, callback )
Set expired time to the entry. It will be created a new reference entry to manage it.
- expiration: Expired number in milliseconds
- callback: callback function invoked when everythings went well
// set expired numberstorage // set expired number with callbackstorage // set expired number with Promisestorage // set expired listenerstorage
removeExpired( callback )
Remove expired time to the entry. It will be removed a reference entry from Storage.
- callback: callback function invoked when everythings went well
// remove expiredstorage // remove expired with callbackstorage // remove expired with Promisestorage // remove expired listenerstorage
isExpired()
Check if expiration time is exceeded
// remove expiredstorage // true | false
clearExpireds( type )
Clear all expired entries from Storage.
- type: Storage type (local | session)
// clear expired eentriesstorage // This method is also a static method of Storer, so you can invoke it without creating a new instanceStorage // Also, you can import it as a ES6 module;
--
License
MIT
TODO
- Unit testing (in process)
- Fallback to cookies if Storage is not supported