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

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-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.

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: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

Comment thread src/DOM/DOM.res Outdated

Comment thread src/Base/Base.res Outdated

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

Comment thread docs/content/docs/contributing/api-module-structure.mdx Outdated

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

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


		`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!

Uh oh!

tsnobip left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tsnobip Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

jderochervlk Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

jderochervlk Jun 3, 2026

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!

jderochervlk Jun 3, 2026

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