refactor: clean up public owners and singleton APIs by jderochervlk · Pull Request #270 · rescript-lang/experimental-rescript-webapi

jderochervlk · 2026-05-20T14:22:58Z

Summary

This PR continues the WebAPI package split by moving object ownership toward public leaf modules and making global/singleton APIs callable directly from their leaf modules.

// before: get the host object and pass it to the module function
let before = Dom.crypto->Crypto.randomUUID

// after: call the leaf API directly
let after = Crypto.randomUUID()

The package now models focused feature relationships in rescript.json, removes the residual DOMExtended source bucket, and keeps public modules registered through source public lists. Consumers can depend on narrower feature slices instead of compiling the whole DOM/WebAPI surface.

{
  "dependencies": [
    {
      "name": "@rescript/webapi",
      "features": ["WebAPI.Crypto", "WebAPI.Location"]
    }
  ]
}

Public Owner Cleanup

Moved many public object APIs toward local type t ownership and pipeable @send functions.
Added scripts/audit-method-style.mjs and tests/unmonorepo/method-style.test.mjs to track remaining type-bucket method receivers.
Removed DOMExtended in favor of explicit leaf source directories and feature dependencies.
Kept follow-up work in one active plan: docs/superpowers/plans/2026-06-09-public-owner-follow-ups.md.

Event And DOM Shape

Keeps DOM, Event, and EventTarget interoperable through shared hidden base owners.
Keeps DOM.event opaque and exposes event behavior through Event getters.
Keeps the DOM feature thin for React-oriented consumers while moving broader API behavior to leaf features.

Testing

Passed locally during this branch:

npm run build
npm test
npm run format:check
node_modules/.bin/rescript build --features WebAPI.DOM --prod
node_modules/.bin/rescript build --features WebAPI.Event --prod
node_modules/.bin/rescript build --features WebAPI.Fetch --prod
node_modules/.bin/rescript build --features WebAPI.File --prod
node_modules/.bin/rescript build --features WebAPI.CredentialManagement --prod
node_modules/.bin/rescript build --features WebAPI.Notification --prod
node_modules/.bin/rescript build --features WebAPI.Push --prod
node_modules/.bin/rescript build --features WebAPI.Locks --prod

jderochervlk · 2026-05-30T15:35:11Z

@codex

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 49420e4362

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

jderochervlk · 2026-05-30T16:14:05Z

@codex

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c526dd58cc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

tsnobip

the rest looks ok to me but I have two main comments on the general structure

tsnobip · 2026-05-31T17:55:50Z

+type element = Base__Element.element
+type document = Base__Document.document


why don't we do:

Suggested change

type element = Base__Element.element

type document = Base__Document.document

module Element = Base__Element

module Document = Base__Document

as we agreed on?

Yup, that's much better.

tsnobip

ok I re-reviewed it, and really I don't understand this PR, we had quite a nice structure where DOM was in base package, this way we could make rescript-react and other dependencies depend on DOM.element for example, now it would depend on Base.Element.element and these types are not really usable anymore given they use abstract types that are duplicated.

tsnobip · 2026-06-02T09:58:43Z

@@ -13,37 +14,37 @@ type structuredSerializeOptions = ChannelMessagingTypes.structuredSerializeOptio
 type htmlElement = DOM.htmlElement
 type mediaError = DOM.mediaError
 type timeRanges = DOM.timeRanges
-type textTrackList = DOM.textTrackList
+type textTrackList = TextTrackList.t = private {...TextTrackList.t}
 type htmlFormElement = DOM.htmlFormElement
 type htmlCollection<'a> = DOM.htmlCollection<'a>
-type element = DOM.element
+type element = Base.Element.element
 type validityState = DOM.validityState
-type document = DOM.document
+type document = Base.Document.document
 type cssStyleSheet = DOM.cssStyleSheet
 type nodeList<'a> = DOM.nodeList<'a>
 type htmlLabelElement = DOM.htmlLabelElement
 type documentFragment = DOM.documentFragment
 type node = DOM.node
 type cssStyleDeclaration = DOM.cssStyleDeclaration
-type domRectReadOnly = DOM.domRectReadOnly
+type domRectReadOnly = DOMRectReadOnly.t = private {...DOMRectReadOnly.t}
 type shadowRoot = DOM.shadowRoot
 type styleSheet = DOM.styleSheet
 type mediaQueryList = DOM.mediaQueryList
-type domRect = DOM.domRect
+type domRect = DOMRect.t = private {...DOMRect.t}
 type range = DOM.range
 type documentType = DOM.documentType
-type cssStyleValue = DOM.cssStyleValue
+type cssStyleValue = CSSStyleValue.t = private {...CSSStyleValue.t}
 type treeWalker = DOM.treeWalker
 type selection = DOM.selection
 type abstractRange = DOM.abstractRange
 type htmlOptionsCollection = DOM.htmlOptionsCollection
 type styleSheetList = DOM.styleSheetList
 type elementInternals = DOM.elementInternals
 type nodeFilter = DOM.nodeFilter
-type fileList = DOM.fileList
+type fileList = FileList.t = private {...FileList.t}
 type cssRule = DOM.cssRule
 type attr = DOM.attr
-type domRectList = DOM.domRectList
+type domRectList = DOMRectList.t = private {...DOMRectList.t}
 type htmlFormControlsCollection = DOM.htmlFormControlsCollection
 type domImplementation = DOM.domImplementation
 type nodeIterator = DOM.nodeIterator
@@ -74,7 +75,6 @@ type htmlTableRowElement = DOM.htmlTableRowElement
 type htmlImageElement = DOM.htmlImageElement
 type htmlAreaElement = DOM.htmlAreaElement
 type videoPlaybackQuality = DOM.videoPlaybackQuality
-type idleDeadline = DOM.idleDeadline
 type cssRuleList = DOM.cssRuleList
 type mediaKeySystemConfiguration = BaseEncryptedMediaExtensions.mediaKeySystemConfiguration


we need to be consistent here in terms of type spreading

tsnobip · 2026-06-02T10:23:26Z

+type node
+type htmlElement
+type nodeList<'tNode>
+type domImplementation
+type documentType


I don't get this, why do we redefine those as abstract types?

We shouldn't, I am cleaning this up.

tsnobip · 2026-06-02T10:23:37Z

+type document
+type node
+type htmlElement
+type nodeList<'tNode>
+type domTokenList
+type namedNodeMap
+type shadowRoot
+type htmlCollection<'t>
+type htmlSlotElement


same question

tsnobip · 2026-06-02T10:26:48Z

+[See Element on MDN](https://developer.mozilla.org/docs/Web/API/Element)
+TODO: mark as private once mutating fields of private records is allowed
+*/
+@editor.completeFrom(DOM.Element)


same, doesn't exist

tsnobip · 2026-06-02T10:27:22Z

+[See Document on MDN](https://developer.mozilla.org/docs/Web/API/Document)
+TODO: mark as private once mutating fields of private records is allowed
+*/
+@editor.completeFrom(DOM.Document)


DOM.Document module doesn't exist, does it?

tsnobip · 2026-06-02T10:28:10Z

+NodeList objects are collections of nodes, usually returned by properties such as Node.childNodes and methods such as document.querySelectorAll().
+[See NodeList on MDN](https://developer.mozilla.org/docs/Web/API/NodeList)
+*/
+@editor.completeFrom(DOM.NodeList) and nodeList<'tNode> = private {


brnrdog · 2026-06-02T18:22:21Z

+@scope("globalThis.document")
+external getElementById: string => null<DomTypes.element> = "getElementById"


Any reason getElementById is the only Document method scoped to globalThis.document? Everything else in this module is still @send.

This means iframeDocument->Document.getElementById(id) would break, since it always reads from the global doc (so no iframes/XML docs, for example). Should we keep using @send for flexibility?

My goal is to rely on @scope instead of @send. This means you can avoid having to get the object and pipe it to a function and then you can just call the functions directly on the module, but I am not sure that will actually work in practice for everything.

It depends really on what we want the public API to be.

let e: Event.t = {} let value = e->Event.target // or let e: Event.t = { target: /* */ } let value = e.target

jderochervlk · 2026-06-03T14:31:20Z

+For shared DOM base interfaces such as `Element`, the structural record can live in a Base-owned module such as `Base__Element.res`. `Base.res` should re-export that implementation as a module, for example `module Element = Base__Element`, so the DOM API module can keep the familiar `DOM.element` alias while method modules use `DomTypes.element`.
+


This is no longer accurate.

Base__ should only be used if it needs to be separate from a Types* module. For example, if there is a type t that is used by DOM and Module but module has other types or functions that DOM does not need there should be a Base__Module and a ModuleTypes file. If DOM does not access the Module or all types are used, then there should just be a ModuleTypes file.

And DomTypes has been removed in favor of keeping things simple and one directional.

jderochervlk · 2026-06-03T14:38:57Z

+
+`Element.res` is a method module. It does not define the `element` record type directly. The shared DOM element type is owned by Base and threaded back into DOM through aliases:
+


I am not 100% on this one. It is similar to how the old webapi bindings worked and does not expose keys on an object and instead relies on piping to access values using @get or @send.

This means you have to do this:

let title = element->Element.title

instead of this:

let title = element.title

By using the pipe option we can have the types not required by other libraries such as rescript-react which can make it more lightweight, but if Event and Element are lightweight enough I don't see why they can't be a requirement of rescript-react?

jderochervlk · 2026-06-03T14:44:42Z


-location->WebAPI.Location.reload
+WebAPI.Location.reload()
 ```


This should use a simpler way to get the location instead of using current. I don't know how I feel about that pattern actually, but I suppose we need some way to pass around location? I actually don't know why you would need to do that...

let href = WebAPI.Location.href WebAPI.Location.reload()

jderochervlk · 2026-06-03T14:46:54Z

+With `"-open WebAPI"`, the same modules can be referenced without the `WebAPI.` prefix:
+
+```ReScript
+let location = Location.current


I don't know how I feel about that pattern actually, but I suppose we need some way to pass around location? I actually don't know why you would need to do that...

* refactor: establish option 2 DOM API shape * docs: document option 2 DOM API shape * refactor: remove DOM compatibility aliases * fix: expose document APIs through Document.t * fix: include DOM owner modules in DOM feature * fix: shrink DOM feature for React consumers * Simplify internal feature groups * Address PR review for shared DOM base types * Add method style audit plan * Move CanvasRenderingContext2D methods to public receiver * Move DOMExtended methods to public receivers * Move IndexedDB methods to public receivers * Move Window methods to public receiver * Move Canvas methods to public receivers * Move DOM utility methods to public receivers * Move HTML methods to public receivers * working with AI and it's not doing great * fix DOM casing and cleanup CSSStyleSheet * remove DomExtended * Rename DOMTypes module to DOM --------- Co-authored-by: Codex <codex@openai.com>

…e-conflicts

refactor: move DOM file out of base folder

9248425

jderochervlk marked this pull request as draft May 20, 2026 14:23

jderochervlk added 16 commits May 20, 2026 10:25

update package-lock.json

bc1a0e7

update to rescript 13-beta.4

1519d88

add Base and element type

bd0ebf4

split out element into sub modules

bea1b18

update remaining element

6dce207

update Element docs

e5d67a7

start splitting up document and switching to @scope

43fcf3d

test out change to Document

d8dc3ce

refactor to break up modules

c83f19c

even more changes

29ead8e

break up dom features

c8ffac8

rename features

5b10b90

breakup location and idledealing

fdc8e56

refactor location

ef46bda

break up more of dom

c762145

refactor to break out base

49420e4

jderochervlk marked this pull request as ready for review May 30, 2026 15:37

chatgpt-codex-connector Bot reviewed May 30, 2026

View reviewed changes

Comment thread src/WebCrypto/Crypto.res Outdated

jderochervlk marked this pull request as draft May 30, 2026 15:38

jderochervlk changed the title ~~refactor: move DOM file out of base folder~~ refactor: split DOM bindings into focused feature modules May 30, 2026

jderochervlk marked this pull request as ready for review May 30, 2026 15:38

jderochervlk added 4 commits May 30, 2026 11:39

remove test binding

4854dbd

update readme

ea34e4a

add back namespace

bbed284

update some docs

c526dd5

chatgpt-codex-connector Bot reviewed May 30, 2026

View reviewed changes

Comment thread src/WebCrypto/Crypto.res Outdated

make random values type safe

ccfa64a

jderochervlk requested review from brnrdog and tsnobip May 31, 2026 13:35

tsnobip reviewed May 31, 2026

View reviewed changes

jderochervlk added 3 commits June 1, 2026 19:44

add back missing private and spread types

d9b8f3c

fixing a couple that were missed

536a2e0

pr feedback

49e227d

jderochervlk requested a review from tsnobip June 2, 2026 00:48

tsnobip requested changes Jun 2, 2026

View reviewed changes

jderochervlk marked this pull request as draft June 2, 2026 15:30

brnrdog reviewed Jun 2, 2026

View reviewed changes

jderochervlk added 5 commits June 2, 2026 17:03

refactor: add shared event base types

dfff1c9

test: remove event unmonorepo assertions

9312db8

docs: update event base types plan

9855b04

refactor: remove event aliases from DomTypes

69a67e2

more splitting up

7b99fc5

jderochervlk commented Jun 3, 2026

View reviewed changes

split out even more from DOM.res

783bd12

jderochervlk commented Jun 3, 2026

View reviewed changes

jderochervlk and others added 2 commits June 3, 2026 12:20

I think it's getting better?

e229716

jderochervlk changed the title ~~refactor: split DOM bindings into focused feature modules~~ refactor: clean up public owners and singleton APIs Jun 9, 2026

jderochervlk added 2 commits June 9, 2026 15:00

Merge remote-tracking branch 'origin/main' into codex/resolve-vlk-bas…

ca2a475

…e-conflicts

docs: consolidate follow-up plan

2611881

		type element = Base__Element.element
		type document = Base__Document.document

		@scope("globalThis.document")
		external getElementById: string => null<DomTypes.element> = "getElementById"

		For shared DOM base interfaces such as `Element`, the structural record can live in a Base-owned module such as `Base__Element.res`. `Base.res` should re-export that implementation as a module, for example `module Element = Base__Element`, so the DOM API module can keep the familiar `DOM.element` alias while method modules use `DomTypes.element`.


		`Element.res` is a method module. It does not define the `element` record type directly. The shared DOM element type is owned by Base and threaded back into DOM through aliases:

Conversation

jderochervlk commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Public Owner Cleanup

Event And DOM Shape

Testing

Uh oh!

jderochervlk commented May 30, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

jderochervlk commented May 30, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

tsnobip left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tsnobip left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brnrdog Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jderochervlk Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jderochervlk Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jderochervlk commented May 20, 2026 •

edited

Loading

brnrdog Jun 2, 2026 •

edited

Loading

jderochervlk Jun 2, 2026 •

edited

Loading

jderochervlk Jun 3, 2026 •

edited

Loading