binding.c

#include <js.h>
#include <bare.h>
#include <string.h>
#include <stdlib.h>
#include "usearch.h"

// Exception-safe wrappers (defined in usearch_wrapper.cpp)
extern usearch_index_t usearch_init_safe(usearch_init_options_t* options, usearch_error_t* error);
extern void usearch_free_safe(usearch_index_t index, usearch_error_t* error);
extern size_t usearch_size_safe(usearch_index_t index, usearch_error_t* error);
extern size_t usearch_capacity_safe(usearch_index_t index, usearch_error_t* error);
extern size_t usearch_dimensions_safe(usearch_index_t index, usearch_error_t* error);
extern void usearch_reserve_safe(usearch_index_t index, size_t capacity, usearch_error_t* error);
extern void usearch_add_safe(usearch_index_t index, usearch_key_t key, void const* vector, 
                              usearch_scalar_kind_t kind, usearch_error_t* error);
extern size_t usearch_search_safe(usearch_index_t index, void const* query, usearch_scalar_kind_t kind,
                                   size_t count, usearch_key_t* keys, usearch_distance_t* distances,
                                   usearch_error_t* error);
extern size_t usearch_remove_safe(usearch_index_t index, usearch_key_t key, usearch_error_t* error);
extern bool usearch_contains_safe(usearch_index_t index, usearch_key_t key, usearch_error_t* error);
extern size_t usearch_get_safe(usearch_index_t index, usearch_key_t key, size_t count,
                                void* vector, usearch_scalar_kind_t kind, usearch_error_t* error);
extern void usearch_save_safe(usearch_index_t index, char const* path, usearch_error_t* error);
extern void usearch_load_safe(usearch_index_t index, char const* path, usearch_error_t* error);
extern void usearch_view_safe(usearch_index_t index, char const* path, usearch_error_t* error);
extern void usearch_clear_safe(usearch_index_t index, usearch_error_t* error);

// Helper to throw JS error from usearch error
static void throw_if_error(js_env_t *env, usearch_error_t error) {
  if (error) {
    js_throw_error(env, NULL, error);
  }
}

// Create a new index
static js_value_t *fn_init(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 1;
  js_value_t *argv[1];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_init_options_t opts;
  memset(&opts, 0, sizeof(opts));
  opts.metric_kind = usearch_metric_cos_k;
  opts.quantization = usearch_scalar_f32_k;
  opts.dimensions = 0;
  opts.connectivity = 16;      // default M value for HNSW
  opts.expansion_add = 128;    // ef_construction
  opts.expansion_search = 64;  // ef
  opts.multi = false;

  if (argc > 0) {
    js_value_t *val;
    js_value_type_t val_type;

    // dimensions (required) - check type
    if (js_get_named_property(env, argv[0], "dimensions", &val) == 0) {
      js_typeof(env, val, &val_type);
      if (val_type == js_number) {
        uint32_t dim;
        js_get_value_uint32(env, val, &dim);
        opts.dimensions = dim;
      }
    }

    // metric - check if property exists AND is a string
    if (js_get_named_property(env, argv[0], "metric", &val) == 0) {
      js_typeof(env, val, &val_type);
      if (val_type == js_string) {
        utf8_t metric[32];
        size_t len;
        js_get_value_string_utf8(env, val, metric, sizeof(metric), &len);
        if (strcmp((char *)metric, "cos") == 0 || strcmp((char *)metric, "cosine") == 0) {
          opts.metric_kind = usearch_metric_cos_k;
        } else if (strcmp((char *)metric, "ip") == 0 || strcmp((char *)metric, "inner") == 0) {
          opts.metric_kind = usearch_metric_ip_k;
        } else if (strcmp((char *)metric, "l2sq") == 0 || strcmp((char *)metric, "l2") == 0) {
          opts.metric_kind = usearch_metric_l2sq_k;
        } else if (strcmp((char *)metric, "hamming") == 0) {
          opts.metric_kind = usearch_metric_hamming_k;
        } else if (strcmp((char *)metric, "jaccard") == 0) {
          opts.metric_kind = usearch_metric_jaccard_k;
        }
      }
    }

    // quantization - check if property exists AND is a string
    if (js_get_named_property(env, argv[0], "quantization", &val) == 0) {
      js_typeof(env, val, &val_type);
      if (val_type == js_string) {
        utf8_t quant[16];
        size_t len;
        js_get_value_string_utf8(env, val, quant, sizeof(quant), &len);
        if (strcmp((char *)quant, "f32") == 0) {
          opts.quantization = usearch_scalar_f32_k;
        } else if (strcmp((char *)quant, "f16") == 0) {
          opts.quantization = usearch_scalar_f16_k;
        } else if (strcmp((char *)quant, "i8") == 0) {
          opts.quantization = usearch_scalar_i8_k;
        }
      }
    }

    // connectivity - check type
    if (js_get_named_property(env, argv[0], "connectivity", &val) == 0) {
      js_typeof(env, val, &val_type);
      if (val_type == js_number) {
        uint32_t conn;
        js_get_value_uint32(env, val, &conn);
        opts.connectivity = conn;
      }
    }

    // multi - check type
    if (js_get_named_property(env, argv[0], "multi", &val) == 0) {
      js_typeof(env, val, &val_type);
      if (val_type == js_boolean) {
        bool multi;
        js_get_value_bool(env, val, &multi);
        opts.multi = multi;
      }
    }
  }
  usearch_error_t error = NULL;
  usearch_index_t index = usearch_init_safe(&opts, &error);
  if (error) {
    throw_if_error(env, error);
    js_value_t *undef;
    js_get_undefined(env, &undef);
    return undef;
  }

  // Reserve initial capacity (required before adding vectors)
  usearch_reserve_safe(index, 1024, &error);
  if (error) {
    usearch_free_safe(index, &error);
    throw_if_error(env, "Failed to reserve initial capacity");
    js_value_t *undef;
    js_get_undefined(env, &undef);
    return undef;
  }

  js_value_t *result;
  js_create_external(env, index, NULL, NULL, &result);
  return result;
}

// Free an index
static js_value_t *fn_free(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 1;
  js_value_t *argv[1];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  usearch_error_t error = NULL;
  usearch_free_safe(index, &error);
  throw_if_error(env, error);

  js_value_t *undef;
  js_get_undefined(env, &undef);
  return undef;
}

// Get index size
static js_value_t *fn_size(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 1;
  js_value_t *argv[1];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  usearch_error_t error = NULL;
  size_t size = usearch_size_safe(index, &error);
  throw_if_error(env, error);

  js_value_t *result;
  js_create_uint32(env, (uint32_t)size, &result);
  return result;
}

// Get index dimensions
static js_value_t *fn_dimensions(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 1;
  js_value_t *argv[1];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  usearch_error_t error = NULL;
  size_t dims = usearch_dimensions_safe(index, &error);
  throw_if_error(env, error);

  js_value_t *result;
  js_create_uint32(env, (uint32_t)dims, &result);
  return result;
}

// Get index capacity
static js_value_t *fn_capacity(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 1;
  js_value_t *argv[1];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  usearch_error_t error = NULL;
  size_t cap = usearch_capacity_safe(index, &error);
  throw_if_error(env, error);

  js_value_t *result;
  js_create_uint32(env, (uint32_t)cap, &result);
  return result;
}

// Reserve capacity
static js_value_t *fn_reserve(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 2;
  js_value_t *argv[2];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  uint32_t capacity;
  js_get_value_uint32(env, argv[1], &capacity);

  usearch_error_t error = NULL;
  usearch_reserve_safe(index, capacity, &error);
  throw_if_error(env, error);

  js_value_t *undef;
  js_get_undefined(env, &undef);
  return undef;
}

