/Client-Storage

🗄 Bulletproof persistent Client storage, works with disabled Cookies and/or localStorage

Primary LanguageJavaScriptBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

support support

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;
  • ☄️ Meteor.js-specific docs
  • 📦 Available via NPM and Atmosphere.

ClientStorage NPM library logo

Install:

npm install --save ClientStorage

Require:

const ClientStorage = require('ClientStorage').ClientStorage;
const clientStorage = new ClientStorage();

ES6 Import:

import { ClientStorage } from 'ClientStorage';
const 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).

Storage-specific 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:

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

Use localStorage only:

Pass localStorage as an argument to new instance of ClientStorage:

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

Use js only:

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

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

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

Examples:

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

Tests are written using Tiny, follow testing instruction in meteor docs

Support this project: