react-native-nitro-modules 0.5.0 → 0.7.0

package/android/src/main/java/com/margelo/nitro/core/ArrayBuffer.kt

@@ -0,0 +1,115 @@
+package com.margelo.nitro.core
+
+import androidx.annotation.Keep
+import com.facebook.jni.HybridData
+import com.facebook.proguard.annotations.DoNotStrip
+import dalvik.annotation.optimization.CriticalNative
+import java.nio.ByteBuffer
+
+/**
+ * An ArrayBuffer instance shared between native (Kotlin/C++) and JS.
+ *
+ * A `ByteBuffer` will be used as the underlying `ArrayBuffer`'s data,
+ * which has to remain valid for as long as the `ArrayBuffer` is alive.
+ */
+@Suppress("KotlinJniMissingFunction")
+@Keep
+@DoNotStrip
+class ArrayBuffer {
+    /**
+     * Holds the native C++ instance of the `ArrayBuffer`.
+     */
+    private val mHybridData: HybridData
+
+    /**
+     * Whether this `ArrayBuffer` is an **owning-**, or a **non-owning-** `ArrayBuffer`.
+     * - **Owning** ArrayBuffers can safely be held in memory for longer, and accessed at any point.
+     * - **Non-owning** ArrayBuffers can not be held in memory for longer, and can only be safely
+     * accessed within the synchronous function's scope (aka on the JS Thread). Once you switch Threads,
+     * data access is not safe anymore. If you need to access data longer, copy the data.
+     */
+    val isOwner: Boolean
+        get() = getIsOwner()
+
+    /**
+     * Whether this `ArrayBuffer` is holding a `ByteBuffer`, or not.
+     * - If the `ArrayBuffer` holds a `ByteBuffer`, `getBuffer(false)` can safely be called to
+     * get shared access to the underlying data, without performing any copies.
+     * - If the `ArrayBuffer` doesn't hold a `ByteBuffer`, it can still be accessed via `getBuffer(false)`,
+     * but the returned `ByteBuffer` is only valid as long as it's parent `ArrayBuffer` is alive.
+     */
+    val isByteBuffer: Boolean
+        get() = getIsByteBuffer()
+
+    /**
+     * Get the size of bytes in this `ArrayBuffer`.
+     */
+    val size: Int
+        get() = getBufferSize()
+
+    /**
+     * Get a `ByteBuffer` that holds- or wraps- the underlying data.
+     * - If this `ArrayBuffer` has been created from Kotlin/Java, it is already holding a
+     * `ByteBuffer` (`isByteBuffer == true`). In this case, the returned buffer is safe to access,
+     * even after the `ArrayBuffer` has already been destroyed in JS.
+     * - If this `ArrayBuffer` has been created elsewhere (C++/JS), it is not holding a
+     * `ByteBuffer` (`isByteBuffer == false`). In this case, the returned buffer will either be a copy
+     * of the data (`copyIfNeeded == true`), or just wrapping the data (`copyIfNeeded == false`).
+     *
+     * @param copyIfNeeded If this `ArrayBuffer` is not holding a `ByteBuffer` (`isByteBuffer == false`),
+     * the foreign data needs to be either _wrapped_, or _copied_ to be represented as a `ByteBuffer`.
+     * This flag controls that behaviour.
+     */
+    fun getBuffer(copyIfNeeded: Boolean): ByteBuffer {
+        return getByteBuffer(copyIfNeeded)
+    }
+
+    /**
+     * Create a new **owning-** `ArrayBuffer` that holds the given `ByteBuffer`.
+     * The `ByteBuffer` needs to remain valid for as long as the `ArrayBuffer` is alive.
+     */
+    constructor(byteBuffer: ByteBuffer) {
+        if (!byteBuffer.isDirect) {
+            throw Error("ArrayBuffers can only be created from direct ByteBuffers, " +
+                    "and the given ByteBuffer is not direct!")
+        }
+        mHybridData = initHybrid(byteBuffer)
+    }
+
+    /**
+     * Create a new **non-owning-** `ArrayBuffer` that holds foreign data, potentially coming from JS.
+     */
+    @Suppress("unused")
+    private constructor(hybridData: HybridData) {
+        mHybridData = hybridData
+    }
+
+    private external fun initHybrid(buffer: ByteBuffer): HybridData
+    private external fun getByteBuffer(copyIfNeeded: Boolean): ByteBuffer
+    @CriticalNative
+    private external fun getIsOwner(): Boolean
+    @CriticalNative
+    private external fun getIsByteBuffer(): Boolean
+    @CriticalNative
+    private external fun getBufferSize(): Int
+
+    companion object {
+        /**
+         * Copy the given `ArrayBuffer` into a new **owning** `ArrayBuffer`.
+         */
+        fun copyOf(other: ArrayBuffer): ArrayBuffer {
+            // 1. Create a new buffer with the same size as the other
+            val newBuffer = ByteBuffer.allocateDirect(other.size)
+            // 2. Prepare the source buffer
+            val originalBuffer = other.getBuffer(false)
+            originalBuffer.rewind()
+            // 3. Copy over the source buffer into the new buffer
+            newBuffer.put(originalBuffer)
+            // 4. Rewind both buffers again to index 0
+            newBuffer.rewind()
+            originalBuffer.rewind()
+            // 5. Create a new `ArrayBuffer`
+            return ArrayBuffer(newBuffer)
+        }
+    }
+}

