bun-storage

A 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

Installation

# npm
bun install bun-storage

# JSR
bunx jsr add @idleberg/bun-storage

Usage

[!NOTE] The following examples will assume that you're installing npm. If you're using JSR, make sure to adjust the imports.

For simple use cases, the automatic setup will expose both sessionStorage and localStorage, on the global object.

import "bun-storage/auto";

The location of the database will default to .bun-storage/localStorage.sqlite. However, this comes at the downside of not being able to listen to storage events or to control the quota.

If you need more control, see the API documentation below.

API

createStorage

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

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

Example:

import { createStorage } from "bun-storage";

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

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

Options

options.quota

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

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

• @idleberg/local-storage: a NodeJS implementation of this package

License

This work is licensed under The MIT License.