Meteor Community Logo

Meteor Community

Packosphere

undefined's Avatar

ostrio:cstorage

v5.0.0•Published 2 weeks ago

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.

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 @veliovgroup/client-storage

Usage

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

Values

Values pass through JSON serialization when stored in persistent drivers.

1const storage = new ClientStorage();
2
3storage.set('locale', 'en');
4storage.set('user', { id: 1, prefs: { theme: 'dark' } }, 3600);
5storage.set('flags', ['beta', 'compact']);
6storage.set('enabled', true);
7storage.set('empty', null);
8storage.set('void', undefined);
9
10storage.get('user');     // { id: 1, prefs: { theme: 'dark' } }
11storage.has('void');     // true
12storage.get('void');     // undefined
13storage.keys();          // non-expired keys

TTL

1storage.set('session', 'secret', 30);
2
3storage.get('session'); // 'secret'
4// after 30 seconds:
5storage.get('session'); // undefined, record removed

Drivers

1new ClientStorage();             // auto: localStorage -> cookies -> js
2new ClientStorage('localStorage');
3new ClientStorage('cookies');
4new 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.
1storage.set(key: string, value: any, ttl?: number): boolean
2storage.get(key: string): any
3storage.has(key: string): boolean
4storage.keys(): string[]
5storage.remove(key?: string): boolean
6storage.empty(): boolean
7storage.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

1const storage = new ClientStorage();
2
3storage.set('locale', 'en');
4storage.set('user', { id: 1, prefs: { theme: 'dark' } }, 3600); // 1hr TTL
5storage.set('flag', true);
6
7console.log(storage.get('user')); // {id:1, prefs:...}
8console.log(storage.has('locale')); // true
9console.log(storage.keys()); // ['locale', 'user', 'flag']
10
11storage.remove('locale');
12storage.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