react-native-nitro-modules 0.4.1 → 0.6.0

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
@@ -33,6 +33,12 @@ using DeleteFn = void (*)(void* context);
  *   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,
@@ -41,11 +47,12 @@ public:
    */
   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);
 };
 
 /**
@@ -67,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:
@@ -77,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.
@@ -162,6 +161,81 @@ private:
       return JSIConverter<std::decay_t<ReturnType>>::toJSI(runtime, std::move(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 + "`";
+    }
+  }
 };
 
 } // namespace margelo::nitro

package/cpp/core/HybridObject.cpp

@@ -49,8 +49,8 @@ HybridObject::HybridObject(const char* name) : HybridObjectPrototype(), _name(na
   _instanceId = getId(name);
   uint32_t alive = incrementAliveInstancesAndGet(_name);
   uint32_t totalObjects = getTotalAliveInstances();
-  Logger::log(TAG, "(MEMORY) ✅ Creating %s (#%i)... (Total %s(s): %i | Total HybridObjects: %i)", _name, _instanceId, _name, alive,
-              totalObjects);
+  Logger::log(LogLevel::Info, TAG, "(MEMORY) ✅ Creating %s (#%i)... (Total %s(s): %i | Total HybridObjects: %i)", _name, _instanceId,
+              _name, alive, totalObjects);
 #endif
 }
 
@@ -58,8 +58,8 @@ HybridObject::~HybridObject() {
 #if LOG_MEMORY_ALLOCATIONS
   uint32_t alive = decrementAliveInstancesAndGet(_name);
   uint32_t totalObjects = getTotalAliveInstances();
-  Logger::log(TAG, "(MEMORY) ❌ Deleting %s (#%i)... (Total %s(s): %i | Total HybridObjects: %i) ", _name, _instanceId, _name, alive,
-              totalObjects);
+  Logger::log(LogLevel::Info, TAG, "(MEMORY) ❌ Deleting %s (#%i)... (Total %s(s): %i | Total HybridObjects: %i) ", _name, _instanceId,
+              _name, alive, totalObjects);
 #endif
 }
 
@@ -75,11 +75,22 @@ bool HybridObject::equals(std::shared_ptr<HybridObject> other) {
   return this == other.get();
 }
 
+jsi::Value HybridObject::disposeRaw(jsi::Runtime& runtime, const jsi::Value& thisArg, const jsi::Value* args, size_t count) {
+  // 1. Dispose any resources - this might be overridden by child classes to perform manual cleanup.
+  dispose();
+  // 2. Remove the NativeState from `this`
+  jsi::Object thisObject = thisArg.asObject(runtime);
+  thisObject.setNativeState(runtime, nullptr);
+
+  return jsi::Value::undefined();
+}
+
 void HybridObject::loadHybridMethods() {
   registerHybrids(this, [](Prototype& prototype) {
     prototype.registerHybridGetter("name", &HybridObject::getName);
-    prototype.registerHybridMethod("toString", &HybridObject::toString);
     prototype.registerHybridMethod("equals", &HybridObject::equals);
+    prototype.registerHybridMethod("toString", &HybridObject::toString);
+    prototype.registerRawHybridMethod("dispose", 0, &HybridObject::disposeRaw);
   });
 }
 
@@ -112,7 +123,7 @@ jsi::Value HybridObject::toObject(jsi::Runtime& runtime) {
   // 6. Set memory size so Hermes GC knows about actual memory
   object.setExternalMemoryPressure(runtime, getExternalMemorySize());
 
-#if DEBUG
+#ifndef NDEBUG
   // 7. Assign a private __type property for debugging - this will be used so users know it's not just an empty object.
   object.setProperty(runtime, "__type", jsi::String::createFromUtf8(runtime, "NativeState<" + std::string(_name) + ">"));
 #endif

package/cpp/core/HybridObject.hpp

@@ -23,7 +23,7 @@ using namespace facebook;
  *
  * The new class can then be passed to JS using the `JSIConverter<HybridObject>`.
  */
-class HybridObject : public jsi::NativeState, public HybridObjectPrototype, public std::enable_shared_from_this<HybridObject> {
+class HybridObject : public virtual jsi::NativeState, public HybridObjectPrototype, public std::enable_shared_from_this<HybridObject> {
 public:
   /**
    * Create a new instance of a `HybridObject`.
@@ -38,11 +38,17 @@ public:
   /**
    * HybridObjects cannot be copied.
    */
-  HybridObject(const HybridObject& copy) = delete;
+  HybridObject(const HybridObject& copy) = default;
   /**
    * HybridObjects cannot be moved.
    */
-  HybridObject(HybridObject&& move) = delete;
+  HybridObject(HybridObject&& move) = default;
+  /**
+   * HybridObjects cannot be default-constructed!
+   */
+  HybridObject() {
+    throw std::runtime_error("Cannot default-construct HybridObject!");
+  }
 
 public:
   /**
@@ -60,7 +66,7 @@ public:
    */
   template <typename Derived>
   std::shared_ptr<Derived> shared() {
-    return std::static_pointer_cast<Derived>(shared_from_this());
+    return std::dynamic_pointer_cast<Derived>(shared_from_this());
   }
 
 public:
@@ -68,10 +74,6 @@ public:
    * Get the HybridObject's name
    */
   std::string getName();
-  /**
-   * Get a string representation of this HostObject, useful for logging or debugging.
-   */
-  virtual std::string toString();
   /**
    * Compare this HybridObject for reference equality to the other HybridObject.
    *
@@ -79,6 +81,28 @@ public:
    * they might still be the same `HybridObject` - in this case `equals(other)` will return true.
    */
   bool equals(std::shared_ptr<HybridObject> other);
+  /**
+   * Get a string representation of this `HybridObject` - useful for logging or debugging.
+   */
+  virtual std::string toString();
+  /**
+   * Eagerly- (and manually-) dispose all native resources this `HybridObject` holds.
+   * This method can only be manually called from JS using `dispose()`.
+   *
+   * If this method is never manually called, a `HybridObject` is expected to disposes it's
+   * resources as usual via the object's destructor (`~HybridObject()`, `deinit` or `finalize()`).
+   *
+   * By default, this method does nothing. It can be overridden to perform actual disposing/cleanup
+   * if required.
+   */
+  virtual void dispose() {}
+
+private:
+  /**
+   * The actual `dispose()` function from JS.
+   * This needs to be a raw JSI function as we remove the NativeState here.
+   */
+  jsi::Value disposeRaw(jsi::Runtime& runtime, const jsi::Value& thisArg, const jsi::Value* args, size_t count);
 
 protected:
   /**