// Add a vector
static js_value_t *fn_add(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 3;
  js_value_t *argv[3];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  int64_t key;
  js_get_value_int64(env, argv[1], &key);

  // Get Float32Array data
  void *data;
  size_t length;
  js_typedarray_type_t type;
  js_get_typedarray_info(env, argv[2], &type, &data, &length, NULL, NULL);

  usearch_error_t error = NULL;
  usearch_add_safe(index, (usearch_key_t)key, data, usearch_scalar_f32_k, &error);
  throw_if_error(env, error);

  js_value_t *undef;
  js_get_undefined(env, &undef);
  return undef;
}

// Search for nearest neighbors
static js_value_t *fn_search(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 3;
  js_value_t *argv[3];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  // Query vector
  void *query_data;
  size_t query_length;
  js_typedarray_type_t type;
  js_get_typedarray_info(env, argv[1], &type, &query_data, &query_length, NULL, NULL);

  // Count (k)
  uint32_t count;
  js_get_value_uint32(env, argv[2], &count);

  // Allocate output buffers
  usearch_key_t *keys = (usearch_key_t *)malloc(count * sizeof(usearch_key_t));
  usearch_distance_t *distances = (usearch_distance_t *)malloc(count * sizeof(usearch_distance_t));

  usearch_error_t error = NULL;
  size_t found = usearch_search_safe(index, query_data, usearch_scalar_f32_k, count, keys, distances, &error);

  if (error) {
    free(keys);
    free(distances);
    throw_if_error(env, error);
    js_value_t *undef;
    js_get_undefined(env, &undef);
    return undef;
  }

  // Create result object { keys: BigUint64Array, distances: Float32Array, count: number }
  js_value_t *result;
  js_create_object(env, &result);

  // Keys array (BigUint64Array)
  js_value_t *keys_ab, *keys_arr;
  void *keys_buf;
  js_create_arraybuffer(env, found * sizeof(uint64_t), &keys_buf, &keys_ab);
  memcpy(keys_buf, keys, found * sizeof(uint64_t));
  js_create_typedarray(env, js_biguint64array, found, keys_ab, 0, &keys_arr);
  js_set_named_property(env, result, "keys", keys_arr);

  // Distances array (Float32Array)
  js_value_t *dist_ab, *dist_arr;
  void *dist_buf;
  js_create_arraybuffer(env, found * sizeof(float), &dist_buf, &dist_ab);
  memcpy(dist_buf, distances, found * sizeof(float));
  js_create_typedarray(env, js_float32array, found, dist_ab, 0, &dist_arr);
  js_set_named_property(env, result, "distances", dist_arr);

  // Count
  js_value_t *count_val;
  js_create_uint32(env, (uint32_t)found, &count_val);
  js_set_named_property(env, result, "count", count_val);

  free(keys);
  free(distances);

  return result;
}

// Remove a vector
static js_value_t *fn_remove(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 2;
  js_value_t *argv[2];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  int64_t key;
  js_get_value_int64(env, argv[1], &key);

  usearch_error_t error = NULL;
  size_t removed = usearch_remove_safe(index, (usearch_key_t)key, &error);
  throw_if_error(env, error);

  js_value_t *result;
  js_create_uint32(env, (uint32_t)removed, &result);
  return result;
}

// Check if index contains a key
static js_value_t *fn_contains(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 2;
  js_value_t *argv[2];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  int64_t key;
  js_get_value_int64(env, argv[1], &key);

  usearch_error_t error = NULL;
  bool exists = usearch_contains_safe(index, (usearch_key_t)key, &error);
  throw_if_error(env, error);

  js_value_t *result;
  js_get_boolean(env, exists, &result);
  return result;
}

