bare-usearch 0.1.0

package/CMakeLists.txt

@@ -0,0 +1,70 @@
+cmake_minimum_required(VERSION 3.25)
+
+find_package(cmake-bare REQUIRED PATHS node_modules/cmake-bare)
+find_package(cmake-napi REQUIRED PATHS node_modules/cmake-napi)
+
+project(bare_usearch C CXX)
+
+# usearch requires C++ exceptions - remove -fno-exceptions if present
+string(REPLACE "-fno-exceptions" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fexceptions")
+
+# Remove NDEBUG to avoid noexcept declarations that conflict with exception handling
+string(REPLACE "-DNDEBUG" "" CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE}")
+
+set(usearch_sources
+  binding.c
+  vendor/usearch/c/lib.cpp
+  usearch_wrapper.cpp
+)
+
+set(usearch_includes
+  vendor/usearch/include
+  vendor/usearch/c
+  vendor/usearch/fp16/include
+)
+
+set(usearch_defines
+  USEARCH_USE_OPENMP=0
+  USEARCH_USE_SIMSIMD=0
+  USEARCH_USE_FP16LIB=1
+  USEARCH_CAN_COMPILE_FP16=0
+  USEARCH_CAN_COMPILE_FLOAT16=0
+  USEARCH_CAN_COMPILE_BF16=0
+  USEARCH_CAN_COMPILE_BFLOAT16=0
+)
+
+# Create the Bare addon
+add_bare_module(bare_usearch_bare)
+
+target_sources(${bare_usearch_bare} PRIVATE ${usearch_sources})
+target_include_directories(${bare_usearch_bare} PRIVATE ${usearch_includes})
+target_compile_definitions(${bare_usearch_bare} PRIVATE ${usearch_defines})
+set_target_properties(${bare_usearch_bare} PROPERTIES
+  CXX_STANDARD 11
+  CXX_STANDARD_REQUIRED ON
+)
+target_compile_options(${bare_usearch_bare} PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fexceptions>)
+
+# Create the Node.js NAPI addon
+add_napi_module(bare_usearch_node)
+
+target_sources(${bare_usearch_node} PRIVATE ${usearch_sources})
+target_compile_definitions(${bare_usearch_node} PRIVATE
+  ${usearch_defines}
+  NAPI_VERSION=9
+)
+target_include_directories(${bare_usearch_node} PRIVATE ${usearch_includes})
+set_target_properties(${bare_usearch_node} PROPERTIES
+  CXX_STANDARD 11
+  CXX_STANDARD_REQUIRED ON
+)
+target_compile_options(${bare_usearch_node} PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fexceptions>)
+
+resolve_node_module(bare-compat-napi compat)
+
+target_include_directories(
+  ${bare_usearch_node}
+  PRIVATE
+    "${compat}/include"
+)

package/README.md

@@ -0,0 +1,133 @@
+# bare-usearch
+
+Native [USearch](https://github.com/unum-cloud/usearch) bindings for [Bare](https://github.com/holepunchto/bare).
+
+Fast approximate nearest neighbor search for high-dimensional vectors.
+
+## Requirements
+
+- CMake 3.25+
+- C/C++ compiler (clang, gcc, or MSVC)
+- Node.js (for npm/cmake-bare)
+- Bare runtime
+
+## Building
+
+Clone with submodules:
+
+```bash
+git clone --recursive https://github.com/CameronTofer/bare-usearch
+cd bare-usearch
+```
+
+Or if already cloned:
+
+```bash
+git submodule update --init --recursive
+```
+
+Install dependencies and build:
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+```javascript
+const { Index } = require('bare-usearch')
+
+// Create index with 128-dimensional vectors
+const index = new Index({
+  dimensions: 128,
+  metric: 'cos'  // cosine similarity
+})
+
+// Add vectors (key, vector)
+index.add(1, new Float32Array([0.1, 0.2, ...]))
+index.add(2, new Float32Array([0.3, 0.4, ...]))
+
+// Search for k nearest neighbors
+const results = index.search(queryVector, 10)
+console.log(results.keys)       // [2, 1, ...]
+console.log(results.distances)  // Float32Array
+
+// Persistence
+index.save('index.usearch')
+index.load('index.usearch')
+
+// Cleanup
+index.free()
+```
+
+See `examples/` for more:
+- `basic.js` - Basic usage with add/search/remove
+- `persistence.js` - Saving and loading indexes
+- `topics.js` - Topic extraction using vector similarity
+
+Run examples with:
+```bash
+bare examples/basic.js
+```
+
+## Testing
+
+```bash
+npm test            # bare
+npm run test:node   # node
+```
+
+## API Reference
+
+### Index
+
+```javascript
+new Index(options?)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dimensions` | number | required | Vector dimensionality |
+| `metric` | string | `'cos'` | Distance metric |
+| `quantization` | string | `'f32'` | Scalar quantization |
+| `connectivity` | number | auto | Graph connectivity (M) |
+| `multi` | boolean | `false` | Allow multiple vectors per key |
+
+**Metrics:** `'cos'`, `'ip'` (inner product), `'l2'` (L2 squared), `'hamming'`, `'jaccard'`
+
+**Quantization:** `'f32'`, `'f16'`, `'i8'`
+
+**Properties:**
+
+- `size` - Number of vectors in index
+- `dimensions` - Vector dimensionality
+- `capacity` - Current capacity
+
+**Methods:**
+
+- `add(key, vector)` - Add a vector with numeric key
+- `search(query, k)` - Find k nearest neighbors, returns `{ keys, distances, count }`
+- `remove(key)` - Remove vector by key
+- `contains(key)` - Check if key exists
+- `get(key)` - Retrieve vector by key (returns Float32Array or null)
+- `reserve(capacity)` - Pre-allocate space for vectors
+- `save(path)` - Save index to file
+- `load(path)` - Load index from file
+- `view(path)` - Memory-map index from file (read-only)
+- `clear()` - Remove all vectors
+- `free()` - Release resources
+
+## Platform Support
+
+| Platform | Architecture |
+|----------|--------------|
+| macOS | arm64, x64 |
+| Linux | x64, arm64 |
+| Windows | x64, arm64 |
+| Android | arm64, arm, x64, ia32 |
+| iOS | arm64, x64 (simulator) |
+
+## License
+
+MIT

package/binding.c

@@ -0,0 +1,529 @@
+#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)

package/binding.js

@@ -0,0 +1,2 @@
+require.addon = require('require-addon')
+module.exports = require.addon('.', __filename)

package/index.js

@@ -0,0 +1,84 @@
+const binding = require('./binding')
+
+class Index {
+  constructor (opts = {}) {
+    this._handle = binding.init(opts)
+  }
+
+  get size () {
+    return binding.size(this._handle)
+  }
+
+  get dimensions () {
+    return binding.dimensions(this._handle)
+  }
+
+  get capacity () {
+    return binding.capacity(this._handle)
+  }
+
+  reserve (capacity) {
+    binding.reserve(this._handle, capacity)
+  }
+
+  add (key, vector) {
+    if (!(vector instanceof Float32Array)) {
+      vector = new Float32Array(vector)
+    }
+    binding.add(this._handle, key, vector)
+  }
+
+  search (query, k = 10) {
+    if (!(query instanceof Float32Array)) {
+      query = new Float32Array(query)
+    }
+    const result = binding.search(this._handle, query, k)
+    // Convert BigUint64Array keys to regular numbers for convenience
+    const keys = new Array(result.count)
+    for (let i = 0; i < result.count; i++) {
+      keys[i] = Number(result.keys[i])
+    }
+    return {
+      keys,
+      distances: result.distances,
+      count: result.count
+    }
+  }
+
+  remove (key) {
+    return binding.remove(this._handle, key)
+  }
+
+  contains (key) {
+    return binding.contains(this._handle, key)
+  }
+
+  get (key) {
+    return binding.get(this._handle, key)
+  }
+
+  save (path) {
+    binding.save(this._handle, path)
+  }
+
+  load (path) {
+    binding.load(this._handle, path)
+  }
+
+  view (path) {
+    binding.view(this._handle, path)
+  }
+
+  clear () {
+    binding.clear(this._handle)
+  }
+
+  free () {
+    if (this._handle) {
+      binding.free(this._handle)
+      this._handle = null
+    }
+  }
+}
+
+module.exports = { Index, binding }

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "bare-usearch",
+  "version": "0.1.0",
+  "description": "USearch vector similarity search bindings for Bare",
+  "main": "index.js",
+  "addon": true,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CameronTofer/bare-usearch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CameronTofer/bare-usearch/issues"
+  },
+  "homepage": "https://github.com/CameronTofer/bare-usearch",
+  "keywords": [
+    "usearch",
+    "vector",
+    "similarity",
+    "search",
+    "hnsw",
+    "bare",
+    "native"
+  ],
+  "imports": {
+    "fs": {
+      "bare": "bare-fs",
+      "default": "fs"
+    },
+    "fs/*": {
+      "bare": "bare-fs/*",
+      "default": "fs/*"
+    },
+    "path": {
+      "bare": "bare-path",
+      "default": "path"
+    },
+    "os": {
+      "bare": "bare-os",
+      "default": "os"
+    }
+  },
+  "engines": {
+    "bare": ">=1.16.0"
+  },
+  "files": [
+    "index.js",
+    "binding.js",
+    "binding.c",
+    "usearch_wrapper.cpp",
+    "prebuilds",
+    "CMakeLists.txt",
+    "vendor/usearch/c",
+    "vendor/usearch/include",
+    "vendor/usearch/fp16/include",
+    "vendor/usearch/VERSION"
+  ],
+  "scripts": {
+    "build": "bare-make generate && bare-make build && bare-make install",
+    "test": "npm run test:bare",
+    "test:bare": "brittle-bare test/*.js",
+    "test:node": "brittle test/*.js",
+    "clean": "rm -rf build prebuilds",
+    "update-usearch": "git submodule update --remote --recursive vendor/usearch"
+  },
+  "dependencies": {
+    "require-addon": "^1.0.0"
+  },
+  "devDependencies": {
+    "bare-compat-napi": "^1.3.5",
+    "bare-fs": "^4.5.3",
+    "bare-os": "^3.6.2",
+    "bare-path": "^3.0.0",
+    "brittle": "^3.19.1",
+    "cmake-bare": "^1.1.2",
+    "cmake-napi": "^1.2.1"
+  }
+}

