Persistent Client (Browser) Storage
- 😎 No external dependencies;
- 💪 Bulletproof persistent Client storage;
- ㊗️ Support for Unicode values and keys;
- 👨💻 Support for
String
,Array
,Object
, andBoolean
as values; - ♿ Works with disabled
localStorage
andcookies
; - 👷♂️ 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
- Clone this package
- In Terminal (Console) go to directory where package is cloned
- 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.