expo-modules-jsi 58.0.6 → 58.0.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 58.0.7
+
+### Patch Changes
+
+- Bump precompiled artifacts due to ABI breakage in expo-modules-jsi@58.0.6. ([#50881](https://github.com/expo/expo/pull/50881) by [@kitten](https://github.com/kitten))
+- [iOS] Add conversions between JavaScript values and free-form `Any`, `[Any]` and `[String: Any]` values. ([#50660](https://github.com/expo/expo/pull/50660) by [@tsapeta](https://github.com/tsapeta))
+
 ## 58.0.6
 
 ### Patch Changes

package/apple/Benchmarks/FreeFormBenchmarks.swift

@@ -0,0 +1,61 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Testing
+
+/// Benchmarks for the free-form (`Any`) conversions. Each pair compares the dedicated fast path for
+/// `[String: Any]` against the generic path that converts through `Any` and casts, on the same
+/// attributes-like object of string, number and boolean values.
+extension JSIBenchmarks {
+  private static let attributesSource = """
+    ({ screen: 'home', build: 'release', region: 'eu', retries: 3, latency: 12.5, cached: true, visible: false, count: 42 })
+    """
+
+  @Test
+  func `decode free-form dictionary`() async throws {
+    try await benchmarkCase { runtime in
+      let value = try runtime.eval(Self.attributesSource)
+      try benchmark("JavaScriptValue.decodeAnyDictionary(_:in:)", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try JavaScriptValue.decodeAnyDictionary(value, in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `decode free-form dictionary through the generic path`() async throws {
+    try await benchmarkCase { runtime in
+      let value = try runtime.eval(Self.attributesSource)
+      try benchmark("JavaScriptValue.decodeAny(_:as: [String: Any].self, in:)", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try JavaScriptValue.decodeAny(value, as: [String: Any].self, in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `encode free-form dictionary`() async throws {
+    try await benchmarkCase { runtime in
+      let attributes = try JavaScriptValue.decodeAnyDictionary(runtime.eval(Self.attributesSource), in: runtime)
+      try benchmark("JavaScriptValue.encodeAnyDictionary(_:in:)", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try JavaScriptValue.encodeAnyDictionary(attributes, in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `encode free-form dictionary through the generic path`() async throws {
+    try await benchmarkCase { runtime in
+      let attributes: Any = try JavaScriptValue.decodeAnyDictionary(runtime.eval(Self.attributesSource), in: runtime)
+      try benchmark("JavaScriptValue.encodeAny(_:in:): [String: Any]", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try JavaScriptValue.encodeAny(attributes, in: runtime)
+        }
+      }
+    }
+  }
+}

package/apple/Sources/ExpoModulesJSI/Coding/JavaScriptCodable+Any.swift

@@ -0,0 +1,500 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import Foundation
+
+// Conversions for free-form values: `Any`, `[Any]`, `[String: Any]`, and types nested from them.
+//
+// `Any` can't conform to `JavaScriptDecodable`/`JavaScriptEncodable` (it isn't a nominal type), and
+// the container conformances require their elements to conform, so none of these types have a
+// `decode`/`encode` of their own. These static methods fill that gap. The three common shapes each
+// have a dedicated decode and encode pair that reads or writes the container directly. Any other
+// shape that holds `Any` (`[[Any]]`, `[String: [Any]]?`, …) goes through the generic
+// `decodeAny(_:as:in:)` and `encodeAny(_:in:)`, which convert the whole value and cast it.
+//
+// Decoding turns numbers into `Double`, drops `undefined` object properties, and turns `null` and
+// `undefined` into `nil` boxed in `Any`, so a decoded value casts to optional types at any depth.
+// A `Date` decodes as `Date`, a `Set` as an array of its elements and a `Map` with string keys as a
+// dictionary. It differs from the deprecated `getAny()` in two ways: `getAny()` uses `NSNull` for
+// `null`, and it silently turns values it can't represent into `NSNull`. Here, a bigint becomes
+// `Int64` (throwing when it doesn't fit), and a function, symbol, typed array, `ArrayBuffer`,
+// `DataView`, `WeakMap`, `WeakSet` or `Map` with a non-string key anywhere in the value throws
+// `TypeError`, as does a value nested deeper than `maxFreeFormDepth` (usually a cycle). Any other
+// object decodes from its enumerable own properties only, so data it keeps elsewhere is not
+// decoded: an `Error` loses its `message` and `stack`, and a class instance loses values it exposes
+// through getters.
+
+extension JavaScriptValue {
+  // MARK: - Decoding
+
+  /// Decodes a JavaScript value into a free-form native value: `Bool`, `Double`, `String`, `Int64`
+  /// (from a bigint), `Date`, `[Any]`, `[String: Any]`, or `nil` (boxed in `Any`) for `null` and
+  /// `undefined`. A `Set` decodes as an array of its elements and a `Map` with string keys as a
+  /// dictionary. Any other object decodes from its enumerable own properties only, so an `Error`, for
+  /// example, decodes without its `message` and `stack`.
+  ///
+  /// Throws `TypeError` for a function, symbol, typed array, `ArrayBuffer`, `DataView`, `WeakMap`,
+  /// `WeakSet` or `Map` with a non-string key anywhere in the value, or for a value nested more than
+  /// 64 levels deep (such as one that contains itself). The error names the path to the failing value.
+  /// Throws `BigIntConversionError` for a bigint outside the `Int64` range.
+  @JavaScriptActor
+  public static func decodeAny(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
+    -> Any
+  {
+    return try freeFormValue(of: value, depth: 0, in: runtime)
+  }
+
+  /// Decodes a borrowed JavaScript value into a free-form native value. See ``decodeAny(_:in:)``.
+  @JavaScriptActor
+  public static func decodeAny(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime)
+    throws -> Any
+  {
+    return try freeFormValue(of: value, depth: 0, in: runtime)
+  }
+
+  /// Decodes a JavaScript array into an array of free-form native values. A `Set` decodes as an array
+  /// of its elements, and any other value that isn't an array is wrapped in a single-element array,
+  /// like `Array.decode` does.
+  @JavaScriptActor
+  public static func decodeAnyArray(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime)
+    throws -> [Any]
+  {
+    guard value.isArray() else {
+      return wrappingInArray(try freeFormValue(of: value, depth: 0, in: runtime))
+    }
+    return try freeFormElements(of: value.getArray(), depth: 0, in: runtime)
+  }
+
+  /// Decodes a borrowed JavaScript array into an array of free-form native values. See
+  /// ``decodeAnyArray(_:in:)``.
+  @JavaScriptActor
+  public static func decodeAnyArray(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime)
+    throws -> [Any]
+  {
+    guard value.isObject() else {
+      return [try freeFormValue(of: value, depth: 0, in: runtime)]
+    }
+    let object = value.getObject(in: copy runtime)
+    guard object.isArray() else {
+      return wrappingInArray(try freeFormValue(ofObject: object, depth: 0, in: runtime))
+    }
+    return try freeFormElements(of: object.getArray(), depth: 0, in: runtime)
+  }
+
+  /// Decodes a JavaScript object into a string-keyed dictionary of free-form native values, with the
+  /// same rules as a nested object in ``decodeAny(_:in:)`` (so a `Map` with string keys converts).
+  /// Throws `TypeError` if the value doesn't decode as a dictionary, such as a primitive, an array, a
+  /// `Date`, a `Set` or a function, or if anything inside it can't be decoded.
+  @JavaScriptActor
+  public static func decodeAnyDictionary(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime)
+    throws -> [String: Any]
+  {
+    return try freeFormDictionary(of: value.asObject(), in: runtime)
+  }
+
+  /// Decodes a borrowed JavaScript object into a string-keyed dictionary of free-form native values.
+  /// See ``decodeAnyDictionary(_:in:)``.
+  @JavaScriptActor
+  public static func decodeAnyDictionary(
+    _ value: borrowing JavaScriptUnownedValue,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> [String: Any] {
+    return try freeFormDictionary(of: value.asObject(in: copy runtime), in: runtime)
+  }
+
+  /// Decodes a JavaScript value into any type built from free-form values, such as `[[Any]]` or
+  /// `[String: [Any]]?`. The value is decoded with ``decodeAny(_:in:)`` and then
+  /// cast to `type`. A `null` or `undefined` at any depth decodes as `nil`, so it fits an optional
+  /// in `type` at that position (`[String: [Any]?]` accepts `{ a: null }`).
+  ///
+  /// Throws `TypeError` if the decoded value can't be cast to `type`. Prefer ``decodeAny(_:in:)``,
+  /// ``decodeAnyArray(_:in:)`` or ``decodeAnyDictionary(_:in:)`` for the types they cover, because
+  /// they don't need the cast.
+  @JavaScriptActor
+  public static func decodeAny<T>(
+    _ value: borrowing JavaScriptValue,
+    as type: T.Type,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> T {
+    guard let result = try decodeAny(value, in: runtime) as? T else {
+      throw TypeError(type: T.self, reason: castFailureReason(for: T.self))
+    }
+    return result
+  }
+
+  // MARK: - Encoding
+
+  /// Encodes a free-form native value into a JavaScript value.
+  ///
+  /// Supports strings, numbers (including `NSNumber`), booleans, `nil` and `NSNull` (encoded as
+  /// `null`), `[Any]` and `[String: Any]` with supported elements, and any `JavaScriptEncodable` or
+  /// `JavaScriptRepresentable` value. Throws `EncodingError` for any other value.
+  @JavaScriptActor
+  public static func encodeAny(_ value: Any, in runtime: borrowing JavaScriptRuntime) throws -> JavaScriptValue {
+    // Strings and the native number and boolean types are the most common leaf values, so they're
+    // checked first, before the slower protocol casts, and each converts through its own `encode` (so
+    // an `Int` outside the safe-integer range throws, as `Int.encode` does). The number and boolean
+    // checks compare the exact type rather than casting, since an `NSNumber` casts to both `Bool` and
+    // `Double` and has to be told apart below.
+    if let string = value as? String {
+      return try String.encode(string, in: runtime)
+    }
+    let valueType = type(of: value)
+    if valueType == Double.self {
+      return try Double.encode(value as! Double, in: runtime)
+    }
+    if valueType == Bool.self {
+      return try Bool.encode(value as! Bool, in: runtime)
+    }
+    if valueType == Int.self {
+      return try Int.encode(value as! Int, in: runtime)
+    }
+    if let dictionary = value as? [String: Any] {
+      return try encodeAnyDictionary(dictionary, in: runtime)
+    }
+    if let array = value as? [Any] {
+      return try encodeAnyArray(array, in: runtime)
+    }
+    if value is NSNull {
+      return .null
+    }
+    if let optional = value as? any FreeFormOptional {
+      guard let wrapped = optional.freeFormWrappedValue else {
+        return .null
+      }
+      return try encodeAny(wrapped, in: runtime)
+    }
+    if let encodable = value as? any JavaScriptEncodable {
+      return try encode(opening: encodable, in: runtime)
+    }
+    if let number = value as? NSNumber {
+      if CFGetTypeID(number) == CFBooleanGetTypeID() {
+        return number.boolValue ? .true() : .false()
+      }
+      return .number(number.doubleValue)
+    }
+    if let representable = value as? any JavaScriptRepresentable {
+      return representable.toJavaScriptValue(in: copy runtime)
+    }
+    throw EncodingError(valueType: valueType)
+  }
+
+  /// Encodes an array of free-form native values into a JavaScript array. Each element is encoded
+  /// with ``encodeAny(_:in:)``.
+  @JavaScriptActor
+  public static func encodeAnyArray(_ value: [Any], in runtime: borrowing JavaScriptRuntime) throws -> JavaScriptValue {
+    let array = runtime.createArray(length: value.count)
+    for (index, element) in value.enumerated() {
+      try array.set(value: encodeAny(element, in: runtime), at: index)
+    }
+    return array.asValue()
+  }
+
+  /// Encodes a string-keyed dictionary of free-form native values into a JavaScript object. Each
+  /// value is encoded with ``encodeAny(_:in:)``.
+  @JavaScriptActor
+  public static func encodeAnyDictionary(_ value: [String: Any], in runtime: borrowing JavaScriptRuntime) throws
+    -> JavaScriptValue
+  {
+    let object = runtime.createObject()
+    for (key, element) in value {
+      object.setProperty(key, value: try encodeAny(element, in: runtime))
+    }
+    return object.asValue()
+  }
+
+  // MARK: - Helpers
+
+  @JavaScriptActor
+  private static func freeFormValue(
+    of value: borrowing JavaScriptValue,
+    depth: Int,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> Any {
+    if value.isString() {
+      return value.getString()
+    }
+    if value.isNumber() {
+      return value.getDouble()
+    }
+    if value.isBool() {
+      return value.getBool()
+    }
+    if value.isObject() {
+      return try freeFormValue(ofObject: value.getObject(), depth: depth, in: runtime)
+    }
+    if value.isNull() || value.isUndefined() {
+      return Optional<Any>.none as Any
+    }
+    if value.isBigInt() {
+      return try value.getBigInt().asInt64()
+    }
+    throw TypeError(type: Any.self, reason: unrepresentableValueReason)
+  }
+
+  @JavaScriptActor
+  private static func freeFormValue(
+    of value: borrowing JavaScriptUnownedValue,
+    depth: Int,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> Any {
+    if value.isString() {
+      return value.getString()
+    }
+    if value.isNumber() {
+      return value.getDouble()
+    }
+    if value.isBool() {
+      return value.getBool()
+    }
+    if value.isObject() {
+      return try freeFormValue(ofObject: value.getObject(in: copy runtime), depth: depth, in: runtime)
+    }
+    if value.isNull() || value.isUndefined() {
+      return Optional<Any>.none as Any
+    }
+    if value.isBigInt() {
+      // The borrowed value has no bigint accessor, so this rare case goes through an owning copy.
+      return try value.copied(in: copy runtime).getBigInt().asInt64()
+    }
+    throw TypeError(type: Any.self, reason: unrepresentableValueReason)
+  }
+
+  @JavaScriptActor
+  private static func freeFormValue(
+    ofObject object: borrowing JavaScriptObject,
+    depth: Int,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> Any {
+    if object.isArray() {
+      return try freeFormElements(of: object.getArray(), depth: depth, in: runtime)
+    }
+    if object.isFunction() {
+      throw TypeError(type: Any.self, reason: unrepresentableValueReason)
+    }
+    try rejectBinaryData(object)
+    let keys = object.getPropertyNames()
+    if keys.isEmpty {
+      // A `Date`, `Set`, `Map`, `WeakMap`, `WeakSet` or `DataView` has no enumerable properties, so only
+      // an object without any can be one. This keeps the global lookup and `instanceof` walk of `is(_:)`
+      // off objects that have properties.
+      let value = object.asValue()
+      if value.is("Date") {
+        return try Date.decode(value, in: runtime)
+      }
+      if value.is("Set") {
+        // A `Set` has no native free-form counterpart (a Swift `Set` needs hashable elements), so it
+        // decodes as an array of its elements, in insertion order.
+        let elements = try runtime.global()
+          .getPropertyAsObject("Array")
+          .getPropertyAsFunction("from")
+          .call(arguments: value)
+        return try freeFormElements(of: elements.asArray(), depth: depth, in: runtime)
+      }
+      if value.is("Map") {
+        // A `Map` keeps its entries outside its properties, so it's read through its `[key, value]`
+        // pairs. Only string keys have a dictionary counterpart; any other key throws.
+        let entries = try runtime.global()
+          .getPropertyAsObject("Array")
+          .getPropertyAsFunction("from")
+          .call(arguments: value)
+        return try freeFormMapEntries(of: entries.asArray(), depth: depth, in: runtime)
+      }
+      if value.is("WeakMap") || value.is("WeakSet") {
+        throw TypeError(type: Any.self, reason: weakCollectionReason)
+      }
+      if value.is("DataView") {
+        throw TypeError(type: Any.self, reason: binaryDataReason)
+      }
+    }
+    return try freeFormProperties(of: object, keys: keys, depth: depth, in: runtime)
+  }
+
+  /// Decodes a top-level object exactly as it would decode nested inside a value, then requires a
+  /// dictionary, so a top-level `Map` converts and a function, `Date`, `Set` or array throws, just as
+  /// through `decodeAny(_:as: [String: Any].self)`.
+  @JavaScriptActor
+  private static func freeFormDictionary(
+    of object: borrowing JavaScriptObject,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> [String: Any] {
+    guard let dictionary = try freeFormValue(ofObject: object, depth: 0, in: runtime) as? [String: Any] else {
+      throw TypeError(type: [String: Any].self, reason: castFailureReason(for: [String: Any].self))
+    }
+    return dictionary
+  }
+
+  @JavaScriptActor
+  private static func freeFormElements(
+    of array: borrowing JavaScriptArray,
+    depth: Int,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> [Any] {
+    try checkDepth(depth)
+    var index = 0
+    return try array.map { element in
+      defer {
+        index += 1
+      }
+      do {
+        return try freeFormValue(of: element, depth: depth + 1, in: runtime)
+      } catch let error as TypeError {
+        throw error.prependingPath("[\(index)]")
+      }
+    }
+  }
+
+  @JavaScriptActor
+  private static func freeFormProperties(
+    of object: borrowing JavaScriptObject,
+    keys: [String],
+    depth: Int,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> [String: Any] {
+    try checkDepth(depth)
+    var result = [String: Any](minimumCapacity: keys.count)
+    for key in keys {
+      let property = object.getProperty(key)
+      if property.isUndefined() {
+        continue
+      }
+      do {
+        result[key] = try freeFormValue(of: property, depth: depth + 1, in: runtime)
+      } catch let error as TypeError {
+        throw error.prependingPath(".\(key)")
+      }
+    }
+    return result
+  }
+
+  /// Wraps a decoded non-array value in a single-element array, unless it already is an array, which
+  /// only a `Set` decodes to. Wrapping a `Set` would add a level that the generic path doesn't.
+  private static func wrappingInArray(_ decoded: Any) -> [Any] {
+    if let elements = decoded as? [Any] {
+      return elements
+    }
+    return [decoded]
+  }
+
+  /// Decodes the `[key, value]` pairs of a `Map` into a dictionary. Throws for a key that isn't a
+  /// string, since a dictionary key would have to be a string the entry doesn't have.
+  @JavaScriptActor
+  private static func freeFormMapEntries(
+    of entries: borrowing JavaScriptArray,
+    depth: Int,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> [String: Any] {
+    try checkDepth(depth)
+    var result = [String: Any](minimumCapacity: entries.length)
+    for index in 0..<entries.length {
+      let entry = try entries.getValue(at: index).asArray()
+      let key = try entry.getValue(at: 0)
+      guard key.isString() else {
+        throw TypeError(type: Any.self, reason: nonStringMapKeyReason)
+      }
+      let name = key.getString()
+      let value = try entry.getValue(at: 1)
+      // An `undefined` value means "absent", as it does for an object property.
+      if value.isUndefined() {
+        continue
+      }
+      do {
+        result[name] = try freeFormValue(of: value, depth: depth + 1, in: runtime)
+      } catch let error as TypeError {
+        throw error.prependingPath(".\(name)")
+      }
+    }
+    return result
+  }
+
+  /// Throws for a typed array or `ArrayBuffer`, whose bytes would otherwise decode as a dictionary
+  /// keyed by index, or as an empty one.
+  @JavaScriptActor
+  private static func rejectBinaryData(_ object: borrowing JavaScriptObject) throws {
+    if object.isTypedArray() || object.isArrayBuffer() {
+      throw TypeError(type: Any.self, reason: binaryDataReason)
+    }
+  }
+
+  /// Throws once a value is nested deeper than `maxFreeFormDepth`, which stops a cycle from
+  /// recursing until the stack overflows.
+  private static func checkDepth(_ depth: Int) throws {
+    if depth >= maxFreeFormDepth {
+      throw TypeError(type: Any.self, reason: nestingTooDeepReason)
+    }
+  }
+
+  /// Opens the existential so the conforming type's own `encode` runs.
+  @JavaScriptActor
+  private static func encode<Value: JavaScriptEncodable>(
+    opening value: Value,
+    in runtime: borrowing JavaScriptRuntime
+  ) throws -> JavaScriptValue {
+    return try Value.encode(value, in: runtime)
+  }
+}
+
+// MARK: - Errors
+
+/// The deepest nesting of arrays and objects that free-form decoding accepts.
+private let maxFreeFormDepth = 64
+
+/// The `TypeError` reason for a JavaScript value that has no free-form native form.
+private let unrepresentableValueReason =
+  "Cannot convert a JavaScript function or symbol to a native value, because neither has a native representation. Remove it from the value before passing it to native code, or declare the native type as JavaScriptValue to receive it unconverted."
+
+/// The `TypeError` reason for a typed array, `ArrayBuffer` or `DataView` inside a free-form value.
+private let binaryDataReason =
+  "Cannot convert a typed array, ArrayBuffer or DataView to a free-form native value, because free-form values hold only primitives, plain objects, arrays and dates. Convert it to an array first (for example, with Array.from), or declare the native type as JavaScriptValue to receive it unconverted."
+
+/// The `TypeError` reason for a `WeakMap` or `WeakSet` inside a free-form value.
+private let weakCollectionReason =
+  "Cannot convert a WeakMap or WeakSet to a native value, because JavaScript doesn't allow reading their entries. Pass a Map or Set instead, or declare the native type as JavaScriptValue to receive it unconverted."
+
+/// The `TypeError` reason for a `Map` with a key that isn't a string.
+private let nonStringMapKeyReason =
+  "Cannot convert a Map with a key that isn't a string to a native value, because it decodes as a dictionary, whose keys are strings. Use only string keys, convert the Map to an array of entries first (for example, with Array.from), or declare the native type as JavaScriptValue to receive it unconverted."
+
+/// The `TypeError` reason for a value nested deeper than `maxFreeFormDepth`.
+private let nestingTooDeepReason =
+  "Cannot convert a JavaScript value nested more than \(maxFreeFormDepth) levels deep to a native value, most likely because it contains a reference to itself (a cycle). Remove the cycle before passing the value to native code, or declare the native type as JavaScriptValue to receive it unconverted."
+
+/// The `TypeError` reason for a decoded free-form value that doesn't cast to the requested type.
+private func castFailureReason(for type: Any.Type) -> String {
+  return
+    "Cannot convert the JavaScript value to '\(type)', because the decoded value has a different shape. Free-form decoding produces only Bool, Double (for every number), String, Int64, Date, [Any], [String: Any] (object keys are always String) and nil. Declare the type in terms of these, for example [String: Any] rather than [Int: Any], or pass a value of the expected shape."
+}
+
+extension JavaScriptValue.TypeError {
+  /// Returns the error with `component` (such as `.key` or `[2]`) added to the front of its path, as
+  /// the error passes up through each container on the way out.
+  fileprivate func prependingPath(_ component: String) -> Self {
+    var error = self
+    error.path = component + path
+    return error
+  }
+}
+
+extension JavaScriptValue {
+  /// Thrown by ``JavaScriptValue/encodeAny(_:in:)`` for a value it can't convert to JavaScript.
+  public struct EncodingError: Error, CustomStringConvertible {
+    let valueType: Any.Type
+
+    public var description: String {
+      return
+        "Cannot convert a value of type '\(valueType)' to a JavaScript value, because it isn't a string, number, boolean, null, array, dictionary, or a JavaScriptEncodable value. Convert it to one of these types first, or make '\(valueType)' conform to JavaScriptEncodable."
+    }
+  }
+}
+
+// MARK: - Optional support
+
+/// Lets `encodeAny` unwrap an `Optional` found inside `Any`, whose wrapped type isn't known statically.
+private protocol FreeFormOptional {
+  var freeFormWrappedValue: Any? { get }
+}
+
+extension Optional: FreeFormOptional {
+  var freeFormWrappedValue: Any? {
+    return self.map { $0 as Any }
+  }
+}

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

@@ -92,6 +92,14 @@ public struct JavaScriptObject: JavaScriptType, Sendable, ~Copyable {
     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 expo.isTypedArray(runtime.pointee, pointee)
+  }
+
   /// Returns the object as an array buffer, or asserts if not an array buffer.
   public func getArrayBuffer() -> JavaScriptArrayBuffer {
     guard let runtime else {

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

@@ -732,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)))"
     }
   }
 }

package/apple/Tests/JavaScriptCodableAnyTests.swift

@@ -0,0 +1,531 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Foundation
+import Testing
+
+@Suite("JavaScriptCodable+Any")
+@JavaScriptActor
+struct JavaScriptCodableAnyTests {
+  let runtime = JavaScriptRuntime()
+
+  // MARK: - decodeAny
+
+  @Test
+  func `decodes primitives into their native types`() throws {
+    #expect(try JavaScriptValue.decodeAny(runtime.eval("true"), in: runtime) as? Bool == true)
+    #expect(try JavaScriptValue.decodeAny(runtime.eval("1.5"), in: runtime) as? Double == 1.5)
+    #expect(try JavaScriptValue.decodeAny(runtime.eval("'abc'"), in: runtime) as? String == "abc")
+  }
+
+  @Test
+  func `decodes numbers as doubles`() throws {
+    let decoded = try JavaScriptValue.decodeAny(runtime.eval("3"), in: runtime)
+    #expect(decoded is Double)
+    #expect(decoded as? Double == 3)
+  }
+
+  @Test
+  func `decodes null and undefined as nil`() throws {
+    #expect(try isNil(JavaScriptValue.decodeAny(runtime.eval("null"), in: runtime)))
+    #expect(try isNil(JavaScriptValue.decodeAny(runtime.eval("undefined"), in: runtime)))
+  }
+
+  @Test
+  func `decodes nested containers`() throws {
+    let decoded = try JavaScriptValue.decodeAny(
+      runtime.eval("({ list: [1, 'a', null], inner: { flag: false } })"),
+      in: runtime
+    )
+    let dictionary = try #require(decoded as? [String: Any])
+    let list = try #require(dictionary["list"] as? [Any])
+    let inner = try #require(dictionary["inner"] as? [String: Any])
+    #expect(list.count == 3)
+    #expect(list[0] as? Double == 1)
+    #expect(list[1] as? String == "a")
+    #expect(isNil(list[2]))
+    #expect(inner["flag"] as? Bool == false)
+  }
+
+  @Test
+  func `decodes from a borrowed value`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("({ a: 'x' })"))
+    let decoded = try JavaScriptValue.decodeAny(buffer.unownedValue(at: 0), in: runtime)
+    #expect((decoded as? [String: Any])?["a"] as? String == "x")
+  }
+
+  @Test
+  func `decodes a bigint within the Int64 range as Int64`() throws {
+    #expect(try JavaScriptValue.decodeAny(runtime.eval("42n"), in: runtime) as? Int64 == 42)
+  }
+
+  @Test
+  func `throws for a bigint outside the Int64 range`() throws {
+    #expect(throws: BigIntConversionError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("2n ** 64n"), in: runtime)
+    }
+  }
+
+  @Test
+  func `throws TypeError for a function`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("(() => {})"), in: runtime)
+    }
+  }
+
+  @Test
+  func `throws TypeError for a symbol`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("Symbol('s')"), in: runtime)
+    }
+  }
+
+  @Test
+  func `throws TypeError for a function nested in a container`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAnyDictionary(runtime.eval("({ callback() {} })"), in: runtime)
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAnyArray(runtime.eval("[1, () => {}]"), in: runtime)
+    }
+  }
+
+  @Test
+  func `throws TypeError for a borrowed function`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("(() => {})"))
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(buffer.unownedValue(at: 0), in: runtime)
+    }
+  }
+
+  @Test
+  func `decodes a borrowed bigint as Int64`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("7n"))
+    let decoded = try JavaScriptValue.decodeAny(buffer.unownedValue(at: 0), in: runtime)
+    #expect(decoded as? Int64 == 7)
+  }
+
+  @Test
+  func `decodes a Date as Date`() throws {
+    let decoded = try JavaScriptValue.decodeAny(runtime.eval("({ at: new Date(1500) })"), in: runtime)
+    #expect((decoded as? [String: Any])?["at"] as? Date == Date(timeIntervalSince1970: 1.5))
+  }
+
+  @Test
+  func `decodes a borrowed Date as Date`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("new Date(1500)"))
+    let decoded = try JavaScriptValue.decodeAny(buffer.unownedValue(at: 0), in: runtime)
+    #expect(decoded as? Date == Date(timeIntervalSince1970: 1.5))
+  }
+
+  @Test
+  func `round-trips a Date through encode and decode`() throws {
+    let date = Date(timeIntervalSince1970: 2)
+    let decoded = try JavaScriptValue.decodeAny(JavaScriptValue.encodeAny(date, in: runtime), in: runtime)
+    #expect(decoded as? Date == date)
+  }
+
+  @Test
+  func `decodes a Map with string keys as a dictionary and a Set as an array of its elements`() throws {
+    let decoded = try JavaScriptValue.decodeAnyDictionary(
+      runtime.eval("({ map: new Map([['k', 1], ['n', { x: true }]]), set: new Set([1, 'two', [3]]) })"),
+      in: runtime
+    )
+    let map = try #require(decoded["map"] as? [String: Any])
+    #expect(map.count == 2)
+    #expect(map["k"] as? Double == 1)
+    #expect((map["n"] as? [String: Any])?["x"] as? Bool == true)
+    let set = try #require(decoded["set"] as? [Any])
+    try #require(set.count == 3)
+    #expect(set[0] as? Double == 1)
+    #expect(set[1] as? String == "two")
+    #expect((set[2] as? [Any])?.first as? Double == 3)
+  }
+
+  // An `undefined` value means "absent" in a `Map` too, the same as for an object property.
+  @Test
+  func `drops Map entries whose value is undefined`() throws {
+    let decoded = try JavaScriptValue.decodeAnyDictionary(
+      runtime.eval("new Map([['gone', undefined], ['kept', 1]])"),
+      in: runtime
+    )
+    #expect(Array(decoded.keys) == ["kept"])
+  }
+
+  @Test
+  func `throws TypeError for a Map with a key that isn't a string`() throws {
+    let error = #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("({ lookup: new Map([[1, 'one']]) })"), in: runtime)
+    }
+    #expect(error?.description.contains("path: lookup") == true)
+  }
+
+  @Test
+  func `names the path to an unrepresentable value inside a Map`() throws {
+    let error = #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("({ lookup: new Map([['k', () => {}]]) })"), in: runtime)
+    }
+    #expect(error?.description.contains("path: lookup.k") == true)
+  }
+
+  @Test
+  func `throws TypeError for a WeakMap, a WeakSet or a DataView`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("({ cache: new WeakMap() })"), in: runtime)
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("[new WeakSet()]"), in: runtime)
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("({ view: new DataView(new ArrayBuffer(4)) })"), in: runtime)
+    }
+  }
+
+  // An `Error` keeps `message` and `stack` in non-enumerable properties, so only what the caller
+  // added is decoded. This pins the documented limit of decoding from enumerable own properties.
+  @Test
+  func `decodes an Error from its enumerable properties only`() throws {
+    let decoded = try JavaScriptValue.decodeAnyDictionary(
+      runtime.eval("const error = new Error('failed'); error.code = 'E_FAILED'; error"),
+      in: runtime
+    )
+    #expect(Array(decoded.keys) == ["code"])
+    #expect(decoded["code"] as? String == "E_FAILED")
+  }
+
+  @Test
+  func `throws TypeError for a typed array or an ArrayBuffer`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("({ bytes: new Uint8Array(4) })"), in: runtime)
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("[new ArrayBuffer(4)]"), in: runtime)
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAnyDictionary(runtime.eval("new Float64Array(4)"), in: runtime)
+    }
+  }
+
+  @Test
+  func `throws TypeError for a cyclic value`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAnyDictionary(
+        runtime.eval("const object = {}; object.self = object; object"),
+        in: runtime
+      )
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAnyArray(runtime.eval("const array = []; array.push(array); array"), in: runtime)
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("const set = new Set(); set.add(set); set"), in: runtime)
+    }
+  }
+
+  @Test
+  func `names the path to an unrepresentable value in the error`() throws {
+    let error = #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("({ user: { tags: ['a', () => {}] } })"), in: runtime)
+    }
+    #expect(error?.description.contains("user.tags[1]") == true)
+  }
+
+  // MARK: - decodeAnyArray
+
+  @Test
+  func `decodes an array of mixed values`() throws {
+    let decoded = try JavaScriptValue.decodeAnyArray(runtime.eval("[true, 2, 'three', [4]]"), in: runtime)
+    #expect(decoded.count == 4)
+    #expect(decoded[0] as? Bool == true)
+    #expect(decoded[1] as? Double == 2)
+    #expect(decoded[2] as? String == "three")
+    #expect((decoded[3] as? [Any])?.first as? Double == 4)
+  }
+
+  @Test
+  func `decodes undefined array elements as nil`() throws {
+    let decoded = try JavaScriptValue.decodeAnyArray(runtime.eval("[undefined, 1]"), in: runtime)
+    #expect(decoded.count == 2)
+    #expect(isNil(decoded[0]))
+  }
+
+  // A `Set` already decodes as an array of its elements, so it isn't wrapped like other non-array
+  // values. This matches `decodeAny(_:as: [Any].self)` and a `Set` nested inside a value.
+  @Test
+  func `decodes a top-level Set as its elements`() throws {
+    let decoded = try JavaScriptValue.decodeAnyArray(runtime.eval("new Set([1, 'two'])"), in: runtime)
+    try #require(decoded.count == 2)
+    #expect(decoded[0] as? Double == 1)
+    #expect(decoded[1] as? String == "two")
+  }
+
+  @Test
+  func `decodes a borrowed top-level Set as its elements`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("new Set([1, 'two'])"))
+    let decoded = try JavaScriptValue.decodeAnyArray(buffer.unownedValue(at: 0), in: runtime)
+    try #require(decoded.count == 2)
+    #expect(decoded[1] as? String == "two")
+  }
+
+  @Test
+  func `arrayizes a non-array value`() throws {
+    let decoded = try JavaScriptValue.decodeAnyArray(runtime.eval("'solo'"), in: runtime)
+    #expect(decoded.count == 1)
+    #expect(decoded[0] as? String == "solo")
+  }
+
+  @Test
+  func `decodes an array from a borrowed value`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("[1, 2]"))
+    let decoded = try JavaScriptValue.decodeAnyArray(buffer.unownedValue(at: 0), in: runtime)
+    #expect(decoded.compactMap { $0 as? Double } == [1, 2])
+  }
+
+  // MARK: - decodeAnyDictionary
+
+  @Test
+  func `decodes an object of mixed values`() throws {
+    let decoded = try JavaScriptValue.decodeAnyDictionary(runtime.eval("({ a: 1, b: 'two', c: null })"), in: runtime)
+    #expect(decoded.count == 3)
+    #expect(decoded["a"] as? Double == 1)
+    #expect(decoded["b"] as? String == "two")
+    #expect(decoded.keys.contains("c"))
+    #expect(isNil(decoded["c"]!))
+  }
+
+  @Test
+  func `drops undefined properties`() throws {
+    let decoded = try JavaScriptValue.decodeAnyDictionary(runtime.eval("({ a: undefined, b: 1 })"), in: runtime)
+    #expect(Array(decoded.keys) == ["b"])
+  }
+
+  @Test
+  func `throws TypeError for a non-object value`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAnyDictionary(runtime.eval("42"), in: runtime)
+    }
+  }
+
+  // The dedicated dictionary path must treat a top-level value the same way as a nested one, and the
+  // same way as the generic `decodeAny(_:as: [String: Any].self)`.
+  @Test
+  func `decodes a top-level Map with string keys as a dictionary`() throws {
+    let decoded = try JavaScriptValue.decodeAnyDictionary(runtime.eval("new Map([['a', 1]])"), in: runtime)
+    #expect(decoded.count == 1)
+    #expect(decoded["a"] as? Double == 1)
+  }
+
+  @Test
+  func `decodes a borrowed top-level Map with string keys as a dictionary`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("new Map([['a', 1]])"))
+    let decoded = try JavaScriptValue.decodeAnyDictionary(buffer.unownedValue(at: 0), in: runtime)
+    #expect(decoded["a"] as? Double == 1)
+  }
+
+  @Test(arguments: [
+    "[1, 2]",
+    "new Date(0)",
+    "new Set([1])",
+    "(() => {})",
+    "new WeakMap()",
+    "new WeakSet()",
+    "new DataView(new ArrayBuffer(4))",
+    "new Map([[1, 'one']])",
+  ])
+  func `throws TypeError for a top-level value that isn't a dictionary`(source: String) throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAnyDictionary(runtime.eval(source), in: runtime)
+    }
+  }
+
+  @Test
+  func `decodes an object from a borrowed value`() throws {
+    let buffer = try JavaScriptValuesBuffer.allocate(in: runtime, with: runtime.eval("({ k: true })"))
+    let decoded = try JavaScriptValue.decodeAnyDictionary(buffer.unownedValue(at: 0), in: runtime)
+    #expect(decoded["k"] as? Bool == true)
+  }
+
+  // MARK: - decodeAny(_:as:in:)
+
+  @Test
+  func `decodes a nested free-form type`() throws {
+    let decoded = try JavaScriptValue.decodeAny(runtime.eval("[[1], ['a', 'b']]"), as: [[Any]].self, in: runtime)
+    #expect(decoded.count == 2)
+    #expect(decoded[1].count == 2)
+    #expect(decoded[1][0] as? String == "a")
+  }
+
+  @Test
+  func `decodes null and undefined as nil for an optional type`() throws {
+    #expect(try JavaScriptValue.decodeAny(runtime.eval("null"), as: [String: [Any]]?.self, in: runtime) == nil)
+    #expect(try JavaScriptValue.decodeAny(runtime.eval("undefined"), as: [String: [Any]]?.self, in: runtime) == nil)
+  }
+
+  @Test
+  func `decodes a present value for an optional type`() throws {
+    let decoded = try JavaScriptValue.decodeAny(runtime.eval("({ a: [1] })"), as: [String: [Any]]?.self, in: runtime)
+    #expect(decoded?["a"]?.first as? Double == 1)
+  }
+
+  @Test
+  func `throws TypeError when the value doesn't match the type`() throws {
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("'text'"), as: [String: [Any]].self, in: runtime)
+    }
+    #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("null"), as: [[Any]].self, in: runtime)
+    }
+  }
+
+  @Test
+  func `explains how free-form values decode when the cast fails`() throws {
+    let error = #expect(throws: JavaScriptValue.TypeError.self) {
+      try JavaScriptValue.decodeAny(runtime.eval("({ 1: 'one' })"), as: [Int: Any].self, in: runtime)
+    }
+    #expect(error?.description.contains("Double") == true)
+    #expect(error?.description.contains("String") == true)
+  }
+
+  @Test
+  func `decodes a nested null as nil for a nested optional`() throws {
+    let dictionary = try JavaScriptValue.decodeAny(
+      runtime.eval("({ a: null, b: [1] })"),
+      as: [String: [Any]?].self,
+      in: runtime
+    )
+    #expect(dictionary.keys.contains("a"))
+    #expect(dictionary["a"]! == nil)
+    #expect(dictionary["b"]??.first as? Double == 1)
+    let list = try JavaScriptValue.decodeAny(runtime.eval("[null, 1]"), as: [Any?].self, in: runtime)
+    #expect(list.count == 2)
+    #expect(list[0] == nil)
+    #expect(list[1] as? Double == 1)
+  }
+
+  // MARK: - encodeAny
+
+  @Test
+  func `encodes native primitives`() throws {
+    #expect(try JavaScriptValue.encodeAny("abc", in: runtime).getString() == "abc")
+    #expect(try JavaScriptValue.encodeAny(1.5, in: runtime).getDouble() == 1.5)
+    #expect(try JavaScriptValue.encodeAny(true, in: runtime).getBool() == true)
+    #expect(try JavaScriptValue.encodeAny(42, in: runtime).getInt() == 42)
+  }
+
+  @Test
+  func `throws for an Int outside the safe-integer range, like Int.encode`() throws {
+    #expect(throws: (any Error).self) {
+      try JavaScriptValue.encodeAny(9_007_199_254_740_993, in: runtime)
+    }
+    #expect(throws: (any Error).self) {
+      try JavaScriptValue.encodeAnyDictionary(["big": 9_007_199_254_740_993], in: runtime)
+    }
+  }
+
+  @Test
+  func `encodes boolean NSNumbers as booleans and other NSNumbers as numbers`() throws {
+    let yes = try JavaScriptValue.encodeAny(NSNumber(value: true), in: runtime)
+    let one = try JavaScriptValue.encodeAny(NSNumber(value: 1), in: runtime)
+    #expect(yes.isBool())
+    #expect(yes.getBool() == true)
+    #expect(one.isNumber())
+    #expect(one.getDouble() == 1)
+  }
+
+  @Test
+  func `encodes nil and NSNull as null`() throws {
+    let none: String? = nil
+    #expect(try JavaScriptValue.encodeAny(none as Any, in: runtime).isNull())
+    #expect(try JavaScriptValue.encodeAny(NSNull(), in: runtime).isNull())
+  }
+
+  @Test
+  func `encodes a present optional as its wrapped value`() throws {
+    let some: Any? = "wrapped"
+    #expect(try JavaScriptValue.encodeAny(some as Any, in: runtime).getString() == "wrapped")
+  }
+
+  @Test
+  func `encodes nested free-form containers`() throws {
+    let value: [[Any]] = [[1, "a"], [["k": true] as [String: Any]]]
+    let encoded = try JavaScriptValue.encodeAny(value, in: runtime)
+    runtime.global().setProperty("encoded", value: encoded)
+    #expect(try runtime.eval("JSON.stringify(encoded)").getString() == #"[[1,"a"],[{"k":true}]]"#)
+  }
+
+  @Test
+  func `encodes JavaScriptEncodable values`() throws {
+    let date = Date(timeIntervalSince1970: 1)
+    let encoded = try JavaScriptValue.encodeAny(date, in: runtime)
+    #expect(encoded.isObject())
+    #expect(try JavaScriptValue.encodeAny([1, 2] as [Int], in: runtime).getArray().length == 2)
+  }
+
+  @Test
+  func `round-trips a bigint through Int64`() throws {
+    let decoded = try JavaScriptValue.decodeAny(runtime.eval("9007199254740993n"), in: runtime)
+    let encoded = try JavaScriptValue.encodeAny(decoded, in: runtime)
+    try #require(encoded.isBigInt())
+    #expect(try encoded.getBigInt().asInt64() == 9_007_199_254_740_993)
+  }
+
+  @Test
+  func `passes a JavaScriptValue through`() throws {
+    let object = try runtime.eval("({ marker: 7 })")
+    let encoded = try JavaScriptValue.encodeAny(object, in: runtime)
+    #expect(encoded.getObject().getProperty("marker").getInt() == 7)
+  }
+
+  @Test
+  func `throws for a value with no JavaScript representation`() throws {
+    struct Opaque {}
+    #expect(throws: JavaScriptValue.EncodingError.self) {
+      try JavaScriptValue.encodeAny(Opaque(), in: runtime)
+    }
+  }
+
+  // MARK: - encodeAnyArray / encodeAnyDictionary
+
+  @Test
+  func `encodes an array of mixed values`() throws {
+    let encoded = try JavaScriptValue.encodeAnyArray([true, 2, "three", NSNull()], in: runtime)
+    runtime.global().setProperty("encoded", value: encoded)
+    #expect(try runtime.eval("JSON.stringify(encoded)").getString() == #"[true,2,"three",null]"#)
+  }
+
+  @Test
+  func `encodes a dictionary of mixed values`() throws {
+    let encoded = try JavaScriptValue.encodeAnyDictionary(["a": 1, "b": ["x", false] as [Any]], in: runtime)
+    let object = encoded.getObject()
+    #expect(object.getProperty("a").getInt() == 1)
+    runtime.global().setProperty("encoded", value: object.getProperty("b"))
+    #expect(try runtime.eval("JSON.stringify(encoded)").getString() == #"["x",false]"#)
+  }
+
+  @Test
+  func `round-trips a dictionary through decode and encode`() throws {
+    let decoded = try JavaScriptValue.decodeAnyDictionary(
+      runtime.eval("({ n: 1.5, s: 's', l: [true, null], o: { z: 0 } })"),
+      in: runtime
+    )
+    let encoded = try JavaScriptValue.encodeAnyDictionary(decoded, in: runtime)
+    runtime.global().setProperty("encoded", value: encoded)
+    #expect(
+      try runtime.eval("JSON.stringify(encoded, ['l', 'n', 'o', 's', 'z'])").getString()
+        == #"{"l":[true,null],"n":1.5,"o":{"z":0},"s":"s"}"#
+    )
+  }
+}
+
+/// True when a free-form value is `nil`, looking through any optionals it's boxed in (a decoded
+/// `null` is a `nil` boxed in `Any`, which `== nil` doesn't see).
+private func isNil(_ value: Any) -> Bool {
+  let mirror = Mirror(reflecting: value)
+  guard mirror.displayStyle == .optional else {
+    return false
+  }
+  guard let wrapped = mirror.children.first else {
+    return true
+  }
+  return isNil(wrapped.value)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-jsi",
-  "version": "58.0.6",
+  "version": "58.0.7",
   "description": "The JavaScript Interface for Expo Modules",
   "main": "index.js",
   "sideEffects": [],