package/android/src/main/java/com/margelo/nitro/{HybridObject.kt → core/HybridObject.kt}

@@ -1,4 +1,4 @@
-package com.margelo.nitro
+package com.margelo.nitro.core
 
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
@@ -9,7 +9,6 @@ import com.facebook.proguard.annotations.DoNotStrip
  */
 @Keep
 @DoNotStrip
-@Suppress("KotlinJniMissingFunction")
 abstract class HybridObject {
     /**
      * Get the memory size of the Kotlin instance (plus any external heap allocations),
@@ -29,22 +28,20 @@ abstract class HybridObject {
      */
     @get:DoNotStrip
     @get:Keep
-    abstract val memorySize: ULong
+    abstract val memorySize: Long
 
     /**
-     * Contains the C++ context (Hybrid Data) for the fbjni C++ part.
+     * Holds the native C++ instance.
+     * In `HybridObject`, the C++ instance is a sub-class of `JHybridObject`, such as one of it's specs.
+     * This is `null`, until `updateNative(..)` is called.
      */
-    @DoNotStrip
-    @Keep
-    val mHybridData: HybridData
+    private var mHybridData: HybridData? = null
 
-    init {
-        mHybridData = initHybrid()
-    }
-
-    private external fun initHybrid(): HybridData
-
-    companion object {
-        private const val TAG = "HybridObject"
+    /**
+     * Must be called in the constructor of a subclass of `HybridObject`, to initialize the C++
+     * `JHybridObject` with a subclass of it.
+     */
+    protected fun updateNative(hybridData: HybridData) {
+        mHybridData = hybridData
     }
 }

package/android/src/main/java/com/margelo/nitro/{HybridObjectInitializer.java → core/HybridObjectInitializer.java}

@@ -1,4 +1,4 @@
-package com.margelo.nitro;
+package com.margelo.nitro.core;
 
 import androidx.annotation.Keep;
 

package/android/src/main/java/com/margelo/nitro/{HybridObjectRegistry.java → core/HybridObjectRegistry.java}

@@ -1,6 +1,6 @@
-package com.margelo.nitro;
+package com.margelo.nitro.core;
 
-import java.util.function.Supplier;
+import com.margelo.nitro.JNIOnLoad;
 
 /**
  * A registry that holds initializers for HybridObjects.
@@ -8,12 +8,14 @@ import java.util.function.Supplier;
  * @noinspection JavaJniMissingFunction
  */
 public class HybridObjectRegistry {
+    static {
+        JNIOnLoad.initializeNativeNitro();
+    }
+
     /**
      * Registers the given HybridObject in the `HybridObjectRegistry`.
      * It will be uniquely identified via it's `hybridObjectName`, and can be initialized from
      * JS using `NitroModules.createHybridObject<T>(name)` - which will call the `constructorFn` here.
      */
     public static native void registerHybridObjectConstructor(String hybridObjectName, HybridObjectInitializer initializer);
-
-    private static final String TAG = "HybridObjectRegistry";
 }

package/android/src/main/java/com/margelo/nitro/core/Promise.kt

@@ -0,0 +1,115 @@
+package com.margelo.nitro.core
+
+import androidx.annotation.Keep
+import com.facebook.jni.HybridData
+import com.facebook.proguard.annotations.DoNotStrip
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.async
+import kotlinx.coroutines.launch
+import kotlin.concurrent.thread
+
+/**
+ * Represents a Promise that can be passed to JS.
+ *
+ * Create a new Promise with the following APIs:
+ * - [Promise.async]` { ... }` - Creates a new Promise that runs the given suspending function in a Kotlin coroutine scope.
+ * - [Promise.parallel]` { ... }` - Creates a new Promise that runs the given code in a parallel Thread.
+ * - [Promise.resolved]`(..)` - Creates a new already resolved Promise.
+ * - [Promise.rejected]`(..)` - Creates a new already rejected Promise.
+ * - [Promise]`()` - Creates a new Promise with fully manual control over the `resolve(..)`/`reject(..)` functions.
+ */
+@Suppress("KotlinJniMissingFunction")
+@Keep
+@DoNotStrip
+class Promise<T> {
+  private val mHybridData: HybridData
+
+  /**
+   * Creates a new Promise with fully manual control over the `resolve(..)`/`reject(..)` functions
+   */
+  init {
+    mHybridData = initHybrid()
+  }
+
+  /**
+   * Resolves the Promise with the given result.
+   * Any `onResolved` listeners will be invoked.
+   */
+  fun resolve(result: T) {
+    nativeResolve(result as Any)
+  }
+
+  /**
+   * Rejects the Promise with the given error.
+   * Any `onRejected` listeners will be invoked.
+   */
+  fun reject(error: Error) {
+    nativeReject(error.toString())
+  }
+
+  // C++ functions
+  private external fun nativeResolve(result: Any)
+  private external fun nativeReject(error: String)
+  private external fun initHybrid(): HybridData
+
+  companion object {
+    private val defaultScope = CoroutineScope(Dispatchers.Default)
+
+    /**
+     * Creates a new Promise that asynchronously runs the given suspending function [run]
+     * on the given coroutine scope [scope].
+     *
+     * If [scope] is omitted, the [Dispatchers.Default] scope will be used.
+     *
+     * When the suspending function returns, the Promise gets resolved. If the suspending
+     * function throws, the Promise gets rejected.
+     */
+    fun <T> async(scope: CoroutineScope = defaultScope, run: suspend () -> T): Promise<T> {
+      val promise = Promise<T>()
+      scope.launch {
+        try {
+          val result = run()
+          promise.resolve(result)
+        } catch (e: Error) {
+          promise.reject(e)
+        }
+      }
+      return promise
+    }
+
+    /**
+     * Creates a new Promise that runs the given function [run] on a separate
+     * Thread.
+     *
+     * When the function returns, the Promise gets resolved. If the
+     * function throws, the Promise gets rejected.
+     */
+    fun <T> parallel(run: () -> T): Promise<T> {
+      val promise = Promise<T>()
+      thread {
+        try {
+          val result = run()
+          promise.resolve(result)
+        } catch (e: Error) {
+          promise.reject(e)
+        }
+      }
+      return promise
+    }
+
+    /**
+     * Creates a new Promise that is already resolved with the given result.
+     */
+    fun <T> resolved(result: T): Promise<T> {
+      return Promise<T>().apply { resolve(result) }
+    }
+
+    /**
+     * Creates a new Promise that is already rejected with the given error.
+     */
+    fun <T> rejected(error: Error): Promise<T> {
+      return Promise<T>().apply { reject(error) }
+    }
+  }
+}

package/cpp/core/AnyMap.hpp

@@ -49,13 +49,13 @@ public:
 
 public:
   /**
-   * Create a new shared_ptr instance of AnyMap.
+   * Create a new `shared_ptr` instance of AnyMap.
    */
   static std::shared_ptr<AnyMap> make() {
     return std::make_shared<AnyMap>();
   }
   /**
-   * Create a new shared_ptr instance of AnyMap with the given amount of spaces pre-allocated.
+   * Create a new `shared_ptr` instance of AnyMap with the given amount of spaces pre-allocated.
    */
   static std::shared_ptr<AnyMap> make(size_t size) {
     return std::make_shared<AnyMap>(size);

package/cpp/core/ArrayBuffer.cpp

@@ -17,18 +17,18 @@ using namespace facebook;
 
 // 1. ArrayBuffer
 
-std::shared_ptr<ArrayBuffer> ArrayBuffer::makeBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext) {
-  return std::make_shared<NativeArrayBuffer>(data, size, deleteFunc, deleteFuncContext);
+std::shared_ptr<ArrayBuffer> ArrayBuffer::makeBuffer(uint8_t* data, size_t size, DeleteFn&& deleteFunc) {
+  return std::make_shared<NativeArrayBuffer>(data, size, std::move(deleteFunc));
 }
 
 // 2. NativeArrayBuffer
 
-NativeArrayBuffer::NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext)
-    : ArrayBuffer(), _data(data), _size(size), _deleteFunc(deleteFunc), _deleteFuncContext(deleteFuncContext) {}
+NativeArrayBuffer::NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn&& deleteFunc)
+    : ArrayBuffer(), _data(data), _size(size), _deleteFunc(std::move(deleteFunc)) {}
 
 NativeArrayBuffer::~NativeArrayBuffer() {
   if (_deleteFunc != nullptr) {
-    _deleteFunc(_deleteFuncContext);
+    _deleteFunc();
   }
 }
 

