suaveplan/packages/persistence/storage/storage-browser-indexeddb/README.md

@suaveplan/storage-browser-indexeddb - Browser IndexedDB AbstractStorage adapter for @suaveplan/storage: structured-clone key-value storage via globalThis.indexedDB, AbortSignal everywhere, strict key sanitisation, TTL via expiresAt index, metadata storage, partial reads, DOMException → typed IndexedDbError mapping, full OTel surface.

Browser-tier AbstractStorage adapter backed by the W3C IndexedDB API (globalThis.indexedDB). Provides persistent, origin-scoped key-value storage for browser consumers — vault snapshots, drive chunk caches, in-app i18n catalogues, password manager records — with full AbstractStorage conformance, TTL via an expiresAt index, AbortSignal threading, strict key sanitisation, Zod-validated options, structured IndexedDbError boundary, DOMException → typed-code mapping, and a complete OpenTelemetry surface.

Documentation tree

• error-codes — (no submodules)
  • error-codes — (no submodules)
• idb-adapter — (no submodules)
  • idb-adapter — (no submodules)
• indexeddb-storage — (no submodules) - indexeddb-storage.ops — This module owns the Promis…
  • indexeddb-storage.config — This module exposes the two building blocks every public method of IndexedDbStorage relies on: resolveOptions valid…
  • indexeddb-storage.crud — This module hosts the pure CRUD primitives that IndexedDbStorage composes its public methods from. Splitting them out…
  • indexeddb-storage.errors — This module concentrates the DOMException-to-IndexedDbError translation that the IndexedDbStorage class relies on.…
  • indexeddb-storage — (no submodules) - indexeddb-storage.ops — This module owns the Promis…
  • indexeddb-storage.ops — This module owns the Promise-bridging glue around the callback-shaped IDBRequest and IDBTransaction APIs. Separatin…
• key-sanitizer — (no submodules)
  • key-sanitizer — (no submodules)
• otel — (no submodules)
  • otel — (no submodules)
• registry — (no submodules)
  • registry — (no submodules)

• error-codes — (no submodules)- idb-adapter — (no submodules) - idb-adapter — (no submodules)- indexeddb-storage — (no submodules) - indexeddb-storage.config — This module exposes the two building blocks every public method of IndexedDbStorage relies on: resolveOptions valid…
• indexeddb-storage.crud — This module hosts the pure CRUD primitives that IndexedDbStorage composes its public methods from. Splitting them out…
• indexeddb-storage.errors — This module concentrates the DOMException-to-IndexedDbError translation that the IndexedDbStorage class relies on.…
• indexeddb-storage — (no submodules) - indexeddb-storage.ops — This module owns the Promise-bridging glue around the callback-shaped IDBRequest and IDBTransaction APIs. Separatin…
• key-sanitizer — (no submodules) - key-sanitizer — (no submodules)- otel — (no submodules) - otel — (no submodules)- registry — (no submodules) - registry — (no submodules)

Install

bun add @suaveplan/storage-browser-indexeddb

Quick start

import {
 createIndexedDbStorage,
 isIndexedDbAvailable,
} from "@suaveplan/storage-browser-indexeddb";

if (!isIndexedDbAvailable()) {
 throw new Error("This browser does not support IndexedDB");
}

const storage = createIndexedDbStorage({ dbName: "myapp" });
await storage.set("user/42", new TextEncoder().encode("hello"));
const back = await storage.get("user/42");

Factory integration

import { registerIndexedDbProvider } from "@suaveplan/storage-browser-indexeddb/registry";
import { createStorage } from "@suaveplan/storage/factory";

registerIndexedDbProvider();
const storage = createStorage({ type: "indexeddb", config: { dbName: "myapp" } });

The package does NOT self-register at module-evaluation time — call registerIndexedDbProvider() explicitly so sideEffects: false bundlers can tree-shake the factory path when not used.

Capabilities

Capability	Value	Notes
partialReads	true	Via Uint8Array.subarray(...) on the in-memory copy of the stored row.
partialWrites	false	IndexedDB has no random-access put; setPartial uses the AbstractStorage read-modify-write fallback.
nativeStreams	false	IndexedDB has no native streaming surface; createReadStream / createWriteStream use the buffered fallback.
atomicWrites	true	Each objectStore.put is a single-transaction commit.
contentAddressable	false	Keys are caller-supplied strings.

Modules

• src/error-codes/error-codes.ts — INDEXEDDB_CODES registry + IndexedDbError.
• src/key-sanitizer/key-sanitizer.ts — strict key boundary.
• src/idb-adapter/idb-adapter.ts — defaultIndexedDB() + isIndexedDbAvailable().
• src/indexeddb-storage/indexeddb-storage.ts — the IndexedDbStorage class.
• src/indexeddb-storage/indexeddb-storage.config.ts — option resolver + OTel wrapper.
• src/indexeddb-storage/indexeddb-storage.crud.ts — CRUD primitives.
• src/indexeddb-storage/indexeddb-storage.errors.ts — DOMException mapping.
• src/indexeddb-storage/indexeddb-storage.ops.ts — transaction + open + cursor helpers.
• src/otel/otel.ts — OpenTelemetry instrument set.
• src/registry/registry.ts — registerIndexedDbProvider().
• src/types/idb-like.types.ts — structural IndexedDB surface.
• src/types/indexeddb-storage.types.ts — option boundary.

License

MIT.