Add test suite, update CI to run tests, upgrade action versions

- Add Vitest with 5 integration tests: search ranking, memory stats,
  compression ratio comparison, vector removal, exact vs quantized overlap
- CI now runs tests before build
- Upgrade actions/checkout and actions/setup-node to v6

Author: danilodevhub

.github/workflows/ci.yml

@@ -19,14 +19,16 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version-file: ".nvmrc"
           cache: npm
       - run: npm ci
       - run: npx tsc -b
         working-directory: examples/semantic-search
+      - run: npx vitest run
+        working-directory: examples/semantic-search
       - run: npx vite build
         working-directory: examples/semantic-search
         env:

examples/semantic-search/package.json

@@ -7,7 +7,9 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@huggingface/transformers": "^4.0.1",
@@ -20,6 +22,7 @@
     "@types/react-dom": "^19.1.2",
     "@vitejs/plugin-react": "^4.5.2",
     "typescript": "^6.0.2",
-    "vite": "^6.3.5"
+    "vite": "^6.3.5",
+    "vitest": "^4.1.4"
   }
 }

examples/semantic-search/tests/vector-index.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { VectorIndex } from "turboquant-js";
+
+describe("VectorIndex integration", () => {
+  const DIMENSION = 16;
+
+  function randomVector(seed: number): number[] {
+    const v: number[] = [];
+    let s = seed;
+    for (let i = 0; i < DIMENSION; i++) {
+      s = (s * 1103515245 + 12345) & 0x7fffffff;
+      v.push((s / 0x7fffffff) * 2 - 1);
+    }
+    // Normalize
+    const norm = Math.sqrt(v.reduce((sum, x) => sum + x * x, 0));
+    return v.map((x) => x / norm);
+  }
+
+  it("should add, search, and return ranked results", () => {
+    const index = new VectorIndex({ dimension: DIMENSION, bits: 3, metric: "cosine" });
+
+    const vectors = Array.from({ length: 20 }, (_, i) => ({
+      id: `doc-${i}`,
+      vector: randomVector(i + 1),
+    }));
+
+    index.addBatch(vectors);
+    expect(index.size).toBe(20);
+
+    const results = index.search(randomVector(1), 5);
+    expect(results).toHaveLength(5);
+    expect(results[0].id).toBe("doc-0"); // Self-query should rank first
+    expect(results[0].score).toBeGreaterThan(0.5);
+
+    // Scores should be in descending order
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i].score).toBeLessThanOrEqual(results[i - 1].score);
+    }
+  });
+
+  it("should report memory usage with compression", () => {
+    const index = new VectorIndex({ dimension: DIMENSION, bits: 3, metric: "cosine" });
+    for (let i = 0; i < 10; i++) {
+      index.add(i, randomVector(i));
+    }
+
+    const mem = index.memoryUsage;
+    expect(mem.compressionRatio).toBeGreaterThan(1);
+    expect(mem.totalBits).toBeGreaterThan(0);
+    expect(mem.bitsPerVector).toBeGreaterThan(0);
+  });
+
+  it("should produce different compression ratios at different bit-widths", () => {
+    const vectors = Array.from({ length: 10 }, (_, i) => randomVector(i));
+
+    const ratios: number[] = [];
+    for (const bits of [2, 3, 4]) {
+      const index = new VectorIndex({ dimension: DIMENSION, bits, metric: "cosine" });
+      vectors.forEach((v, i) => index.add(i, v));
+      ratios.push(index.memoryUsage.compressionRatio);
+    }
+
+    // Higher bits = lower compression ratio
+    expect(ratios[0]).toBeGreaterThan(ratios[1]);
+    expect(ratios[1]).toBeGreaterThan(ratios[2]);
+  });
+
+  it("should remove vectors by id", () => {
+    const index = new VectorIndex({ dimension: DIMENSION, bits: 3, metric: "cosine" });
+    index.add("a", randomVector(1));
+    index.add("b", randomVector(2));
+    index.add("c", randomVector(3));
+    expect(index.size).toBe(3);
+
+    const removed = index.remove("b");
+    expect(removed).toBe(true);
+    expect(index.size).toBe(2);
+
+    const notFound = index.remove("nonexistent");
+    expect(notFound).toBe(false);
+  });
+});
+
+describe("Exact vs quantized search comparison", () => {
+  const DIMENSION = 32;
+  const NUM_VECTORS = 50;
+
+  function randomVector(seed: number): number[] {
+    const v: number[] = [];
+    let s = seed;
+    for (let i = 0; i < DIMENSION; i++) {
+      s = (s * 1103515245 + 12345) & 0x7fffffff;
+      v.push((s / 0x7fffffff) * 2 - 1);
+    }
+    const norm = Math.sqrt(v.reduce((sum, x) => sum + x * x, 0));
+    return v.map((x) => x / norm);
+  }
+
+  function exactCosineSearch(query: number[], vectors: number[][], topK: number) {
+    const scores = vectors.map((v, i) => {
+      let dot = 0;
+      for (let j = 0; j < DIMENSION; j++) dot += query[j] * v[j];
+      return { id: i, score: dot };
+    });
+    scores.sort((a, b) => b.score - a.score);
+    return scores.slice(0, topK);
+  }
+
+  it("should have meaningful overlap between exact and quantized results", () => {
+    const index = new VectorIndex({ dimension: DIMENSION, bits: 3, metric: "cosine" });
+    const vectors = Array.from({ length: NUM_VECTORS }, (_, i) => randomVector(i + 100));
+    vectors.forEach((v, i) => index.add(i, v));
+
+    const query = randomVector(999);
+    const quantizedResults = index.search(query, 10);
+    const exactResults = exactCosineSearch(query, vectors, 10);
+
+    const exactIds = new Set(exactResults.map((r) => r.id));
+    const overlap = quantizedResults.filter((r) => exactIds.has(r.id as number)).length;
+
+    // At 3-bit quantization, expect at least 30% overlap in top-10
+    expect(overlap).toBeGreaterThanOrEqual(3);
+  });
+});