package/cpp/core/ArrayBuffer.hpp

@@ -15,7 +15,7 @@ namespace margelo::nitro {
 
 using namespace facebook;
 
-using DeleteFn = void (*)(void* context);
+using DeleteFn = std::function<void()>;
 
 /**
  * Represents a raw byte buffer that can be read from-, and
@@ -38,7 +38,7 @@ public:
   ArrayBuffer(const ArrayBuffer&) = delete;
   ArrayBuffer(ArrayBuffer&&) = delete;
   virtual ~ArrayBuffer() = default;
-  
+
 public:
   /**
    * Returns whether this `ArrayBuffer` is actually owning the data,
@@ -46,13 +46,13 @@ public:
    * memory that we didn't allocate, or from JS - which can be deleted at any point).
    */
   virtual bool isOwner() const noexcept = 0;
-  
+
 public:
   /**
    * Create a new `NativeArrayBuffer` that wraps the given data (without copy) of the given size,
-   * and calls `deleteFunc` with the given `deleteFuncContext` as a parameter in which `data` should be deleted.
+   * and calls `deleteFunc` in which `data` should be deleted.
    */
-  static std::shared_ptr<ArrayBuffer> makeBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext);
+  static std::shared_ptr<ArrayBuffer> makeBuffer(uint8_t* data, size_t size, DeleteFn&& deleteFunc);
 };
 
 /**
@@ -74,9 +74,9 @@ public:
    * and will only delete it once this `ArrayBuffer` gets deleted.
    *
    * Once this `ArrayBuffer` goes out of scope, `deleteFunc` will be called.
-   * The caller is responsible for deleting the memory (`data` and `deleteFuncContext`) here.
+   * The caller is responsible for deleting the memory (`data`) here.
    */
