@taladb/react-native 0.4.0 → 0.6.0

package/android/src/main/java/com/taladb/TalaDBModule.kt

@@ -23,7 +23,6 @@ package com.taladb
 
 import com.facebook.react.bridge.*
 import com.facebook.react.module.annotations.ReactModule
-import com.facebook.react.turbomodule.core.CallInvokerHolderImpl
 
 @ReactModule(name = TalaDBModule.NAME)
 class TalaDBModule(private val reactContext: ReactApplicationContext) :
@@ -33,9 +32,11 @@ class TalaDBModule(private val reactContext: ReactApplicationContext) :
         const val NAME = "TalaDB"
 
         init {
-            // libtaladb_ffi.so is built by CMakeLists.txt (see android/).
-            // It bundles both the C++ JSI HostObject and the Rust FFI crate.
+            // libtaladb_ffi.so is the pre-built Rust crate (jniLibs/).
+            // libtaladb_jsi.so wraps the C++ JSI HostObject and links taladb_ffi.
+            // Load ffi first so the dynamic linker can resolve it when jsi loads.
             System.loadLibrary("taladb_ffi")
+            System.loadLibrary("taladb_jsi")
         }
     }
 
@@ -50,24 +51,23 @@ class TalaDBModule(private val reactContext: ReactApplicationContext) :
      * JSI runtime identified by [jsContextNativePtr].
      * Called once from [initialize].
      */
-    private external fun nativeInstall(jsContextNativePtr: Long, dbPath: String)
+    private external fun nativeInstall(jsContextNativePtr: Long, dbPath: String, configJson: String?)
 
     // -----------------------------------------------------------------------
-    // TurboModule: initialize(dbName) → Promise<void>
+    // TurboModule: initialize(dbName, configJson?) → Promise<void>
     // -----------------------------------------------------------------------
 