// Save index to file
static js_value_t *fn_save(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 2;
  js_value_t *argv[2];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  utf8_t path[4096];
  size_t path_len;
  js_get_value_string_utf8(env, argv[1], path, sizeof(path), &path_len);

  usearch_error_t error = NULL;
  usearch_save_safe(index, (char *)path, &error);
  throw_if_error(env, error);

  js_value_t *undef;
  js_get_undefined(env, &undef);
  return undef;
}

// Load index from file
static js_value_t *fn_load(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 2;
  js_value_t *argv[2];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  utf8_t path[4096];
  size_t path_len;
  js_get_value_string_utf8(env, argv[1], path, sizeof(path), &path_len);

  usearch_error_t error = NULL;
  usearch_load_safe(index, (char *)path, &error);
  throw_if_error(env, error);

  js_value_t *undef;
  js_get_undefined(env, &undef);
  return undef;
}

// View index from file (memory-mapped)
static js_value_t *fn_view(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 2;
  js_value_t *argv[2];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  utf8_t path[4096];
  size_t path_len;
  js_get_value_string_utf8(env, argv[1], path, sizeof(path), &path_len);

  usearch_error_t error = NULL;
  usearch_view_safe(index, (char *)path, &error);
  throw_if_error(env, error);

  js_value_t *undef;
  js_get_undefined(env, &undef);
  return undef;
}

// Get vector by key
static js_value_t *fn_get(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 2;
  js_value_t *argv[2];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  int64_t key;
  js_get_value_int64(env, argv[1], &key);

  // Get dimensions to allocate buffer
  usearch_error_t error = NULL;
  size_t dims = usearch_dimensions_safe(index, &error);
  if (error) {
    throw_if_error(env, error);
    js_value_t *undef;
    js_get_undefined(env, &undef);
    return undef;
  }

  // Create output Float32Array
  js_value_t *ab, *arr;
  void *data;
  js_create_arraybuffer(env, dims * sizeof(float), &data, &ab);

  error = NULL;
  size_t found = usearch_get_safe(index, (usearch_key_t)key, 1, data, usearch_scalar_f32_k, &error);

  if (error || found == 0) {
    if (error) throw_if_error(env, error);
    js_value_t *null_val;
    js_get_null(env, &null_val);
    return null_val;
  }

  js_create_typedarray(env, js_float32array, dims, ab, 0, &arr);
  return arr;
}

// Clear index
static js_value_t *fn_clear(js_env_t *env, js_callback_info_t *info) {
  size_t argc = 1;
  js_value_t *argv[1];
  js_get_callback_info(env, info, &argc, argv, NULL, NULL);

  usearch_index_t index;
  js_get_value_external(env, argv[0], (void **)&index);

  usearch_error_t error = NULL;
  usearch_clear_safe(index, &error);
  throw_if_error(env, error);

  js_value_t *undef;
  js_get_undefined(env, &undef);
  return undef;
}

static js_value_t *init(js_env_t *env, js_value_t *exports) {
  // Define all exports
  #define EXPORT_FN(name, fn) { \
    js_value_t *val; \
    js_create_function(env, name, -1, fn, NULL, &val); \
    js_set_named_property(env, exports, name, val); \
  }

  EXPORT_FN("init", fn_init)
  EXPORT_FN("free", fn_free)
  EXPORT_FN("size", fn_size)
  EXPORT_FN("dimensions", fn_dimensions)
  EXPORT_FN("capacity", fn_capacity)
  EXPORT_FN("reserve", fn_reserve)
  EXPORT_FN("add", fn_add)
  EXPORT_FN("search", fn_search)
  EXPORT_FN("remove", fn_remove)
  EXPORT_FN("contains", fn_contains)
  EXPORT_FN("get", fn_get)
  EXPORT_FN("save", fn_save)
  EXPORT_FN("load", fn_load)
  EXPORT_FN("view", fn_view)
  EXPORT_FN("clear", fn_clear)

  #undef EXPORT_FN

  return exports;
}

BARE_MODULE(usearch, init)