@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

Installation

pnpm add @jmondi/browser-storage

For Deno:

import { LocaleStorage, SessionStorage, BrowserStorage } from "https://deno.land/x/browser_storage"

Usage

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

LocalStorage

Persists after closing browser:

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

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

SessionStorage

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" }

Custom storage adapter:

import { type Adapter, BrowserStorage } from "@jmondi/browser-storage";
import Cookies, { type CookieAttributes } 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: CookieAttributes): void { Cookies.set(key, value, config); }
}

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

Defining Storage Groups

Use define for individual keys:

const storage = new BrowserStorage();
const USER_COOKIE = storage.define<{ email: string }>("user_info");
USER_COOKIE.set({ email: "jason@example.com" });

Use defineGroup for key groups:

const storage = new BrowserStorage();

const GROUP = storage.defineGroup({ token: "refresh_token", user: "user_info" });
GROUP.token.set("newtoken");
GROUP.user.set({ email: "jason@example.com" });

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); }
}