LockerJS - HTML5 Storage Wrapper

Extremely light library that makes HTML5 storage usage easier to the edge. No dependencies, no configuration.

Installation

NPM

npm install --save lockerjs

Yarn

yarn add lockerjs

Usage

import Locker from 'lockerjs';

const locker = new Locker(window.localStorage);
// or
const locker = new Locker(window.sessionStorage);

Features

add

setItem does the job, although it is quite limited as it accepts only String - String values. By using LockerJS you are no longer limited by value types! Saving object with key 1 is as easy as:

const myObj = {
    'name': 'John',
    'surname': 'Test',
};
locker.add(1, myObj);

Isn't that easy? You can use any parameter type as your key and value;

addSafely

Only adds value to specific key if a given key is not already used. Otherwise throws an error.

locker.addSafely('Key 1', 1); //OK
locker.addSafely('Key 1', 123); //ReferenceError: 'Provided key is already in use'

get

getItem allows you to retrieve text value from storage by passing key, but wouldn't that be great just to pass any parameter type? Consider this snippet:

locker.get(123);

Isn't that as easy as one-two-three? There's more! Locker will return you an original value type!

const myArr = [1, 2, 3];
locker.add(1, myArr);
const retrievedArr = locker.get(1);
typeof retrievedArr; // "array"
console.log(retrievedArr); // [1, 2, 3]

Of course, same goes for numbers, objects, ES6 Maps etc.

keyExists

Simply returns true if a given key has been already used, otherwise false

locker.add(2, 1234);
locker.keyExists(2) // True
locker.keyExists({'name': 'John'}) // False

valueExists

Simply returns true if a given value has been already used, otherwise false.

const mySet = new Set();
mySet.set("Some array", [1, 2, 3]);
locker.add(mySet);
locker.valueExists(mySet); // True

clear

Clear the whole storage

locker.add(1, [1, 2]);
locker.clear(); //Empty

size

Returns the size of the storage

locker.add(12, [1,2]);
locker.size(); //2

clearSpecified

Pass an array of keys that shall be removed and Locker will remove only those entries

const testObj = {
    'name': 'John',
}
locker.add(testObj, "We like this customer!");
locker.add(1, 123);
const keysToRemove = ['1', testObj];
locker.clearSpecified(keysToRemove); // Empty

As you have noticed you can mix & match all value types to your preferences.

saveMap

Convert & copy keys and values from ES6 Map into storage.

const sampleMap = new Map();
map.set(1, 'First entry');
map.set(2, 'Second entry');
locker.clear();
locker.saveMap(sampleMap);
locker.get(1); // 'First entry'
locker.get(2); // 'Second entry'

getMap

If you would like to get a 'backup' of client's storage you can do so by invoking saveMap(). It will construct ES6 Map from storage.

locker.add(1, [1, 2, 3]);
const backup = locker.getMap();

Contributing

Issues

Please raise any issues using a template inside ./github folder.

Pull requests

All PRs are more than welcome! Please run

npm test

before submitting a merge request.

License

MIT