usearch 2.17.0 → 2.19.4

package/include/usearch/index_dense.hpp

@@ -624,7 +624,7 @@ class index_dense_gt {
         }
         operator index_dense_gt&&() && {
             if (error)
-                __usearch_raise_runtime_error(error.what());
+                usearch_raise_runtime_error(error.what());
             return std::move(index);
         }
     };
@@ -757,39 +757,45 @@ class index_dense_gt {
     };
 
     // clang-format off
-    add_result_t add(vector_key_t key, b1x8_t const* vector, std::size_t thread = any_thread(), bool force_vector_copy = true) { return add_(key, vector, thread, force_vector_copy, casts_.from.b1x8); }
-    add_result_t add(vector_key_t key, i8_t const* vector, std::size_t thread = any_thread(), bool force_vector_copy = true) { return add_(key, vector, thread, force_vector_copy, casts_.from.i8); }
-    add_result_t add(vector_key_t key, f16_t const* vector, std::size_t thread = any_thread(), bool force_vector_copy = true) { return add_(key, vector, thread, force_vector_copy, casts_.from.f16); }
-    add_result_t add(vector_key_t key, f32_t const* vector, std::size_t thread = any_thread(), bool force_vector_copy = true) { return add_(key, vector, thread, force_vector_copy, casts_.from.f32); }
-    add_result_t add(vector_key_t key, f64_t const* vector, std::size_t thread = any_thread(), bool force_vector_copy = true) { return add_(key, vector, thread, force_vector_copy, casts_.from.f64); }
+    add_result_t add(vector_key_t key, b1x8_t const* vector, std::size_t thread = any_thread(), bool copy_vector = true) { return add_(key, vector, thread, copy_vector, casts_.from.b1x8); }
+    add_result_t add(vector_key_t key, i8_t const* vector, std::size_t thread = any_thread(), bool copy_vector = true) { return add_(key, vector, thread, copy_vector, casts_.from.i8); }
+    add_result_t add(vector_key_t key, f16_t const* vector, std::size_t thread = any_thread(), bool copy_vector = true) { return add_(key, vector, thread, copy_vector, casts_.from.f16); }
+    add_result_t add(vector_key_t key, bf16_t const* vector, std::size_t thread = any_thread(), bool copy_vector = true) { return add_(key, vector, thread, copy_vector, casts_.from.bf16); }
+    add_result_t add(vector_key_t key, f32_t const* vector, std::size_t thread = any_thread(), bool copy_vector = true) { return add_(key, vector, thread, copy_vector, casts_.from.f32); }
+    add_result_t add(vector_key_t key, f64_t const* vector, std::size_t thread = any_thread(), bool copy_vector = true) { return add_(key, vector, thread, copy_vector, casts_.from.f64); }
 
     search_result_t search(b1x8_t const* vector, std::size_t wanted, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, dummy_predicate_t {}, thread, exact, casts_.from.b1x8); }
     search_result_t search(i8_t const* vector, std::size_t wanted, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, dummy_predicate_t {}, thread, exact, casts_.from.i8); }
     search_result_t search(f16_t const* vector, std::size_t wanted, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, dummy_predicate_t {}, thread, exact, casts_.from.f16); }
+    search_result_t search(bf16_t const* vector, std::size_t wanted, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, dummy_predicate_t {}, thread, exact, casts_.from.bf16); }
     search_result_t search(f32_t const* vector, std::size_t wanted, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, dummy_predicate_t {}, thread, exact, casts_.from.f32); }
     search_result_t search(f64_t const* vector, std::size_t wanted, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, dummy_predicate_t {}, thread, exact, casts_.from.f64); }
 
     template <typename predicate_at> search_result_t filtered_search(b1x8_t const* vector, std::size_t wanted, predicate_at&& predicate, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, std::forward<predicate_at>(predicate), thread, exact, casts_.from.b1x8); }
     template <typename predicate_at> search_result_t filtered_search(i8_t const* vector, std::size_t wanted, predicate_at&& predicate, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, std::forward<predicate_at>(predicate), thread, exact, casts_.from.i8); }
     template <typename predicate_at> search_result_t filtered_search(f16_t const* vector, std::size_t wanted, predicate_at&& predicate, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, std::forward<predicate_at>(predicate), thread, exact, casts_.from.f16); }