-    override fun initialize(dbName: String, promise: Promise) {
+    override fun initialize(dbName: String, configJson: String?, promise: Promise) {
         try {
             val dbPath = reactContext.filesDir.absolutePath + "/$dbName"
 
-            val jsCallInvokerHolder = reactContext.catalystInstance
-                .jsCallInvokerHolder as CallInvokerHolderImpl
-            val jsContextPtr = jsCallInvokerHolder.nativeCallInvoker
+            // javaScriptContextHolder.get() returns the raw jsi::Runtime* pointer.
+            val jsContextPtr = reactContext.javaScriptContextHolder!!.get()
 
             // Install on the JS thread
             reactContext.runOnJSQueueThread {
                 try {
-                    nativeInstall(jsContextPtr, dbPath)
+                    nativeInstall(jsContextPtr, dbPath, configJson)
                     promise.resolve(null)
                 } catch (e: Exception) {
                     promise.reject("TALADB_INSTALL_ERROR", e.message, e)

package/cpp/TalaDBJni.cpp

@@ -1,13 +1,13 @@
 /**
  * TalaDB JNI glue — Android only.
  *
- * Exposes `nativeInstall(jsContextNativePtr, dbPath)` to Kotlin so that
- * `TalaDBModule.kt` can install the JSI HostObject from the JS thread.
+ * Exposes `nativeInstall(jsContextNativePtr, dbPath, configJson)` to Kotlin so
+ * that `TalaDBModule.kt` can install the JSI HostObject from the JS thread.
  *
  * The function signature must match the Kotlin `external fun` declaration:
  *   package  : com.taladb
  *   class    : TalaDBModule
- *   method   : nativeInstall(Long, String)
+ *   method   : nativeInstall(Long, String, String?)
  *
  * CMakeLists.txt compiles this file together with TalaDBHostObject.cpp.
  */
@@ -26,15 +26,23 @@ Java_com_taladb_TalaDBModule_nativeInstall(
         JNIEnv  *env,
         jobject  /* thiz */,
         jlong    jsContextNativePtr,
-        jstring  dbPathJ)
+        jstring  dbPathJ,
+        jstring  configJsonJ)
 {
     // Resolve db path
     const char *dbPathC = env->GetStringUTFChars(dbPathJ, nullptr);
     std::string dbPath(dbPathC);
     env->ReleaseStringUTFChars(dbPathJ, dbPathC);
 
-    // Open the Rust database
-    TalaDbHandle *db = taladb_open(dbPath.c_str());
+    // Open the Rust database — use taladb_open_with_config when config provided
+    TalaDbHandle *db = nullptr;
+    if (configJsonJ != nullptr) {
+        const char *configC = env->GetStringUTFChars(configJsonJ, nullptr);
+        db = taladb_open_with_config(dbPath.c_str(), configC);
+        env->ReleaseStringUTFChars(configJsonJ, configC);
+    } else {
+        db = taladb_open(dbPath.c_str());
+    }
     if (!db) return; // failed to open — JS will see no __TalaDB__ global
 
     // Get the JSI runtime from the pointer passed by RN internals

package/cpp/taladb.h

@@ -37,6 +37,14 @@ typedef struct TalaDbHandle TalaDbHandle;
 /** Open (or create) a database at the given file-system path. */
 TalaDbHandle *taladb_open(const char *path);
 
+/**
+ * Open (or create) a database with HTTP push sync configuration.
+ *
+ * config_json — JSON-serialised TalaDbConfig, or NULL to open without sync.
+ * Returns an opaque handle (same semantics as taladb_open), or NULL on failure.
+ */
+TalaDbHandle *taladb_open_with_config(const char *path, const char *config_json);
+
 /** Flush and close the database, freeing the handle. */
 void taladb_close(TalaDbHandle *handle);
 

package/ios/TalaDB.mm

@@ -3,11 +3,10 @@
  *
  * Build setup (Xcode / CocoaPods)
  * --------------------------------
- *  1. Run `cargo build --target aarch64-apple-ios --release` (device) and
- *     `cargo build --target x86_64-apple-ios --release` (simulator), then
- *     `lipo` them into a universal `libtaladb_ffi.a`.
- *  2. The podspec links the fat archive and adds `cpp/` to the header search
- *     paths — both are handled automatically when using the podspec.
+ *  1. Run `scripts/build-ios.sh` (or the release CI) to produce
+ *     `ios/TalaDBFfi.xcframework` — device (arm64) + simulator (arm64 + x86_64).
+ *  2. The podspec declares `vendored_frameworks` pointing to that xcframework.
+ *     Headers and link flags are handled automatically by CocoaPods.
  *
  * Runtime flow
  * ------------
@@ -53,13 +52,19 @@ RCT_EXPORT_MODULE(TalaDB)
 // ---- Class method: open DB and install the JSI HostObject ----------------
 
 + (void)installInRuntime:(facebook::jsi::Runtime &)rt
-                  dbPath:(NSString *)path {
+                  dbPath:(NSString *)path
+              configJson:(NSString * _Nullable)configJson {
     if (gHandle) {
         taladb_close(gHandle);
         gHandle = nullptr;
     }
 
-    gHandle = taladb_open(path.UTF8String);
+    if (configJson != nil) {
+        gHandle = taladb_open_with_config(path.UTF8String, configJson.UTF8String);
+    } else {
+        gHandle = taladb_open(path.UTF8String);
+    }
+
     if (!gHandle) {
         NSLog(@"[TalaDB] Failed to open database at %@", path);
         return;
@@ -72,6 +77,7 @@ RCT_EXPORT_MODULE(TalaDB)
 // ---- initialize(dbName) → Promise<void>  ---------------------------------
 
 RCT_EXPORT_METHOD(initialize:(NSString *)dbName
+                  configJson:(NSString * _Nullable)configJson
                   resolve:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject) {
     @try {
@@ -86,9 +92,9 @@ RCT_EXPORT_METHOD(initialize:(NSString *)dbName
         }
 
         // Install the HostObject on the JS thread
-        bridge.jsCallInvoker->invokeAsync([bridge, dbPath]() {
+        bridge.jsCallInvoker->invokeAsync([bridge, dbPath, configJson]() {
             auto &rt = *(Runtime *)bridge.runtime;
-            [TalaDB installInRuntime:rt dbPath:dbPath];
+            [TalaDB installInRuntime:rt dbPath:dbPath configJson:configJson];
         });
 
         resolve(nil);

package/ios/TalaDBFfi.xcframework/Info.plist

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AvailableLibraries</key>
+	<array>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libtaladb_ffi.a</string>
+			<key>HeadersPath</key>
+			<string>Headers</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64</string>
+			<key>LibraryPath</key>
+			<string>libtaladb_ffi.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+		</dict>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libtaladb_ffi_sim.a</string>
+			<key>HeadersPath</key>
+			<string>Headers</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64_x86_64-simulator</string>
+			<key>LibraryPath</key>
+			<string>libtaladb_ffi_sim.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+				<string>x86_64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
+		</dict>
+	</array>
+	<key>CFBundlePackageType</key>
+	<string>XFWK</string>
+	<key>XCFrameworkFormatVersion</key>
+	<string>1.0</string>
+</dict>
+</plist>

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

@@ -0,0 +1,285 @@
+#include "TalaDBHostObject.h"
+
+#include <stdexcept>
+#include <vector>
+
+using namespace facebook::jsi;
+
+namespace taladb {
+
+// ---------------------------------------------------------------------------
+// Constructor / Destructor
+// ---------------------------------------------------------------------------
+
+TalaDBHostObject::TalaDBHostObject(TalaDbHandle *db) : db_(db) {}
+
+TalaDBHostObject::~TalaDBHostObject() {
+    if (db_) {
+        taladb_close(db_);
+        db_ = nullptr;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Static installer
+// ---------------------------------------------------------------------------
+
+void TalaDBHostObject::install(Runtime &rt, TalaDbHandle *db) {
+    auto hostObject = std::make_shared<TalaDBHostObject>(db);
+    auto jsiObject  = Object::createFromHostObject(rt, hostObject);
+    rt.global().setProperty(rt, "__TalaDB__", std::move(jsiObject));
+}
+
+// ---------------------------------------------------------------------------
+// JSON helpers
+// ---------------------------------------------------------------------------
+
+std::string TalaDBHostObject::stringify(Runtime &rt, const Value &val) {
+    auto json    = rt.global().getPropertyAsObject(rt, "JSON");
+    auto strFn   = json.getPropertyAsFunction(rt, "stringify");
+    auto result  = strFn.call(rt, val);
+    if (result.isString()) {
+        return result.getString(rt).utf8(rt);
+    }
+    return "null";
+}
+
+Value TalaDBHostObject::parse(Runtime &rt, const std::string &json) {
+    auto jsonObj = rt.global().getPropertyAsObject(rt, "JSON");
+    auto parseFn = jsonObj.getPropertyAsFunction(rt, "parse");
+    return parseFn.call(rt, String::createFromUtf8(rt, json));
+}
+
+std::string TalaDBHostObject::valueToFilterJson(Runtime &rt, const Value &val) {
+    if (val.isNull() || val.isUndefined()) {
+        return "{}";
+    }
+    return stringify(rt, val);
+}
+
+// ---------------------------------------------------------------------------
+// Property names advertised to JS
+// ---------------------------------------------------------------------------
+
+std::vector<PropNameID> TalaDBHostObject::getPropertyNames(Runtime &rt) {
+    std::vector<std::string> names = {
+        "insert", "insertMany",
+        "find", "findOne",
+        "updateOne", "updateMany",
+        "deleteOne", "deleteMany",
+        "count",
+        "createIndex", "dropIndex",
+        "createFtsIndex", "dropFtsIndex",
+        "close",
+    };
+    std::vector<PropNameID> result;
+    result.reserve(names.size());
+    for (auto &n : names) {
+        result.push_back(PropNameID::forUtf8(rt, n));
+    }
+    return result;
+}
+
+void TalaDBHostObject::set(Runtime &, const PropNameID &, const Value &) {}
+
+// ---------------------------------------------------------------------------
+// Property dispatch
+// ---------------------------------------------------------------------------
+
+Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
+    auto name = propName.utf8(rt);
+
+    // ------------------------------------------------------------------
+    // insert(collection: string, doc: object): string
+    // ------------------------------------------------------------------
+    if (name == "insert") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "insert"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "insert requires 2 arguments");
+                auto col     = args[0].getString(rt).utf8(rt);
+                auto docJson = stringify(rt, args[1]);
+                char *result = taladb_insert(db_, col.c_str(), docJson.c_str());
+                if (!result) throw JSError(rt, "taladb_insert failed");
+                std::string id(result);
+                taladb_free_string(result);
+                return String::createFromUtf8(rt, id);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // insertMany(collection: string, docs: object[]): string[]
+    // ------------------------------------------------------------------
+    if (name == "insertMany") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "insertMany"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "insertMany requires 2 arguments");
+                auto col      = args[0].getString(rt).utf8(rt);
+                auto docsJson = stringify(rt, args[1]);
+                char *result  = taladb_insert_many(db_, col.c_str(), docsJson.c_str());
+                if (!result) throw JSError(rt, "taladb_insert_many failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // find(collection: string, filter: object | null): object[]
+    // ------------------------------------------------------------------
+    if (name == "find") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "find"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 1) throw JSError(rt, "find requires at least 1 argument");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = count > 1 ? valueToFilterJson(rt, args[1]) : "{}";
+                char *result    = taladb_find(db_, col.c_str(), filterJson.c_str());
+                if (!result) throw JSError(rt, "taladb_find failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // findOne(collection: string, filter: object | null): object | null
+    // ------------------------------------------------------------------
+    if (name == "findOne") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "findOne"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 1) throw JSError(rt, "findOne requires at least 1 argument");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = count > 1 ? valueToFilterJson(rt, args[1]) : "{}";
+                char *result    = taladb_find_one(db_, col.c_str(), filterJson.c_str());
+                if (!result) throw JSError(rt, "taladb_find_one failed");
+                std::string json(result);
+                taladb_free_string(result);
+                return parse(rt, json);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // updateOne(collection, filter, update): boolean
+    // ------------------------------------------------------------------
+    if (name == "updateOne") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "updateOne"), 3,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 3) throw JSError(rt, "updateOne requires 3 arguments");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = stringify(rt, args[1]);
+                auto updateJson = stringify(rt, args[2]);
+                int32_t res = taladb_update_one(
+                    db_, col.c_str(), filterJson.c_str(), updateJson.c_str());
+                if (res < 0) throw JSError(rt, "taladb_update_one failed");
+                return Value(res == 1);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // updateMany(collection, filter, update): number
+    // ------------------------------------------------------------------
+    if (name == "updateMany") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "updateMany"), 3,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 3) throw JSError(rt, "updateMany requires 3 arguments");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = stringify(rt, args[1]);
+                auto updateJson = stringify(rt, args[2]);
+                int32_t res = taladb_update_many(
+                    db_, col.c_str(), filterJson.c_str(), updateJson.c_str());
+                if (res < 0) throw JSError(rt, "taladb_update_many failed");
+                return Value(static_cast<double>(res));
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // deleteOne(collection, filter): boolean
+    // ------------------------------------------------------------------
+    if (name == "deleteOne") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "deleteOne"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "deleteOne requires 2 arguments");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = stringify(rt, args[1]);
+                int32_t res = taladb_delete_one(db_, col.c_str(), filterJson.c_str());
+                if (res < 0) throw JSError(rt, "taladb_delete_one failed");
+                return Value(res == 1);
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // deleteMany(collection, filter): number
+    // ------------------------------------------------------------------
+    if (name == "deleteMany") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "deleteMany"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, "deleteMany requires 2 arguments");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = stringify(rt, args[1]);
+                int32_t res = taladb_delete_many(db_, col.c_str(), filterJson.c_str());
+                if (res < 0) throw JSError(rt, "taladb_delete_many failed");
+                return Value(static_cast<double>(res));
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // count(collection, filter): number
+    // ------------------------------------------------------------------
+    if (name == "count") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "count"), 2,
+            [this](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 1) throw JSError(rt, "count requires at least 1 argument");
+                auto col        = args[0].getString(rt).utf8(rt);
+                auto filterJson = count > 1 ? valueToFilterJson(rt, args[1]) : "{}";
+                int32_t res = taladb_count(db_, col.c_str(), filterJson.c_str());
+                if (res < 0) throw JSError(rt, "taladb_count failed");
+                return Value(static_cast<double>(res));
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // createIndex / dropIndex / createFtsIndex / dropFtsIndex
+    // ------------------------------------------------------------------
+    if (name == "createIndex" || name == "dropIndex" ||
+        name == "createFtsIndex" || name == "dropFtsIndex") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forUtf8(rt, name), 2,
+            [this, name](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
+                if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
+                auto col   = args[0].getString(rt).utf8(rt);
+                auto field = args[1].getString(rt).utf8(rt);
+                if      (name == "createIndex")    taladb_create_index    (db_, col.c_str(), field.c_str());
+                else if (name == "dropIndex")      taladb_drop_index      (db_, col.c_str(), field.c_str());
+                else if (name == "createFtsIndex") taladb_create_fts_index(db_, col.c_str(), field.c_str());
+                else                               taladb_drop_fts_index  (db_, col.c_str(), field.c_str());
+                return Value::undefined();
+            });
+    }
+
+    // ------------------------------------------------------------------
+    // close(): void  (synchronous — the destructor does the real work)
+    // ------------------------------------------------------------------
+    if (name == "close") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "close"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                if (db_) {
+                    taladb_close(db_);
+                    db_ = nullptr;
+                }
+                return Value::undefined();
+            });
+    }
+
+    return Value::undefined();
+}
+
+} // namespace taladb

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

