Repository navigation
Description
Decision
Close #404 rather than adopt its package-wide private-record and explicit-setter migration. Direct field reads and direct mutation of writable native properties are the preferred consumer API:
let url = WebAPI.URL.make(~url="https://example.com")
url.hash = "#details"
let href = url.hrefDo not replace this with getter/setter functions, suppress private-field mutation warnings, or introduce runtime wrappers merely to enforce record-construction restrictions. Preventing fabricated native records remains a separate design/compiler-support question and must preserve this API.
Smaller follow-up PRs
Re-evaluate each change against current main and extract only the independent fix and its focused tests from #404, not the privacy/setter rollout.
1. Checked narrowing for native unions
- Replace unchecked
FillStyle.toCanvasGradient/toCanvasPatternandIntersectionObserverRoot.toElement/toDocumentprojections with checked results such asoption. - Keep existing decoders coherent with the checked projections and document the return-type migration.
- Cover valid native instances, other union members, null roots, and environments without the relevant DOM constructors.
- Make the current-realm limitation explicit; do not claim that
instanceofchecks recognize instances from every iframe/realm.
2. Concrete native result and handle types
- Give stream reader/writer handles distinct abstract identities rather than
unknown, preserving their element types and supported operations. - Preserve a canonical offscreen rendering-context identity across the DOM and Canvas aliases.
- Type performance-entry lists as ordinary arrays of native performance entries.
- Return the concrete media-key access type from
Navigator.requestMediaKeySystemAccess, not an unconstrained type variable.
Split these by API family where that makes review easier. Include positive packed-consumer checks and focused negative cases proving results cannot be assigned arbitrary unrelated types. These fixes do not require making all native records private.
3. Constructible NodeFilter callbacks
- Model
NodeFilteras a caller-owned callback dictionary withacceptNode, rather than an unconstructible native instance. - Cover a consumer-created callback dictionary in a real DOM traversal workflow.
- Keep other caller-owned options, initializers, and callback dictionaries constructible.
4. MessageEvent constructor payload defaults
- Model the native
nullpayload whenMessageEvent.makeomitsdata; do not allow callers to infer an arbitrary non-null native payload from an omitted initializer. - Evaluate a nullable result versus separate constructor forms so explicitly supplied payloads can retain useful typing.
- Cover omitted data, explicit data, and null data with consumer typing checks and runtime tests.
Existing work and boundaries
- Enforce the external boundary for native binding functors #417 already tracks generic binding functors accepting arbitrary receivers. Keep that investigation separate rather than duplicate it here. Reconcile its acceptance criteria with this decision: supported direct field writes must remain usable, and typed setters are not a prerequisite. Concrete upcast helpers alone do not solve generic native-returning methods.
- Make native Web API object types private #403 currently proposes the broad private-record/setter rollout. Its plan needs revisiting in light of this decision; it is not an instruction to resume that rollout unchanged. Any future construction protection must preserve direct mutation of genuine native values.
- The inventory, tests, and documentation in fix(webapi): protect native records with private types #404 may be useful reference material, but do not carry forward checks or contributor rules that mandate the rejected setter migration.
Each extracted fix should stand on its own, document any actual API change, and include focused installed-package and runtime coverage appropriate to the binding. This issue does not authorize merging, publishing, or a compiler/API redesign.
Activity