expo-modules-jsi 58.0.7 → 58.0.8

package/apple/Sources/ExpoModulesJSI/Coding/JavaScriptValueKinds.swift

@@ -0,0 +1,73 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+internal import jsi
+
+/// A set of JavaScript value kinds, as told apart by the value's type tag alone.
+///
+/// Unlike `JavaScriptValue.Kind`, a function is an `object` here: telling it apart needs a call into
+/// the runtime, while every kind in this set is read from the tag without one. Used by
+/// `JavaScriptDecodable.decodableKinds` to describe the kinds a type can decode from. Frozen, so a check
+/// against it compiles to a mask test in the client.
+@frozen
+public struct JavaScriptValueKinds: OptionSet, Sendable {
+  public let rawValue: UInt16
+
+  // `UInt16` leaves room for more kinds without changing the frozen layout.
+  //
+  // The kinds are computed and inlinable rather than stored `static let`s, which a client would reach
+  // through a lazily initialized global, so a mask built from them folds to a constant.
+
+  @inlinable
+  public init(rawValue: UInt16) {
+    self.rawValue = rawValue
+  }
+
+  @inlinable public static var undefined: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 0) }
+  @inlinable public static var null: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 1) }
+  @inlinable public static var bool: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 2) }
+  @inlinable public static var number: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 3) }
+  @inlinable public static var bigint: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 4) }
+  @inlinable public static var string: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 5) }
+  @inlinable public static var symbol: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 6) }
+  /// Any object, including arrays, typed arrays and functions.
+  @inlinable public static var object: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: 1 << 7) }
+
+  /// Every kind, including any added later: the bits above the current kinds are set too, so a type that
+  /// accepts every kind keeps doing so.
+  @inlinable public static var all: JavaScriptValueKinds { JavaScriptValueKinds(rawValue: .max) }
+
+  /// The kind of `value`.
+  ///
+  /// Not inlinable on purpose: the type checks read the `jsi::Value`, which clients can't see, so an
+  /// inlined initializer would make one call into this module per check. Here it is a single call.
+  public init(of value: borrowing JavaScriptValue) {
+    self.init(of: value.pointee)
+  }
+
+  /// The kind of the borrowed `value`, read the same way as from an owning value.
+  public init(of value: borrowing JavaScriptUnownedValue) {
+    self.init(of: value.pointer.pointee)
+  }
+
+  /// Reads the kind from the `jsi::Value` both public initializers wrap. The checks go from the most to
+  /// the least common kind of an argument.
+  private init(of value: borrowing facebook.jsi.Value) {
+    if value.isNumber() {
+      self = .number
+    } else if value.isString() {
+      self = .string
+    } else if value.isObject() {
+      self = .object
+    } else if value.isBool() {
+      self = .bool
+    } else if value.isNull() {
+      self = .null
+    } else if value.isUndefined() {
+      self = .undefined
+    } else if value.isBigInt() {
+      self = .bigint
+    } else {
+      self = .symbol
+    }
+  }
+}

package/apple/Sources/ExpoModulesJSI/Protocols/JSIRepresentable.swift

@@ -93,14 +93,16 @@ extension String: JSIRepresentable {
     // allocation, copy and free per string. `withUTF8` is mutating (it makes a bridged string
     // contiguous first), hence the local copy; native strings are already contiguous and pay nothing.
     // The value is moved out through a local because `withUTF8` needs a `Copyable` closure result.
+    // The C++ helper moves the engine's `jsi::String` into the value, so this costs one engine handle;
+    // `jsi::Value(runtime, string)` would clone it and then release the original.
     var string = self
     var value = facebook.jsi.Value.undefined()
     string.withUTF8 { utf8 in
       guard let base = utf8.baseAddress else {
-        value = facebook.jsi.Value(runtime, facebook.jsi.String.createFromAscii(runtime, "", 0))
+        value = expo.createStringValueFromAscii(runtime, "", 0)
         return
       }
-      value = facebook.jsi.Value(runtime, facebook.jsi.String.createFromUtf8(runtime, base, utf8.count))
+      value = expo.createStringValueFromUtf8(runtime, base, utf8.count)
     }
     return value
   }

package/apple/Sources/ExpoModulesJSI/Runtime/JavaScriptRuntime.swift

