Skip to content

Extract independent binding fixes from closed PR #404 #418

Open

Description

@jderochervlk

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

Do 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 / toCanvasPattern and IntersectionObserverRoot.toElement / toDocument projections with checked results such as option.
  • 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 instanceof checks 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 NodeFilter as a caller-owned callback dictionary with acceptNode, 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 null payload when MessageEvent.make omits data; 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions