Repository navigation
Description
Summary
Rename overloaded constructor bindings from numbered make* names to semantic from* names, while keeping singleton and true default constructors named make. This pass should also update constructor source comments so generated API docs describe each overload's input shape, add compile-coverage tests for every renamed constructor, and update contributor docs with the constructor naming and documentation rules.
Plan source: docs/superpowers/plans/2026-04-18-constructor-make-rename-plan.md
Context from PR #234
PR #234 (Rename a few bindings with a proper descriptive naming) is the prior rename pass for this area. It was authored against the pre-*API module layout, so treat paths like src/DOM/* and src/WebSockets/* in that PR as earlier equivalents of the current src/DOMAPI/* and src/WebSocketsAPI/* files.
Use PR #234 as source material only for the overlapping constructor families in this issue:
FontFace:make2->fromDataView,make3->fromArrayBuffer, but the string constructor stayedmakeVideoFrame:make2throughmake10were renamed, but the HTML image constructor stayedmakeand several names were shorter than the source-type names this issue wants (fromSvgImage,fromVideoElement,fromCanvasElement)MediaStream:make2->fromStream,make3->fromTracksPath2D:make2->fromString, but the default constructor and copy constructor were not splitDOMMatrix/DOMMatrixReadOnly:make2->fromFloatArray, but the string overload stayed merged intomakeOfflineAudioContext:make2->makeWithParamsWebSocket:make2->makeWithProtocolsReadableStream:make2andmake3were removed instead of being remodeled as typed constructors
This issue intentionally supersedes the constructor naming choices from PR #234 where they do not match the make / from* rules:
- rename non-default constructors still called
make - prefer source-type names such as
fromMediaStream,fromURL,fromURLWithProtocols,fromHTMLVideoElement,fromString, andfromArray - split optional-argument constructors into a true
make()plus typedfrom*overloads - keep the non-constructor overload renames from PR Rename a few bindings with a proper descriptive naming #234 out of scope here
Rules to enforce
- Keep singleton constructors named
make. - Keep true default constructors named
make, even inside overloaded families. - Rename typed constructor overloads in overloaded families to
from*names based on the source input type. - Do not change existing
makeWith*constructors in this pass. - If an optional labeled argument currently hides the default constructor, split it into a real
makeplus typedfrom*overloads.
Scope
Rename pure overload families
-
src/CSSFontLoadingAPI/FontFace.resfromStringfromDataViewfromArrayBuffer
-
src/DOMAPI/VideoFrame.resfromHTMLImageElementfromSVGImageElementfromHTMLVideoElementfromHTMLCanvasElementfromImageBitmapfromOffscreenCanvasfromVideoFramefromArrayBufferfromSharedArrayBufferfromDataView
-
src/WebSocketsAPI/WebSocket.resfromURLfromURLWithProtocols
-
src/WebAudioAPI/OfflineAudioContext.resfromOptionsfromChannelCountLengthAndSampleRate
Update mixed default-plus-typed families
-
src/MediaCaptureAndStreamsAPI/MediaStream.res- keep
make()as the default constructor - rename typed overloads to
fromMediaStreamandfromTracks
- keep
-
src/FileAPI.res- add
type underlyingSource<'t> = anynear the existing stream support types
- add
-
src/FileAPI/ReadableStream.res- make
makegeneric:unit => readableStream<'t> - rename typed overloads to
fromUnderlyingSourceandfromUnderlyingSourceWithStrategy
- make
Split constructor bindings that currently hide the default constructor
-
src/CanvasAPI/Path2D.res- split into
make(),fromPath2D(~path),fromString(~path)
- split into
-
src/DOMAPI/DOMMatrix.res- split into
make(),fromString(~init),fromArray(~init)
- split into
-
src/DOMAPI/DOMMatrixReadOnly.res- split into
make(),fromString(~init),fromArray(~init)
- split into
Documentation
- Rewrite every touched constructor comment to use the final function name in the signature line and example.
- Add a
Source shape:block for every touched constructor comment. - Include MDN links for the input type.
- Include ReScript stdlib links when the source input is a stdlib type such as
string,array<'a>,ArrayBuffer.t, orDataView.t. - Include local source links when the shape is a project-local record or alias.
- Preserve the existing constructor-level MDN link in each comment.
- Update
docs/content/docs/contributing/api-modelling.mdxwith a constructor-overload subsection coveringmakevsfrom*naming and overload splitting. - Update
docs/content/docs/contributing/documentation.mdxso the documented comment structure explicitly includes source-shape links and shows a constructor overload example. - Do not hand-edit
docs/pages/apidocs/**; those pages are template-driven from source comments.
Tests and generated artifacts
- Add compile-coverage test modules for:
tests/CSSFontLoadingAPI/FontFace__test.restests/DOMAPI/VideoFrame__test.restests/WebSocketsAPI/WebSocket__test.restests/WebAudioAPI/OfflineAudioContext__test.restests/MediaCaptureAndStreamsAPI/MediaStream__test.restests/FileAPI/ReadableStream__test.restests/CanvasAPI/Path2D__test.restests/DOMAPI/DOMMatrix__test.restests/DOMAPI/DOMMatrixReadOnly__test.res
- Commit the generated
tests/**/*.jssnapshots for those new coverage modules. - Do not hand-edit
lib/**; it should be regenerated through the normal build.
Verification
-
npm run build -
npm run test -
npm run build:docs -
npm run format:check
Expected results:
- build succeeds with the renamed constructors and overload splits
- tests succeed with the new committed
.jssnapshots and no leftover snapshot diffs - docs build succeeds with the updated source comments and contributor docs
- format check succeeds after formatting
Out of scope
- adopting Vitest in this pass
- adopting happy-dom in this pass
- replacing the current compile-and-snapshot test flow
- runtime browser-behavior assertions
- updating contributor testing docs for a future runtime harness before that harness exists
Rollout order
- Update
ReadableStreamsupport types insrc/FileAPI.resfirst. - Rename the pure overload families.
- Update the mixed default-plus-typed families.
- Split the optional-argument constructor bindings into true default
makeplus typedfrom*overloads. - Rewrite all touched constructor comments.
- Add compile-coverage tests and generated JS snapshots.
- Update contributor docs.
- Leave a clear note that runtime verification will be handled later via Vitest and happy-dom.
- Run build, test, docs, and format verification.
Activity
brnrdog commentedon Apr 18, 2026
We should be good to close this one
jderochervlk commentedon Nov 8, 2026
Completed in #255 and verified against current main
844c32af. The renamed constructor families, default/typed overloads, contributor guidance and all nine requested compile fixtures are present. The fixtures are registered in the current test manifest, and main CI passed build, formatting, tests and documentation checks.The original checklist differs from the final agreed implementation. Review explicitly removed Source shape blocks, approved separate ArrayBuffer/TypedArray/DataView bindings, and chose one ReadableStream source constructor with optional strategy. Those are accepted changes, not unfinished work.
The newer test infrastructure in #397/#399/#398 also replaces the old generated-JavaScript snapshot requirement with explicit compile/runtime categories and real Chromium tests. Generated JS snapshots are not being claimed as present. Closing as completed under the reviewed requirements rather than treating the obsolete checklist wording as remaining work.