react-native-nitro-modules 0.1.7 → 0.2.0

package/cpp/prototype/Prototype.hpp

@@ -0,0 +1,163 @@
+//
+//  PrototypeChain.hpp
+//  NitroModules
+//
+//  Created by Marc Rousavy on 07.08.24.
+//
+
+#pragma once
+
+#include "HybridFunction.hpp"
+#include <memory>
+#include <string>
+#include <typeindex>
+#include <unordered_map>
+
+namespace margelo::nitro {
+
+/**
+ * Represents a Prototype's native C++ type ID.
+ * This can be used to identify a prototype against a C++ instance,
+ * or used as a cache-key.
+ */
+using NativeInstanceId = std::type_index;
+
+/**
+ * Represents a JS `Prototype`'s structure.
+ * Every prototype has a related C++ type ID (`instanceTypeId`).
+ * Prototypes can be sub-classes, in which case they have a `base` prototype.
+ * Each prototype has a list of methods, and properties (getters + setters).
+ *
+ * By using this `Prototype` structure, we can create JS objects that act
+ * as prototypes for `HybridObject`s.
+ *
+ * While a `Prototype` actually holds all the methods, a `HybridObject` only
+ * contains state and memory.
+ * This way the JS VM doesn't need to re-create methods for each `HybridObject`,
+ * they are only initialized once on the shared `Prototype`.
+ */
+struct Prototype final {
+private:
+  std::shared_ptr<Prototype> _base = nullptr;
+  NativeInstanceId _instanceTypeId;
+  std::unordered_map<std::string, HybridFunction> _methods;
+  std::unordered_map<std::string, HybridFunction> _getters;
+  std::unordered_map<std::string, HybridFunction> _setters;
+
+private:
+  Prototype(const NativeInstanceId& typeId, const std::shared_ptr<Prototype>& base) : _instanceTypeId(typeId), _base(base) {}
+
+public:
+  /**
+   * Gets a `Prototype` specification/node for the given native C++ type ID.
+   *
+   * If the given C++ type ID is unknown, a new `Prototype` node is created,
+   * which has to be initialized with methods, getters and setters first.
+   *
+   * If the given C++ type ID is already known in the static `Prototype` tree,
+   * a shared reference to it is returned.
+   */
+  static std::shared_ptr<Prototype> get(const NativeInstanceId& typeId, const std::shared_ptr<Prototype>& base = nullptr) {
+    static std::unordered_map<NativeInstanceId, std::shared_ptr<Prototype>> _prototypesCache;
+
+    const auto& found = _prototypesCache.find(typeId);
+    if (found != _prototypesCache.end()) {
+      // We know this C++ type ID / Prototype - return it!
+      return found->second;
+    } else {
+      // This is the first time we see this C++ type ID - create a new base Prototype for this.
+      auto prototype = std::shared_ptr<Prototype>(new Prototype(typeId, base));
+      _prototypesCache.emplace(typeId, prototype);
+      return prototype;
+    }
+  }
+
+public:
+  template <typename T>
+  inline bool isNativeInstance() const noexcept {
+    return _instanceTypeId == std::type_index(typeid(T));
+  }
+
+  inline bool hasHybrids() const {
+    return !_methods.empty() || !_getters.empty() || !_setters.empty();
+  }
+
+  inline bool hasBase() const noexcept {
+    return _base != nullptr;
+  }
+  inline const std::shared_ptr<Prototype>& getBase() const noexcept {
+    return _base;
+  }
+  inline const NativeInstanceId& getNativeInstanceId() const noexcept {
+    return _instanceTypeId;
+  }
+  inline const std::unordered_map<std::string, HybridFunction>& getMethods() const noexcept {
+    return _methods;
+  }
+  inline const std::unordered_map<std::string, HybridFunction>& getGetters() const noexcept {
+    return _getters;
+  }
+  inline const std::unordered_map<std::string, HybridFunction>& getSetters() const noexcept {
+    return _setters;
+  }
+
+public:
+  /**
+   * Registers the given C++ method as a Hybrid Method that can be called from JS, through the object's Prototype.
+   * Example:
+   * ```cpp
+   * registerHybridMethod("sayHello", &MyObject::sayHello);
+   * ```
+   */
+  template <typename Derived, typename ReturnType, typename... Args>
+  inline void registerHybridMethod(std::string name, ReturnType (Derived::*method)(Args...)) {
+    if (_getters.contains(name) || _setters.contains(name)) [[unlikely]] {
+      throw std::runtime_error("Cannot add Hybrid Method \"" + name + "\" - a property with that name already exists!");
+    }
+    if (_methods.contains(name)) [[unlikely]] {
+      throw std::runtime_error("Cannot add Hybrid Method \"" + name + "\" - a method with that name already exists!");
+    }
+
+    _methods.emplace(name, HybridFunction::createHybridFunction(name, method, FunctionType::METHOD));
+  }
+
+  /**
+   * Registers the given C++ method as a property getter that can be called from JS, through the object's Prototype.
+   * Example:
+   * ```cpp
+   * registerHybridGetter("foo", &MyObject::getFoo);
+   * ```
+   */
+  template <typename Derived, typename ReturnType>
+  inline void registerHybridGetter(std::string name, ReturnType (Derived::*method)()) {
+    if (_getters.contains(name)) [[unlikely]] {
+      throw std::runtime_error("Cannot add Hybrid Property Getter \"" + name + "\" - a getter with that name already exists!");
+    }
+    if (_methods.contains(name)) [[unlikely]] {
+      throw std::runtime_error("Cannot add Hybrid Property Getter \"" + name + "\" - a method with that name already exists!");
+    }
+
+    _getters.emplace(name, HybridFunction::createHybridFunction(name, method, FunctionType::GETTER));
+  }
+
+  /**
+   * Registers the given C++ method as a property setter that can be called from JS, through the object's Prototype.
+   * Example:
+   * ```cpp
+   * registerHybridSetter("foo", &MyObject::setFoo);
+   * ```
+   */
+  template <typename Derived, typename ValueType>
+  inline void registerHybridSetter(std::string name, void (Derived::*method)(ValueType)) {
+    if (_setters.contains(name)) [[unlikely]] {
+      throw std::runtime_error("Cannot add Hybrid Property Setter \"" + name + "\" - a setter with that name already exists!");
+    }
+    if (_methods.contains(name)) [[unlikely]] {
+      throw std::runtime_error("Cannot add Hybrid Property Setter \"" + name + "\" - a method with that name already exists!");
+    }
+
+    _setters.emplace(name, HybridFunction::createHybridFunction(name, method, FunctionType::SETTER));
+  }
+};
+
+} // namespace margelo::nitro

package/cpp/prototype/PrototypeChain.hpp

@@ -0,0 +1,78 @@
+//
+//  PrototypeChain.hpp
+//  NitroModules
+//
+//  Created by Marc Rousavy on 07.08.24.
+//
+
+#pragma once
+
+#include "Prototype.hpp"
+
+namespace margelo::nitro {
+
+/**
+ * Represents a mutable chain of prototypes.
+ * Callers can use this class to incrementally add sub-classes to prototypes and build
+ * prototype chains/trees using C++ type information.
+ *
+ * The template methods can be used to find a specific C++ instance in the prototype tree,
+ * or create a new sub-class if it cannot be found.
+ */
+class PrototypeChain final {
+private:
+  std::shared_ptr<Prototype> _prototype;
+
+public:
+  PrototypeChain() {}
+
+public:
+  /**
+   * Gets the current `Prototype` as a whole.
+   * This does not do any modifications to the Prototype tree.
+   */
+  inline const std::shared_ptr<Prototype>& getPrototype() const {
+    return _prototype;
+  }
+
+public:
+  /**
+   * Extends the Prototype with the given type `Derived`.
+   * If the Prototype already extended `Derived`, this returns the current state.
+   */
+  template <typename Derived>
+  inline const std::shared_ptr<Prototype>& extendPrototype() {
+    if (_prototype == nullptr) {
+      _prototype = Prototype::get(typeid(Derived));
+    }
+
+    return getOrExtendPrototype<Derived>(_prototype);
+  }
+
+private:
+  /**
+   * Perform a bottom-down search of the given `Derived` C++ type info.
+   * If the current prototype tree does not have a Prototype that represents the
+   * C++ type `Derived`, it will extend it at the bottom and shift the `Prototype` tree
+   * up by one.
+   */
+  template <typename Derived>
+  inline const std::shared_ptr<Prototype>& getOrExtendPrototype(const std::shared_ptr<Prototype>& node) {
+    if (node->isNativeInstance<Derived>()) {
+      // If the Prototype represents the caller type (`Derived`), we work with this Prototype.
+      return node;
+    } else {
+      if (node->hasBase()) {
+        // We didn't find a match in this prototype, let's recursively try it's parent!
+        return getOrExtendPrototype<Derived>(node->getBase());
+      } else {
+        // We didn't find `Derived` and we don't have a base- add a child and shift the tree by one.
+        auto newBase = _prototype;
+        _prototype = Prototype::get(typeid(Derived), newBase);
+        return _prototype;
+      }
+    }
+  }
+};
+
+} // namespace margelo::nitro

