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

Install (npm)

pnpm add @jmondi/browser-storage

Deno

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

Usage

The LocalStorage and SessionStorage classes serve as helper abstractions over the built-in window.localStorage and window.sessionStorage web storage mechanisms respectively.

Local Storage Adapter

Local storage is persistent after close.

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

Session Storage Adapter

Session storage is reset when the browser is closed.

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

The BrowserStorage class gives you the option to use a custom storage adapter.

Underneath, both LocalStorage and SessionStorage extend the BrowserStorage class, which operates over an arbitrary storage adapter. This design enables you to extend BrowserStorage to interface with any custom storage provider of your choice.

For a custom storage provider to work correctly, it needs to implement the Adapter interface.

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 prefix = "app_"

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

Configuration

You can optionally provide a configuration object.

• prefix: This optional value will be prepended to every key when stored.
• serializer: This optional value can be any object that implements the StorageSerializer interface. By default, this is JSON.

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

const localStorage = new LocalStorage({
  prefix: 'app_', // Optional. Defaults to "".
  serializer: JSON, // Optional. Defaults to JSON.
});
const sessionStorage = new SessionStorage({
  prefix: 'app_', // Optional. Defaults to "".
  serializer: JSON, // Optional. Defaults to JSON.
});
const browserStorage = new BrowserStorage({
  prefix: 'app_', // Optional. Defaults to "".
  serializer: JSON, // Optional. Defaults to JSON.
  adapter: Adapter, // Optional. Defaults to an InMemoryStorageProvider.
});

Custom Serializers

The StorageSerializer is an interface which requires the implementation of two methods: parse and stringify. The default example of this is the built in JSON object.

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

Defining a named group of keys

The define method

This method allows the creation of named keys in storage. Each key is associated with a type. Here’s an example:

const storage = new BrowserStorage(); // or LocalStorage, SessionStorage, etc.
const GROUP = {
  token: storage.define<string>("access_token"),
  user: storage.define<{ email: string }>("user_info"),
};
GROUP.token.set("ABC123");
GROUP.user.set({ email: "jason@example.com" });

GROUP.token.get(); // "ABC123"
GROUP.user.get(); // { email: "jason@example" }

In this example, GROUP has two keys: token and user.

The defineGroup method

The defineGroup method provides a more concise way to define named keys. Here’s an example:

const storage = new BrowserStorage(); // or LocalStorage, SessionStorage, etc.

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

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

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