@@ -146,7 +146,7 @@ open class JavaScriptRuntime: Equatable, Identifiable, @unchecked Sendable {
     // when the last reference is gone. `deinit` is `nonisolated`, so it can touch the actor-isolated
     // registry directly given that exclusive access.
     propNameIdsRegistry.removeAll()
-    cachedDeferredPromiseFactory = nil
+    cache.clear()
     expo.destroyRuntime(runtimePointee)
   }
 
@@ -203,7 +203,8 @@ open class JavaScriptRuntime: Equatable, Identifiable, @unchecked Sendable {
         let propertyName = String(jsiPropNameID: propertyName.pointee, in: runtime.pointee)
         return JavaScriptActor.assumeIsolated {
           return forwardingSwiftErrorsToJS(runtime: runtime) {
-            try context.get(propertyName).writeJSIValue(to: resultPtr)
+            var result = try context.get(propertyName)
+            JavaScriptValue.write(&result, to: resultPtr)
           }
         }
       }
@@ -789,12 +790,14 @@ open class JavaScriptRuntime: Equatable, Identifiable, @unchecked Sendable {
   @JavaScriptActor
   internal var propNameIdsRegistry: [String: JavaScriptPropNameID] = [:]
 
-  // MARK: - Deferred promise factory
+  // MARK: - Cache
 
-  /// The JavaScript function ``JavaScriptPromise`` uses to create deferred promises, built on first
-  /// use and released with the runtime. See `JavaScriptPromise.init(_:)` for why it exists.
+  /// Values cached with ``cached(_:_:)``. Unchecked exclusivity skips the dynamic access checks on
+  /// every lookup: the cache is only used on the JavaScript thread, and `cached(_:_:)` never keeps an
+  /// access open while it calls out, so accesses can't overlap.
   @JavaScriptActor
-  internal var cachedDeferredPromiseFactory: JavaScriptValue?
+  @exclusivity(unchecked)
+  internal var cache = Cache()
 
   // MARK: - Long-lived objects
 
@@ -826,12 +829,12 @@ open class JavaScriptRuntime: Equatable, Identifiable, @unchecked Sendable {
         // hop back to the JavaScript thread first.
         JavaScriptActor.assumeIsolated {
           longLivedObjects.clear()
-          // Also flush the cached `jsi::PropNameID`s and the deferred-promise factory: a non-owning
-          // wrapper can outlive its runtime (e.g. captured by a task abandoned on reload) and would
-          // otherwise destroy them against the freed runtime when it deallocates. `self` is weak so
-          // the teardown object doesn't retain the wrapper; the owning wrapper clears both in `deinit`.
+          // Also flush the cached `jsi::PropNameID`s and the cache: a non-owning wrapper can outlive its
+          // runtime (e.g. captured by a task abandoned on reload) and would otherwise destroy them against
+          // the freed runtime when it deallocates. `self` is weak so the teardown object doesn't retain the
+          // wrapper; the owning wrapper clears both in `deinit`.
           self?.propNameIdsRegistry.removeAll()
-          self?.cachedDeferredPromiseFactory = nil
+          self?.cache.clear()
         }
       }
       let object = createObject()
@@ -883,7 +886,8 @@ private func createFunctionClosure(
           let this = UnsafeMutablePointer(mutating: thisPtr).move()
           let arguments = JavaScriptValuesBuffer(runtime, start: argumentsPtr, count: argumentsCount)
           let thisValue = JavaScriptValue(runtime, this)
-          try context.call(thisValue, consume arguments).writeJSIValue(to: resultPtr)
+          var result = try context.call(thisValue, consume arguments)
+          JavaScriptValue.write(&result, to: resultPtr)
         }
       }
     }
@@ -926,7 +930,8 @@ private func createFunctionClosure(
         return forwardingSwiftErrorsToJS(runtime: runtime) {
           let arguments = JavaScriptValuesBuffer(runtime, start: argumentsPtr, count: argumentsCount)
           let thisValue = JavaScriptUnownedValue(runtime.pointee, thisPtr)
-          try context.call(thisValue, consume arguments).writeJSIValue(to: resultPtr)
+          var result = try context.call(thisValue, consume arguments)
+          JavaScriptValue.write(&result, to: resultPtr)
         }
       }
     }

package/apple/Sources/ExpoModulesJSI/Runtime/JavaScriptRuntimeCache.swift

@@ -0,0 +1,74 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import os
+
+extension JavaScriptRuntime {
+  /// Values cached by a runtime, stored by their keys' indices. Isolated to the JavaScript thread
+  /// together with the runtime that owns it. Values are read and created through
+  /// ``JavaScriptRuntime/cached(_:_:)``.
+  public struct Cache: ~Copyable {
+    /// A key for a value that a runtime creates once and then reuses, such as a JavaScript constructor
+    /// or a property name. Declare keys as `static let`s and pass them to ``JavaScriptRuntime/cached(_:_:)``.
+    ///
+    /// Each key gets a fixed index from a process-wide counter when it is created, so a lookup reads one
+    /// array slot instead of hashing a string. Every runtime keeps its own values for the same keys.
+    public struct Key<Value: AnyObject>: Sendable {
+      internal let index: Int
+
+      public init() {
+        self.index = nextCacheKeyIndex.withLock { index in
+          defer { index += 1 }
+          return index
+        }
+      }
+    }
+
+    // A slot per key index, up to the highest index used so far in this runtime. Slots of keys that
+    // haven't been used here yet are `nil`. `ContiguousArray` stores the references directly, without
+    // the bridging checks that `Array` can do for class elements on Apple platforms.
+    private var storage = ContiguousArray<AnyObject?>()
+
+    internal func value<Value>(for key: Key<Value>) -> Value? {
+      guard key.index < storage.count, let value = storage[key.index] else {
+        return nil
+      }
+      // The key's type guarantees the type of the value stored under it.
+      return unsafeDowncast(value, to: Value.self)
+    }
+
+    internal mutating func store<Value>(_ value: Value, for key: Key<Value>) {
+      if key.index >= storage.count {
+        storage.append(contentsOf: repeatElement(nil, count: key.index - storage.count + 1))
+      }
+      storage[key.index] = value
+    }
+
+    /// Releases all cached values. They often hold JSI objects, which must be destroyed before the
+    /// runtime they belong to.
+    internal mutating func clear() {
+      storage.removeAll()
+    }
+  }
+
+  /// Returns the value cached under `key`, creating it with `make` the first time the key is used in
+  /// this runtime. If `make` throws, nothing is cached and the next call tries again.
+  ///
+  /// `make` may look up other cached values, for example to build a prototype from a cached
+  /// constructor.
+  @JavaScriptActor
+  public func cached<Value>(_ key: Cache.Key<Value>, _ make: () throws -> Value) rethrows -> Value {
+    if let value = cache.value(for: key) {
+      return value
+    }
+    // Call `make` without accessing the cache, so that the lookups it does itself don't overlap with
+    // an access in progress here.
+    let value = try make()
+    cache.store(value, for: key)
+    return value
+  }
+}
+
+/// The index for the next created ``JavaScriptRuntime/Cache/Key``. Keys can be created on any thread,
+/// for example by initializing a `static let`, so the counter is behind a lock. That costs nothing on
+/// the lookup path, since each key takes an index only once.
+private let nextCacheKeyIndex = OSAllocatedUnfairLock(initialState: 0)

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

@@ -460,6 +460,32 @@ public struct JavaScriptArray: JavaScriptType, ~Copyable {
     return result
   }
 
+  /// Transforms each element like `map(_:)`, but lends each element to `transform` as a
+  /// `JavaScriptUnownedValue` instead of wrapping it in a new `JavaScriptValue`. An element is valid only
+  /// for the duration of its `transform` call and must not be stored or escaped.
+  public func mapUnowned<T>(_ transform: (borrowing JavaScriptUnownedValue) throws -> T) rethrows -> [T] {
+    guard let jsiRuntime else {
+      FatalError.runtimeLost()
+    }
+    let count = self.length
+    var result: [T] = []
+    result.reserveCapacity(count)
+    for index in 0..<count {
+      let element = pointee.getValueAtIndex(jsiRuntime, index)
+      // `withUnsafeBytes(of:)` rather than `withUnsafePointer(to:)`; see `JavaScriptValue.withUnsafePointee(_:)`.
+      try withUnsafeBytes(of: element) { bytes in
+        guard let baseAddress = bytes.baseAddress else {
+          preconditionFailure(
+            "withUnsafeBytes(of:) gave an empty buffer for a jsi::Value, which can't happen for a non-zero-sized type"
+          )
+        }
+        let pointer = baseAddress.assumingMemoryBound(to: facebook.jsi.Value.self)
+        result.append(try transform(JavaScriptUnownedValue(jsiRuntime, pointer)))
+      }
+    }
+    return result
+  }
+
   /// Converts the JavaScript array to a `JavaScriptValue`.
   ///
   /// - Returns: A `JavaScriptValue` representing this array

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

