usearch 2.21.4 → 2.25.0

package/simsimd/javascript/fallback.ts

@@ -1,233 +0,0 @@
-/**
- * @brief Computes the inner product of two vectors (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 function inner(a: Float64Array | Float32Array, b: Float64Array | 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 result;
-}
-
-/**
- * @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 function dot(a: Float64Array | Float32Array, b: Float64Array | Float32Array): number {
-  return inner(a, b);
-}
-
-/**
- * @brief Computes the squared Euclidean distance between two vectors.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} a - The first vector.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} b - The second vector.
- * @returns {number} The squared Euclidean distance between vectors a and b.
- */
-export function sqeuclidean(
-  a: Float64Array | Float32Array | Int8Array | Uint8Array,
-  b: Float64Array | Float32Array | Int8Array | Uint8Array
-): 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 L2 Euclidean distance between two vectors.
- * @param {Float64Array|Float32Array|Int8Array | Uint8Array} a - The first vector.
- * @param {Float64Array|Float32Array|Int8Array | Uint8Array} b - The second vector.
- * @returns {number} The L2 Euclidean distance between vectors a and b.
- */
-export function euclidean(
-  a: Float64Array | Float32Array | Int8Array | Uint8Array,
-  b: Float64Array | Float32Array | Int8Array | Uint8Array
-): 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 Math.sqrt(result);
-}
-
-
-/**
- * @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 function cosine(
-  a: Float64Array | Float32Array | Int8Array,
-  b: Float64Array | 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) return 0; // distance when both zero
-  if (magnitudeA === 0 || magnitudeB === 0) return 1; // distance when one is zero
-
-  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 distance between two vectors.
- * @param {Uint8Array} a - The first vector.
- * @param {Uint8Array} b - The second vector.
- * @returns {number} The Jaccard distance 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 Kullback-Leibler divergence between two probability distributions.
- * @param {Float64Array|Float32Array} a - The first vector.
- * @param {Float64Array|Float32Array} b - The second vector.
- * @returns {number} The Kullback-Leibler divergence between vectors a and b.
- */
-export const kullbackleibler = (a: Float64Array | Float32Array, b: Float64Array | 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 || b[i] < 0) {
-      throw new Error("Negative values are not allowed in probability distributions");
-    }
-    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 Jensen-Shannon distance between two probability distributions.
- * @param {Float64Array|Float32Array} a - The first probability distribution.
- * @param {Float64Array|Float32Array} b - The second probability distribution.
- * @returns {number} The Jensen-Shannon distance between distributions a and b.
- */
-export const jensenshannon = (a: Float64Array | Float32Array, b: Float64Array | Float32Array): number => {
-  if (a.length !== b.length) {
-    throw new Error("Arrays must be of the same length");
-  }
-
-  let divergence = 0;
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] < 0 || b[i] < 0) {
-      throw new Error("Negative values are not allowed in probability distributions");
-    }
-    const m = (a[i] + b[i]) / 2;
-    if (m > 0) {
-      if (a[i] > 0) divergence += a[i] * Math.log(a[i] / m);
-      if (b[i] > 0) divergence += b[i] * Math.log(b[i] / m);
-    }
-  }
-
-  divergence /= 2;
-  return Math.sqrt(divergence);
-};
-
-
-export default {
-  sqeuclidean,
-  euclidean,
-  cosine,
-  inner,
-  hamming,
-  jaccard,
-  kullbackleibler,
-  jensenshannon,
-};

package/simsimd/javascript/lib.c

