diff --git a/docs/content/docs/contributing/api-modelling.mdx b/docs/content/docs/contributing/api-modelling.mdx index 1b7aedb..032b32c 100644 --- a/docs/content/docs/contributing/api-modelling.mdx +++ b/docs/content/docs/contributing/api-modelling.mdx @@ -58,6 +58,48 @@ external addEventListenerWithCapture: ( When naming an overloaded function, we can use the `With` suffix to indicate that it is an overloaded function. +### Constructor overloads + +Constructors follow a different naming rule than methods. + +- Keep singleton constructors named `make`. +- Keep true default constructors named `make`, even when the constructor family also has typed overloads. +- When a constructor family does not have a default constructor, use `from*` names for every overload, including the first one. +- Base `from*` names on the source input type: `fromString`, `fromArrayBuffer`, `fromMediaStream`, `fromURLWithProtocols`, and so on. +- If an optional labeled argument hides a real default constructor, split that binding into `make()` plus typed `from*` overloads instead of keeping the optional argument on `make`. + +For example, these constructor families are easier to understand than numbered overloads: + +```ReScript +@new +external fromString: (~family: string, ~source: string) => fontFace = "FontFace" + +@new +external fromDataView: (~family: string, ~source: DataView.t) => fontFace = "FontFace" + +@new +external fromArrayBuffer: (~family: string, ~source: ArrayBuffer.t) => fontFace = "FontFace" +``` + +And if a constructor really does have a default form, split it instead of hiding it: + +```ReScript +@new +external make: unit => domMatrix = "DOMMatrix" + +@new +external fromString: string => domMatrix = "DOMMatrix" + +@new +external fromArray: array => domMatrix = "DOMMatrix" +``` + +Single-source constructor variants should take the source value directly without a label. + +Keep `makeWith*` names for non-default convenience constructors that are not part of a source-type overload family. + +Constructor naming is currently verified with compile-coverage tests. Runtime verification for these constructor families will be added later when the Vitest and happy-dom harness lands. + ### Decoded variants We can be pragmatic with overloaded functions and use model them in various creative ways. diff --git a/docs/content/docs/contributing/documentation.mdx b/docs/content/docs/contributing/documentation.mdx index 2f75358..d2c19e0 100644 --- a/docs/content/docs/contributing/documentation.mdx +++ b/docs/content/docs/contributing/documentation.mdx @@ -21,7 +21,8 @@ It keeps the user inside the IDE and avoids context switching. The documentation for each binding should roughly follow this structure: - signature -- key description (tip: check MDN for inspiration) +- short description (tip: check MDN for inspiration) +- `Source shape:` block with links for the overload-specific input types - example usage - link to the MDN documentation @@ -44,3 +45,28 @@ window->Window.fetch("https://rescript-lang.org") external fetch: (window, string, ~init: requestInit=?) => promise = "fetch" ```` + +Constructor overloads should use the same structure, but make the differentiating input shape explicit. +Link ReScript stdlib types such as `string`, `array<'a>`, `ArrayBuffer.t`, and `DataView.t`, and link project-local records or aliases when the constructor takes one of those shapes. +If a constructor variant has a single source input, show it as a direct unlabeled argument in both the signature and example. + +````ReScript +/* +`fromArray(array)` + +The DOMMatrix() constructor creates a new DOMMatrix from an array of matrix component values. + +Source shape: +- ReScript [array](https://rescript-lang.org/docs/manual/api/stdlib/array) of numeric values accepted by MDN [DOMMatrix()](https://developer.mozilla.org/docs/Web/API/DOMMatrix/DOMMatrix). + +```res +let matrix = DOMMatrix.fromArray([1., 0., 0., 1., 0., 0.]) +``` + +[Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrix) +*/ +@new +external fromArray: array => domMatrix = "DOMMatrix" +```` + +For now, these examples stay compile-coverage oriented. Runtime verification of constructor behavior will be handled later via Vitest and happy-dom. diff --git a/packages/CSSFontLoading/src/FontFace.res b/packages/CSSFontLoading/src/FontFace.res index d777e10..8045ec5 100644 --- a/packages/CSSFontLoading/src/FontFace.res +++ b/packages/CSSFontLoading/src/FontFace.res @@ -1,28 +1,70 @@ /** +`fromString(~family: string, ~source: string, ~descriptors: fontFaceDescriptors=?)` + +The FontFace() constructor creates a new FontFace object from CSS source text. + +Source shape: +- `family`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the font family name. +- `source`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) containing CSS [`@font-face` `src`](https://developer.mozilla.org/docs/Web/CSS/@font-face/src) text. +- `descriptors`: local [`fontFaceDescriptors`](../#fontFaceDescriptors) values for optional constructor descriptors. + +```res +let fontFace = + FontFace.fromString(~family="Inter", ~source="url(/fonts/inter.woff2)") +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/FontFace) */ @new -external make: ( +external fromString: ( ~family: string, ~source: string, ~descriptors: Types.fontFaceDescriptors=?, ) => Types.fontFace = "FontFace" /** +`fromDataView(~family: string, ~source: DataView.t, ~descriptors: fontFaceDescriptors=?)` + +The FontFace() constructor creates a new FontFace object from DataView-backed font data. + +Source shape: +- `family`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the font family name. +- `source`: ReScript [`DataView.t`](https://rescript-lang.org/docs/manual/api/stdlib/dataview) mapped to MDN [DataView](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DataView). +- `descriptors`: local [`fontFaceDescriptors`](../#fontFaceDescriptors) values for optional constructor descriptors. + +```res +let fontFace = + FontFace.fromDataView(~family="Inter", ~source=myDataView) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/FontFace) */ @new -external make2: ( +external fromDataView: ( ~family: string, ~source: DataView.t, ~descriptors: Types.fontFaceDescriptors=?, ) => Types.fontFace = "FontFace" /** +`fromArrayBuffer(~family: string, ~source: ArrayBuffer.t, ~descriptors: fontFaceDescriptors=?)` + +The FontFace() constructor creates a new FontFace object from ArrayBuffer-backed font data. + +Source shape: +- `family`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the font family name. +- `source`: ReScript [`ArrayBuffer.t`](https://rescript-lang.org/docs/manual/api/stdlib/arraybuffer) mapped to MDN [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer). +- `descriptors`: local [`fontFaceDescriptors`](../#fontFaceDescriptors) values for optional constructor descriptors. + +```res +let fontFace = + FontFace.fromArrayBuffer(~family="Inter", ~source=myArrayBuffer) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/FontFace) */ @new -external make3: ( +external fromArrayBuffer: ( ~family: string, ~source: ArrayBuffer.t, ~descriptors: Types.fontFaceDescriptors=?, diff --git a/packages/Canvas/src/Path2D.res b/packages/Canvas/src/Path2D.res index 663b245..cb25e92 100644 --- a/packages/Canvas/src/Path2D.res +++ b/packages/Canvas/src/Path2D.res @@ -1,16 +1,55 @@ type domMatrix2DInit = WebApiDOM.Types.domMatrix2DInit /** +`make()` + +The Path2D() constructor creates a new empty Path2D object. + +Source shape: +- no source input; this constructor creates a fresh MDN [Path2D](https://developer.mozilla.org/docs/Web/API/Path2D). + +```res +let path = Path2D.make() +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/Path2D) */ @new -external make: (~path: Types.path2D=?) => Types.path2D = "Path2D" +external make: unit => Types.path2D = "Path2D" /** +`fromPath2D(path2D)` + +The Path2D() constructor creates a new Path2D object by copying another Path2D source. + +Source shape: +- local [`Path2D.t`](#t) mapped to MDN [Path2D](https://developer.mozilla.org/docs/Web/API/Path2D). + +```res +let copiedPath = Path2D.fromPath2D(existingPath) +``` + +[Read more on MDN](https://developer.mozilla.org/docs/Web/API/Path2D) +*/ +@new +external fromPath2D: Types.path2D => Types.path2D = "Path2D" + +/** +`fromString(string)` + +The Path2D() constructor creates a new Path2D object from SVG path data text. + +Source shape: +- ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) containing SVG path data accepted by MDN [Path2D()](https://developer.mozilla.org/docs/Web/API/Path2D/Path2D). + +```res +let path = Path2D.fromString("M0 0 L10 10") +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/Path2D) */ @new -external make2: (~path: string=?) => Types.path2D = "Path2D" +external fromString: string => Types.path2D = "Path2D" /** [Read more on MDN](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/closePath) diff --git a/packages/Canvas/src/VideoFrame.res b/packages/Canvas/src/VideoFrame.res index 10fb9cd..fdcb89a 100644 --- a/packages/Canvas/src/VideoFrame.res +++ b/packages/Canvas/src/VideoFrame.res @@ -1,89 +1,217 @@ +type sharedArrayBuffer = unknown + /** +`fromHTMLImageElement(~image: HTMLImageElement.t, ~init: videoFrameInit=?)` + +The VideoFrame() constructor creates a new VideoFrame from an HTMLImageElement source. + +Source shape: +- `image`: local [`HTMLImageElement.t`](../dom/html-image-element#t) mapped to MDN [HTMLImageElement](https://developer.mozilla.org/docs/Web/API/HTMLImageElement). +- `init`: local [`videoFrameInit`](../dom#videoFrameInit) values for optional frame initialization. + +```res +let frame = VideoFrame.fromHTMLImageElement(~image=myImageElement) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make: ( +external fromHTMLImageElement: ( ~image: WebApiDOM.Types.htmlImageElement, ~init: WebApiDOM.Types.videoFrameInit=?, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromSVGImageElement(~image: SVGImageElement.t, ~init: videoFrameInit=?)` + +The VideoFrame() constructor creates a new VideoFrame from an SVGImageElement source. + +Source shape: +- `image`: local [`SVGImageElement.t`](../dom/svg-image-element#t) mapped to MDN [SVGImageElement](https://developer.mozilla.org/docs/Web/API/SVGImageElement). +- `init`: local [`videoFrameInit`](../dom#videoFrameInit) values for optional frame initialization. + +```res +let frame = VideoFrame.fromSVGImageElement(~image=mySvgImageElement) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make2: ( +external fromSVGImageElement: ( ~image: WebApiDOM.Types.svgImageElement, ~init: WebApiDOM.Types.videoFrameInit=?, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromHTMLVideoElement(~image: HTMLVideoElement.t, ~init: videoFrameInit=?)` + +The VideoFrame() constructor creates a new VideoFrame from an HTMLVideoElement source. + +Source shape: +- `image`: local [`HTMLVideoElement.t`](../dom/html-video-element#t) mapped to MDN [HTMLVideoElement](https://developer.mozilla.org/docs/Web/API/HTMLVideoElement). +- `init`: local [`videoFrameInit`](../dom#videoFrameInit) values for optional frame initialization. + +```res +let frame = VideoFrame.fromHTMLVideoElement(~image=myVideoElement) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make3: ( +external fromHTMLVideoElement: ( ~image: WebApiDOM.Types.htmlVideoElement, ~init: WebApiDOM.Types.videoFrameInit=?, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromHTMLCanvasElement(~image: HTMLCanvasElement.t, ~init: videoFrameInit=?)` + +The VideoFrame() constructor creates a new VideoFrame from an HTMLCanvasElement source. + +Source shape: +- `image`: local [`HTMLCanvasElement.t`](./html-canvas-element#t) mapped to MDN [HTMLCanvasElement](https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement). +- `init`: local [`videoFrameInit`](../dom#videoFrameInit) values for optional frame initialization. + +```res +let frame = VideoFrame.fromHTMLCanvasElement(~image=myCanvasElement) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make4: ( +external fromHTMLCanvasElement: ( ~image: WebApiDOM.Types.htmlCanvasElement, ~init: WebApiDOM.Types.videoFrameInit=?, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromImageBitmap(~image: ImageBitmap.t, ~init: videoFrameInit=?)` + +The VideoFrame() constructor creates a new VideoFrame from an ImageBitmap source. + +Source shape: +- `image`: local [`ImageBitmap.t`](./image-bitmap#t) mapped to MDN [ImageBitmap](https://developer.mozilla.org/docs/Web/API/ImageBitmap). +- `init`: local [`videoFrameInit`](../dom#videoFrameInit) values for optional frame initialization. + +```res +let frame = VideoFrame.fromImageBitmap(~image=myImageBitmap) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make5: ( +external fromImageBitmap: ( ~image: Types.imageBitmap, ~init: WebApiDOM.Types.videoFrameInit=?, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromOffscreenCanvas(~image: OffscreenCanvas.t, ~init: videoFrameInit=?)` + +The VideoFrame() constructor creates a new VideoFrame from an OffscreenCanvas source. + +Source shape: +- `image`: local [`OffscreenCanvas.t`](./offscreen-canvas#t) mapped to MDN [OffscreenCanvas](https://developer.mozilla.org/docs/Web/API/OffscreenCanvas). +- `init`: local [`videoFrameInit`](../dom#videoFrameInit) values for optional frame initialization. + +```res +let frame = VideoFrame.fromOffscreenCanvas(~image=myOffscreenCanvas) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make6: ( +external fromOffscreenCanvas: ( ~image: Types.offscreenCanvas, ~init: WebApiDOM.Types.videoFrameInit=?, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromVideoFrame(~image: VideoFrame.t, ~init: videoFrameInit=?)` + +The VideoFrame() constructor creates a new VideoFrame from an existing VideoFrame source. + +Source shape: +- `image`: local [`VideoFrame.t`](#t) mapped to MDN [VideoFrame](https://developer.mozilla.org/docs/Web/API/VideoFrame). +- `init`: local [`videoFrameInit`](../dom#videoFrameInit) values for optional frame initialization. + +```res +let frame = VideoFrame.fromVideoFrame(~image=otherFrame) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make7: ( +external fromVideoFrame: ( ~image: WebApiDOM.Types.videoFrame, ~init: WebApiDOM.Types.videoFrameInit=?, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromArrayBuffer(~data: ArrayBuffer.t, ~init: videoFrameBufferInit)` + +The VideoFrame() constructor creates a new VideoFrame from ArrayBuffer-backed pixel data. + +Source shape: +- `data`: ReScript [`ArrayBuffer.t`](https://rescript-lang.org/docs/manual/api/stdlib/arraybuffer) mapped to MDN [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer). +- `init`: local [`videoFrameBufferInit`](../dom#videoFrameBufferInit) values describing the buffer-backed frame layout. + +```res +let frame = + VideoFrame.fromArrayBuffer(~data=myArrayBuffer, ~init=myVideoFrameBufferInit) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make8: ( +external fromArrayBuffer: ( ~data: ArrayBuffer.t, ~init: WebApiDOM.Types.videoFrameBufferInit, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromSharedArrayBuffer(~data: sharedArrayBuffer, ~init: videoFrameBufferInit)` + +The VideoFrame() constructor creates a new VideoFrame from SharedArrayBuffer-backed pixel data. + +Source shape: +- `data`: opaque SharedArrayBuffer-aligned data accepted by MDN [SharedArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer). +- `init`: local [`videoFrameBufferInit`](../dom#videoFrameBufferInit) values describing the buffer-backed frame layout. + +```res +let frame = + VideoFrame.fromSharedArrayBuffer( + ~data=mySharedArrayBuffer, + ~init=myVideoFrameBufferInit, + ) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make9: ( - ~data: WebApiBase.ArrayBufferTypedArrayOrDataView.t, +external fromSharedArrayBuffer: ( + ~data: sharedArrayBuffer, ~init: WebApiDOM.Types.videoFrameBufferInit, ) => WebApiDOM.Types.videoFrame = "VideoFrame" /** +`fromDataView(~data: DataView.t, ~init: videoFrameBufferInit)` + +The VideoFrame() constructor creates a new VideoFrame from DataView-backed pixel data. + +Source shape: +- `data`: ReScript [`DataView.t`](https://rescript-lang.org/docs/manual/api/stdlib/dataview) mapped to MDN [DataView](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DataView). +- `init`: local [`videoFrameBufferInit`](../dom#videoFrameBufferInit) values describing the buffer-backed frame layout. + +```res +let frame = + VideoFrame.fromDataView(~data=myDataView, ~init=myVideoFrameBufferInit) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/VideoFrame) */ @new -external make10: ( +external fromDataView: ( ~data: DataView.t, ~init: WebApiDOM.Types.videoFrameBufferInit, ) => WebApiDOM.Types.videoFrame = "VideoFrame" diff --git a/packages/DOM/src/DOMMatrix.res b/packages/DOM/src/DOMMatrix.res index f9e8564..09748fd 100644 --- a/packages/DOM/src/DOMMatrix.res +++ b/packages/DOM/src/DOMMatrix.res @@ -1,14 +1,53 @@ /** +`make()` + +The DOMMatrix() constructor creates a new identity DOMMatrix. + +Source shape: +- no source input; this constructor creates a fresh MDN [DOMMatrix](https://developer.mozilla.org/docs/Web/API/DOMMatrix). + +```res +let matrix = DOMMatrix.make() +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrix) */ @new -external make: (~init: string=?) => Types.domMatrix = "DOMMatrix" +external make: unit => Types.domMatrix = "DOMMatrix" /** +`fromString(string)` + +The DOMMatrix() constructor creates a new DOMMatrix from a transform string. + +Source shape: +- ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) accepted by MDN [DOMMatrix()](https://developer.mozilla.org/docs/Web/API/DOMMatrix/DOMMatrix). + +```res +let matrix = DOMMatrix.fromString("matrix(1, 0, 0, 1, 0, 0)") +``` + +[Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrix) +*/ +@new +external fromString: string => Types.domMatrix = "DOMMatrix" + +/** +`fromArray(array)` + +The DOMMatrix() constructor creates a new DOMMatrix from an array of matrix component values. + +Source shape: +- ReScript [array](https://rescript-lang.org/docs/manual/api/stdlib/array) of numeric values accepted by MDN [DOMMatrix()](https://developer.mozilla.org/docs/Web/API/DOMMatrix/DOMMatrix). + +```res +let matrix = DOMMatrix.fromArray([1., 0., 0., 1., 0., 0.]) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrix) */ @new -external make2: (~init: array=?) => Types.domMatrix = "DOMMatrix" +external fromArray: array => Types.domMatrix = "DOMMatrix" external asDOMMatrixReadOnly: Types.domMatrix => Types.domMatrixReadOnly = "%identity" @scope("DOMMatrix") diff --git a/packages/DOM/src/DOMMatrixReadOnly.res b/packages/DOM/src/DOMMatrixReadOnly.res index 1c5cc27..4b7cba7 100644 --- a/packages/DOM/src/DOMMatrixReadOnly.res +++ b/packages/DOM/src/DOMMatrixReadOnly.res @@ -1,14 +1,53 @@ /** +`make()` + +The DOMMatrixReadOnly() constructor creates a new identity DOMMatrixReadOnly value. + +Source shape: +- no source input; this constructor creates a fresh MDN [DOMMatrixReadOnly](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly). + +```res +let matrix = DOMMatrixReadOnly.make() +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly) */ @new -external make: (~init: string=?) => Types.domMatrixReadOnly = "DOMMatrixReadOnly" +external make: unit => Types.domMatrixReadOnly = "DOMMatrixReadOnly" /** +`fromString(string)` + +The DOMMatrixReadOnly() constructor creates a new DOMMatrixReadOnly value from a transform string. + +Source shape: +- ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) accepted by MDN [DOMMatrixReadOnly()](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/DOMMatrixReadOnly). + +```res +let matrix = DOMMatrixReadOnly.fromString("matrix(1, 0, 0, 1, 0, 0)") +``` + +[Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly) +*/ +@new +external fromString: string => Types.domMatrixReadOnly = "DOMMatrixReadOnly" + +/** +`fromArray(array)` + +The DOMMatrixReadOnly() constructor creates a new DOMMatrixReadOnly value from an array of matrix component values. + +Source shape: +- ReScript [array](https://rescript-lang.org/docs/manual/api/stdlib/array) of numeric values accepted by MDN [DOMMatrixReadOnly()](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/DOMMatrixReadOnly). + +```res +let matrix = DOMMatrixReadOnly.fromArray([1., 0., 0., 1., 0., 0.]) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly) */ @new -external make2: (~init: array=?) => Types.domMatrixReadOnly = "DOMMatrixReadOnly" +external fromArray: array => Types.domMatrixReadOnly = "DOMMatrixReadOnly" @scope("DOMMatrixReadOnly") external fromMatrix: (~other: Types.domMatrixInit=?) => Types.domMatrixReadOnly = "fromMatrix" diff --git a/packages/File/src/ReadableStream.res b/packages/File/src/ReadableStream.res index 205e4fc..2c58527 100644 --- a/packages/File/src/ReadableStream.res +++ b/packages/File/src/ReadableStream.res @@ -4,22 +4,63 @@ type t<'r> = Types.readableStream<'r> /** +`make()` + +The ReadableStream() constructor creates a new empty ReadableStream. + +Source shape: +- no source input; this constructor creates a fresh MDN [ReadableStream](https://developer.mozilla.org/docs/Web/API/ReadableStream). + +```res +let stream: ReadableStream.t = ReadableStream.make() +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/ReadableStream) */ @new -external make: unit => t> = "ReadableStream" +external make: unit => t<'t> = "ReadableStream" /** +`fromUnderlyingSource(underlyingSource<'t>)` + +The ReadableStream() constructor creates a new ReadableStream from an underlying source definition. + +Source shape: +- local [`underlyingSource<'t>`](../#underlyingSource) values accepted by MDN [ReadableStream()](https://developer.mozilla.org/docs/Web/API/ReadableStream/ReadableStream). + +```res +let stream = ReadableStream.fromUnderlyingSource(myUnderlyingSource) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/ReadableStream) */ @new -external make2: unit => unknown = "ReadableStream" +external fromUnderlyingSource: Types.underlyingSource<'t> => t<'t> = "ReadableStream" /** +`fromUnderlyingSourceWithStrategy(~underlyingSource: underlyingSource<'t>, ~strategy: queuingStrategy<'t>)` + +The ReadableStream() constructor creates a new ReadableStream from an underlying source definition and a queuing strategy. + +Source shape: +- local [`underlyingSource<'t>`](../#underlyingSource) values accepted by MDN [ReadableStream()](https://developer.mozilla.org/docs/Web/API/ReadableStream/ReadableStream). +- local [`queuingStrategy<'t>`](../#queuingStrategy) values describing the stream queueing behavior. + +```res +let stream = + ReadableStream.fromUnderlyingSourceWithStrategy( + ~underlyingSource=myUnderlyingSource, + ~strategy=myQueuingStrategy, + ) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/ReadableStream) */ @new -external make3: unit => unknown = "ReadableStream" +external fromUnderlyingSourceWithStrategy: ( + ~underlyingSource: Types.underlyingSource<'t>, + ~strategy: Types.queuingStrategy<'t>, +) => t<'t> = "ReadableStream" /** [Read more on MDN](https://developer.mozilla.org/docs/Web/API/ReadableStream/cancel) diff --git a/packages/File/src/Types.res b/packages/File/src/Types.res index 44c9d3a..fee2c9a 100644 --- a/packages/File/src/Types.res +++ b/packages/File/src/Types.res @@ -137,6 +137,8 @@ type queuingStrategy<'t> = unknown type underlyingSink<'t> = unknown +type underlyingSource<'t> = unknown + type readableStreamReader<'t> = unknown type writableStreamDefaultWriter<'t> = unknown diff --git a/packages/MediaCaptureAndStreams/src/MediaStream.res b/packages/MediaCaptureAndStreams/src/MediaStream.res index 518205e..8dc0e00 100644 --- a/packages/MediaCaptureAndStreams/src/MediaStream.res +++ b/packages/MediaCaptureAndStreams/src/MediaStream.res @@ -1,22 +1,55 @@ type t = Types.mediaStream = private {...Types.mediaStream} /** +`make()` + +The MediaStream() constructor creates a new empty MediaStream. + +Source shape: +- no source input; this constructor creates a fresh MDN [MediaStream](https://developer.mozilla.org/docs/Web/API/MediaStream). + +```res +let stream = MediaStream.make() +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/MediaStream) */ @new external make: unit => t = "MediaStream" /** +`fromMediaStream(mediaStream)` + +The MediaStream() constructor creates a new MediaStream by copying another MediaStream source. + +Source shape: +- local [`MediaStream.t`](#t) mapped to MDN [MediaStream](https://developer.mozilla.org/docs/Web/API/MediaStream). + +```res +let copiedStream = MediaStream.fromMediaStream(existingStream) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/MediaStream) */ @new -external makeFromMediaStream: t => t = "MediaStream" +external fromMediaStream: t => t = "MediaStream" /** +`fromTracks(array)` + +The MediaStream() constructor creates a new MediaStream from an array of MediaStreamTrack values. + +Source shape: +- ReScript [array](https://rescript-lang.org/docs/manual/api/stdlib/array) of local [`MediaStreamTrack.t`](./media-stream-track#t) values mapped to MDN [MediaStreamTrack](https://developer.mozilla.org/docs/Web/API/MediaStreamTrack). + +```res +let stream = MediaStream.fromTracks([audioTrack, videoTrack]) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/MediaStream) */ @new -external makeFromMediaStreams: array => t = "MediaStream" +external fromTracks: array => t = "MediaStream" include WebApiEvent.EventTarget.Impl({type t = t}) diff --git a/packages/WebAudio/src/OfflineAudioContext.res b/packages/WebAudio/src/OfflineAudioContext.res index 3598e9d..d47fb93 100644 --- a/packages/WebAudio/src/OfflineAudioContext.res +++ b/packages/WebAudio/src/OfflineAudioContext.res @@ -1,16 +1,44 @@ include BaseAudioContext.Impl({type t = Types.offlineAudioContext}) /** +`fromOptions(offlineAudioContextOptions)` + +The OfflineAudioContext() constructor creates a new OfflineAudioContext from an options record. + +Source shape: +- local [`offlineAudioContextOptions`](../#offlineAudioContextOptions) values accepted by MDN [OfflineAudioContext()](https://developer.mozilla.org/docs/Web/API/OfflineAudioContext/OfflineAudioContext). + +```res +let context = OfflineAudioContext.fromOptions(myOfflineAudioContextOptions) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/OfflineAudioContext) */ @new -external make: Types.offlineAudioContextOptions => Types.offlineAudioContext = "OfflineAudioContext" +external fromOptions: Types.offlineAudioContextOptions => Types.offlineAudioContext = + "OfflineAudioContext" /** +`fromChannelCountLengthAndSampleRate(~numberOfChannels: int, ~length: int, ~sampleRate: float)` + +The OfflineAudioContext() constructor creates a new OfflineAudioContext from explicit channel-count, length, and sample-rate values. + +Source shape: +- numeric `numberOfChannels`, `length`, and `sampleRate` values accepted by MDN [OfflineAudioContext()](https://developer.mozilla.org/docs/Web/API/OfflineAudioContext/OfflineAudioContext). + +```res +let context = + OfflineAudioContext.fromChannelCountLengthAndSampleRate( + ~numberOfChannels=2, + ~length=44_100, + ~sampleRate=44_100., + ) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/OfflineAudioContext) */ @new -external make2: ( +external fromChannelCountLengthAndSampleRate: ( ~numberOfChannels: int, ~length: int, ~sampleRate: float, diff --git a/packages/WebSockets/src/WebSocket.res b/packages/WebSockets/src/WebSocket.res index 455ec50..38ec48d 100644 --- a/packages/WebSockets/src/WebSocket.res +++ b/packages/WebSockets/src/WebSocket.res @@ -7,16 +7,44 @@ type closeEvent = Types.closeEvent = private {...Types.closeEvent} type messageEventSource = Types.messageEventSource /** +`fromURL(~url: string, ~protocols: string=?)` + +The WebSocket() constructor creates a new WebSocket connection from a URL string and an optional single protocol. + +Source shape: +- `url`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the [WebSocket URL](https://developer.mozilla.org/docs/Web/API/WebSocket/WebSocket) to connect to. +- `protocols`: optional ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for a single WebSocket sub-protocol name. + +```res +let socket = WebSocket.fromURL(~url="wss://example.com/socket") +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/WebSocket) */ @new -external make: (~url: string, ~protocols: string=?) => t = "WebSocket" +external fromURL: (~url: string, ~protocols: string=?) => t = "WebSocket" /** +`fromURLWithProtocols(~url: string, ~protocols: array)` + +The WebSocket() constructor creates a new WebSocket connection from a URL string and multiple protocol names. + +Source shape: +- `url`: ReScript [string](https://rescript-lang.org/docs/manual/primitive-types/#string) for the [WebSocket URL](https://developer.mozilla.org/docs/Web/API/WebSocket/WebSocket) to connect to. +- `protocols`: ReScript [array](https://rescript-lang.org/docs/manual/api/stdlib/array) of protocol names accepted by the MDN [WebSocket()](https://developer.mozilla.org/docs/Web/API/WebSocket/WebSocket) constructor. + +```res +let socket = + WebSocket.fromURLWithProtocols( + ~url="wss://example.com/socket", + ~protocols=["chat", "superchat"], + ) +``` + [Read more on MDN](https://developer.mozilla.org/docs/Web/API/WebSocket) */ @new -external makeWithProtocols: (~url: string, ~protocols: array=?) => t = "WebSocket" +external fromURLWithProtocols: (~url: string, ~protocols: array) => t = "WebSocket" include WebApiEvent.EventTarget.Impl({type t = t}) diff --git a/tests/CSSFontLoadingAPI/FontFace__test.res b/tests/CSSFontLoadingAPI/FontFace__test.res new file mode 100644 index 0000000..d5700b2 --- /dev/null +++ b/tests/CSSFontLoadingAPI/FontFace__test.res @@ -0,0 +1,14 @@ +let dataView: DataView.t = Obj.magic() +let arrayBuffer: ArrayBuffer.t = Obj.magic() + +let _fromString = WebApiCSSFontLoading.FontFace.fromString( + ~family="Inter", + ~source="url(/fonts/inter.woff2)", +) + +let _fromDataView = WebApiCSSFontLoading.FontFace.fromDataView(~family="Inter", ~source=dataView) + +let _fromArrayBuffer = WebApiCSSFontLoading.FontFace.fromArrayBuffer( + ~family="Inter", + ~source=arrayBuffer, +) diff --git a/tests/CanvasAPI/Path2D__test.res b/tests/CanvasAPI/Path2D__test.res new file mode 100644 index 0000000..9e954d7 --- /dev/null +++ b/tests/CanvasAPI/Path2D__test.res @@ -0,0 +1,5 @@ +let path2D: WebApiCanvas.Types.path2D = Obj.magic() + +let _make = WebApiCanvas.Path2D.make() +let _fromPath2D = WebApiCanvas.Path2D.fromPath2D(path2D) +let _fromString = WebApiCanvas.Path2D.fromString("M0 0 L10 10") diff --git a/tests/DOMAPI/DOMMatrixReadOnly__test.res b/tests/DOMAPI/DOMMatrixReadOnly__test.res new file mode 100644 index 0000000..24dcba0 --- /dev/null +++ b/tests/DOMAPI/DOMMatrixReadOnly__test.res @@ -0,0 +1,5 @@ +let _make = WebApiDOM.DOMMatrixReadOnly.make() + +let _fromString = WebApiDOM.DOMMatrixReadOnly.fromString("matrix(1, 0, 0, 1, 0, 0)") + +let _fromArray = WebApiDOM.DOMMatrixReadOnly.fromArray([1., 0., 0., 1., 0., 0.]) diff --git a/tests/DOMAPI/DOMMatrix__test.res b/tests/DOMAPI/DOMMatrix__test.res new file mode 100644 index 0000000..512f98d --- /dev/null +++ b/tests/DOMAPI/DOMMatrix__test.res @@ -0,0 +1,3 @@ +let _make = WebApiDOM.DOMMatrix.make() +let _fromString = WebApiDOM.DOMMatrix.fromString("matrix(1, 0, 0, 1, 0, 0)") +let _fromArray = WebApiDOM.DOMMatrix.fromArray([1., 0., 0., 1., 0., 0.]) diff --git a/tests/DOMAPI/VideoFrame__test.res b/tests/DOMAPI/VideoFrame__test.res new file mode 100644 index 0000000..9696276 --- /dev/null +++ b/tests/DOMAPI/VideoFrame__test.res @@ -0,0 +1,59 @@ +let htmlImageElement: WebApiDOM.Types.htmlImageElement = Obj.magic() +let svgImageElement: WebApiDOM.Types.svgImageElement = Obj.magic() +let htmlVideoElement: WebApiDOM.Types.htmlVideoElement = Obj.magic() +let htmlCanvasElement: WebApiDOM.Types.htmlCanvasElement = Obj.magic() +let imageBitmap: WebApiCanvas.Types.imageBitmap = Obj.magic() +let offscreenCanvas: WebApiCanvas.Types.offscreenCanvas = Obj.magic() +let videoFrame: WebApiDOM.Types.videoFrame = Obj.magic() +let arrayBuffer: ArrayBuffer.t = Obj.magic() +let sharedArrayBuffer = Obj.magic() +let dataView: DataView.t = Obj.magic() +let videoFrameInit: WebApiDOM.Types.videoFrameInit = Obj.magic() +let videoFrameBufferInit: WebApiDOM.Types.videoFrameBufferInit = Obj.magic() + +let _fromHTMLImageElement = WebApiCanvas.VideoFrame.fromHTMLImageElement( + ~image=htmlImageElement, + ~init=videoFrameInit, +) + +let _fromSVGImageElement = WebApiCanvas.VideoFrame.fromSVGImageElement( + ~image=svgImageElement, + ~init=videoFrameInit, +) + +let _fromHTMLVideoElement = WebApiCanvas.VideoFrame.fromHTMLVideoElement( + ~image=htmlVideoElement, + ~init=videoFrameInit, +) + +let _fromHTMLCanvasElement = WebApiCanvas.VideoFrame.fromHTMLCanvasElement( + ~image=htmlCanvasElement, + ~init=videoFrameInit, +) + +let _fromImageBitmap = WebApiCanvas.VideoFrame.fromImageBitmap( + ~image=imageBitmap, + ~init=videoFrameInit, +) + +let _fromOffscreenCanvas = WebApiCanvas.VideoFrame.fromOffscreenCanvas( + ~image=offscreenCanvas, + ~init=videoFrameInit, +) + +let _fromVideoFrame = WebApiCanvas.VideoFrame.fromVideoFrame( + ~image=videoFrame, + ~init=videoFrameInit, +) + +let _fromArrayBuffer = WebApiCanvas.VideoFrame.fromArrayBuffer( + ~data=arrayBuffer, + ~init=videoFrameBufferInit, +) + +let _fromSharedArrayBuffer = WebApiCanvas.VideoFrame.fromSharedArrayBuffer( + ~data=sharedArrayBuffer, + ~init=videoFrameBufferInit, +) + +let _fromDataView = WebApiCanvas.VideoFrame.fromDataView(~data=dataView, ~init=videoFrameBufferInit) diff --git a/tests/FileAPI/ReadableStream__test.res b/tests/FileAPI/ReadableStream__test.res new file mode 100644 index 0000000..2696edb --- /dev/null +++ b/tests/FileAPI/ReadableStream__test.res @@ -0,0 +1,11 @@ +let underlyingSource: WebApiFile.Types.underlyingSource = Obj.magic() +let strategy: WebApiFile.Types.queuingStrategy = Obj.magic() + +let _make: WebApiFile.ReadableStream.t = WebApiFile.ReadableStream.make() + +let _fromUnderlyingSource = WebApiFile.ReadableStream.fromUnderlyingSource(underlyingSource) + +let _fromUnderlyingSourceWithStrategy = WebApiFile.ReadableStream.fromUnderlyingSourceWithStrategy( + ~underlyingSource, + ~strategy, +) diff --git a/tests/MediaCaptureAndStreamsAPI/MediaStream__test.res b/tests/MediaCaptureAndStreamsAPI/MediaStream__test.res new file mode 100644 index 0000000..00fd70d --- /dev/null +++ b/tests/MediaCaptureAndStreamsAPI/MediaStream__test.res @@ -0,0 +1,8 @@ +let mediaStream: WebApiMediaCaptureAndStreams.Types.mediaStream = Obj.magic() +let mediaStreamTrack: WebApiMediaCaptureAndStreams.Types.mediaStreamTrack = Obj.magic() + +let _make = WebApiMediaCaptureAndStreams.MediaStream.make() + +let _fromMediaStream = WebApiMediaCaptureAndStreams.MediaStream.fromMediaStream(mediaStream) + +let _fromTracks = WebApiMediaCaptureAndStreams.MediaStream.fromTracks([mediaStreamTrack]) diff --git a/tests/WebAudioAPI/OfflineAudioContext__test.res b/tests/WebAudioAPI/OfflineAudioContext__test.res new file mode 100644 index 0000000..e9f38c6 --- /dev/null +++ b/tests/WebAudioAPI/OfflineAudioContext__test.res @@ -0,0 +1,9 @@ +let offlineAudioContextOptions: WebApiWebAudio.Types.offlineAudioContextOptions = Obj.magic() + +let _fromOptions = WebApiWebAudio.OfflineAudioContext.fromOptions(offlineAudioContextOptions) + +let _fromChannelCountLengthAndSampleRate = WebApiWebAudio.OfflineAudioContext.fromChannelCountLengthAndSampleRate( + ~numberOfChannels=2, + ~length=1024, + ~sampleRate=44_100., +) diff --git a/tests/WebSocketsAPI/WebSocket__test.res b/tests/WebSocketsAPI/WebSocket__test.res new file mode 100644 index 0000000..03bcbdf --- /dev/null +++ b/tests/WebSocketsAPI/WebSocket__test.res @@ -0,0 +1,6 @@ +let _fromURL = WebApiWebSockets.WebSocket.fromURL(~url="wss://example.com/socket") + +let _fromURLWithProtocols = WebApiWebSockets.WebSocket.fromURLWithProtocols( + ~url="wss://example.com/socket", + ~protocols=["chat", "superchat"], +)