SmartStorage - Smarter localstorage API

An HTML5 localStorage helper library that extends the native localStorage API through Javascript. It offers a more efficient and robust way of retrieving, setting and updating important information needed for your web application, with built-in callback support. This library also includes support for older browsers that don't natively support the localStorage API.

Installation

Via Bower

$ bower install smartstorage

Via NPM

$ npm install smartstorage

Extract and link to the library

<script src='smartstorage.min.js'></script>

SmartStorage constructor

Extends the window.localStorage API.

Constructor Methods

First, create a new instance of the SmartStorage class

var lstorage = new SmartStorage();

SmartStorage.set(key, val, expiry)

Extends the native window.localStorage.setItem() method allowing for object and array saving, plus returning the saved element.

lstorage.set('animal', {type: 'dog'}, 60); // stores and returns {type: 'dog'} (that expires in 60 seconds)

You can chain methods

lstorage
  .set('name', 'john', 60*60)
  .get('name') // Returns 'john'

SmartStorage.get(key)

Extends the native window.localStorage.getItem() method allowing for object and array retrieving.

lstorage.get('animal'); // returns {type: 'dog'}

or with a callback

lstorage.get('animal', function(value) {
  return `My favorite animal is a ${value.type}`; // returns "My favorite animal is a dog"
});

SmartStorage.setBulk(obj)

Allows you to execute a bulk storage of key-value pairs in an object being passed in.

var things = {
  color: "blue",
  language: "Javascript",
  groceries: { ketchup: 3.00, lettuce: 6.00 }
};

lstorage.setBulk(things); // equivalent to setting each local storage key to corresponding value individually

You can also chain the method

lstorage
  .setBuik(things)
  .get('animal') // returns {type: 'dog'}

SmartStorage.isEmpty()

Returns a true or false depending on if any key-value pairs are found in local storage.

lstorage.set('name', 'john', 60*60);
lstorage.isEmpty(); // returns false

ls.clear(); // clears localStorage
ls.isEmpty(); // returns true

or with a callback

lstorage.isEmpty(function(isEmpty) {
  return `LocalStorage is currently empty: ${isEmpty}`;
});

SmartStorage.getKeys()

Returns an array of keys found in window.localStorage.

var things = {
  color: "blue",
  language: "Javascript",
  groceries: { ketchup: 3.00, lettuce: 6.00 }
};

lstorage.setBulk(things);

lstorage.getKeys(); // returns ['color', 'language', 'groceries'];

SmartStorage.getAll()

Returns an array of all values in window.localStorage.

var things = {
  color: "blue",
  language: "Javascript",
  groceries: { ketchup: 3.00, lettuce: 6.00 }
};

lstorage.setBulk(things);

lstorage.getAll(); // returns ['blue', 'Javascript', { ketchup: 3.00, lettuce: 6.00 }];

or with a callback

lstorage.getAll(function(result) {
  // Do something with the result
});

SmartStorage.toObject()

Returns an object representation of current window.localStorage key-value pairs.

var things = {
  color: "blue",
  language: "Javascript",
  groceries: { ketchup: 3.00, lettuce: 6.00 }
};

lstorage.setBulk(things);

lstorage.toObject(); // { color: "blue", language: "Javascript", groceries: { ketchup: 3.00, lettuce: 6.00 }}

or with a callback

lstorage.toObject(function(obj) {
  // use the data in how you want
  for (key in obj) {
    // loop through
  }
});

SmartStorage.pushTo(key, item or array)

Allows you to push data (Single item or Array) to an existing Array stored in localstorage

lstorage.set('names', ['John', 'Jane'];
lstorage.pushTo('names', 'Joe');
lstorage.get('names') // Returns updated array ['John', 'Jane', 'Joe']

SmartStorage.extend(key, mergeObj)

Allows you to extend an existing object stored in localstorage

let extraInfo = {gender: 'M', eyeColor: 'brown'};

lstorage.set('person', {name: 'Tim', age: 25};
lstorage.extend('person', extraInfo);
lstorage.get('person') // Returns updated object {gender: 'M', eyeColor: 'brown', gender: 'M', eyeColor: 'brown'}

SmartStorage.remove(key)

Extends the native window.localStorage.remove() method allowing for deletion based on index number as well. Returns true if the key was found before deletion, false if not.

lstorage.set('name', 'Joe');
lstorage.remove('name'); // removes 'name' item in localStorage

SmartStorage.size()

Returns the number of keys stored in window.localStorage.

lstorage.set('name', 'Joe');
lstorage.size(); // 1

SmartStorage.has(key)

Returns either true or false depending on if the key exists.

or with a callback

lstorage.has('someKey',function(exists) {
  return `This key exists: ${exists}`;
});

SmartStorage.setProperty(key, property, value, expiry)

Updates an existing localStorage Key if it exists by updating the property value provided and also updating the expiry. If the key does not exists then it creates a new window.localStorage key using the SmartStorage.set() method in our constructor.

var car = {
  make: "Honda",
  model: "Accord"
};
  
lstorage.set('vehicle', car);
lstorage.setProperty('vehicle', 'model', 'civic', 3600); // updates the 'vehicle' key-value object from a model of Accord to Civic

SmartStorage.clear()

Extends the native window.localStorage.clear() method returning the total of items cleared.

Running Tests

Unit Tests

Run unit tests powered by Mocha and Chai Since the window.localStorage API is meant to be ran in the browser, run the test but opening up test/index.html file in your browser and see the results.

Linting

$ npm run lint