@@ -1,125 +0,0 @@
-/**
- *  @file       lib.c
- *  @brief      JavaScript bindings for SimSIMD.
- *  @author     Ash Vardanian
- *  @date       October 18, 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 once, when the module is loaded.
-simsimd_capability_t static_capabilities = simsimd_cap_serial_k;
-
-napi_value dense(napi_env env, napi_callback_info info, simsimd_metric_kind_t metric_kind,
-                 simsimd_datatype_t datatype) {
-    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;
-    }
-
-    if (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_u8_k; break;
-        default: break;
-        }
-
-    simsimd_metric_dense_punned_t metric = NULL;
-    simsimd_capability_t capability = simsimd_cap_serial_k;
-    simsimd_find_kernel_punned(metric_kind, datatype, static_capabilities, simsimd_cap_any_k,
-                               (simsimd_kernel_punned_t *)&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 api_ip(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_dot_k, simsimd_datatype_unknown_k);
-}
-napi_value api_cos(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_cosine_k, simsimd_datatype_unknown_k);
-}
-napi_value api_l2sq(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_sqeuclidean_k, simsimd_datatype_unknown_k);
-}
-napi_value api_l2(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_l2_k, simsimd_datatype_unknown_k);
-}
-napi_value api_kl(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_kl_k, simsimd_datatype_unknown_k);
-}
-napi_value api_js(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_js_k, simsimd_datatype_unknown_k);
-}
-napi_value api_hamming(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_hamming_k, simsimd_datatype_b8_k);
-}
-napi_value api_jaccard(napi_env env, napi_callback_info info) {
-    return dense(env, info, simsimd_metric_jaccard_k, simsimd_datatype_b8_k);
-}
-
-napi_value Init(napi_env env, napi_value exports) {
-
-    // Define an array of property descriptors
-    napi_property_descriptor dot_descriptor = {"dot", 0, api_ip, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor inner_descriptor = {"inner", 0, api_ip, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor sqeuclidean_descriptor = {"sqeuclidean", 0, api_l2sq, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor euclidean_descriptor = {"euclidean", 0, api_l2, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor cosine_descriptor = {"cosine", 0, api_cos, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor hamming_descriptor = {"hamming", 0, api_hamming, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor jaccard_descriptor = {"jaccard", 0, api_jaccard, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor kl_descriptor = {"kullbackleibler", 0, api_kl, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor js_descriptor = {"jensenshannon", 0, api_js, 0, 0, 0, napi_default, 0};
-    napi_property_descriptor properties[] = {
-        dot_descriptor,     inner_descriptor,   sqeuclidean_descriptor, euclidean_descriptor, cosine_descriptor,
-        hamming_descriptor, jaccard_descriptor, kl_descriptor,          js_descriptor,
-    };
-
-    // Define the properties on the `exports` object
-    size_t property_count = sizeof(properties) / sizeof(properties[0]);
-    napi_define_properties(env, exports, property_count, properties);
-
-    static_capabilities = simsimd_capabilities();
-    return exports;
-}
-
-NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

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

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

package/simsimd/javascript/simsimd.ts

@@ -1,179 +0,0 @@
-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 doesn'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|Uint8Array} a - The first vector.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} b - The second vector.
- * @returns {number} The squared Euclidean distance between vectors a and b.
- */
-export const sqeuclidean = (
-  a: Float64Array | Float32Array | Int8Array | Uint8Array,
-  b: Float64Array | Float32Array | Int8Array | Uint8Array
-): number => {
-  return compiled.sqeuclidean(a, b);
-};
-
-/**
- * @brief Computes the Euclidean distance between two vectors.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} a - The first vector.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} b - The second vector.
- * @returns {number} The Euclidean distance between vectors a and b.
- */
-export const euclidean = (
-  a: Float64Array | Float32Array | Int8Array | Uint8Array,
-  b: Float64Array | Float32Array | Int8Array | Uint8Array
-): number => {
-  return compiled.euclidean(a, b);
-};
-
-/**
- * @brief Computes the cosine distance between two vectors.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} a - The first vector.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} b - The second vector.
- * @returns {number} The cosine distance between vectors a and b.
- */
-export const cosine = (
-  a: Float64Array | Float32Array | Int8Array | Uint8Array,
-  b: Float64Array | Float32Array | Int8Array | Uint8Array
-): number => {
-  return compiled.cosine(a, b);
-};
-
-/**
- * @brief Computes the inner product of two vectors (same as dot product).
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} a - The first vector.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} b - The second vector.
- * @returns {number} The inner product of vectors a and b.
- */
-export const inner = (
-  a: Float64Array | Float32Array | Int8Array | Uint8Array,
-  b: Float64Array | Float32Array | Int8Array | Uint8Array
-): number => {
-  return compiled.inner(a, b);
-};
-
-/**
- * @brief Computes the dot product of two vectors (same as inner product).
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} a - The first vector.
- * @param {Float64Array|Float32Array|Int8Array|Uint8Array} b - The second vector.
- * @returns {number} The dot product of vectors a and b.
- */
-export const dot = (
-  a: Float64Array | Float32Array | Int8Array | Uint8Array,
-  b: Float64Array | Float32Array | Int8Array | Uint8Array
-): 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 distance between two vectors.
- * @param {Uint8Array} a - The first vector.
- * @param {Uint8Array} b - The second vector.
- * @returns {number} The Jaccard distance between vectors a and b.
- */
-export const jaccard = (a: Uint8Array, b: Uint8Array): number => {
-  return compiled.jaccard(a, b);
-};
-
-/**
- * @brief Computes the Kullback-Leibler divergence between two vectors.
- * @param {Float64Array|Float32Array} a - The first vector.
- * @param {Float64Array|Float32Array} b - The second vector.
- * @returns {number} The Kullback-Leibler divergence between vectors a and b.
- */
-export const kullbackleibler = (a: Float64Array | Float32Array, b: Float64Array | Float32Array): number => {
-  return compiled.kullbackleibler(a, b);
-};
-
-/**
- * @brief Computes the Jensen-Shannon divergence between two vectors.
- * @param {Float64Array|Float32Array} a - The first vector.
- * @param {Float64Array|Float32Array} b - The second vector.
- * @returns {number} The Jensen-Shannon divergence between vectors a and b.
- */
-export const jensenshannon = (a: Float64Array | Float32Array, b: Float64Array | Float32Array): number => {
-  return compiled.jensenshannon(a, b);
-};
-
-/**
- * Quantizes a floating-point vector into a binary vector (1 for positive values, 0 for non-positive values) and packs the result into a Uint8Array, where each element represents 8 binary values from the original vector.
- * This function is useful for preparing data for bitwise distance computations, such as Hamming or Jaccard indices.
- * 
- * @param {Float32Array | Float64Array | Int8Array} vector The floating-point vector to be quantized and packed.
- * @returns {Uint8Array} A Uint8Array where each byte represents 8 binary quantized values from the input vector.
- */
-export const toBinary = (vector: Float32Array | Float64Array | Int8Array): Uint8Array => {
-  const byteLength = Math.ceil(vector.length / 8);
-  const packedVector = new Uint8Array(byteLength);
-
-  for (let i = 0; i < vector.length; i++) {
-    if (vector[i] > 0) {
-      const byteIndex = Math.floor(i / 8);
-      const bitPosition = 7 - (i % 8);
-      packedVector[byteIndex] |= (1 << bitPosition);
-    }
-  }
-
-  return packedVector;
-};
-export default {
-  dot,
-  inner,
-  sqeuclidean,
-  euclidean,
-  cosine,
-  hamming,
-  jaccard,
-  kullbackleibler,
-  jensenshannon,
-  toBinary,
-};
-
-/**
- * @brief Finds the directory where the native build of the simsimd module is located.
- * @param {string} dir - The directory to start the search from.
- */
-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/tsconfig-cjs.json

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