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
, andBoolean
support as values; - ♿ Works with disabled
localStorage
andcookies
; - 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):
localStorage
cookies
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
- Clone this package
- In Terminal (Console) go to directory where package is cloned
- 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