verso-db 0.1.1

package/dist/HNSWIndex.d.ts

@@ -0,0 +1,357 @@
+import type { DistanceBackend } from './backends/DistanceBackend';
+export type DistanceMetric = 'cosine' | 'euclidean' | 'dot_product';
+export interface Node {
+    id: number;
+    level: number;
+    vector: Float32Array;
+    neighbors: number[][];
+}
+export declare class HNSWIndex {
+    private M;
+    private M0;
+    private efConstruction;
+    private levelMult;
+    private maxLevel;
+    private entryPointId;
+    private nodes;
+    private nodeCount;
+    private dimension;
+    private metric;
+    private maxLayers;
+    private distanceBackend;
+    private flatVectors;
+    private flatVectorsCapacity;
+    private searchHeap;
+    private visitedArray;
+    private visitedArraySize;
+    private visitedGeneration;
+    private candidatesHeap;
+    private resultsHeap;
+    private selectionHeap;
+    private heapCapacity;
+    private vectorsAreNormalized;
+    private distanceFn;
+    private scalarQuantizer;
+    private int8Vectors;
+    private quantizationEnabled;
+    private lazyLoadEnabled;
+    private vectorOffsets;
+    private vectorBuffer;
+    private vectorsLoaded;
+    private queryNormBuffer;
+    private neighborSets;
+    private constructionMode;
+    constructor(dimension: number, metric?: DistanceMetric, M?: number, efConstruction?: number, distanceBackend?: DistanceBackend);
+    /**
+     * Ensure node array and flat vector storage have enough capacity
+     */
+    private ensureCapacity;
+    /**
+     * Get vector from flat storage by node ID
+     * Returns a subarray view (no copy) for efficiency
+     */
+    private getFlatVector;
+    /**
+     * Set vector in flat storage
+     */
+    private setFlatVector;
+    /**
+     * Get node by ID (O(1) array access)
+     */
+    private getNode;
+    /**
+     * Set node by ID
+     */
+    private setNode;
+    private batchNeighborIds;
+    private batchDistances;
+    /**
+     * OPTIMIZATION: Batch distance calculation for better cache locality
+     * Computes distances from query to multiple neighbors at once
+     * Uses flat vector storage for contiguous memory access
+     */
+    private calculateDistancesBatch;
+    /**
+     * Check if a node has been visited in the current search.
+     * Uses generation counting to avoid clearing the array.
+     */
+    private isVisited;
+    /**
+     * Mark a node as visited in the current search.
+     * Grows the array if needed.
+     */
+    private markVisited;
+    /**
+     * Clear all visited markers by incrementing the generation.
+     * Much faster than filling the array with zeros.
+     */
+    private clearVisited;
+    private normalizeVector;
+    private selectLevel;
+    /**
+     * Calculate distance between two vectors using the configured metric.
+     * Uses cached function pointer to avoid switch overhead.
+     */
+    calculateDistance(a: Float32Array, b: Float32Array): number;
+    /**
+     * Get a node's vector, loading it if necessary (for lazy loading support)
+     */
+    private getNodeVector;
+    private getLayerMaxConnections;
+    private selectNeighbors;
+    private addBidirectionalConnection;
+    /**
+     * Ensure heap capacity is sufficient for the given ef value.
+     * Resizes heaps if needed.
+     */
+    private ensureHeapCapacity;
+    /**
+     * Search a layer using the standard two-heap HNSW algorithm.
+     *
+     * Uses two heaps:
+     * - candidatesHeap (min-heap): Tracks nodes to explore, prioritizing closest
+     * - resultsHeap (max-heap): Tracks top-ef results, allowing O(log n) eviction of furthest
+     *
+     * Termination: Stops when closest unvisited candidate is farther than furthest result.
+     */
+    private searchLayer;
+    private greedySearch;
+    /**
+     * Add a point to the index (async wrapper for API compatibility)
+     * For bulk operations, use addPointsBulk() which uses the faster sync version internally
+     */
+    addPoint(id: number, vector: number[] | Float32Array, options?: {
+        skipNormalization?: boolean;
+    }): Promise<void>;
+    /**
+     * Synchronous version of addPoint - avoids async/await microtask overhead
+     * 10-15x faster for bulk insertions where async is not needed
+     * @param skipNormalization - Set true if vectors are already unit-normalized (e.g., Cohere embeddings)
+     */
+    addPointSync(id: number, vector: number[] | Float32Array, options?: {
+        skipNormalization?: boolean;
+    }): void;
+    searchKNN(query: Float32Array, k: number, efSearch?: number): Array<{
+        id: number;
+        distance: number;
+    }>;
+    /**
+     * Batch search for multiple query vectors.
+     * More efficient than calling searchKNN multiple times as it reuses internal buffers.
+     *
+     * @param queries Array of query vectors
+     * @param k Number of nearest neighbors to return per query
+     * @param efSearch Search effort parameter (higher = better recall, slower)
+     * @returns Array of results, one per query
+     */
+    searchKNNBatch(queries: Float32Array[], k: number, efSearch?: number): Array<Array<{
+        id: number;
+        distance: number;
+    }>>;
+    /**
+     * Optimized batch search that returns results in a flat structure for better performance.
+     * Useful when you need to process many queries quickly.
+     *
+     * @param queries Flat Float32Array containing all queries concatenated
+     * @param numQueries Number of queries in the array
+     * @param k Number of nearest neighbors to return per query
+     * @param efSearch Search effort parameter
+     * @returns Object with flat arrays for ids and distances
+     */
+    searchKNNBatchFlat(queries: Float32Array, numQueries: number, k: number, efSearch?: number): {
+        ids: Uint32Array;
+        distances: Float32Array;
+    };
+    /**
+     * Add a single vector with auto-generated ID.
+     * Returns the assigned ID.
+     *
+     * @param vector Vector to add
+     * @returns The auto-generated ID
+     *
+     * @example
+     * ```typescript
+     * const id = await index.add([0.1, 0.2, 0.3]);
+     * console.log(`Added vector with ID: ${id}`);
+     * ```
+     */
+    add(vector: number[] | Float32Array): Promise<number>;
+    /**
+     * Simple query interface - find k nearest neighbors.
+     *
+     * @param vector Query vector
+     * @param k Number of results (default: 10)
+     * @returns Array of {id, distance} results
+     *
+     * @example
+     * ```typescript
+     * const results = index.query([0.1, 0.2, 0.3], 5);
+     * results.forEach(r => console.log(`ID: ${r.id}, Distance: ${r.distance}`));
+     * ```
+     */
+    query(vector: number[] | Float32Array, k?: number): Array<{
+        id: number;
+        distance: number;
+    }>;
+    /**
+     * Add multiple vectors with auto-generated IDs.
+     * Returns the assigned IDs.
+     *
+     * @param vectors Array of vectors to add
+     * @returns Array of auto-generated IDs
+     *
+     * @example
+     * ```typescript
+     * const ids = await index.addAll([[0.1, 0.2], [0.3, 0.4]]);
+     * ```
+     */
+    addAll(vectors: Array<number[] | Float32Array>): Promise<number[]>;
+    /**
+     * Bulk add multiple points with optimized O(1) neighbor lookups.
+     * Significantly faster than sequential addPoint() calls for large batches.
+     * Uses Set-based membership testing during construction, then releases memory.
+     *
+     * @param points Array of {id, vector} to add
+     * @example
+     * ```typescript
+     * await index.addPointsBulk([
+     *   { id: 0, vector: new Float32Array([0.1, 0.2, ...]) },
+     *   { id: 1, vector: new Float32Array([0.3, 0.4, ...]) },
+     * ]);
+     * ```
+     */
+    addPointsBulk(points: Array<{
+        id: number;
+        vector: Float32Array;
+    }>, options?: {
+        skipNormalization?: boolean;
+    }): Promise<void>;
+    /**
+     * Synchronous bulk insertion - 10-15x faster than async version
+     * Uses addPointSync() internally to avoid microtask queue overhead
+     * @param skipNormalization - Set true if vectors are already unit-normalized
+     */
+    addPointsBulkSync(points: Array<{
+        id: number;
+        vector: Float32Array;
+    }>, options?: {
+        skipNormalization?: boolean;
+    }): void;
+    /**
+     * Clear construction-time data structures to free memory.
+     * Called automatically after addPointsBulk(), but can be called
+     * manually if needed.
+     */
+    clearConstructionCache(): void;
+    private static readonly MAGIC;
+    private static readonly FORMAT_VERSION;
+    private static readonly HEADER_SIZE;
+    /**
+     * Get all nodes as an array (filters out undefined slots)
+     */
+    private getNodesArray;
+    serialize(): ArrayBuffer;
+    /**
+     * Deserialize an HNSW index from a buffer.
+     *
+     * @param buffer The serialized index buffer
+     * @param options Optional loading options
+     *   - lazyLoadVectors: If true, don't load vectors immediately (v3+ only)
+     */
+    static deserialize(buffer: ArrayBuffer, options?: {
+        lazyLoadVectors?: boolean;
+    }): HNSWIndex;
+    /**
+     * Load a specific vector on demand (for lazy-loaded indices).
+     * Returns the vector if lazy loading is enabled, otherwise returns the already-loaded vector.
+     */
+    loadVector(nodeId: number): Float32Array | null;
+    /**
+     * Preload vectors for specific node IDs.
+     * Useful for warming up cache before searches.
+     */
+    preloadVectors(nodeIds: number[]): void;
+    /**
+     * Check if lazy loading is enabled
+     */
+    isLazyLoadEnabled(): boolean;
+    /**
+     * Get lazy loading statistics
+     */
+    getLazyLoadStats(): {
+        enabled: boolean;
+        totalNodes: number;
+        loadedVectors: number;
+        memoryReduction: string;
+    };
+    saveToFile(filePath: string): Promise<void>;
+    static loadFromFile(filePath: string): Promise<HNSWIndex>;
+    destroy(): void;
+    /**
+     * Get memory usage statistics
+     */
+    getMemoryUsage(): number;
+    /**
+     * Get all vectors for brute-force search
+     */
+    getAllVectors(): Map<number, Float32Array>;
+    /**
+     * Enable Int8 quantization for faster search with automatic rescoring.
+     * Trains the quantizer on existing vectors and quantizes them.
+     *
+     * Performance:
+     * - 4x memory reduction
+     * - 3-4x faster distance calculations
+     * - 99%+ recall with automatic rescoring
+     *
+     * @example
+     * ```typescript
+     * // After adding vectors
+     * index.enableQuantization();
+     *
+     * // Now use quantized search (automatically rescores for high recall)
+     * const results = index.searchKNNQuantized(query, 10);
+     * ```
+     */
+    enableQuantization(): void;
+    /**
+     * Check if quantization is enabled
+     */
+    isQuantizationEnabled(): boolean;
+    /**
+     * Fast quantized search with automatic rescoring.
+     *
+     * Uses Int8 quantized vectors for initial candidate retrieval (3-4x faster),
+     * then rescores top candidates with float32 for accurate ranking.
+     *
+     * @param query Query vector
+     * @param k Number of results to return
+     * @param candidateMultiplier How many extra candidates to retrieve for rescoring (default: 3)
+     * @param efSearch Search effort parameter
+     * @returns Array of {id, distance} results (same format as searchKNN)
+     *
+     * Performance:
+     * - 3-4x faster than float32 for distance calculations
+     * - 99%+ recall with candidateMultiplier=3 (automatic rescoring)
+     * - 4x memory reduction
+     */
+    searchKNNQuantized(query: Float32Array, k: number, candidateMultiplier?: number, efSearch?: number): Array<{
+        id: number;
+        distance: number;
+    }>;
+    /**
+     * Search layer using Int8 quantized distances for speed.
+     * Same algorithm as searchLayer but uses faster Int8 distance calculations.
+     */
+    private searchLayerQuantized;
+    /**
+     * Get quantization statistics
+     */
+    getQuantizationStats(): {
+        enabled: boolean;
+        vectorCount: number;
+        memoryReduction: string;
+        expectedSpeedup: string;
+    };
+}
+//# sourceMappingURL=HNSWIndex.d.ts.map

