boxcrate
v2.1.1
Published
A smart wrapper for the browser's localStorage that allows you to set and get items as they are with optional expiration times.
Downloads
2
Maintainers
Readme
Installation
To install this module through npm, simply use the following command:
$ npm install --save boxcrate
To use it as an ES6 module you can either install it through npm or download it directly and import it as so:
import BoxCrate from './node_modules/boxcrate/boxcrate.js';
Initialization
After installing BoxCrate, a new instance can be created like so:
const boxcrate = new BoxCrate();
There are two optional initialization options for BoxCrate which deal with the expiration of data.
If you don't specify a type of expiration check to perform, none will be u sed.
Also note that you can choose to not put an expiration date on any item you set which means it will not expire ever.
| param | type | description | default | |------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|---------| | options | Object | | | | options.expiredCheckType | string | The type of expiration check to perform. (Either 'passive' or 'active') | null | | options.expiredCheckInterval | number | If you select the passive expiration check type, you can specify the interval of time in which data is checked for expired items. | 1000 |
The options for expiredCheckType
are as follows:
'passive': With the type set to 'passive', whenever an item is set to be retrieved from localStorage, it is checked to see if it is expired and if so deleted and never retrieved.
Advantage: Very passive type of check, minimal performance cost.
Disadvantage: The item could be expired for a long time and still be accessible directly in the localStorage through the browser if the user checks it themselves.
'active': Every x seconds the localStorage will be checked for expired values and if found, they will be removed.
Advantage: Very active type of check, expired values are removed almost instantly.
Disadvantage: Performance cost is highest.
API
BoxCrate aims to replicate the API of localStorage so it feels seamless switching over.
storage
Returns a reference to the storage. Note, this should not be modified as it will affect the original storage also.
example:
const storage = boxcrate.storage;
count
Returns the number of items saved in BoxCrate's storage.
example:
const numOfItems = boxcrate.count;
setItem
Set item lets you save an item to BoxCrate's storage using a key, value, and optional expiration time.
One of the advtanges of using BoxCrate is when saving an item to the storage, you can save it as is. Normally with localStorage you can only save strings but BoxCrate lets you save strings, numbers, arrays, and objects as they are and they will be retrieved in the same format.
The only exception to this are Symbols which cannot be saved and retrieved as is as they are unique and when retrieving it the Symbol would not be equal to the original Symbol.
| param | type | description | default | |------------|--------|------------------------------------------------------------------------------------------|---------| | key | string | A unique key to use for the saved item. | | | value | string | The item to save. | | | msToExpire | number | The time, in milliseconds, until this key value pair should be removed from the storage. | |
example:
const pizzaToppings = ['Cheese', 'Pepperoni', 'Spinach'];
boxcrate.setItem('toppings', pizzaToppings);
getItem
Retrieve an item from BoxCrate's storage. The item will be retrieved in the same format it was saved.
| param | type | description | default | |-------|--------|----------------------------------------|---------| | key | string | The key of the saved item to retrieve. | |
example:
const toppings = boxcrate.getItem('toppings');
console.log(toppings);
// => ['Cheese', 'Pepperonoi', 'Spinach']
removeItem
Remove a saved item from the storage by its key.
| param | type | description | default | |-------|--------|--------------------------------------|---------| | key | string | The key of the saved item to remove. | |
example:
boxcrate.removeItem('toppings');
clear
Remove all saved items from BoxCrate's storage.
example:
boxcrate.clear();
Tests
Since BoxCrate's tests are run in the browser, you have to run:
$ npm run test
and then in your browser, go to http://localhost:8888/test/index.html
to run the test suite.
License
MIT