@unikvs/indexeddb

Learn how to use the storage plugin that saves arbitrary data to the browser's IndexedDB.

Overview

@unikvs/indexeddb is a storage plugin that uses the browser’s IndexedDB as its persistence layer. It stores arbitrary data keyed by name.

It uses the idb package (8.0.3) internally and implements IStorage from @unikvs/core.

Install it as follows.

npm install @unikvs/indexeddb

pnpm add @unikvs/indexeddb

yarn add @unikvs/indexeddb

bun add @unikvs/indexeddb

nub add @unikvs/indexeddb

aube add @unikvs/indexeddb

Usage

The storage class is Indexeddb, provided as a default export. Its name is "Indexeddb".

import Indexeddb from "@unikvs/indexeddb";

Both constructor arguments are optional.

import Indexeddb from "@unikvs/indexeddb";

// Using the defaults (unikvs_db / kvs_store)
const storage = new Indexeddb();

// Specifying names
const customStorage = new Indexeddb("my-app-db", "my-store");

Call open() before use. It connects with version 1 and creates the store when missing. It does nothing when already open. Check with isOpen and close with close().

Registering with UniKvs looks like this.

import Indexeddb from "@unikvs/indexeddb";
import { UniKvs } from "unikvs";

const kvs = UniKvs.config()
  .appendStorage(new Indexeddb())
  .create();

await kvs.open();
await kvs.set("greeting", "hello");
const value = await kvs.get("greeting");
await kvs.close();

Data Format

write accepts any, and read returns any. Values are forwarded to idb’s put/get as is, so non-byte values can be stored too.

Streams are also supported, but IndexedDB has no native streaming, so they are emulated in memory.

• getWritable buffers chunks in memory and concatenates them into a single Uint8Array on close.
• getReadable loads the whole value into memory, then emits it as a single chunk before closing.

Existence checks use count(), deletion uses delete(), and full clearing uses clear().

Notes

• All methods are async. Don’t call write, read, exists, delete, or clear before open() completes. The connection is null until then.
• read throws a DOMException (NotFoundError) for a missing key. This matches the Opfs plugin. Check beforehand with exists().
• The database version is fixed at 1, and the store is auto-created when missing. No migration logic is included.
• Browser only. It uses IndexedDB, DOMException, WritableStream, and ReadableStream.
• Capacity and quota depend on the browser. Data may not persist in private mode.

Examples

import Indexeddb from "@unikvs/indexeddb";

const storage = new Indexeddb();

await storage.open();

await storage.write({ key: "greeting", data: "hello" });

if (await storage.exists({ key: "greeting" })) {
  const value = await storage.read({ key: "greeting" });
  console.log(value);
}

await storage.delete({ key: "greeting" });
await storage.close();