+    template <typename predicate_at> search_result_t filtered_search(bf16_t const* vector, std::size_t wanted, predicate_at&& predicate, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, std::forward<predicate_at>(predicate), thread, exact, casts_.from.bf16); }
     template <typename predicate_at> search_result_t filtered_search(f32_t const* vector, std::size_t wanted, predicate_at&& predicate, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, std::forward<predicate_at>(predicate), thread, exact, casts_.from.f32); }
     template <typename predicate_at> search_result_t filtered_search(f64_t const* vector, std::size_t wanted, predicate_at&& predicate, std::size_t thread = any_thread(), bool exact = false) const { return search_(vector, wanted, std::forward<predicate_at>(predicate), thread, exact, casts_.from.f64); }
 
     std::size_t get(vector_key_t key, b1x8_t* vector, std::size_t vectors_count = 1) const { return get_(key, vector, vectors_count, casts_.to.b1x8); }
     std::size_t get(vector_key_t key, i8_t* vector, std::size_t vectors_count = 1) const { return get_(key, vector, vectors_count, casts_.to.i8); }
     std::size_t get(vector_key_t key, f16_t* vector, std::size_t vectors_count = 1) const { return get_(key, vector, vectors_count, casts_.to.f16); }
+    std::size_t get(vector_key_t key, bf16_t* vector, std::size_t vectors_count = 1) const { return get_(key, vector, vectors_count, casts_.to.bf16); }
     std::size_t get(vector_key_t key, f32_t* vector, std::size_t vectors_count = 1) const { return get_(key, vector, vectors_count, casts_.to.f32); }
     std::size_t get(vector_key_t key, f64_t* vector, std::size_t vectors_count = 1) const { return get_(key, vector, vectors_count, casts_.to.f64); }
 
     cluster_result_t cluster(b1x8_t const* vector, std::size_t level, std::size_t thread = any_thread()) const { return cluster_(vector, level, thread, casts_.from.b1x8); }
     cluster_result_t cluster(i8_t const* vector, std::size_t level, std::size_t thread = any_thread()) const { return cluster_(vector, level, thread, casts_.from.i8); }
     cluster_result_t cluster(f16_t const* vector, std::size_t level, std::size_t thread = any_thread()) const { return cluster_(vector, level, thread, casts_.from.f16); }
+    cluster_result_t cluster(bf16_t const* vector, std::size_t level, std::size_t thread = any_thread()) const { return cluster_(vector, level, thread, casts_.from.bf16); }
     cluster_result_t cluster(f32_t const* vector, std::size_t level, std::size_t thread = any_thread()) const { return cluster_(vector, level, thread, casts_.from.f32); }
     cluster_result_t cluster(f64_t const* vector, std::size_t level, std::size_t thread = any_thread()) const { return cluster_(vector, level, thread, casts_.from.f64); }
 
     aggregated_distances_t distance_between(vector_key_t key, b1x8_t const* vector, std::size_t thread = any_thread()) const { return distance_between_(key, vector, thread, casts_.to.b1x8); }
     aggregated_distances_t distance_between(vector_key_t key, i8_t const* vector, std::size_t thread = any_thread()) const { return distance_between_(key, vector, thread, casts_.to.i8); }
     aggregated_distances_t distance_between(vector_key_t key, f16_t const* vector, std::size_t thread = any_thread()) const { return distance_between_(key, vector, thread, casts_.to.f16); }
+    aggregated_distances_t distance_between(vector_key_t key, bf16_t const* vector, std::size_t thread = any_thread()) const { return distance_between_(key, vector, thread, casts_.to.bf16); }
     aggregated_distances_t distance_between(vector_key_t key, f32_t const* vector, std::size_t thread = any_thread()) const { return distance_between_(key, vector, thread, casts_.to.f32); }
     aggregated_distances_t distance_between(vector_key_t key, f64_t const* vector, std::size_t thread = any_thread()) const { return distance_between_(key, vector, thread, casts_.to.f64); }
     // clang-format on
