@idleberg/local-storage

A NodeJS ponyfill for the Storage API, utilizing SQLite.

Features

• zero dependencies
• fully API compatible to both, localStorage and sessionStorage
• persists data across sessions
• supports storage events
• supports optional quota

[!NOTE] This module depends on the experimental node:sqlite module included in NodeJS v22.5 and later.

Installation

npm install @idleberg/local-storage

Usage

API

createStorage

Usage: createStorage(dbFile?: string, options?: StorageFactoryOptions)
Returns: { sessionStorage, localStorage, emitter }

Creates instances of both, sessionStorage and localStorage, as well as a corresponding EventEmitter.

Example:

import { createStorage } from "@idleberg/local-storage";

const { sessionStorage, localStorage, emitter } = createStorage("./db.sqlite");

// Listen for storage changes
emitter.on("storage", console.log);

Options

options.quota

Storage (Advanced Usage)

Usage: new Storage(filePath: string | ':memory:', options: StorageClassOptions)

This class is used internally by the above factory functions. It allows you more control over the EventEmitter, e.g. you could re-use an existing one from your application code.

Example:

import { Storage } from "@idleberg/local-storage";
import EventEmitter from "events";

const myEmitter = new EventEmitter();

const localStorage = new Storage("./db.sqlite", {
    emitter: myEmitter,
});

// Listen for storage changes
myEmitter.on("storage", console.log);

Options

options.emitter

An instance of EventEmitter to use for dispatching storage events.

options.eventName

The name of the event to dispatch when a storage event occurs. Defaults to storage.

options.quota

Optional storage quota in bytes, useful for emulating browser behaviour.

Related

• bun-storage: a Bun implementation of this package

License

This work is licensed under The MIT License.