Browser KeyVal Stores

The browser-keyval-stores package offers a clean and unified API to interact with browser storage mechanisms (localStorage, sessionStorage, and indexedDB) from your applications. It streamlines development and eliminates the need for browser-specific code when working with client-side data storage.

Getting Started

Install the package:

npm i -S browser-keyval-stores

Usage

localStorage Store

import { LocalStorageStore } from 'browser-keyval-stores';

type IUserPreferences = {
  language: string,
  theme: string
};

const store = new LocalStorageStore<IUserPreferences>('userPreferences');

const uid = '2d22df80-fc4b-498a-a4a7-734daa71c8dd';

store.get(uid);
// undefined

store.set(uid, { language: 'en', theme: 'dark' });
store.get(uid);
// { language: 'en', theme: 'dark' }

store.set(uid, { language: 'es', theme: 'light' });
store.get(uid);
// { language: 'es', theme: 'light' }

store.del(uid);
store.get(uid);
// undefined

sessionStorage Store

import { SessionStorageStore } from 'browser-keyval-stores';

type IApplicationFormData = {
  fullName: string,
  passportNum: string,
};

const store = new SessionStorageStore<IApplicationFormData>('applicationForm');

store.get();
// undefined

store.set(undefined, { fullName: 'Jess Grateol', passportNum: 'P4366918' });
store.get();
// { fullName: 'Jess Grateol', passportNum: 'P4366918' }

store.set(undefined, { fullName: 'Jesus Graterol', passportNum: 'LA080402' });
store.get();
// { fullName: 'Jesus Graterol', passportNum: 'LA080402' }

store.del();
store.get();
// undefined

indexedDB Store

import { IndexedDBStore } from 'browser-keyval-stores';

type IBlogPost = {
  id: number,
  title: string,
  content: string,
};

const store = new IndexedDBStore<IBlogPost>('blogPosts');

await store.set(1, { id: 1, title: 'Test title', content: 'This is the ...'});
await store.get(1);
// { id: 1, title: 'Test title', content: 'This is the ...'}

await store.del(1);
await store.get(1);
// undefined

IndexedDBStore also works in service workers when IndexedDB is available. A window and its service worker on the same origin can use the same store ID and record ID to access the same persisted record. Check await store.isCompatible() before relying on cross-context persistence: when IndexedDB is unavailable, the store falls back to memory, which is local to that context.

Types

The supported browser storage mechanisms.

type IStoreMechanism = 'tempMemory' | 'localStorage' | 'sessionStorage' | 'indexedDB';

The identifier used to manage records. The store behaves differently based on the type:

• undefined: the data will be stored at the root of the store
• string | number: the value will be coerced into a string and can be used to locate the data

type IRecordID = undefined | string | number;

Object in charge of interacting with the Browser's Storage API. This API is used by Window.localStorage & Window.sessionStorage.

interface IWebStorageStore<T> {
  // properties
  id: string;

  // methods
  isCompatible: () => boolean;
  get: (id?: IRecordID) => T | undefined;
  set: (id: IRecordID, data: T) => void;
  del: (id?: IRecordID) => void;
}

interface ILocalStorageStore<T> extends IWebStorageStore<T> {
  // ...
}

interface ISessionStorageStore<T> extends IWebStorageStore<T> {
  // ...
}

Object in charge of charge of interacting with the Browser's IndexedDB implementation.

interface IIndexedDBStore<T> {
  // properties
  id: string;

  // methods
  isCompatible(): Promise<boolean>;
  get: (id?: IRecordID) => Promise<T | undefined>;
  set: (id: IRecordID, data: T) => Promise<void>;
  del: (id?: IRecordID) => Promise<void>;
}

Built With

• TypeScript

Running the Tests

# unit and integration tests
npm run test

# integration tests
npm run test:integration

# unit tests
npm run test:unit

License

MIT