verso-db 0.1.4 → 0.2.0

package/dist/VectorDB.d.ts

@@ -1,6 +1,6 @@
 import { Collection } from './Collection';
+import type { DistanceMetric } from './HNSWIndex';
 import type { StorageBackend } from './storage/StorageBackend';
-export type DistanceMetric = 'cosine' | 'euclidean' | 'dot_product';
 export interface VectorDBConfig {
     /**
      * Path for storing collections on disk. Default: './vectordb_data'
@@ -9,7 +9,7 @@ export interface VectorDBConfig {
     storagePath?: string;
     /**
      * Custom storage backend for platform-specific storage (e.g., OPFS for browsers).
-     * If not provided, defaults to BunStorageBackend with storagePath.
+     * If not provided, backend is auto-selected for the current runtime.
      */
     storageBackend?: StorageBackend;
 }
@@ -21,24 +21,38 @@ export interface CollectionConfig {
 }
 export declare class VectorDB {
     private collections;
-    private storagePath;
     private storageBackend;
     private initialized;
+    private initPromise;
+    private createCollectionLocks;
     constructor(config?: VectorDBConfig);
+    private createDefaultStorageBackend;
     /**
      * Get the storage backend used by this VectorDB instance.
      * Useful for custom storage operations or debugging.
      */
     getStorageBackend(): StorageBackend;
     /**
-     * Initialize the VectorDB - creates storage directory if needed.
+     * Initialize the VectorDB - creates storage directory and loads existing collections.
      * Called automatically on first operation if not called explicitly.
+     * Safe to call concurrently — only runs initialization once.
      */
     init(): Promise<void>;
+    private doInit;
+    /**
+     * Load collection metadata from the manifest file and restore collections.
+     */
+    private loadManifest;
+    /**
+     * Save collection metadata to the manifest file.
+     */
+    private saveManifest;
+    private withCollectionCreateLock;
     createCollection(name: string, config: CollectionConfig): Promise<Collection>;
-    getCollection(name: string): Collection | undefined;
+    getCollection(name: string): Promise<Collection | undefined>;
     listCollections(): Promise<string[]>;
     deleteCollection(name: string): Promise<void>;
+    private validateCollectionName;
     close(): Promise<void>;
 }
 //# sourceMappingURL=VectorDB.d.ts.map

