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
import Storer from 'storer';
 
// ES5
var Storer = require('storer');

or you can simply grab storer.min.js file and load it in the <head> tag of yout html.

<script src="your-path/storer.min.js"></script>

How to use it

You can create a new instance of Storer class or directly use Storer's static methods

// creating a new instance
const storer = new Storer('myStore');
storer.set('foo', 'bar');
storer.set({ my:'value' });
 
// calling static method "set"
Storer.set('foo', 'bar');

Paths

Every method accepts a path as the key to search, so, for example, you can:

// creating a new instance
const storer = new Storer('myStore');
storer.set('foo', {
  names: [
    { name:'bar' },
    { name: 'xxx' }
  ]
}).then(value => {
  const name = storer.get('names[0].name');
  console.log(name); // 'bar'
})

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 namespace
Storer.set('foo', 'bar');
 
// calling static method "remove", where 'foo' will be the namespace
Storer.remove('foo');
 
// calling static method "create". It will create a new instance o Storer
const storer = Storer.create('foo');

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 string
const storer = new Storer('myStore');
 
// options as object
const storer = new 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 value
storer.set('foo');
storer.set({ foo:'bar' });
 
// Search the key and fill it with the value
storer.set('foo', 'bar');
 
// Search following the path and fill it with the value
storer.set('foo.bar[0].anotherKey', 'newValue');

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 value
storer.set('foo.bar[1]', 'newValue');
 
// Push the value to the new last index
storer.set('foo.bar[]', 'newPushedValue');
 
// If index to insert to is higher than array length, Storer manage ir and push it correctly
storer.set('foo.bar[25]', 'newPushedValue');

If callback function is present, will be invoked. Promise callbacks will always be invoked

// callback
storer.set('foo.bar[1]', 'newValue', value => console.log(value));
 
// Push the value to the new last index
storer.set('foo.bar[]', 'newPushedValue')
  .then(value => console.log(value))
  .catch(error => console.error(error))

And finally, you can listen to EventEmitter to wait the updating of the value

// listen to
storage.on('set', value => console.log(value))

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 key
storer.remove('foo');
 
// Remove by path
storer.remove('foo.bar[0].anotherKey');
 
// Success callback
storer.remove('foo.bar[0].anotherKey', store => {
  console.log('everything went well')
});
 
// Success Promise
storer.remove('foo.bar[0].anotherKey')
  .then(store => console.log(store))
  .catch(error => console.error(error))

Also, you can listen to EventEmitter to wait the updating of the value

// listen to
storage.on('remove', value => console.log(value))

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 key
storage.get('foo')
 
// search by path
storage.get('foo.bar[0].name')

You can pass multiple params to get multiple value in an array

// multiple keys/paths
storage.get('foo', 'xxx', 'foo.bar[0].name', 'bar') // 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 key
storage.pick('foo') // { foo:'bar' }
 
// search by path
storage.pick('foo.bar[0].name') // { name:'bar' }

You can pass multiple params to get multiple value in an array

// multiple keys/paths
storage.pick('foo', 'xxx', 'foo.bar[0].name', 'bar') // 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 key
storage.has('foo') // true
 
// search by path
storage.pick('foo.bar[0].name') // 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/paths
storage.has('foo', 'xxx', 'foo.bar[0].name', 'bar');

keys()

Get all the keys in namespace. Return an array of keys.

// get all keys
storage.keys()

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 callbacks
storage.loop(( value, key, i ) => {
  console.log(value, key, i);
}, store => {
  //everything went well
  console.log(store);
})

Also, you can get success moment with Promise

// loop with callbacks
storage.loop(( value, key, i ) => {
  console.log(value, key, i);
})
.then(store => console.log(store))
.catch(error => console.error(error))

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 object
storage.reset();
 
// reset and replace namespace with the new content
storage.reset({ foo:'bar' });
 
// reset and replace namespace with the new content in SessionStorage
storage.reset({ foo:'bar' }, 'session');
 
// listen to reset event
storage.on('reset', store => console.log(store))

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 object
storage.clear();
 
// reset and replace namespace with the new content in SessionStorage
storage.reset({ foo:'bar' }, 'session');
 
// listen to clear event
storage.on('clear', store => console.log(store))

all()

Get all content of namespace

// get all content
storage.all();

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 object
storage.switchStore('session');
 
// listen to clear event
storage.on('switch', (type, store) => console.log(type, store))

toSession()

Switch storage type to SessionStorage.

// switch to session
storage.toSession();

toLocal()

Switch storage type to LocalStorage.

// switch to local
storage.toLocal();

destroy()

Destroy namespace on both Local and Session Storage. Also removes memory vars.

// Destroy
storage.destroy();
 
// listen to destroy event. Will be invoked before destroy.
storage.on('before.destroy', store => console.log(store))

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 number
storage.setExpired(8000)
 
// set expired number with callback
storage.setExpired(8000, (error, value) => console.log(value))
 
// set expired number with Promise
storage.setExpired(8000)
  .then(value => console.log(value))
  .catch(error => console.error(error))
 
// set expired listener
storage.on('set.expired', value => console.log(value))

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 expired
storage.removeExpired(8000)
 
// remove expired with callback
storage.removeExpired(8000, (error, value) => console.log(value))
 
// remove expired with Promise
storage.removeExpired(8000)
  .then(value => console.log(value))
  .catch(error => console.error(error))
 
// remove expired listener
storage.on('remove.expired', value => console.log(value))

isExpired()

Check if expiration time is exceeded

// remove expired
storage.isExpired() // true | false

clearExpireds( type )

Clear all expired entries from Storage.

type: Storage type (local | session)

// clear expired eentries
storage.clearExpireds('local')
 
// This method is also a static method of Storer, so you can invoke it without creating a new instance
Storage.clearExpireds('session')
 
// Also, you can import it as a ES6 module
import { clearExpired } from 'storer';
clearExpireds('local')

License

MIT

TODO

Unit testing (in process)
Fallback to cookies if Storage is not supported

storer

Storer

Installation

How to use it

Paths

Expiration

API

Storer

new Storer( namespace | { options } )

set( (value | key, value | path, value), callback( error | value ) )

remove( key | path, successCallback )

get( key | path )

pick( key | path )

has( key | path )

keys()

loop( iteratorCallback | successCallback )

reset( value, type )

clear( type )

all()

switchStore( type )

toSession()

toLocal()

destroy()

Expiration API

setExpired( expiration, callback )

removeExpired( callback )

isExpired()

clearExpireds( type )

License

TODO

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads