verso-db 0.1.5 → 0.2.0

package/src/MaxBinaryHeap.ts

@@ -1,181 +0,0 @@
-/**
- * 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 class MaxBinaryHeap {
-  private ids: Uint32Array;
-  private dists: Float32Array;
-  private _size: number;
-  private capacity: number;
-
-  constructor(capacity: number) {
-    this.capacity = capacity;
-    this.ids = new Uint32Array(capacity);
-    this.dists = new Float32Array(capacity);
-    this._size = 0;
-  }
-
-  /**
-   * Push an element onto the heap.
-   * Auto-grows when at capacity to avoid silently dropping elements.
-   */
-  push(id: number, dist: number): void {
-    if (this._size >= this.capacity) {
-      this.grow();
-    }
-
-    this.ids[this._size] = id;
-    this.dists[this._size] = dist;
-    this._size++;
-    this.heapifyUp(this._size - 1);
-  }
-
-  /**
-   * Double the heap capacity when full.
-   */
-  private grow(): void {
-    const newCapacity = Math.max(this.capacity * 2, 16);
-    const newIds = new Uint32Array(newCapacity);
-    const newDists = new Float32Array(newCapacity);
-    newIds.set(this.ids);
-    newDists.set(this.dists);
-    this.ids = newIds;
-    this.dists = newDists;
-    this.capacity = newCapacity;
-  }
-
-  /**
-   * Remove and return the ID of the maximum element (furthest distance).
-   * Returns -1 if heap is empty.
-   */
-  pop(): number {
-    if (this._size === 0) return -1;
-
-    const result = this.ids[0];
-    this._size--;
-
-    if (this._size > 0) {
-      this.ids[0] = this.ids[this._size];
-      this.dists[0] = this.dists[this._size];
-      this.heapifyDown(0);
-    }
-
-    return result;
-  }
-
-  /**
-   * Peek at the ID of the maximum element without removing it.
-   * Returns -1 if heap is empty.
-   */
-  peek(): number {
-    return this._size > 0 ? this.ids[0] : -1;
-  }
-
-  /**
-   * Peek at the distance of the maximum element (furthest from query).
-   * Returns -Infinity if heap is empty.
-   */
-  peekValue(): number {
-    return this._size > 0 ? this.dists[0] : -Infinity;
-  }
-
-  /**
-   * Get the current number of elements in the heap.
-   */
-  size(): number {
-    return this._size;
-  }
-
-  /**
-   * Check if the heap is empty.
-   */
-  isEmpty(): boolean {
-    return this._size === 0;
-  }
-
-  /**
-   * Clear all elements from the heap.
-   */
-  clear(): void {
-    this._size = 0;
-  }
-
-  /**
-   * Get the capacity of the heap.
-   */
-  getCapacity(): number {
-    return this.capacity;
-  }
-
-  /**
-   * Heapify up: restore max-heap property after insertion.
-   * Parent should be LARGER than children in a max-heap.
-   */
-  private heapifyUp(index: number): void {
-    // Cache array references to avoid repeated property lookups
-    const ids = this.ids;
-    const dists = this.dists;
-
-    while (index > 0) {
-      // Use bitwise shift for faster integer division
-      const parentIndex = (index - 1) >> 1;
-      // MAX-HEAP: Parent should be >= child
-      if (dists[parentIndex] >= dists[index]) break;
-
-      // Inline swap for performance
-      const tmpId = ids[index];
-      ids[index] = ids[parentIndex];
-      ids[parentIndex] = tmpId;
-
-      const tmpDist = dists[index];
-      dists[index] = dists[parentIndex];
-      dists[parentIndex] = tmpDist;
-
-      index = parentIndex;
-    }
-  }
-
-  /**
-   * Heapify down: restore max-heap property after removal.
-   * Find largest among node and children, swap if needed.
-   */
-  private heapifyDown(index: number): void {
-    // Cache array references to avoid repeated property lookups
-    const ids = this.ids;
-    const dists = this.dists;
-    const size = this._size;
-
-    while (true) {
-      const leftChild = (index << 1) + 1; // 2 * index + 1
-      const rightChild = leftChild + 1;   // 2 * index + 2
-      let largest = index;
-
-      // MAX-HEAP: Find largest among node and children
-      if (leftChild < size && dists[leftChild] > dists[largest]) {
-        largest = leftChild;
-      }
-
-      if (rightChild < size && dists[rightChild] > dists[largest]) {
-        largest = rightChild;
-      }
-
-      if (largest === index) break;
-
-      // Inline swap for performance
-      const tmpId = ids[index];
-      ids[index] = ids[largest];
-      ids[largest] = tmpId;
-
-      const tmpDist = dists[index];
-      dists[index] = dists[largest];
-      dists[largest] = tmpDist;
-
-      index = largest;
-    }
-  }
-}

package/src/SearchWorker.ts

@@ -1,264 +0,0 @@
-/**
- * Search worker entry point for parallel query processing.
- * Each worker maintains independent search state (visited array, heaps)
- * and operates on shared read-only vector data.
- */
-
-import { dotProductFast, l2SquaredFast, normalizeInPlace } from './backends/JsDistanceBackend';
-import { BinaryHeap } from './BinaryHeap';
-import { MaxBinaryHeap } from './MaxBinaryHeap';
-
-export interface WorkerInitData {
-  flatVectors: Float32Array;
-  dimension: number;
-  nodeCount: number;
-  metric: 'cosine' | 'euclidean' | 'dot_product';
-  entryPointId: number;
-  maxLevel: number;
-  M: number;
-  M0: number;
-  // Graph structure: serialized neighbor lists
-  graphData: ArrayBuffer;
-  nodeLevels: Uint8Array;
-}
-
-interface WorkerInitMessage extends WorkerInitData {
-  type: 'init';
-}
-
-interface WorkerSearchMessage {
-  type: 'search';
-  queryId: number;
-  query: Float32Array;
-  k: number;
-  efSearch: number;
-}
-
-interface WorkerSearchResult {
-  type: 'result';
-  queryId: number;
-  results: Array<{ id: number; distance: number }>;
-}
-
-// Only run as worker if loaded in worker context
-if (typeof self !== 'undefined' && typeof (self as any).postMessage === 'function') {
-  let state: WorkerSearchState | null = null;
-
-  self.onmessage = (event: MessageEvent) => {
-    const msg = event.data;
-
-    if (msg.type === 'init') {
-      state = new WorkerSearchState(msg);
-      (self as any).postMessage({ type: 'ready' });
-    } else if (msg.type === 'search') {
-      if (!state) {
-        (self as any).postMessage({ type: 'error', queryId: msg.queryId, error: 'Worker not initialized' });
-        return;
-      }
-      const results = state.searchKNN(msg.query, msg.k, msg.efSearch);
-      (self as any).postMessage({ type: 'result', queryId: msg.queryId, results } as WorkerSearchResult);
-    }
-  };
-}
-
-/**
- * Independent search state for a single worker.
- * Mirrors the essential search logic from HNSWIndex without mutation.
- */
-export class WorkerSearchState {
-  private flatVectors: Float32Array;
-  private dimension: number;
-  private nodeCount: number;
-  private metric: 'cosine' | 'euclidean' | 'dot_product';
-  private entryPointId: number;
-  private maxLevel: number;
-  private M: number;
-  private M0: number;
-  private nodeLevels: Uint8Array;
-  // Deserialized neighbor lists: neighbors[nodeId][layer] = number[]
-  private neighbors: number[][][];
-
-  // Independent search state
-  private visitedArray: Uint16Array;
-  private visitedGeneration: number = 1;
-  private candidatesHeap: BinaryHeap;
-  private resultsHeap: MaxBinaryHeap;
-  private queryNormBuffer: Float32Array;
-  private vectorsAreNormalized: boolean;
-
-  private distanceFn: (a: Float32Array, b: Float32Array) => number;
-
-  constructor(init: WorkerInitData) {
-    this.flatVectors = init.flatVectors;
-    this.dimension = init.dimension;
-    this.nodeCount = init.nodeCount;
-    this.metric = init.metric;
-    this.entryPointId = init.entryPointId;
-    this.maxLevel = init.maxLevel;
-    this.M = init.M;
-    this.M0 = init.M0;
-    this.nodeLevels = init.nodeLevels;
-    this.vectorsAreNormalized = init.metric === 'cosine';
-
-    // Deserialize graph structure
-    this.neighbors = this.deserializeGraph(init.graphData);
-
-    // Initialize search state
-    this.visitedArray = new Uint16Array(init.nodeCount + 1000);
-    const heapCap = Math.max(512, 500);
-    this.candidatesHeap = new BinaryHeap(heapCap);
-    this.resultsHeap = new MaxBinaryHeap(heapCap);
-    this.queryNormBuffer = new Float32Array(init.dimension);
-
-    // Set up distance function
-    if (init.metric === 'cosine') {
-      this.distanceFn = (a, b) => {
-        const dot = dotProductFast(a, b);
-        const d = 1 - dot;
-        return d < 1e-10 ? 0 : d;
-      };
-    } else if (init.metric === 'euclidean') {
-      this.distanceFn = (a, b) => Math.sqrt(l2SquaredFast(a, b));
-    } else {
-      this.distanceFn = (a, b) => -dotProductFast(a, b);
-    }
-  }
-
-  private deserializeGraph(buffer: ArrayBuffer): number[][][] {
-    const view = new DataView(buffer);
-    const neighbors: number[][][] = new Array(this.nodeCount);
-    let offset = 0;
-
-    for (let nodeId = 0; nodeId < this.nodeCount; nodeId++) {
-      const numLayers = view.getUint8(offset++);
-      const layers: number[][] = new Array(numLayers);
-
-      for (let l = 0; l < numLayers; l++) {
-        const numNeighbors = view.getUint16(offset, true);
-        offset += 2;
-        const neighborList: number[] = new Array(numNeighbors);
-
-        for (let n = 0; n < numNeighbors; n++) {
-          neighborList[n] = view.getUint32(offset, true);
-          offset += 4;
-        }
-        layers[l] = neighborList;
-      }
-      neighbors[nodeId] = layers;
-    }
-
-    return neighbors;
-  }
-
-  private getVector(nodeId: number): Float32Array {
-    const offset = nodeId * this.dimension;
-    return this.flatVectors.subarray(offset, offset + this.dimension);
-  }
-
-  private clearVisited(): void {
-    this.visitedGeneration++;
-    if (this.visitedGeneration > 65000) {
-      this.visitedArray.fill(0);
-      this.visitedGeneration = 1;
-    }
-  }
-
-  private isVisited(id: number): boolean {
-    return id < this.visitedArray.length && this.visitedArray[id] === this.visitedGeneration;
-  }
-
-  private markVisited(id: number): void {
-    if (id >= this.visitedArray.length) {
-      const newArr = new Uint16Array(Math.max(this.visitedArray.length * 2, id + 1000));
-      newArr.set(this.visitedArray);
-      this.visitedArray = newArr;
-    }
-    this.visitedArray[id] = this.visitedGeneration;
-  }
-
-  searchKNN(query: Float32Array, k: number, efSearch: number): Array<{ id: number; distance: number }> {
-    if (this.entryPointId === -1 || this.nodeCount === 0) return [];
-
-    const effectiveEf = efSearch || Math.max(k * 2, 50);
-
-    let normalizedQuery = query;
-    if (this.vectorsAreNormalized) {
-      this.queryNormBuffer.set(query);
-      normalizeInPlace(this.queryNormBuffer);
-      normalizedQuery = this.queryNormBuffer;
-    }
-
-    // Greedy descent from top to layer 1
-    let currentBestId = this.entryPointId;
-    let currentBestDist = this.distanceFn(normalizedQuery, this.getVector(this.entryPointId));
-
-    for (let l = this.maxLevel; l > 0; l--) {
-      this.clearVisited();
-      this.markVisited(currentBestId);
-      let improved = true;
-      while (improved) {
-        improved = false;
-        const nodeNeighbors = this.neighbors[currentBestId]?.[l] || [];
-        for (const nid of nodeNeighbors) {
-          if (this.isVisited(nid)) continue;
-          this.markVisited(nid);
-          const dist = this.distanceFn(normalizedQuery, this.getVector(nid));
-          if (dist < currentBestDist) {
-            currentBestDist = dist;
-            currentBestId = nid;
-            improved = true;
-          }
-        }
-      }
-    }
-
-    // Search layer 0
-    this.clearVisited();
-    this.candidatesHeap.clear();
-    this.resultsHeap.clear();
-
-    this.candidatesHeap.push(currentBestId, currentBestDist);
-    this.resultsHeap.push(currentBestId, currentBestDist);
-    this.markVisited(currentBestId);
-
-    let furthestResultDist = currentBestDist;
-
-    while (!this.candidatesHeap.isEmpty()) {
-      const candDist = this.candidatesHeap.peekValue();
-      if (candDist > furthestResultDist && this.resultsHeap.size() >= effectiveEf) break;
-
-      const candId = this.candidatesHeap.pop();
-      const nodeNeighbors = this.neighbors[candId]?.[0] || [];
-
-      for (const neighborId of nodeNeighbors) {
-        if (this.isVisited(neighborId)) continue;
-        this.markVisited(neighborId);
-
-        const distance = this.distanceFn(normalizedQuery, this.getVector(neighborId));
-
-        if (this.resultsHeap.size() < effectiveEf || distance < furthestResultDist) {
-          this.candidatesHeap.push(neighborId, distance);
-          this.resultsHeap.push(neighborId, distance);
-
-          if (this.resultsHeap.size() > effectiveEf) {
-            this.resultsHeap.pop();
-          }
-          furthestResultDist = this.resultsHeap.peekValue();
-        }
-      }
-    }
-
-    // Extract results in ascending distance order
-    const resultCount = this.resultsHeap.size();
-    const results: Array<{ id: number; distance: number }> = new Array(resultCount);
-    let idx = resultCount - 1;
-    while (!this.resultsHeap.isEmpty()) {
-      const dist = this.resultsHeap.peekValue();
-      const id = this.resultsHeap.pop();
-      results[idx--] = { id, distance: dist };
-    }
-
-    if (results.length > k) results.length = k;
-    return results;
-  }
-}