ClientStorage

Warning

ClientStorage is deprecated on npm. Use @veliovgroup/client-storage going forward.

Bulletproof persistent browser storage. Drivers: localStorage > cookies > js (in-memory). TTL, JSON values (objects/arrays/booleans/null/undefined), Unicode. No deps. Meteor + NPM + full TS 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.

Install

npm install @veliovgroup/client-storage

Usage

// NPM / TS / ESM
import { ClientStorage } from '@veliovgroup/client-storage';
const storage = new ClientStorage(); // auto or 'localStorage' | 'cookies' | 'js'

Values

Values pass through JSON serialization when stored in persistent drivers.

const storage = new ClientStorage();

storage.set('locale', 'en');
storage.set('user', { id: 1, prefs: { theme: 'dark' } }, 3600);
storage.set('flags', ['beta', 'compact']);
storage.set('enabled', true);
storage.set('empty', null);
storage.set('void', undefined);

storage.get('user');     // { id: 1, prefs: { theme: 'dark' } }
storage.has('void');     // true
storage.get('void');     // undefined
storage.keys();          // non-expired keys

TTL

storage.set('session', 'secret', 30);

storage.get('session'); // 'secret'
// after 30 seconds:
storage.get('session'); // undefined, record removed

Drivers

new ClientStorage();             // auto: localStorage -> cookies -> js
new ClientStorage('localStorage');
new ClientStorage('cookies');
new ClientStorage('js');         // in-memory, per instance

Important

Multiple instances: Persistent drivers (localStorage/cookies) share data; js has isolated context per each instance. Server-side code uses js because browser storage APIs do not exist there.

API

• storage.set(key: string, value: any, ttl?: number): boolean — Store. TTL in seconds.
• storage.get(key: string): any | undefined — Read. Auto-removes expired. undefined if missing.
• storage.has(key: string): boolean — Exists and not expired.
• storage.remove(key?: string): boolean — Remove key or all (empty).
• storage.empty(): boolean — Alias for remove(). Caution: clears tracked keys; may affect other cookies if no prefix.
• storage.keys(): string[] — Current keys.
• storage.driverName — Active driver.

storage.set(key: string, value: any, ttl?: number): boolean
storage.get(key: string): any
storage.has(key: string): boolean
storage.keys(): string[]
storage.remove(key?: string): boolean
storage.empty(): boolean
storage.driverName: 'localStorage' | 'cookies' | 'js'

TS: Full types included. See index.d.ts. Use with import type { ClientStorage } from '@veliovgroup/client-storage';

• ttl is seconds.
• get() and has() remove expired records before returning.
• keys() returns non-expired keys.
• remove(key) removes one record.
• remove() and empty() remove all records known to selected backend.
• js driver is in-memory and isolated per ClientStorage instance.
• localStorage and cookies persist across instances on same origin.

Tip

Drivers exported: ClientStorage, BaseStorage, BrowserStorage, CookiesStorage, JSStorage.

Examples

const storage = new ClientStorage();

storage.set('locale', 'en');
storage.set('user', { id: 1, prefs: { theme: 'dark' } }, 3600); // 1hr TTL
storage.set('flag', true);

console.log(storage.get('user')); // {id:1, prefs:...}
console.log(storage.has('locale')); // true
console.log(storage.keys()); // ['locale', 'user', 'flag']

storage.remove('locale');
storage.empty(); // clears all

Tests

• Jest (NPM): npm test — covers API, edges, errors, drivers, BaseStorage.

npm test

100% functional coverage. See client-storage-tests.js, tests/client-storage.test.js.

Support this project

• Upload and share files using ☄️ meteor-files.com — Continue interrupted file uploads without losing any progress. There is nothing that will stop Meteor from delivering your file to the desired destination
• Use ▲ ostr.io for Server Monitoring, Web Analytics, WebSec, Web-CRON and SEO Pre-rendering of a website
• Star on GitHub
• Star on NPM
• Star on Atmosphere
• Sponsor via GitHub
• Support via PayPal