eigen-db 4.4.0 → 5.0.0

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

@@ -248,7 +248,7 @@ describe("VectorDB", () => {
       expect(results[2].similarity).toBeCloseTo(0.0, 2);
     });
 
-    it("query respects topK option", async () => {
+    it("query respects limit option", async () => {
       const db = await VectorDB.open({
         dimensions: 4,
         storage,
@@ -259,7 +259,7 @@ describe("VectorDB", () => {
       db.set("b", [0, 1, 0, 0]);
       db.set("c", [0, 0, 1, 0]);
 
-      const results = db.query([1, 0, 0, 0], { topK: 2 });
+      const results = db.query([1, 0, 0, 0], { limit: 2 });
       expect(results.length).toBe(2);
     });
 
@@ -371,7 +371,7 @@ describe("VectorDB", () => {
       expect(results[1].key).toBe("xy-axis");
     });
 
-    it("query topK defaults to Infinity (returns all results)", async () => {
+    it("query limit defaults to Infinity (returns all results)", async () => {
       const db = await VectorDB.open({
         dimensions: 4,
         storage,
@@ -384,11 +384,195 @@ describe("VectorDB", () => {
         db.set(`v${i}`, vec);
       }
 
-      // Without topK, all 10 results should be returned
+      // Without limit, all 10 results should be returned
       const results = db.query([1, 0, 0, 0]);
       expect(results.length).toBe(10);
     });
 
+    it("query with order ascend returns least similar first", 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], { order: "ascend" });
+      expect(results.length).toBe(3);
+      // y-axis (similarity ≈ 0) should be first in ascending order
+      expect(results[0].key).toBe("y-axis");
+      expect(results[0].similarity).toBeCloseTo(0.0, 2);
+      // x-axis (similarity ≈ 1) should be last
+      expect(results[2].key).toBe("x-axis");
+      expect(results[2].similarity).toBeCloseTo(1.0, 2);
+    });
+
+    it("query with order ascend and limit returns bottomK", 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], { order: "ascend", limit: 1 });
+      expect(results.length).toBe(1);
+      expect(results[0].key).toBe("y-axis");
+    });
+
+    it("query respects maxSimilarity 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 similarity ≤ 0.8 from the x-axis query
+      const results = db.query([1, 0, 0, 0], { maxSimilarity: 0.8 });
+      // x-axis: similarity ≈ 1 (excluded), xy-axis: similarity ≈ 0.71, y-axis: similarity ≈ 0
+      expect(results.length).toBe(2);
+      expect(results[0].key).toBe("xy-axis");
+      expect(results[1].key).toBe("y-axis");
+    });
+
+    it("query with both minSimilarity and maxSimilarity", 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 0.5 ≤ similarity ≤ 0.8
+      const results = db.query([1, 0, 0, 0], { minSimilarity: 0.5, maxSimilarity: 0.8 });
+      // xy-axis: similarity ≈ 0.71 (included)
+      // x-axis ≈ 1.0 (excluded), y-axis ≈ 0.0 (excluded)
+      expect(results.length).toBe(1);
+      expect(results[0].key).toBe("xy-axis");
+    });
+
+    it("query maxSimilarity 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], { maxSimilarity: 0.8, iterable: true })];
+      expect(results.length).toBe(2);
+      expect(results[0].key).toBe("xy-axis");
+      expect(results[1].key).toBe("y-axis");
+    });
+
+    it("query order ascend 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], { order: "ascend", iterable: true })];
+      expect(results.length).toBe(3);
+      expect(results[0].key).toBe("y-axis");
+      expect(results[2].key).toBe("x-axis");
+    });
+
+    it("query supports full similarity range [-1, 1] with opposite vectors", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("same", [1, 0, 0, 0]); // similarity ≈ 1
+      db.set("ortho", [0, 1, 0, 0]); // similarity ≈ 0
+      db.set("opposite", [-1, 0, 0, 0]); // similarity ≈ -1
+
+      const results = db.query([1, 0, 0, 0]);
+      expect(results.length).toBe(3);
+      expect(results[0].key).toBe("same");
+      expect(results[0].similarity).toBeCloseTo(1.0, 2);
+      expect(results[1].key).toBe("ortho");
+      expect(results[1].similarity).toBeCloseTo(0.0, 2);
+      expect(results[2].key).toBe("opposite");
+      expect(results[2].similarity).toBeCloseTo(-1.0, 2);
+    });
+
+    it("query minSimilarity works with negative values", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("same", [1, 0, 0, 0]); // similarity ≈ 1
+      db.set("ortho", [0, 1, 0, 0]); // similarity ≈ 0
+      db.set("opposite", [-1, 0, 0, 0]); // similarity ≈ -1
+
+      // minSimilarity = -0.5 should include same and ortho, exclude opposite
+      const results = db.query([1, 0, 0, 0], { minSimilarity: -0.5 });
+      expect(results.length).toBe(2);
+      expect(results[0].key).toBe("same");
+      expect(results[1].key).toBe("ortho");
+    });
+
+    it("query maxSimilarity works with negative values", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("same", [1, 0, 0, 0]); // similarity ≈ 1
+      db.set("ortho", [0, 1, 0, 0]); // similarity ≈ 0
+      db.set("opposite", [-1, 0, 0, 0]); // similarity ≈ -1
+
+      // maxSimilarity = -0.5 should include only opposite
+      const results = db.query([1, 0, 0, 0], { maxSimilarity: -0.5 });
+      expect(results.length).toBe(1);
+      expect(results[0].key).toBe("opposite");
+    });
+
+    it("query ascending order with negative similarities", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("same", [1, 0, 0, 0]);
+      db.set("ortho", [0, 1, 0, 0]);
+      db.set("opposite", [-1, 0, 0, 0]);
+
+      const results = db.query([1, 0, 0, 0], { order: "ascend" });
+      expect(results.length).toBe(3);
+      expect(results[0].key).toBe("opposite");
+      expect(results[0].similarity).toBeCloseTo(-1.0, 2);
+      expect(results[2].key).toBe("same");
+      expect(results[2].similarity).toBeCloseTo(1.0, 2);
+    });
+
     // --- flush and persistence ---
     it("flush persists data and reopen loads it", async () => {
       const db1 = await VectorDB.open({

package/src/lib/result-set.ts

@@ -3,7 +3,7 @@
  *
  * Utility functions for sorting scores and producing query results.
  * Two modes:
- *   1. topKResults  — eagerly materializes a ResultItem[] (default query path)
+ *   1. queryResults  — 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)
  *
@@ -19,41 +19,65 @@ export interface ResultItem {
 
 export type KeyResolver = (index: number) => string;
 
+export interface ResultOptions {
+  limit: number;
+  order: "ascend" | "descend";
+  minSimilarity?: number;
+  maxSimilarity?: number;
+}
+
+/** Check whether a score falls within the [minSimilarity, maxSimilarity] range. */
+function inRange(similarity: number, minSimilarity?: number, maxSimilarity?: number): boolean {
+  if (minSimilarity !== undefined && similarity < minSimilarity) return false;
+  if (maxSimilarity !== undefined && similarity > maxSimilarity) return false;
+  return true;
+}
+
 /**
- * Sort by descending similarity and return the top K results as a plain array.
+ * Sort scores and return the top results as a plain array.
  * All keys are resolved eagerly.
- * If minSimilarity is provided, results with similarity < minSimilarity are excluded.
+ *
+ * `order` controls sort direction:
+ *   - "descend" (default) — highest similarity first
+ *   - "ascend" — lowest similarity first
+ *
+ * Results outside [minSimilarity, maxSimilarity] are excluded.
  */
-export function topKResults(
+export function queryResults(
   scores: Float32Array,
   resolveKey: KeyResolver,
-  topK: number,
-  minSimilarity?: number,
+  options: ResultOptions,
 ): ResultItem[] {
+  const { limit, order, minSimilarity, maxSimilarity } = options;
   const n = scores.length;
   if (n === 0) return [];
 
   const indices = new Uint32Array(n);
   for (let i = 0; i < n; i++) indices[i] = i;
-  indices.sort((a, b) => scores[b] - scores[a]);
 
-  const k = Math.min(topK, n);
+  if (order === "ascend") {
+    indices.sort((a, b) => scores[a] - scores[b]);
+  } else {
+    indices.sort((a, b) => scores[b] - scores[a]);
+  }
+
+  const k = Math.min(limit, n);
   const results: ResultItem[] = [];
-  for (let i = 0; i < k; i++) {
+  for (let i = 0; i < n && results.length < k; i++) {
     const idx = indices[i];
     const similarity = scores[idx];
-    if (minSimilarity !== undefined && similarity < minSimilarity) break;
+    if (!inRange(similarity, minSimilarity, maxSimilarity)) continue;
     results.push({ key: resolveKey(idx), similarity });
   }
   return results;
 }
 
 /**
- * Sort by descending similarity and return a lazy iterable over the top K results.
+ * Sort scores and return a lazy iterable over the results.
  * Keys are resolved only when each item is consumed, saving allocations
  * when the caller iterates partially (e.g., pagination).
  *
- * If minSimilarity is provided, iteration stops when similarity < minSimilarity.
+ * Results outside [minSimilarity, maxSimilarity] are skipped.
  *
  * The returned iterable is re-iterable — each call to [Symbol.iterator]()
  * produces a fresh cursor over the same pre-sorted data.
@@ -61,31 +85,38 @@ export function topKResults(
 export function iterableResults(
   scores: Float32Array,
   resolveKey: KeyResolver,
-  topK: number,
-  minSimilarity?: number,
+  options: ResultOptions,
 ): Iterable<ResultItem> {
+  const { limit, order, minSimilarity, maxSimilarity } = options;
   const n = scores.length;
   if (n === 0) return [];
 
   const indices = new Uint32Array(n);
   for (let i = 0; i < n; i++) indices[i] = i;
-  indices.sort((a, b) => scores[b] - scores[a]);
 
-  const k = Math.min(topK, n);
+  if (order === "ascend") {
+    indices.sort((a, b) => scores[a] - scores[b]);
+  } else {
+    indices.sort((a, b) => scores[b] - scores[a]);
+  }
 
   return {
     [Symbol.iterator](): Iterator<ResultItem> {
       let i = 0;
+      let emitted = 0;
       return {
         next(): IteratorResult<ResultItem> {
-          if (i >= k) return { done: true, value: undefined };
-          const idx = indices[i++];
-          const similarity = scores[idx];
-          if (minSimilarity !== undefined && similarity < minSimilarity) return { done: true, value: undefined };
-          return {
-            done: false,
-            value: { key: resolveKey(idx), similarity },
-          };
+          while (i < n && emitted < limit) {
+            const idx = indices[i++];
+            const similarity = scores[idx];
+            if (!inRange(similarity, minSimilarity, maxSimilarity)) continue;
+            emitted++;
+            return {
+              done: false,
+              value: { key: resolveKey(idx), similarity },
+            };
+          }
+          return { done: true, value: undefined };
         },
       };
     },

package/src/lib/types.ts

@@ -38,9 +38,13 @@ export interface SetOptions {
  */
 export interface QueryOptions {
   /** Maximum number of results to return. Defaults to Infinity (all results). */
-  topK?: number;
+  limit?: number;
+  /** Result ordering. "ascend" sorts by ascending similarity, "descend" sorts by descending similarity. Defaults to "descend". */
+  order?: "ascend" | "descend";
   /** Minimum similarity threshold (inclusive). Results with similarity < minSimilarity are excluded. */
   minSimilarity?: number;
+  /** Maximum similarity threshold (inclusive). Results with similarity > maxSimilarity are excluded. */
+  maxSimilarity?: number;
   /** Override normalization for this call. */
   normalize?: boolean;
   /** When true, returns an Iterable<ResultItem> instead of ResultItem[]. */

package/src/lib/vector-db.ts

@@ -17,7 +17,7 @@ import { VectorCapacityExceededError } from "./errors";
 import { decodeLexicon, encodeLexicon } from "./lexicon";
 import { MemoryManager } from "./memory-manager";
 import type { ResultItem } from "./result-set";
-import { iterableResults, topKResults } from "./result-set";
+import { iterableResults, queryResults } from "./result-set";
 import { getSimdWasmBinary } from "./simd-binary";
 import type { StorageProvider } from "./storage";
 import { InMemoryStorageProvider } from "./storage";
@@ -281,8 +281,10 @@ export class VectorDB {
   query(value: VectorInput, options?: QueryOptions): ResultItem[] | Iterable<ResultItem> {
     this.assertOpen();
 
-    const k = options?.topK ?? Infinity;
+    const limit = options?.limit ?? Infinity;
+    const order = options?.order ?? "descend";
     const minSimilarity = options?.minSimilarity;
+    const maxSimilarity = options?.maxSimilarity;
     const iterable = options && "iterable" in options && options.iterable;
 
     if (this.size === 0) {
@@ -343,10 +345,12 @@ export class VectorDB {
       return slotToKey[slotIndex];
     };
 
+    const resultOptions = { limit, order, minSimilarity, maxSimilarity } as const;
+
     if (iterable) {
-      return iterableResults(scores, resolveKey, k, minSimilarity);
+      return iterableResults(scores, resolveKey, resultOptions);
     }
-    return topKResults(scores, resolveKey, k, minSimilarity);
+    return queryResults(scores, resolveKey, resultOptions);
   }
 
   /**