variant-web-storage

Web Storage with support for complex data types.

The Web Storage API requires values to be stored as strings. You can use variant-web-storage to expand the set of supported data types. This thin wrapper handles conversions between developer-friendly types and web storage requirements.

Install

npm install variant-web-storage

Usage

Minimal example

Store and retrieve a Set from localStorage

import { fromStorage } from 'variant-web-storage';

const variantStorage = fromStorage(localStorage);
variantStorage.set('foo', new Set(['bar', 'baz']));
variantStorage.get('foo'); // returns Set(2) { 'bar', 'baz' }

Extended example

Retrieve session state- if available. Otherwise, use and persist the default.

import { fromStorage, KEY_NOT_FOUND } from 'variant-web-storage';

type Store = { mode: 'default' | 'light' | 'dark'; items: Set<string> };
const DEFAULT: Store = {
  mode: 'default',
  items: new Set(),
};

const variantStorage = fromStorage(sessionStorage);

// get object shaped like `Store` from sessionStorage at key 'session-store'
let store = variantStorage.get<Store>('session-store');

if (store === KEY_NOT_FOUND) {
  // sessionStorage had no 'session-store' key. use and save the `DEFAULT`
  variantStorage.set('session-store', (store = DEFAULT));
}

store; // returns { mode: 'default', items: Set(0) {} }

Find additional examples in the test/ directory.

Data types

Supported types are formally defined as follows (and include circular, referential, and deeply-nested values).

type SupportedValue =
  | Array<SupportedValue>
  | BigInt
  | Date
  | Map<SupportedValue, SupportedValue>
  | RegExp
  | Set<SupportedValue>
  | boolean
  | null
  | number
  | string
  | undefined
  | { [k in string | number]: SupportedValue };

Known limitations include:

• functions
• instances of custom classes
• weak sets/maps

Internals

Value /(en|de)coding/ is largely handled by the awesome (read: schema-inferring + well-dense + TypeScript-centric) Bunker library (note: GNU GPL 3). After a value is bunkered into a compact byte sequence, it's then converted to a base64-encoded string- achieving web storage compatibility. Lastly, a sentinel value (... OK OK, it's a magic string) is prefixed for quick package/versioning lookup.