react-native-nitro-modules 0.1.3 → 0.1.5

package/NitroModules.podspec

@@ -28,14 +28,16 @@ Pod::Spec.new do |s|
   ]
   s.public_header_files = [
     # Public C++ headers will be exposed in modulemap (for Swift)
+    "cpp/core/AnyMap.hpp",
     "cpp/core/ArrayBuffer.hpp",
     "cpp/core/HybridObject.hpp",
-    "cpp/core/HybridContext.hpp",
     "cpp/registry/HybridObjectRegistry.hpp",
     "cpp/jsi/JSIConverter.hpp",
     "cpp/threading/Dispatcher.hpp",
     "cpp/utils/NitroHash.hpp",
     "cpp/utils/NitroDefines.hpp",
+    # Public iOS-specific headers that will be exposed in modulemap (for Swift)
+    "ios/core/HybridContext.hpp"
   ]
 
   s.pod_target_xcconfig = {

package/android/src/main/cpp/platform/ThreadUtils.cpp

@@ -9,6 +9,7 @@
 #include <pthread.h>
 #include <sstream>
 #include <string>
+#include <sys/prctl.h>
 #include <thread>
 
 namespace margelo::nitro {
@@ -32,4 +33,8 @@ std::string ThreadUtils::getThreadName() {
   return "Thread #" + threadId;
 }
 
+void ThreadUtils::setThreadName(const std::string& name) {
+  prctl(PR_SET_NAME, name.c_str(), 0, 0, 0);
+}
+
 } // namespace margelo::nitro

package/cpp/core/AnyMap.hpp

@@ -9,6 +9,7 @@
 #include <string>
 #include <unordered_map>
 #include <variant>
+#include <vector>
 
 namespace margelo::nitro {
 
@@ -33,7 +34,7 @@ struct AnyValue : VariantType {
  * 2. Arrays of primitives
  * 3. Objects of primitives
  */
-class AnyMap {
+class AnyMap final {
 public:
   /**
    * Create a new instance of AnyMap.

package/cpp/core/ArrayBuffer.hpp

@@ -7,8 +7,10 @@
 
 #pragma once
 
+#include "OwningReference.hpp"
 #include <functional>
 #include <jsi/jsi.h>
+#include <thread>
 
 namespace margelo::nitro {
 
@@ -23,50 +25,76 @@ static DeleteFn defaultDeleteFn = [](uint8_t* buffer) { delete[] buffer; };
  * written to- from both JavaScript and C++.
  * `ArrayBuffer` is not thread-safe and does not lock multi-thread access.
  *
- * Also, if `ArrayBuffer` is coming from JS, it is not safe to keep a strong
- * reference on `ArrayBuffer` as C++ does not own the data (`isOwner() == false`) -
- * it can be deleted at any point without C++ knowing about it.
+ * `ArrayBuffer` can either be a `JSArrayBuffer`, or a `NativeArrayBuffer`.
+ * - `NativeArrayBuffer`: Created from native (C++), and can either own the memory (`isOwner()`), or borrow it.
+ * - `JSArrayBuffer`: Received from JS, and will only be alive for as long as the JS Runtime is actually alive.
  *
- * Only if C++ creates the `ArrayBuffer` a reference to it can be safely
- * kept in memory, as C++ is then the owner of `ArrayBuffer` (`isOwner() == true`).
+ * Also, an `ArrayBuffer` can either own it's memory, or just borrow it's memory.
+ * - Owning = the `ArrayBuffer`'s `data()` is alive as long as the `ArrayBuffer` is alive.
+ *   When this `ArrayBuffer` gets deleted, it will free the memory.
+ * - Borrowed = the `ArrayBuffer`'s `data()` might be deleted at any point from an external source (e.g. the JS garbage collector).
+ *   When this `ArrayBuffer` gets deleted, the memory will not be freed explicitly, as someone else owns it.
  */
 class ArrayBuffer : public jsi::MutableBuffer {
+public:
+  ArrayBuffer() = default;
+  ArrayBuffer(const ArrayBuffer&) = delete;
+  ArrayBuffer(ArrayBuffer&&) = delete;
+  virtual ~ArrayBuffer() = default;
+
+public:
+  /**
+   * Returns whether this `ArrayBuffer` is actually owning the data,
+   * or if it is just borrowed from an external source (either a native
+   * memory that we didn't allocate, or from JS - which can be deleted at any point).
+   */
+  virtual bool isOwner() const noexcept = 0;
+};
+
+/**
+ * Represents an `ArrayBuffer` that is allocated on the native (C++) side.
+ * It can either be "owning" or "borrowing".
+ *
+ * - Owning = the `ArrayBuffer`'s `data()` is alive as long as the `ArrayBuffer` is alive.
+ *   When this `ArrayBuffer` gets deleted, it will free the memory.
+ * - Borrowed = the `ArrayBuffer`'s `data()` might be deleted at any point from an external source (e.g. the JS garbage collector).
+ *   When this `ArrayBuffer` gets deleted, the memory will not be freed explicitly, as someone else owns it.
+ *
+ * It is safe to access `data()` and `size()` from any Thread, but there are no synchronization/mutexes implemented by default.
+ */
+class NativeArrayBuffer : public ArrayBuffer {
 public:
   /**
    * Create a new **owning** `ArrayBuffer`.
    * The `ArrayBuffer` can be kept in memory, as C++ owns the data
    * and will only delete it once this `ArrayBuffer` gets deleted
    */
-  ArrayBuffer(uint8_t* data, size_t size, DeleteFn&& deleteFunc) : _data(data), _size(size), _deleteFunc(std::move(deleteFunc)) {}
+  NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn&& deleteFunc)
+      : ArrayBuffer(), _data(data), _size(size), _deleteFunc(std::move(deleteFunc)) {}
   /**
    * Create a new `ArrayBuffer`.
    * If `destroyOnDeletion` is `true`, the `ArrayBuffer` is **owning**, otherwise it is **non-owning**.
    * The `ArrayBuffer` can only be safely kept in memory if it is owning (`isOwning()`).
    */
-  ArrayBuffer(uint8_t* data, size_t size, bool destroyOnDeletion) : _data(data), _size(size) {
+  NativeArrayBuffer(uint8_t* data, size_t size, bool destroyOnDeletion) : ArrayBuffer(), _data(data), _size(size) {
     _deleteFunc = destroyOnDeletion ? defaultDeleteFn : nullptr;
   }
 
-  // ArrayBuffer cannot be copied
-  ArrayBuffer(const ArrayBuffer&) = delete;
-  // ArrayBuffer cannot be moved
-  ArrayBuffer(ArrayBuffer&&) = delete;
-
-  ~ArrayBuffer() {
+  ~NativeArrayBuffer() {
     if (_deleteFunc != nullptr) {
       _deleteFunc(_data);
     }
   }
 
-  uint8_t* data() noexcept override {
+  uint8_t* data() override {
     return _data;
   }
 
-  size_t size() const noexcept override {
+  size_t size() const override {
     return _size;
   }
 
-  bool isOwner() const noexcept {
+  bool isOwner() const noexcept override {
     return _deleteFunc != nullptr;
   }
 
@@ -76,4 +104,68 @@ private:
   DeleteFn _deleteFunc;
 };
 
+/**
+ * Represents a JS-based `ArrayBuffer`.
+ *
+ * While it's underlying data might have been allocated on the native side (`NativeArrayBuffer`),
+ * we only have a JS reference to the `ArrayBuffer` object so it is considered a "borrowed"-resource.
+ *
+ * `data()` and `size()` can only be accessed synchronously on the JS Runtime Thread.
+ * If you want to access it elsewhere, copy the buffer first.
+ *
+ * If the JS ArrayBuffer (or it's JS Runtime) have already been deleted, `data()` returns `nullptr`.
+ */
+class JSArrayBuffer : public ArrayBuffer {
+public:
+  explicit JSArrayBuffer(jsi::Runtime* runtime, OwningReference<jsi::ArrayBuffer> jsReference)
+      : ArrayBuffer(), _runtime(runtime), _jsReference(jsReference), _initialThreadId(std::this_thread::get_id()) {}
+  ~JSArrayBuffer() {}
+
+public:
+  /**
+   * Gets the data this `ArrayBuffer` points to, or `nullptr` if it has already been deleted.
+   */
+  uint8_t* data() override {
+    if (_initialThreadId != std::this_thread::get_id()) [[unlikely]] {
+      throw std::runtime_error("`data()` can only be accessed synchronously on the JS Thread! "
+                               "If you want to access it elsewhere, copy it first.");
+    }
+
+    OwningLock<jsi::ArrayBuffer> lock = _jsReference.lock();
+    if (!_jsReference) [[unlikely]] {
+      // JS Part has been deleted - data is now nullptr.
+      return nullptr;
+    }
+    // JS Part is still alive - we can assume that the jsi::Runtime is safe to access here too.
+    return _jsReference->data(*_runtime);
+  }
+
+  /**
+   * Gets the size of the data this `ArrayBuffer` points to, or `0` if it has already been deleted.
+   */
+  size_t size() const override {
+    if (_initialThreadId != std::this_thread::get_id()) [[unlikely]] {
+      throw std::runtime_error("`size()` can only be accessed synchronously on the JS Thread! "
+                               "If you want to access it elsewhere, copy it first.");
+    }
+
+    OwningLock<jsi::ArrayBuffer> lock = _jsReference.lock();
+    if (!_jsReference) [[unlikely]] {
+      // JS Part has been deleted - size is now 0.
+      return 0;
+    }
+    // JS Part is still alive - we can assume that the jsi::Runtime is safe to access here too.
+    return _jsReference->size(*_runtime);
+  }
+
+  bool isOwner() const noexcept override {
+    return false;
+  }
+
+private:
+  jsi::Runtime* _runtime;
+  OwningReference<jsi::ArrayBuffer> _jsReference;
+  std::thread::id _initialThreadId;
+};
+
 } // namespace margelo::nitro

package/cpp/core/HybridObject.hpp

@@ -5,10 +5,9 @@
 #pragma once
 
 #include "CountTrailingOptionals.hpp"
-#include "HybridContext.hpp"
 #include "JSIConverter.hpp"
-#include "NitroLogger.hpp"
 #include "OwningReference.hpp"
+#include "TypeInfo.hpp"
 #include <functional>
 #include <jsi/jsi.h>
 #include <memory>
@@ -176,10 +175,10 @@ private:
       constexpr size_t maxArgsCount = sizeof...(Args);
       constexpr size_t minArgsCount = maxArgsCount - optionalArgsCount;
       bool isWithinArgsRange = (count >= minArgsCount && count <= maxArgsCount);
-      if (!isWithinArgsRange) {
+      if (!isWithinArgsRange) [[unlikely]] {
         // invalid amount of arguments passed!
         std::string hybridObjectName = derivedInstance->_name;
-        if (minArgsCount == maxArgsCount) {
+        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) + "!");

package/cpp/jsi/JSIConverter+AnyMap.hpp

@@ -0,0 +1,64 @@
+//
+// Created by Marc Rousavy on 21.02.24.
+//
+
+#pragma once
+
+// Forward declare a few of the common types that might have cyclic includes.
+namespace margelo::nitro {
+struct AnyValue;
+class AnyMap;
+
+template <typename T, typename Enable>
+struct JSIConverter;
+} // namespace margelo::nitro
+
+#include "JSIConverter+Variant.hpp"
+#include "JSIConverter.hpp"
+
+#include "AnyMap.hpp"
+#include <jsi/jsi.h>
+#include <memory>
+
+namespace margelo::nitro {
+
+using namespace facebook;
+
+// AnyValue <> Record<K, V>
+template <>
+struct JSIConverter<AnyValue> {
+  static inline AnyValue fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+    return JSIConverter<AnyValue::variant>::fromJSI(runtime, arg);
+  }
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, const AnyValue& value) {
+    return JSIConverter<AnyValue::variant>::toJSI(runtime, value);
+  }
+};
+
+// AnyMap <> Record<K, V>
+template <>
+struct JSIConverter<std::shared_ptr<AnyMap>> {
+  static inline std::shared_ptr<AnyMap> fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+    jsi::Object object = arg.asObject(runtime);
+    jsi::Array propNames = object.getPropertyNames(runtime);
+    size_t size = propNames.size(runtime);
+    std::shared_ptr<AnyMap> map = AnyMap::make();
+    for (size_t i = 0; i < size; i++) {
+      jsi::String jsKey = propNames.getValueAtIndex(runtime, i).getString(runtime);
+      jsi::Value jsValue = object.getProperty(runtime, jsKey);
+      map->setAny(jsKey.utf8(runtime), JSIConverter<AnyValue>::fromJSI(runtime, jsValue));
+    }
+    return map;
+  }
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, std::shared_ptr<AnyMap> map) {
+    jsi::Object object(runtime);
+    for (const auto& item : map->getMap()) {
+      jsi::String key = jsi::String::createFromUtf8(runtime, item.first);
+      jsi::Value value = JSIConverter<AnyValue>::toJSI(runtime, item.second);
+      object.setProperty(runtime, std::move(key), std::move(value));
+    }
+    return object;
+  }
+};
+
+} // namespace margelo::nitro

package/cpp/jsi/JSIConverter+ArrayBuffer.hpp

@@ -0,0 +1,50 @@
+//
+// Created by Marc Rousavy on 21.02.24.
+//
+
+#pragma once
+
+// Forward declare a few of the common types that might have cyclic includes.
+namespace margelo::nitro {
+class ArrayBuffer;
+
+template <typename T>
+struct JSICache;
+
+template <typename T, typename Enable>
+struct JSIConverter;
+} // namespace margelo::nitro
+
+#include "JSIConverter.hpp"
+
+#include "ArrayBuffer.hpp"
+#include "IsSharedPtrTo.hpp"
+#include "JSICache.hpp"
+#include <jsi/jsi.h>
+#include <memory>
+#include <type_traits>
+
+namespace margelo::nitro {
+
+using namespace facebook;
+
+// MutableBuffer <> ArrayBuffer
+template <typename T>
+struct JSIConverter<T, std::enable_if_t<is_shared_ptr_to_v<T, jsi::MutableBuffer>>> {
+  static inline std::shared_ptr<ArrayBuffer> fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+    jsi::Object object = arg.asObject(runtime);
+    if (!object.isArrayBuffer(runtime)) [[unlikely]] {
+      throw std::runtime_error("Object \"" + arg.toString(runtime).utf8(runtime) + "\" is not an ArrayBuffer!");
+    }
+
+    JSICacheReference<jsi::ArrayBuffer> cache = JSICache<jsi::ArrayBuffer>::getOrCreateCache(runtime);
+    auto owningArrayBuffer = cache.makeGlobal(object.getArrayBuffer(runtime));
+
+    return std::make_shared<JSArrayBuffer>(&runtime, owningArrayBuffer);
+  }
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, std::shared_ptr<jsi::MutableBuffer> buffer) {
+    return jsi::ArrayBuffer(runtime, buffer);
+  }
+};
+
+} // namespace margelo::nitro

package/cpp/jsi/JSIConverter+Function.hpp

@@ -0,0 +1,124 @@
+//
+// Created by Marc Rousavy on 21.02.24.
+//
+
+#pragma once
+
+// Forward declare a few of the common types that might have cyclic includes.
+namespace margelo::nitro {
+template <typename T>
+class JSICache;
+
+template <typename T, typename Enable>
+struct JSIConverter;
+} // namespace margelo::nitro
+
+#include "JSIConverter.hpp"
+
+#include "Dispatcher.hpp"
+#include "FutureType.hpp"
+#include "JSICache.hpp"
+#include <functional>
+#include <future>
+#include <jsi/jsi.h>
+
+namespace margelo::nitro {
+
+using namespace facebook;
+
+// [](Args...) -> T {} <> (Args...) => T
+template <typename ReturnType, typename... Args>
+struct JSIConverter<std::function<ReturnType(Args...)>> {
+  // std::future<T> -> T
+  using ResultingType = future_type_v<ReturnType>;
+
+  static inline std::function<ReturnType(Args...)> fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+    // Make function global - it'll be managed by the Runtime's memory, and we only have a weak_ref to it.
+    auto cache = JSICache<jsi::Function>::getOrCreateCache(runtime);
+    jsi::Function function = arg.asObject(runtime).asFunction(runtime);
+    OwningReference<jsi::Function> sharedFunction = cache.makeGlobal(std::move(function));
+
+    std::shared_ptr<Dispatcher> strongDispatcher = Dispatcher::getRuntimeGlobalDispatcher(runtime);
+    std::weak_ptr<Dispatcher> weakDispatcher = strongDispatcher;
+
+    // Create a C++ function that can be called by the consumer.
+    // This will call the jsi::Function if it is still alive.
+    return [&runtime, weakDispatcher, sharedFunction = std::move(sharedFunction)](Args... args) -> ReturnType {
+      // Try to get the JS Dispatcher if the Runtime is still alive
+      std::shared_ptr<Dispatcher> dispatcher = weakDispatcher.lock();
+      if (!dispatcher) {
+        if constexpr (std::is_void_v<ResultingType>) {
+          Logger::log("JSIConverter", "Tried calling void(..) function, but the JS Dispatcher has already been deleted by JS!");
+          return;
+        } else {
+          throw std::runtime_error("Cannot call the given Function - the JS Dispatcher has already been destroyed by the JS Runtime!");
+        }
+      }
+
+      if constexpr (std::is_void_v<ResultingType>) {
+        dispatcher->runAsync([&runtime, sharedFunction = std::move(sharedFunction), ... args = std::move(args)]() {
+          callJSFunction(runtime, sharedFunction, args...);
+        });
+      } else {
+        return dispatcher->runAsyncAwaitable<ResultingType>(
+            [&runtime, sharedFunction = std::move(sharedFunction), ... args = std::move(args)]() -> ResultingType {
+              return callJSFunction(runtime, sharedFunction, args...);
+            });
+      }
+    };
+  }
+
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, std::function<ReturnType(Args...)>&& function) {
+    jsi::HostFunctionType jsFunction = [function = std::move(function)](jsi::Runtime& runtime, const jsi::Value& thisValue,
+                                                                        const jsi::Value* args, size_t count) -> jsi::Value {
+      if (count != sizeof...(Args)) [[unlikely]] {
+        throw jsi::JSError(runtime, "Function expected " + std::to_string(sizeof...(Args)) + " arguments, but received " +
+                                        std::to_string(count) + "!");
+      }
+      return callHybridFunction(function, runtime, args, std::index_sequence_for<Args...>{});
+    };
+    return jsi::Function::createFromHostFunction(runtime, jsi::PropNameID::forUtf8(runtime, "hostFunction"), sizeof...(Args), jsFunction);
+  }
+
+private:
+  static inline ResultingType callJSFunction(jsi::Runtime& runtime, const OwningReference<jsi::Function>& function, const Args&... args) {
+    // Throw a lock on the OwningReference<T> so we can guarantee safe access (Hermes GC cannot delete it while `lock` is alive)
+    OwningLock<jsi::Function> lock = function.lock();
+
+    if (!function) {
+      if constexpr (std::is_void_v<ResultingType>) {
+        // runtime has already been deleted. since this returns void, we can just ignore it being deleted.
+        Logger::log("JSIConverter", "Tried calling void(..) function, but it has already been deleted by JS!");
+        return;
+      } else {
+        // runtime has already been deleted, but we are expecting a return value - throw an error in this case.
+        throw std::runtime_error("Cannot call the given Function - the JS Dispatcher has already been destroyed by the JS Runtime!");
+      }
+    }
+
+    if constexpr (std::is_void_v<ResultingType>) {
+      // It returns void. Just call the function
+      function->call(runtime, JSIConverter<std::decay_t<Args>>::toJSI(runtime, args)...);
+    } else {
+      // It returns some kind of value - call the function, and convert the return value.
+      jsi::Value result = function->call(runtime, JSIConverter<std::decay_t<Args>>::toJSI(runtime, args)...);
+      return JSIConverter<ResultingType>::fromJSI(runtime, std::move(result));
+    }
+  }
+
+  template <size_t... Is>
+  static inline jsi::Value callHybridFunction(const std::function<ReturnType(Args...)>& function, jsi::Runtime& runtime,
+                                              const jsi::Value* args, std::index_sequence<Is...>) {
+    if constexpr (std::is_void_v<ReturnType>) {
+      // it is a void function (will return undefined in JS)
+      function(JSIConverter<std::decay_t<Args>>::fromJSI(runtime, args[Is])...);
+      return jsi::Value::undefined();
+    } else {
+      // it is a custom type, parse it to a JS value
+      ReturnType result = function(JSIConverter<std::decay_t<Args>>::fromJSI(runtime, args[Is])...);
+      return JSIConverter<ReturnType>::toJSI(runtime, result);
+    }
+  }
+};
+
+} // namespace margelo::nitro

package/cpp/jsi/JSIConverter+HybridObject.hpp

@@ -0,0 +1,130 @@
+//
+// Created by Marc Rousavy on 21.02.24.
+//
+
+#pragma once
+
+// Forward declare a few of the common types that might have cyclic includes.
+namespace margelo::nitro {
+class HybridObject;
+
+template <typename T, typename Enable>
+struct JSIConverter;
+} // namespace margelo::nitro
+
+#include "JSIConverter.hpp"
+
+#include "HybridObject.hpp"
+#include "IsSharedPtrTo.hpp"
+#include "TypeInfo.hpp"
+#include <jsi/jsi.h>
+#include <memory>
+#include <type_traits>
+
+#define DO_NULL_CHECKS true
+
+namespace margelo::nitro {
+
+using namespace facebook;
+
+// HybridObject <> {}
+template <typename T>
+struct JSIConverter<T, std::enable_if_t<is_shared_ptr_to_v<T, jsi::HostObject>>> {
+  using TPointee = typename T::element_type;
+
+  static inline T fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+#if DO_NULL_CHECKS
+    if (arg.isUndefined()) [[unlikely]] {
+      throw jsi::JSError(runtime, invalidTypeErrorMessage("undefined", "It is undefined!"));
+    }
+    if (!arg.isObject()) [[unlikely]] {
+      std::string stringRepresentation = arg.toString(runtime).utf8(runtime);
+      throw jsi::JSError(runtime, invalidTypeErrorMessage(stringRepresentation, "It is not an object!"));
+    }
+#endif
+    jsi::Object object = arg.asObject(runtime);
+#if DO_NULL_CHECKS
+    if (!object.isHostObject(runtime)) [[unlikely]] {
+      std::string stringRepresentation = arg.toString(runtime).utf8(runtime);
+      throw jsi::JSError(runtime, invalidTypeErrorMessage(stringRepresentation, "It is not a HostObject!"));
+    }
+    if (!object.isHostObject<TPointee>(runtime)) [[unlikely]] {
+      std::string stringRepresentation = arg.toString(runtime).utf8(runtime);
+      throw jsi::JSError(runtime, invalidTypeErrorMessage(stringRepresentation, "It is a different HostObject<T>!"));
+    }
+#endif
+    return object.asHostObject<TPointee>(runtime);
+  }
+
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, const T& arg) {
+#if DO_NULL_CHECKS
+    if (arg == nullptr) [[unlikely]] {
+      std::string typeName = TypeInfo::getFriendlyTypename<TPointee>();
+      throw jsi::JSError(runtime, "Cannot convert nullptr to HostObject<" + typeName + ">!");
+    }
+#endif
+    if constexpr (std::is_base_of_v<HybridObject, TPointee>) {
+      // It's a HybridObject - use it's internal constructor which caches jsi::Objects for proper memory management!
+      return arg->toObject(runtime);
+    } else {
+      // It's any other kind of jsi::HostObject - just create it as normal.
+      return jsi::Object::createFromHostObject(runtime, arg);
+    }
+  }
+
+private:
+  static inline std::string invalidTypeErrorMessage(const std::string& typeDescription, const std::string& reason) {
+    std::string typeName = TypeInfo::getFriendlyTypename<TPointee>();
+    return "Cannot convert \"" + typeDescription + "\" to HostObject<" + typeName + ">! " + reason;
+  }
+};
+
+// NativeState <> {}
+template <typename T>
+struct JSIConverter<T, std::enable_if_t<is_shared_ptr_to_v<T, jsi::NativeState>>> {
+  using TPointee = typename T::element_type;
+
+  static inline T fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+#if DO_NULL_CHECKS
+    if (arg.isUndefined()) [[unlikely]] {
+      throw jsi::JSError(runtime, invalidTypeErrorMessage("undefined", "It is undefined!"));
+    }
+    if (!arg.isObject()) [[unlikely]] {
+      std::string stringRepresentation = arg.toString(runtime).utf8(runtime);
+      throw jsi::JSError(runtime, invalidTypeErrorMessage(stringRepresentation, "It is not an object!"));
+    }
+#endif
+    jsi::Object object = arg.asObject(runtime);
+#if DO_NULL_CHECKS
+    if (!object.hasNativeState(runtime)) [[unlikely]] {
+      std::string stringRepresentation = arg.toString(runtime).utf8(runtime);
+      throw jsi::JSError(runtime, invalidTypeErrorMessage(stringRepresentation, "It is not a NativeState!"));
+    }
+    if (!object.hasNativeState<TPointee>(runtime)) [[unlikely]] {
+      std::string stringRepresentation = arg.toString(runtime).utf8(runtime);
+      throw jsi::JSError(runtime, invalidTypeErrorMessage(stringRepresentation, "It is a different NativeState<T>!"));
+    }
+#endif
+    return object.getNativeState<TPointee>(runtime);
+  }
+
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, const T& arg) {
+#if DO_NULL_CHECKS
+    if (arg == nullptr) [[unlikely]] {
+      std::string typeName = TypeInfo::getFriendlyTypename<TPointee>();
+      throw jsi::JSError(runtime, "Cannot convert nullptr to NativeState<" + typeName + ">!");
+    }
+#endif
+    jsi::Object object(runtime);
+    object.setNativeState(runtime, arg);
+    return object;
+  }
+
+private:
+  static inline std::string invalidTypeErrorMessage(const std::string& typeDescription, const std::string& reason) {
+    std::string typeName = TypeInfo::getFriendlyTypename<TPointee>();
+    return "Cannot convert \"" + typeDescription + "\" to NativeState<" + typeName + ">! " + reason;
+  }
+};
+
+} // namespace margelo::nitro

package/cpp/jsi/JSIConverter+Optional.hpp

@@ -0,0 +1,41 @@
+//
+// Created by Marc Rousavy on 21.02.24.
+//
+
+#pragma once
+
+// Forward declare a few of the common types that might have cyclic includes.
+namespace margelo::nitro {
+template <typename T, typename Enable>
+struct JSIConverter;
+} // namespace margelo::nitro
+
+#include "JSIConverter.hpp"
+
+#include <jsi/jsi.h>
+#include <optional>
+
+namespace margelo::nitro {
+
+using namespace facebook;
+
+// std::optional<T> <> T | undefined
+template <typename TInner>
+struct JSIConverter<std::optional<TInner>> {
+  static inline std::optional<TInner> fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+    if (arg.isUndefined() || arg.isNull()) {
+      return std::nullopt;
+    } else {
+      return JSIConverter<TInner>::fromJSI(runtime, arg);
+    }
+  }
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, const std::optional<TInner>& arg) {
+    if (arg == std::nullopt) {
+      return jsi::Value::undefined();
+    } else {
+      return JSIConverter<TInner>::toJSI(runtime, arg.value());
+    }
+  }
+};
+
+} // namespace margelo::nitro