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.