@@ -0,0 +1,55 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <string>
+#include "taladb.h"
+
+namespace taladb {
+
+/**
+ * TalaDBHostObject — JSI HostObject wrapping the Rust taladb-ffi C library.
+ *
+ * Installed into the JS runtime as a global:
+ *   global.__TalaDB__ = <TalaDBHostObject instance>
+ *
+ * Every property access returns a JSI Function. All CRUD methods are
+ * synchronous (the Rust core does no async I/O); `initialize` and `close`
+ * are async only to conform to the TurboModule spec (they resolve immediately).
+ *
+ * JSON is used at the C boundary:
+ *   JS object  →  JSON.stringify  →  C string  →  Rust  →  C string  →  JSON.parse  →  JS object
+ */
+class TalaDBHostObject : public facebook::jsi::HostObject {
+public:
+    explicit TalaDBHostObject(TalaDbHandle *db);
+    ~TalaDBHostObject() override;
+
+    facebook::jsi::Value get(facebook::jsi::Runtime &rt,
+                             const facebook::jsi::PropNameID &name) override;
+
+    void set(facebook::jsi::Runtime &rt,
+             const facebook::jsi::PropNameID &name,
+             const facebook::jsi::Value &value) override;
+
+    std::vector<facebook::jsi::PropNameID>
+    getPropertyNames(facebook::jsi::Runtime &rt) override;
+
+    /** Install this object as global.__TalaDB__ in the given runtime. */
+    static void install(facebook::jsi::Runtime &rt, TalaDbHandle *db);
+
+private:
+    TalaDbHandle *db_;
+
+    // JSON helpers
+    static std::string stringify(facebook::jsi::Runtime &rt,
+                                 const facebook::jsi::Value &val);
+    static facebook::jsi::Value parse(facebook::jsi::Runtime &rt,
+                                      const std::string &json);
+
+    // Convenience: convert a nullable JSI Value to a JSON C-string.
+    // Returns "{}" when the value is null/undefined.
+    static std::string valueToFilterJson(facebook::jsi::Runtime &rt,
+                                         const facebook::jsi::Value &val);
+};
+
+} // namespace taladb

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

