@jmondi/browser-storage

DateDuration

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 { DateDuration } 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

Local storage is persistent after close.

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

const storage = new LocalStorage();

storage.set("user1", null);
storage.set("user2", { email: "[e-mail]", name: "Hermoine" });

console.log(storage.get("user1"));
// null
console.log(storage.get("user2"));
// { email: "[e-mail]", name: "Hermoine" }

Session Storage

Session storage is reset when the browser is closed.

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

const storage = new SessionStorage();

storage.set("user1", null);
storage.set("user2", { email: "[e-mail]", name: "Hermoine" });

console.log(storage.get("user1"));
// null
console.log(storage.get("user2"));
// { email: "[e-mail]", name: "Hermoine" }

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.

const storage = new LocalStorage({
  prefix: 'app_', // Optional. Defaults to "".
  serializer: JSON // Optional. Defaults to JSON.
});

Custom Storage Adapter

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

For a custom storage provider to work correctly, it needs to adhere to the browser's Storage interface – that is, it must implement methods such as getItem, setItem, removeItem, and clear, along with the length property. As an example, the provided MemoryStorageProvider class is a valid storage provider that stores data in an in-memory JavaScript map.

export class MemoryStorageProvider implements Storage {
  private storage = new Map<string, string | null>();

  clear(): void {
    this.storage.clear();
  }

  getItem(key: string): string | null {
    return this.storage.get(key) ?? null;
  }

  key(_: number): string | null {
    return null;
  }

  removeItem(key: string): void {
    this.storage.delete(key);
  }

  setItem(key: string, value: string): void {
    this.storage.set(key, value);
  }

  get length() {
    return this.storage.size;
  }
}

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