usearch 2.21.4 → 2.25.1

package/javascript/README.md

@@ -48,7 +48,7 @@ Customize your index with additional configuration options:
 const index = new usearch.Index({
   dimensions: 128,
   metric: 'ip',
-  quantization: 'f32',
+  quantization: 'f32', // or 'bf16', 'f16', 'e5m2', 'e4m3', 'e3m2', 'e2m3', 'u8', 'i8', 'b1'
   connectivity: 10,
   expansion_add: 5,
   expansion_search: 3,

package/javascript/dist/cjs/usearch.d.ts

@@ -1,4 +1,4 @@
-type Vector = Float32Array | Float64Array | Int8Array;
+type Vector = Float32Array | Float64Array | Int8Array | Uint8Array;
 type Matrix = Vector[];
 type VectorOrMatrix = Vector | Matrix;
 /**
@@ -26,11 +26,16 @@ export declare enum MetricKind {
  */
 export declare enum ScalarKind {
     Unknown = "unknown",
-    F32 = "f32",
     F64 = "f64",
-    F16 = "f16",
+    F32 = "f32",
     BF16 = "bf16",
+    F16 = "f16",
+    E5M2 = "e5m2",
+    E4M3 = "e4m3",
+    E3M2 = "e3m2",
+    E2M3 = "e2m3",
     I8 = "i8",
+    U8 = "u8",
     B1 = "b1"
 }
 /**

package/javascript/dist/cjs/usearch.js

@@ -82,11 +82,16 @@ var MetricKind;
 var ScalarKind;
 (function (ScalarKind) {
     ScalarKind["Unknown"] = "unknown";
-    ScalarKind["F32"] = "f32";
     ScalarKind["F64"] = "f64";
-    ScalarKind["F16"] = "f16";
+    ScalarKind["F32"] = "f32";
     ScalarKind["BF16"] = "bf16";
+    ScalarKind["F16"] = "f16";
+    ScalarKind["E5M2"] = "e5m2";
+    ScalarKind["E4M3"] = "e4m3";
+    ScalarKind["E3M2"] = "e3m2";
+    ScalarKind["E2M3"] = "e2m3";
     ScalarKind["I8"] = "i8";
+    ScalarKind["U8"] = "u8";
     ScalarKind["B1"] = "b1";
 })(ScalarKind || (exports.ScalarKind = ScalarKind = {}));
 /**
@@ -174,7 +179,8 @@ function normalizeKeys(keys) {
 function isVector(vectors) {
     return (vectors instanceof Float32Array ||
         vectors instanceof Float64Array ||
-        vectors instanceof Int8Array);
+        vectors instanceof Int8Array ||
+        vectors instanceof Uint8Array);
 }
 function normalizeVectors(vectors, dimensions, targetType = Float32Array) {
     let flattenedVectors;
@@ -482,8 +488,10 @@ function exactSearch(dataset, queries, dimensions, count, metric, threads = 0) {
         targetType = Float64Array;
     else if (dataset instanceof Int8Array)
         targetType = Int8Array;
+    else if (dataset instanceof Uint8Array)
+        targetType = Uint8Array;
     else
-        targetType = Float32Array; // default to Float32Array if dataset is not Float64Array or Int8Array
+        targetType = Float32Array; // default to Float32Array if dataset is not Float64Array, Int8Array, or Uint8Array
     dataset = normalizeVectors(dataset, dimensions, targetType);
     queries = normalizeVectors(queries, dimensions, targetType);
     const countInDataset = dataset.length / dimensions;

package/javascript/dist/esm/usearch.d.ts

@@ -1,4 +1,4 @@
-type Vector = Float32Array | Float64Array | Int8Array;
+type Vector = Float32Array | Float64Array | Int8Array | Uint8Array;
 type Matrix = Vector[];
 type VectorOrMatrix = Vector | Matrix;
 /**
@@ -26,11 +26,16 @@ export declare enum MetricKind {
  */
 export declare enum ScalarKind {
     Unknown = "unknown",
-    F32 = "f32",
     F64 = "f64",
-    F16 = "f16",
+    F32 = "f32",
     BF16 = "bf16",
+    F16 = "f16",
+    E5M2 = "e5m2",
+    E4M3 = "e4m3",
+    E3M2 = "e3m2",
+    E2M3 = "e2m3",
     I8 = "i8",
+    U8 = "u8",
     B1 = "b1"
 }
 /**

package/javascript/dist/esm/usearch.js

@@ -30,11 +30,16 @@ export var MetricKind;
 export var ScalarKind;
 (function (ScalarKind) {
     ScalarKind["Unknown"] = "unknown";
-    ScalarKind["F32"] = "f32";
     ScalarKind["F64"] = "f64";
-    ScalarKind["F16"] = "f16";
+    ScalarKind["F32"] = "f32";
     ScalarKind["BF16"] = "bf16";
+    ScalarKind["F16"] = "f16";
+    ScalarKind["E5M2"] = "e5m2";
+    ScalarKind["E4M3"] = "e4m3";
+    ScalarKind["E3M2"] = "e3m2";
+    ScalarKind["E2M3"] = "e2m3";
     ScalarKind["I8"] = "i8";
+    ScalarKind["U8"] = "u8";
     ScalarKind["B1"] = "b1";
 })(ScalarKind || (ScalarKind = {}));
 /**
@@ -126,7 +131,8 @@ function normalizeKeys(keys) {
 function isVector(vectors) {
     return (vectors instanceof Float32Array ||
         vectors instanceof Float64Array ||
-        vectors instanceof Int8Array);
+        vectors instanceof Int8Array ||
+        vectors instanceof Uint8Array);
 }
 function normalizeVectors(vectors, dimensions, targetType = Float32Array) {
     let flattenedVectors;
@@ -432,8 +438,10 @@ export function exactSearch(dataset, queries, dimensions, count, metric, threads
         targetType = Float64Array;
     else if (dataset instanceof Int8Array)
         targetType = Int8Array;
+    else if (dataset instanceof Uint8Array)
+        targetType = Uint8Array;
     else
-        targetType = Float32Array; // default to Float32Array if dataset is not Float64Array or Int8Array
+        targetType = Float32Array; // default to Float32Array if dataset is not Float64Array, Int8Array, or Uint8Array
     dataset = normalizeVectors(dataset, dimensions, targetType);
     queries = normalizeVectors(queries, dimensions, targetType);
     const countInDataset = dataset.length / dimensions;

package/javascript/lib.cpp

@@ -432,7 +432,24 @@ Napi::Value exactSearch(Napi::CallbackInfo const& ctx) {
     return result_js;
 }
 
+Napi::Value version(Napi::CallbackInfo const& info) {
+    static char buf[32];
+    std::snprintf(buf, sizeof(buf), "%d.%d.%d", USEARCH_VERSION_MAJOR, USEARCH_VERSION_MINOR, USEARCH_VERSION_PATCH);
+    return Napi::String::New(info.Env(), buf);
+}
+
+Napi::Value hardwareAccelerationCompiled(Napi::CallbackInfo const& info) {
+    return Napi::String::New(info.Env(), unum::usearch::hardware_acceleration_compiled());
+}
+
+Napi::Value hardwareAccelerationAvailable(Napi::CallbackInfo const& info) {
+    return Napi::String::New(info.Env(), unum::usearch::hardware_acceleration_available());
+}
+
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
+    exports.Set("version", Napi::Function::New(env, version));
+    exports.Set("hardwareAccelerationCompiled", Napi::Function::New(env, hardwareAccelerationCompiled));
+    exports.Set("hardwareAccelerationAvailable", Napi::Function::New(env, hardwareAccelerationAvailable));
     exports.Set("exactSearch", Napi::Function::New(env, exactSearch));
     return CompiledIndex::Init(env, exports);
 }

package/javascript/usearch.test.js

@@ -1,23 +1,23 @@
-const nodeTest = require('node:test');
+const nodeTest = require("node:test");
 const realTest = nodeTest.test; // the original function
 
 function loggedTest(name, options, fn) {
   // The API has two call signatures:
   //   test(name, fn)
   //   test(name, options, fn)
-  if (typeof options === 'function') {
+  if (typeof options === "function") {
     fn = options;
     options = undefined;
   }
 
   // Wrap the body so we can log before / after
   const wrapped = async (t) => {
-    console.log('▶', name);
+    console.log("▶", name);
     try {
       await fn(t); // run the user’s test
-      console.log('✓', name);
+      console.log("✓", name);
     } catch (err) {
-      console.log('✖', name);
+      console.log("✖", name);
       throw err; // re-throw so the runner records the failure
     }
   };
@@ -30,43 +30,43 @@ function loggedTest(name, options, fn) {
 global.test = loggedTest;
 module.exports = loggedTest; // for completeness if this file is `require`d
 
-const assert = require('node:assert');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const usearch = require('./dist/cjs/usearch.js');
+const assert = require("node:assert");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const usearch = require("./dist/cjs/usearch.js");
 
 function assertAlmostEqual(actual, expected, tolerance = 1e-6) {
   const lowerBound = expected - tolerance;
   const upperBound = expected + tolerance;
   assert(
     actual >= lowerBound && actual <= upperBound,
-    `Expected ${actual} to be almost equal to ${expected}`
+    `Expected ${actual} to be almost equal to ${expected}`,
   );
 }
 
 const THREADS = 2;
 
-test('Single-entry operations', async (t) => {
-  await t.test('index info', () => {
-    const index = new usearch.Index(2, 'l2sq');
+test("Single-entry operations", async (t) => {
+  await t.test("index info", () => {
+    const index = new usearch.Index(2, "l2sq");
 
-    assert.equal(index.connectivity(), 16, 'connectivity should be 16');
-    assert.equal(index.dimensions(), 2, 'dimensions should be 2');
-    assert.equal(index.size(), 0, 'initial size should be 0');
+    assert.equal(index.connectivity(), 16, "connectivity should be 16");
+    assert.equal(index.dimensions(), 2, "dimensions should be 2");
+    assert.equal(index.size(), 0, "initial size should be 0");
   });
 
-  await t.test('add', () => {
-    const index = new usearch.Index(2, 'l2sq');
+  await t.test("add", () => {
+    const index = new usearch.Index(2, "l2sq");
 
     index.add(15n, new Float32Array([10, 20]));
     index.add(16n, new Float32Array([10, 25]));
 
-    assert.equal(index.size(), 2, 'size after adding elements should be 2');
+    assert.equal(index.size(), 2, "size after adding elements should be 2");
     assert.equal(
       index.contains(15),
       true,
-      'entry must be present after insertion'
+      "entry must be present after insertion",
     );
 
     const results = index.search(new Float32Array([13, 14]), 2);
@@ -74,17 +74,17 @@ test('Single-entry operations', async (t) => {
     assert.deepEqual(
       results.keys,
       new BigUint64Array([15n, 16n]),
-      'keys should be 15 and 16'
+      "keys should be 15 and 16",
     );
     assert.deepEqual(
       results.distances,
       new Float32Array([45, 130]),
-      'distances should be 45 and 130'
+      "distances should be 45 and 130",
     );
   });
 
-  await t.test('remove', () => {
-    const index = new usearch.Index(2, 'l2sq');
+  await t.test("remove", () => {
+    const index = new usearch.Index(2, "l2sq");
 
     index.add(15n, new Float32Array([10, 20]));
     index.add(16n, new Float32Array([10, 25]));
@@ -93,11 +93,11 @@ test('Single-entry operations', async (t) => {
 
     assert.equal(index.remove(15n), 1);
 
-    assert.equal(index.size(), 3, 'size after removing elements should be 3');
+    assert.equal(index.size(), 3, "size after removing elements should be 3");
     assert.equal(
       index.contains(15),
       false,
-      'entry must be absent after insertion'
+      "entry must be absent after insertion",
     );
 
     const results = index.search(new Float32Array([13, 14]), 2);
@@ -105,37 +105,37 @@ test('Single-entry operations', async (t) => {
     assert.deepEqual(
       results.keys,
       new BigUint64Array([16n, 25n]),
-      'keys should not include 15'
+      "keys should not include 15",
     );
   });
 });
 
-test('Batch operations', async (t) => {
-  await t.test('add', () => {
-    const indexBatch = new usearch.Index(2, 'l2sq');
+test("Batch operations", async (t) => {
+  await t.test("add", () => {
+    const indexBatch = new usearch.Index(2, "l2sq");
 
     const keys = [15n, 16n];
     const vectors = [new Float32Array([10, 20]), new Float32Array([10, 25])];
 
     indexBatch.add(keys, vectors);
-    assert.equal(indexBatch.size(), 2, 'size after adding batch should be 2');
+    assert.equal(indexBatch.size(), 2, "size after adding batch should be 2");
 
     const results = indexBatch.search(new Float32Array([13, 14]), 2);
 
     assert.deepEqual(
       results.keys,
       new BigUint64Array([15n, 16n]),
-      'keys should be 15 and 16'
+      "keys should be 15 and 16",
     );
     assert.deepEqual(
       results.distances,
       new Float32Array([45, 130]),
-      'distances should be 45 and 130'
+      "distances should be 45 and 130",
     );
   });
 
-  await t.test('remove', () => {
-    const indexBatch = new usearch.Index(2, 'l2sq');
+  await t.test("remove", () => {
+    const indexBatch = new usearch.Index(2, "l2sq");
 
     const keys = [15n, 16n, 25n, 26n];
     const vectors = [
@@ -147,53 +147,58 @@ test('Batch operations', async (t) => {
     indexBatch.add(keys, vectors);
 
     assert.deepEqual(indexBatch.remove([15n, 25n]), [1, 1]);
-    assert.equal(indexBatch.size(), 2, 'size after removing batch should be 2');
+    assert.equal(indexBatch.size(), 2, "size after removing batch should be 2");
 
     const results = indexBatch.search(new Float32Array([13, 14]), 2);
 
     assert.deepEqual(
       results.keys,
       new BigUint64Array([16n, 26n]),
-      'keys should not include 15 and 25'
+      "keys should not include 15 and 25",
     );
   });
 
-  await t.test('search', () => {
-    const indexBatch = new usearch.Index(3, 'l2sq');
+  await t.test("search", () => {
+    const indexBatch = new usearch.Index(3, "l2sq");
 
     const keys = [15n, 16n];
-    const vectors = [new Float32Array([10, 20, 30]), new Float32Array([10, 25, 35])];
+    const vectors = [
+      new Float32Array([10, 20, 30]),
+      new Float32Array([10, 25, 35]),
+    ];
 
     indexBatch.add(keys, vectors);
-    assert.equal(indexBatch.size(), 2, 'size after adding batch should be 2');
+    assert.equal(indexBatch.size(), 2, "size after adding batch should be 2");
+
+    const results = indexBatch.search(
+      [new Float32Array([13, 14, 15]), new Float32Array([13, 14, 15])],
+      2,
+    );
 
-    const results = indexBatch.search([new Float32Array([13, 14, 15]), new Float32Array([13, 14, 15])], 2);
-    
-    assert.equal(results.k, 2, 'k should be 2');
+    assert.equal(results.k, 2, "k should be 2");
 
     assert.deepEqual(
       results.counts,
-      new BigUint64Array([ 2n, 2n ]) ,
-      'counts should be 2 for both keys'
+      new BigUint64Array([2n, 2n]),
+      "counts should be 2 for both keys",
     );
 
     assert.deepEqual(
       results.keys,
       new BigUint64Array([15n, 16n, 15n, 16n]),
-      'keys should be 15 and 16'
+      "keys should be 15 and 16",
     );
     assert.deepEqual(
       results.distances,
-      new Float32Array( [ 270, 530, 270, 530 ]),
-      'distances should be 270 and 530'
+      new Float32Array([270, 530, 270, 530]),
+      "distances should be 270 and 530",
     );
   });
-
 });
 
-test('Expected results', () => {
+test("Expected results", () => {
   const index = new usearch.Index({
-    metric: 'l2sq',
+    metric: "l2sq",
     connectivity: 16,
     dimensions: 3,
   });
@@ -205,9 +210,9 @@ test('Expected results', () => {
   assertAlmostEqual(results.distances[0], new Float32Array([0]));
 });
 
-test('Multithread search returns same results', () => {
+test("Multithread search returns same results", () => {
   const index = new usearch.Index({
-    metric: 'l2sq',
+    metric: "l2sq",
     connectivity: 16,
     dimensions: 3,
   });
@@ -218,14 +223,14 @@ test('Multithread search returns same results', () => {
   const results_2 = index.search(
     new Float32Array([0.2, 0.6, 0.4]),
     10,
-    THREADS
+    THREADS,
   );
 
   assert.deepEqual(results_1.keys, results_2.keys);
   assertAlmostEqual(results_1.distances, results_2.distances);
 });
 
-test('Exact search', async (t) => {
+test("Exact search", async (t) => {
   const dataset = [
     new Float32Array([0.2, 0.6, 0.4]),
     new Float32Array([0.6, 0.6, 0.4]),
@@ -233,16 +238,16 @@ test('Exact search', async (t) => {
   const queries = new Float32Array([0.2, 0.6, 0.4]);
   const dimensions = 3;
   const count = 2;
-  const metric = 'l2sq';
+  const metric = "l2sq";
 
-  await t.test('Single core search', () => {
+  await t.test("Single core search", () => {
     const result = usearch.exactSearch(
       dataset,
       queries,
       dimensions,
       count,
       metric,
-      1 // threads
+      1, // threads
     );
 
     assert.deepEqual(result.keys, new BigUint64Array([0n, 1n]));
@@ -250,14 +255,14 @@ test('Exact search', async (t) => {
     assertAlmostEqual(new Float32Array([0.16]), result.distances[1]);
   });
 
-  await t.test('Multithreaded search', () => {
+  await t.test("Multithreaded search", () => {
     const result = usearch.exactSearch(
       dataset,
       queries,
       dimensions,
       count,
       metric,
-      THREADS // threads
+      THREADS, // threads
     );
 
     assert.deepEqual(result.keys, new BigUint64Array([0n, 1n]));
@@ -266,30 +271,30 @@ test('Exact search', async (t) => {
   });
 });
 
-test('Expected count()', async (t) => {
+test("Expected count()", async (t) => {
   const index = new usearch.Index({
-    metric: 'l2sq',
+    metric: "l2sq",
     connectivity: 16,
     dimensions: 3,
   });
   index.add(
     [42n, 43n],
-    [new Float32Array([0.2, 0.6, 0.4]), new Float32Array([0.2, 0.6, 0.4])]
+    [new Float32Array([0.2, 0.6, 0.4]), new Float32Array([0.2, 0.6, 0.4])],
   );
 
-  await t.test('Argument is a number', () => {
+  await t.test("Argument is a number", () => {
     assert.equal(1, index.count(43n));
   });
-  await t.test('Argument is a number (does not exist)', () => {
+  await t.test("Argument is a number (does not exist)", () => {
     assert.equal(0, index.count(44n));
   });
-  await t.test('Argument is an array', () => {
+  await t.test("Argument is an array", () => {
     assert.deepEqual([1, 1, 0], index.count([42n, 43n, 44n]));
   });
 });
 
-test('Operations with invalid values', () => {
-  const indexBatch = new usearch.Index(2, 'l2sq');
+test("Operations with invalid values", () => {
+  const indexBatch = new usearch.Index(2, "l2sq");
 
   const keys = [NaN, 16n];
   const vectors = [new Float32Array([10, 30]), new Float32Array([1, 5])];
@@ -301,10 +306,10 @@ test('Operations with invalid values', () => {
   assert.throws(() => indexBatch.search(NaN, 2));
 });
 
-test('Invalid operations', async (t) => {
-  await t.test('Add the same keys', () => {
+test("Invalid operations", async (t) => {
+  await t.test("Add the same keys", () => {
     const index = new usearch.Index({
-      metric: 'l2sq',
+      metric: "l2sq",
       connectivity: 16,
       dimensions: 3,
     });
@@ -312,9 +317,9 @@ test('Invalid operations', async (t) => {
     assert.throws(() => index.add(42n, new Float32Array([0.2, 0.6, 0.4])));
   });
 
-  await t.test('Batch add containing the same key', () => {
+  await t.test("Batch add containing the same key", () => {
     const index = new usearch.Index({
-      metric: 'l2sq',
+      metric: "l2sq",
       connectivity: 16,
       dimensions: 3,
     });
@@ -326,18 +331,18 @@ test('Invalid operations', async (t) => {
           [0.1, 0.6, 0.4],
           [0.2, 0.6, 0.4],
           [0.3, 0.6, 0.4],
-        ]
+        ],
       );
     });
   });
 });
 
-test('Serialization', async (t) => {
-  const indexPath = path.join(os.tmpdir(), 'usearch.test.index');
+test("Serialization", async (t) => {
+  const indexPath = path.join(os.tmpdir(), "usearch.test.index");
 
   t.beforeEach(() => {
     const index = new usearch.Index({
-      metric: 'l2sq',
+      metric: "l2sq",
       connectivity: 16,
       dimensions: 3,
     });
@@ -349,9 +354,9 @@ test('Serialization', async (t) => {
     fs.unlinkSync(indexPath);
   });
 
-  await t.test('load', () => {
+  await t.test("load", () => {
     const index = new usearch.Index({
-      metric: 'l2sq',
+      metric: "l2sq",
       connectivity: 16,
       dimensions: 3,
     });
@@ -359,7 +364,7 @@ test('Serialization', async (t) => {
     const results = index.search(
       new Float32Array([0.2, 0.6, 0.4]),
       10,
-      THREADS
+      THREADS,
     );
 
     assert.equal(index.size(), 1);
@@ -371,11 +376,11 @@ test('Serialization', async (t) => {
   // The following error in afterEach().
   // `error: "EBUSY: resource busy or locked, unlink`
   await t.test(
-    'view: Read data',
-    { skip: process.platform === 'win32' },
+    "view: Read data",
+    { skip: process.platform === "win32" },
     () => {
       const index = new usearch.Index({
-        metric: 'l2sq',
+        metric: "l2sq",
         connectivity: 16,
         dimensions: 3,
       });
@@ -385,15 +390,15 @@ test('Serialization', async (t) => {
       assert.equal(index.size(), 1);
       assert.deepEqual(results.keys, new BigUint64Array([42n]));
       assertAlmostEqual(results.distances[0], new Float32Array([0]));
-    }
+    },
   );
 
   await t.test(
-    'view: Invalid operations: add',
-    { skip: process.platform === 'win32' },
+    "view: Invalid operations: add",
+    { skip: process.platform === "win32" },
     () => {
       const index = new usearch.Index({
-        metric: 'l2sq',
+        metric: "l2sq",
         connectivity: 16,
         dimensions: 3,
       });
@@ -401,15 +406,15 @@ test('Serialization', async (t) => {
 
       // Can't add to an immutable index
       assert.throws(() => index.add(43n, new Float32Array([0.2, 0.6, 0.4])));
-    }
+    },
   );
 
   await t.test(
-    'view: Invalid operations: remove',
-    { skip: process.platform === 'win32' },
+    "view: Invalid operations: remove",
+    { skip: process.platform === "win32" },
     () => {
       const index = new usearch.Index({
-        metric: 'l2sq',
+        metric: "l2sq",
         connectivity: 16,
         dimensions: 3,
       });
@@ -417,6 +422,24 @@ test('Serialization', async (t) => {
 
       // Can't remove from an immutable index
       assert.throws(() => index.remove(42n));
-    }
+    },
   );
 });
+
+test("Mini-float quantization types", async (t) => {
+  for (const quantization of ["e5m2", "e4m3", "e3m2", "e2m3"]) {
+    await t.test(`add and search with ${quantization}`, () => {
+      const index = new usearch.Index({
+        metric: "cos",
+        dimensions: 64,
+        quantization: quantization,
+      });
+      const vector = new Float32Array(64);
+      for (let i = 0; i < 64; i++) vector[i] = i * 0.1;
+      index.add(1n, vector);
+
+      const results = index.search(vector, 1);
+      assert.equal(results.keys[0], 1n);
+    });
+  }
+});