@@ -940,7 +946,7 @@ class index_dense_gt {
 
     void reserve(index_limits_t limits) {
         if (!try_reserve(limits))
-            __usearch_raise_runtime_error("failed to reserve memory");
+            usearch_raise_runtime_error("failed to reserve memory");
     }
 
     /**
@@ -1070,8 +1076,9 @@ class index_dense_gt {
 
     /**
      *  @brief Parses the index from file to RAM.
-     *  @param[in] path The path to the file.
+     *  @param[in] input The input stream to read from.
      *  @param[in] config Configuration parameters for imports.
+     *  @param[in] progress Callback to report the execution progress.
      *  @return Outcome descriptor explicitly convertible to boolean.
      */
     template <typename input_callback_at, typename progress_at = dummy_progress_t>
@@ -1141,7 +1148,9 @@ class index_dense_gt {
 
             config_.multi = head.multi;
             metric_ = metric_t::builtin(head.dimensions, head.kind_metric, head.kind_scalar);
-            cast_buffer_ = cast_buffer_t(available_threads_.size() * metric_.bytes_per_vector());
+            // available_threads_.size() will be updated to old_limits.threads() later in this
+            // method, so use that as the number of threads to prepare for.
+            cast_buffer_ = cast_buffer_t(old_limits.threads() * metric_.bytes_per_vector());
             if (!cast_buffer_)
                 return result.failed("Failed to allocate memory for the casts");
             casts_ = casts_punned_t::make(head.kind_scalar);
@@ -1180,8 +1189,10 @@ class index_dense_gt {
 
     /**
      *  @brief Parses the index from file, without loading it into RAM.
-     *  @param[in] path The path to the file.
+     *  @param[in] file The input file to read from.
+     *  @param[in] offset The offset in the file to start reading from.
      *  @param[in] config Configuration parameters for imports.
+     *  @param[in] progress Callback to report the execution progress.
      *  @return Outcome descriptor explicitly convertible to boolean.
      */
     template <typename progress_at = dummy_progress_t>
@@ -1253,7 +1264,9 @@ class index_dense_gt {
 
             config_.multi = head.multi;
             metric_ = metric_t::builtin(head.dimensions, head.kind_metric, head.kind_scalar);
-            cast_buffer_ = cast_buffer_t(available_threads_.size() * metric_.bytes_per_vector());
+            // available_threads_.size() will be updated to old_limits.threads() later in this
+            // method, so use that as the number of threads to prepare for.
+            cast_buffer_ = cast_buffer_t(old_limits.threads() * metric_.bytes_per_vector());
             if (!cast_buffer_)
                 return result.failed("Failed to allocate memory for the casts");
             casts_ = casts_punned_t::make(head.kind_scalar);
@@ -1301,8 +1314,9 @@ class index_dense_gt {
 
     /**
      *  @brief Saves the index to a file.
-     *  @param[in] path The path to the file.
+     *  @param[in] file The output file to write to.
      *  @param[in] config Configuration parameters for exports.
+     *  @param[in] progress Callback to report the execution progress.
      *  @return Outcome descriptor explicitly convertible to boolean.
      */
     template <typename progress_at = dummy_progress_t>
@@ -1356,8 +1370,9 @@ class index_dense_gt {
 
     /**
      *  @brief Parses the index from file to RAM.
-     *  @param[in] path The path to the file.
+     *  @param[in] file The input file to read from.
      *  @param[in] config Configuration parameters for imports.
+     *  @param[in] progress Progress callback.
      *  @return Outcome descriptor explicitly convertible to boolean.
      */
     template <typename progress_at = dummy_progress_t>
@@ -1694,12 +1709,12 @@ class index_dense_gt {
     compaction_result_t isolate(executor_at&& executor = executor_at{}, progress_at&& progress = progress_at{}) {
         compaction_result_t result;
         std::atomic<std::size_t> pruned_edges;
-        auto disallow = [&](member_cref_t const& member) noexcept {
+        auto allow = [&](member_cref_t const& member) noexcept {
             bool freed = member.key == free_key_;
             pruned_edges += freed;
-            return freed;
+            return !freed;
         };
-        typed_->isolate(disallow, std::forward<executor_at>(executor), std::forward<progress_at>(progress));
+        typed_->isolate(allow, std::forward<executor_at>(executor), std::forward<progress_at>(progress));
         result.pruned_edges = pruned_edges;
         return result;
     }
@@ -1959,6 +1974,7 @@ class index_dense_gt {
 
         result.computed_distances = computed_distances;
         result.visited_members = visited_members;
+        result.clusters = unique_clusters;
 
         (void)progress;
         return result;
@@ -1986,14 +2002,13 @@ class index_dense_gt {
     template <typename scalar_at>
     add_result_t add_(                             //
         vector_key_t key, scalar_at const* vector, //
-        std::size_t thread, bool force_vector_copy, cast_punned_t const& cast) {
+        std::size_t thread, bool copy_vector, cast_punned_t const& cast) {
 
         if (!multi() && config().enable_key_lookups && contains(key))
             return add_result_t{}.failed("Duplicate keys not allowed in high-level wrappers");
 
         // Cast the vector, if needed for compatibility with `metric_`
         thread_lock_t lock = thread_lock_(thread);
-        bool copy_vector = !config_.exclude_vectors || force_vector_copy;
         byte_t const* vector_data = reinterpret_cast<byte_t const*>(vector);
         {
             byte_t* casted_data = cast_buffer_.data() + metric_.bytes_per_vector() * lock.thread_id;
@@ -2255,4 +2270,4 @@ static join_result_t join(                                    //
 }
 
 } // namespace usearch
-} // namespace unum
+} // namespace unum

package/include/usearch/index_plugins.hpp

@@ -483,7 +483,7 @@ class f16_bits_t {
     inline operator float() const noexcept { return f16_to_f32(uint16_); }
     inline explicit operator bool() const noexcept { return f16_to_f32(uint16_) > 0.5f; }
 
-    inline f16_bits_t(std::int8_t v) noexcept : uint16_(f32_to_f16(v)) {}
+    inline f16_bits_t(int v) noexcept : uint16_(f32_to_f16(v)) {}
     inline f16_bits_t(bool v) noexcept : uint16_(f32_to_f16(v)) {}
     inline f16_bits_t(float v) noexcept : uint16_(f32_to_f16(v)) {}
     inline f16_bits_t(double v) noexcept : uint16_(f32_to_f16(static_cast<float>(v))) {}
@@ -524,6 +524,11 @@ class f16_bits_t {
     }
 };
 
+#if USEARCH_USE_OPENMP
+#pragma omp declare reduction(+ : unum::usearch::f16_bits_t : omp_out = omp_out + omp_in)                              \
+    initializer(omp_priv = unum::usearch::f16_bits_t())
+#endif
+
 /**
  *  @brief  Numeric type for brain-floating point half-precision floating point.
  *          If hardware support isn't available, falls back to a hardware
@@ -542,7 +547,7 @@ class bf16_bits_t {
     inline operator float() const noexcept { return bf16_to_f32(uint16_); }
     inline explicit operator bool() const noexcept { return bf16_to_f32(uint16_) > 0.5f; }
 
-    inline bf16_bits_t(std::int8_t v) noexcept : uint16_(f32_to_bf16(v)) {}
+    inline bf16_bits_t(int v) noexcept : uint16_(f32_to_bf16(v)) {}
     inline bf16_bits_t(bool v) noexcept : uint16_(f32_to_bf16(v)) {}
     inline bf16_bits_t(float v) noexcept : uint16_(f32_to_bf16(v)) {}
     inline bf16_bits_t(double v) noexcept : uint16_(f32_to_bf16(static_cast<float>(v))) {}
@@ -581,8 +586,18 @@ class bf16_bits_t {
         uint16_ = f32_to_bf16(v / bf16_to_f32(uint16_));
         return *this;
     }
+
+    inline bf16_bits_t& operator=(float v) noexcept {
+        uint16_ = f32_to_bf16(v);
+        return *this;
+    }
 };
 
+#if USEARCH_USE_OPENMP
+#pragma omp declare reduction(+ : unum::usearch::bf16_bits_t : omp_out = omp_out + omp_in)                             \
+    initializer(omp_priv = unum::usearch::bf16_bits_t())
+#endif
+
 /**
  *  @brief  An STL-based executor or a "thread-pool" for parallel execution.
  *          Isn't efficient for small batches, as it recreates the threads on every call.
@@ -760,7 +775,9 @@ class executor_openmp_t {
     template <typename thread_aware_function_at>
     void parallel(thread_aware_function_at&& thread_aware_function) noexcept(false) {
 #pragma omp parallel
-        { thread_aware_function(omp_get_thread_num()); }
+        {
+            thread_aware_function(omp_get_thread_num());
+        }
     }
 };
 
@@ -1223,6 +1240,7 @@ struct casts_punned_t {
         cast_punned_t b1x8{};
         cast_punned_t i8{};
         cast_punned_t f16{};
+        cast_punned_t bf16{};
         cast_punned_t f32{};
         cast_punned_t f64{};
 
@@ -1231,7 +1249,7 @@ struct casts_punned_t {
             case scalar_kind_t::f64_k: return f64;
             case scalar_kind_t::f32_k: return f32;
             case scalar_kind_t::f16_k: return f16;
-            case scalar_kind_t::bf16_k: return f16;
+            case scalar_kind_t::bf16_k: return bf16;
             case scalar_kind_t::i8_k: return i8;
             case scalar_kind_t::b1x8_k: return b1x8;
             default: return nullptr;
@@ -1246,12 +1264,14 @@ struct casts_punned_t {
         result.from.b1x8 = &cast_gt<b1x8_t, scalar_at>::try_;
         result.from.i8 = &cast_gt<i8_t, scalar_at>::try_;
         result.from.f16 = &cast_gt<f16_t, scalar_at>::try_;
+        result.from.bf16 = &cast_gt<bf16_t, scalar_at>::try_;
         result.from.f32 = &cast_gt<f32_t, scalar_at>::try_;
         result.from.f64 = &cast_gt<f64_t, scalar_at>::try_;
 
         result.to.b1x8 = &cast_gt<scalar_at, b1x8_t>::try_;
         result.to.i8 = &cast_gt<scalar_at, i8_t>::try_;
         result.to.f16 = &cast_gt<scalar_at, f16_t>::try_;
+        result.to.bf16 = &cast_gt<scalar_at, bf16_t>::try_;
         result.to.f32 = &cast_gt<scalar_at, f32_t>::try_;
         result.to.f64 = &cast_gt<scalar_at, f64_t>::try_;
 
@@ -1283,6 +1303,8 @@ struct casts_punned_t {
 
 /**
  *  @brief  Inner (Dot) Product distance.
+ *          Vectors should be normalized to unit length,
+ *          otherwise `::metric_cos_gt` should be used instead.
  */
 template <typename scalar_at = float, typename result_at = scalar_at> struct metric_ip_gt {
     using scalar_t = scalar_at;
@@ -2566,7 +2588,7 @@ class flat_hash_multi_set_gt {
         // Allocate new memory
         data_ = (char*)allocator_t{}.allocate(other.buckets_ * bytes_per_bucket());
         if (!data_)
-            __usearch_raise_runtime_error("failed memory allocation");
+            usearch_raise_runtime_error("failed memory allocation");
 
         // Copy metadata
         buckets_ = other.buckets_;
@@ -2606,7 +2628,7 @@ class flat_hash_multi_set_gt {
         // Allocate new memory
         data_ = (char*)allocator_t{}.allocate(other.buckets_ * bytes_per_bucket());
         if (!data_)
-            __usearch_raise_runtime_error("failed memory allocation");
+            usearch_raise_runtime_error("failed memory allocation");
 
         // Copy metadata
         buckets_ = other.buckets_;
@@ -2979,7 +3001,7 @@ class flat_hash_multi_set_gt {
 
     void reserve(std::size_t capacity) {
         if (!try_reserve(capacity))
-            __usearch_raise_runtime_error("failed to reserve memory");
+            usearch_raise_runtime_error("failed to reserve memory");
     }
 
     bool try_emplace(element_t const& element) noexcept {

package/javascript/README.md

@@ -10,12 +10,6 @@ For Node.js environments, install USearch using `npm`:
 npm install usearch
 ```
 
-For front-end applications using WASM, use the Wasmer package manager:
-
-```sh
-wasmer install unum/usearch
-```
-
 ## Quickstart
 
 Create an index, add vectors, and perform searches with ease:
@@ -78,6 +72,14 @@ const batchResults = index.search(vectors, 2);
 const firstMatch = batchResults.get(0);
 ```
 
+Multi-threading is supported for batch operations:
+
+```js
+const threads_count = 0; // Zero for auto-detection or pass an unsigned integer
+index.add(keys, vectors, threads_count);
+const batchResults = index.search(vectors, 2, threads_count);
+```
+
 ## Index Introspection
 
 Inspect and interact with the index:

package/javascript/dist/cjs/usearch.d.ts

@@ -115,10 +115,12 @@ export declare class Index {
      *        If a single key is provided, it is associated with all provided vectors.
      * @param {Float32Array|Float64Array|Int8Array} vectors - Input matrix representing vectors,
      *        matrix of size n * d, where n is the number of vectors, and d is their dimensionality.
+     * @param {number} [threads=0] - Optional, default is 0. Number of threads to use for indexing.
+     *        If set to 0, the number of threads is determined automatically.
      * @throws Will throw an error if the length of keys doesn't match the number of vectors
      *         or if it's not a single key.
      */
-    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector): void;
+    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector, threads?: number): void;
     /**
      * Perform a k-nearest neighbor search on the index.
      *
@@ -136,11 +138,12 @@ export declare class Index {
      *
      * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of TypedArray.
      * @param {number} k - The number of nearest neighbors to search for each query vector.
+     * @param {number} [threads=0] - Optional, default is 0. Number of threads to use for searching. If set to 0, the number of threads is determined automatically.
      * @return {Matches|BatchMatches} - Search results for one or more queries, containing keys, distances, and counts of the matches found.
      * @throws Will throw an error if `k` is not a positive integer or if the size of the vectors is not a multiple of dimensions.
      * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of TypedArray) or if its flattened size is not a multiple of dimensions.
      */
-    search(vectors: VectorOrMatrix, k: number): Matches | BatchMatches;
+    search(vectors: VectorOrMatrix, k: number, threads?: number): Matches | BatchMatches;
     /**
      * Verifies the presence of one or more keys in the index.
      *
@@ -218,6 +221,7 @@ export declare class Index {
  * @param {number} dimensions - The dimensionality of the vectors in both the dataset and the queries. It defines the number of elements in each vector.
  * @param {number} count - The number of nearest neighbors to return for each query. If the dataset contains fewer vectors than the specified count, the result will contain only the available vectors.
  * @param {MetricKind} metric - The distance metric to be used for the search.
+ * @param {number} [threads=0] - Optional, default is 0. The number of threads to use for the search. If set to 0, the number of threads is determined automatically.
  * @return {Matches|BatchMatches} - Returns a `Matches` or `BatchMatches` object containing the results of the search.
  * @throws Will throw an error if `dimensions` and `count` are not positive integers.
  * @throws Will throw an error if `metric` is not a valid MetricKind.
@@ -231,15 +235,16 @@ export declare class Index {
  * const dimensions = 2; // The number of elements in each vector.
  * const count = 1; // The number of nearest neighbors to return for each query.
  * const metric = MetricKind.IP; // Using the Inner Product distance metric.
+ * const threads = 0; // How many threads to use to perform the search.
  *
- * const result = exactSearch(dataset, queries, dimensions, count, metric);
+ * const result = exactSearch(dataset, queries, dimensions, count, metric, threads);
  * // result might be:
  * // {
  * //    keys: BigUint64Array [ 1n ],
  * //    distances: Float32Array [ some_value ],
  * // }
  */
-declare function exactSearch(dataset: VectorOrMatrix, queries: VectorOrMatrix, dimensions: number, count: number, metric: MetricKind): Matches | BatchMatches;
+export declare function exactSearch(dataset: VectorOrMatrix, queries: VectorOrMatrix, dimensions: number, count: number, metric: MetricKind, threads?: number): Matches | BatchMatches;
 declare const usearch: {
     Index: typeof Index;
     MetricKind: typeof MetricKind;

package/javascript/dist/cjs/usearch.js

@@ -38,7 +38,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 var _Index_compiledIndex;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Index = exports.BatchMatches = exports.Matches = exports.ScalarKind = exports.MetricKind = void 0;
+exports.exactSearch = exports.Index = exports.BatchMatches = exports.Matches = exports.ScalarKind = exports.MetricKind = void 0;
 const node_gyp_build_1 = __importDefault(require("node-gyp-build"));
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
@@ -266,10 +266,12 @@ class Index {
      *        If a single key is provided, it is associated with all provided vectors.
      * @param {Float32Array|Float64Array|Int8Array} vectors - Input matrix representing vectors,
      *        matrix of size n * d, where n is the number of vectors, and d is their dimensionality.
+     * @param {number} [threads=0] - Optional, default is 0. Number of threads to use for indexing.
+     *        If set to 0, the number of threads is determined automatically.
      * @throws Will throw an error if the length of keys doesn't match the number of vectors
      *         or if it's not a single key.
      */
-    add(keys, vectors) {
+    add(keys, vectors, threads = 0) {
         let normalizedKeys = normalizeKeys(keys);
         let normalizedVectors = normalizeVectors(vectors, __classPrivateFieldGet(this, _Index_compiledIndex, "f").dimensions());
         let countVectors = normalizedVectors.length / __classPrivateFieldGet(this, _Index_compiledIndex, "f").dimensions();
@@ -281,8 +283,11 @@ class Index {
         else if (normalizedKeys.length !== countVectors) {
             throw new Error(`The length of keys (${normalizedKeys.length}) must match the number of vectors (${countVectors}) or be a single key.`);
         }
+        if ((!Number.isNaN(threads) && typeof threads !== "number") || threads < 0) {
+            throw new Error("`threads` must be a non-negative integer representing the number of threads to use for searching.");
+        }
         // Call the compiled method
-        __classPrivateFieldGet(this, _Index_compiledIndex, "f").add(normalizedKeys, normalizedVectors);
+        __classPrivateFieldGet(this, _Index_compiledIndex, "f").add(normalizedKeys, normalizedVectors, threads);
     }
     /**
      * Perform a k-nearest neighbor search on the index.
@@ -301,17 +306,21 @@ class Index {
      *
      * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of TypedArray.
      * @param {number} k - The number of nearest neighbors to search for each query vector.
+     * @param {number} [threads=0] - Optional, default is 0. Number of threads to use for searching. If set to 0, the number of threads is determined automatically.
      * @return {Matches|BatchMatches} - Search results for one or more queries, containing keys, distances, and counts of the matches found.
      * @throws Will throw an error if `k` is not a positive integer or if the size of the vectors is not a multiple of dimensions.
      * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of TypedArray) or if its flattened size is not a multiple of dimensions.
      */
-    search(vectors, k) {
+    search(vectors, k, threads = 0) {
         if ((!Number.isNaN(k) && typeof k !== "number") || k <= 0) {
             throw new Error("`k` must be a positive integer representing the number of nearest neighbors to search for.");
         }
+        if ((!Number.isNaN(threads) && typeof threads !== "number") || threads < 0) {
+            throw new Error("`threads` must be a non-negative integer representing the number of threads to use for searching.");
+        }
         const normalizedVectors = normalizeVectors(vectors, __classPrivateFieldGet(this, _Index_compiledIndex, "f").dimensions());
         // Call the compiled method and create Matches or BatchMatches object with the result
-        const result = __classPrivateFieldGet(this, _Index_compiledIndex, "f").search(normalizedVectors, k);
+        const result = __classPrivateFieldGet(this, _Index_compiledIndex, "f").search(normalizedVectors, k, threads);
         const countInQueries = normalizedVectors.length / Number(__classPrivateFieldGet(this, _Index_compiledIndex, "f").dimensions());
         const batchMatches = new BatchMatches(...result, k);
         if (countInQueries === 1) {
@@ -441,6 +450,7 @@ _Index_compiledIndex = new WeakMap();
  * @param {number} dimensions - The dimensionality of the vectors in both the dataset and the queries. It defines the number of elements in each vector.
  * @param {number} count - The number of nearest neighbors to return for each query. If the dataset contains fewer vectors than the specified count, the result will contain only the available vectors.
  * @param {MetricKind} metric - The distance metric to be used for the search.
+ * @param {number} [threads=0] - Optional, default is 0. The number of threads to use for the search. If set to 0, the number of threads is determined automatically.
  * @return {Matches|BatchMatches} - Returns a `Matches` or `BatchMatches` object containing the results of the search.
  * @throws Will throw an error if `dimensions` and `count` are not positive integers.
  * @throws Will throw an error if `metric` is not a valid MetricKind.
@@ -454,21 +464,25 @@ _Index_compiledIndex = new WeakMap();
  * const dimensions = 2; // The number of elements in each vector.
  * const count = 1; // The number of nearest neighbors to return for each query.
  * const metric = MetricKind.IP; // Using the Inner Product distance metric.
+ * const threads = 0; // How many threads to use to perform the search.
  *
- * const result = exactSearch(dataset, queries, dimensions, count, metric);
+ * const result = exactSearch(dataset, queries, dimensions, count, metric, threads);
  * // result might be:
  * // {
  * //    keys: BigUint64Array [ 1n ],
  * //    distances: Float32Array [ some_value ],
  * // }
  */
-function exactSearch(dataset, queries, dimensions, count, metric) {
+function exactSearch(dataset, queries, dimensions, count, metric, threads = 0) {
     // Validate and normalize the dimensions and count
     dimensions = Number(dimensions);
     count = Number(count);
     if (count <= 0 || dimensions <= 0) {
         throw new Error("Dimensions and count must be positive integers.");
     }
+    if ((!Number.isNaN(threads) && typeof threads !== "number") || threads < 0) {
+        throw new Error("`threads` must be a non-negative integer representing the number of threads to use for searching.");
+    }
     // Validate metric
     if (!Object.values(MetricKind).includes(metric)) {
         throw new Error(`Invalid metric: ${metric}. It must be one of: ${Object.values(MetricKind).join(", ")}`);
@@ -489,7 +503,7 @@ function exactSearch(dataset, queries, dimensions, count, metric) {
         throw new Error("Count must be equal or smaller than the number of vectors in the dataset.");
     }
     // Call the compiled function with the normalized input
-    const result = compiled.exactSearch(dataset, queries, dimensions, count, metric);
+    const result = compiled.exactSearch(dataset, queries, dimensions, count, metric, threads);
     // Create and return a Matches or BatchMatches object with the result
     if (countInQueries == 1) {
         return new Matches(result[0], result[1]);
@@ -498,6 +512,7 @@ function exactSearch(dataset, queries, dimensions, count, metric) {
         return new BatchMatches(...result, count);
     }
 }
+exports.exactSearch = exactSearch;
 const usearch = {
     Index,
     MetricKind,

package/javascript/dist/esm/usearch.d.ts

@@ -115,10 +115,12 @@ export declare class Index {
      *        If a single key is provided, it is associated with all provided vectors.
      * @param {Float32Array|Float64Array|Int8Array} vectors - Input matrix representing vectors,
      *        matrix of size n * d, where n is the number of vectors, and d is their dimensionality.
+     * @param {number} [threads=0] - Optional, default is 0. Number of threads to use for indexing.
+     *        If set to 0, the number of threads is determined automatically.
      * @throws Will throw an error if the length of keys doesn't match the number of vectors
      *         or if it's not a single key.
      */
-    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector): void;
+    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector, threads?: number): void;
     /**
      * Perform a k-nearest neighbor search on the index.
      *
@@ -136,11 +138,12 @@ export declare class Index {
      *
      * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of TypedArray.
      * @param {number} k - The number of nearest neighbors to search for each query vector.
+     * @param {number} [threads=0] - Optional, default is 0. Number of threads to use for searching. If set to 0, the number of threads is determined automatically.
      * @return {Matches|BatchMatches} - Search results for one or more queries, containing keys, distances, and counts of the matches found.
      * @throws Will throw an error if `k` is not a positive integer or if the size of the vectors is not a multiple of dimensions.
      * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of TypedArray) or if its flattened size is not a multiple of dimensions.
      */
-    search(vectors: VectorOrMatrix, k: number): Matches | BatchMatches;
+    search(vectors: VectorOrMatrix, k: number, threads?: number): Matches | BatchMatches;
     /**
      * Verifies the presence of one or more keys in the index.
      *
@@ -218,6 +221,7 @@ export declare class Index {
  * @param {number} dimensions - The dimensionality of the vectors in both the dataset and the queries. It defines the number of elements in each vector.
  * @param {number} count - The number of nearest neighbors to return for each query. If the dataset contains fewer vectors than the specified count, the result will contain only the available vectors.
  * @param {MetricKind} metric - The distance metric to be used for the search.
+ * @param {number} [threads=0] - Optional, default is 0. The number of threads to use for the search. If set to 0, the number of threads is determined automatically.
  * @return {Matches|BatchMatches} - Returns a `Matches` or `BatchMatches` object containing the results of the search.
  * @throws Will throw an error if `dimensions` and `count` are not positive integers.
  * @throws Will throw an error if `metric` is not a valid MetricKind.
@@ -231,15 +235,16 @@ export declare class Index {
  * const dimensions = 2; // The number of elements in each vector.
  * const count = 1; // The number of nearest neighbors to return for each query.
  * const metric = MetricKind.IP; // Using the Inner Product distance metric.
+ * const threads = 0; // How many threads to use to perform the search.
  *
- * const result = exactSearch(dataset, queries, dimensions, count, metric);
+ * const result = exactSearch(dataset, queries, dimensions, count, metric, threads);
  * // result might be:
  * // {
  * //    keys: BigUint64Array [ 1n ],
  * //    distances: Float32Array [ some_value ],
  * // }
  */
-declare function exactSearch(dataset: VectorOrMatrix, queries: VectorOrMatrix, dimensions: number, count: number, metric: MetricKind): Matches | BatchMatches;
+export declare function exactSearch(dataset: VectorOrMatrix, queries: VectorOrMatrix, dimensions: number, count: number, metric: MetricKind, threads?: number): Matches | BatchMatches;
 declare const usearch: {
     Index: typeof Index;
     MetricKind: typeof MetricKind;