Persistent Client (Browser) Storage

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

Install:

npm install --save ClientStorage

Install Meteor:

# Via Atmosphere
meteor add ostrio:cstorage

# Via NPM
meteor npm install --save ClientStorage

Require:

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

ES6 Import (Meteor):

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

Usage:

• ClientStorage.get('key') - Read a record. If the key doesn't exist a null value will be returned;
  • key - {String} - Record's key;
• ClientStorage.set('key', value) - Create/overwrite a value in storage;
  • key - {String} - Record's key;
  • value - {String|[mix]|Boolean|Object} - Record's value (content);
• 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):

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

or in ES6 (Meteor):

1import { clientStorage } from 'meteor/ostrio:cstorage';
2const csLocalStorage = new clientStorage('cookies');
3csLocalStorage.has('locale'); // false
4csLocalStorage.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):

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

or in ES6 (Meteor):

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

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

[Meteor] Add reactivity:

1import { ReactiveVar }   from 'meteor/reactive-var';
2import { ClientStorage } from 'meteor/ostrio:cstorage';
3
4const persistentReactive = (name, initial = false) => {
5  let reactive;
6  if (ClientStorage.has(name)) {
7    reactive = new ReactiveVar(ClientStorage.get(name));
8  } else {
9    ClientStorage.set(name, initial);
10    reactive = new ReactiveVar(initial);
11  }
12
13  reactive.set = function (newValue) {
14    let oldValue = reactive.curValue;
15    if ((reactive.equalsFunc || ReactiveVar._isEqual)(oldValue, newValue)) {
16      return;
17    }
18    reactive.curValue = newValue;
19    ClientStorage.set(name, newValue);
20    reactive.dep.changed();
21  };
22
23  return reactive;
24};
25
26const UILayout = persistentReactive('UILayout', 'two-columns');
27UILayout.get(); // two-columns
28UILayout.set('single-column');

Examples:

1var ClientStorage = require('ClientStorage').ClientStorage;
2
3ClientStorage.set('locale', 'en'); // true
4ClientStorage.set('country', 'usa'); // true
5ClientStorage.set('gender', 'male'); // true
6
7ClientStorage.get('gender'); // male
8
9ClientStorage.has('locale'); // true
10ClientStorage.has('city'); // false
11
12ClientStorage.keys(); // ['locale', 'country', 'gender']
13
14ClientStorage.remove('locale'); // true
15ClientStorage.get('locale'); // undefined
16
17ClientStorage.keys(); // ['country', 'gender']
18
19ClientStorage.empty(); // true
20ClientStorage.keys(); // []
21
22ClientStorage.empty(); // false

Running Tests

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

Meteor/Tinytest

meteor test-packages ./

Support our open source contribution:

This project wouldn't be possible without ostr.io.

Using ostr.io you are not only protecting domain names, monitoring websites and servers, using Prerendering for better SEO of your JavaScript website, but support our Open Source activity, and great packages like this one are available for free.