package/cpp/turbomodule/NativeNitroModules.cpp

@@ -58,12 +58,12 @@ void NativeNitroModules::install(jsi::Runtime& runtime) {
   Dispatcher::installRuntimeGlobalDispatcher(runtime, dispatcher);
 }
 
-jsi::Object NativeNitroModules::createHybridObject(jsi::Runtime& runtime, const jsi::String& hybridObjectName,
-                                                   const std::optional<jsi::Object>& args) {
+jsi::Value NativeNitroModules::createHybridObject(jsi::Runtime& runtime, const jsi::String& hybridObjectName,
+                                                  const std::optional<jsi::Object>& args) {
   auto name = hybridObjectName.utf8(runtime);
   // TODO: Pass args? Do we need that?
   auto hybridObject = HybridObjectRegistry::createHybridObject(name.c_str());
-  return jsi::Object::createFromHostObject(runtime, hybridObject);
+  return hybridObject->toObject(runtime);
 }
 
 } // namespace facebook::react

package/cpp/turbomodule/NativeNitroModules.hpp

@@ -23,7 +23,7 @@ public:
   jsi::Value get(jsi::Runtime& runtime, const jsi::PropNameID& propName) override;
 
   void install(jsi::Runtime& runtime);
-  jsi::Object createHybridObject(jsi::Runtime& runtime, const jsi::String& hybridObjectName, const std::optional<jsi::Object>& args);
+  jsi::Value createHybridObject(jsi::Runtime& runtime, const jsi::String& hybridObjectName, const std::optional<jsi::Object>& args);
 
 public:
   constexpr static auto kModuleName = "NitroModulesCxx";

package/cpp/utils/BorrowingReference+Owning.hpp

@@ -22,7 +22,7 @@ BorrowingReference<T>::BorrowingReference(const OwningReference<T>& ref) {
 }
 
 template <typename T>
-OwningReference<T> BorrowingReference<T>::lock() {
+OwningReference<T> BorrowingReference<T>::lock() const {
   std::unique_lock lock(*_mutex);
 
   if (*_isDeleted) {

package/cpp/utils/BorrowingReference.hpp

@@ -82,7 +82,7 @@ public:
    Try to lock the borrowing reference to an owning reference, or `nullptr` if it has already been deleted.
    */
   [[nodiscard]]
-  OwningReference<T> lock();
+  OwningReference<T> lock() const;
 
 public:
   friend class OwningReference<T>;

package/lib/HybridObject.d.ts

@@ -9,7 +9,10 @@ export interface PlatformSpec {
  * Represents a Nitro `HybridObject` which is implemented natively in either C++,
  * or Swift/Kotlin.
  *
- * Uses the Nitro Tunnel for efficient, low-overhead JS <-> Native communication.
+ * `HybridObject`s use the Nitro Tunnel for efficient, low-overhead JS <-> Native communication.
+ *
+ * All `HybridObject`s are implemented using `NativeState`, and inherit their properties
+ * and methods from their prototype, so the actual JS object is empty.
  *
  * @example
  * ```ts
@@ -22,6 +25,22 @@ export interface PlatformSpec {
  * ```
  */
 export interface HybridObject<Spec extends PlatformSpec> {
+    /**
+     * Holds a type-name describing the native `HybridObject` instance.
+     *
+     * This is the only property actually present on the actual JavaScript object,
+     * because all other properties and methods are inherited from a shared Prototype.
+     *
+     * Nitro prototypes also have a `__type`.
+     *
+     * For actual HybridObject instances, this is `NativeState<...>`, for
+     * prototypes this is `Prototype<...>`.
+     *
+     * @internal
+     * @private
+     * @note This value is available in debug only.
+     */
+    readonly __type?: string;
     /**
      * The `HybridObject`'s name.
      */