package/usearch_wrapper.cpp

@@ -0,0 +1,164 @@
+// Wrapper that catches C++ exceptions and converts to C error strings
+// This prevents exceptions from escaping into the Bare runtime (compiled with -fno-exceptions)
+
+#include <cstring>
+#include <cstdlib>
+#include <exception>
+
+extern "C" {
+#include "usearch.h"
+}
+
+// Thread-local buffer for error messages
+static thread_local char error_buffer[256];
+
+static const char* capture_exception() {
+    try {
+        throw; // rethrow current exception
+    } catch (const std::exception& e) {
+        std::strncpy(error_buffer, e.what(), sizeof(error_buffer) - 1);
+        error_buffer[sizeof(error_buffer) - 1] = '\0';
+        return error_buffer;
+    } catch (...) {
+        return "Unknown C++ exception";
+    }
+}
+
+// Wrapped versions of usearch functions that catch exceptions
+
+extern "C" {
+
+USEARCH_EXPORT usearch_index_t usearch_init_safe(usearch_init_options_t* options, usearch_error_t* error) {
+    try {
+        return usearch_init(options, error);
+    } catch (...) {
+        *error = capture_exception();
+        return nullptr;
+    }
+}
+
+USEARCH_EXPORT void usearch_free_safe(usearch_index_t index, usearch_error_t* error) {
+    try {
+        usearch_free(index, error);
+    } catch (...) {
+        *error = capture_exception();
+    }
+}
+
+USEARCH_EXPORT size_t usearch_size_safe(usearch_index_t index, usearch_error_t* error) {
+    try {
+        return usearch_size(index, error);
+    } catch (...) {
+        *error = capture_exception();
+        return 0;
+    }
+}
+
+USEARCH_EXPORT size_t usearch_capacity_safe(usearch_index_t index, usearch_error_t* error) {
+    try {
+        return usearch_capacity(index, error);
+    } catch (...) {
+        *error = capture_exception();
+        return 0;
+    }
+}
+
+USEARCH_EXPORT size_t usearch_dimensions_safe(usearch_index_t index, usearch_error_t* error) {
+    try {
+        return usearch_dimensions(index, error);
+    } catch (...) {
+        *error = capture_exception();
+        return 0;
+    }
+}
+
+USEARCH_EXPORT void usearch_reserve_safe(usearch_index_t index, size_t capacity, usearch_error_t* error) {
+    try {
+        usearch_reserve(index, capacity, error);
+    } catch (...) {
+        *error = capture_exception();
+    }
+}
+
+USEARCH_EXPORT void usearch_add_safe(usearch_index_t index, usearch_key_t key, void const* vector, 
+                                      usearch_scalar_kind_t kind, usearch_error_t* error) {
+    try {
+        usearch_add(index, key, vector, kind, error);
+    } catch (...) {
+        *error = capture_exception();
+    }
+}
+
+USEARCH_EXPORT 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) {
+    try {
+        return usearch_search(index, query, kind, count, keys, distances, error);
+    } catch (...) {
+        *error = capture_exception();
+        return 0;
+    }
+}
+
+USEARCH_EXPORT size_t usearch_remove_safe(usearch_index_t index, usearch_key_t key, usearch_error_t* error) {
+    try {
+        return usearch_remove(index, key, error);
+    } catch (...) {
+        *error = capture_exception();
+        return 0;
+    }
+}
+
+USEARCH_EXPORT bool usearch_contains_safe(usearch_index_t index, usearch_key_t key, usearch_error_t* error) {
+    try {
+        return usearch_contains(index, key, error);
+    } catch (...) {
+        *error = capture_exception();
+        return false;
+    }
+}
+
+USEARCH_EXPORT 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) {
+    try {
+        return usearch_get(index, key, count, vector, kind, error);
+    } catch (...) {
+        *error = capture_exception();
+        return 0;
+    }
+}
+
+USEARCH_EXPORT void usearch_save_safe(usearch_index_t index, char const* path, usearch_error_t* error) {
+    try {
+        usearch_save(index, path, error);
+    } catch (...) {
+        *error = capture_exception();
+    }
+}
+
+USEARCH_EXPORT void usearch_load_safe(usearch_index_t index, char const* path, usearch_error_t* error) {
+    try {
+        usearch_load(index, path, error);
+    } catch (...) {
+        *error = capture_exception();
+    }
+}
+
+USEARCH_EXPORT void usearch_view_safe(usearch_index_t index, char const* path, usearch_error_t* error) {
+    try {
+        usearch_view(index, path, error);
+    } catch (...) {
+        *error = capture_exception();
+    }
+}
+
+USEARCH_EXPORT void usearch_clear_safe(usearch_index_t index, usearch_error_t* error) {
+    try {
+        usearch_clear(index, error);
+    } catch (...) {
+        *error = capture_exception();
+    }
+}
+
+} // extern "C"
+