RFC: Class hierarchies in WebAPI, and developing WebAPI, React and the compiler together #9058

Activity

1. Freddy03h commented on Oct 26, 2026

   

   Freddy03h

   on Oct 26, 2026

   More actions

   This comment was drafted by Claude from the rescript-react-native bindings and the React Native sources.

   Feedback from the React Native side. RN ships a small, read-only DOM (Node, Element, Text, Document). That makes it a convenient small test case for this RFC, and it is the example from #8280, so here it is rewritten with A + B.

   One prerequisite: instanceof dispatch needs the classes to exist as globals, otherwise it throws a ReferenceError (as the RFC notes for server runtimes). React Native does provide them: in RN 0.85, Node, Element, HTMLElement, CharacterData, Text and Document are installed as globals at app startup. So the approach works on RN.

   Today (simplified)

   type readOnlyNode<'node, 'document, 'element> = {
     childNodes: nodeList<'node>,
     nodeType: int,
     ownerDocument: null<'document>,
     parentElement: null<'element>,
     parentNode: null<'node>,
   }
   
   type rec node = {...readOnlyNode<node, document, anyElement>}
   and element<'nativeElement> = {
     ...readOnlyNode<node, document, anyElement>,
     children: htmlCollection<anyElement>,
     tagName: string,
   }
   and text = {...readOnlyNode<node, document, anyElement>, data: string}
   and document = {...readOnlyNode<node, document, anyElement>, documentElement: anyElement}
   and anyElement = element<unknownNativeElement>
   
   // + `asNode` upcasts via %identity in a Node.Impl functor
   // + a hand-written classifier on nodeType with Obj.magic
   module NodeType = {
     type t = Element(anyElement) | Text(text) | Document(document) | Unknown
     let classify = (node: node) =>
       switch node {
       | {nodeType: 1} => Element(node->Obj.magic)
       | {nodeType: 3} => Text(node->Obj.magic)
       | {nodeType: 9} => Document(node->Obj.magic)
       | _ => Unknown
       }
   }

   With this RFC

   // fields template, outside the recursive group
   type nodeFields<'node, 'document, 'element> = {
     childNodes: nodeList<'node>,
     nodeType: int,
     ownerDocument: null<'document>,
     parentElement: null<'element>,
     parentNode: null<'node>,
   }
   
   // the type used everywhere: a union dispatched with instanceof
   @unboxed
   type rec node =
     | Element(anyElement)
     | Text(text)
     | Document(document)
     | Other(baseNode)
   
   @instanceOf("Node")
   and baseNode = private {...nodeFields<node, document, anyElement>}
   
   @instanceOf("Element") @extends(: baseNode)
   and element<'nativeElement> = private {
     ...nodeFields<node, document, anyElement>,
     children: htmlCollection<anyElement>,
     tagName: string,
   }
   
   @instanceOf("CharacterData") @extends(: baseNode)
   and characterData = private {...nodeFields<node, document, anyElement>, data: string}
   
   @instanceOf("Text") @extends(: characterData)
   and text = private {...nodeFields<node, document, anyElement>, data: string}
   
   @instanceOf("Document") @extends(: baseNode)
   and document = private {
     ...nodeFields<node, document, anyElement>,
     documentElement: anyElement,
   }
   
   and anyElement = element<unknownNativeElement>
   
   // no classify: fields are already typed with the union
   let describeParent = (t: text) =>
     switch t.parentNode {
     | Null.Value(Element(e)) => `<${e.tagName}>`
     | Null.Value(Document(_)) => "#document"
     | Null.Value(Text(_) | Other(_)) | Null.Null => "none"
     }
   
   let asNode = (e: anyElement) => (e :> node) // see question 2

   function describeParent(t) {
     let match = t.parentNode;
     if (match === null) { return "none"; }
     if (match instanceof Element) { ... }
     else if (match instanceof Text) { ... }
     else if (match instanceof Document) { ... }
     else { return "none"; }
   }

   This covers what #8280 asked for better than the original proposal. These values are never constructed in ReScript, so with private records the identity concern raised there goes away, and the hand-written classifier is gone. If this lands, #8280 can be closed.

   Remarks / questions

   1. Spreads in recursive groups. The RFC says the generator has to write inherited fields out. A pattern that already works: a parameterized fields record defined outside the group, spread inside it (...nodeFields<node, document, anyElement>). I assume @extends(: baseNode) accepts this, since the field check runs after spread expansion. It would be worth a test case.
   2. Case type → union. With node being the union, the Node.Impl functions (contains, compareDocumentPosition, …) take a node, so an element has to go up into it. Could (e :> node) be allowed when the unboxed variant has a case whose payload is e's type (or one of its superclasses)? It's sound, since the runtime value is unchanged, and it would remove the last %identity.
   3. Unboxed variant inside the recursive group. Here the union lives in the same type rec group as the class records it dispatches on, so that fields can point to it directly. Is that supported, i.e. are the @instanceOf / @extends of the group's records known when the variant's dispatch order is computed? This is what removes the need for a separate classify.
   4. Type parameters. element<'nativeElement> has a phantom parameter (the native component type of a ref). I assume @instanceOf on a parameterized private record works like TypedArray.t<'a>. Can a variant case use a concrete instantiation (Element(anyElement), i.e. element<unknownNativeElement>)?
   5. C. It doesn't matter for RN: its DOM is read-only (ReadOnlyNode, ReadOnlyElement, …), so private records fit as-is. No objection to C1.
   6. Spelling. @instanceOf("Element") @extends(: baseNode) reads well to me.

   React bindings on top of WebAPI

   I'm fine with React building on WebAPI only if the bindings are split into React and React DOM, with only the React DOM part depending on WebAPI. The core of React (components, hooks, JSX, refs, context) is platform-agnostic, and rescript-react-native depends on it. RN has no window, history or location, and it has its own Element. If core React pulled in WebAPI, every RN project would get the web DOM types, which would conflict with RN's own DOM. The DOM-specific parts (ReactDOM, DOM props, synthetic DOM events, window / history / location, …) would live in a separate React DOM package, the only one that depends on WebAPI.