package/dist/HNSWIndex.d.ts.map

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

package/dist/MaxBinaryHeap.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MaxBinaryHeap - A max-heap implementation for HNSW result tracking.
+ *
+ * In HNSW search, we need to track the top-k closest results efficiently.
+ * A max-heap keeps the FURTHEST element at the top, allowing O(log n) eviction
+ * of the worst result when a better one is found.
+ *
+ * This complements BinaryHeap (min-heap) which is used for candidate exploration.
+ */
+export declare class MaxBinaryHeap {
+    private ids;
+    private dists;
+    private _size;
+    private capacity;
+    constructor(capacity: number);
+    /**
+     * Push an element onto the heap.
+     * When at capacity, replaces the max element if the new one is closer.
+     */
+    push(id: number, dist: number): void;
+    /**
+     * Remove and return the ID of the maximum element (furthest distance).
+     * Returns -1 if heap is empty.
+     */
+    pop(): number;
+    /**
+     * Peek at the ID of the maximum element without removing it.
+     * Returns -1 if heap is empty.
+     */
+    peek(): number;
+    /**
+     * Peek at the distance of the maximum element (furthest from query).
+     * Returns -Infinity if heap is empty.
+     */
+    peekValue(): number;
+    /**
+     * Get the current number of elements in the heap.
+     */
+    size(): number;
+    /**
+     * Check if the heap is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Clear all elements from the heap.
+     */
+    clear(): void;
+    /**
+     * Get the capacity of the heap.
+     */
+    getCapacity(): number;
+    /**
+     * Heapify up: restore max-heap property after insertion.
+     * Parent should be LARGER than children in a max-heap.
+     */
+    private heapifyUp;
+    /**
+     * Heapify down: restore max-heap property after removal.
+     * Find largest among node and children, swap if needed.
+     */
+    private heapifyDown;
+}
+//# sourceMappingURL=MaxBinaryHeap.d.ts.map

package/dist/MaxBinaryHeap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaxBinaryHeap.d.ts","sourceRoot":"","sources":["../src/MaxBinaryHeap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAO5B;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAmBpC;;;OAGG;IACH,GAAG,IAAI,MAAM;IAeb;;;OAGG;IACH,IAAI,IAAI,MAAM;IAId;;;OAGG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAwBjB;;;OAGG;IACH,OAAO,CAAC,WAAW;CAkCpB"}

package/dist/Storage.d.ts

@@ -0,0 +1,54 @@
+export declare class MetadataStorage {
+    private metadataMap;
+    private idList;
+    constructor();
+    private ensureInitialized;
+    set(id: string, metadata: any): void;
+    get(id: string): any | undefined;
+    has(id: string): boolean;
+    delete(id: string): boolean;
+    getAllIds(): string[];
+    entries(): [string, any][];
+    clear(): void;
+    destroy(): void;
+    size(): number;
+    saveToDisk(filePath: string): Promise<void>;
+    private createBinaryBuffer;
+    loadFromDisk(filePath: string): Promise<void>;
+    private loadFromBinaryBuffer;
+}
+export declare class VectorStorage {
+    private dimension;
+    private vectors;
+    private vectorCount;
+    private capacity;
+    private filePath;
+    private fileHandle;
+    constructor(dimension: number, initialCapacity?: number);
+    initializeForMemoryMapping(filePath: string): Promise<void>;
+    addVector(vector: number[]): number;
+    getVector(index: number): number[];
+    getVectorAsTypedArray(index: number): Float32Array;
+    getVectorCount(): number;
+    getDimension(): number;
+    private expandCapacity;
+    saveToDisk(filePath: string): Promise<void>;
+    loadFromDisk(filePath: string): Promise<void>;
+    destroy(): void;
+}
+export declare class MemoryMappedVectorStorage {
+    private dimension;
+    private vectorCount;
+    private filePath;
+    private mappedBuffer;
+    private mappedView;
+    constructor(dimension: number);
+    initializeMemoryMapping(filePath: string): Promise<void>;
+    getVector(index: number): number[];
+    getVectorAsTypedArray(index: number): Float32Array;
+    getVectorCount(): number;
+    getDimension(): number;
+    appendVector(vector: number[]): Promise<void>;
+    destroy(): void;
+}
+//# sourceMappingURL=Storage.d.ts.map

package/dist/Storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../src/Storage.ts"],"names":[],"mappings":"AAKA,qBAAa,eAAe;IAC1B,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,MAAM,CAAkB;;IAOhC,OAAO,CAAC,iBAAiB;IAMzB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,IAAI;IAUpC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAKhC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAKxB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAU3B,SAAS,IAAI,MAAM,EAAE;IAKrB,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;IAK1B,KAAK,IAAI,IAAI;IAMb,OAAO,IAAI,IAAI;IAMf,IAAI,IAAI,MAAM;IAKR,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,OAAO,CAAC,kBAAkB;IAoCpB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAanD,OAAO,CAAC,oBAAoB;CA6B7B;AAGD,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,UAAU,CAAa;gBAEnB,SAAS,EAAE,MAAM,EAAE,eAAe,GAAE,MAAa;IAOvD,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAejE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM;IAuBnC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAclC,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IASlD,cAAc,IAAI,MAAM;IAIxB,YAAY,IAAI,MAAM;IAItB,OAAO,CAAC,cAAc;IAQhB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB3C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnD,OAAO,IAAI,IAAI;CAQhB;AAGD,qBAAa,yBAAyB;IACpC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,UAAU,CAA6B;gBAEnC,SAAS,EAAE,MAAM;IAKvB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B9D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAkBlC,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAalD,cAAc,IAAI,MAAM;IAIxB,YAAY,IAAI,MAAM;IAIhB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4CnD,OAAO,IAAI,IAAI;CAMhB"}

