boxcrate

BoxCrate

A smart wrapper for the browser's localStorage that allows you to set and get items as they are with optional expiration times.

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:

1. '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.

2. '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