expo-modules-jsi 57.0.6 → 57.0.8

package/CHANGELOG.md

@@ -10,6 +10,33 @@
 
 ### 💡 Others
 
+## 57.0.8 — 2026-09-04
+
+### 🎉 New features
+
+- [iOS] Add `JavaScriptRuntime.collectGarbage(cause:)` that requests a full garbage collection through the runtime's JSI instrumentation. It is a no-op on engines whose runtime doesn't implement GC instrumentation, unlike the Hermes-only `gc()` global that the tests used to evaluate. ([#48446](https://github.com/expo/expo/pull/48446) by [@tsapeta](https://github.com/tsapeta))
+
+### 🐛 Bug fixes
+
+- [iOS] Fixed `JavaScriptPropNameID(_:string:)` and the array's string-keyed subscript truncating non-ASCII property keys: they passed `String.count` (the grapheme-cluster count) as the UTF-8 byte length to `PropNameID::forUtf8`, so keys like `"café"` or `"🎉"` were built from mangled bytes and no longer matched the intended property. ([#48329](https://github.com/expo/expo/pull/48329) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Fixed the prebuilt `ExpoModulesJSI.xcframework` shipping with code coverage instrumentation: building through the auto-generated SwiftPM scheme made Xcode pass `-profile-generate -profile-coverage-mapping` to swiftc even for a plain Release `build`, adding a counter increment to every function on the host function call path and about 40% to the binary size. The benchmark target had the same instrumentation and now runs without it. ([#49637](https://github.com/expo/expo/pull/49637) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Fixed property names with non-ASCII characters being mangled when accessed by name from Swift, such as `getProperty`, `setProperty`, `hasProperty`, the array string subscript and dictionary conversions. ([#49679](https://github.com/expo/expo/pull/49679) by [@tsapeta](https://github.com/tsapeta))
+
+### 💡 Others
+
+- [iOS] Added an opt-in benchmark target that measures value access, host function calls, and JS function calls; run it with `pnpm benchmark`. ([#49579](https://github.com/expo/expo/pull/49579) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Reduced the native overhead of synchronous host function calls and host object property accessors by removing the per-call weak and unowned runtime reference traffic on the call path. ([#49631](https://github.com/expo/expo/pull/49631) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Made passing strings between JavaScript and Swift faster, up to ~3.8× for long strings. ([#49678](https://github.com/expo/expo/pull/49678) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Values returned to Swift from property reads, array reads and function calls are now taken over instead of cloned through the engine, making `toJavaScriptValue(in:)` ~1.16× faster. ([#49688](https://github.com/expo/expo/pull/49688) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Made decoding non-ASCII JS strings up to 512 UTF-16 code units long ~1.5× faster. ([#49691](https://github.com/expo/expo/pull/49691) by [@tsapeta](https://github.com/tsapeta))
+
+## 57.0.7 — 2026-09-01
+
+### 💡 Others
+
+- [iOS] `JavaScriptValue.undefined` and `JavaScriptValue.null` now return shared immortal instances instead of allocating a new value on each access, removing one allocation from every void-returning host call. ([#49545](https://github.com/expo/expo/pull/49545) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] `CppError::tryCatch` now takes a C++ callable instead of an Objective-C block. Every caller already passes a pure C++ body, so the block bridged no Swift closure and only added a non-inlinable indirect call and an Objective-C runtime dependency on the JS call/eval error-handling path. ([#48333](https://github.com/expo/expo/pull/48333) by [@tsapeta](https://github.com/tsapeta))
+
 ## 57.0.6 — 2026-08-26
 
 ### 💡 Others

package/CLAUDE.md

@@ -65,6 +65,41 @@ Tests are in `apple/Tests/` and each file covers one type. Some suites use the g
 
 Run them with `pnpm test` from the package root, which calls `apple/scripts/test.sh`. The script needs an installed host app's `Pods` directory (defaults to `$EXPO_ROOT_DIR/apps/bare-expo/ios/Pods`); override with `PODS_ROOT`. It symlinks React / hermesvm / ReactNativeDependencies xcframeworks into `apple/.test-frameworks/` so SPM can resolve them as relative-path binary targets, generates the `jsi` modulemap, and runs `xcodebuild test` against an iOS Simulator (override with `DESTINATION`). Extra args pass through to xcodebuild — e.g. `pnpm test -only-testing TestName`.
 
+## Benchmarks
+
+Performance benchmarks live in `apple/Benchmarks/` as a separate opt-in test target. Run them with
+`pnpm benchmark` from the package root; it reuses the test harness (`apple/scripts/test.sh`, same
+Pods requirements as tests) but builds in the Release configuration, which is required for
+meaningful numbers. Regular test runs build the target but skip every suite: the suites are gated
+on the `EXPO_BENCHMARK` environment variable, which the script forwards to the test runner via
+`TEST_RUNNER_EXPO_BENCHMARK=1`.
+
+Benchmarks default to the Mac Catalyst destination (the prebuilt xcframeworks ship catalyst
+slices): they run natively on the Mac with no simulator, and measured spreads drop to 1-2% versus
+roughly 10-25% on a simulator. Set `DESTINATION` to override, e.g. for a simulator or device run.
+
+Each benchmark prints one line to the xcodebuild log:
+
+```
+[benchmark] <name>: median <X> ns/op, min <Y> ns/op (<iterations> iterations, <samples> samples)
+```
+
+Every benchmark is a test in the single `JSIBenchmarks` suite (extended across the files), which
+is `.serialized` so only one benchmark runs at a time: the `JavaScriptActor` executor runs jobs
+synchronously on the calling thread, so parallel suites would disturb each other's measurements.
+Each test wraps its content in `benchmarkCase { runtime in ... }`, which creates a fresh runtime
+and runs the case in a high-priority task; at the testing library's default priority the scheduler
+sometimes places the run on efficiency cores, which produced multi-fold run-to-run swings.
+
+Inside a case, the `benchmark(_:runtime:samples:_:)` helper calibrates the iteration count to
+~50ms per sample (two-phase: tenfold growth to get an estimate, then a rescale from the warmup
+run), and collects garbage between samples. The body receives the iteration count and must perform
+exactly that many operations: loop in Swift for micro benchmarks, or pass the count to a
+JavaScript driver function to measure a full JS-to-native round trip (see
+`HostFunctionBenchmarks.swift`, which includes an empty-driver-loop baseline to read the other
+results against). Expect run-to-run medians to agree within roughly ±10-25% on a workstation;
+compare medians, and treat anything within that band as noise.
+
 ## Formatting
 
 Swift sources are formatted with swift-format. From the package root, `pnpm swift:format` rewrites files in place and `pnpm swift:lint` checks without modifying; both delegate to the repo-root `scripts/swift-format.sh`, which reads the repo-root `.swift-format` config and only touches tracked `.swift` files. CI enforces this via `.github/workflows/swift-format.yml`, which pins a specific swift-format version &mdash; mismatched local versions can produce different output, so prefer the pinned one. Style conventions beyond what the formatter enforces live in [`guides/Swift Style Guide.md`](../../guides/Swift%20Style%20Guide.md) at the repo root.

package/apple/Benchmarks/BenchmarkRunner.swift

@@ -0,0 +1,115 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Foundation
+import Testing
+
+/// Whether benchmark suites are enabled for this test run. Benchmarks are opt-in:
+/// regular test runs skip them. Run `pnpm benchmark`, which enables them by forwarding
+/// the `EXPO_BENCHMARK` environment variable to the test runner and builds the package
+/// in the Release configuration so the numbers are meaningful. It also turns code coverage
+/// off: `xcodebuild test` instruments every function and closure with profile counters
+/// otherwise, even in Release, which adds a few nanoseconds to each measured call.
+let benchmarksEnabled = ProcessInfo.processInfo.environment["EXPO_BENCHMARK"] == "1"
+
+/// Umbrella suite that all benchmarks belong to (as extensions in the other files).
+/// It's serialized so only one benchmark runs at a time: the `JavaScriptActor` executor
+/// runs jobs synchronously on the calling thread, so separate suites would execute
+/// concurrently on the parallel testing pool and disturb each other's measurements.
+@Suite(.enabled(if: benchmarksEnabled), .serialized)
+struct JSIBenchmarks {}
+
+/// Runs one benchmark case inside a high-priority task, with a fresh runtime created
+/// for it. The priority matters: the testing library runs tests at default priority,
+/// whose threads the scheduler sometimes places on efficiency cores, which showed up
+/// as multi-fold run-to-run swings in the results. Create the runtime, the measured
+/// values, and the `benchmark(_:runtime:samples:_:)` calls inside the closure.
+func benchmarkCase(_ body: @escaping @JavaScriptActor (JavaScriptRuntime) throws -> Void) async throws {
+  try await Task(priority: .high) { @JavaScriptActor in
+    let runtime = JavaScriptRuntime()
+    try body(runtime)
+  }.value
+}
+
+/// Runs the given body repeatedly and prints a single-line report with the median and
+/// minimum time per operation. The body receives the number of operations to perform,
+/// either in a Swift loop or by passing the count to a JavaScript driver function.
+///
+/// The iteration count is calibrated so that a single sample takes roughly 50ms, and the
+/// garbage collector runs between samples so collection pauses triggered by garbage from
+/// one sample don't land in the next one's measurement.
+@JavaScriptActor
+func benchmark(
+  _ name: String,
+  runtime: JavaScriptRuntime,
+  samples sampleCount: Int = 7,
+  _ body: (_ iterations: Int) throws -> Void
+) rethrows {
+  let clock = ContinuousClock()
+  var iterations = try calibrateIterations(clock: clock, body)
+  // The warmup run doubles as the second calibration phase: it runs at the estimated
+  // iteration count, which is more representative than the short runs the estimate came
+  // from (caches are warm, one-time costs are paid), so rescale the count from it.
+  let warmupElapsed = try clock.measure {
+    try body(iterations)
+  }
+  iterations = rescaleIterations(iterations, elapsed: warmupElapsed)
+  var nanosecondsPerOperation = [Double]()
+  for _ in 0..<sampleCount {
+    runtime.collectGarbage()
+    let elapsed = try clock.measure {
+      try body(iterations)
+    }
+    nanosecondsPerOperation.append(Double(elapsed.nanoseconds) / Double(iterations))
+  }
+  nanosecondsPerOperation.sort()
+  let median = format(nanosecondsPerOperation[nanosecondsPerOperation.count / 2])
+  let minimum = format(nanosecondsPerOperation[0])
+  print(
+    "[benchmark] \(name): median \(median) ns/op, min \(minimum) ns/op"
+      + " (\(iterations) iterations, \(sampleCount) samples)"
+  )
+}
+
+/// How long a single measured sample should take.
+private let targetSampleNanoseconds = 50_000_000.0
+
+/// Finds an iteration count that makes one sample take roughly 50ms. Starts at a single
+/// iteration and grows tenfold until the measured time is long enough to extrapolate from,
+/// so even sub-nanosecond bodies calibrate quickly without overshooting.
+@JavaScriptActor
+private func calibrateIterations(
+  clock: ContinuousClock,
+  _ body: (_ iterations: Int) throws -> Void
+) rethrows -> Int {
+  var iterations = 1
+  while true {
+    let elapsed = try clock.measure {
+      try body(iterations)
+    }
+    if elapsed >= .milliseconds(5) || iterations >= 100_000_000 {
+      return rescaleIterations(iterations, elapsed: elapsed)
+    }
+    iterations *= 10
+  }
+}
+
+/// Rescales an iteration count so the next run of that many iterations takes roughly
+/// the target sample duration, given how long `iterations` of the body just took.
+private func rescaleIterations(_ iterations: Int, elapsed: Duration) -> Int {
+  let nanoseconds = max(elapsed.nanoseconds, 1)
+  let rescaled = Int(Double(iterations) * targetSampleNanoseconds / Double(nanoseconds))
+  return min(max(rescaled, 1), 100_000_000)
+}
+
+/// Formats a nanosecond quantity with a single decimal place.
+private func format(_ nanoseconds: Double) -> String {
+  return String(format: "%.1f", nanoseconds)
+}
+
+extension Duration {
+  /// The duration expressed as a whole number of nanoseconds.
+  var nanoseconds: Int64 {
+    return components.seconds * 1_000_000_000 + components.attoseconds / 1_000_000_000
+  }
+}

package/apple/Benchmarks/FunctionCallBenchmarks.swift

@@ -0,0 +1,45 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Testing
+
+/// Benchmarks for Swift calling into JavaScript functions, the opposite direction
+/// of the host function benchmarks. Each operation covers encoding the arguments,
+/// the engine's function invocation, and wrapping the returned value.
+extension JSIBenchmarks {
+  @Test
+  func `call noop JS function`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = try runtime.eval("(function() {})").getFunction()
+      try benchmark("JavaScriptFunction.call(): noop", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try fn.call()
+        }
+      }
+    }
+  }
+
+  @Test
+  func `call JS function with two numbers`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = try runtime.eval("(function(a, b) { return a + b; })").getFunction()
+      try benchmark("JavaScriptFunction.call(): add two numbers", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try fn.call(arguments: 3.5, 38.5)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `call JS function with two strings`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = try runtime.eval("(function(a, b) { return a + b; })").getFunction()
+      try benchmark("JavaScriptFunction.call(): concat two strings", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try fn.call(arguments: "expo ", "modules")
+        }
+      }
+    }
+  }
+}

package/apple/Benchmarks/HostFunctionBenchmarks.swift

@@ -0,0 +1,217 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Testing
+
+/// End-to-end benchmarks for JavaScript calling into Swift host functions.
+/// A JavaScript driver function runs the measured loop, so each operation covers
+/// the full round trip: the engine's call dispatch, argument decoding in Swift,
+/// and encoding the result back to JavaScript.
+extension JSIBenchmarks {
+  /// Measures the raw JavaScript loop that drives the other host function benchmarks,
+  /// so their results can be read relative to the loop's own overhead.
+  @Test
+  func `empty JS loop`() async throws {
+    try await benchmarkCase { runtime in
+      let driver = try runtime.eval("(function(n) { for (var i = 0; i < n; i++); })").getFunction()
+      try benchmark("host function: empty driver loop", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  @Test
+  func `noop host function`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("noop") { _, _ in
+        return .undefined
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval("(function(n) { for (var i = 0; i < n; i++) benchFn(); })").getFunction()
+      try benchmark("host function: noop", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  /// Same as `noop host function`, but through the unowned-`this` closure form that
+  /// macro-generated `@JS` functions bind to.
+  @Test
+  func `noop unowned-this host function`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("noop") {
+        (this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) in
+        return .undefined
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval("(function(n) { for (var i = 0; i < n; i++) benchFn(); })").getFunction()
+      try benchmark("host function: noop unowned-this", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  @Test
+  func `host function concatenating two strings`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("concat") { [runtime] _, arguments in
+        let a = try arguments[0].asString()
+        let b = try arguments[1].asString()
+        return JavaScriptValue(runtime, a + b)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        "(function(n) { for (var i = 0; i < n; i++) benchFn('expo ', 'modules'); })"
+      ).getFunction()
+      try benchmark("host function: concat two strings", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  @Test
+  func `host function adding two numbers`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("add") { [runtime] _, arguments in
+        let a = try arguments[0].asDouble()
+        let b = try arguments[1].asDouble()
+        return JavaScriptValue(runtime, a + b)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        "(function(n) { for (var i = 0; i < n; i++) benchFn(3.5, 38.5); })"
+      ).getFunction()
+      try benchmark("host function: add two numbers", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  // MARK: - Unowned-this form with string arguments
+
+  @Test
+  func `concat two strings unowned-this`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("concat") {
+        [runtime] (this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) in
+        let a = try String.decode(arguments.unownedValue(at: 0), in: runtime)
+        let b = try String.decode(arguments.unownedValue(at: 1), in: runtime)
+        return try String.encode(a + b, in: runtime)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        """
+        (function(n) { for (var i = 0; i < n; i++) benchFn('expo ', 'modules'); })
+        """
+      ).getFunction()
+      try benchmark("host function: concat two strings unowned-this", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  /// Like `concat two strings unowned-this`, with inputs and result longer than libc++'s 22-byte
+  /// `std::string` inline capacity, so every `std::string` on the path has to allocate.
+  @Test
+  func `concat two long strings unowned-this`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("concat") {
+        [runtime] (this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) in
+        let a = try String.decode(arguments.unownedValue(at: 0), in: runtime)
+        let b = try String.decode(arguments.unownedValue(at: 1), in: runtime)
+        return try String.encode(a + b, in: runtime)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        """
+        (function(n) {
+          for (var i = 0; i < n; i++) benchFn('expo modules are quite fast, ', 'and this string is also long');
+        })
+        """
+      ).getFunction()
+      try benchmark("host function: concat two long strings unowned-this", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  @Test
+  func `concat two 256B strings unowned-this`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("concat") {
+        [runtime] (this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) in
+        let a = try String.decode(arguments.unownedValue(at: 0), in: runtime)
+        let b = try String.decode(arguments.unownedValue(at: 1), in: runtime)
+        return try String.encode(a + b, in: runtime)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        "(function(n) { var a = 'a'.repeat(128); var b = 'b'.repeat(128); for (var i = 0; i < n; i++) benchFn(a, b); })"
+      ).getFunction()
+      try benchmark("host function: concat two 256B strings unowned-this", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  @Test
+  func `concat two 4KB strings unowned-this`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("concat") {
+        [runtime] (this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) in
+        let a = try String.decode(arguments.unownedValue(at: 0), in: runtime)
+        let b = try String.decode(arguments.unownedValue(at: 1), in: runtime)
+        return try String.encode(a + b, in: runtime)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        """
+        (function(n) { var a = 'a'.repeat(2048); var b = 'b'.repeat(2048); for (var i = 0; i < n; i++) benchFn(a, b); })
+        """
+      ).getFunction()
+      try benchmark("host function: concat two 4KB strings unowned-this", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  @Test
+  func `concat two 4KB non-ASCII strings unowned-this`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("concat") {
+        [runtime] (this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) in
+        let a = try String.decode(arguments.unownedValue(at: 0), in: runtime)
+        let b = try String.decode(arguments.unownedValue(at: 1), in: runtime)
+        return try String.encode(a + b, in: runtime)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        """
+        (function(n) { var a = 'ą'.repeat(2048); var b = 'ą'.repeat(2048); for (var i = 0; i < n; i++) benchFn(a, b); })
+        """
+      ).getFunction()
+      try benchmark("host function: concat two 4KB non-ASCII strings unowned-this", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+
+  @Test
+  func `concat two 12B non-ASCII strings unowned-this`() async throws {
+    try await benchmarkCase { runtime in
+      let fn = runtime.createFunction("concat") {
+        [runtime] (this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer) in
+        let a = try String.decode(arguments.unownedValue(at: 0), in: runtime)
+        let b = try String.decode(arguments.unownedValue(at: 1), in: runtime)
+        return try String.encode(a + b, in: runtime)
+      }
+      runtime.global().setProperty("benchFn", value: fn)
+      let driver = try runtime.eval(
+        "(function(n) { var a = 'ąęó'.repeat(2); var b = 'ąęó'.repeat(2); for (var i = 0; i < n; i++) benchFn(a, b); })"
+      ).getFunction()
+      try benchmark("host function: concat two 12B non-ASCII strings unowned-this", runtime: runtime) { iterations in
+        _ = try driver.call(arguments: iterations)
+      }
+    }
+  }
+}