usearch 2.10.3 → 2.11.0

package/simsimd/javascript/lib.c

@@ -0,0 +1,107 @@
+/**
+ *  @file       lib.c
+ *  @brief      JavaScript bindings for SimSIMD.
+ *  @author     Ash Vardanian
+ *  @date       October 18, 2023
+ *
+ *  @copyright  Copyright (c) 2023
+ *  @see        NodeJS docs: https://nodejs.org/api/n-api.html
+ */
+
+#include <node_api.h>        // `napi_*` functions
+#include <simsimd/simsimd.h> // `simsimd_*` functions
+
+/// @brief  Global variable that caches the CPU capabilities, and is computed just onc, when the module is loaded.
+simsimd_capability_t static_capabilities = simsimd_cap_serial_k;
+
+napi_value runAPI(napi_env env, napi_callback_info info, simsimd_metric_kind_t metric_kind) {
+    size_t argc = 2;
+    napi_value args[2];
+    napi_status status;
+
+    // Get callback info and ensure the argument count is correct
+    status = napi_get_cb_info(env, info, &argc, args, NULL, NULL);
+    if (status != napi_ok || argc != 2) {
+        napi_throw_error(env, NULL, "Wrong number of arguments");
+        return NULL;
+    }
+
+    // Obtain the typed arrays from the arguments
+    void *data_a, *data_b;
+    size_t length_a, length_b;
+    napi_typedarray_type type_a, type_b;
+    napi_status status_a, status_b;
+    status_a = napi_get_typedarray_info(env, args[0], &type_a, &length_a, &data_a, NULL, NULL);
+    status_b = napi_get_typedarray_info(env, args[1], &type_b, &length_b, &data_b, NULL, NULL);
+    if (status_a != napi_ok || status_b != napi_ok || type_a != type_b || length_a != length_b) {
+        napi_throw_error(env, NULL, "Both arguments must be typed arrays of matching types and dimensionality");
+        return NULL;
+    }
+    if (type_a != napi_float64_array && type_a != napi_float32_array && //
+        type_a != napi_int8_array && type_a != napi_uint8_array) {
+        napi_throw_error(env, NULL,
+                         "Only `float64`, `float32`, `int8` and `uint8` arrays are supported in JavaScript bindings");
+        return NULL;
+    }
+
+    simsimd_datatype_t datatype = simsimd_datatype_unknown_k;
+    switch (type_a) {
+    case napi_float64_array: datatype = simsimd_datatype_f64_k; break;
+    case napi_float32_array: datatype = simsimd_datatype_f32_k; break;
+    case napi_int8_array: datatype = simsimd_datatype_i8_k; break;
+    case napi_uint8_array: datatype = simsimd_datatype_b8_k; break;
+    default: break;
+    }
+
+    simsimd_metric_punned_t metric = NULL;
+    simsimd_capability_t capability = simsimd_cap_serial_k;
+    simsimd_find_metric_punned(metric_kind, datatype, static_capabilities, simsimd_cap_any_k, &metric, &capability);
+    if (metric == NULL) {
+        napi_throw_error(env, NULL, "Unsupported datatype for given metric");
+        return NULL;
+    }
+
+    simsimd_distance_t result;
+    metric(data_a, data_b, length_a, &result);
+
+    // Convert the result to a JavaScript number
+    napi_value js_result;
+    status = napi_create_double(env, result, &js_result);
+    if (status != napi_ok)
+        return NULL;
+
+    return js_result;
+}
+
+napi_value ipAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_dot_k); }
+napi_value cosAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_cosine_k); }
+napi_value l2sqAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_sqeuclidean_k); }
+napi_value klAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_kl_k); }
+napi_value jsAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_js_k); }
+napi_value hammingAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_hamming_k); }
+napi_value jaccardAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_jaccard_k); }
+
+napi_value Init(napi_env env, napi_value exports) {
+
+    // Define an array of property descriptors
+    napi_property_descriptor dotDesc = {"dot", 0, ipAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor innerDesc = {"inner", 0, ipAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor sqeuclideanDesc = {"sqeuclidean", 0, l2sqAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor cosineDesc = {"cosine", 0, cosAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor hammingDesc = {"hamming", 0, hammingAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor jaccardDesc = {"jaccard", 0, jaccardAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor klDesc = {"kullbackleibler", 0, klAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor jsDesc = {"jensenshannon", 0, jsAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor properties[] = {
+        dotDesc, innerDesc, sqeuclideanDesc, cosineDesc, hammingDesc, jaccardDesc, klDesc, jsDesc,
+    };
+
+    // Define the properties on the `exports` object
+    size_t propertyCount = sizeof(properties) / sizeof(properties[0]);
+    napi_define_properties(env, exports, propertyCount, properties);
+
+    static_capabilities = simsimd_capabilities();
+    return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

package/simsimd/javascript/node-gyp-build.d.ts

@@ -0,0 +1 @@
+declare module "node-gyp-build";

package/simsimd/javascript/simsimd.ts

@@ -0,0 +1,135 @@
+import build from "node-gyp-build";
+import * as path from "node:path";
+import { existsSync } from "node:fs";
+import { getFileName, getRoot } from "bindings";
+import * as fallback from "./fallback.js";
+
+let compiled: any;
+
+try {
+  let builddir = getBuildDir(getDirName());
+  compiled = build(builddir);
+} catch (e) {
+  compiled = fallback;
+  console.warn(
+    "It seems like your environment does't support the native simsimd module, so we are providing a JS fallback."
+  );
+}
+
+/**
+ * @brief Computes the squared Euclidean distance between two vectors.
+ * @param {Float64Array|Float32Array|Int8Array} a - The first vector.
+ * @param {Float64Array|Float32Array|Int8Array} b - The second vector.
+ * @returns {number} The squared Euclidean distance between vectors a and b.
+ */
+export const sqeuclidean = (
+  a: Float64Array | Float32Array | Int8Array,
+  b: Float64Array | Float32Array | Int8Array
+): number => {
+  return compiled.sqeuclidean(a, b);
+};
+
+/**
+ * @brief Computes the cosine distance between two vectors.
+ * @param {Float64Array|Float32Array|Int8Array} a - The first vector.
+ * @param {Float64Array|Float32Array|Int8Array} b - The second vector.
+ * @returns {number} The cosine distance between vectors a and b.
+ */
+export const cosine = (
+  a: Float64Array | Float32Array | Int8Array,
+  b: Float64Array | Float32Array | Int8Array
+): number => {
+  return compiled.cosine(a, b);
+};
+
+/**
+ * @brief Computes the inner product of two vectors (same as dot product).
+ * @param {Float64Array|Float32Array} a - The first vector.
+ * @param {Float64Array|Float32Array} b - The second vector.
+ * @returns {number} The inner product of vectors a and b.
+ */
+export const inner = (a: Float64Array | Float32Array, b: Float64Array | Float32Array): number => {
+  return compiled.inner(a, b);
+};
+
+/**
+ * @brief Computes the dot product of two vectors (same as inner product).
+ * @param {Float64Array|Float32Array} a - The first vector.
+ * @param {Float64Array|Float32Array} b - The second vector.
+ * @returns {number} The dot product of vectors a and b.
+ */
+export const dot = (a: Float64Array | Float32Array, b: Float64Array | Float32Array): number => {
+  return compiled.dot(a, b);
+};
+
+/**
+ * @brief Computes the bitwise Hamming distance between two vectors.
+ * @param {Uint8Array} a - The first vector.
+ * @param {Uint8Array} b - The second vector.
+ * @returns {number} The Hamming distance between vectors a and b.
+ */
+export const hamming = (a: Uint8Array, b: Uint8Array): number => {
+  return compiled.hamming(a, b);
+};
+
+/**
+ * @brief Computes the bitwise Jaccard similarity coefficient between two vectors.
+ * @param {Uint8Array} a - The first vector.
+ * @param {Uint8Array} b - The second vector.
+ * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+ */
+export const jaccard = (a: Uint8Array, b: Uint8Array): number => {
+  return compiled.jaccard(a, b);
+};
+
+/**
+ * @brief Computes the kullbackleibler similarity coefficient between two vectors.
+ * @param {Float64Array|Float32Array} a - The first vector.
+ * @param {Float64Array|Float32Array} b - The second vector.
+ * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+ */
+export const kullbackleibler = (a: Float64Array | Float32Array, b: Float64Array | Float32Array): number => {
+  return compiled.kullbackleibler(a, b);
+};
+
+/**
+ * @brief Computes the jensenshannon similarity coefficient between two vectors.
+ * @param {Float64Array|Float32Array} a - The first vector.
+ * @param {Float64Array|Float32Array} b - The second vector.
+ * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+ */
+export const jensenshannon = (a: Float64Array | Float32Array, b: Float64Array | Float32Array): number => {
+  return compiled.jensenshannon(a, b);
+};
+
+export default {
+  dot,
+  inner,
+  sqeuclidean,
+  cosine,
+  hamming,
+  jaccard,
+  kullbackleibler,
+  jensenshannon,
+};
+
+// utility functions to help find native builds
+
+function getBuildDir(dir: string) {
+  if (existsSync(path.join(dir, "build"))) return dir;
+  if (existsSync(path.join(dir, "prebuilds"))) return dir;
+  if (path.basename(dir) === ".next") {
+    // special case for next.js on custom node (not vercel)
+    const sideways = path.join(dir, "..", "node_modules", "simsimd");
+    if (existsSync(sideways)) return getBuildDir(sideways);
+  }
+  if (dir === "/") throw new Error("Could not find native build for simsimd");
+  return getBuildDir(path.join(dir, ".."));
+}
+
+function getDirName() {
+  try {
+    if (__dirname) return __dirname;
+  } catch (e) { }
+  return getRoot(getFileName());
+}

package/simsimd/javascript/test.mjs

@@ -0,0 +1,179 @@
+// Currently the builds are expected to run only on Node.js,
+// but Deno tests pass as well.
+//
+// Bun supports `node:assert`, but not `node:test`.
+// Using `require` we can make the tests compatible with Bun.
+//
+//    const isBun = typeof Bun !== "undefined";
+//    let assert, test;
+//    if (isBun) {
+//      assert = require('node:assert');
+//      test = require('bun:test');
+//    } else {
+//      assert = require('node:assert');
+//      test = require('node:test');
+//    }
+//
+// That, however, leads to other issues, like the following:
+//
+//    require is not defined in ES module scope, you can use import instead
+//
+// https://bun.sh/docs/runtime/nodejs-apis
+// https://bun.sh/guides/util/detect-bun
+import test from "node:test";
+import assert from "node:assert";
+
+import * as simsimd from "./dist/esm/simsimd.js";
+
+import * as fallback from "./dist/esm/fallback.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}`
+  );
+}
+
+test("Distance from itself", () => {
+  const f32s = new Float32Array([1.0, 2.0, 3.0]);
+  assertAlmostEqual(simsimd.sqeuclidean(f32s, f32s), 0.0, 0.01);
+  assertAlmostEqual(simsimd.cosine(f32s, f32s), 0.0, 0.01);
+
+  const f64s = new Float64Array([1.0, 2.0, 3.0]);
+  assertAlmostEqual(simsimd.sqeuclidean(f64s, f64s), 0.0, 0.01);
+  assertAlmostEqual(simsimd.cosine(f64s, f64s), 0.0, 0.01);
+
+  const f32sNormalized = new Float32Array([
+    1.0 / Math.sqrt(14),
+    2.0 / Math.sqrt(14),
+    3.0 / Math.sqrt(14),
+  ]);
+  assertAlmostEqual(simsimd.inner(f32sNormalized, f32sNormalized), 1.0, 0.01);
+
+  const f32sDistribution = new Float32Array([1.0 / 6, 2.0 / 6, 3.0 / 6]);
+  assertAlmostEqual(
+    simsimd.kullbackleibler(f32sDistribution, f32sDistribution),
+    0.0,
+    0.01
+  );
+  assertAlmostEqual(
+    simsimd.jensenshannon(f32sDistribution, f32sDistribution),
+    0.0,
+    0.01
+  );
+
+  const u8s = new Uint8Array([1, 2, 3]);
+  assertAlmostEqual(simsimd.hamming(u8s, u8s), 0.0, 0.01);
+  assertAlmostEqual(simsimd.jaccard(u8s, u8s), 0.0, 0.01);
+});
+
+test("Distance from itself JS fallback", () => {
+  const f32s = new Float32Array([1.0, 2.0, 3.0]);
+
+  assertAlmostEqual(fallback.sqeuclidean(f32s, f32s), 0.0, 0.01);
+  assertAlmostEqual(fallback.cosine(f32s, f32s), 0.0, 0.01);
+
+  const arrNormalized = new Float32Array([
+    1.0 / Math.sqrt(14),
+    2.0 / Math.sqrt(14),
+    3.0 / Math.sqrt(14),
+  ]);
+  assertAlmostEqual(fallback.inner(arrNormalized, arrNormalized), 1.0, 0.01);
+
+  const f32sDistribution = new Float32Array([1.0 / 6, 2.0 / 6, 3.0 / 6]);
+  assertAlmostEqual(
+    fallback.kullbackleibler(f32sDistribution, f32sDistribution),
+    0.0,
+    0.01
+  );
+  assertAlmostEqual(
+    fallback.jensenshannon(f32sDistribution, f32sDistribution),
+    0.0,
+    0.01
+  );
+
+  const u8s = new Uint8Array([1, 2, 3]);
+  assertAlmostEqual(fallback.hamming(u8s, u8s), 0.0, 0.01);
+  assertAlmostEqual(fallback.jaccard(u8s, u8s), 0.0, 0.01);
+});
+
+const f32Array1 = new Float32Array([1.0, 2.0, 3.0]);
+const f32Array2 = new Float32Array([4.0, 5.0, 6.0]);
+
+test("Squared Euclidean Distance", () => {
+  const result = simsimd.sqeuclidean(f32Array1, f32Array2);
+  assertAlmostEqual(result, 27.0, 0.01);
+});
+
+test("Inner Distance", () => {
+  const result = simsimd.inner(f32Array1, f32Array2);
+  assertAlmostEqual(result, 32.0, 0.01);
+});
+
+test("Cosine Similarity", () => {
+  const result = simsimd.cosine(f32Array1, f32Array2);
+  assertAlmostEqual(result, 0.029, 0.01);
+});
+
+test("Squared Euclidean Distance JS", () => {
+  const result = fallback.sqeuclidean(f32Array1, f32Array2);
+  assertAlmostEqual(result, 27.0, 0.01);
+});
+
+test("Inner Distance JS", () => {
+  const result = fallback.inner(f32Array1, f32Array2);
+  assertAlmostEqual(result, 32.0, 0.01);
+});
+
+test("Cosine Similarity JS", () => {
+  const result = fallback.cosine(f32Array1, f32Array2);
+  assertAlmostEqual(result, 0.029, 0.01);
+});
+
+test("Squared Euclidean Distance C vs JS", () => {
+  const result = simsimd.sqeuclidean(f32Array1, f32Array2);
+  const resultjs = fallback.sqeuclidean(f32Array1, f32Array2);
+  assertAlmostEqual(resultjs, result, 0.01);
+});
+
+test("Inner Distance C vs JS", () => {
+  const result = simsimd.inner(f32Array1, f32Array2);
+  const resultjs = fallback.inner(f32Array1, f32Array2);
+  assertAlmostEqual(resultjs, result, 0.01);
+});
+
+test("Cosine Similarity C vs JS", () => {
+  const result = simsimd.cosine(f32Array1, f32Array2);
+  const resultjs = fallback.cosine(f32Array1, f32Array2);
+  assertAlmostEqual(resultjs, result, 0.01);
+});
+
+test("Hamming C vs JS", () => {
+  const u8s = new Uint8Array([1, 2, 3]);
+  const result = simsimd.hamming(u8s, u8s);
+  const resultjs = fallback.hamming(u8s, u8s);
+  assertAlmostEqual(resultjs, result, 0.01);
+});
+
+test("Jaccard C vs JS", () => {
+  const u8s = new Uint8Array([1, 2, 3]);
+  const result = simsimd.jaccard(u8s, u8s);
+  const resultjs = fallback.jaccard(u8s, u8s);
+  assertAlmostEqual(resultjs, result, 0.01);
+});
+
+test("Kullback-Leibler C vs JS", () => {
+  const f32sDistribution = new Float32Array([1.0 / 6, 2.0 / 6, 3.0 / 6]);
+  const result = simsimd.kullbackleibler(f32sDistribution, f32sDistribution);
+  const resultjs = fallback.kullbackleibler(f32sDistribution, f32sDistribution);
+  assertAlmostEqual(resultjs, result, 0.01);
+});
+
+test("Jensen-Shannon C vs JS", () => {
+  const f32sDistribution = new Float32Array([1.0 / 6, 2.0 / 6, 3.0 / 6]);
+  const result = simsimd.jensenshannon(f32sDistribution, f32sDistribution);
+  const resultjs = fallback.jensenshannon(f32sDistribution, f32sDistribution);
+  assertAlmostEqual(resultjs, result, 0.01);
+});

package/simsimd/javascript/tsconfig-base.json

@@ -0,0 +1,37 @@
+{
+    "compileOnSave": false,
+    "exclude": [
+        "node_modules",
+        "dist"
+    ],
+    "include": [
+        "node-gyp-build.d.ts",
+        "simsimd.ts",
+        "fallback.ts"
+    ],
+    "compilerOptions": {
+        "allowJs": true,
+        "allowSyntheticDefaultImports": true,
+        "baseUrl": ".",
+        "declaration": true,
+        "esModuleInterop": true,
+        "inlineSourceMap": false,
+        "lib": [
+            "esnext"
+        ],
+        "listEmittedFiles": false,
+        "listFiles": false,
+        "moduleResolution": "node",
+        "noFallthroughCasesInSwitch": true,
+        "pretty": true,
+        "resolveJsonModule": true,
+        "rootDir": ".",
+        "skipLibCheck": true,
+        "strict": true,
+        "traceResolution": false,
+        "types": [
+            "node",
+            "./node-gyp-build.d.ts"
+        ]
+    }
+}

package/simsimd/javascript/tsconfig-cjs.json

@@ -0,0 +1,8 @@
+{
+    "extends": "./tsconfig-base.json",
+    "compilerOptions": {
+        "module": "commonjs",
+        "outDir": "dist/cjs",
+        "target": "es2015"
+    }
+}

package/simsimd/javascript/tsconfig-esm.json

@@ -0,0 +1,8 @@
+{
+    "extends": "./tsconfig-base.json",
+    "compilerOptions": {
+        "module": "esnext",
+        "outDir": "dist/esm",
+        "target": "esnext"
+    }
+}