usearch 2.8.14 → 2.8.16

package/simsimd/javascript/fallback.ts

@@ -0,0 +1,193 @@
+/**
+ * @brief Computes the inner distance of two vectors.
+ * @param {Float32Array} a - The first vector.
+ * @param {Float32Array} b - The second vector.
+ * @returns {number} The inner distance of vectors a and b.
+ */
+export function inner(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length) {
+    throw new Error("Vectors must have the same length");
+  }
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result += a[i] * b[i];
+  }
+  return 1 - result;
+}
+
+/**
+ * @brief Computes the squared Euclidean distance between two vectors.
+ * @param {Float32Array|Int8Array} a - The first vector.
+ * @param {Float32Array|Int8Array} b - The second vector.
+ * @returns {number} The squared Euclidean distance between vectors a and b.
+ */
+export function sqeuclidean(
+  a: Float32Array | Int8Array,
+  b: Float32Array | Int8Array
+): number {
+  if (a.length !== b.length) {
+    throw new Error("Vectors must have the same length");
+  }
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result += (a[i] - b[i]) * (a[i] - b[i]);
+  }
+  return result;
+}
+
+/**
+ * @brief Computes the cosine distance between two vectors.
+ * @param {Float32Array|Int8Array} a - The first vector.
+ * @param {Float32Array|Int8Array} b - The second vector.
+ * @returns {number} The cosine distance between vectors a and b.
+ */
+export function cosine(
+  a: Float32Array | Int8Array,
+  b: Float32Array | Int8Array
+): number {
+  if (a.length !== b.length) {
+    throw new Error("Vectors must have the same length");
+  }
+
+  let dotProduct = 0;
+  let magnitudeA = 0;
+  let magnitudeB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    magnitudeA += a[i] * a[i];
+    magnitudeB += b[i] * b[i];
+  }
+
+  magnitudeA = Math.sqrt(magnitudeA);
+  magnitudeB = Math.sqrt(magnitudeB);
+
+  if (magnitudeA === 0 || magnitudeB === 0) {
+    console.warn(
+      "Warning: One of the magnitudes is zero. Cosine similarity is undefined."
+    );
+    return 0;
+  }
+
+  return 1 - dotProduct / (magnitudeA * magnitudeB);
+}
+
+/**
+ * @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 => {
+  if (a.length !== b.length) {
+    throw new Error("Arrays must be of the same length");
+  }
+
+  let distance = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    let xor = a[i] ^ b[i]; // XOR operation to find differing bits
+
+    // Count the number of set bits (differing bits)
+    while (xor > 0) {
+      distance += xor & 1;
+      xor >>= 1;
+    }
+  }
+
+  return distance;
+};
+
+/**
+ * @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 => {
+  if (a.length !== b.length) {
+    throw new Error("Arrays must be of the same length");
+  }
+
+  let intersection = 0;
+  let union = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    let ai = a[i];
+    let bi = b[i];
+
+    // Count the number of set bits in a AND b for intersection
+    let and = ai & bi;
+    while (and > 0) {
+      intersection += and & 1;
+      and >>= 1;
+    }
+
+    // Count the number of set bits in a OR b for union
+    let or = ai | bi;
+    while (or > 0) {
+      union += or & 1;
+      or >>= 1;
+    }
+  }
+
+  if (union === 0) return 0; // Avoid division by zero
+
+  return 1 - intersection / union;
+};
+
+/**
+ * @brief Computes the kullbackleibler similarity coefficient between two vectors.
+ * @param {Float32Array} a - The first vector.
+ * @param {Float32Array} b - The second vector.
+ * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+ */
+export const kullbackleibler = (a: Float32Array, b: Float32Array): number => {
+  if (a.length !== b.length) {
+    throw new Error("Arrays must be of the same length");
+  }
+
+  let divergence = 0.0;
+
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] > 0) {
+      if (b[i] === 0) {
+        throw new Error(
+          "Division by zero encountered in KL divergence calculation"
+        );
+      }
+      divergence += a[i] * Math.log(a[i] / b[i]);
+    }
+  }
+
+  return divergence;
+};
+
+/**
+ * @brief Computes the jensenshannon similarity coefficient between two vectors.
+ * @param {Float32Array} a - The first vector.
+ * @param {Float32Array} b - The second vector.
+ * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+ */
+export const jensenshannon = (p: Float32Array, q: Float32Array): number => {
+  if (p.length !== q.length) {
+    throw new Error("Arrays must be of the same length");
+  }
+
+  const m = p.map((value, index) => (value + q[index]) / 2);
+
+  const divergence = 0.5 * kullbackleibler(p, m) + 0.5 * kullbackleibler(q, m);
+  return Math.sqrt(divergence);
+};
+
+export default {
+  sqeuclidean,
+  cosine,
+  inner,
+  hamming,
+  jaccard,
+  kullbackleibler,
+  jensenshannon,
+};

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

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

package/simsimd/javascript/simsimd.ts

@@ -0,0 +1,124 @@
+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 {Float32Array|Int8Array} a - The first vector.
+ * @param {Float32Array|Int8Array} b - The second vector.
+ * @returns {number} The squared Euclidean distance between vectors a and b.
+ */
+export const sqeuclidean = (
+  a: Float32Array | Int8Array,
+  b: Float32Array | Int8Array
+): number => {
+  return compiled.sqeuclidean(a, b);
+};
+
+/**
+ * @brief Computes the cosine distance between two vectors.
+ * @param {Float32Array|Int8Array} a - The first vector.
+ * @param {Float32Array|Int8Array} b - The second vector.
+ * @returns {number} The cosine distance between vectors a and b.
+ */
+export const cosine = (
+  a: Float32Array | Int8Array,
+  b: Float32Array | Int8Array
+): number => {
+  return compiled.cosine(a, b);
+};
+
+/**
+ * @brief Computes the inner distance of two vectors.
+ * @param {Float32Array} a - The first vector.
+ * @param {Float32Array} b - The second vector.
+ * @returns {number} The inner distance of vectors a and b.
+ */
+export const inner = (a: Float32Array, b: Float32Array): number => {
+  return compiled.inner(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 {Float32Array} a - The first vector.
+ * @param {Float32Array} b - The second vector.
+ * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+ */
+export const kullbackleibler = (a: Float32Array, b: Float32Array): number => {
+  return compiled.kullbackleibler(a, b);
+};
+
+/**
+ * @brief Computes the jensenshannon similarity coefficient between two vectors.
+ * @param {Float32Array} a - The first vector.
+ * @param {Float32Array} b - The second vector.
+ * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+ */
+export const jensenshannon = (a: Float32Array, b: Float32Array): number => {
+  return compiled.jensenshannon(a, b);
+};
+
+export default {
+  sqeuclidean,
+  cosine,
+  inner,
+  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,153 @@
+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 f32sNormalized = new Float32Array([
+    1.0 / Math.sqrt(14),
+    2.0 / Math.sqrt(14),
+    3.0 / Math.sqrt(14),
+  ]);
+  assertAlmostEqual(simsimd.inner(f32sNormalized, f32sNormalized), 0.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), 0.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, -31.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, -31.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.cosine(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,25 @@
+{
+    "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"
+    }
+}