eigen-db 4.0.1 → 4.1.0

package/src/lib/__tests__/vector-db.test.ts

@@ -180,17 +180,17 @@ describe("VectorDB", () => {
       const results = db.query([1, 0, 0, 0]);
       expect(results.length).toBe(3);
 
-      // x-axis should be the best match (identical direction)
+      // x-axis should be the best match (identical direction, distance ≈ 0)
       expect(results[0].key).toBe("x-axis");
-      expect(results[0].score).toBeCloseTo(1.0, 2);
+      expect(results[0].distance).toBeCloseTo(0.0, 2);
 
       // xy-axis should be second (partially aligned)
       expect(results[1].key).toBe("xy-axis");
-      expect(results[1].score).toBeGreaterThan(0);
+      expect(results[1].distance).toBeLessThan(1);
 
-      // y-axis should be last (orthogonal)
+      // y-axis should be last (orthogonal, distance ≈ 1)
       expect(results[2].key).toBe("y-axis");
-      expect(results[2].score).toBeCloseTo(0.0, 2);
+      expect(results[2].distance).toBeCloseTo(1.0, 2);
     });
 
     it("query respects topK option", async () => {
@@ -251,7 +251,7 @@ describe("VectorDB", () => {
       expect(all).toHaveLength(5);
 
       // Partial iteration (simulate pagination)
-      const page: { key: string; score: number }[] = [];
+      const page: { key: string; distance: number }[] = [];
       for (const item of results) {
         page.push(item);
         if (page.length === 2) break;
@@ -273,12 +273,67 @@ describe("VectorDB", () => {
       db.set("point", [0, 1, 0, 0]);
 
       const results = db.query([0, 1, 0, 0]);
-      // Both 'point' and 'other' are now along y-axis, so both should score high
-      expect(results[0].score).toBeCloseTo(1.0, 2);
-      expect(results[1].score).toBeCloseTo(1.0, 2);
+      // Both 'point' and 'other' are now along y-axis, so both should have distance ≈ 0
+      expect(results[0].distance).toBeCloseTo(0.0, 2);
+      expect(results[1].distance).toBeCloseTo(0.0, 2);
       expect(db.size).toBe(2);
     });
 
+    it("query respects maxDistance option", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("x-axis", [1, 0, 0, 0]);
+      db.set("y-axis", [0, 1, 0, 0]);
+      db.set("xy-axis", [1, 1, 0, 0]);
+
+      // Only return results with distance ≤ 0.5 from the x-axis query
+      const results = db.query([1, 0, 0, 0], { maxDistance: 0.5 });
+      // x-axis: distance ≈ 0, xy-axis: distance ≈ 0.29
+      // y-axis: distance ≈ 1 (excluded)
+      expect(results.length).toBe(2);
+      expect(results[0].key).toBe("x-axis");
+      expect(results[1].key).toBe("xy-axis");
+    });
+
+    it("query maxDistance works with iterable mode", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("x-axis", [1, 0, 0, 0]);
+      db.set("y-axis", [0, 1, 0, 0]);
+      db.set("xy-axis", [1, 1, 0, 0]);
+
+      const results = [...db.query([1, 0, 0, 0], { maxDistance: 0.5, iterable: true })];
+      expect(results.length).toBe(2);
+      expect(results[0].key).toBe("x-axis");
+      expect(results[1].key).toBe("xy-axis");
+    });
+
+    it("query topK defaults to Infinity (returns all results)", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      for (let i = 0; i < 10; i++) {
+        const vec = [0, 0, 0, 0];
+        vec[i % 4] = 1;
+        db.set(`v${i}`, vec);
+      }
+
+      // Without topK, all 10 results should be returned
+      const results = db.query([1, 0, 0, 0]);
+      expect(results.length).toBe(10);
+    });
+
     // --- flush and persistence ---
     it("flush persists data and reopen loads it", async () => {
       const db1 = await VectorDB.open({

package/src/lib/index.ts

@@ -9,12 +9,5 @@ export { VectorCapacityExceededError } from "./errors";
 export type { ResultItem } from "./result-set";
 export { InMemoryStorageProvider, OPFSStorageProvider } from "./storage";
 export type { StorageProvider } from "./storage";
-export type {
-  IterableQueryOptions,
-  OpenOptions,
-  OpenOptionsInternal,
-  QueryOptions,
-  SetOptions,
-  VectorInput,
-} from "./types";
+export type { OpenOptions, OpenOptionsInternal, QueryOptions, SetOptions, VectorInput } from "./types";
 export { VectorDB as DB } from "./vector-db";

package/src/lib/result-set.ts

@@ -6,20 +6,29 @@
  *   1. topKResults  — eagerly materializes a ResultItem[] (default query path)
  *   2. iterableResults — returns a lazy Iterable<ResultItem> where keys are
  *      resolved only as each item is consumed (for pagination / streaming)
+ *
+ * Distance is defined as `1 - dotProduct`. For normalized vectors (the default),
+ * this equals cosine distance, ranging from 0 (identical) to 2 (opposite).
  */
 
 export interface ResultItem {
   key: string;
-  score: number;
+  distance: number;
 }
 
 export type KeyResolver = (index: number) => string;
 
 /**
- * Sort scores descending and return the top K results as a plain array.
+ * Sort by ascending distance and return the top K results as a plain array.
  * All keys are resolved eagerly.
+ * If maxDistance is provided, results with distance > maxDistance are excluded.
  */
-export function topKResults(scores: Float32Array, resolveKey: KeyResolver, topK: number): ResultItem[] {
+export function topKResults(
+  scores: Float32Array,
+  resolveKey: KeyResolver,
+  topK: number,
+  maxDistance?: number,
+): ResultItem[] {
   const n = scores.length;
   if (n === 0) return [];
 
@@ -28,23 +37,32 @@ export function topKResults(scores: Float32Array, resolveKey: KeyResolver, topK:
   indices.sort((a, b) => scores[b] - scores[a]);
 
   const k = Math.min(topK, n);
-  const results: ResultItem[] = new Array(k);
+  const results: ResultItem[] = [];
   for (let i = 0; i < k; i++) {
     const idx = indices[i];
-    results[i] = { key: resolveKey(idx), score: scores[idx] };
+    const distance = 1 - scores[idx];
+    if (maxDistance !== undefined && distance > maxDistance) break;
+    results.push({ key: resolveKey(idx), distance });
   }
   return results;
 }
 
 /**
- * Sort scores descending and return a lazy iterable over the top K results.
+ * Sort by ascending distance and return a lazy iterable over the top K results.
  * Keys are resolved only when each item is consumed, saving allocations
  * when the caller iterates partially (e.g., pagination).
  *
+ * If maxDistance is provided, iteration stops when distance > maxDistance.
+ *
  * The returned iterable is re-iterable — each call to [Symbol.iterator]()
  * produces a fresh cursor over the same pre-sorted data.
  */
-export function iterableResults(scores: Float32Array, resolveKey: KeyResolver, topK: number): Iterable<ResultItem> {
+export function iterableResults(
+  scores: Float32Array,
+  resolveKey: KeyResolver,
+  topK: number,
+  maxDistance?: number,
+): Iterable<ResultItem> {
   const n = scores.length;
   if (n === 0) return [];
 
@@ -61,9 +79,11 @@ export function iterableResults(scores: Float32Array, resolveKey: KeyResolver, t
         next(): IteratorResult<ResultItem> {
           if (i >= k) return { done: true, value: undefined };
           const idx = indices[i++];
+          const distance = 1 - scores[idx];
+          if (maxDistance !== undefined && distance > maxDistance) return { done: true, value: undefined };
           return {
             done: false,
-            value: { key: resolveKey(idx), score: scores[idx] },
+            value: { key: resolveKey(idx), distance },
           };
         },
       };

package/src/lib/simd-binary.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED - Do not edit. Run: npx tsx scripts/compile-wat.ts
-const SIMD_WASM_BASE64 = "AGFzbQEAAAABDgJgAn9/AGAFf39/f38AAg8BA2VudgZtZW1vcnkCAAEDAwIAAQcaAglub3JtYWxpemUAAApzZWFyY2hfYWxsAAEKsgQCtQIFAX8BewN9AXsDf/0MAAAAAAAAAAAAAAAAAAAAACEDIAFBfHEhCEEAIQICQANAIAIgCE8NASAAIAJBAnRqIQogAyAK/QAEACAK/QAEAP3mAf3kASEDIAJBBGohAgwACwsgA/0fACAD/R8BkiAD/R8CIAP9HwOSkiEEIAghCQJAA0AgCSABTw0BIAAgCUECdGohCiAEIAoqAgAgCioCAJSSIQQgCUEBaiEJDAALCyAEkSEFIAVDAAAAAFsEQA8LQwAAgD8gBZUhBiAG/RMhB0EAIQICQANAIAIgCE8NASAAIAJBAnRqIQogCiAK/QAEACAH/eYB/QsEACACQQRqIQIMAAsLIAghCQJAA0AgCSABTw0BIAAgCUECdGohCiAKIAoqAgAgBpQ4AgAgCUEBaiEJDAALCwv4AQQCfwF7AX0GfyAEQXxxIQogBEECdCEOQQAhBQJAA0AgBSADTw0BIAEgBSAObGohCf0MAAAAAAAAAAAAAAAAAAAAACEHQQAhBgJAA0AgBiAKTw0BIAAgBkECdGohDCAJIAZBAnRqIQ0gByAM/QAEACAN/QAEAP3mAf3kASEHIAZBBGohBgwACwsgB/0fACAH/R8BkiAH/R8CIAf9HwOSkiEIIAohCwJAA0AgCyAETw0BIAAgC0ECdGohDCAJIAtBAnRqIQ0gCCAMKgIAIA0qAgCUkiEIIAtBAWohCwwACwsgAiAFQQJ0aiAIOAIAIAVBAWohBQwACwsL";
+const SIMD_WASM_BASE64 = "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";
 
 export function getSimdWasmBinary(): Uint8Array {
   const binaryString = atob(SIMD_WASM_BASE64);