expo-modules-jsi 58.0.6 → 58.0.8

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
@@ -732,9 +785,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/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/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)
+}