@@ -0,0 +1,53 @@
+/**
+ * TalaDB JNI glue — Android only.
+ *
+ * Exposes `nativeInstall(jsContextNativePtr, dbPath, configJson)` to Kotlin so
+ * that `TalaDBModule.kt` can install the JSI HostObject from the JS thread.
+ *
+ * The function signature must match the Kotlin `external fun` declaration:
+ *   package  : com.taladb
+ *   class    : TalaDBModule
+ *   method   : nativeInstall(Long, String, String?)
+ *
+ * CMakeLists.txt compiles this file together with TalaDBHostObject.cpp.
+ */
+
+#include <jni.h>
+#include <jsi/jsi.h>
+#include <string>
+
+#include "TalaDBHostObject.h"
+#include "taladb.h"
+
+using namespace facebook::jsi;
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_taladb_TalaDBModule_nativeInstall(
+        JNIEnv  *env,
+        jobject  /* thiz */,
+        jlong    jsContextNativePtr,
+        jstring  dbPathJ,
+        jstring  configJsonJ)
+{
+    // Resolve db path
+    const char *dbPathC = env->GetStringUTFChars(dbPathJ, nullptr);
+    std::string dbPath(dbPathC);
+    env->ReleaseStringUTFChars(dbPathJ, dbPathC);
+
+    // Open the Rust database — use taladb_open_with_config when config provided
+    TalaDbHandle *db = nullptr;
+    if (configJsonJ != nullptr) {
+        const char *configC = env->GetStringUTFChars(configJsonJ, nullptr);
+        db = taladb_open_with_config(dbPath.c_str(), configC);
+        env->ReleaseStringUTFChars(configJsonJ, configC);
+    } else {
+        db = taladb_open(dbPath.c_str());
+    }
+    if (!db) return; // failed to open — JS will see no __TalaDB__ global
+
+    // Get the JSI runtime from the pointer passed by RN internals
+    auto &rt = *reinterpret_cast<Runtime *>(jsContextNativePtr);
+
+    // Install the JSI HostObject as global.__TalaDB__
+    taladb::TalaDBHostObject::install(rt, db);
+}