@@ -146,6 +146,28 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
     return JavaScriptValue(runtimeHandle, pointee.getProperty(jsiRuntime, name.toJSIPropNameID(in: jsiRuntime)))
   }
 
+  /// Calls `body` with the property of the object with the given name, or `undefined` if there is no
+  /// such property, lent as a `JavaScriptUnownedValue` instead of wrapped in a new `JavaScriptValue`.
+  /// The value is valid only for the duration of the closure and must not be stored or escaped.
+  public func withUnownedProperty<R>(_ name: String, _ body: (borrowing JavaScriptUnownedValue) throws -> R) rethrows
+    -> R
+  {
+    guard let jsiRuntime else {
+      FatalError.runtimeLost()
+    }
+    let property = pointee.getProperty(jsiRuntime, name.toJSIPropNameID(in: jsiRuntime))
+    // `withUnsafeBytes(of:)` rather than `withUnsafePointer(to:)`; see `JavaScriptValue.withUnsafePointee(_:)`.
+    return try withUnsafeBytes(of: property) { bytes in
+      guard let baseAddress = bytes.baseAddress else {
+        preconditionFailure(
+          "withUnsafeBytes(of:) gave an empty buffer for a jsi::Value, which can't happen for a non-zero-sized type"
+        )
+      }
+      let pointer = baseAddress.assumingMemoryBound(to: facebook.jsi.Value.self)
+      return try body(JavaScriptUnownedValue(jsiRuntime, pointer))
+    }
+  }
+
   /// 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 {

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

@@ -284,20 +284,20 @@ extension JavaScriptRuntime {
   /// optimize like any other closure.
   @JavaScriptActor
   fileprivate func deferredPromiseFactory() throws -> JavaScriptValue {
-    if let factory = cachedDeferredPromiseFactory {
-      return factory
+    return try cached(deferredPromiseFactoryKey) {
+      return try eval(
+        label: "expo-modules-jsi/deferred-promise.js",
+        """
+        (function () {
+          let resolve, reject;
+          const promise = new Promise(function (a, b) { resolve = a; reject = b; });
+          return [promise, resolve, reject];
+        })
+        """
+      )
     }
-    let factory = try eval(
-      label: "expo-modules-jsi/deferred-promise.js",
-      """
-      (function () {
-        let resolve, reject;
-        const promise = new Promise(function (a, b) { resolve = a; reject = b; });
-        return [promise, resolve, reject];
-      })
-      """
-    )
-    cachedDeferredPromiseFactory = factory
-    return factory
   }
 }
+
+/// Key of the deferred promise factory in each runtime's cache.
+private let deferredPromiseFactoryKey = JavaScriptRuntime.Cache.Key<JavaScriptValue>()

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

@@ -130,6 +130,23 @@ public struct JavaScriptUnownedValue: ~Copyable {
     return JavaScriptObject(runtime, pointer.pointee.getObject(self.runtime))
   }
 
+  /// Whether the value is an array. The zero-copy counterpart of ``JavaScriptValue/isArray()``.
+  public func isArray() -> Bool {
+    return pointer.pointee.isObject() && pointer.pointee.getObject(runtime).isArray(runtime)
+  }
+
+  /// Returns the value as a ``JavaScriptArray``, or asserts if it is not an array. The zero-copy
+  /// counterpart of ``JavaScriptValue/getArray()``, with the same runtime contract as
+  /// ``getObject(in:)``.
+  public func getArray(in runtime: JavaScriptRuntime) -> JavaScriptArray {
+    assert(isArray(), "Value is not an array")
+    assert(
+      Unmanaged.passUnretained(runtime.pointee).toOpaque() == Unmanaged.passUnretained(self.runtime).toOpaque(),
+      "`getArray(in:)` must be passed the runtime that owns the borrowed value"
+    )
+    return JavaScriptArray(runtime, pointer.pointee.getObject(self.runtime).getArray(self.runtime))
+  }
+
   // MARK: - Throwing conversions ("as functions")
 
   /// Returns the value as a boolean, or throws `TypeError` if it is not a boolean.

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

@@ -10,7 +10,10 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
   /// 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
+  /// Mutable only so that ``write(_:to:)`` can move the engine value out of a uniquely referenced
+  /// instance on the JS thread, right before it is deallocated. Unchecked exclusivity keeps reads of
+  /// a mutable class property free of the dynamic exclusivity check.
+  @exclusivity(unchecked) nonisolated(unsafe) internal var pointee: facebook.jsi.Value
 
   /// 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.
@@ -119,6 +122,45 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
     }
   }
 