-  NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext);
+  NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn&& deleteFunc);
   ~NativeArrayBuffer();
 
 public:
@@ -84,8 +84,6 @@ public:
   size_t size() const override;
   bool isOwner() const noexcept override;
 
-  double something();
-
 private:
   uint8_t* _data;
   size_t _size;

package/cpp/core/HybridFunction.hpp

@@ -26,19 +26,19 @@ namespace margelo::nitro {
 using namespace facebook;
 
 /**
- * Represents the type of a function - it can be either a normal function ("METHOD"),
+ * Represents the kind of a function - it can be either a normal function ("METHOD"),
  * or a property ("GETTER" + "SETTER")
  */
-enum class FunctionType { METHOD, GETTER, SETTER };
+enum class FunctionKind { METHOD, GETTER, SETTER };
 
 /**
  * Represents a Hybrid Function.
  */
 class HybridFunction final {
 private:
-  std::string _name;
-  size_t _paramCount;
   jsi::HostFunctionType _function;
+  size_t _paramCount;
+  std::string _name;
 
 public:
   // getters
@@ -69,30 +69,14 @@ public:
    * and assumes that the object this is called on has a proper `this` configured.
    * The object's `this` needs to be a `NativeState`.
    */
-  template <typename Derived, typename ReturnType, typename... Args>
-  static inline HybridFunction createHybridFunction(const std::string& name, ReturnType (Derived::*method)(Args...), FunctionType type) {
-    jsi::HostFunctionType hostFunction = [name, method, type](/* JS Runtime */ jsi::Runtime& runtime,
+  template <typename THybrid, typename ReturnType, typename... Args>
+  static inline HybridFunction createHybridFunction(const std::string& name, ReturnType (THybrid::*method)(Args...), FunctionKind kind) {
+    jsi::HostFunctionType hostFunction = [name, method, kind](/* JS Runtime */ jsi::Runtime& runtime,
                                                               /* HybridObject */ const jsi::Value& thisValue,
                                                               /* JS arguments */ const jsi::Value* args,
                                                               /* argument size */ size_t count) -> jsi::Value {
-    // 1. Get actual `HybridObject` instance from `thisValue` (it's stored as `NativeState`)
-#if DEBUG
-      if (!thisValue.isObject()) [[unlikely]] {
-        throw jsi::JSError(runtime, "Cannot call hybrid function " + name + "(...) - `this` is not bound!");
-      }
-#endif
-      jsi::Object thisObject = thisValue.getObject(runtime);
-
-#if DEBUG
-      if (!thisObject.hasNativeState<Derived>(runtime)) [[unlikely]] {
-        if (thisObject.hasNativeState(runtime)) {
-          throw jsi::JSError(runtime, "Cannot call hybrid function " + name + "(...) - `this` has a NativeState, but it's the wrong type!");
-        } else {
-          throw jsi::JSError(runtime, "Cannot call hybrid function " + name + "(...) - `this` does not have a NativeState!");
-        }
-      }
-#endif
-      std::shared_ptr<Derived> hybridInstance = thisObject.getNativeState<Derived>(runtime);
+      // 1. Get actual `HybridObject` instance from `thisValue` (it's stored as `NativeState`)
+      std::shared_ptr<THybrid> hybridInstance = getHybridObjectNativeState<THybrid>(runtime, thisValue, kind, name);
 
       // 2. Make sure the given arguments match, either with a static size, or with potentially optional arguments size.
       constexpr size_t optionalArgsCount = trailing_optionals_count_v<Args...>;
@@ -101,47 +85,62 @@ public:
       bool isWithinArgsRange = (count >= minArgsCount && count <= maxArgsCount);
       if (!isWithinArgsRange) [[unlikely]] {
         // invalid amount of arguments passed!
-        std::string hybridObjectName = hybridInstance->getName();
+        std::string funcName = getHybridFuncFullName<THybrid>(kind, name, hybridInstance.get());
         if constexpr (minArgsCount == maxArgsCount) {
           // min and max args length is the same, so we don't have any optional parameters. fixed count
-          throw jsi::JSError(runtime, hybridObjectName + "." + name + "(...) expected " + std::to_string(maxArgsCount) +
-                                          " arguments, but received " + std::to_string(count) + "!");
+          throw jsi::JSError(runtime, "`" + funcName + "` expected " + std::to_string(maxArgsCount) + " arguments, but received " +
+                                          std::to_string(count) + "!");
         } else {
           // min and max args length are different, so we have optional parameters - variable length arguments.
-          throw jsi::JSError(runtime, hybridObjectName + "." + name + "(...) expected between " + std::to_string(minArgsCount) + " and " +
+          throw jsi::JSError(runtime, "`" + funcName + "` expected between " + std::to_string(minArgsCount) + " and " +
                                           std::to_string(maxArgsCount) + " arguments, but received " + std::to_string(count) + "!");
         }
       }
 
-      // 3. Actually call method - either raw JSI method, or by going through `JSIConverter<T>` first.
       try {
-        if constexpr (std::is_same_v<ReturnType, jsi::Value>) {
-          // If the return type is a jsi::Value, we assume the user wants full JSI code control.
-          // The signature must be identical to jsi::HostFunction (jsi::Runtime&, jsi::Value& this, ...)
-          return (hybridInstance->*method)(runtime, thisValue, args, count);
-        } else {
-          // Call the actual method with JSI values as arguments and return a JSI value again.
-          // Internally, this method converts the JSI values to C++ values.
-          return callMethod(hybridInstance.get(), method, runtime, args, count, std::index_sequence_for<Args...>{});
-        }
+        // 3. Actually call the method with JSI values as arguments and return a JSI value again.
+        //    Internally, this method converts the JSI values to C++ values using `JSIConverter<T>`.
+        return callMethod(hybridInstance.get(), method, runtime, args, count, std::index_sequence_for<Args...>{});
       } catch (const std::exception& exception) {
         // Some exception was thrown - add method name information and re-throw as `JSError`.
-        std::string hybridObjectName = hybridInstance->getName();
+        std::string funcName = getHybridFuncFullName<THybrid>(kind, name, hybridInstance.get());
         std::string message = exception.what();
-        std::string suffix = type == FunctionType::METHOD ? "(...)" : "";
-        throw jsi::JSError(runtime, hybridObjectName + "." + name + suffix + ": " + message);
+        throw jsi::JSError(runtime, funcName + ": " + message);
       } catch (...) {
         // Some unknown exception was thrown - add method name information and re-throw as `JSError`.
-        std::string hybridObjectName = hybridInstance->getName();
+        std::string funcName = getHybridFuncFullName<THybrid>(kind, name, hybridInstance.get());
         std::string errorName = TypeInfo::getCurrentExceptionName();
-        std::string suffix = type == FunctionType::METHOD ? "(...)" : "";
-        throw jsi::JSError(runtime, hybridObjectName + "." + name + suffix + " threw an unknown " + errorName + " error.");
+        throw jsi::JSError(runtime, "`" + funcName + "` threw an unknown " + errorName + " error.");
       }
     };
 
     return HybridFunction(std::move(hostFunction), sizeof...(Args), name);
   }
 
+  /**
+   * Create a new `HybridFunction` that can be called from JS.
+   * Unlike `createHybridFunction(...)`, this method does **not** perform any argument parsing or size checking.
+   * It is a raw-, untyped JSI method, and the user is expected to manually handle arguments and return values.
+   */
+  template <typename Derived>
+  static inline HybridFunction createRawHybridFunction(const std::string& name, size_t expectedArgumentsCount,
+                                                       jsi::Value (Derived::*method)(jsi::Runtime& runtime, const jsi::Value& thisArg,
+                                                                                     const jsi::Value* args, size_t count)) {
+    jsi::HostFunctionType hostFunction = [name, method](/* JS Runtime */ jsi::Runtime& runtime,
+                                                        /* HybridObject */ const jsi::Value& thisValue,
+                                                        /* JS arguments */ const jsi::Value* args,
+                                                        /* argument size */ size_t count) -> jsi::Value {
+      // 1. Get actual `HybridObject` instance from `thisValue` (it's stored as `NativeState`)
+      std::shared_ptr<Derived> hybridInstance = getHybridObjectNativeState<Derived>(runtime, thisValue, FunctionKind::METHOD, name);
+
+      // 2. Call the raw JSI method using raw JSI Values. Exceptions are also expected to be handled by the user.
+      Derived* pointer = hybridInstance.get();
+      return (pointer->*method)(runtime, thisValue, args, count);
+    };
+
+    return HybridFunction(std::move(hostFunction), expectedArgumentsCount, name);
+  }
+
 private:
   /**
    * Calls the given method on the given instance with the given `jsi::Value` arguments by converting them to the desired target types.
@@ -159,7 +158,82 @@ private:
     } else {
       // It's returning some C++ type, we need to convert that to a JSI value now.
       ReturnType result = (obj->*method)(JSIConverter<std::decay_t<Args>>::fromJSI(runtime, Is < argsSize ? args[Is] : defaultValue)...);
-      return JSIConverter<std::decay_t<ReturnType>>::toJSI(runtime, std::move(result));
+      return JSIConverter<ReturnType>::toJSI(runtime, std::forward<ReturnType>(result));
+    }
+  }
+
+private:
+  /**
+   * Get the `NativeState` of the given `value`.
+   */
+  template <typename THybrid>
+  static inline std::shared_ptr<THybrid> getHybridObjectNativeState(jsi::Runtime& runtime, const jsi::Value& value, FunctionKind funcKind,
+                                                                    const std::string& funcName) {
+    // 1. Convert jsi::Value to jsi::Object
+#ifndef NDEBUG
+    if (!value.isObject()) [[unlikely]] {
+      throw jsi::JSError(runtime, "Cannot " + getHybridFuncDebugInfo<THybrid>(funcKind, funcName) + " - `this` is not bound!");
+    }
+#endif
+    jsi::Object object = value.getObject(runtime);
+
+    // 2. Check if it even has any kind of `NativeState`
+#ifndef NDEBUG
+    if (!object.hasNativeState(runtime)) [[unlikely]] {
+      throw jsi::JSError(runtime, "Cannot " + getHybridFuncDebugInfo<THybrid>(funcKind, funcName) +
+                                      " - `this` does not have a NativeState! Suggestions:\n"
+                                      "- Did you accidentally destructure the `HybridObject` and lose a reference to the original object?\n"
+                                      "- Did you call `dispose()` on the `HybridObject` before?"
+                                      "- Did you accidentally call `" +
+                                      funcName + "` on the prototype directly?\n");
+    }
+#endif
+
+    // 3. Get `NativeState` from the jsi::Object and check if it is non-null
+    std::shared_ptr<jsi::NativeState> nativeState = object.getNativeState(runtime);
+#ifndef NDEBUG
+    if (nativeState == nullptr) [[unlikely]] {
+      throw jsi::JSError(runtime, "Cannot " + getHybridFuncDebugInfo<THybrid>(funcKind, funcName) +
+                                      " - `this`'s `NativeState` is `nullptr`, "
+                                      "did you accidentally call `dispose()` on this object?");
+    }
+#endif
+
+    // 4. Try casting it to our desired target type.
+    std::shared_ptr<THybrid> hybridInstance = std::dynamic_pointer_cast<THybrid>(nativeState);
+#ifndef NDEBUG
+    if (hybridInstance == nullptr) [[unlikely]] {
+      throw jsi::JSError(runtime, "Cannot " + getHybridFuncDebugInfo<THybrid>(funcKind, funcName) +
+                                      " - `this` has a NativeState, but it's the wrong type!");
+    }
+#endif
+    return hybridInstance;
+  }
+
+private:
+  template <typename THybrid>
+  static inline std::string getHybridFuncFullName(FunctionKind kind, const std::string& registrationName,
+                                                  THybrid* hybridInstance = nullptr) {
+    std::string typeName = hybridInstance != nullptr ? hybridInstance->getName() : TypeInfo::getFriendlyTypenameNoNamespace<THybrid>();
+    switch (kind) {
+      case FunctionKind::METHOD:
+        return typeName + "." + registrationName + "(...)";
+      case FunctionKind::GETTER:
+      case FunctionKind::SETTER:
+        return typeName + "." + registrationName;
+    }
+  }
+  template <typename THybrid>
+  static inline std::string getHybridFuncDebugInfo(FunctionKind kind, const std::string& registrationName,
+                                                   THybrid* hybridInstance = nullptr) {
+    auto funcName = getHybridFuncFullName<THybrid>(kind, registrationName, hybridInstance);
+    switch (kind) {
+      case FunctionKind::METHOD:
+        return "call hybrid function `" + funcName + "`";
+      case FunctionKind::GETTER:
+        return "get hybrid property `" + funcName + "`";
+      case FunctionKind::SETTER:
+        return "set hybrid property `" + funcName + "`";
     }
   }
 };