Persistent Browser (Client) 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;
• Available via 📦 NPM and ☄️ Atmosphere.

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;
2var clientStorage = new ClientStorage();

ES6 Import:

1import { ClientStorage } from 'ClientStorage';
2const clientStorage = new ClientStorage();

ES6 Import (Meteor):

1import { ClientStorage } from 'meteor/ostrio:cstorage';
2const clientStorage = new ClientStorage();

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:

By default ClientStorage package handle selecting storage driver in the next order (descending priority):

1. localStorage
2. cookies
3. js (JS Object driven storage)

To alter priority pass "preferred driver" to new ClientStorage(driverName) constructor.

Use cookies only:

Pass cookies as an argument to new instance of ClientStorage:

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

Use localStorage only:

Pass localStorage as an argument to new instance of ClientStorage:

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

Use js only:

Pass js (in-memory js object) as an argument to new instance of ClientStorage:

1const { clientStorage } = require('ClientStorage');
2var jsStorage = new ClientStorage('js');
3jsStorage.has('locale'); // false
4jsStorage.set('locale', 'en_US'); // true

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

[Meteor] Add reactivity:

Persistent ReactiveVar implementation:

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

Examples:

1const clientStorage = new (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

# 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:

• Sponsor via GitHub
• Support via PayPal
• Use ostr.io — Monitoring, Analytics, WebSec, Web-CRON and Pre-rendering for a website