Skip to content

README.md

Latest commit

 

History

History
104 lines (76 loc) · 3.97 KB

README.md

File metadata and controls

104 lines (76 loc) · 3.97 KB
Raw

@localmode/idb

Minimal idb storage adapter for LocalMode — lightweight IndexedDB wrapper with the smallest bundle footprint (~3KB).

npm license

Docs UI Components Blocks & Apps

Installation

pnpm install @localmode/idb @localmode/core

Quick Start

import { IDBStorage } from '@localmode/idb';
import { createVectorDB } from '@localmode/core';

const storage = new IDBStorage({ name: 'my-app' });

const db = await createVectorDB({
  name: 'my-app',
  dimensions: 384,
  storage,
});

// Use db.add(), db.search(), etc.

API

Constructor

new IDBStorage({ name: string })

StorageAdapter Methods

IDBStorage implements the StorageAdapter interface from @localmode/core:

Method Description
open() / close() Manage database connection
addDocument(doc) Add/upsert a document
getDocument(id) Get document by ID (returns null if missing)
deleteDocument(id) Delete a document
getAllDocuments(collectionId) Get all documents in a collection
countDocuments(collectionId) Count documents in a collection
addVector(vec) Add/upsert a vector
getVector(id) Get vector as Float32Array | Uint8Array | null (Uint8Array for SQ8/PQ-compressed payloads)
deleteVector(id) Delete a vector
getAllVectors(collectionId) Get all vectors as Map<string, Float32Array | Uint8Array>
saveIndex(collectionId, index) Save serialized HNSW index
loadIndex(collectionId) Load serialized HNSW index
deleteIndex(collectionId) Delete an index
createCollection(collection) Create a collection
getCollection(id) Get collection by ID
getCollectionByName(name) Get collection by name
getAllCollections() List all collections
deleteCollection(id) Delete a collection
clear() Clear all data
clearCollection(collectionId) Clear a specific collection
estimateSize() Estimate storage size in bytes

Collection records round-trip the full Collection object — including quantization calibration (calibration, pqCodebook), storage-compression calibration (compressionCalibration, deltaCalibration, compression), and the drift-detection modelFingerprint — so SQ8/PQ-quantized and compressed databases decode identically after a close→reopen. Verified by core's createStorageAdapterConformanceSuite contract tests (tests/conformance.test.ts).

Why idb?

The idb library is a tiny (~3KB gzipped) Promise wrapper around IndexedDB by Jake Archibald (Google Chrome team):

  1. Minimal size — Smallest viable IndexedDB wrapper
  2. Promise-based — Clean async/await API, no callbacks
  3. TypeScript — Excellent type support
  4. Well-maintained — Widely used, battle-tested

Comparison

Feature IndexedDBStorage (built-in) IDBStorage DexieStorage
Bundle size 0KB (built-in) ~3KB ~15KB
Schema versioning Manual Basic Advanced
Transactions Manual Manual Automatic
Queries Basic Basic Indexed
TypeScript Good Excellent Excellent

When to Use

  • You need the smallest possible bundle
  • Simple storage needs without complex queries
  • Prefer minimal abstractions over feature-rich wrappers

Acknowledgments

This package is built on idb by Jake Archibald — a tiny, Promise-based IndexedDB wrapper.

License

MIT