@taladb/react-native 0.7.3 → 0.7.4

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/TalaDBHostObject.cpp

@@ -1,5 +1,6 @@
 #include "TalaDBHostObject.h"
 
+#include <memory>
 #include <stdexcept>
 #include <vector>
 
@@ -7,6 +8,28 @@ using namespace facebook::jsi;
 
 namespace taladb {
 
+namespace {
+
+// Read the error string set by the most recent FFI call. Safe to call even
+// when no error has been set — returns an empty string in that case.
+std::string lastError() {
+    const char *msg = taladb_last_error();
+    return msg ? std::string(msg) : std::string();
+}
+
+// Build a JSError with the FFI last-error message appended.
+JSError ffiError(Runtime &rt, const char *prefix) {
+    std::string msg = prefix;
+    std::string last = lastError();
+    if (!last.empty()) {
+        msg += ": ";
+        msg += last;
+    }
+    return JSError(rt, msg);
+}
+
+} // namespace
+
 // ---------------------------------------------------------------------------
 // Constructor / Destructor
 // ---------------------------------------------------------------------------
@@ -57,6 +80,159 @@ std::string TalaDBHostObject::valueToFilterJson(Runtime &rt, const Value &val) {
     return stringify(rt, val);
 }
 
+// ---------------------------------------------------------------------------
+// Float32Array fast path
+// ---------------------------------------------------------------------------
+
+void TalaDBHostObject::extractF32Query(Runtime &rt, const Value &val,
+                                       std::vector<float> &out) {
+    if (!val.isObject()) {
+        throw JSError(rt, "query must be a Float32Array or number[]");
+    }
+    auto obj = val.getObject(rt);
+
+    // --- Fast path: Float32Array — zero-copy read from the underlying ArrayBuffer ---
+    if (obj.isArrayBuffer(rt)) {
+        // Raw ArrayBuffer of bytes (length must be a multiple of 4)
+        auto ab     = obj.getArrayBuffer(rt);
+        size_t size = ab.size(rt);
+        if (size % sizeof(float) != 0) {
+            throw JSError(rt, "ArrayBuffer length is not a multiple of 4 bytes");
+        }
+        size_t n = size / sizeof(float);
+        out.resize(n);
+        std::memcpy(out.data(), ab.data(rt), size);
+        return;
+    }
+
+    // Float32Array exposes `.buffer`, `.byteOffset`, `.byteLength`. We read
+    // those directly and memcpy from the underlying ArrayBuffer — no JSON,
+    // no per-element Value conversion.
+    if (obj.hasProperty(rt, "BYTES_PER_ELEMENT")) {
+        auto bpe = obj.getProperty(rt, "BYTES_PER_ELEMENT");
+        if (bpe.isNumber() && (int)bpe.getNumber() == 4) {
+            auto buf      = obj.getPropertyAsObject(rt, "buffer");
+            auto ab       = buf.getArrayBuffer(rt);
+            auto offsetV  = obj.getProperty(rt, "byteOffset");
+            auto lengthV  = obj.getProperty(rt, "byteLength");
+            size_t offset = offsetV.isNumber() ? (size_t)offsetV.getNumber() : 0;
+            size_t length = lengthV.isNumber() ? (size_t)lengthV.getNumber() : 0;
+            if (length % sizeof(float) != 0) {
+                throw JSError(rt, "typed-array byteLength is not a multiple of 4");
+            }
+            size_t n = length / sizeof(float);
+            out.resize(n);
+            std::memcpy(out.data(), ab.data(rt) + offset, length);
+            return;
+        }
+    }
+
+    // --- Fallback: number[] — per-element conversion (slow, but correct) ---
+    if (obj.isArray(rt)) {
+        auto arr   = obj.getArray(rt);
+        size_t len = arr.size(rt);
+        out.resize(len);
+        for (size_t i = 0; i < len; i++) {
+            auto v = arr.getValueAtIndex(rt, i);
+            if (!v.isNumber()) {
+                throw JSError(rt, "query array must contain only numbers");
+            }
+            out[i] = (float)v.getNumber();
+        }
+        return;
+    }
+
+    throw JSError(rt, "query must be a Float32Array, typed array, or number[]");
+}
+
+// ---------------------------------------------------------------------------
+// Async job → Promise bridge
+//
+// JSI on RN does not give us a thread-safe way to resolve a Promise from a
+// background OS thread. We poll the job handle from the JS thread using
+// `setImmediate`, which costs ~0.1 ms per tick — negligible next to a
+// hundred-millisecond vector search — and the DB work itself runs on the
+// background worker the FFI spawned.
+// ---------------------------------------------------------------------------
+
+Value TalaDBHostObject::awaitJobAsPromise(Runtime &rt, TalaDbJob *job, bool parseAsJson) {
+    if (!job) {
+        throw ffiError(rt, "failed to start background job");
+    }
+
+    auto promiseCtor = rt.global().getPropertyAsFunction(rt, "Promise");
+
+    // The job pointer is owned by the executor closure; we null it out on
+    // consumption to prevent double-free.
+    auto jobBox = std::make_shared<TalaDbJob *>(job);
+
+    auto executor = Function::createFromHostFunction(
+        rt, PropNameID::forAscii(rt, "taladbJobExecutor"), 2,
+        [jobBox, parseAsJson](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+            if (count < 2) {
+                return Value::undefined();
+            }
+            auto resolve = std::make_shared<Function>(args[0].getObject(rt).getFunction(rt));
+            auto reject  = std::make_shared<Function>(args[1].getObject(rt).getFunction(rt));
+
+            // `setImmediate` is provided by React Native. Recurse until the
+            // worker thread finishes, then take the result on the JS thread.
+            auto setImmediate = rt.global().getPropertyAsFunction(rt, "setImmediate");
+            auto setImmediateShared = std::make_shared<Function>(std::move(setImmediate));
+
+            // Capture a self-reference so the polling lambda can schedule itself.
+            auto poller = std::make_shared<std::function<void(Runtime &)>>();
+            *poller = [jobBox, resolve, reject, setImmediateShared, poller, parseAsJson](Runtime &rt) {
+                TalaDbJob *j = *jobBox;
+                if (!j) {
+                    return; // already consumed — defensive
+                }
+                int32_t state = taladb_job_poll(j);
+                if (state == 0) {
+                    // Still running — reschedule.
+                    auto tick = Function::createFromHostFunction(
+                        rt, PropNameID::forAscii(rt, "taladbJobTick"), 0,
+                        [poller](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                            (*poller)(rt);
+                            return Value::undefined();
+                        });
+                    setImmediateShared->call(rt, tick);
+                    return;
+                }
+
+                // Done — take the result and clear the job slot.
+                char *raw = taladb_job_take_result(j);
+                *jobBox = nullptr;
+
+                if (!raw) {
+                    std::string last = lastError();
+                    auto err = String::createFromUtf8(
+                        rt, last.empty() ? "taladb job failed" : last);
+                    reject->call(rt, err);
+                    return;
+                }
+
+                std::string json(raw);
+                taladb_free_string(raw);
+
+                if (parseAsJson) {
+                    try {
+                        resolve->call(rt, parse(rt, json));
+                    } catch (const JSError &e) {
+                        reject->call(rt, String::createFromUtf8(rt, e.getMessage()));
+                    }
+                } else {
+                    resolve->call(rt, String::createFromUtf8(rt, json));
+                }
+            };
+
+            (*poller)(rt);
+            return Value::undefined();
+        });
+
+    return promiseCtor.callAsConstructor(rt, executor);
+}
+
 // ---------------------------------------------------------------------------
 // Property names advertised to JS
 // ---------------------------------------------------------------------------
@@ -70,6 +246,9 @@ std::vector<PropNameID> TalaDBHostObject::getPropertyNames(Runtime &rt) {
         "count",
         "createIndex", "dropIndex",
         "createFtsIndex", "dropFtsIndex",
+        "createVectorIndex", "dropVectorIndex", "upgradeVectorIndex",
+        "findNearest", "findNearestAsync",
+        "findAsync",
         "compact",
         "close",
     };
@@ -265,6 +444,153 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // createVectorIndex(collection, field, dimensions, opts?): void
+    //   opts: { metric?: 'cosine'|'dot'|'euclidean', hnsw?: HnswOptions }
+    // ------------------------------------------------------------------
+    if (name == "createVectorIndex") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "createVectorIndex"), 4,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 3) throw JSError(rt, "createVectorIndex requires (collection, field, dimensions, opts?)");
+                auto col   = args[0].getString(rt).utf8(rt);
+                auto field = args[1].getString(rt).utf8(rt);
+                if (!args[2].isNumber()) throw JSError(rt, "dimensions must be a number");
+                size_t dims = (size_t)args[2].getNumber();
+
+                std::string metricStr;
+                std::string hnswJson;
+                const char *metricPtr = nullptr;
+                const char *hnswPtr   = nullptr;
+                if (count > 3 && args[3].isObject()) {
+                    auto opts = args[3].getObject(rt);
+                    if (opts.hasProperty(rt, "metric")) {
+                        auto m = opts.getProperty(rt, "metric");
+                        if (m.isString()) {
+                            metricStr = m.getString(rt).utf8(rt);
+                            metricPtr = metricStr.c_str();
+                        }
+                    }
+                    if (opts.hasProperty(rt, "hnsw")) {
+                        auto h = opts.getProperty(rt, "hnsw");
+                        if (h.isObject()) {
+                            hnswJson = stringify(rt, h);
+                            hnswPtr  = hnswJson.c_str();
+                        }
+                    }
+                }
+
+                int32_t res = taladb_create_vector_index(
+                    db_, col.c_str(), field.c_str(), dims, metricPtr, hnswPtr);
+                if (res < 0) throw ffiError(rt, "taladb_create_vector_index failed");
+                return Value::undefined();
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // dropVectorIndex(collection, field): void
+    // ------------------------------------------------------------------
+    if (name == "dropVectorIndex") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "dropVectorIndex"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "dropVectorIndex requires 2 arguments");
+                auto col   = args[0].getString(rt).utf8(rt);
+                auto field = args[1].getString(rt).utf8(rt);
+                int32_t res = taladb_drop_vector_index(db_, col.c_str(), field.c_str());
+                if (res < 0) throw ffiError(rt, "taladb_drop_vector_index failed");
+                return Value::undefined();
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // upgradeVectorIndex(collection, field): void
+    // ------------------------------------------------------------------
+    if (name == "upgradeVectorIndex") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "upgradeVectorIndex"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "upgradeVectorIndex requires 2 arguments");
+                auto col   = args[0].getString(rt).utf8(rt);
+                auto field = args[1].getString(rt).utf8(rt);
+                int32_t res = taladb_upgrade_vector_index(db_, col.c_str(), field.c_str());
+                if (res < 0) throw ffiError(rt, "taladb_upgrade_vector_index failed");
+                return Value::undefined();
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // findNearest(collection, field, query, topK, filter?): { document, score }[]
+    //   query — Float32Array (preferred, zero-copy) or number[]
+    // ------------------------------------------------------------------
+    if (name == "findNearest") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "findNearest"), 5,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 4) throw JSError(rt, "findNearest requires (collection, field, query, topK, filter?)");
+                auto col   = args[0].getString(rt).utf8(rt);
+                auto field = args[1].getString(rt).utf8(rt);
+                std::vector<float> qbuf;
+                extractF32Query(rt, args[2], qbuf);
+                if (!args[3].isNumber()) throw JSError(rt, "topK must be a number");
+                size_t topK = (size_t)args[3].getNumber();
+                std::string filterJson = count > 4
+                    ? valueToFilterJson(rt, args[4])
+                    : std::string();
+                const char *filterPtr = count > 4 ? filterJson.c_str() : nullptr;
+
+                char *result = taladb_find_nearest(
+                    db_, col.c_str(), field.c_str(),
+                    qbuf.data(), qbuf.size(), topK, filterPtr);
+                if (!result) throw ffiError(rt, "taladb_find_nearest failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // findNearestAsync(...) → Promise<{ document, score }[]>
+    //   Runs on a background thread. JS thread polls via setImmediate.
+    // ------------------------------------------------------------------
+    if (name == "findNearestAsync") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "findNearestAsync"), 5,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 4) throw JSError(rt, "findNearestAsync requires (collection, field, query, topK, filter?)");
+                auto col   = args[0].getString(rt).utf8(rt);
+                auto field = args[1].getString(rt).utf8(rt);
+                std::vector<float> qbuf;
+                extractF32Query(rt, args[2], qbuf);
+                if (!args[3].isNumber()) throw JSError(rt, "topK must be a number");
+                size_t topK = (size_t)args[3].getNumber();
+                std::string filterJson = count > 4
+                    ? valueToFilterJson(rt, args[4])
+                    : std::string();
+                const char *filterPtr = count > 4 ? filterJson.c_str() : nullptr;
+
+                TalaDbJob *job = taladb_find_nearest_start(
+                    db_, col.c_str(), field.c_str(),
+                    qbuf.data(), qbuf.size(), topK, filterPtr);
+                return awaitJobAsPromise(rt, job, /*parseAsJson=*/true);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // findAsync(collection, filter?) → Promise<object[]>
+    // ------------------------------------------------------------------
+    if (name == "findAsync") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "findAsync"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 1) throw JSError(rt, "findAsync requires at least 1 argument");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = count > 1 ? valueToFilterJson(rt, args[1]) : std::string("{}");
+                TalaDbJob *job = taladb_find_start(db_, col.c_str(), filterJson.c_str());
+                return awaitJobAsPromise(rt, job, /*parseAsJson=*/true);
+            });
+    }
+
     // ------------------------------------------------------------------
     // compact(): void
     // ------------------------------------------------------------------

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/TalaDBHostObject.h

