Naughty Program Manipulator

    ClientStorage

    3.0.1 • Public • Published

    Persistent Client (Browser) Storage

    • 👷 100% Tests coverage;
    • 📦 No external dependencies;
    • 💪 Bulletproof persistent Client storage;
    • ㊗️ With Unicode support for values and keys;
    • 👨‍💻 With String, Array, Object, and Boolean support as values;
    • ♿ Works with disabled localStorage and cookies.

    ClientStorage NPM library logo

    Install:

    npm install --save ClientStorage

    Install Meteor:

    # Via Atmosphere 
    meteor add ostrio:cstorage
    # Via NPM 
    meteor npm install --save ClientStorage

    Require:

    var ClientStorage = require('ClientStorage').ClientStorage;

    ES6 Import (Meteor):

    import { ClientStorage } from 'meteor/ostrio:cstorage';

    Usage:

    • ClientStorage.get('key') - Read a record. If the key doesn't exist a undefined value will be returned;
      • key - {String} - Record's key;
    • ClientStorage.set('key', value[, ttl]) - Create/overwrite a value in storage;
      • key - {String} - Record's key;
      • value - {String|[mix]|Boolean|Object} - Record's value (content);
      • ttl - {Number} — [Optional] Record's TTL in seconds;
    • ClientStorage.remove('key') - Remove a record;
      • key - {String} - Record's key;
    • ClientStorage.has('key') - Check whether a record exists, returns a boolean value;
      • key - {String} - Record's key;
    • ClientStorage.keys() - Returns an array of all storage keys;
    • ClientStorage.empty() - Empty storage (remove all key/value pairs). Use with caution! (May remove cookies which weren't set by you).

    Alternate usage:

    Use cookies only:

    To use cookies as a driver for ClientStorage create new instance of clientStorage (camel-case, first letter lower-case):

    var clientStorage  = require('ClientStorage').clientStorage;
    var csCookies = new clientStorage('cookies');
    csCookies.has('locale'); // false
    csCookies.set('locale', 'en_US'); // true

    or in ES6 (Meteor):

    import { clientStorage } from 'meteor/ostrio:cstorage';
    const csLocalStorage = new clientStorage('cookies');
    csLocalStorage.has('locale'); // false
    csLocalStorage.set('locale', 'en_US'); // true

    Use localStorage only:

    To use localStorage as a driver for ClientStorage create new instance of clientStorage (camel-case, first letter lower-case):

    var clientStorage  = require('ClientStorage').clientStorage;
    var csLocalStorage = new clientStorage('localStorage');
    csLocalStorage.has('locale'); // false
    csLocalStorage.set('locale', 'en_US'); // true

    or in ES6 (Meteor):

    import { clientStorage } from 'meteor/ostrio:cstorage';
    const csLocalStorage = new clientStorage('localStorage');
    csLocalStorage.has('locale'); // false
    csLocalStorage.set('locale', 'en_US'); // true

    Note: All instances are sharing same cookie and localStorage records!

    [Meteor] Add reactivity:

    import { ReactiveVar }   from 'meteor/reactive-var';
    import { ClientStorage } from 'meteor/ostrio:cstorage';
     
    const persistentReactive = (name, initial = false) => {
      let reactive;
      if (ClientStorage.has(name)) {
        reactive = new ReactiveVar(ClientStorage.get(name));
      } else {
        ClientStorage.set(name, initial);
        reactive = new ReactiveVar(initial);
      }
     
      reactive.set = function (newValue) {
        let oldValue = reactive.curValue;
        if ((reactive.equalsFunc || ReactiveVar._isEqual)(oldValue, newValue)) {
          return;
        }
        reactive.curValue = newValue;
        ClientStorage.set(name, newValue);
        reactive.dep.changed();
      };
     
      return reactive;
    };
     
    const UILayout = persistentReactive('UILayout', 'two-columns');
    UILayout.get(); // two-columns
    UILayout.set('single-column');

    Examples:

    var ClientStorage = require('ClientStorage').ClientStorage;
     
    ClientStorage.set('locale', 'en'); // true
    ClientStorage.set('country', 'usa'); // true
    ClientStorage.set('gender', 'male'); // true
     
    ClientStorage.get('gender'); // male
     
    ClientStorage.has('locale'); // true
    ClientStorage.has('city'); // false
     
    ClientStorage.keys(); // ['locale', 'country', 'gender']
     
    ClientStorage.remove('locale'); // true
    ClientStorage.get('locale'); // undefined
     
    ClientStorage.keys(); // ['country', 'gender']
     
    ClientStorage.empty(); // true
    ClientStorage.keys(); // []
     
    ClientStorage.empty(); // false

    Running Tests

    1. Clone this package
    2. In Terminal (Console) go to directory where package is cloned
    3. Then run:

    Meteor/Tinytest

    # Default 
    meteor test-packages ./
     
    # With custom port 
    meteor test-packages ./ --port 8888
     
    # With local MongoDB and custom port 
    MONGO_URL="mongodb://127.0.0.1:27017/client-storage-tests" meteor test-packages ./ --port 8888

    Support this project:

    Install

    npm i ClientStorage

    DownloadsWeekly Downloads

    64

    Version

    3.0.1

    License

    BSD-3-Clause

    Unpacked Size

    26.2 kB

    Total Files

    9

    Last publish

    Collaborators

    • dr.dimitru