2. cristianoc commented on Oct 27, 2026

   

   cristianoc

   on Oct 27, 2026

   Collaborator

   More actions

   Some findings from trying this out against master (1a49d91), which may change the shape of the proposal.

   Classification already works with ordinary constructors

   An untagged constructor does not fix which case a value matches (UntaggedVariants.md, rule 8). Wrapping a value in its catch-all case and matching on it selects the most specific class:

   @instanceOf("Animal") type animal
   @instanceOf("Dog") type dog = private animal
   @unboxed type pet = Dog(dog) | Animal(animal)
   
   let classify = (a: animal) => Animal(a)   // compiles to `return a`
   let isDog = (a: animal) =>
     switch classify(a) {
     | Dog(_) => true                        // compiles to `a instanceof Dog`
     | Animal(_) => false
     }

   isDog(new Dog()) is true and isDog(new Animal()) is false. So WebAPI's classify / decode can become ordinary (generated) functions over an untagged variant with a covering superclass case, with no %identity and no new feature. Allowing (a :> pet) would only spare writing the constructor.

   Two prerequisites for @instanceOf on private records (A)

   1. Coercion into a class record must be refused. Today a plain record coerces into a private one with the same fields:

      type plain = {size: float}
      type blob = private {size: float}
      let fake = (p: plain) => (p :> blob)   // compiles

      If blob carried @instanceOf("Blob"), a literal could pass as a Blob this way, so being private would not be enough.
   2. Record coercion ignores mutable (Record coercion can turn an immutable field into a mutable one #9063): {x: float} coerces to {mutable x: float}. WebAPI's writable fields would inherit this hole through :>.

   On B and C

   • An explicit @extends seems right: field composition and class inheritance are different facts (mixin fields imply no ancestry), and recursive groups need the explicit form anyway. Inference from spread can stay an optional shorthand.
   • C1 changes what private means for every record, independently of classes, so it may be better decided on its own. If A goes ahead, an opt-in for writable fields (C2) keeps write permission separate from runtime recognition; exempting only @instanceOf records would tie the two together.

   An alternative that needs no compiler change

   Model interfaces as abstract class types rather than records: @instanceOf("Blob") type blob, @instanceOf("File") type file = private blob, properties through generated @get/@set externals, and generated classifiers as above. Ancestry, recognition and property access then each have one existing mechanism, and :> upcasts already work ((d :> animal) compiles to return d). The cost is record syntax: Blob.size(b) instead of b.size, and the generator emits the inherited accessors instead of using record spread.

   So the question for the WebAPI team is mainly this trade: keep record syntax with A + B + an answer to C (plus the two prerequisites), or move to abstract types with accessors and need nothing new from the compiler.

   Unchanged by any option: interfaces without a global constructor (mixins) cannot be cases, instanceof fails across realms, and @instanceOf declarations are trusted rather than checked.
3. cknitt commented on Oct 29, 2026

   

   cknitt

   on Oct 29, 2026

   Last edited by cknitt

   MemberAuthor

   More actions

   Thanks both, this is very helpful.

   Records or abstract types. The abstract-types alternative is appealing because it needs no compiler work. As far as I know, though, the WebAPI team chose records deliberately, for the developer experience. So the RFC continues with records: A + B, the prerequisites, and a separate answer for C. If the WebAPI team sees it differently, the abstract-type route is a good fallback that works today.

   @cristianoc:

   • Classification works today. Good point: a value wrapped in its superclass case is re-classified by matching, so hand-written classifiers like classify/decode aren't needed at all. One matches on the value wrapped in its catch-all case, or the bindings type fields and results as the union directly, as in Freddy's sketch. The RFC implied A/B were needed for this, and that should be corrected.
   • Coercion into a private record. Agreed, this has to be refused for A to be sound. I'd refuse it for every private record, not only class records: private means the record can't be constructed outside its module, and :> from a plain record is a way to construct it. If that turns out to break real code, it can be narrowed to records with @instanceOf.
   • Mutability in record coercion: fixed in the meantime by Check field mutability in record coercion #9086 (Record coercion can turn an immutable field into a mutable one #9063).
   • B: agreed. The explicit @extends comes first; inference from a spread can be an optional shorthand later.
   • C: agreed that it's a decision about private records in general, not about classes, so it's best decided on its own. Both options have a case. C1 is simpler: mutable fields of private records are just writable, with no new attribute. C2 keeps write permission separate from runtime recognition, at the cost of an opt-in. I'd leave the choice open for now.

   @Freddy03h:

   1. A parameterized fields record spread inside the group: yes. @extends checks the fields after spreads are expanded, so this pattern works. It should become a test case.
   2. (e :> node): the constructor already does it, as @cristianoc showed: Element(e) compiles to e, and matching re-classifies. A coercion would be sugar on top. It would fit the existing rule that lets string coerce into an @unboxed variant with a string case, so it's a reasonable follow-up, but not needed for this RFC.
   3. The union in the same recursive group: yes. I checked with abstract class types: a variant in the same type rec group dispatches subclass-first (instanceof Text, instanceof Element, then the Node catch-all). Records with A take the same path.
   4. Type parameters: yes. @instanceOf works on parameterized types, and the dispatch ignores the parameters, so Element(anyElement) is fine.
   5. React vs React DOM: agreed. Core React has to stay platform-agnostic for rescript-react-native, so only a React DOM part should depend on WebAPI. How to split the bindings is up to rescript-react.

   I've folded this into the RFC text; objections welcome.