react-native-nitro-modules 0.23.0 → 0.24.0

package/NitroModules.podspec

@@ -41,6 +41,7 @@ Pod::Spec.new do |s|
     "cpp/jsi/JSIConverter.hpp",
     "cpp/platform/NitroLogger.hpp",
     "cpp/threading/Dispatcher.hpp",
+    "cpp/utils/JSCallback.hpp",
     "cpp/utils/NitroHash.hpp",
     "cpp/utils/NitroDefines.hpp",
     "cpp/views/CachedProp.hpp",

package/README.md

@@ -181,6 +181,12 @@ The following C++ / JS types are supported out of the box:
     <td><code>(T...) -&gt; <a href="./ios/core/Promise.swift">Promise&lt;T&gt;</a></code></td>
     <td><code>(T...) -&gt; <a href="./android/src/main/java/com/margelo/nitro/core/Promise.kt">Promise&lt;T&gt;</a></code></td>
   </tr>
+  <tr>
+    <td><code>Sync&lt;(T...) =&gt; R&gt;</code></td>
+    <td><code>std::function&lt;R (T...)&gt;</code></td>
+    <td><code>@escaping (T...) -&gt; R</code></td>
+    <td><code>(T...) -&gt; R</code></td>
+  </tr>
   <tr>
     <td><code>Error</code></td>
     <td><code>std::exception_ptr</code></td>

package/android/src/main/cpp/registry/DefaultConstructableObject.hpp

@@ -59,7 +59,7 @@ public:
     auto instance = _javaClass->newObject(_defaultConstructor);
 #ifdef NITRO_DEBUG
     if (instance == nullptr) [[unlikely]] {
-      throw std::runtime_error("Failed to create an instance of \"JHybridTestObjectSwiftKotlinSpec\" - the constructor returned null!");
+      throw std::runtime_error("Failed to create an instance of \"" + _javaClass->toString() + "\" - the constructor returned null!");
     }
 #endif
     return instance;

package/cpp/core/ArrayBuffer.cpp

@@ -61,7 +61,7 @@ bool NativeArrayBuffer::isOwner() const noexcept {
 
 // 3. JSArrayBuffer
 
-JSArrayBuffer::JSArrayBuffer(jsi::Runtime* runtime, BorrowingReference<jsi::ArrayBuffer> jsReference)
+JSArrayBuffer::JSArrayBuffer(jsi::Runtime& runtime, BorrowingReference<jsi::ArrayBuffer> jsReference)
     : ArrayBuffer(), _runtime(runtime), _jsReference(jsReference), _initialThreadId(std::this_thread::get_id()) {}
 
 JSArrayBuffer::~JSArrayBuffer() {}
@@ -72,13 +72,12 @@ uint8_t* JSArrayBuffer::data() {
                              "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);
+  return _jsReference->data(_runtime);
 }
 
 size_t JSArrayBuffer::size() const {
@@ -87,13 +86,12 @@ size_t JSArrayBuffer::size() const {
                              "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);
+  return _jsReference->size(_runtime);
 }
 
 bool JSArrayBuffer::isOwner() const noexcept {

package/cpp/core/ArrayBuffer.hpp

@@ -122,7 +122,7 @@ private:
  */
 class JSArrayBuffer final : public ArrayBuffer {
 public:
-  explicit JSArrayBuffer(jsi::Runtime* runtime, BorrowingReference<jsi::ArrayBuffer> jsReference);
+  explicit JSArrayBuffer(jsi::Runtime& runtime, BorrowingReference<jsi::ArrayBuffer> jsReference);
   ~JSArrayBuffer();
 
 public:
@@ -140,7 +140,7 @@ public:
   bool isOwner() const noexcept override;
 
 private:
-  jsi::Runtime* _runtime;
+  jsi::Runtime& _runtime;
   BorrowingReference<jsi::ArrayBuffer> _jsReference;
   std::thread::id _initialThreadId;
 };

package/cpp/core/HybridFunction.hpp

@@ -57,7 +57,8 @@ public:
 public:
   // functions
   inline jsi::Function toJSFunction(jsi::Runtime& runtime) const {
-    return jsi::Function::createFromHostFunction(runtime, jsi::PropNameID::forUtf8(runtime, _name), _paramCount, _function);
+    return jsi::Function::createFromHostFunction(runtime, jsi::PropNameID::forUtf8(runtime, _name), static_cast<unsigned int>(_paramCount),
+                                                 _function);
   }
 
 private:

package/cpp/core/HybridObject.cpp

@@ -46,7 +46,9 @@ jsi::Value HybridObject::toObject(jsi::Runtime& runtime) {
   auto cachedObject = _objectCache.find(&runtime);
   if (cachedObject != _objectCache.end()) {
     // 1.1. We have a WeakObject, try to see if it is still alive
-    OwningLock<jsi::WeakObject> lock = cachedObject->second.lock();
+    if (cachedObject->second == nullptr) [[unlikely]] {
+      throw std::runtime_error("HybridObject \"" + getName() + "\" was cached, but the reference got destroyed!");
+    }
     jsi::Value value = cachedObject->second->lock(runtime);
     if (!value.isUndefined()) {
       // 1.2. It is still alive - we can use it instead of creating a new one! But first, let's update memory-size

package/cpp/core/Promise.hpp

@@ -122,7 +122,8 @@ public:
    */
   void reject(const std::exception_ptr& exception) {
     if (exception == nullptr) [[unlikely]] {
-      throw std::runtime_error("Cannot reject Promise with a null exception_ptr!");
+      std::string typeName = TypeInfo::getFriendlyTypename<TResult>(true);
+      throw std::runtime_error("Cannot reject Promise<" + typeName + "> with a null exception_ptr!");
     }
 
     std::unique_lock lock(_mutex);
@@ -208,7 +209,8 @@ public:
    */
   inline const TResult& getResult() {
     if (!isResolved()) {
-      throw std::runtime_error("Cannot get result when Promise is not yet resolved!");
+      std::string typeName = TypeInfo::getFriendlyTypename<TResult>(true);
+      throw std::runtime_error("Cannot get result when Promise<" + typeName + "> is not yet resolved!");
     }
     return std::get<TResult>(_state);
   }
@@ -218,7 +220,8 @@ public:
    */
   inline const std::exception_ptr& getError() {
     if (!isRejected()) {
-      throw std::runtime_error("Cannot get error when Promise is not yet rejected!");
+      std::string typeName = TypeInfo::getFriendlyTypename<TResult>(true);
+      throw std::runtime_error("Cannot get error when Promise<" + typeName + "> is not yet rejected!");
     }
     return std::get<std::exception_ptr>(_state);
   }
@@ -323,7 +326,7 @@ public:
   }
   void reject(const std::exception_ptr& exception) {
     if (exception == nullptr) [[unlikely]] {
-      throw std::runtime_error("Cannot reject Promise with a null exception_ptr!");
+      throw std::runtime_error("Cannot reject Promise<void> with a null exception_ptr!");
     }
 
     std::unique_lock lock(_mutex);
@@ -383,7 +386,7 @@ public:
 public:
   inline const std::exception_ptr& getError() {
     if (!isRejected()) {
-      throw std::runtime_error("Cannot get error when Promise is not yet rejected!");
+      throw std::runtime_error("Cannot get error when Promise<void> is not yet rejected!");
     }
     return _error;
   }

package/cpp/jsi/JSICache.hpp

@@ -29,9 +29,9 @@ class JSICacheReference;
  * `jsi::Value`s are managed by a `jsi::Runtime`, and will be deleted if the `jsi::Runtime`
  * is deleted - even if there are still strong references to the `jsi::Value`.
  *
- * To access a `BorrowingReference<jsi::Value>` safely, use `lock()` to get an `OwningLock<jsi::Value>`.
- * This will allow you to access the `jsi::Value` as long as the `OwningLock` is alive,
- * and `JSICache` will hold any garbage collection calls until the `OwningLock` is destroyed.
+ * To access a `BorrowingReference<jsi::Value>` safely, make sure you are using it from
+ * the same Thread that it was created on. This ensures that the `jsi::Runtime` cannot
+ * delete it while you are still using it.
  */
 class JSICache final : public jsi::NativeState {
 public:

package/cpp/jsi/JSIConverter+ArrayBuffer.hpp

@@ -51,7 +51,7 @@ struct JSIConverter<T, std::enable_if_t<is_shared_ptr_to_v<T, jsi::MutableBuffer
     JSICacheReference cache = JSICache::getOrCreateCache(runtime);
     auto borrowingArrayBuffer = cache.makeShared(object.getArrayBuffer(runtime));
 
-    return std::make_shared<JSArrayBuffer>(&runtime, borrowingArrayBuffer);
+    return std::make_shared<JSArrayBuffer>(runtime, borrowingArrayBuffer);
   }
   static inline jsi::Value toJSI(jsi::Runtime& runtime, const std::shared_ptr<jsi::MutableBuffer>& buffer) {
     return jsi::ArrayBuffer(runtime, buffer);

package/cpp/jsi/JSIConverter+Exception.hpp

@@ -31,7 +31,7 @@ struct JSIConverter<std::exception_ptr> final {
   }
   static inline jsi::Value toJSI(jsi::Runtime& runtime, const std::exception_ptr& exception) {
     if (exception == nullptr) [[unlikely]] {
-      throw std::runtime_error("Cannot convert an empty exception_ptr to a JS Error!");
+      throw std::runtime_error("Cannot convert a nullptr exception_ptr to a JS Error!");
     }
 
     try {
@@ -40,10 +40,13 @@ struct JSIConverter<std::exception_ptr> final {
       jsi::JSError error(runtime, e.what());
       return jsi::Value(runtime, error.value());
 #ifdef ANDROID
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wexceptions"
       // Workaround for https://github.com/mrousavy/nitro/issues/382
     } catch (const std::runtime_error& e) {
       jsi::JSError error(runtime, e.what());
       return jsi::Value(runtime, error.value());
+#pragma clang diagnostic pop
 #endif
     } catch (...) {
       // Some unknown exception was thrown - maybe an Objective-C error?

package/cpp/jsi/JSIConverter+Function.hpp

@@ -12,12 +12,10 @@ template <typename T, typename Enable>
 struct JSIConverter;
 } // namespace margelo::nitro
 
-#include "JSIConverter.hpp"
-
 #include "Dispatcher.hpp"
+#include "JSCallback.hpp"
 #include "JSICache.hpp"
 #include "PromiseType.hpp"
-#include <functional>
 #include <jsi/jsi.h>
 
 namespace margelo::nitro {
@@ -25,49 +23,31 @@ namespace margelo::nitro {
 using namespace facebook;
 
 // [](Args...) -> T {} <> (Args...) => T
-template <typename ReturnType, typename... Args>
-struct JSIConverter<std::function<ReturnType(Args...)>> final {
+template <typename R, typename... Args>
+struct JSIConverter<std::function<R(Args...)>> final {
+  // Use AsyncJSCallback or SyncJSCallback
+  inline static constexpr bool isAsync = is_promise_v<R> || std::is_void_v<R>;
   // Promise<T> -> T
-  using ResultingType = promise_type_v<ReturnType>;
+  using ActualR = std::conditional_t<isAsync, promise_type_v<R>, R>;
 
-  static inline std::function<ReturnType(Args...)> fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+  static inline std::function<R(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::getOrCreateCache(runtime);
     jsi::Function function = arg.asObject(runtime).asFunction(runtime);
     BorrowingReference<jsi::Function> sharedFunction = cache.makeShared(std::move(function));
+    SyncJSCallback<ActualR(Args...)> callback(runtime, std::move(sharedFunction));
 
-    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 = std::move(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(LogLevel::Error, "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...);
-            });
-      }
-    };
+    if constexpr (isAsync) {
+      // Return type is `Promise<T>` or `void` - it's an async callback!
+      std::shared_ptr<Dispatcher> dispatcher = Dispatcher::getRuntimeGlobalDispatcher(runtime);
+      return AsyncJSCallback<ActualR(Args...)>(std::move(callback), dispatcher);
+    } else {
+      // Return type is `T` - it's a sync callback!
+      return callback;
+    }
   }
 
-  static inline jsi::Value toJSI(jsi::Runtime& runtime, std::function<ReturnType(Args...)>&& function) {
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, std::function<R(Args...)>&& function) {
     jsi::HostFunctionType jsFunction = [function = std::move(function)](jsi::Runtime& runtime, const jsi::Value&, const jsi::Value* args,
                                                                         size_t count) -> jsi::Value {
       if (count != sizeof...(Args)) [[unlikely]] {
@@ -80,8 +60,8 @@ struct JSIConverter<std::function<ReturnType(Args...)>> final {
                                                  std::move(jsFunction));
   }
 
-  static inline jsi::Value toJSI(jsi::Runtime& runtime, const std::function<ReturnType(Args...)>& function) {
-    std::function<ReturnType(Args...)> copy = function;
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, const std::function<R(Args...)>& function) {
+    std::function<R(Args...)> copy = function;
     return toJSI(runtime, std::move(copy));
   }
 
@@ -94,40 +74,17 @@ struct JSIConverter<std::function<ReturnType(Args...)>> final {
   }
 
 private:
-  static inline ResultingType callJSFunction(jsi::Runtime& runtime, const BorrowingReference<jsi::Function>& function,
-                                             const Args&... args) {
-    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(LogLevel::Error, "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>) {
+  static inline jsi::Value callHybridFunction(const std::function<R(Args...)>& function, jsi::Runtime& runtime, const jsi::Value* args,
+                                              std::index_sequence<Is...>) {
+    if constexpr (std::is_void_v<R>) {
       // 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, std::forward<ReturnType>(result));
+      R result = function(JSIConverter<std::decay_t<Args>>::fromJSI(runtime, args[Is])...);
+      return JSIConverter<R>::toJSI(runtime, std::forward<R>(result));
     }
   }
 };

package/cpp/jsi/JSIConverter+Promise.hpp

@@ -12,7 +12,7 @@ struct JSIConverter;
 } // namespace margelo::nitro
 
 #include "JSIConverter.hpp"
-
+#include "NitroTypeInfo.hpp"
 #include "Promise.hpp"
 #include <exception>
 #include <jsi/jsi.h>
@@ -92,7 +92,8 @@ struct JSIConverter<std::shared_ptr<Promise<TResult>>> final {
       jsi::Value error = JSIConverter<std::exception_ptr>::toJSI(runtime, promise->getError());
       return createRejectedPromise.call(runtime, std::move(error));
     } else {
-      throw std::runtime_error("Promise has invalid state!");
+      std::string typeName = TypeInfo::getFriendlyTypename<TResult>(true);
+      throw std::runtime_error("Promise<" + typeName + "> has invalid state!");
     }
   }
 

package/cpp/prototype/HybridObjectPrototype.cpp

@@ -27,7 +27,10 @@ jsi::Value HybridObjectPrototype::createPrototype(jsi::Runtime& runtime, const s
   auto cachedPrototype = prototypeCache.find(prototype->getNativeInstanceId());
   if (cachedPrototype != prototypeCache.end()) {
     const BorrowingReference<jsi::Object>& cachedObject = cachedPrototype->second;
-    return jsi::Value(runtime, *cachedObject).getObject(runtime);
+    if (cachedObject != nullptr) {
+      // 1.1. Found it in cache! Copy & return it.
+      return jsi::Value(runtime, *cachedObject);
+    }
   }
 
   // 2. We didn't find the given prototype in cache (either it's a new prototype, or a new runtime),
@@ -66,19 +69,19 @@ jsi::Value HybridObjectPrototype::createPrototype(jsi::Runtime& runtime, const s
                               /* descriptorObj */ property);
   }
 
-  // 6. Throw it into our cache so the next lookup can be cached and therefore faster
-  JSICacheReference jsiCache = JSICache::getOrCreateCache(runtime);
-  BorrowingReference<jsi::Object> cachedObject = jsiCache.makeShared(std::move(object));
-  prototypeCache.emplace(prototype->getNativeInstanceId(), cachedObject);
-
-  // 7. In DEBUG, add a __type info to the prototype object.
+  // 6. In DEBUG, add a __type info to the prototype object.
 #ifdef NITRO_DEBUG
   auto prototypeName = "Prototype<" + typeName + ">";
-  cachedObject->setProperty(runtime, "__type", jsi::String::createFromUtf8(runtime, prototypeName));
+  object.setProperty(runtime, "__type", jsi::String::createFromUtf8(runtime, prototypeName));
 #endif
 
+  // 7. Throw it into our cache so the next lookup can be cached and therefore faster
+  JSICacheReference jsiCache = JSICache::getOrCreateCache(runtime);
+  BorrowingReference<jsi::Object> sharedObject = jsiCache.makeShared(std::move(object));
+  prototypeCache.emplace(prototype->getNativeInstanceId(), sharedObject);
+
   // 8. Return it!
-  return jsi::Value(runtime, *cachedObject);
+  return jsi::Value(runtime, *sharedObject);
 }
 
 jsi::Value HybridObjectPrototype::getPrototype(jsi::Runtime& runtime) {

package/cpp/templates/PromiseType.hpp

@@ -16,17 +16,29 @@ namespace margelo::nitro {
 template <typename T>
 struct promise_type {
   using type = void;
+  using is_promise = std::false_type;
+};
+
+template <>
+struct promise_type<void> {
+  using type = void;
+  using is_promise = std::true_type;
 };
 template <typename T>
 struct promise_type<Promise<T>> {
   using type = T;
+  using is_promise = std::true_type;
 };
 template <typename T>
 struct promise_type<std::shared_ptr<Promise<T>>> {
   using type = T;
+  using is_promise = std::true_type;
 };
 
 template <typename T>
 using promise_type_v = typename promise_type<std::remove_reference_t<T>>::type;
 
+template <typename T>
+inline constexpr bool is_promise_v = promise_type<std::remove_reference_t<T>>::is_promise::value;
+
 } // namespace margelo::nitro

package/cpp/threading/Dispatcher.cpp

@@ -45,18 +45,20 @@ std::shared_ptr<Dispatcher> Dispatcher::getRuntimeGlobalDispatcher(jsi::Runtime&
               getRuntimeId(runtime).c_str());
   jsi::Value dispatcherHolderValue = getRuntimeGlobalDispatcherHolder(runtime);
   jsi::Object dispatcherHolder = dispatcherHolderValue.getObject(runtime);
-  return dispatcherHolder.getNativeState<Dispatcher>(runtime);
+  std::shared_ptr<Dispatcher> dispatcher = dispatcherHolder.getNativeState<Dispatcher>(runtime);
+  _globalCache[&runtime] = dispatcher;
+  return dispatcher;
 }
 
 jsi::Value Dispatcher::getRuntimeGlobalDispatcherHolder(jsi::Runtime& runtime) {
 #ifdef NITRO_DEBUG
   if (!runtime.global().hasProperty(runtime, GLOBAL_DISPATCHER_HOLDER_NAME)) [[unlikely]] {
     throw std::runtime_error("Failed to get current Dispatcher - the global Dispatcher "
-                             "holder (global." +
+                             "holder (`global." +
                              std::string(GLOBAL_DISPATCHER_HOLDER_NAME) +
-                             ") "
-                             "does not exist! Was Dispatcher::installDispatcherIntoRuntime() called "
-                             "for this jsi::Runtime?");
+                             "`) "
+                             "does not exist! Was `Dispatcher::installDispatcherIntoRuntime()` called "
+                             "for this `jsi::Runtime`?");
   }
 #endif
   return runtime.global().getProperty(runtime, GLOBAL_DISPATCHER_HOLDER_NAME);

package/cpp/utils/BorrowingReference.hpp

@@ -8,7 +8,7 @@
 #pragma once
 
 #include "NitroDefines.hpp"
-#include "OwningLock.hpp"
+#include "NitroTypeInfo.hpp"
 #include "ReferenceState.hpp"
 #include "WeakReference.hpp"
 #include <atomic>
@@ -18,19 +18,15 @@
 namespace margelo::nitro {
 
 /**
- An `BorrowingReference<T>` is a smart-pointer that holds a strong reference to a pointer.
- You can have multiple `BorrowingReference<T>` instances point to the same pointer, as they internally keep a ref-count.
- As opposed to a `shared_ptr<T>`, an `BorrowingReference<T>` can also be imperatively manually deleted, even if there
- are multiple strong references still holding onto the pointer.
- This is useful in cases where the `BorrowingReference` might keep a reference alive, but an external value holder
- is actually responsible for truly deleting the underlying value - like a `jsi::Runtime` for a `jsi::Value`.
-
- An `BorrowingReference<T>` can be weakified, which gives the user a `WeakReference<T>`.
- A `WeakReference<T>` can be locked to get an `BorrowingReference<T>` again, assuming it has not been deleted yet.
-
- A `BorrowingReference<T>` can also be locked using `lock()`, which gives the user an `OwningLock<T>`.
- Only an `OwningLock<T>` guarantees safe access to the underlying value reference, as any external value holders
- that might try to delete the value will have to wait until the lock is freed again.
+ * An `BorrowingReference<T>` is a smart-pointer that holds a strong reference to a pointer.
+ * You can have multiple `BorrowingReference<T>` instances point to the same pointer, as they internally keep a ref-count.
+ * As opposed to a `shared_ptr<T>`, an `BorrowingReference<T>` can also be imperatively manually deleted, even if there
+ * are multiple strong references still holding onto the pointer.
+ * This is useful in cases where the `BorrowingReference` might keep a reference alive, but an external value holder
+ * is actually responsible for truly deleting the underlying value - like a `jsi::Runtime` for a `jsi::Value`.
+ *
+ * An `BorrowingReference<T>` can be weakified, which gives the user a `WeakReference<T>`.
+ * A `WeakReference<T>` can be locked to get an `BorrowingReference<T>` again, assuming it has not been deleted yet.
  */
 template <typename T>
 class BorrowingReference final {
@@ -46,7 +42,7 @@ public:
     }
   }
 
-  BorrowingReference(BorrowingReference&& ref) : _value(ref._value), _state(ref._state) {
+  BorrowingReference(BorrowingReference&& ref) noexcept : _value(ref._value), _state(ref._state) {
     ref._value = nullptr;
     ref._state = nullptr;
   }
@@ -76,7 +72,7 @@ public:
 
 private:
   // WeakReference<T> -> BorrowingReference<T> Lock-constructor
-  BorrowingReference(const WeakReference<T>& ref) : _value(ref._value), _state(ref._state) {
+  explicit BorrowingReference(const WeakReference<T>& ref) : _value(ref._value), _state(ref._state) {
     _state->strongRefCount++;
   }
 
@@ -107,7 +103,7 @@ public:
 
 public:
   /**
-   Casts this `BorrowingReference<T>` to a `BorrowingReference<C>`.
+   * Casts this `BorrowingReference<T>` to a `BorrowingReference<C>`.
    */
   template <typename C>
   BorrowingReference<C> as() {
@@ -116,25 +112,15 @@ public:
 
 public:
   /**
-   Creates an `OwningLock<T>` for the given `BorrowingReference<T>` to guarantee safe
-   safe access to `BorrowingReference<T>`.
-   Other threads (e.g. the Hermes garbage collector) cannot delete the `BorrowingReference<T>`
-   as long as the `OwningLock<T>` is still alive.
+   * Get whether the `BorrowingReference<T>` is still pointing to a valid value, or not.
    */
   [[nodiscard]]
-  OwningLock<T> lock() const {
-    return OwningLock<T>(*this);
-  }
-
-  /**
-   Get whether the `BorrowingReference<T>` is still pointing to a valid value, or not.
-   */
   inline bool hasValue() const {
     return _value != nullptr && !_state->isDeleted;
   }
 
   /**
-   Get a borrowing (or "weak") reference to this owning reference
+   * Get a borrowing (or "weak") reference to this owning reference
    */
   [[nodiscard]]
   WeakReference<T> weak() const {
@@ -142,10 +128,8 @@ public:
   }
 
   /**
-   Delete and destroy the value this BorrowingReference is pointing to.
-   This can even be called if there are still multiple strong references to the value.
-
-   This will block as long as one or more `OwningLock<T>`s of this `BorrowingReference<T>` are still alive.
+   * Delete and destroy the value this BorrowingReference is pointing to.
+   * This can even be called if there are still multiple strong references to the value.
    */
   void destroy() {
     std::unique_lock lock(_state->mutex);
@@ -154,40 +138,55 @@ public:
   }
 
 public:
-  explicit inline operator bool() const {
-    return hasValue();
-  }
-
+  // Dereference (*)
   inline T& operator*() const {
 #ifdef NITRO_DEBUG
     if (!hasValue()) [[unlikely]] {
-      throw std::runtime_error("Tried to dereference (*) nullptr BorrowingReference<T>!");
+      std::string typeName = TypeInfo::getFriendlyTypename<T>(true);
+      throw std::runtime_error("Tried to dereference (*) nullptr BorrowingReference<" + typeName + ">!");
     }
 #endif
     return *_value;
   }
 
+  // Dereference (->)
   inline T* operator->() const {
 #ifdef NITRO_DEBUG
     if (!hasValue()) [[unlikely]] {
-      throw std::runtime_error("Tried to dereference (->) nullptr BorrowingReference<T>!");
+      std::string typeName = TypeInfo::getFriendlyTypename<T>(true);
+      throw std::runtime_error("Tried to dereference (->) nullptr BorrowingReference<" + typeName + ">!");
     }
 #endif
     return _value;
   }
 
+  // null-check (bool)
+  explicit inline operator bool() const {
+    return hasValue();
+  }
+  // null-check (== nullptr)
+  inline bool operator==(std::nullptr_t) const {
+    return !hasValue();
+  }
+  // null-check (!= nullptr)
+  inline bool operator!=(std::nullptr_t) const {
+    return hasValue();
+  }
+
+  // comparison (== *)
   inline bool operator==(T* other) const {
     return _value == other;
   }
-
+  // comparison (!= *)
   inline bool operator!=(T* other) const {
     return _value != other;
   }
 
+  // comparison (== BorrowingReference<T>)
   inline bool operator==(const BorrowingReference<T>& other) const {
     return _value == other._value;
   }
-
+  // comparison (!= BorrowingReference<T>)
   inline bool operator!=(const BorrowingReference<T>& other) const {
     return _value != other._value;
   }
@@ -198,7 +197,6 @@ private:
       // free the full memory if there are no more references at all
       delete _state;
       _state = nullptr;
-      return;
     }
   }
 
@@ -214,7 +212,6 @@ private:
 
 public:
   friend class WeakReference<T>;
-  friend class OwningLock<T>;
 
 private:
   T* _value;