smartstorage

    0.1.2 • Public • Published

    SmartStorage - Smarter localstorage API

    Build Status

    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

    Install

    npm i smartstorage

    DownloadsWeekly Downloads

    0

    Version

    0.1.2

    License

    MIT

    Last publish

    Collaborators

    • ikep