eigen-db 4.3.0 → 5.0.0

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

@@ -94,6 +94,16 @@ describe("VectorDB", () => {
       expect(db.size).toBe(0);
     });
 
+    it("exposes dimensions property", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      expect(db.dimensions).toBe(4);
+    });
+
     // --- set and get ---
     it("stores and retrieves a vector by key", async () => {
       const db = await VectorDB.open({
@@ -238,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,
@@ -249,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);
     });
 
@@ -361,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,
@@ -374,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({
@@ -838,6 +1032,284 @@ describe("VectorDB", () => {
       expect(db2.get("gamma")![2]).toBeCloseTo(1);
     });
 
+    // --- has ---
+    it("has returns true for existing key", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("a", [1, 0, 0, 0]);
+      expect(db.has("a")).toBe(true);
+    });
+
+    it("has returns false for non-existent key", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      expect(db.has("nonexistent")).toBe(false);
+    });
+
+    it("has throws on closed database", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      await db.close();
+      expect(() => db.has("a")).toThrow("closed");
+    });
+
+    // --- delete ---
+    it("delete removes an existing entry and returns true", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("a", [1, 0, 0, 0]);
+      db.set("b", [0, 1, 0, 0]);
+      expect(db.size).toBe(2);
+
+      const result = db.delete("a");
+      expect(result).toBe(true);
+      expect(db.size).toBe(1);
+      expect(db.get("a")).toBeUndefined();
+      expect(db.has("a")).toBe(false);
+      expect(db.get("b")).toBeDefined();
+    });
+
+    it("delete returns false for non-existent key", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      expect(db.delete("nonexistent")).toBe(false);
+    });
+
+    it("delete last entry leaves empty database", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("only", [1, 2, 3, 4]);
+      db.delete("only");
+      expect(db.size).toBe(0);
+      expect(db.get("only")).toBeUndefined();
+    });
+
+    it("delete preserves remaining entries and query works", 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("z-axis", [0, 0, 1, 0]);
+
+      db.delete("y-axis");
+      expect(db.size).toBe(2);
+
+      const results = db.query([1, 0, 0, 0]);
+      expect(results.length).toBe(2);
+      expect(results[0].key).toBe("x-axis");
+      expect(results.find((r) => r.key === "y-axis")).toBeUndefined();
+    });
+
+    it("delete then set reuses the database correctly", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("a", [1, 0, 0, 0]);
+      db.set("b", [0, 1, 0, 0]);
+      db.delete("a");
+
+      db.set("c", [0, 0, 1, 0]);
+      expect(db.size).toBe(2);
+      expect(db.get("a")).toBeUndefined();
+      expect(db.get("b")![1]).toBeCloseTo(1);
+      expect(db.get("c")![2]).toBeCloseTo(1);
+    });
+
+    it("delete persists correctly after flush", async () => {
+      const db1 = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db1.set("a", [1, 0, 0, 0]);
+      db1.set("b", [0, 1, 0, 0]);
+      db1.delete("a");
+      await db1.flush();
+
+      const db2 = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      expect(db2.size).toBe(1);
+      expect(db2.get("a")).toBeUndefined();
+      expect(db2.get("b")![1]).toBeCloseTo(1);
+    });
+
+    it("delete throws on closed database", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      await db.close();
+      expect(() => db.delete("a")).toThrow("closed");
+    });
+
+    // --- keys ---
+    it("keys returns an iterable of all keys", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("a", [1, 0, 0, 0]);
+      db.set("b", [0, 1, 0, 0]);
+      db.set("c", [0, 0, 1, 0]);
+
+      const keys = [...db.keys()];
+      expect(keys).toHaveLength(3);
+      expect(keys).toContain("a");
+      expect(keys).toContain("b");
+      expect(keys).toContain("c");
+    });
+
+    it("keys returns empty iterable for empty database", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      expect([...db.keys()]).toEqual([]);
+    });
+
+    it("keys throws on closed database", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      await db.close();
+      expect(() => db.keys()).toThrow("closed");
+    });
+
+    // --- entries ---
+    it("entries returns an iterable of [key, value] pairs", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("a", [1, 0, 0, 0]);
+      db.set("b", [0, 1, 0, 0]);
+
+      const entries = [...db.entries()];
+      expect(entries).toHaveLength(2);
+
+      const aEntry = entries.find(([key]) => key === "a");
+      expect(aEntry).toBeDefined();
+      expect(aEntry![1][0]).toBeCloseTo(1);
+
+      const bEntry = entries.find(([key]) => key === "b");
+      expect(bEntry).toBeDefined();
+      expect(bEntry![1][1]).toBeCloseTo(1);
+    });
+
+    it("entries returns empty iterable for empty database", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      expect([...db.entries()]).toEqual([]);
+    });
+
+    it("entries throws on closed database", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        storage,
+        wasmBinary,
+      });
+
+      await db.close();
+      expect(() => db.entries()).toThrow("closed");
+    });
+
+    // --- Symbol.iterator ---
+    it("supports spread operator via Symbol.iterator", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("a", [1, 0, 0, 0]);
+      db.set("b", [0, 1, 0, 0]);
+
+      const spread = [...db];
+      expect(spread).toHaveLength(2);
+
+      // Same as entries()
+      const entries = [...db.entries()];
+      expect(spread).toEqual(entries);
+    });
+
+    it("supports for-of iteration", async () => {
+      const db = await VectorDB.open({
+        dimensions: 4,
+        normalize: false,
+        storage,
+        wasmBinary,
+      });
+
+      db.set("a", [1, 0, 0, 0]);
+      db.set("b", [0, 1, 0, 0]);
+
+      const collected: [string, number[]][] = [];
+      for (const entry of db) {
+        collected.push(entry);
+      }
+      expect(collected).toHaveLength(2);
+    });
+
     it("import works correctly with single-byte stream chunks", async () => {
       const db1 = await VectorDB.open({
         dimensions: 4,

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[]. */