usearch 2.10.5 → 2.11.1

package/include/usearch/index_dense.hpp

@@ -604,11 +604,17 @@ class index_dense_gt {
     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); }
 
-    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, 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, 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, thread, exact, casts_.from_f16); }
-    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, 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, thread, exact, 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(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(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); }
@@ -708,7 +714,9 @@ class index_dense_gt {
         cluster_config.thread = lock.thread_id;
         cluster_config.expansion = config_.expansion_search;
         metric_proxy_t metric{*this};
-        auto allow = [=](member_cref_t const& member) noexcept { return member.key != free_key_; };
+        auto allow = [free_key_ = this->free_key_](member_cref_t const& member) noexcept {
+            return member.key != free_key_;
+        };
 
         // Find the closest cluster for any vector under that key.
         while (key_range.first != key_range.second) {
@@ -734,6 +742,11 @@ class index_dense_gt {
             unique_lock_t lock(slot_lookup_mutex_);
             slot_lookup_.reserve(limits.members);
             vectors_lookup_.resize(limits.members);
+
+            // During reserve, no insertions may be happening, so we can safely overwrite the whole collection.
+            std::unique_lock<std::mutex> available_threads_lock(available_threads_mutex_);
+            available_threads_.resize(limits.threads());
+            std::iota(available_threads_.begin(), available_threads_.end(), 0ul);
         }
         return typed_->reserve(limits);
     }
@@ -930,7 +943,7 @@ class index_dense_gt {
                 return result.failed("Slot type doesn't match, consider rebuilding");
 
             config_.multi = head.multi;
-            metric_ = metric_t(head.dimensions, head.kind_metric, head.kind_scalar);
+            metric_ = metric_t::builtin(head.dimensions, head.kind_metric, head.kind_scalar);
             cast_buffer_.resize(available_threads_.size() * metric_.bytes_per_vector());
             casts_ = make_casts_(head.kind_scalar);
         }
@@ -1016,7 +1029,7 @@ class index_dense_gt {
                 return result.failed("Slot type doesn't match, consider rebuilding");
 
             config_.multi = head.multi;
-            metric_ = metric_t(head.dimensions, head.kind_metric, head.kind_scalar);
+            metric_ = metric_t::builtin(head.dimensions, head.kind_metric, head.kind_scalar);
             cast_buffer_.resize(available_threads_.size() * metric_.bytes_per_vector());
             casts_ = make_casts_(head.kind_scalar);
             offset += sizeof(buffer);
@@ -1767,10 +1780,9 @@ class index_dense_gt {
                    : typed_->add(key, vector_data, metric, update_config, on_success);
     }
 
-    template <typename scalar_at>
-    search_result_t search_(                         //
-        scalar_at const* vector, std::size_t wanted, //
-        std::size_t thread, bool exact, cast_t const& cast) const {
+    template <typename scalar_at, typename predicate_at>
+    search_result_t search_(scalar_at const* vector, std::size_t wanted, predicate_at&& predicate, std::size_t thread,
+                            bool exact, cast_t const& cast) const {
 
         // Cast the vector, if needed for compatibility with `metric_`
         thread_lock_t lock = thread_lock_(thread);
@@ -1787,8 +1799,17 @@ class index_dense_gt {
         search_config.expansion = config_.expansion_search;
         search_config.exact = exact;
 
-        auto allow = [=](member_cref_t const& member) noexcept { return member.key != free_key_; };
-        return typed_->search(vector_data, wanted, metric_proxy_t{*this}, search_config, allow);
+        if (std::is_same<typename std::decay<predicate_at>::type, dummy_predicate_t>::value) {
+            auto allow = [free_key_ = this->free_key_](member_cref_t const& member) noexcept {
+                return member.key != free_key_;
+            };
+            return typed_->search(vector_data, wanted, metric_proxy_t{*this}, search_config, allow);
+        } else {
+            auto allow = [free_key_ = this->free_key_, &predicate](member_cref_t const& member) noexcept {
+                return member.key != free_key_ && predicate(member.key);
+            };
+            return typed_->search(vector_data, wanted, metric_proxy_t{*this}, search_config, allow);
+        }
     }
 
     template <typename scalar_at>
@@ -1810,7 +1831,9 @@ class index_dense_gt {
         cluster_config.thread = lock.thread_id;
         cluster_config.expansion = config_.expansion_search;
 
-        auto allow = [=](member_cref_t const& member) noexcept { return member.key != free_key_; };
+        auto allow = [free_key_ = this->free_key_](member_cref_t const& member) noexcept {
+            return member.key != free_key_;
+        };
         return typed_->cluster(vector_data, level, metric_proxy_t{*this}, cluster_config, allow);
     }
 

package/include/usearch/index_plugins.hpp

@@ -1320,6 +1320,7 @@ using span_punned_t = span_gt<byte_t const>;
 enum class metric_punned_signature_t {
     array_array_k = 0,
     array_array_size_k,
+    array_array_state_k,
 };
 
 /**
@@ -1339,12 +1340,14 @@ class metric_punned_t {
     using metric_array_array_t = result_t (*)(uptr_t, uptr_t);
     /// Distance function that takes two arrays and their length and returns a scalar.
     using metric_array_array_size_t = result_t (*)(uptr_t, uptr_t, uptr_t);
+    /// Distance function that takes two arrays and some callback state and returns a scalar.
+    using metric_array_array_state_t = result_t (*)(uptr_t, uptr_t, uptr_t);
     /// Distance function callback, like `metric_array_array_size_t`, but depends on member variables.
     using metric_rounted_t = result_t (metric_punned_t::*)(uptr_t, uptr_t) const;
 
     metric_rounted_t metric_routed_ = nullptr;
     uptr_t metric_ptr_ = 0;
-    uptr_t metric_size_arg_ = 0;
+    uptr_t metric_third_arg_ = 0;
 
     std::size_t dimensions_ = 0;
     metric_kind_t metric_kind_ = metric_kind_t::unknown_k;
@@ -1367,37 +1370,95 @@ class metric_punned_t {
     inline metric_punned_t() noexcept = default;
     inline metric_punned_t(metric_punned_t const&) noexcept = default;
     inline metric_punned_t& operator=(metric_punned_t const&) noexcept = default;
-    inline metric_punned_t(                                //
-        std::size_t dimensions,                            //
-        metric_kind_t metric_kind = metric_kind_t::l2sq_k, //
-        scalar_kind_t scalar_kind = scalar_kind_t::f32_k) noexcept
-        : metric_routed_(&metric_punned_t::invoke_array_array_size), metric_size_arg_(dimensions),
-          dimensions_(dimensions), metric_kind_(metric_kind), scalar_kind_(scalar_kind) {
+
+    inline metric_punned_t(std::size_t dimensions, metric_kind_t metric_kind = metric_kind_t::l2sq_k,
+                           scalar_kind_t scalar_kind = scalar_kind_t::f32_k) noexcept
+        : metric_punned_t(builtin(dimensions, metric_kind, scalar_kind)) {}
+
+    inline metric_punned_t(std::size_t dimensions, std::uintptr_t metric_uintptr, metric_punned_signature_t signature,
+                           metric_kind_t metric_kind, scalar_kind_t scalar_kind) noexcept
+        : metric_punned_t(stateless(dimensions, metric_uintptr, signature, metric_kind, scalar_kind)) {}
+
+    /**
+     *  @brief  Creates a metric of a natively supported kind, choosing the best
+     *          available backend internally or from SimSIMD.
+     *
+     *  @param  dimensions      The number of elements in the input arrays.
+     *  @param  metric_kind     The kind of metric to use.
+     *  @param  scalar_kind     The kind of scalar to use.
+     *  @return                 A metric object that can be used to compute distances between vectors.
+     */
+    inline static metric_punned_t builtin(std::size_t dimensions, metric_kind_t metric_kind = metric_kind_t::l2sq_k,
+                                          scalar_kind_t scalar_kind = scalar_kind_t::f32_k) noexcept {
+        metric_punned_t metric;
+        metric.metric_routed_ = &metric_punned_t::invoke_array_array_third;
+        metric.metric_ptr_ = 0;
+        metric.metric_third_arg_ =
+            scalar_kind == scalar_kind_t::b1x8_k ? divide_round_up<CHAR_BIT>(dimensions) : dimensions;
+        metric.dimensions_ = dimensions;
+        metric.metric_kind_ = metric_kind;
+        metric.scalar_kind_ = scalar_kind;
 
 #if USEARCH_USE_SIMSIMD
-        if (!configure_with_simsimd())
-            configure_with_autovec();
+        if (!metric.configure_with_simsimd())
+            metric.configure_with_autovec();
 #else
-        configure_with_autovec();
+        metric.configure_with_autovec();
 #endif
 
-        if (scalar_kind == scalar_kind_t::b1x8_k)
-            metric_size_arg_ = divide_round_up<CHAR_BIT>(dimensions_);
+        return metric;
     }
 
-    inline metric_punned_t(                                                 //
-        std::size_t dimensions,                                             //
-        std::uintptr_t metric_uintptr, metric_punned_signature_t signature, //
-        metric_kind_t metric_kind,                                          //
-        scalar_kind_t scalar_kind) noexcept
-        : metric_routed_(signature == metric_punned_signature_t::array_array_k
-                             ? &metric_punned_t::invoke_array_array
-                             : &metric_punned_t::invoke_array_array_size),
-          metric_ptr_(metric_uintptr), metric_size_arg_(dimensions), dimensions_(dimensions), metric_kind_(metric_kind),
-          scalar_kind_(scalar_kind) {
+    /**
+     *  @brief  Creates a metric using the provided function pointer for a stateless metric.
+     *          So the provided ::metric_uintptr is a pointer to a function that takes two arrays
+     *          and returns a scalar. If the ::signature is metric_punned_signature_t::array_array_size_k,
+     *          then the third argument is the number of scalar words in the input vectors.
+     *
+     *  @param  dimensions      The number of elements in the input arrays.
+     *  @param  metric_uintptr  The function pointer to the metric function.
+     *  @param  signature       The signature of the metric function.
+     *  @param  metric_kind     The kind of metric to use.
+     *  @param  scalar_kind     The kind of scalar to use.
+     *  @return                 A metric object that can be used to compute distances between vectors.
+     */
+    inline static metric_punned_t stateless(std::size_t dimensions, std::uintptr_t metric_uintptr,
+                                            metric_punned_signature_t signature, metric_kind_t metric_kind,
+                                            scalar_kind_t scalar_kind) noexcept {
+        metric_punned_t metric;
+        metric.metric_routed_ = signature == metric_punned_signature_t::array_array_k
+                                    ? &metric_punned_t::invoke_array_array
+                                    : &metric_punned_t::invoke_array_array_third;
+        metric.metric_ptr_ = metric_uintptr;
+        metric.metric_third_arg_ =
+            scalar_kind == scalar_kind_t::b1x8_k ? divide_round_up<CHAR_BIT>(dimensions) : dimensions;
+        metric.dimensions_ = dimensions;
+        metric.metric_kind_ = metric_kind;
+        metric.scalar_kind_ = scalar_kind;
+        return metric;
+    }
 
-        if (scalar_kind == scalar_kind_t::b1x8_k)
-            metric_size_arg_ = divide_round_up<CHAR_BIT>(dimensions_);
+    /**
+     *  @brief  Creates a metric using the provided function pointer for a statefull metric.
+     *          The third argument is the state that will be passed to the metric function.
+     *
+     *  @param  metric_uintptr  The function pointer to the metric function.
+     *  @param  metric_state    The state to pass to the metric function.
+     *  @param  metric_kind     The kind of metric to use.
+     *  @param  scalar_kind     The kind of scalar to use.
+     *  @return                 A metric object that can be used to compute distances between vectors.
+     */
+    inline static metric_punned_t statefull(std::uintptr_t metric_uintptr, std::uintptr_t metric_state,
+                                            metric_kind_t metric_kind = metric_kind_t::unknown_k,
+                                            scalar_kind_t scalar_kind = scalar_kind_t::unknown_k) noexcept {
+        metric_punned_t metric;
+        metric.metric_routed_ = &metric_punned_t::invoke_array_array_third;
+        metric.metric_ptr_ = metric_uintptr;
+        metric.metric_third_arg_ = metric_state;
+        metric.dimensions_ = 0;
+        metric.metric_kind_ = metric_kind;
+        metric.scalar_kind_ = scalar_kind;
+        return metric;
     }
 
     inline std::size_t dimensions() const noexcept { return dimensions_; }
@@ -1485,16 +1546,17 @@ class metric_punned_t {
         simsimd_distance_t result;
         // Here `reinterpret_cast` raises warning... we know what we are doing!
         auto function_pointer = (simsimd_metric_punned_t)(metric_ptr_);
-        function_pointer(reinterpret_cast<void const*>(a), reinterpret_cast<void const*>(b), metric_size_arg_, &result);
+        function_pointer(reinterpret_cast<void const*>(a), reinterpret_cast<void const*>(b), metric_third_arg_,
+                         &result);
         return (result_t)result;
     }
     result_t invoke_simsimd_reverse(uptr_t a, uptr_t b) const noexcept { return 1 - invoke_simsimd(a, b); }
 #else
     bool configure_with_simsimd() noexcept { return false; }
 #endif
-    result_t invoke_array_array_size(uptr_t a, uptr_t b) const noexcept {
+    result_t invoke_array_array_third(uptr_t a, uptr_t b) const noexcept {
         auto function_pointer = (metric_array_array_size_t)(metric_ptr_);
-        result_t result = function_pointer(a, b, metric_size_arg_);
+        result_t result = function_pointer(a, b, metric_third_arg_);
         return result;
     }
     result_t invoke_array_array(uptr_t a, uptr_t b) const noexcept {

package/javascript/dist/cjs/usearch.js

@@ -40,8 +40,8 @@ var _Index_compiledIndex;
 Object.defineProperty(exports, "__esModule", { value: true });
 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("node:path"));
-const node_fs_1 = require("node:fs");
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
 const bindings_1 = require("bindings");
 const compiled = (0, node_gyp_build_1.default)(getBuildDir(getDirName()));
 /**
@@ -507,14 +507,14 @@ module.exports = {
 };
 // utility functions to help find native builds
 function getBuildDir(dir) {
-    if ((0, node_fs_1.existsSync)(path.join(dir, "build")))
+    if ((0, fs_1.existsSync)(path.join(dir, "build")))
         return dir;
-    if ((0, node_fs_1.existsSync)(path.join(dir, "prebuilds")))
+    if ((0, fs_1.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", "usearch");
-        if ((0, node_fs_1.existsSync)(sideways))
+        if ((0, fs_1.existsSync)(sideways))
             return getBuildDir(sideways);
     }
     if (dir === "/")

package/javascript/dist/esm/usearch.js

@@ -1,6 +1,6 @@
 import build from "node-gyp-build";
-import * as path from "node:path";
-import { existsSync } from "node:fs";
+import * as path from "path";
+import { existsSync } from "fs";
 import { getFileName, getRoot } from "bindings";
 const compiled = build(getBuildDir(getDirName()));
 /**

package/javascript/usearch.ts

@@ -1,6 +1,6 @@
 import build from "node-gyp-build";
-import * as path from "node:path";
-import { existsSync } from "node:fs";
+import * as path from "path";
+import { existsSync } from "fs";
 import { getFileName, getRoot } from "bindings";
 
 const compiled: Compiled = build(getBuildDir(getDirName()));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.10.5",
+    "version": "2.11.1",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",
@@ -29,7 +29,7 @@
     ],
     "dependencies": {
         "bindings": "^1.5.0",
-        "node-addon-api": "^3.0.0",
+        "node-addon-api": "^8.0.0",
         "node-gyp-build": "^4.8.0"
     },
     "scripts": {
@@ -42,10 +42,10 @@
     },
     "devDependencies": {
         "@types/bindings": "^1.5.5",
-        "@types/node": "^20.11.0",
-        "node-gyp": "^10.0.1",
+        "@types/node": "^20.12.4",
+        "node-gyp": "^10.1.0",
         "prebuildify": "^6.0.0",
-        "typescript": "^5.3.3"
+        "typescript": "^5.4.4"
     },
     "main": "javascript/dist/cjs/usearch.js",
     "module": "javascript/dist/esm/usearch.js",