package/dist/VectorDB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VectorDB.d.ts","sourceRoot":"","sources":["../src/VectorDB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;AAEpE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,WAAW,CAAkB;gBAEzB,MAAM,CAAC,EAAE,cAAc;IAOnC;;;OAGG;IACH,iBAAiB,IAAI,cAAc;IAInC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IASrB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBnF,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIpC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B"}
+{"version":3,"file":"VectorDB.d.ts","sourceRoot":"","sources":["../src/VectorDB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO/D,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAaD,qBAAa,QAAQ;IACnB,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,qBAAqB,CAAyC;gBAE1D,MAAM,CAAC,EAAE,cAAc;IASnC,OAAO,CAAC,2BAA2B;IAcnC;;;OAGG;IACH,iBAAiB,IAAI,cAAc;IAInC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAab,MAAM;IAUpB;;OAEG;YACW,YAAY;IAqD1B;;OAEG;YACW,YAAY;YAgBZ,wBAAwB;IAmBhC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAyB7E,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAK5D,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKpC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBnD,OAAO,CAAC,sBAAsB;IA+BxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAiC7B"}

package/dist/VectorDB.js

@@ -0,0 +1,246 @@
+import { Collection } from './Collection.js';
+import { BunStorageBackend } from './storage/BunStorageBackend.js';
+import { MemoryBackend } from './storage/MemoryBackend.js';
+import { OPFSBackend } from './storage/OPFSBackend.js';
+import { detectEnvironment } from './storage/createStorageBackend.js';
+import { CollectionExistsError, CollectionNotFoundError, VectorDBError } from './errors.js';
+const MANIFEST_KEY = 'manifest.json';
+const VALID_METRICS = new Set(['cosine', 'euclidean', 'dot_product']);
+export class VectorDB {
+    collections;
+    storageBackend;
+    initialized = false;
+    initPromise = null;
+    createCollectionLocks = new Map();
+    constructor(config) {
+        this.collections = new Map();
+        if (config?.storageBackend) {
+            this.storageBackend = config.storageBackend;
+        }
+        else {
+            this.storageBackend = this.createDefaultStorageBackend(config?.storagePath);
+        }
+    }
+    createDefaultStorageBackend(storagePath) {
+        const env = detectEnvironment();
+        if (env === 'bun' || env === 'node') {
+            return new BunStorageBackend(storagePath || './vectordb_data');
+        }
+        if (env === 'browser' && OPFSBackend.isAvailable()) {
+            return new OPFSBackend();
+        }
+        return new MemoryBackend();
+    }
+    /**
+     * Get the storage backend used by this VectorDB instance.
+     * Useful for custom storage operations or debugging.
+     */
+    getStorageBackend() {
+        return this.storageBackend;
+    }
+    /**
+     * Initialize the VectorDB - creates storage directory and loads existing collections.
+     * Called automatically on first operation if not called explicitly.
+     * Safe to call concurrently — only runs initialization once.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        if (!this.initPromise) {
+            this.initPromise = this.doInit().catch((err) => {
+                // Allow retry after transient initialization failures.
+                this.initPromise = null;
+                this.initialized = false;
+                throw err;
+            });
+        }
+        return this.initPromise;
+    }
+    async doInit() {
+        // Use storage backend to create root directory
+        await this.storageBackend.mkdir('');
+        // Load existing collections from manifest
+        await this.loadManifest();
+        this.initialized = true;
+    }
+    /**
+     * Load collection metadata from the manifest file and restore collections.
+     */
+    async loadManifest() {
+        const data = await this.storageBackend.read(MANIFEST_KEY);
+        if (!data)
+            return;
+        let manifest;
+        try {
+            const text = new TextDecoder().decode(data);
+            manifest = JSON.parse(text);
+        }
+        catch {
+            // Corrupt manifest JSON — continue with empty collections
+            return;
+        }
+        for (const [name, entry] of Object.entries(manifest)) {
+            // Skip collections already loaded
+            if (this.collections.has(name))
+                continue;
+            try {
+                this.validateCollectionName(name);
+            }
+            catch {
+                console.warn(`Skipping collection '${name}' with invalid name in manifest`);
+                continue;
+            }
+            // Validate manifest entry types to catch corrupted manifests early
+            if (typeof entry.dimension !== 'number' || entry.dimension <= 0 || !Number.isInteger(entry.dimension) ||
+                typeof entry.metric !== 'string' || !VALID_METRICS.has(entry.metric) ||
+                typeof entry.M !== 'number' || entry.M <= 0 || !Number.isInteger(entry.M) ||
+                typeof entry.efConstruction !== 'number' || entry.efConstruction <= 0 || !Number.isInteger(entry.efConstruction)) {
+                console.warn(`Skipping collection '${name}' with invalid manifest entry`);
+                continue;
+            }
+            const config = {
+                dimension: entry.dimension,
+                metric: entry.metric,
+                M: entry.M,
+                efConstruction: entry.efConstruction,
+            };
+            try {
+                const collection = new Collection(name, config, this.storageBackend, { autoPersist: true });
+                await collection.init();
+                this.collections.set(name, collection);
+            }
+            catch (e) {
+                // Per-collection init failure — skip this collection but continue loading others
+                console.warn(`Failed to load collection '${name}':`, e);
+            }
+        }
+    }
+    /**
+     * Save collection metadata to the manifest file.
+     */
+    async saveManifest() {
+        const manifest = {};
+        for (const [name, collection] of this.collections) {
+            manifest[name] = {
+                dimension: collection.getDimension(),
+                metric: collection.getMetric(),
+                M: collection.getM(),
+                efConstruction: collection.getEfConstruction(),
+            };
+        }
+        const data = new TextEncoder().encode(JSON.stringify(manifest));
+        await this.storageBackend.write(MANIFEST_KEY, data);
+    }
+    async withCollectionCreateLock(name, fn) {
+        const previous = this.createCollectionLocks.get(name) ?? Promise.resolve();
+        let release;
+        const lock = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.createCollectionLocks.set(name, lock);
+        await previous;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.createCollectionLocks.get(name) === lock) {
+                this.createCollectionLocks.delete(name);
+            }
+        }
+    }
+    async createCollection(name, config) {
+        this.validateCollectionName(name);
+        // Ensure VectorDB is initialized
+        await this.init();
+        return this.withCollectionCreateLock(name, async () => {
+            if (this.collections.has(name)) {
+                throw new CollectionExistsError(name);
+            }
+            // Create collection directory using storage backend
+            await this.storageBackend.mkdir(name);
+            const collection = new Collection(name, config, this.storageBackend, { autoPersist: true });
+            await collection.init();
+            this.collections.set(name, collection);
+            // Persist manifest
+            await this.saveManifest();
+            return collection;
+        });
+    }
+    async getCollection(name) {
+        await this.init();
+        return this.collections.get(name);
+    }
+    async listCollections() {
+        await this.init();
+        return [...this.collections.keys()];
+    }
+    async deleteCollection(name) {
+        await this.init();
+        const collection = this.collections.get(name);
+        if (!collection) {
+            throw new CollectionNotFoundError(name);
+        }
+        // Destroy without saving — we're deleting the collection
+        await collection.destroy(false);
+        this.collections.delete(name);
+        // Remove all files under the collection prefix, including versioned snapshots.
+        const keys = await this.storageBackend.list(name);
+        for (const key of keys) {
+            await this.storageBackend.delete(key).catch(() => { });
+        }
+        // Update manifest
+        await this.saveManifest();
+    }
+    validateCollectionName(name) {
+        if (!name || name.trim().length === 0) {
+            throw new VectorDBError('Collection name must be a non-empty string', 'VALIDATION_ERROR');
+        }
+        if (name.length > 255) {
+            throw new VectorDBError(`Collection name must be 255 characters or fewer, got ${name.length}`, 'VALIDATION_ERROR');
+        }
+        if (/[\/\\.\x00]/.test(name)) {
+            throw new VectorDBError(`Collection name '${name}' contains invalid characters (/, \\, ., or null)`, 'VALIDATION_ERROR');
+        }
+        // Reject control characters (U+0001–U+001F, U+007F)
+        // eslint-disable-next-line no-control-regex
+        if (/[\x01-\x1f\x7f]/.test(name)) {
+            throw new VectorDBError('Collection name contains control characters', 'VALIDATION_ERROR');
+        }
+        // Reject leading/trailing whitespace (checked after control chars since
+        // tab/etc. are control chars and should get the more specific message)
+        if (name !== name.trim()) {
+            throw new VectorDBError('Collection name must not have leading or trailing whitespace', 'VALIDATION_ERROR');
+        }
+    }
+    async close() {
+        // Close all collections — continue on individual failures so remaining
+        // collections still get saved and cleanup always completes.
+        const errors = [];
+        for (const collection of this.collections.values()) {
+            try {
+                await collection.destroy();
+            }
+            catch (e) {
+                errors.push(e instanceof Error ? e : new Error(String(e)));
+            }
+        }
+        // Persist the manifest so collection metadata survives re-open
+        if (this.initialized) {
+            try {
+                await this.saveManifest();
+            }
+            catch (e) {
+                errors.push(e instanceof Error ? e : new Error(String(e)));
+            }
+        }
+        this.collections.clear();
+        this.createCollectionLocks.clear();
+        this.initialized = false;
+        this.initPromise = null;
+        if (errors.length > 0) {
+            throw new VectorDBError(`Failed to close ${errors.length} collection(s): ${errors.map(e => e.message).join('; ')}`, 'STORAGE_ERROR');
+        }
+    }
+}
+//# sourceMappingURL=VectorDB.js.map