+  /// Calls `body` with a `JavaScriptUnownedValue` that borrows this value's `jsi::Value`, without
+  /// copying it. The unowned value is valid only for the duration of the closure and must not be
+  /// stored or escaped.
+  ///
+  /// `runtime` must be the runtime the value belongs to. It is passed in because a runtime-free value
+  /// (undefined, null, a boolean or a number) doesn't hold one.
+  ///
+  /// Inlinable, so the closure and `R` specialize in the caller; only `borrowUnownedValue(in:)` is a
+  /// call into this module.
+  @inlinable
+  public func withUnownedValue<R>(
+    in runtime: borrowing JavaScriptRuntime,
+    _ body: (borrowing JavaScriptUnownedValue) throws -> R
+  ) rethrows -> R {
+    let unownedValue = borrowUnownedValue(in: runtime)
+    // The unowned value points into `self`, so `self` must outlive `body`.
+    defer { withExtendedLifetime(self) {} }
+    return try body(unownedValue)
+  }
+
+  /// A `JavaScriptUnownedValue` pointing at the stored `jsi::Value`. It stays valid while `self` is
+  /// alive: the value is a stored property of this instance, so its address doesn't change, and
+  /// `withUnsafeBytes(of:)` yields that address because a `jsi::Value` can't be copied. Not inlinable,
+  /// since it touches the JSI types; `withUnownedValue(in:_:)` is the only caller.
+  @usableFromInline
+  internal func borrowUnownedValue(in runtime: borrowing JavaScriptRuntime) -> JavaScriptUnownedValue {
+    let pointer = withUnsafeBytes(of: pointee) { bytes in
+      // `withUnsafeBytes(of:)` rather than `withUnsafePointer(to:)`, for the same SIL optimizer crash
+      // `withUnsafePointee(_:)` avoids.
+      guard let baseAddress = bytes.baseAddress else {
+        preconditionFailure(
+          "withUnsafeBytes(of:) gave an empty buffer for a jsi::Value, which can't happen for a non-zero-sized type"
+        )
+      }
+      return baseAddress.assumingMemoryBound(to: facebook.jsi.Value.self)
+    }
+    return JavaScriptUnownedValue(runtime.pointee, pointer)
+  }
+
   // MARK: - Type checks
 
   public func isUndefined() -> Bool {
@@ -534,6 +576,17 @@ public final class JavaScriptValue: JavaScriptType, Equatable, Escapable {
     return copy()
   }
 
+  /// Writes `value` into a host callback's result slot. A uniquely referenced instance, the normal
+  /// case for a value the callback just created, has its engine value moved out instead of cloned,
+  /// since the instance is deallocated right after. Shared instances go through ``writeJSIValue(to:)``.
+  internal static func write(_ value: inout JavaScriptValue, to slot: UnsafeMutablePointer<facebook.jsi.Value>) {
+    if value.runtimeHandle != nil, isKnownUniquelyReferenced(&value) {
+      expo.emplaceMovedValue(slot, &value.pointee)
+    } else {
+      value.writeJSIValue(to: slot)
+    }
+  }
+
   /// Writes this value into a host callback's result slot. Undefined, null, booleans and numbers are
   /// emplaced with the engine's inline constructors, so the common results skip the out-of-line
   /// `jsi::Value` move and destroy that assigning to the slot would cost; everything else is copied

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

@@ -69,9 +69,10 @@ private func appendEngineStringChunk(ctx: UnsafeMutableRawPointer?, ascii: Bool,
   let chunk: String
   if ascii {
     let bytes = UnsafeBufferPointer(start: data.assumingMemoryBound(to: UInt8.self), count: count)
-    chunk = String(unsafeUninitializedCapacity: count) { buffer in
-      return buffer.initialize(fromContentsOf: bytes)
-    }
+    // `String(decoding:as:)` re-validates bytes the engine already guarantees to be ASCII, but it
+    // builds short strings inline. `String(unsafeUninitializedCapacity:)` always allocates heap
+    // storage first, which measured 5 to 10 ns slower for 6 and 22 byte strings.
+    chunk = String(decoding: bytes, as: UTF8.self)
   } else {
     let units = UnsafeBufferPointer(start: data.assumingMemoryBound(to: UInt16.self), count: count)
     if count < 512 {

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

@@ -165,6 +165,8 @@ inline void collectGarbage(jsi::IRuntime &runtime, const std::string &cause) {
 // owns nothing; an object or string there would leak its engine handle. Both callers,
 // `createHostFunction` and `HostObject::get`, pass a default-constructed slot. The Swift side picks
 // the helper by kind in `JavaScriptValue.writeJSIValue(to:)` and moves everything else.
+// `JavaScriptValue.write(_:to:)` moves a uniquely referenced value's handle into the slot the same
+// way, through `emplaceMovedValue`.
 inline void emplaceUndefined(jsi::Value *_Nonnull slot) noexcept {
   ::new (slot) jsi::Value();
 }
@@ -181,6 +183,31 @@ inline void emplaceNumber(jsi::Value *_Nonnull slot, double value) noexcept {
   ::new (slot) jsi::Value(value);
 }
 
+/**
+ Moves the value at `source` into the engine's result slot. Placement new, like the `emplace*`
+ helpers above: the slot must hold a value that owns nothing. `source` is left holding a null
+ pointer, so destroying it afterwards releases nothing.
+ */
+inline void emplaceMovedValue(jsi::Value *_Nonnull slot, jsi::Value *_Nonnull source) noexcept {
+  ::new (slot) jsi::Value(std::move(*source));
+}
+
+/**
+ Creates a string value straight from UTF-8 bytes. The `jsi::String` returned by `createFromUtf8`
+ is moved into the value, so the engine allocates one handle. Going through `jsi::Value(runtime,
+ const jsi::String &)` from Swift instead clones the handle and then releases the original.
+ */
+inline jsi::Value createStringValueFromUtf8(jsi::IRuntime &runtime, const uint8_t *_Nonnull utf8, size_t length) {
+  return jsi::Value(jsi::String::createFromUtf8(runtime, utf8, length));
+}
+
+/**
+ Same as `createStringValueFromUtf8`, for bytes the caller knows to be ASCII.
+ */
+inline jsi::Value createStringValueFromAscii(jsi::IRuntime &runtime, const char *_Nonnull ascii, size_t length) {
+  return jsi::Value(jsi::String::createFromAscii(runtime, ascii, length));
+}
+
 inline jsi::Value callFunction(jsi::IRuntime &runtime, const jsi::Function &function, const jsi::Value *_Nullable args, size_t count) {
   return expo::CppError::tryCatch(runtime, [&] {
     return function.call(runtime, args, count);

package/apple/Tests/JavaScriptDecodableKindsTests.swift

@@ -0,0 +1,132 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Foundation
+import Testing
+
+@Suite("JavaScriptDecodable.decodableKinds")
+@JavaScriptActor
+struct JavaScriptDecodableKindsTests {
+  let runtime = JavaScriptRuntime()
+
+  /// One sample value of each JS type, keyed by the source that evaluates to it.
+  static let samples = [
+    "42", "1.5", "'text'", "true", "null", "undefined", "10n", "Symbol()", "({})", "[1]", "new Uint8Array(1)",
+    "(function () {})",
+  ]
+
+  // MARK: - JavaScriptValueKinds(of:)
+
+  @Test
+  func `reads the kind of every JS type from owning and unowned values`() throws {
+    let expected: [String: JavaScriptValueKinds] = [
+      "42": .number, "1.5": .number, "'text'": .string, "true": .bool, "null": .null,
+      "undefined": .undefined, "10n": .bigint, "Symbol()": .symbol, "({})": .object, "[1]": .object,
+      "new Uint8Array(1)": .object, "(function () {})": .object,
+    ]
+    for source in Self.samples {
+      let value = try runtime.eval(source)
+      #expect(JavaScriptValueKinds(of: value) == expected[source], "owning \(source)")
+
+      let buffer = JavaScriptValuesBuffer.allocate(in: runtime, with: value)
+      let unownedKind = JavaScriptValueKinds(of: buffer.unownedValue(at: 0))
+      #expect(unownedKind == expected[source], "unowned \(source)")
+    }
+  }
+
+  // MARK: - decodableKinds
+
+  /// Checks that `decodableKinds` contains the kind of exactly the `accepted` samples, and that `decode`
+  /// throws for every rejected one. A rejection must be definitive, because a union skips the case
+  /// without trying to decode it.
+  private func expectDecodableKinds<T: JavaScriptDecodable>(
+    _ type: T.Type,
+    accept accepted: Set<String>,
+    sourceLocation: SourceLocation = #_sourceLocation
+  ) throws {
+    for source in Self.samples {
+      let value = try runtime.eval(source)
+      let expected = accepted.contains(source)
+      #expect(
+        T.decodableKinds.contains(JavaScriptValueKinds(of: value)) == expected,
+        "\(source)",
+        sourceLocation: sourceLocation
+      )
+      if !expected {
+        #expect(throws: (any Error).self, "decode \(source)", sourceLocation: sourceLocation) {
+          _ = try T.decode(value, in: runtime)
+        }
+      }
+    }
+  }
+
+  static let numbers: Set<String> = ["42", "1.5"]
+  static let objects: Set<String> = ["({})", "[1]", "new Uint8Array(1)", "(function () {})"]
+
+  @Test
+  func `Bool accepts only booleans`() throws {
+    try expectDecodableKinds(Bool.self, accept: ["true"])
+  }
+
+  @Test
+  func `String accepts only strings`() throws {
+    try expectDecodableKinds(String.self, accept: ["'text'"])
+  }
+
+  @Test
+  func `floating-point types accept only numbers`() throws {
+    try expectDecodableKinds(Double.self, accept: Self.numbers)
+    try expectDecodableKinds(Float.self, accept: Self.numbers)
+    try expectDecodableKinds(CGFloat.self, accept: Self.numbers)
+  }
+
+  @Test
+  func `narrow integer types accept only numbers`() throws {
+    try expectDecodableKinds(Int8.self, accept: Self.numbers)
+    try expectDecodableKinds(Int16.self, accept: Self.numbers)
+    try expectDecodableKinds(Int32.self, accept: Self.numbers)
+    try expectDecodableKinds(UInt8.self, accept: Self.numbers)
+    try expectDecodableKinds(UInt16.self, accept: Self.numbers)
+    try expectDecodableKinds(UInt32.self, accept: Self.numbers)
+  }
+
+  @Test
+  func `64-bit integer types accept numbers and bigints`() throws {
+    let accepted = Self.numbers.union(["10n"])
+    try expectDecodableKinds(Int.self, accept: accepted)
+    try expectDecodableKinds(Int64.self, accept: accepted)
+    try expectDecodableKinds(UInt.self, accept: accepted)
+    try expectDecodableKinds(UInt64.self, accept: accepted)
+  }
+
+  @Test
+  func `Optional accepts null, undefined and what the wrapped type accepts`() throws {
+    try expectDecodableKinds(String?.self, accept: ["'text'", "null", "undefined"])
+  }
+
+  @Test
+  func `Array accepts objects and what the element type accepts`() throws {
+    // A non-array value is decoded as a single-element array.
+    try expectDecodableKinds([String].self, accept: Self.objects.union(["'text'"]))
+  }
+
+  @Test
+  func `Dictionary accepts only objects`() throws {
+    try expectDecodableKinds([String: Int].self, accept: Self.objects)
+  }
+
+  @Test
+  func `Data accepts only objects`() throws {
+    try expectDecodableKinds(Data.self, accept: Self.objects)
+  }
+
+  @Test
+  func `Date accepts numbers, strings and objects`() throws {
+    try expectDecodableKinds(Date.self, accept: Self.numbers.union(["'text'"]).union(Self.objects))
+  }
+
+  @Test
+  func `JavaScriptValue accepts every value`() throws {
+    try expectDecodableKinds(JavaScriptValue.self, accept: Set(Self.samples))
+  }
+}