expo-modules-jsi 58.0.7 → 58.0.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 58.0.8
+
+### Patch Changes
+
+- [iOS] Add `decodableKinds` to `JavaScriptDecodable`: the kinds of JavaScript value (`JavaScriptValueKinds`) that `decode` can accept, so code that picks between several types can skip the ones that can't match. ([#50905](https://github.com/expo/expo/pull/50905) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Fix crash reports symbolicated on the device showing no function names for `ExpoModulesJSI` frames. ([#50698](https://github.com/expo/expo/pull/50698) by [@tsapeta](https://github.com/tsapeta))
+- Return strings, objects and arrays from host functions and host object getters without cloning the engine handle, and build short ASCII strings from JS inline. ([#50937](https://github.com/expo/expo/pull/50937) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Add `JavaScriptRuntime.cached(_:_:)` with typed `JavaScriptRuntime.Cache.Key`s, to create a value once per runtime and reuse it, for example a JavaScript constructor or a property name. A lookup reads one array slot, about 5× faster than the string-keyed `JavaScriptPropNameID.cached(_:_:)`. ([#50888](https://github.com/expo/expo/pull/50888) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Add `JavaScriptValue.withUnownedValue(in:_:)`, and give the owning `JavaScriptDecodable.decode` a default that borrows the value and decodes it through the `JavaScriptUnownedValue` overload, so a conformer can implement only that one. Arrays, dictionaries, dates, records and enums now decode unowned values without copying them first. ([#50960](https://github.com/expo/expo/pull/50960) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Add `JavaScriptArray.mapUnowned(_:)`, `JavaScriptObject.withUnownedProperty(_:_:)`, and `isArray()` and `getArray(in:)` on `JavaScriptUnownedValue`. Arrays, dictionaries and dates now decode through their unowned overload without copying the value or wrapping each element in a `JavaScriptValue`, and their owning decodes forward to it. ([#50980](https://github.com/expo/expo/pull/50980) by [@tsapeta](https://github.com/tsapeta))
+- [iOS] Keep checkout paths out of the Swift compilation cache key so modules importing ExpoModulesCore can reuse cached compilation results across checkouts and worktrees. ([#50354](https://github.com/expo/expo/pull/50354) by [@janicduplessis](https://github.com/janicduplessis))
+
 ## 58.0.7
 
 ### Patch Changes

package/apple/Benchmarks/RuntimeCacheBenchmarks.swift

@@ -0,0 +1,71 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Testing
+
+private let answerPropNameKey = JavaScriptRuntime.Cache.Key<JavaScriptPropNameID>()
+
+/// Benchmarks for values cached per runtime with ``JavaScriptRuntime/cached(_:_:)``, read against
+/// the string-keyed ``JavaScriptPropNameID/cached(_:_:)`` registry.
+extension JSIBenchmarks {
+  @Test
+  func `runtime cache hit`() async throws {
+    try await benchmarkCase { runtime in
+      _ = runtime.cached(answerPropNameKey) { JavaScriptPropNameID(runtime, string: "answer") }
+      try benchmark("JavaScriptRuntime.cached(_:_:): hit", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = runtime.cached(answerPropNameKey) { JavaScriptPropNameID(runtime, string: "answer") }
+        }
+      }
+    }
+  }
+
+  @Test
+  func `object property by runtime-cached PropNameID`() async throws {
+    try await benchmarkCase { runtime in
+      let object = try runtime.eval("({ answer: 42 })").getObject()
+      try benchmark("JavaScriptObject.getProperty(_:): runtime-cached PropNameID", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = object.getProperty(runtime.cached(answerPropNameKey) { JavaScriptPropNameID(runtime, string: "answer") })
+        }
+      }
+    }
+  }
+
+  @Test
+  func `string-keyed PropNameID cache hit`() async throws {
+    try await benchmarkCase { runtime in
+      try benchmark("JavaScriptPropNameID.cached(_:_:): hit", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = JavaScriptPropNameID.cached(runtime, "answer")
+        }
+      }
+    }
+  }
+
+  @Test
+  func `object property by string-keyed cached PropNameID`() async throws {
+    try await benchmarkCase { runtime in
+      let object = try runtime.eval("({ answer: 42 })").getObject()
+      try benchmark("JavaScriptObject.getProperty(_:): string-cached PropNameID", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = object.getProperty(.cached(runtime, "answer"))
+        }
+      }
+    }
+  }
+
+  @Test
+  func `object property by prebuilt PropNameID`() async throws {
+    try await benchmarkCase { runtime in
+      let object = try runtime.eval("({ answer: 42 })").getObject()
+      let propName = JavaScriptPropNameID(runtime, string: "answer")
+      try benchmark("JavaScriptObject.getProperty(_:): prebuilt PropNameID", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = object.getProperty(propName)
+        }
+      }
+      withExtendedLifetime(propName) {}
+    }
+  }
+}