package/dist/VectorDB.d.ts

@@ -0,0 +1,44 @@
+import { Collection } from './Collection';
+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'
+     * Ignored if a custom storageBackend is provided.
+     */
+    storagePath?: string;
+    /**
+     * Custom storage backend for platform-specific storage (e.g., OPFS for browsers).
+     * If not provided, defaults to BunStorageBackend with storagePath.
+     */
+    storageBackend?: StorageBackend;
+}
+export interface CollectionConfig {
+    dimension: number;
+    metric?: DistanceMetric;
+    M?: number;
+    efConstruction?: number;
+}
+export declare class VectorDB {
+    private collections;
+    private storagePath;
+    private storageBackend;
+    private initialized;
+    constructor(config?: VectorDBConfig);
+    /**
+     * 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.
+     * Called automatically on first operation if not called explicitly.
+     */
+    init(): Promise<void>;
+    createCollection(name: string, config: CollectionConfig): Promise<Collection>;
+    getCollection(name: string): Collection | undefined;
+    listCollections(): Promise<string[]>;
+    deleteCollection(name: string): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=VectorDB.d.ts.map

package/dist/VectorDB.d.ts.map

@@ -0,0 +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"}

package/dist/backends/DistanceBackend.d.ts

@@ -0,0 +1,5 @@
+export interface DistanceBackend {
+    batchL2(base: Float32Array, dim: number, ids: Uint32Array, query: Float32Array, out: Float32Array): void;
+    batchDot(base: Float32Array, dim: number, ids: Uint32Array, query: Float32Array, out: Float32Array): void;
+}
+//# sourceMappingURL=DistanceBackend.d.ts.map

package/dist/backends/DistanceBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DistanceBackend.d.ts","sourceRoot":"","sources":["../../src/backends/DistanceBackend.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,OAAO,CACL,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,YAAY,GAChB,IAAI,CAAC;IAER,QAAQ,CACN,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,YAAY,GAChB,IAAI,CAAC;CACT"}

package/dist/backends/JsDistanceBackend.d.ts

@@ -0,0 +1,37 @@
+import { DistanceBackend } from './DistanceBackend';
+/**
+ * Optimized JavaScript distance backend with SIMD-style 4-wide unrolling.
+ * This provides ~1.5-2x speedup over naive loops by reducing loop overhead
+ * and enabling better CPU pipelining.
+ */
+export declare class JsDistanceBackend implements DistanceBackend {
+    batchL2(base: Float32Array, dim: number, ids: Uint32Array, query: Float32Array, out: Float32Array): void;
+    batchDot(base: Float32Array, dim: number, ids: Uint32Array, query: Float32Array, out: Float32Array): void;
+    /**
+     * Compute dot product with 4-wide manual unrolling for better performance.
+     * Uses separate accumulators to enable instruction-level parallelism.
+     */
+    private dotProductUnrolled;
+    /**
+     * Compute L2 squared distance with 4-wide manual unrolling.
+     */
+    private l2SquaredUnrolled;
+}
+/**
+ * Fast inline distance functions for single-vector comparisons.
+ * These avoid the batch interface overhead for point-to-point distance calculations.
+ */
+export declare function dotProductFast(a: Float32Array, b: Float32Array): number;
+export declare function l2SquaredFast(a: Float32Array, b: Float32Array): number;
+/**
+ * Normalize a vector in place.
+ * Uses 8-wide unrolling for better ILP.
+ */
+export declare function normalizeInPlace(v: Float32Array): number;
+/**
+ * Compute cosine distance between two vectors.
+ * For pre-normalized vectors, this is simply 1 - dot(a, b).
+ * Uses 8-wide unrolling for norm computation.
+ */
+export declare function cosineDistanceFast(a: Float32Array, b: Float32Array, aIsNormalized?: boolean, bIsNormalized?: boolean): number;
+//# sourceMappingURL=JsDistanceBackend.d.ts.map

package/dist/backends/JsDistanceBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsDistanceBackend.d.ts","sourceRoot":"","sources":["../../src/backends/JsDistanceBackend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI;IAQxG,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI;IAQzG;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAyB1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CA0BvE;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAmCtE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CA6BxD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,aAAa,UAAQ,EAAE,aAAa,UAAQ,GAAG,MAAM,CAsCzH"}

package/dist/encoding/DeltaEncoder.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Delta Encoding with Varint for Neighbor Lists
+ *
+ * Implements delta-encoded neighbor lists as used by Qdrant for ~38% storage reduction.
+ * Neighbor IDs are sorted, then stored as deltas with variable-length encoding.
+ *
+ * Format:
+ * - First ID stored as full uint32
+ * - Subsequent IDs stored as varint deltas from previous ID
+ *
+ * Varint encoding (like Protocol Buffers):
+ * - Values 0-127: 1 byte
+ * - Values 128-16383: 2 bytes
+ * - Values 16384-2097151: 3 bytes
+ * - Values 2097152-268435455: 4 bytes
+ * - Larger: 5 bytes
+ */
+/**
+ * Encode an unsigned integer as a varint
+ * Returns the number of bytes written
+ */
+export declare function encodeVarint(value: number, buffer: Uint8Array, offset: number): number;
+/**
+ * Decode a varint from buffer
+ * Returns [value, bytesRead]
+ */
+export declare function decodeVarint(buffer: Uint8Array, offset: number): [number, number];
+/**
+ * Calculate the number of bytes needed to encode a varint
+ */
+export declare function varintSize(value: number): number;
+/**
+ * Delta-encode a sorted array of neighbor IDs
+ * Returns the encoded buffer
+ */
+export declare function deltaEncodeNeighbors(neighbors: number[]): Uint8Array;
+/**
+ * Decode a delta-encoded neighbor list
+ * Returns the original neighbor IDs (sorted)
+ */
+export declare function deltaDecodeNeighbors(buffer: Uint8Array, count: number): number[];
+/**
+ * Calculate the encoded size for a neighbor list without actually encoding
+ * Useful for calculating total buffer size before serialization
+ */
+export declare function deltaEncodedSize(neighbors: number[]): number;
+/**
+ * Batch encode multiple neighbor lists efficiently
+ * Returns a single buffer with all encoded lists concatenated
+ * Also returns offsets for each list
+ */
+export declare function deltaEncodeBatch(neighborLists: number[][]): {
+    buffer: Uint8Array;
+    offsets: number[];
+    sizes: number[];
+};
+/**
+ * Decode a batch of neighbor lists from a single buffer
+ */
+export declare function deltaDecodeBatch(buffer: Uint8Array, offsets: number[], sizes: number[], counts: number[]): number[][];
+//# sourceMappingURL=DeltaEncoder.d.ts.map

package/dist/encoding/DeltaEncoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeltaEncoder.d.ts","sourceRoot":"","sources":["../../src/encoding/DeltaEncoder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAWtF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqBjF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,CAkCpE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBhF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAgB5D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,EAAE,GAAG;IAC3D,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAqBA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,EAAE,EAAE,CAaZ"}