expo-modules-jsi 58.0.5 → 58.0.7

package/apple/Sources/ExpoModulesJSI/Runtime/Values/JavaScriptObject.swift

@@ -6,32 +6,53 @@ internal import jsi
 /// A Swift representation of a JavaScript object. Provides access to JavaScript object properties and methods,
 /// supporting property access, modification, enumeration, prototype manipulation, and function calling.
 public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
-  internal weak let runtime: JavaScriptRuntime?
+  /// Handle to the runtime the object belongs to.
+  internal let runtimeHandle: JavaScriptRuntimeHandle
   internal var pointee: facebook.jsi.Object
 
+  /// The runtime the object belongs to, or `nil` if it has been deallocated. Prefer ``jsiRuntime`` on
+  /// hot paths: it costs no reference counting.
+  internal var runtime: JavaScriptRuntime? {
+    return runtimeHandle.runtime
+  }
+
+  /// The engine runtime the object belongs to, or `nil` if the runtime has been deallocated.
+  internal var jsiRuntime: facebook.jsi.IRuntime? {
+    return runtimeHandle.pointee
+  }
+
   /// Creates a new object in the given runtime.
-  public init(_ runtime: JavaScriptRuntime) {
+  public init(_ runtime: borrowing JavaScriptRuntime) {
     self.init(runtime, facebook.jsi.Object(runtime.pointee))
   }
 
   /// Creates a new object from the dictionary whose values are representable in JS.
-  public init<DictValue: JavaScriptRepresentable>(_ runtime: JavaScriptRuntime, _ dictionary: [String: DictValue]) {
-    self.runtime = runtime
+  public init<DictValue: JavaScriptRepresentable>(
+    _ runtime: borrowing JavaScriptRuntime,
+    _ dictionary: [String: DictValue]
+  ) {
+    self.runtimeHandle = runtime.handle
     self.pointee = dictionary.toJavaScriptValue(in: runtime).getObject().pointee
   }
 
   /// Creates a new object from existing JSI object.
-  internal init(_ runtime: JavaScriptRuntime, _ object: consuming facebook.jsi.Object) {
-    self.runtime = runtime
+  internal init(_ runtime: borrowing JavaScriptRuntime, _ object: consuming facebook.jsi.Object) {
+    self.runtimeHandle = runtime.handle
+    self.pointee = object
+  }
+
+  /// Creates a new object from existing JSI object, which belongs to the runtime behind `runtimeHandle`.
+  internal init(_ runtimeHandle: JavaScriptRuntimeHandle, _ object: consuming facebook.jsi.Object) {
+    self.runtimeHandle = runtimeHandle
     self.pointee = object
   }
 
   /// Result of `object instanceof constructor`, which tests if the prototype property of a constructor appears anywhere in the prototype chain of an object.
   public func instanceOf(_ constructor: borrowing JavaScriptFunction) -> Bool {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return pointee.instanceOf(runtime.pointee, constructor.pointee)
+    return pointee.instanceOf(jsiRuntime, constructor.pointee)
   }
 
   /// Result of `object instanceof constructor`, which tests if the prototype property of a constructor appears anywhere in the prototype chain of an object.
@@ -41,34 +62,42 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
 
   /// Equivalent to `Array.isArray()` in JS. If it returns `true`, then `getArray()` will succeed.
   public func isArray() -> Bool {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return pointee.isArray(runtime.pointee)
+    return pointee.isArray(jsiRuntime)
   }
 
   /// Returns `true` if the object is callable. If so, then `getFunction()` will succeed.
   public func isFunction() -> Bool {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return pointee.isFunction(runtime.pointee)
+    return pointee.isFunction(jsiRuntime)
   }
 
   /// Returns `true` if the object is backed by a `jsi::HostObject`, including host objects
   /// created via `JavaScriptRuntime.createHostObject` and ones produced by other native code.
   public func isHostObject() -> Bool {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return expo.isHostObject(runtime.pointee, pointee)
+    return expo.isHostObject(jsiRuntime, pointee)
   }
 
   public func isArrayBuffer() -> Bool {
+    guard let jsiRuntime else {
+      FatalError.runtimeLost()
+    }
+    return pointee.isArrayBuffer(jsiRuntime)
+  }
+
+  /// Returns `true` if the object is a typed array, such as `Uint8Array`.
+  internal func isTypedArray() -> Bool {
     guard let runtime else {
       FatalError.runtimeLost()
     }
-    return pointee.isArrayBuffer(runtime.pointee)
+    return expo.isTypedArray(runtime.pointee, pointee)
   }
 
   /// Returns the object as an array buffer, or asserts if not an array buffer.
@@ -82,11 +111,11 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
 
   /// Returns the object as an array, or asserts if not an array.
   public func getArray() -> JavaScriptArray {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     assert(isArray(), "Object is not an array")
-    return JavaScriptArray(runtime, pointee.getArray(runtime.pointee))
+    return JavaScriptArray(runtimeHandle, pointee.getArray(jsiRuntime))
   }
 
   /// Returns the object as a function, or asserts if not a function.
@@ -102,28 +131,28 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
 
   /// Checks whether the object has a property with the given name.
   public func hasProperty(_ name: String) -> Bool {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return pointee.hasProperty(runtime.pointee, name.toJSIPropNameID(in: runtime.pointee))
+    return pointee.hasProperty(jsiRuntime, name.toJSIPropNameID(in: jsiRuntime))
   }
 
   /// Returns the property of the object with the given name,
   /// or `undefined` value if the name is not a property of the object.
   public func getProperty(_ name: String) -> JavaScriptValue {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return JavaScriptValue(runtime, pointee.getProperty(runtime.pointee, name.toJSIPropNameID(in: runtime.pointee)))
+    return JavaScriptValue(runtimeHandle, pointee.getProperty(jsiRuntime, name.toJSIPropNameID(in: jsiRuntime)))
   }
 
   /// Returns the property of the object with the given prop name id,
   /// or `undefined` value if the name is not a property of the object.
   public func getProperty(_ propName: JavaScriptPropNameID) -> JavaScriptValue {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return JavaScriptValue(runtime, pointee.getProperty(runtime.pointee, propName.pointee))
+    return JavaScriptValue(runtimeHandle, pointee.getProperty(jsiRuntime, propName.pointee))
   }
 
   /// Accesses nested properties in a single subscript operation by traversing the object chain.
@@ -138,16 +167,15 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   /// - Note: Each intermediate value in the chain (except the last) must be an object.
   ///   If any intermediate value is not an object, the behavior is undefined and may crash.
   public subscript(_ key: String, _ nestedKeys: String...) -> JavaScriptValue {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    let jsiRuntime = runtime.pointee
     var value = pointee.getProperty(jsiRuntime, key)
 
     for key in nestedKeys {
       value = value.getObject(jsiRuntime).getProperty(jsiRuntime, key)
     }
-    return JavaScriptValue(runtime, value)
+    return JavaScriptValue(runtimeHandle, value)
   }
 
   /// Returns an array of the object's own enumerable property names.
@@ -156,7 +184,7 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   ///
   /// - Returns: An array of property names as strings
   public func getPropertyNames() -> [String] {
-    guard let jsiRuntime = runtime?.pointee else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     let propertyNames: facebook.jsi.Array = pointee.getPropertyNames(jsiRuntime)
@@ -209,32 +237,32 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
 
   /// Returns a prototype of the object. Same as `Object.getPrototypeOf(object)` in JS.
   public func getPrototype() -> JavaScriptValue {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return JavaScriptValue(runtime, pointee.getPrototype(runtime.pointee))
+    return JavaScriptValue(runtimeHandle, pointee.getPrototype(jsiRuntime))
   }
 
   /// Sets a prototype of the object. Same as `Object.setPrototypeOf(object, prototype)` in JS.
   public func setPrototype(_ prototype: JavaScriptValue) {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    pointee.setPrototype(runtime.pointee, prototype.pointee)
+    pointee.setPrototype(jsiRuntime, prototype.pointee)
   }
 
   // MARK: - Modifying object properties
 
   public func setProperty(_ name: String, value: JavaScriptValue) {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     // This specialization is to avoid copying the value; `asValue()` on `JavaScriptValue` needs to do a copy.
     expo.setProperty(
-      runtime.pointee,
+      jsiRuntime,
       pointee,
-      name.toJSIPropNameID(in: runtime.pointee),
-      value.toJSIValue(in: runtime.pointee)
+      name.toJSIPropNameID(in: jsiRuntime),
+      value.toJSIValue(in: jsiRuntime)
     )
   }
 
@@ -247,22 +275,22 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   }
 
   internal func setProperty<T: JavaScriptRepresentable>(_ name: String, value: consuming T) where T: JSIRepresentable {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    let jsiValue = value.toJSIValue(in: runtime.pointee)
-    expo.setProperty(runtime.pointee, pointee, name.toJSIPropNameID(in: runtime.pointee), jsiValue)
+    let jsiValue = value.toJSIValue(in: jsiRuntime)
+    expo.setProperty(jsiRuntime, pointee, name.toJSIPropNameID(in: jsiRuntime), jsiValue)
   }
 
   public func setProperty(_ name: String, _ object: consuming JavaScriptObject) {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     expo.setProperty(
-      runtime.pointee,
+      jsiRuntime,
       pointee,
-      name.toJSIPropNameID(in: runtime.pointee),
-      facebook.jsi.Value(runtime.pointee, object.pointee)
+      name.toJSIPropNameID(in: jsiRuntime),
+      facebook.jsi.Value(jsiRuntime, object.pointee)
     )
   }
 
@@ -314,10 +342,10 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   #if !os(macOS)
   // TODO: remove when bumping to react-native-macos 0.86
   public func deleteProperty(_ name: String) {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    pointee.deleteProperty(runtime.pointee, name.toJSIPropNameID(in: runtime.pointee))
+    pointee.deleteProperty(jsiRuntime, name.toJSIPropNameID(in: jsiRuntime))
   }
   #endif
 
@@ -381,18 +409,18 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   // MARK: - Conversions
 
   public func asValue() -> JavaScriptValue {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return JavaScriptValue(runtime, facebook.jsi.Value(runtime.pointee, pointee))
+    return JavaScriptValue(runtimeHandle, facebook.jsi.Value(jsiRuntime, pointee))
   }
 
   /// Returns the object as a `facebook.jsi.Value` instance.
   internal func asJSIValue() -> facebook.jsi.Value {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return facebook.jsi.Value(runtime.pointee, pointee)
+    return facebook.jsi.Value(jsiRuntime, pointee)
   }
 
   /// Provides scoped access to a raw pointer to the underlying `facebook.jsi.Object`.
@@ -428,10 +456,10 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   /// wrapper: C++-produced states carry a null context and are unrecoverable from
   /// the Swift side by design.
   public func hasNativeState() -> Bool {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    return expo.hasNativeState(runtime.pointee, pointee)
+    return expo.hasNativeState(jsiRuntime, pointee)
   }
 
   /// Returns the Swift `JavaScriptNativeState` wrapper attached to this object via
@@ -439,10 +467,10 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   /// produced C++-side without a Swift back-pointer, or its concrete type doesn't
   /// match `T`.
   public func getNativeState<T: JavaScriptNativeState>(as: T.Type = JavaScriptNativeState.self) -> T? {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    guard let cxxNativeState = expo.getExpoNativeState(runtime.pointee, pointee) else {
+    guard let cxxNativeState = expo.getExpoNativeState(jsiRuntime, pointee) else {
       return nil
     }
     return T.from(cxx: cxxNativeState)
@@ -452,27 +480,27 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
   /// Creates a new shared_ptr to the object managed by state, which will live until the value at this property becomes unreachable.
   /// - TODO: throw a type error if this object is a proxy or host object.
   public func setNativeState<T: JavaScriptNativeState>(_ nativeState: T) {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    expo.setNativeState(runtime.pointee, self.pointee, nativeState.acquireShared())
+    expo.setNativeState(jsiRuntime, self.pointee, nativeState.acquireShared())
   }
 
   /// Unsets the native state of this object.
   public func unsetNativeState() {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    expo.unsetNativeState(runtime.pointee, pointee)
+    expo.unsetNativeState(jsiRuntime, pointee)
   }
 
   // MARK: - Memory pressure
 
   public func setExternalMemoryPressure(_ size: Int) {
-    guard let runtime else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
-    pointee.setExternalMemoryPressure(runtime.pointee, size)
+    pointee.setExternalMemoryPressure(jsiRuntime, size)
   }
 
   // MARK: - Equality

package/apple/Sources/ExpoModulesJSI/Runtime/Values/JavaScriptValue.swift

@@ -7,21 +7,38 @@ internal import jsi
 /// this one is a reference type so can be safely captured in closures, passed to other isolation context,
 /// and stored in containers that don't support non-copyable types etc.
 public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
-  internal weak let runtime: JavaScriptRuntime?
+  /// Handle to the runtime the value belongs to. `nil` only for runtime-free values (undefined, null,
+  /// booleans and numbers).
+  internal let runtimeHandle: JavaScriptRuntimeHandle?
   internal let pointee: facebook.jsi.Value
 
-  /// Takes ownership of the given JSI value. Only runtime-free values (undefined, null, booleans and
-  /// numbers) pass `nil` here.
-  internal init(_ runtime: JavaScriptRuntime?, _ pointee: consuming facebook.jsi.Value) {
-    self.runtime = runtime
+  /// The runtime the value belongs to, or `nil` if it has been deallocated or the value is runtime-free.
+  /// Prefer ``jsiRuntime`` on hot paths: it costs no reference counting.
+  internal var runtime: JavaScriptRuntime? {
+    return runtimeHandle?.runtime
+  }
+
+  /// The engine runtime the value belongs to, or `nil` if the runtime has been deallocated or the value
+  /// is runtime-free.
+  internal var jsiRuntime: facebook.jsi.IRuntime? {
+    return runtimeHandle?.pointee
+  }
+
+  /// Takes ownership of the given JSI value, which belongs to the runtime behind `runtimeHandle`.
+  internal init(_ runtimeHandle: JavaScriptRuntimeHandle, _ pointee: consuming facebook.jsi.Value) {
+    self.runtimeHandle = runtimeHandle
+    self.pointee = pointee
+  }
+
+  /// Takes ownership of the given runtime-free JSI value (undefined, null, a boolean or a number).
+  internal init(_ pointee: consuming facebook.jsi.Value) {
+    self.runtimeHandle = nil
     self.pointee = pointee
   }
 
-  /// Takes ownership of the given JSI value. Same as the optional-runtime overload, but the exact
-  /// parameter type keeps the caller from promoting its runtime to an optional, which costs a
-  /// retain/release pair around every call on the hot paths (property reads, function results).
-  internal init(_ runtime: JavaScriptRuntime, _ pointee: consuming facebook.jsi.Value) {
-    self.runtime = runtime
+  /// Takes ownership of the given JSI value.
+  internal init(_ runtime: borrowing JavaScriptRuntime, _ pointee: consuming facebook.jsi.Value) {
+    self.runtimeHandle = runtime.handle
     self.pointee = pointee
   }
 
@@ -29,51 +46,51 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
   /// The `copying:` label keeps this initializer from being picked for temporaries: with a plain
   /// second argument, a non-optional runtime used to win overload resolution over the consuming
   /// initializer above, cloning every freshly returned value instead of taking it over.
-  internal init(_ runtime: JavaScriptRuntime, copying pointee: borrowing facebook.jsi.Value) {
-    self.runtime = runtime
+  internal init(_ runtime: borrowing JavaScriptRuntime, copying pointee: borrowing facebook.jsi.Value) {
+    self.runtimeHandle = runtime.handle
     self.pointee = facebook.jsi.Value(runtime.pointee, pointee)
   }
 
   /// Creates a boolean JS value.
-  public init(_ runtime: JavaScriptRuntime, _ bool: Bool) {
-    self.runtime = runtime
+  public init(_ runtime: borrowing JavaScriptRuntime, _ bool: Bool) {
+    self.runtimeHandle = runtime.handle
     self.pointee = facebook.jsi.Value(bool)
   }
 
   /// Creates a string JS value.
-  public init(_ runtime: JavaScriptRuntime, _ string: String) {
-    self.runtime = runtime
+  public init(_ runtime: borrowing JavaScriptRuntime, _ string: String) {
+    self.runtimeHandle = runtime.handle
     self.pointee = string.toJSIValue(in: runtime.pointee)
   }
 
   /// Creates a BigInt JS value from an Int64.
-  public init(_ runtime: JavaScriptRuntime, bigInt: Int64) {
-    self.runtime = runtime
+  public init(_ runtime: borrowing JavaScriptRuntime, bigInt: Int64) {
+    self.runtimeHandle = runtime.handle
     self.pointee = facebook.jsi.Value(runtime.pointee, facebook.jsi.BigInt.fromInt64(runtime.pointee, bigInt))
   }
 
   /// Creates a BigInt JS value from a UInt64.
-  public init(_ runtime: JavaScriptRuntime, bigInt: UInt64) {
-    self.runtime = runtime
+  public init(_ runtime: borrowing JavaScriptRuntime, bigInt: UInt64) {
+    self.runtimeHandle = runtime.handle
     self.pointee = facebook.jsi.Value(runtime.pointee, facebook.jsi.BigInt.fromUint64(runtime.pointee, bigInt))
   }
 
   /// Creates a JS value from a JS representable.
-  public init(_ runtime: JavaScriptRuntime, _ value: JavaScriptRepresentable) {
-    self.runtime = runtime
+  public init(_ runtime: borrowing JavaScriptRuntime, _ value: JavaScriptRepresentable) {
+    self.runtimeHandle = runtime.handle
     self.pointee = value.toJavaScriptValue(in: runtime).toJSIValue(in: runtime.pointee)
   }
 
   /// Creates a JS value from a JSI representable.
-  internal init(_ runtime: JavaScriptRuntime, _ value: JSIRepresentable) {
-    self.runtime = runtime
+  internal init(_ runtime: borrowing JavaScriptRuntime, _ value: JSIRepresentable) {
+    self.runtimeHandle = runtime.handle
     self.pointee = value.toJSIValue(in: runtime.pointee)
   }
 
   /// Copies the value.
   public func copy() -> JavaScriptValue {
-    if let runtime {
-      return JavaScriptValue(runtime, facebook.jsi.Value(runtime.pointee, pointee))
+    if let runtimeHandle, let jsiRuntime = runtimeHandle.pointee {
+      return JavaScriptValue(runtimeHandle, facebook.jsi.Value(jsiRuntime, pointee))
     }
     // Some simple value kinds do not require the runtime.
     switch kind {
@@ -82,9 +99,9 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
     case .null:
       return .null
     case .bool:
-      return .init(nil, facebook.jsi.Value(getBool()))
+      return .init(facebook.jsi.Value(getBool()))
     case .number:
-      return .init(nil, facebook.jsi.Value(getDouble()))
+      return .init(facebook.jsi.Value(getDouble()))
     default:
       FatalError.runtimeLost()
     }
@@ -137,21 +154,21 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
   }
 
   public func isArray() -> Bool {
-    guard let jsiRuntime = runtime?.pointee else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     return pointee.isObject() && pointee.getObject(jsiRuntime).isArray(jsiRuntime)
   }
 
   public func isFunction() -> Bool {
-    guard let jsiRuntime = runtime?.pointee else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     return pointee.isObject() && pointee.getObject(jsiRuntime).isFunction(jsiRuntime)
   }
 
   public func isTypedArray() -> Bool {
-    guard let jsiRuntime = runtime?.pointee else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     return pointee.isObject() && expo.isTypedArray(jsiRuntime, pointee.getObject(jsiRuntime))
@@ -159,7 +176,7 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
 
   /// Checks whether the value is an `ArrayBuffer`.
   public func isArrayBuffer() -> Bool {
-    guard let jsiRuntime = runtime?.pointee else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     return pointee.isObject() && pointee.getObject(jsiRuntime).isArrayBuffer(jsiRuntime)
@@ -258,7 +275,7 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
 
   /// Returns the value as a string, or asserts if not a string.
   public func getString() -> String {
-    guard let jsiRuntime = runtime?.pointee else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     assert(isString(), "Value is not a string")
@@ -276,20 +293,20 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
 
   /// Returns the value as an object, or asserts if not an object.
   public func getObject() -> JavaScriptObject {
-    guard let runtime else {
+    guard let runtimeHandle, let jsiRuntime = runtimeHandle.pointee else {
       FatalError.runtimeLost()
     }
     assert(isObject(), "Value is not an object")
-    return JavaScriptObject(runtime, pointee.getObject(runtime.pointee))
+    return JavaScriptObject(runtimeHandle, pointee.getObject(jsiRuntime))
   }
 
   /// Returns the value as an array, or asserts if not an array.
   public func getArray() -> JavaScriptArray {
-    guard let runtime else {
+    guard let runtimeHandle, let jsiRuntime = runtimeHandle.pointee else {
       FatalError.runtimeLost()
     }
     assert(isArray(), "Value is not an array")
-    return JavaScriptArray(runtime, pointee.getObject(runtime.pointee).getArray(runtime.pointee))
+    return JavaScriptArray(runtimeHandle, pointee.getObject(jsiRuntime).getArray(jsiRuntime))
   }
 
   /// Returns the value as a function, or asserts if not a function.
@@ -426,7 +443,7 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
 
   /// Returns a string representing the value. Same as calling `toString()` in JS.
   public func toString() -> String {
-    guard let jsiRuntime = runtime?.pointee else {
+    guard let jsiRuntime else {
       FatalError.runtimeLost()
     }
     return String(jsiString: pointee.toString(jsiRuntime), in: jsiRuntime)
@@ -536,8 +553,8 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
   }
 
   internal func asJSIValue() -> facebook.jsi.Value {
-    if let runtime {
-      return facebook.jsi.Value(runtime.pointee, pointee)
+    if let jsiRuntime {
+      return facebook.jsi.Value(jsiRuntime, pointee)
     }
     // Some simple value kinds do not require the runtime.
     switch kind {
@@ -597,7 +614,7 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
 
   /// Tests whether two values are strictly equal, according to https://262.ecma-international.org/11.0/#sec-strict-equality-comparison
   public func isEqual(to another: JavaScriptValue) -> Bool {
-    if let jsiRuntime = runtime?.pointee ?? another.runtime?.pointee {
+    if let jsiRuntime = jsiRuntime ?? another.jsiRuntime {
       return facebook.jsi.Value.strictEquals(jsiRuntime, pointee, another.pointee)
     }
     // Some types don't have to be tied to any runtime. Since `strictEquals` needs a runtime, we need to handle this case ourselves.
@@ -659,20 +676,20 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
   /// This is a lightweight way to create a boolean true value that can be used in contexts
   /// where a runtime is not available or needed.
   public static func `true`() -> JavaScriptValue {
-    return JavaScriptValue(nil, facebook.jsi.Value(true))
+    return JavaScriptValue(facebook.jsi.Value(true))
   }
 
   /// This is a lightweight way to create a boolean false value that can be used in contexts
   /// where a runtime is not available or needed.
   public static func `false`() -> JavaScriptValue {
-    return JavaScriptValue(nil, facebook.jsi.Value(false))
+    return JavaScriptValue(facebook.jsi.Value(false))
   }
 
   /// This is a lightweight way to create a numeric value that can be used in contexts
   /// where a runtime is not available or needed. JavaScript numbers are represented
   /// as double-precision floating-point values following the IEEE 754 standard.
   public static func number(_ number: Double) -> JavaScriptValue {
-    return JavaScriptValue(nil, facebook.jsi.Value(number))
+    return JavaScriptValue(facebook.jsi.Value(number))
   }
 
   public static func representing(value: JavaScriptRepresentable, in runtime: JavaScriptRuntime) -> JavaScriptValue {
@@ -715,9 +732,18 @@ extension JavaScriptValue: JSIRepresentable {
 extension JavaScriptValue {
   public struct TypeError: Error, CustomStringConvertible {
     let type: any ~Copyable.Type
+    /// A specific explanation that replaces the generic message, when the failure needs one.
+    var reason: String? = nil
+    /// Where inside the converted value the failure happened, such as `.user.tags[1]`. Empty when it's
+    /// the value itself.
+    var path: String = ""
 
     public var description: String {
-      return "TypeError: Value cannot be represented as \(type)"
+      let message = "TypeError: \(reason ?? "Value cannot be represented as \(type)")"
+      guard !path.isEmpty else {
+        return message
+      }
+      return "\(message) (path: \(path.hasPrefix(".") ? path.dropFirst() : Substring(path)))"
     }
   }
 }
@@ -725,6 +751,6 @@ extension JavaScriptValue {
 // Shared instances behind `JavaScriptValue.undefined` and `JavaScriptValue.null`; see the comment on
 // those accessors for why these are globals.
 @usableFromInline
-internal let sharedUndefinedValue = JavaScriptValue(nil, facebook.jsi.Value.undefined())
+internal let sharedUndefinedValue = JavaScriptValue(facebook.jsi.Value.undefined())
 @usableFromInline
-internal let sharedNullValue = JavaScriptValue(nil, facebook.jsi.Value.null())
+internal let sharedNullValue = JavaScriptValue(facebook.jsi.Value.null())

package/apple/Sources/ExpoModulesJSI/Utilities/String+JSI.swift

@@ -25,6 +25,16 @@ extension String {
     self = result
   }
 
+  /// Builds a Swift `String` from a `jsi::PropNameID` the same way as `init(jsiString:in:)`, reading
+  /// the engine's internal representation without materializing a `std::string` first.
+  internal init(jsiPropNameID: borrowing facebook.jsi.PropNameID, in runtime: facebook.jsi.IRuntime) {
+    var result = ""
+    withUnsafeMutablePointer(to: &result) { resultPtr in
+      expo.getPropNameIdData(runtime, jsiPropNameID, UnsafeMutableRawPointer(resultPtr), appendEngineStringChunk)
+    }
+    self = result
+  }
+
   /// Builds a `jsi::PropNameID` from the string's UTF-8 bytes. This is how every String-keyed
   /// property API turns its name into a key: JSI's `const char*` overloads treat the bytes as ASCII
   /// and would mangle any non-ASCII name.

package/apple/Sources/ExpoModulesJSI-Cxx/include/HostObject.h

@@ -26,7 +26,7 @@ public:
     jsi::Value result;
     // If the Swift getter stored a pending error, rethrow its JSError directly
     // to preserve all properties (message, code, stack, etc.).
-    if (_callbacks.get(name.utf8(runtime).c_str(), result)) {
+    if (_callbacks.get(name, result)) {
       if (auto *error = CppError::getCurrent()) {
         throw error->release();
       }
@@ -39,7 +39,7 @@ public:
     // `jsi::JSError` directly and the `CppError` check below is never reached.
     // For writable host objects, a throwing Swift setter routes its error through
     // `CppError`'s thread-local slot, which we drain and rethrow here.
-    if (_callbacks.set(runtime, name.utf8(runtime).c_str(), value)) {
+    if (_callbacks.set(runtime, name, value)) {
       if (auto *error = CppError::getCurrent()) {
         throw error->release();
       }