expo-modules-macros 0.20.0 → 0.22.0

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -3,51 +3,59 @@ import SwiftSyntax
 import SwiftSyntaxBuilder
 import SwiftSyntaxMacros
 
-/**
- Member macro applied to a record type. Treats **every stored property** that is not
- `static`, `private`, `fileprivate`, `lazy` or computed as a property — no `@Field` wrapper
- needed — and synthesizes the conversion surface from the property's static type:
-
- - an explicit memberwise `init` (so the static factories have a single construction point),
- - `from(object:appContext:)` — the fast path, reading each property straight off a
-   `JavaScriptObject`,
- - `from(dictionary:appContext:)` — reading each property from a `[String: Any]` dictionary,
- - `toDictionary(appContext:)` and `toObject(appContext:)` for the write side.
-
- The type is auto-conformed to `Record` (a core protocol whose requirements are exactly this
- surface); the synthesized methods override `Record`'s reflection-based defaults. Author-facing
- shape — no conformance to spell out:
-
-   @Record
-   struct Options {
-     var name: String          // required (non-optional, no default)
-     var count: Int = 0        // optional (has default)
-     var note: String?         // nullable + optional
-   }
-
- The JS key is always the property name. Requiredness is inferred from the declaration:
- a default value makes a property optional (the default applies when the source omits it),
- an optional type makes it nullable and optional, and a non-optional property without a
- default is required (the factories throw when the source omits it).
-
- The JS-value paths convert through `JavaScriptDecodable.decode` / `JavaScriptEncodable.encode`
- (`from(object:)` / `toObject(appContext:)`); the native-`Any` dictionary paths still go through the
- public dynamic-type API — `T.getDynamicType()` plus `cast(_:appContext:)` / `convertToJS(_:appContext:)`
- (`from(dictionary:)` / `toDictionary(appContext:)`), since `JavaScriptCodable` only converts JS
- values, not native `Any`. Both spell types as `public` symbols so the synthesized code compiles inside
- user modules without any internal core symbols. Every property type must therefore conform to both
- `AnyArgument` and `JavaScriptDecodable & JavaScriptEncodable`.
-
- A property whose type mentions `Any` (`Any?`, `[String: Any]?`, `[String: [Any]]`, …) can't conform to
- the JS codable protocols. On the JS-value paths it converts through the `JavaScriptValue` free-form
- methods instead: `decodeAny`/`decodeAnyArray`/`decodeAnyDictionary` and the matching `encodeAny…`
- for `Any`, `[Any]` and `[String: Any]` (optional or not), and the generic `decodeAny(_:as:in:)` /
- `encodeAny(_:in:)` for any other type. Such a property only needs `AnyArgument` for the dictionary
- paths, and a bare `Any` needs nothing, since the dictionary paths pass it through unchanged.
-
- For classes that inherit from another `@Record`-annotated class, the synthesized
- methods chain to `super` so inherited properties are handled first.
- */
+/// Member macro applied to a record type. Treats **every stored property** that is not
+/// `static`, `private`, `fileprivate`, `lazy` or computed as a property — no `@Field` wrapper
+/// needed — and synthesizes the conversion surface from the property's static type:
+///
+/// - an explicit memberwise `init` (so the static factories have a single construction point),
+/// - `decode(_:in:)` and `encode(_:in:)` — the fast paths, reading each property straight off a JS
+///   object and writing it straight into one,
+/// - `from(object:appContext:)` and `toObject(appContext:)`, which forward to `decode` and `encode`,
+/// - `from(dictionary:appContext:)` and `toDictionary(appContext:)` — converting each property from and
+///   to a `[String: Any]` dictionary.
+///
+/// The type is auto-conformed to `Record` (a core protocol whose requirements are this surface); the
+/// synthesized methods override `Record`'s reflection-based defaults, and the synthesized `decode` and
+/// `encode` replace its default `JavaScriptCodable` witnesses. Author-facing shape — no conformance to
+/// spell out:
+///
+///     @Record
+///     struct Options {
+///       var name: String          // required (non-optional, no default)
+///       var count: Int = 0        // optional (has default)
+///       var note: String?         // nullable + optional
+///     }
+///
+/// The JS key is always the property name. Requiredness is inferred from the declaration:
+/// a default value makes a property optional (the default applies when the source omits it),
+/// an optional type makes it nullable and optional, and a non-optional property without a
+/// default is required (the factories throw when the source omits it).
+///
+/// `decode(_:in:)` and `encode(_:in:)` name each property with a `JavaScriptPropNameID` that each runtime
+/// creates once. The names are held by the nested `_PropNames` class, which each runtime caches under one
+/// key. A record that is generic or nested in a generic type uses string names, since a generic type can't
+/// have static stored properties. The macro can't tell that an extension extends a generic type, so a
+/// record declared in one doesn't compile.
+///
+/// The JS-value paths convert through `JavaScriptDecodable.decode` / `JavaScriptEncodable.encode`
+/// (`decode(_:in:)` / `encode(_:in:)`); the native-`Any` dictionary paths still go through the
+/// public dynamic-type API — `T.getDynamicType()` plus `cast(_:appContext:)` / `convertToJS(_:appContext:)`
+/// (`from(dictionary:)` / `toDictionary(appContext:)`), since `JavaScriptCodable` only converts JS
+/// values, not native `Any`. Both spell types as `public` symbols so the synthesized code compiles inside
+/// user modules without any internal core symbols. Every property type must therefore conform to both
+/// `AnyArgument` and `JavaScriptDecodable & JavaScriptEncodable`.
+///
+/// A property whose type mentions `Any` (`Any?`, `[String: Any]?`, `[String: [Any]]`, …) can't conform to
+/// the JS codable protocols. On the JS-value paths it converts through the `JavaScriptValue` free-form
+/// methods instead: `decodeAny`/`decodeAnyArray`/`decodeAnyDictionary` and the matching `encodeAny…`
+/// for `Any`, `[Any]` and `[String: Any]` (optional or not), and the generic `decodeAny(_:as:in:)` /
+/// `encodeAny(_:in:)` for any other type. Such a property only needs `AnyArgument` for the dictionary
+/// paths, and a bare `Any` needs nothing, since the dictionary paths pass it through unchanged.
+///
+/// A record class must be `final` and have no inheritance clause. The synthesized factories construct
+/// `Self` through the memberwise init, which only a final class can do without a `required` init, and
+/// the macro can't tell a superclass from a protocol in the clause, so protocol conformances go in an
+/// extension.
 public struct RecordMacro: MemberMacro, ExtensionMacro {
   public static func expansion(
     of node: AttributeSyntax,
@@ -55,13 +63,21 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     conformingTo protocols: [TypeSyntax],
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
-    let isClass = declaration.is(ClassDeclSyntax.self)
-    guard declaration.is(StructDeclSyntax.self) || isClass else {
+    let typeName: String
+    if let structDecl = declaration.as(StructDeclSyntax.self) {
+      typeName = structDecl.name.text
+    } else if let classDecl = declaration.as(ClassDeclSyntax.self) {
+      typeName = classDecl.name.text
+    } else {
       throw MacroExpansionErrorMessage("@Record can only be applied to a struct or class")
     }
+    let classDiagnostics = unsupportedClassDiagnostics(of: declaration)
+    guard classDiagnostics.isEmpty else {
+      throw DiagnosticsError(diagnostics: classDiagnostics)
+    }
 
     let properties = try recordProperties(of: declaration)
-    let inheritsRecord = isClass && classHasInheritance(declaration)
+    let cachesPropNames = !properties.isEmpty && !isInGenericContext(declaration, context: context)
 
     // The user may hand-write any of the initializers the macro would otherwise synthesize. Emitting
     // a duplicate is a hard "invalid redeclaration" error, so skip anything already declared and let
@@ -92,29 +108,37 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     }
 
     if !existingInitLabels.contains([]) {
-      if let defaultInit = defaultInit(properties: properties, isClass: isClass) {
+      if let defaultInit = defaultInit(properties: properties) {
         members.append(defaultInit)
       }
     }
     if !existingInitLabels.contains(properties.map { $0.key }) {
       members.append(memberwiseInit(properties: properties))
     }
-    members.append(fromJSObjectFactory(properties: properties))
+    members.append(fromJSObjectFactory())
     members.append(fromDictionaryFactory(properties: properties))
-    members.append(toDictionaryMethod(properties: properties, inheritsRecord: inheritsRecord))
-    members.append(toObjectMethod(properties: properties, inheritsRecord: inheritsRecord))
+    members.append(toDictionaryMethod(properties: properties))
+    members.append(toObjectMethod())
+    if cachesPropNames {
+      members.append(propNamesClass(properties: properties))
+    }
+    members.append(
+      contentsOf: javaScriptCodableWitnesses(
+        properties: properties,
+        typeName: typeName,
+        cachesPropNames: cachesPropNames
+      )
+    )
     return members
   }
 
-  /**
-   Auto-conforms the type to `Record` — the protocol whose requirements are exactly the members
-   synthesized above (`init()`, the two `from(_:)` factories, and the `toDictionary`/`toObject`
-   write side), which the synthesized methods satisfy by overriding `Record`'s reflection-based
-   defaults.
-
-   The conformance is skipped when the type already declares it, and for class subclasses
-   (which inherit it from a `@Record`-annotated parent) no extension is emitted at all.
-   */
+  /// Auto-conforms the type to `Record` — the protocol whose requirements are exactly the members
+  /// synthesized above (`init()`, the two `from(_:)` factories, and the `toDictionary`/`toObject`
+  /// write side), which the synthesized methods satisfy by overriding `Record`'s reflection-based
+  /// defaults.
+  ///
+  /// The conformance is skipped when the type already declares it, and for a class the member role
+  /// rejects, which would otherwise get conformance errors for the members it didn't synthesize.
   public static func expansion(
     of node: AttributeSyntax,
     attachedTo declaration: some DeclGroupSyntax,
@@ -122,10 +146,10 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     conformingTo protocols: [TypeSyntax],
     in context: some MacroExpansionContext
   ) throws -> [ExtensionDeclSyntax] {
-    if declaration.is(ClassDeclSyntax.self) && classHasInheritance(declaration) {
+    guard declaration.is(StructDeclSyntax.self) || declaration.is(ClassDeclSyntax.self) else {
       return []
     }
-    guard declaration.is(StructDeclSyntax.self) || declaration.is(ClassDeclSyntax.self) else {
+    guard unsupportedClassDiagnostics(of: declaration).isEmpty else {
       return []
     }
     if inheritsProtocol(named: "Record", in: declaration) {
@@ -144,10 +168,8 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
 
 // MARK: - Property model
 
-/**
- A single record property discovered on the type, paired with everything the synthesized
- conversions need: its property name, its written type, and how the source may omit it.
- */
+/// A single record property discovered on the type, paired with everything the synthesized
+/// conversions need: its property name, its written type, and how the source may omit it.
 private struct RecordProperty {
   /// The property name as written, backticks included for an escaped name (`` `default` ``), since
   /// every identifier position in the generated code needs them.
@@ -182,11 +204,9 @@ private struct RecordProperty {
   }
 }
 
-/**
- Discovers the record's properties: every stored `var`/`let` binding that is not `static`,
- `private`, `fileprivate`, `lazy`, or computed. Each property must declare an explicit type
- annotation, since the synthesized conversions name the type (e.g. `Type.decode(…)`).
- */
+/// Discovers the record's properties: every stored `var`/`let` binding that is not `static`,
+/// `private`, `fileprivate`, `lazy`, or computed. Each property must declare an explicit type
+/// annotation, since the synthesized conversions name the type (e.g. `Type.decode(…)`).
 private func recordProperties(
   of declaration: some DeclGroupSyntax
 ) throws -> [RecordProperty] {
@@ -220,7 +240,8 @@ private func recordProperties(
       // (Swift's own default-literal type) — covers the common `var name = "foo"` case. Anything
       // whose type a syntactic macro can't determine (calls, collections, member access) still needs
       // an annotation.
-      let inferredType = binding.typeAnnotation?.type.trimmedDescription
+      let inferredType =
+        binding.typeAnnotation?.type.trimmedDescription
         ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
       guard let type = inferredType else {
         throw MacroExpansionErrorMessage(
@@ -239,7 +260,8 @@ private func recordProperties(
             message: RecordDiagnosticMessage(
               "@Record property '\(ident.identifier.text)' can't hold a closure: a record property is also encoded to JavaScript, and a native closure can't be encoded",
               id: "record-closure-property"
-            ))
+            )
+          )
         ])
       }
       let freeForm = try annotatedType.flatMap { annotatedType -> FreeFormConversion? in
@@ -269,23 +291,19 @@ private func recordProperties(
 
 // MARK: - Synthesized members
 
-/**
- The parameterless `init()` required by the `Record` protocol. Nothing in the synthesized code uses
- it — the factories construct through the memberwise init with defaults inlined — so it's purely a
- conformance witness. Swift only synthesizes an implicit `init()` for a struct that declares no other
- initializer, but the macro always emits a memberwise `init(…)`, which suppresses it, so for structs
- the macro must supply `init()` itself.
-
- When no property is required, the body is empty: every stored property initializes from its own
- declaration. When a property *is* required there's no value to give it, so the body traps — this `init()`
- is never reached (the `from(…)` factories don't call it), it exists only to satisfy the requirement.
-
- Not emitted when there are no properties at all — there the memberwise init already *is* `init()`. Classes
- are left alone: they inherit `init()` from their `@Record` superclass, and a base `@Record` class is
- unsupported today.
- */
-private func defaultInit(properties: [RecordProperty], isClass: Bool) -> DeclSyntax? {
-  if isClass || properties.isEmpty {
+/// The parameterless `init()` required by the `Record` protocol. Nothing in the synthesized code uses
+/// it — the factories construct through the memberwise init with defaults inlined — so it's purely a
+/// conformance witness. Swift only synthesizes an implicit `init()` for a type that declares no other
+/// initializer, but the macro always emits a memberwise `init(…)`, which suppresses it, so the macro
+/// must supply `init()` itself.
+///
+/// When no property is required, the body is empty: every stored property initializes from its own
+/// declaration. When a property *is* required there's no value to give it, so the body traps — this `init()`
+/// is never reached (the `from(…)` factories don't call it), it exists only to satisfy the requirement.
+///
+/// Not emitted when there are no properties at all — there the memberwise init already *is* `init()`.
+private func defaultInit(properties: [RecordProperty]) -> DeclSyntax? {
+  if properties.isEmpty {
     return nil
   }
   if properties.contains(where: { $0.isRequired }) {
@@ -325,36 +343,24 @@ private func memberwiseInit(properties: [RecordProperty]) -> DeclSyntax {
     """
 }
 
-/**
- `from(object:appContext:)` — reads each property off the `JavaScriptObject` into a local,
- then constructs the record through the memberwise init. Required properties throw when
- undefined; defaulted properties fall back to the property's declared default (inlined) when
- undefined; optional properties become `nil` when undefined/null. Each property is decoded with
- `JavaScriptDecodable.decode`, so the factory binds the `runtime` from the app context once and
- threads it to every read. A free-form property decodes through the `JavaScriptValue` free-form
- methods, which take the runtime too.
- */
-private func fromJSObjectFactory(properties: [RecordProperty]) -> DeclSyntax {
-  var lines: [String] = []
-  // Only bind the runtime when there's a property to decode — an empty record's factory would
-  // otherwise leave it unused.
-  if !properties.isEmpty {
-    lines.append("  let runtime = try appContext.runtime")
-  }
-  lines.append(factoryBody(properties: properties, readLines: jsObjectReadLines(properties: properties)))
-  let body = lines.joined(separator: "\n")
+/// `from(object:appContext:)`, which forwards to the record's own unowned `decode(_:in:)` witness (see
+/// `javaScriptCodableWitnesses`), where the property reads are.
+private func fromJSObjectFactory() -> DeclSyntax {
+  // The record declares only the unowned `decode`, so the call lends the value unowned. With an owning
+  // value it would reach an owning `decode` default, and `Record`'s converts through this factory.
   return """
     @JavaScriptActor
     public static func from(object: borrowing JavaScriptObject, appContext: AppContext) throws -> Self {
-    \(raw: body)
+      let runtime = try appContext.runtime
+      return try object.asValue().withUnownedValue(in: runtime) { unownedValue in
+        return try decode(unownedValue, in: runtime)
+      }
     }
     """
 }
 
-/**
- `from(dictionary:appContext:)` — same as the JS path but reads from `[String: Any]` and
- uses the `Any?` cast overload; a missing key is `dictionary[key] == nil`.
- */
+/// `from(dictionary:appContext:)` — same as the JS path but reads from `[String: Any]` and
+/// uses the `Any?` cast overload; a missing key is `dictionary[key] == nil`.
 private func fromDictionaryFactory(properties: [RecordProperty]) -> DeclSyntax {
   let body = factoryBody(properties: properties, readLines: dictionaryReadLines(properties: properties))
   return """
@@ -364,172 +370,239 @@ private func fromDictionaryFactory(properties: [RecordProperty]) -> DeclSyntax {
     """
 }
 
-/**
- Builds a factory body: per-property reads into locals, then a single call to the synthesized
- memberwise init. Each property's declared default expression is captured at parse time and inlined
- directly into the omitted-property branch (see the read-line builders), so the factory needs neither
- a throwaway `Self()` nor the record's `init()`.
- */
+/// Builds a factory body: per-property reads into locals, then a single call to the synthesized
+/// memberwise init. Each property's declared default expression is captured at parse time and inlined
+/// directly into the omitted-property branch (see the read-line builders), so the factory needs neither
+/// a throwaway `Self()` nor the record's `init()`.
 private func factoryBody(properties: [RecordProperty], readLines: [String]) -> String {
   var lines: [String] = []
   lines.append(contentsOf: readLines)
-  let initArgs = properties.map { "\($0.name): \($0.name)" }.joined(separator: ", ")
+  let initArgs = properties.enumerated().map { "\($1.name): \(fieldLocal($0))" }.joined(separator: ", ")
   lines.append("  return Self(\(initArgs))")
   return lines.joined(separator: "\n")
 }
 
-/// Per-property read statements for the JS-object factory, each producing a `let <name>` by decoding
-/// the JS value with `JavaScriptDecodable.decode` (recovering the app context from `runtime` itself).
-/// A free-form property decodes through the `JavaScriptValue` free-form methods instead; for an optional
-/// free-form shape, `undefined`/`null` map to `nil` around the call, just like `Optional.decode`.
-private func jsObjectReadLines(properties: [RecordProperty]) -> [String] {
+/// The local that holds the value of the property at `index` in a factory. It's numbered rather than
+/// named after the property, so no property can collide with it or with the factory's other parameters
+/// and locals (`object`, `runtime`, `dictionary`, `appContext`).
+private func fieldLocal(_ index: Int) -> String {
+  return "field\(index)"
+}
+
+/// Per-property read statements, each producing a `let field<index>` from the property of the JS object
+/// named `object`. The property is lent to a closure as a `JavaScriptUnownedValue` and decoded there the
+/// same way as a `@JS` argument (see `decodeCall`), so the read doesn't allocate a `JavaScriptValue`.
+/// Only the generic free-form decode copies the value into one.
+private func jsObjectReadLines(properties: [RecordProperty], cachesPropNames: Bool) -> [String] {
   var lines: [String] = []
-  for property in properties {
+  for (index, property) in properties.enumerated() {
     let valueVar = derivedIdentifier(from: property.name, suffix: "JSValue")
-    let exprType = expressionType(property.type)
-    let decode: String
-    switch property.freeForm {
-    case .shape(let decodeMethod, _, let isOptional, _):
-      let call = "try JavaScriptValue.\(decodeMethod)(\(valueVar), in: runtime)"
-      decode = isOptional ? "\(valueVar).isUndefined() || \(valueVar).isNull() ? nil : \(call)" : call
-    case .generic:
-      decode = "try JavaScriptValue.decodeAny(\(valueVar), as: \(exprType).self, in: runtime)"
-    case nil:
-      decode = "try \(exprType).decode(\(valueVar), in: runtime)"
-    }
-    lines.append("  let \(valueVar) = object.getProperty(\"\(property.key)\")")
+    let decode = "try \(decodeCall(property.type, freeForm: property.freeForm, from: valueVar))"
+    let propName = propNameArgument(for: property, at: index, cached: cachesPropNames)
+    lines.append("  let \(fieldLocal(index)) = try object.withUnownedProperty(\(propName)) { \(valueVar) in")
     if property.isRequired {
-      lines.append("  guard !\(valueVar).isUndefined() else {")
-      lines.append("    throw RecordPropertyRequiredException(\"\(property.key)\")")
-      lines.append("  }")
-      lines.append("  let \(property.name) = \(decode)")
+      lines.append("    guard !\(valueVar).isUndefined() else {")
+      lines.append("      throw RecordPropertyRequiredException(\"\(property.key)\")")
+      lines.append("    }")
+      lines.append("    return \(decode)")
     } else if property.isOptional {
-      // `Optional.decode` (and the free-form reads above) already map `undefined`/`null` to `nil`, so
-      // the read is a plain decode.
-      lines.append("  let \(property.name) = \(decode)")
+      // `Optional.decode` (and the free-form decodes of optional shapes) already map `undefined` and
+      // `null` to `nil`, so the read is a plain decode.
+      lines.append("    return \(decode)")
     } else {
-      lines.append("  let \(property.name) = \(valueVar).isUndefined() ? \(property.defaultValue!) : \(decode)")
+      lines.append("    return \(valueVar).isUndefined() ? \(property.defaultValue!) : \(decode)")
     }
+    lines.append("  }")
   }
   return lines
 }
 
-/// Per-property read statements for the dictionary factory, each producing a `let <name>`. A bare `Any`
-/// property has no dynamic type to cast through, and the dictionary value already is an `Any`, so it's
-/// read unchanged.
+/// Per-property read statements for the dictionary factory, each producing a `let field<index>` from the
+/// raw dictionary value in `entry<index>`. A bare `Any` property has no dynamic type to cast through, and
+/// the dictionary value already is an `Any`, so it's read unchanged.
 private func dictionaryReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
-  for property in properties {
-    let valueVar = derivedIdentifier(from: property.name, suffix: "Value")
+  for (index, property) in properties.enumerated() {
+    let field = fieldLocal(index)
+    let entry = "entry\(index)"
     let exprType = expressionType(property.type)
     let isBareAny = property.freeForm?.isBareAny == true
-    let cast = isBareAny
-      ? valueVar
-      : "try \(exprType).getDynamicType().cast(\(valueVar), appContext: appContext) as! \(exprType)"
-    lines.append("  let \(valueVar) = dictionary[\"\(property.key)\"]")
+    let cast =
+      isBareAny
+      ? entry
+      : "try \(exprType).getDynamicType().cast(\(entry), appContext: appContext) as! \(exprType)"
+    lines.append("  let \(entry) = dictionary[\"\(property.key)\"]")
     if property.isRequired {
-      lines.append("  guard let \(valueVar) else {")
+      lines.append("  guard let \(entry) else {")
       lines.append("    throw RecordPropertyRequiredException(\"\(property.key)\")")
       lines.append("  }")
-      lines.append("  let \(property.name) = \(cast)")
+      lines.append("  let \(field) = \(cast)")
     } else if property.isOptional {
-      lines.append("  let \(property.name): \(property.type) = (\(valueVar) == nil || \(valueVar)! is NSNull) ? nil : \(cast)")
+      lines.append("  let \(field): \(property.type) = (\(entry) == nil || \(entry)! is NSNull) ? nil : \(cast)")
     } else {
-      lines.append("  let \(property.name) = \(valueVar) == nil ? \(property.defaultValue!) : \(isBareAny ? valueVar + "!" : cast)")
+      lines.append("  let \(field) = \(entry) == nil ? \(property.defaultValue!) : \(isBareAny ? entry + "!" : cast)")
     }
   }
   return lines
 }
 
-/**
- `toDictionary(appContext:)` — converts each property back to a JS-compatible value via the
- dynamic type and assembles a `[String: Any]`. Inherited properties are merged in first.
- */
-private func toDictionaryMethod(properties: [RecordProperty], inheritsRecord: Bool) -> DeclSyntax {
-  let overrideKeyword = inheritsRecord ? "override " : ""
-  var lines: [String] = []
-  if inheritsRecord {
-    lines.append("  var dictionary = super.toDictionary(appContext: appContext)")
-  } else {
-    lines.append("  var dictionary: [String: Any] = [:]")
-  }
+/// `toDictionary(appContext:)` — converts each property back to a JS-compatible value via the
+/// dynamic type and assembles a `[String: Any]`.
+private func toDictionaryMethod(properties: [RecordProperty]) -> DeclSyntax {
+  var lines = ["  var dictionary: [String: Any] = [:]"]
   for property in properties {
     lines.append("  dictionary[\"\(property.key)\"] = self.\(property.name)")
   }
   lines.append("  return dictionary")
-  let body = lines.joined(separator: "\n")
-
-  if inheritsRecord {
-    return """
-      public \(raw: overrideKeyword)func toDictionary(appContext: AppContext? = nil) -> [String: Any] {
-      \(raw: body)
-      }
-      """
-  }
   return """
     public func toDictionary(appContext: AppContext? = nil) -> [String: Any] {
-    \(raw: body)
+    \(raw: lines.joined(separator: "\n"))
     }
     """
 }
 
-/**
- `toObject(appContext:)` — builds a `JavaScriptObject` directly, encoding each property with
- `JavaScriptEncodable.encode` (or, for a free-form property, the matching `JavaScriptValue` free-form
- method). The fast write path mirroring `from(object:)`. The `runtime` is bound
- from the app context once and threaded to every write. Subclasses chain to `super` so inherited
- properties are written first.
- */
-private func toObjectMethod(properties: [RecordProperty], inheritsRecord: Bool) -> DeclSyntax {
-  let overrideKeyword = inheritsRecord ? "override " : ""
-  var lines: [String] = []
-  // The base case needs the runtime to create the object; the inheriting case only needs it when
-  // there's a property to encode (it chains to `super` for the object itself). Binding it when unused
-  // would warn.
-  if !inheritsRecord || !properties.isEmpty {
-    lines.append("  let runtime = try appContext.runtime")
-  }
-  if inheritsRecord {
-    lines.append("  let object = try super.toObject(appContext: appContext)")
-  } else {
-    lines.append("  let object = runtime.createObject()")
-  }
-  for property in properties {
-    let exprType = expressionType(property.type)
+/// `toObject(appContext:)`, which forwards to the record's own `encode(_:in:)` witness (see
+/// `javaScriptCodableWitnesses`), where the property writes are.
+private func toObjectMethod() -> DeclSyntax {
+  return """
+    @JavaScriptActor
+    public func toObject(appContext: AppContext) throws -> JavaScriptObject {
+      return try Self.encode(self, in: appContext.runtime).asObject()
+    }
+    """
+}
+
+/// The record's own `JavaScriptDecodable` and `JavaScriptEncodable` witnesses, which convert in the
+/// runtime they're given. Without them the record would convert through `Record`'s default witnesses,
+/// which recover the app context from the runtime and convert in the app context's runtime.
+///
+/// `decode` reads each property off the JS object into a local, then constructs the record through the
+/// memberwise init. Required properties throw when undefined; defaulted properties fall back to the
+/// property's declared default (inlined) when undefined; optional properties become `nil` when
+/// undefined/null. It's the unowned overload: an owning value decodes through `JavaScriptDecodable`'s
+/// default, which forwards to it. `encode` builds the JS object, writing each property. Its parameter
+/// names the type, because a class can't take `Self` as a parameter type.
+private func javaScriptCodableWitnesses(
+  properties: [RecordProperty],
+  typeName: String,
+  cachesPropNames: Bool
+) -> [DeclSyntax] {
+  // An empty record still decodes only from an object, but has no property to read off it.
+  let objectLine =
+    properties.isEmpty
+    ? "  _ = try value.asObject(in: runtime)"
+    : "  let object = try value.asObject(in: runtime)"
+  let lookupLines = cachesPropNames ? propNamesLookupLines() : []
+  let readLines = lookupLines + jsObjectReadLines(properties: properties, cachesPropNames: cachesPropNames)
+  let decodeBody = objectLine + "\n" + factoryBody(properties: properties, readLines: readLines)
+  let encodeLines =
+    ["  let object = runtime.createObject()"]
+    + lookupLines
+    + objectWriteLines(properties: properties, of: "value", cachesPropNames: cachesPropNames)
+    + ["  return object.asValue()"]
+  return [
+    """
+    @JavaScriptActor
+    public static func decode(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime) throws -> Self {
+    \(raw: decodeBody)
+    }
+    """,
+    """
+    @JavaScriptActor
+    public static func encode(_ value: \(raw: typeName), in runtime: borrowing JavaScriptRuntime) throws -> JavaScriptValue {
+    \(raw: encodeLines.joined(separator: "\n"))
+    }
+    """,
+  ]
+}
+
+/// The statements that write each property of `record` (`self` or the `encode` parameter) into the
+/// `object` local, encoding it with `JavaScriptEncodable.encode` or, for a free-form property, the
+/// matching `JavaScriptValue` free-form method.
+private func objectWriteLines(properties: [RecordProperty], of record: String, cachesPropNames: Bool) -> [String] {
+  return properties.enumerated().map { index, property in
+    let value = "\(record).\(property.name)"
     let encode: String
     switch property.freeForm {
     case .shape(_, let encodeMethod, let isOptional, _):
-      encode = isOptional
-        ? "self.\(property.name) == nil ? .null() : try JavaScriptValue.\(encodeMethod)(self.\(property.name)!, in: runtime)"
-        : "try JavaScriptValue.\(encodeMethod)(self.\(property.name), in: runtime)"
+      encode =
+        isOptional
+        ? "\(value) == nil ? .null() : try JavaScriptValue.\(encodeMethod)(\(value)!, in: runtime)"
+        : "try JavaScriptValue.\(encodeMethod)(\(value), in: runtime)"
     case .generic:
       // The explicit `as Any` keeps an optional property from warning about its implicit coercion.
-      encode = "try JavaScriptValue.encodeAny(self.\(property.name) as Any, in: runtime)"
+      encode = "try JavaScriptValue.encodeAny(\(value) as Any, in: runtime)"
     case nil:
-      encode = "try \(exprType).encode(self.\(property.name), in: runtime)"
+      encode = "try \(expressionType(property.type)).encode(\(value), in: runtime)"
     }
-    lines.append("  object.setProperty(\"\(property.key)\", value: \(encode))")
+    let propName = propNameArgument(for: property, at: index, cached: cachesPropNames)
+    return "  object.setProperty(\(propName), value: \(encode))"
   }
-  lines.append("  return object")
-  let body = lines.joined(separator: "\n")
+}
 
+/// The name of the nested class that holds the property names (see `propNamesClass`).
+private let propNamesTypeName = "_PropNames"
+
+/// A nested class that holds the `JavaScriptPropNameID` of each property, `_name<index>` for the property
+/// at `index`, and the runtime cache key for its instances. Each runtime creates one instance, so the
+/// whole record takes one cache key.
+private func propNamesClass(properties: [RecordProperty]) -> DeclSyntax {
+  let storedProperties = properties.indices.map { index in
+    "  let \(propNameMember(index)): JavaScriptPropNameID"
+  }
+  let assignments = properties.enumerated().map { index, property in
+    "    self.\(propNameMember(index)) = JavaScriptPropNameID(runtime, string: \"\(property.key)\")"
+  }
   return """
-    @JavaScriptActor
-    public \(raw: overrideKeyword)func toObject(appContext: AppContext) throws -> JavaScriptObject {
-    \(raw: body)
+    private final class \(raw: propNamesTypeName) {
+      static let _key = JavaScriptRuntime.Cache.Key<\(raw: propNamesTypeName)>()
+
+    \(raw: storedProperties.joined(separator: "\n"))
+
+      init(_ runtime: borrowing JavaScriptRuntime) {
+    \(raw: assignments.joined(separator: "\n"))
+      }
     }
     """
 }
 
+private func propNameMember(_ index: Int) -> String {
+  return "_name\(index)"
+}
+
+/// The statements that get the record's property names from the runtime cache into `_propNames`, at the
+/// start of `decode` and `encode`.
+private func propNamesLookupLines() -> [String] {
+  return [
+    "  let _propNames = runtime.cached(\(propNamesTypeName)._key) {",
+    "    return \(propNamesTypeName)(runtime)",
+    "  }",
+  ]
+}
+
+/// The first argument of the `withUnownedProperty` and `setProperty` calls for the property at `index`:
+/// its name from `_propNames`, or the key as a string literal when the record can't hold the cache key.
+private func propNameArgument(for property: RecordProperty, at index: Int, cached: Bool) -> String {
+  return cached ? "_propNames.\(propNameMember(index))" : "\"\(property.key)\""
+}
+
+/// True when the record or a type that encloses it is generic. Swift doesn't support static stored
+/// properties in generic types, so the record can't hold the cache key.
+private func isInGenericContext(_ declaration: some DeclGroupSyntax, context: some MacroExpansionContext) -> Bool {
+  // The lexical context of a member macro usually starts with the type it's attached to, but the
+  // declaration is checked on its own too.
+  return ([Syntax(declaration)] + context.lexicalContext).contains { node in
+    return node.asProtocol(WithGenericParametersSyntax.self)?.genericParameterClause != nil
+  }
+}
+
 // MARK: - Helpers
 
-/**
- The parameter-label list of every initializer the type already declares, used to avoid emitting a
- duplicate of one the author hand-wrote. Each entry is the ordered external argument labels of one
- `init` — e.g. `init(name: String, count: Int)` → `["name", "count"]`, and `init()` → `[]`. A
- parameter written with `_` or with no external label contributes its internal name's absence as an
- empty-string label, which simply won't match the macro's always-labeled signatures (a safe miss).
- */
+/// The parameter-label list of every initializer the type already declares, used to avoid emitting a
+/// duplicate of one the author hand-wrote. Each entry is the ordered external argument labels of one
+/// `init` — e.g. `init(name: String, count: Int)` → `["name", "count"]`, and `init()` → `[]`. A
+/// parameter written with `_` or with no external label contributes its internal name's absence as an
+/// empty-string label, which simply won't match the macro's always-labeled signatures (a safe miss).
 private func initializerParameterLabels(of declaration: some DeclGroupSyntax) -> [[String]] {
   var signatures: [[String]] = []
   for member in declaration.memberBlock.members {
@@ -546,18 +619,59 @@ private func initializerParameterLabels(of declaration: some DeclGroupSyntax) ->
   return signatures
 }
 
-/**
- True if the class declaration has any inheritance clause. Used as a heuristic for
- whether the superclass also conforms to `Record` and provides the synthesized methods;
- the macro emits `override` in this case.
- */
-private func classHasInheritance(_ declaration: some DeclGroupSyntax) -> Bool {
-  guard let classDecl = declaration.as(ClassDeclSyntax.self),
-    let inherited = classDecl.inheritanceClause?.inheritedTypes,
-    !inherited.isEmpty else {
-    return false
+/// The errors for a class the macro can't synthesize a record for: one that isn't `final`, or one
+/// with an inheritance clause. Empty for a struct and for a supported class.
+private func unsupportedClassDiagnostics(of declaration: some DeclGroupSyntax) -> [Diagnostic] {
+  guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
+    return []
+  }
+  let name = classDecl.name.text
+  var diagnostics: [Diagnostic] = []
+  if !classDecl.modifiers.contains(where: { $0.name.tokenKind == .keyword(.final) }) {
+    // An `open` class can't also be `final`, so changing its access level is left to the author.
+    let isOpen = classDecl.modifiers.contains(where: { $0.name.tokenKind == .keyword(.open) })
+    diagnostics.append(
+      Diagnostic(
+        node: classDecl.classKeyword,
+        message: RecordDiagnosticMessage(
+          "@Record class '\(name)' must be final, because the macro doesn't support subclasses of a record",
+          id: "record-class-not-final"
+        ),
+        fixIts: isOpen ? [] : [markFinalFixIt(for: classDecl)]
+      )
+    )
+  }
+  if let inheritanceClause = classDecl.inheritanceClause {
+    diagnostics.append(
+      Diagnostic(
+        node: inheritanceClause,
+        message: RecordDiagnosticMessage(
+          "@Record class '\(name)' can't have an inheritance clause: a record class can't have a superclass, and the macro can't tell a superclass from a protocol. Declare protocol conformances in an extension",
+          id: "record-class-inheritance"
+        )
+      )
+    )
   }
-  return true
+  return diagnostics
+}
+
+/// The fix-it for a record class that isn't `final`: add the modifier right before `class`.
+private func markFinalFixIt(for classDecl: ClassDeclSyntax) -> FixIt {
+  // The new modifier takes over the leading trivia of `class` (the line break after the attribute
+  // when no other modifier comes first), so it lands where `class` started.
+  let classKeyword = classDecl.classKeyword
+  var modifiers = classDecl.modifiers
+  modifiers.append(
+    DeclModifierSyntax(name: .keyword(.final, leadingTrivia: classKeyword.leadingTrivia, trailingTrivia: .space))
+  )
+  let newDecl =
+    classDecl
+    .with(\.modifiers, modifiers)
+    .with(\.classKeyword, classKeyword.with(\.leadingTrivia, []))
+  return FixIt(
+    message: RecordFixItMessage("Mark the class 'final'", id: "record-class-insert-final"),
+    changes: [.replace(oldNode: Syntax(classDecl), newNode: Syntax(newDecl))]
+  )
 }
 
 private struct RecordDiagnosticMessage: DiagnosticMessage {
@@ -570,3 +684,13 @@ private struct RecordDiagnosticMessage: DiagnosticMessage {
     self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
   }
 }
+
+private struct RecordFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}