Skip to main content

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.

Works with
It is unknown whether this package works with Bun
It is unknown whether this package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
This package works with Browsers
JSR Score
100%
Published
a week ago (1.9.0)

@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.

JSR JSR Score GitHub Workflow Status Test Coverage

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. You can add your own custom adapters to use Cookies or IndexedDB etc.

const storage = new LocalStorage({ prefix: "myapp" });
const LOCAL_STORAGE = storage.defineGroup({ token: "jti", current_user: "u" });
// any primitive value
LOCAL_STORAGE.token.set("newtoken");
LOCAL_STORAGE.token.get(); // "newtoken"
LOCAL_STORAGE.token.remove();

// any serializable object
LOCAL_STORAGE.current_user.set({ email: "jason@example.com" });
LOCAL_STORAGE.current_user.get(); // { email: "jason@example.com" }
LOCAL_STORAGE.current_user.remove();

// pop removes and returns the value
LOCAL_STORAGE.current_user.set({ email: "jason@example.com" });
LOCAL_STORAGE.current_user.pop(); // { email: "jason@example.com" }
LOCAL_STORAGE.current_user.get(); // null

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 Groups

Use defineGroup for key groups.

const storage = new LocalStorage({ prefix: "myapp" });
const LOCAL_STORAGE = storage.defineGroup({ token: "jti", current_user: "u" });
LOCAL_STORAGE.token.set("newtoken");
LOCAL_STORAGE.token.get(); // "newtoken"
LOCAL_STORAGE.token.remove();
LOCAL_STORAGE.current_user.set({ email: "jason@example.com" });
LOCAL_STORAGE.current_user.get(); // { email: "jason@example.com" }
LOCAL_STORAGE.current_user.remove();
LOCAL_STORAGE.current_user.set({ email: "jason@example.com" });
LOCAL_STORAGE.current_user.pop(); // { email: "jason@example.com" }

Defining Single Storage Key

Use define for individual keys. In this example,

type UserInfo = { email: string };
const storage = new LocalStorage();
const USER_INFO_STORAGE = storage.define<UserInfo>("user_info");
USER_INFO_STORAGE.set({ email: "jason@example.com" });
USER_INFO_STORAGE.get(); // gets the latest value
USER_INFO_STORAGE.remove(); // removes the value
Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @jmondi/browser-storage

Import symbol

import * as mod from "@jmondi/browser-storage";

Add Package

npx jsr add @jmondi/browser-storage

Import symbol

import * as mod from "@jmondi/browser-storage";

Add Package

yarn dlx jsr add @jmondi/browser-storage

Import symbol

import * as mod from "@jmondi/browser-storage";

Add Package

pnpm dlx jsr add @jmondi/browser-storage

Import symbol

import * as mod from "@jmondi/browser-storage";

Add Package

bunx jsr add @jmondi/browser-storage

Import symbol

import * as mod from "@jmondi/browser-storage";