package/dist/VectorDB.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorDB.js","sourceRoot":"","sources":["../src/VectorDB.ts"],"names":[],"mappings":"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"}

package/dist/WorkerPool.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Worker pool for parallel query processing.
+ * Dispatches queries to workers via round-robin for concurrent execution.
+ * Falls back to sequential processing when workers are unavailable.
+ */
+import { HNSWIndex } from './HNSWIndex';
+export declare class WorkerPool {
+    private numWorkers?;
+    private workers;
+    private nextQueryId;
+    private roundRobinIndex;
+    private initialized;
+    private fallbackIndex;
+    /**
+     * Create a worker pool for parallel HNSW search.
+     *
+     * @param numWorkers Number of workers (default: available hardware concurrency or 4)
+     */
+    constructor(numWorkers?: number | undefined);
+    /**
+     * Initialize workers with shared index data.
+     * When the index uses SharedArrayBuffer, workers receive zero-copy
+     * views into the same vector memory. Otherwise, data is copied.
+     *
+     * @param index The HNSW index to distribute to workers
+     */
+    init(index: HNSWIndex): Promise<void>;
+    /**
+     * Search for k nearest neighbors using worker pool.
+     * Dispatches to next available worker via round-robin.
+     *
+     * @param query Query vector
+     * @param k Number of results
+     * @param efSearch Search effort parameter
+     * @returns Array of {id, distance} results
+     */
+    search(query: Float32Array, k: number, efSearch?: number): Promise<Array<{
+        id: number;
+        distance: number;
+    }>>;
+    /**
+     * Quantized search using worker pool.
+     * Workers perform int8 candidate scan + float32 rescore.
+     *
+     * @param query Query vector
+     * @param k Number of results
+     * @param candidateMultiplier Multiplier for rescore candidates
+     * @param efSearch Search effort parameter
+     * @returns Array of {id, distance} results
+     */
+    searchQuantized(query: Float32Array, k: number, candidateMultiplier?: number, efSearch?: number): Promise<Array<{
+        id: number;
+        distance: number;
+    }>>;
+    /**
+     * Batch search: dispatch multiple queries in parallel across workers.
+     *
+     * @param queries Array of query vectors
+     * @param k Number of results per query
+     * @param efSearch Search effort parameter
+     * @returns Array of results, one per query
+     */
+    searchBatch(queries: Float32Array[], k: number, efSearch?: number): Promise<Array<Array<{
+        id: number;
+        distance: number;
+    }>>>;
+    /**
+     * Batch quantized search across workers.
+     */
+    searchBatchQuantized(queries: Float32Array[], k: number, candidateMultiplier?: number, efSearch?: number): Promise<Array<Array<{
+        id: number;
+        distance: number;
+    }>>>;
+    /**
+     * Send incremental graph updates to all workers.
+     * Workers update their neighbor lists without full re-initialization.
+     * New vectors are already visible via SharedArrayBuffer.
+     */
+    broadcastGraphUpdate(newNodes: Array<{
+        id: number;
+        neighbors: number[][];
+    }>, entryPointId?: number, maxLevel?: number): void;
+    /**
+     * Terminate all workers and clean up.
+     */
+    destroy(): void;
+    /**
+     * Get the number of active workers.
+     */
+    get workerCount(): number;
+}
+//# sourceMappingURL=WorkerPool.d.ts.map

package/dist/WorkerPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerPool.d.ts","sourceRoot":"","sources":["../src/WorkerPool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAUxC,qBAAa,UAAU;IAYT,OAAO,CAAC,UAAU,CAAC;IAX/B,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,aAAa,CAA0B;IAE/C;;;;OAIG;gBACiB,UAAU,CAAC,EAAE,MAAM,YAAA;IAQvC;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAmG3C;;;;;;;;OAQG;IACG,MAAM,CACV,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA4BnD;;;;;;;;;OASG;IACG,eAAe,CACnB,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,mBAAmB,GAAE,MAAU,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA8BnD;;;;;;;OAOG;IACG,WAAW,CACf,OAAO,EAAE,YAAY,EAAE,EACvB,CAAC,EAAE,MAAM,EACT,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAc1D;;OAEG;IACG,oBAAoB,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,CAAC,EAAE,MAAM,EACT,mBAAmB,GAAE,MAAU,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAa1D;;;;OAIG;IACH,oBAAoB,CAClB,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC,EACtD,YAAY,CAAC,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI;IAgBP;;OAEG;IACH,OAAO,IAAI,IAAI;IAcf;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}