@@ -50,6 +50,23 @@ private:
     // Returns "{}" when the value is null/undefined.
     static std::string valueToFilterJson(facebook::jsi::Runtime &rt,
                                          const facebook::jsi::Value &val);
+
+    // ------------------------------------------------------------------
+    // Float32Array helpers — zero-copy extraction from JSI
+    // ------------------------------------------------------------------
+    //
+    // Accepts a JS `Float32Array` *or* a plain `number[]`. Populates `out`
+    // with a copy of the values (kept alive by the caller for the FFI call).
+    // Throws JSError when the value is neither.
+    static void extractF32Query(facebook::jsi::Runtime &rt,
+                                const facebook::jsi::Value &val,
+                                std::vector<float> &out);
+
+    // Poll a TalaDbJob from the JS thread via setImmediate until done,
+    // then resolve / reject a Promise with the result / error.
+    static facebook::jsi::Value awaitJobAsPromise(facebook::jsi::Runtime &rt,
+                                                  TalaDbJob *job,
+                                                  bool parseAsJson);
 };
 
 } // namespace taladb

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/taladb.h

@@ -150,6 +150,94 @@ void taladb_drop_index      (TalaDbHandle *handle, const char *collection, const
 void taladb_create_fts_index(TalaDbHandle *handle, const char *collection, const char *field);
 void taladb_drop_fts_index  (TalaDbHandle *handle, const char *collection, const char *field);
 
+/* -------------------------------------------------------------------------
+ * Vector index management
+ *
+ *   metric    — "cosine" (default), "dot", or "euclidean". NULL ⇒ cosine.
+ *   hnsw_json — JSON-encoded HnswOptions, or NULL for flat index.
+ * ---------------------------------------------------------------------- */
+
+int32_t taladb_create_vector_index(TalaDbHandle *handle,
+                                   const char   *collection,
+                                   const char   *field,
+                                   size_t        dimensions,
+                                   const char   *metric,
+                                   const char   *hnsw_json);
+
+int32_t taladb_drop_vector_index   (TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_upgrade_vector_index(TalaDbHandle *handle, const char *collection, const char *field);
+
+/* -------------------------------------------------------------------------
+ * findNearest — Float32 zero-copy fast path
+ *
+ * query_ptr / query_len address `query_len` consecutive f32 values. Caller
+ * retains ownership; the buffer may be freed immediately after the call.
+ * filter_json may be NULL / "{}" / "null" to search without a pre-filter.
+ *
+ * Returns a JSON array string `[{document, score}, ...]`, or NULL on error.
+ * Caller must free with taladb_free_string.
+ * ---------------------------------------------------------------------- */
+
+char *taladb_find_nearest(TalaDbHandle *handle,
+                          const char   *collection,
+                          const char   *field,
+                          const float  *query_ptr,
+                          size_t        query_len,
+                          size_t        top_k,
+                          const char   *filter_json);
+
+/* -------------------------------------------------------------------------
+ * Async job API — run heavy queries on a background thread.
+ *
+ * Flow
+ * ----
+ *   TalaDbJob *j = taladb_find_nearest_start(...);  // spawns worker thread
+ *   while (taladb_job_poll(j) == 0) { /* yield to JS event loop */ }
+ *   char *json = taladb_job_take_result(j);         // frees the job
+ *
+ * Lifetime contract
+ * -----------------
+ * The handle passed to `*_start` MUST remain valid until the job has been
+ * taken (via take_result) or cancelled (via cancel). The C++ HostObject
+ * enforces this by not calling taladb_close while jobs are outstanding.
+ * ---------------------------------------------------------------------- */
+
+typedef struct TalaDbJob TalaDbJob;
+
+/** Kick a background `find_nearest`. Returns NULL on immediate arg error. */
+TalaDbJob *taladb_find_nearest_start(TalaDbHandle *handle,
+                                     const char   *collection,
+                                     const char   *field,
+                                     const float  *query_ptr,
+                                     size_t        query_len,
+                                     size_t        top_k,
+                                     const char   *filter_json);
+
+/** Kick a background `find`. Returns NULL on immediate arg error. */
+TalaDbJob *taladb_find_start(TalaDbHandle *handle,
+                             const char   *collection,
+                             const char   *filter_json);
+
+/** Non-blocking. Returns 1 if complete, 0 if still running, -1 on NULL job. */
+int32_t taladb_job_poll(TalaDbJob *job);
+
+/**
+ * Join the worker, take its result, and free the job.
+ * Returns a JSON string on success, or NULL on error (see taladb_last_error).
+ * Caller must free with taladb_free_string. Always frees the job.
+ */
+char *taladb_job_take_result(TalaDbJob *job);
+
+/** Detach the job and free the handle without waiting. */
+void taladb_job_cancel(TalaDbJob *job);
+
+/**
+ * Last error message for the current thread, or NULL.
+ * The returned pointer is valid until the next taladb_* call on this thread.
+ * Do NOT free.
+ */
+const char *taladb_last_error(void);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif