@jmondi/browser-storage

An abstracted storage library for browser applications that interfaces with localStorage, sessionStorage, in-memory storage, or any custom serializer. It provides serialization capabilities with optional key prefixing for better storage management.

npm bundle size npm gzip bundle size

Installation

For Node.js:

pnpx jsr add @jmondi/browser-storage

For Deno:

deno add @jmondi/browser-storage

Usage

LocalStorage and SessionStorage are wrappers for window.localStorage and window.sessionStorage.

The LocalStorage class

Persists after closing browser

import { LocalStorage } from "@jmondi/browser-storage";

const storage = new LocalStorage();
storage.set("user2", { email: "hermoine@hogwarts.com" });
console.log(storage.get("user2")); 
// { email: "hermoine@hogwarts.com" }

The SessionStorage class

Resets on browser close

import { SessionStorage } from "@jmondi/browser-storage";

const storage = new SessionStorage();
storage.set("user2", { email: "hermoine@hogwarts.com", name: "Hermoine" });
console.log(storage.get("user2")); // { email: "hermoine@hogwarts.com", name: "Hermoine" }

Example Custom storage adapter

import { type Adapter, BrowserStorage } from "@jmondi/browser-storage";
import Cookies from "js-cookie";

export class CookieAdapter implements Adapter {
  getItem(key: string): string | null {
    return Cookies.get(key) ?? null;
  }
  removeItem(key: string): void {
    Cookies.remove(key);
  }
  setItem(key: string, value: string, config?: Cookies.CookieAttributes): void {
    Cookies.set(key, value, config);
  }
}

const storage = new BrowserStorage<Cookies.CookieAttributes>({
  prefix: "app_",
  adapter: new CookieAdapter(),
});
storage.set("user2", { email: "hermoine@hogwarts.com", name: "Hermoine" }, { expires: 5 });
console.log(storage.get("user2"));

Configuration

Optional settings: prefix (key prefix), serializer (defaults to JSON).

import { BrowserStorage } from "./index.ts";

const storage = new LocalStorage({ prefix: 'app_', serializer: JSON });

Custom Serializers

To create a custom serializer, implement parse and stringify.

import superjson from "superjson";
import { StorageSerializer } from "@jmondi/browser-storage";

export class SuperJsonSerializer implements StorageSerializer {
  parse<T = unknown>(value: string): T { 
    return superjson.parse(value); 
  }
  stringify<T = unknown>(value: T): string { 
    return superjson.stringify(value); 
  }
}

Advanced Usage / Organization Techniques

With defined storage groups you can organize related data into named groups, simplifying access and management.

Defining Storage Key

Use define for individual keys. In this example,

type UserInfo = { email: string };
const storage = new LocalStorage(); // define is available on all BrowserStorage implementations

const USER_INFO = storage.define<UserInfo>("user_info");

USER_INFO.set({ email: "jason@example.com" });
USER_INFO.get(); // gets the latest value
USER_INFO.remove(); // removes the value

Defining Storage Groups

Use defineGroup for key groups.

const storage = new LocalStorage(); // defineGroup is available on all BrowserStorage implementations

const GROUP = storage.defineGroup({ token: "refresh_token", user: "user_info" });

GROUP.token.set("newtoken");
GROUP.token.get();
GROUP.token.remove();
GROUP.user.set({ email: "jason@example.com" });
GROUP.user.get();
GROUP.user.remove();