package/apple/Benchmarks/UnownedDecodeBenchmarks.swift

@@ -0,0 +1,121 @@
+// Copyright 2026-present 650 Industries. All rights reserved.
+
+import ExpoModulesJSI
+import Foundation
+import Testing
+
+/// Decoding from a borrowed `JavaScriptUnownedValue`, the path a `@JS` argument takes, and from an owning
+/// `JavaScriptValue`, the path a nested value takes. A type without its own unowned decode copies the
+/// value into an owning `JavaScriptValue` first.
+extension JSIBenchmarks {
+  @Test
+  func `unowned decode of an array`() async throws {
+    try await benchmarkCase { runtime in
+      let buffer = JavaScriptValuesBuffer.allocate(in: runtime, with: try runtime.eval("[1, 2, 3, 4, 5, 6, 7, 8]"))
+      try benchmark("[Double].decode(unowned): 8 elements", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try [Double].decode(buffer.unownedValue(at: 0), in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `unowned decode of a dictionary`() async throws {
+    try await benchmarkCase { runtime in
+      let buffer = JavaScriptValuesBuffer.allocate(in: runtime, with: try runtime.eval("({ a: 1, b: 2, c: 3, d: 4 })"))
+      try benchmark("[String: Double].decode(unowned): 4 entries", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try [String: Double].decode(buffer.unownedValue(at: 0), in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `unowned decode of a date`() async throws {
+    try await benchmarkCase { runtime in
+      let buffer = JavaScriptValuesBuffer.allocate(in: runtime, with: try runtime.eval("1700000000000"))
+      try benchmark("Date.decode(unowned): number", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try Date.decode(buffer.unownedValue(at: 0), in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `owning decode of an array`() async throws {
+    try await benchmarkCase { runtime in
+      let value = try runtime.eval("[1, 2, 3, 4, 5, 6, 7, 8]")
+      try benchmark("[Double].decode(owning): 8 elements", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try [Double].decode(value, in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `owning decode of a dictionary`() async throws {
+    try await benchmarkCase { runtime in
+      let value = try runtime.eval("({ a: 1, b: 2, c: 3, d: 4 })")
+      try benchmark("[String: Double].decode(owning): 4 entries", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try [String: Double].decode(value, in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `owning decode of nested arrays`() async throws {
+    try await benchmarkCase { runtime in
+      let value = try runtime.eval("[[1, 2], [3, 4], [5, 6], [7, 8]]")
+      try benchmark("[[Double]].decode(owning): 4 x 2 elements", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try [[Double]].decode(value, in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `unowned decode of nested arrays`() async throws {
+    try await benchmarkCase { runtime in
+      let buffer = JavaScriptValuesBuffer.allocate(
+        in: runtime,
+        with: try runtime.eval("[[1, 2], [3, 4], [5, 6], [7, 8]]")
+      )
+      try benchmark("[[Double]].decode(unowned): 4 x 2 elements", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try [[Double]].decode(buffer.unownedValue(at: 0), in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `unowned decode of a date string`() async throws {
+    try await benchmarkCase { runtime in
+      let buffer = JavaScriptValuesBuffer.allocate(in: runtime, with: try runtime.eval("'2026-10-02T12:00:00Z'"))
+      try benchmark("Date.decode(unowned): ISO string", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try Date.decode(buffer.unownedValue(at: 0), in: runtime)
+        }
+      }
+    }
+  }
+
+  @Test
+  func `unowned decode of a date object`() async throws {
+    try await benchmarkCase { runtime in
+      let buffer = JavaScriptValuesBuffer.allocate(in: runtime, with: try runtime.eval("new Date(1700000000000)"))
+      try benchmark("Date.decode(unowned): Date object", runtime: runtime) { iterations in
+        for _ in 0..<iterations {
+          _ = try Date.decode(buffer.unownedValue(at: 0), in: runtime)
+        }
+      }
+    }
+  }
+}

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

@@ -10,19 +10,36 @@
 // MARK: - Array
 
 extension Array: JavaScriptDecodable where Element: JavaScriptDecodable {
+  // A non-array value is decoded as a single-element array, so it's accepted when the element is.
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return Element.decodableKinds.union(.object)
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
     -> [Element]
+  {
+    // Forwards to the unowned overload, which holds the implementation.
+    let runtime = copy runtime
+    return try value.withUnownedValue(in: runtime) { unownedValue in
+      return try decode(unownedValue, in: runtime)
+    }
+  }
+
+  @JavaScriptActor
+  @inlinable
+  public static func decode(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime) throws
+    -> [Element]
   {
     // A non-array value is "arrayized" into a single-element array, so a caller that passes a
     // scalar where an array is expected still works.
     guard value.isArray() else {
       return [try Element.decode(value, in: runtime)]
     }
-    // `map` reads the length once and uses the unchecked element accessor, avoiding a
-    // per-element weak-runtime load and bounds check on this hot path.
-    return try value.getArray().map { element in
+    // Each element is lent out unowned, so it's decoded without a `JavaScriptValue` per element.
+    return try value.getArray(in: runtime).mapUnowned { element in
       return try Element.decode(element, in: runtime)
     }
   }
@@ -45,6 +62,11 @@ extension Array: JavaScriptEncodable where Element: JavaScriptEncodable {
 // MARK: - Optional
 
 extension Optional: JavaScriptDecodable where Wrapped: JavaScriptDecodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return Wrapped.decodableKinds.union([.null, .undefined])
+  }
+
   // Optional copies nothing itself, so it overrides the zero-copy overload too and forwards the
   // borrowed value straight through — a wrapped primitive argument stays fully zero-copy.
   @JavaScriptActor
@@ -87,22 +109,42 @@ extension Optional: JavaScriptEncodable where Wrapped: JavaScriptEncodable {
 // MARK: - Dictionary
 
 extension Dictionary: JavaScriptDecodable where Key == String, Value: JavaScriptDecodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .object
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
     -> [String: Value]
   {
-    let object = try value.asObject()
+    // Forwards to the unowned overload, which holds the implementation.
+    let runtime = copy runtime
+    return try value.withUnownedValue(in: runtime) { unownedValue in
+      return try decode(unownedValue, in: runtime)
+    }
+  }
+
+  @JavaScriptActor
+  @inlinable
+  public static func decode(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime) throws
+    -> [String: Value]
+  {
+    // Reads the object straight from the borrowed value and lends each property out unowned, so it's
+    // decoded without a `JavaScriptValue` per property.
+    let object = try value.asObject(in: runtime)
     let keys = object.getPropertyNames()
     var result = [String: Value](minimumCapacity: keys.count)
     for key in keys {
-      let property = object.getProperty(key)
-      // Treat an `undefined`-valued property as an absent entry. Without this a non-optional
-      // `Value` would reject an object that simply omits the property as `undefined`.
-      if property.isUndefined() {
-        continue
+      let decoded: Value? = try object.withUnownedProperty(key) { property in
+        // Treat an `undefined`-valued property as an absent entry. Without this a non-optional
+        // `Value` would reject an object that simply omits the property as `undefined`.
+        return property.isUndefined() ? nil : try Value.decode(property, in: runtime)
+      }
+      if let decoded {
+        result[key] = decoded
       }
-      result[key] = try Value.decode(property, in: runtime)
     }
     return result
   }

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

@@ -9,6 +9,11 @@ import Foundation
 // read/write rather than a single accessor.
 
 extension Data: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .object
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Data

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

@@ -9,22 +9,44 @@ import Foundation
 // A `Date` is an absolute instant with no timezone/calendar; resolution is milliseconds.
 
 extension Date: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return [.number, .string, .object]
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Date
   {
-    // The cheap tag checks come before `is("Date")`, which does a global lookup plus an `instanceof`
-    // walk; a number or string can't be a `Date`, so the order is behavior-neutral.
+    // Forwards to the unowned overload, which holds the implementation.
+    let runtime = copy runtime
+    return try value.withUnownedValue(in: runtime) { unownedValue in
+      return try decode(unownedValue, in: runtime)
+    }
+  }
+
+  @JavaScriptActor
+  @inlinable
+  public static func decode(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime) throws
+    -> Date
+  {
+    // The cheap tag checks come before the `instanceof` check, which needs a global lookup; a number or
+    // a string can't be a `Date`, so the order is behavior-neutral. Only the string branch copies the
+    // value, since the `Date` constructor takes owning arguments; a string is the rare input.
     if value.isNumber() {
       return try dateFromMilliseconds(value.getDouble())
     }
     if value.isString() {
       let dateConstructor = try runtime.global().getPropertyAsFunction("Date")
-      let constructed = try dateConstructor.callAsConstructor(value.copy()).asObject()
+      let constructed = try dateConstructor.callAsConstructor(value.copied(in: runtime)).asObject()
       return try dateFromMilliseconds(constructed.callFunction("getTime").asDouble())
     }
-    if value.is("Date") {
-      return try dateFromMilliseconds(value.asObject().callFunction("getTime").asDouble())
+    if value.isObject() {
+      let dateConstructor = try runtime.global().getPropertyAsFunction("Date")
+      let object = value.getObject(in: runtime)
+      if object.instanceOf(dateConstructor) {
+        return try dateFromMilliseconds(object.callFunction("getTime").asDouble())
+      }
     }
     throw InvalidDateException()
   }

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

@@ -15,6 +15,11 @@ import CoreGraphics
 // MARK: - Bool
 
 extension Bool: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .bool
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Bool
@@ -40,6 +45,11 @@ extension Bool: JavaScriptCodable {
 // MARK: - String
 
 extension String: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .string
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
@@ -74,6 +84,11 @@ extension String: JavaScriptCodable {
 // undefined behavior — a native crash, not a catchable error.
 
 extension Double: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
@@ -100,6 +115,11 @@ extension Double: JavaScriptCodable {
 }
 
 extension Float: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Float
@@ -123,6 +143,11 @@ extension Float: JavaScriptCodable {
 }
 
 extension CGFloat: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
@@ -170,6 +195,11 @@ extension CGFloat: JavaScriptCodable {
 // back, and a JS caller may pass either form.
 
 extension Int: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return [.number, .bigint]
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Int {
@@ -192,6 +222,11 @@ extension Int: JavaScriptCodable {
 }
 
 extension Int8: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Int8
@@ -215,6 +250,11 @@ extension Int8: JavaScriptCodable {
 }
 
 extension Int16: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Int16
@@ -238,6 +278,11 @@ extension Int16: JavaScriptCodable {
 }
 
 extension Int32: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Int32
@@ -261,6 +306,11 @@ extension Int32: JavaScriptCodable {
 }
 
 extension Int64: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return [.number, .bigint]
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Int64
@@ -284,6 +334,11 @@ extension Int64: JavaScriptCodable {
 }
 
 extension UInt: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return [.number, .bigint]
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> UInt
@@ -307,6 +362,11 @@ extension UInt: JavaScriptCodable {
 }
 
 extension UInt8: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> UInt8
@@ -330,6 +390,11 @@ extension UInt8: JavaScriptCodable {
 }
 
 extension UInt16: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
@@ -356,6 +421,11 @@ extension UInt16: JavaScriptCodable {
 }
 
 extension UInt32: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .number
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws
@@ -382,6 +452,11 @@ extension UInt32: JavaScriptCodable {
 }
 
 extension UInt64: JavaScriptCodable {
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return [.number, .bigint]
+  }
+
   @JavaScriptActor
   @inlinable
   public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws

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

@@ -13,9 +13,10 @@
 public protocol JavaScriptDecodable {
   /// Decodes an owning `JavaScriptValue` into `Self`.
   ///
-  /// This overload is the protocol requirement: every conformer provides it. It is also the
-  /// correct entry point for any value that must outlive the call (stored, captured, handed to a
-  /// `Promise`).
+  /// Defaulted (see the extension below) to borrow the value and decode it through the
+  /// `JavaScriptUnownedValue` overload, so a conformer may implement just that one. A conformer must
+  /// implement at least one of the two overloads: each default forwards to the other, so with neither
+  /// implemented a decode recurses until the stack overflows.
   @JavaScriptActor
   static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Self
 
@@ -24,13 +25,35 @@ public protocol JavaScriptDecodable {
   ///
   /// This is the argument-decode fast path: the value borrows the argument the
   /// `JavaScriptValuesBuffer` already owns for the duration of the call. It is defaulted (see the
-  /// extension below), so conformers get it for free by materializing an owning value; types that
-  /// can read straight from the borrowed value override it to stay zero-copy.
+  /// extension below) to materialize an owning value and decode that, for conformers that implement
+  /// only the owning overload; types that can read straight from the borrowed value implement it to
+  /// stay zero-copy.
   @JavaScriptActor
   static func decode(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime) throws -> Self
+
+  /// The kinds of JavaScript value `decode` can accept.
+  ///
+  /// A kind outside the set is definitive: `decode` would throw for a value of that kind. A kind in the
+  /// set only means the type may decode it, so `decode` can still throw, for example for an
+  /// out-of-range number or a missing record field. Code that picks between several types, like a
+  /// union, reads it to skip the ones that can't match without paying for a thrown error. Defaults to
+  /// `.all`, so a type that doesn't declare it is always tried.
+  static var decodableKinds: JavaScriptValueKinds { get }
 }
 
 extension JavaScriptDecodable {
+  /// Default owning decode: borrow the value and forward to the unowned overload, so a conformer that
+  /// implements only that one decodes owning values without a copy.
+  @JavaScriptActor
+  @inlinable
+  public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Self
+  {
+    let runtime = copy runtime
+    return try value.withUnownedValue(in: runtime) { unownedValue in
+      return try decode(unownedValue, in: runtime)
+    }
+  }
+
   /// Default fast-path implementation: materialize an owning value and forward to the requirement.
   /// This is the "explicitly copy" behavior for types that cannot (or need not) read directly from
   /// the borrowed value.
@@ -44,4 +67,10 @@ extension JavaScriptDecodable {
   {
     return try decode(value.copied(in: runtime), in: runtime)
   }
+
+  /// Default: every kind, so a conformer that doesn't declare its kinds is always tried.
+  @inlinable
+  public static var decodableKinds: JavaScriptValueKinds {
+    return .all
+  }
 }