@brainwires/idbvec 0.1.0 → 0.2.0

package/pkg/bundler/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "idbvec",
+  "type": "module",
+  "collaborators": [
+    "nightness"
+  ],
+  "description": "Client-side vector database built on IndexedDB with WASM",
+  "version": "0.2.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Brainwires/idbvec"
+  },
+  "files": [
+    "idbvec_bg.wasm",
+    "idbvec.js",
+    "idbvec_bg.js",
+    "idbvec.d.ts",
+    "LICENSE-APACHE",
+    "LICENSE-MIT"
+  ],
+  "main": "idbvec.js",
+  "types": "idbvec.d.ts",
+  "sideEffects": [
+    "./idbvec.js",
+    "./snippets/*"
+  ],
+  "keywords": [
+    "vector",
+    "database",
+    "wasm",
+    "indexeddb",
+    "hnsw"
+  ]
+}

package/wrapper.d.ts

@@ -8,7 +8,7 @@
  */
 export interface SearchResult {
     id: string;
-    score: number;
+    distance: number;
     metadata?: Record<string, string>;
 }
 export interface VectorRecord {
@@ -16,15 +16,22 @@ export interface VectorRecord {
     vector: Float32Array;
     metadata?: Record<string, string>;
 }
+export interface GetResult {
+    id: string;
+    vector: Float32Array;
+    metadata?: Record<string, string>;
+}
 export interface SearchOptions {
     k?: number;
     ef?: number;
 }
+export type DistanceMetric = 'euclidean' | 'cosine' | 'dotproduct';
 export interface VectorDBConfig {
     name: string;
     dimensions: number;
     m?: number;
     efConstruction?: number;
+    metric?: DistanceMetric;
 }
 /**
  * Vector Database with IndexedDB persistence
@@ -33,6 +40,8 @@ export declare class VectorDatabase {
     private wasmDB;
     private idb;
     private config;
+    private saveTimer;
+    private saveDebounceMs;
     constructor(config: VectorDBConfig);
     /**
      * Initialize the database (load WASM + IndexedDB)
@@ -50,10 +59,26 @@ export declare class VectorDatabase {
      * Search for nearest neighbors
      */
     search(query: Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Get a vector and its metadata by ID
+     */
+    get(id: string): Promise<GetResult | null>;
+    /**
+     * Check if a vector exists by ID
+     */
+    has(id: string): boolean;
+    /**
+     * List all vector IDs
+     */
+    listIds(): string[];
     /**
      * Delete a vector by ID
      */
     delete(id: string): Promise<boolean>;
+    /**
+     * Delete multiple vectors by ID
+     */
+    deleteBatch(ids: string[]): Promise<number>;
     /**
      * Get total number of vectors
      */
@@ -62,10 +87,30 @@ export declare class VectorDatabase {
      * Clear all data
      */
     clear(): Promise<void>;
+    /**
+     * Export the database state as a JSON string
+     */
+    exportData(): string;
+    /**
+     * Import database state from a JSON string
+     */
+    importData(json: string): Promise<void>;
+    /**
+     * Flush any pending saves to IndexedDB immediately
+     */
+    flush(): Promise<void>;
+    /**
+     * Destroy the database completely (deletes IndexedDB)
+     */
+    destroy(): Promise<void>;
     /**
      * Open IndexedDB connection
      */
     private openIndexedDB;
+    /**
+     * Debounced save to IndexedDB
+     */
+    private debounceSave;
     /**
      * Save WASM state to IndexedDB
      */
@@ -78,6 +123,10 @@ export declare class VectorDatabase {
      * Close the database
      */
     close(): void;
+    /**
+     * Support for explicit resource management (using syntax)
+     */
+    [Symbol.dispose](): void;
 }
 /**
  * Standalone distance functions

package/wrapper.js

@@ -13,12 +13,15 @@ export class VectorDatabase {
     wasmDB = null;
     idb = null;
     config;
+    saveTimer = null;
+    saveDebounceMs = 1000;
     constructor(config) {
         this.config = {
             name: config.name,
             dimensions: config.dimensions,
             m: config.m ?? 16,
             efConstruction: config.efConstruction ?? 200,
+            metric: config.metric ?? 'euclidean',
         };
     }
     /**
@@ -33,11 +36,9 @@ export class VectorDatabase {
         const saved = await this.loadFromIndexedDB();
         if (saved) {
             this.wasmDB = wasmModule.VectorDB.deserialize(saved);
-            // console.log('Restored VectorDB from IndexedDB')
         }
         else {
-            this.wasmDB = new wasmModule.VectorDB(this.config.dimensions, this.config.m, this.config.efConstruction);
-            // console.log('Created new VectorDB')
+            this.wasmDB = new wasmModule.VectorDB(this.config.dimensions, this.config.m, this.config.efConstruction, this.config.metric);
         }
     }
     /**
@@ -47,8 +48,8 @@ export class VectorDatabase {
         if (!this.wasmDB)
             throw new Error('Database not initialized');
         this.wasmDB.insert(id, vector, metadata ?? null);
-        // Persist to IndexedDB
-        await this.saveToIndexedDB();
+        // Debounced persistence
+        this.debounceSave();
     }
     /**
      * Batch insert multiple vectors
@@ -57,13 +58,6 @@ export class VectorDatabase {
         if (!this.wasmDB)
             throw new Error('Database not initialized');
         for (const record of records) {
-            // console.log('🔍 Inserting to WASM:', {
-            //   id: record.id,
-            //   vectorLength: record.vector.length,
-            //   metadata: record.metadata,
-            //   metadataType: typeof record.metadata,
-            //   metadataKeys: record.metadata ? Object.keys(record.metadata) : null
-            // })
             this.wasmDB.insert(record.id, record.vector, record.metadata ?? null);
         }
         await this.saveToIndexedDB();
@@ -79,6 +73,33 @@ export class VectorDatabase {
         const results = this.wasmDB.search(query, k, ef);
         return results;
     }
+    /**
+     * Get a vector and its metadata by ID
+     */
+    async get(id) {
+        if (!this.wasmDB)
+            throw new Error('Database not initialized');
+        const result = this.wasmDB.get(id);
+        if (result === null || result === undefined)
+            return null;
+        return result;
+    }
+    /**
+     * Check if a vector exists by ID
+     */
+    has(id) {
+        if (!this.wasmDB)
+            throw new Error('Database not initialized');
+        return this.wasmDB.has(id);
+    }
+    /**
+     * List all vector IDs
+     */
+    listIds() {
+        if (!this.wasmDB)
+            throw new Error('Database not initialized');
+        return this.wasmDB.list_ids();
+    }
     /**
      * Delete a vector by ID
      */
@@ -87,10 +108,22 @@ export class VectorDatabase {
             throw new Error('Database not initialized');
         const deleted = this.wasmDB.delete(id);
         if (deleted) {
-            await this.saveToIndexedDB();
+            this.debounceSave();
         }
         return deleted;
     }
+    /**
+     * Delete multiple vectors by ID
+     */
+    async deleteBatch(ids) {
+        if (!this.wasmDB)
+            throw new Error('Database not initialized');
+        const count = this.wasmDB.delete_batch(ids);
+        if (count > 0) {
+            await this.saveToIndexedDB();
+        }
+        return count;
+    }
     /**
      * Get total number of vectors
      */
@@ -106,9 +139,50 @@ export class VectorDatabase {
         if (!this.wasmDB)
             throw new Error('Database not initialized');
         const wasmModule = await import('./pkg/bundler/idbvec');
-        this.wasmDB = new wasmModule.VectorDB(this.config.dimensions, this.config.m, this.config.efConstruction);
+        this.wasmDB.free();
+        this.wasmDB = new wasmModule.VectorDB(this.config.dimensions, this.config.m, this.config.efConstruction, this.config.metric);
+        await this.saveToIndexedDB();
+    }
+    /**
+     * Export the database state as a JSON string
+     */
+    exportData() {
+        if (!this.wasmDB)
+            throw new Error('Database not initialized');
+        return this.wasmDB.serialize();
+    }
+    /**
+     * Import database state from a JSON string
+     */
+    async importData(json) {
+        if (!this.wasmDB)
+            throw new Error('Database not initialized');
+        const wasmModule = await import('./pkg/bundler/idbvec');
+        this.wasmDB.free();
+        this.wasmDB = wasmModule.VectorDB.deserialize(json);
         await this.saveToIndexedDB();
     }
+    /**
+     * Flush any pending saves to IndexedDB immediately
+     */
+    async flush() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        await this.saveToIndexedDB();
+    }
+    /**
+     * Destroy the database completely (deletes IndexedDB)
+     */
+    async destroy() {
+        this.close();
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.deleteDatabase(this.config.name);
+            request.onerror = () => reject(request.error);
+            request.onsuccess = () => resolve();
+        });
+    }
     /**
      * Open IndexedDB connection
      */
@@ -121,7 +195,6 @@ export class VectorDatabase {
                 // CRITICAL: Handle versionchange event to auto-close when database is being deleted
                 // This prevents "blocked" errors when trying to delete the database
                 db.onversionchange = () => {
-                    // console.log(`🔒 VectorDB "${this.config.name}" received versionchange event - closing connection`)
                     db.close();
                     this.idb = null;
                 };
@@ -135,6 +208,18 @@ export class VectorDatabase {
             };
         });
     }
+    /**
+     * Debounced save to IndexedDB
+     */
+    debounceSave() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+        }
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            this.saveToIndexedDB();
+        }, this.saveDebounceMs);
+    }
     /**
      * Save WASM state to IndexedDB
      */
@@ -171,11 +256,25 @@ export class VectorDatabase {
      * Close the database
      */
     close() {
+        // Flush pending saves
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
         if (this.idb) {
             this.idb.close();
             this.idb = null;
         }
-        this.wasmDB = null;
+        if (this.wasmDB) {
+            this.wasmDB.free();
+            this.wasmDB = null;
+        }
+    }
+    /**
+     * Support for explicit resource management (using syntax)
+     */
+    [Symbol.dispose]() {
+        this.close();
     }
 }
 /**