Revise all postMessage methods

Fixes #238

Author: japgolly

api-reports/2_12.txt

@@ -1195,7 +1195,7 @@ DedicatedWorkerGlobalScope[JT] var onmessage: js.Function1[MessageEvent, _]
 DedicatedWorkerGlobalScope[JT] var onoffline: js.Function1[Event, _]
 DedicatedWorkerGlobalScope[JT] var ononline: js.Function1[Event, _]
 DedicatedWorkerGlobalScope[JT] def origin: String
-DedicatedWorkerGlobalScope[JT] def postMessage(aMessage: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
+DedicatedWorkerGlobalScope[JT] def postMessage(message: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
 DedicatedWorkerGlobalScope[JT] def queueMicrotask(function: js.Function0[Any]): Unit
 DedicatedWorkerGlobalScope[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 DedicatedWorkerGlobalScope[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
@@ -13964,7 +13964,7 @@ MessagePort[JT] def addEventListener[T <: Event](`type`: String, listener: js.Fu
 MessagePort[JT] def close(): Unit
 MessagePort[JT] def dispatchEvent(evt: Event): Boolean
 MessagePort[JT] var onmessage: js.Function1[MessageEvent, _]
-MessagePort[JT] def postMessage(message: js.Any, ports: js.Any?): Unit
+MessagePort[JT] def postMessage(message: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
 MessagePort[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 MessagePort[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 MessagePort[JT] def start(): Unit
@@ -23309,7 +23309,7 @@ Window[JC] def pageXOffset: Double
 Window[JC] def pageYOffset: Double
 Window[JC] def parent: Window
 Window[JC] def performance: Performance
-Window[JC] def postMessage(message: js.Any, targetOrigin: String, transfer: js.Any?): Unit
+Window[JC] def postMessage(message: js.Any, targetOrigin: String, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 Window[JC] def print(): Unit
 Window[JC] def prompt(): String
 Window[JC] def prompt(message: String, default: String?): String
@@ -23367,7 +23367,7 @@ Worker[JC] def addEventListener[T <: Event](`type`: String, listener: js.Functio
 Worker[JC] def dispatchEvent(evt: Event): Boolean
 Worker[JC] var onerror: js.Function1[ErrorEvent, _]
 Worker[JC] var onmessage: js.Function1[MessageEvent, _]
-Worker[JC] def postMessage(aMessage: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
+Worker[JC] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 Worker[JC] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 Worker[JC] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 Worker[JC] def terminate(): Unit
@@ -24309,7 +24309,7 @@ experimental/serviceworkers/CacheStorage[JT] def open(cacheName: String): js.Pro
 experimental/serviceworkers/CanvasProxy[JT] def setContext(context: RenderingContext): Unit
 experimental/serviceworkers/Client[JT] def frameType: FrameType
 experimental/serviceworkers/Client[JT] def id: String
-experimental/serviceworkers/Client[JT] def postMessage(message: Any, transfer: Sequence[Transferable] = null): Unit
+experimental/serviceworkers/Client[JT] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 experimental/serviceworkers/Client[JT] def url: String
 experimental/serviceworkers/ClientQueryOptions[JT] var includeUncontrolled: Boolean
 experimental/serviceworkers/ClientQueryOptions[JT] var `type`: ClientType
@@ -24406,7 +24406,7 @@ experimental/serviceworkers/ServiceWorker[JT] def addEventListener[T <: Event](`
 experimental/serviceworkers/ServiceWorker[JT] def addEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 experimental/serviceworkers/ServiceWorker[JT] def dispatchEvent(evt: Event): Boolean
 experimental/serviceworkers/ServiceWorker[JT] var onstatechange: js.Function1[Event, _]
-experimental/serviceworkers/ServiceWorker[JT] def postMessage(message: js.Any, transfer: js.Array[Transferable]?): Unit
+experimental/serviceworkers/ServiceWorker[JT] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 experimental/serviceworkers/ServiceWorker[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 experimental/serviceworkers/ServiceWorker[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 experimental/serviceworkers/ServiceWorker[JT] def scriptURL: String
@@ -24496,7 +24496,7 @@ experimental/serviceworkers/WindowClient[JT] def focused: Boolean
 experimental/serviceworkers/WindowClient[JT] def frameType: FrameType
 experimental/serviceworkers/WindowClient[JT] def id: String
 experimental/serviceworkers/WindowClient[JT] def navigate(url: String): js.Promise[WindowClient]
-experimental/serviceworkers/WindowClient[JT] def postMessage(message: Any, transfer: Sequence[Transferable] = null): Unit
+experimental/serviceworkers/WindowClient[JT] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 experimental/serviceworkers/WindowClient[JT] def url: String
 experimental/serviceworkers/WindowClient[JT] def visibilityState: String
 experimental/serviceworkers/package[SO] type Transferable = org.scalajs.dom.Transferable | CanvasProxy

api-reports/2_13.txt

@@ -1195,7 +1195,7 @@ DedicatedWorkerGlobalScope[JT] var onmessage: js.Function1[MessageEvent, _]
 DedicatedWorkerGlobalScope[JT] var onoffline: js.Function1[Event, _]
 DedicatedWorkerGlobalScope[JT] var ononline: js.Function1[Event, _]
 DedicatedWorkerGlobalScope[JT] def origin: String
-DedicatedWorkerGlobalScope[JT] def postMessage(aMessage: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
+DedicatedWorkerGlobalScope[JT] def postMessage(message: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
 DedicatedWorkerGlobalScope[JT] def queueMicrotask(function: js.Function0[Any]): Unit
 DedicatedWorkerGlobalScope[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 DedicatedWorkerGlobalScope[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
@@ -13964,7 +13964,7 @@ MessagePort[JT] def addEventListener[T <: Event](`type`: String, listener: js.Fu
 MessagePort[JT] def close(): Unit
 MessagePort[JT] def dispatchEvent(evt: Event): Boolean
 MessagePort[JT] var onmessage: js.Function1[MessageEvent, _]
-MessagePort[JT] def postMessage(message: js.Any, ports: js.Any?): Unit
+MessagePort[JT] def postMessage(message: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
 MessagePort[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 MessagePort[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 MessagePort[JT] def start(): Unit
@@ -23309,7 +23309,7 @@ Window[JC] def pageXOffset: Double
 Window[JC] def pageYOffset: Double
 Window[JC] def parent: Window
 Window[JC] def performance: Performance
-Window[JC] def postMessage(message: js.Any, targetOrigin: String, transfer: js.Any?): Unit
+Window[JC] def postMessage(message: js.Any, targetOrigin: String, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 Window[JC] def print(): Unit
 Window[JC] def prompt(): String
 Window[JC] def prompt(message: String, default: String?): String
@@ -23367,7 +23367,7 @@ Worker[JC] def addEventListener[T <: Event](`type`: String, listener: js.Functio
 Worker[JC] def dispatchEvent(evt: Event): Boolean
 Worker[JC] var onerror: js.Function1[ErrorEvent, _]
 Worker[JC] var onmessage: js.Function1[MessageEvent, _]
-Worker[JC] def postMessage(aMessage: js.Any, transferList: js.UndefOr[js.Array[Transferable]]?): Unit
+Worker[JC] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 Worker[JC] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 Worker[JC] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 Worker[JC] def terminate(): Unit
@@ -24309,7 +24309,7 @@ experimental/serviceworkers/CacheStorage[JT] def open(cacheName: String): js.Pro
 experimental/serviceworkers/CanvasProxy[JT] def setContext(context: RenderingContext): Unit
 experimental/serviceworkers/Client[JT] def frameType: FrameType
 experimental/serviceworkers/Client[JT] def id: String
-experimental/serviceworkers/Client[JT] def postMessage(message: Any, transfer: Sequence[Transferable] = null): Unit
+experimental/serviceworkers/Client[JT] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 experimental/serviceworkers/Client[JT] def url: String
 experimental/serviceworkers/ClientQueryOptions[JT] var includeUncontrolled: Boolean
 experimental/serviceworkers/ClientQueryOptions[JT] var `type`: ClientType
@@ -24406,7 +24406,7 @@ experimental/serviceworkers/ServiceWorker[JT] def addEventListener[T <: Event](`
 experimental/serviceworkers/ServiceWorker[JT] def addEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 experimental/serviceworkers/ServiceWorker[JT] def dispatchEvent(evt: Event): Boolean
 experimental/serviceworkers/ServiceWorker[JT] var onstatechange: js.Function1[Event, _]
-experimental/serviceworkers/ServiceWorker[JT] def postMessage(message: js.Any, transfer: js.Array[Transferable]?): Unit
+experimental/serviceworkers/ServiceWorker[JT] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 experimental/serviceworkers/ServiceWorker[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], options: EventListenerOptions): Unit
 experimental/serviceworkers/ServiceWorker[JT] def removeEventListener[T <: Event](`type`: String, listener: js.Function1[T, _], useCapture: Boolean?): Unit
 experimental/serviceworkers/ServiceWorker[JT] def scriptURL: String
@@ -24496,7 +24496,7 @@ experimental/serviceworkers/WindowClient[JT] def focused: Boolean
 experimental/serviceworkers/WindowClient[JT] def frameType: FrameType
 experimental/serviceworkers/WindowClient[JT] def id: String
 experimental/serviceworkers/WindowClient[JT] def navigate(url: String): js.Promise[WindowClient]
-experimental/serviceworkers/WindowClient[JT] def postMessage(message: Any, transfer: Sequence[Transferable] = null): Unit
+experimental/serviceworkers/WindowClient[JT] def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]]?): Unit
 experimental/serviceworkers/WindowClient[JT] def url: String
 experimental/serviceworkers/WindowClient[JT] def visibilityState: String
 experimental/serviceworkers/package[SO] type Transferable = org.scalajs.dom.Transferable | CanvasProxy

src/main/scala/org/scalajs/dom/WebWorkerTypes.scala

@@ -40,19 +40,20 @@ class Worker(stringUrl: String) extends AbstractWorker {
     * The Worker can send back information to the thread that spawned it using the
     * DedicatedWorkerGlobalScope.postMessage method.
     *
-    * @param aMessage
+    * @param message
     *   The object to deliver to the worker; this will be in the data field in the event delivered to the
     *   DedicatedWorkerGlobalScope.onmessage handler. This may be any value or JavaScript object handled by the
     *   structured clone algorithm, which includes cyclical references.
     *
-    * @param transferList
+    * @param transfer
     *   An optional array of Transferable objects to transfer ownership of. If the ownership of an object is
-    *   transferred, it becomes unusable (neutered) in the context it was sent from and it becomes available only to the
-    *   main thread it was sent to.
+    *   transferred, it becomes unusable in the context it was sent from and becomes available only to the worker it was
+    *   sent to.
     *
-    * Only MessagePort and ArrayBuffer objects can be transferred. null is not an acceptable value for the transferList.
+    * Transferable objects are instances of classes like ArrayBuffer, MessagePort or ImageBitmap objects that can be
+    * transferred. null is not an acceptable value for transfer.
     */
-  def postMessage(aMessage: js.Any, transferList: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
+  def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
 
   /** The Worker.terminate() method immediately terminates the Worker. This does not offer the worker an opportunity to
     * finish its operations; it is simply stopped at once.
@@ -139,16 +140,18 @@ trait DedicatedWorkerGlobalScope extends WorkerGlobalScope {
     * The main scope that spawned the worker can send back information to the thread that spawned it using the
     * Worker.postMessage method.
     *
-    * @param aMessage
+    * @param message
     *   The object to deliver to the main thread; this will be in the data field in the event delivered to the
     *   Worker.onmessage handler. This may be any value or JavaScript object handled by the structured clone algorithm,
     *   which includes cyclical references.
     * @param transferList
     *   An optional array of Transferable objects to transfer ownership of. If the ownership of an object is
-    *   transferred, it becomes unusable (neutered) in the context it was sent from and it becomes available only to the
-    *   main thread it was sent to.
+    *   transferred, it becomes unusable in the context it was sent from and it becomes available only to the main
+    *   thread it was sent to.
+    *
+    * Only MessagePort and ArrayBuffer objects can be transferred.
     */
-  def postMessage(aMessage: js.Any, transferList: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
+  def postMessage(message: js.Any, transferList: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
 }
 
 @js.native

src/main/scala/org/scalajs/dom/experimental/serviceworkers/ServiceWorkers.scala

@@ -40,12 +40,14 @@ trait Client extends js.Object {
   /** The id attribute must return its associated service worker client's id. */
   def id: String = js.native
 
-  /** @param message
-    *   the spec says this is of type any (?!)
+  /** Allows a service worker to send a message to a client (a Window, Worker, or SharedWorker). The message is received
+    * in the "message" event on navigator.serviceWorker.
+    *
     * @param transfer
-    *   https://html.spec.whatwg.org/multipage/infrastructure.html#transferable-objects
+    *   A sequence of objects that are transferred with the message. The ownership of these objects is given to the
+    *   destination side and they are no longer usable on the sending side.
     */
-  def postMessage(message: Any, transfer: Sequence[Transferable] = null): Unit = js.native
+  def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
 }
 
 /** see [[https://html.spec.whatwg.org/multipage/scripting.html#canvasproxy ¶4.12.4.1 Proxying canvases to workers]] in
@@ -119,15 +121,16 @@ trait ServiceWorker extends EventTarget {
     */
   def state: String = js.native
 
-  /** An EventListener property called whenever an event of type statechange is fired; it is basically fired anytime the
-    * ServiceWorker.state changes.
+  /** @param transfer
+    *   A sequence of objects that are transferred with the message. The ownership of these objects is given to the
+    *   destination side and they are no longer usable on the sending side.
     */
   var onstatechange: js.Function1[Event, _] = js.native
 
   /** [[https://slightlyoff.github.io/ServiceWorker/spec/service_worker_1/#service-worker-postmessage ¶3.1.3 postMessage]]
     * on whatwg ServiceWorker spec.
     */
-  def postMessage(message: js.Any, transfer: js.Array[Transferable] = js.native): Unit = js.native
+  def postMessage(message: js.Any, transfer: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
 }
 
 /** The ServiceWorkerRegistion interface of the ServiceWorker API represents the service worker registration. You

src/main/scala/org/scalajs/dom/lib.scala

@@ -1529,13 +1529,35 @@ class Window
 
   def closed: Boolean = js.native
 
-  /** The window.postMessage method safely enables cross-origin communication. Normally, scripts on different pages are
-    * allowed to access each other if and only if the pages that executed them are at locations with the same protocol
-    * (usually both http), port number (80 being the default for http), and host (modulo document.domain being set by
-    * both pages to the same value). window.postMessage provides a controlled mechanism to circumvent this restriction
-    * in a way which is secure when properly used.
+  /** Safely enables cross-origin communication between Window objects; e.g., between a page and a pop-up that it
+    * spawned, or between a page and an iframe embedded within it.
+    *
+    * Normally, scripts on different pages are allowed to access each other if and only if the pages they originate from
+    * share the same protocol, port number, and host (also known as the "same-origin policy"). window.postMessage()
+    * provides a controlled mechanism to securely circumvent this restriction (if used properly).
+    *
+    * Broadly, one window may obtain a reference to another (e.g., via targetWindow = window.opener), and then dispatch
+    * a MessageEvent on it with targetWindow.postMessage(). The receiving window is then free to handle this event as
+    * needed. The arguments passed to window.postMessage() (i.e., the “message”) are exposed to the receiving window
+    * through the event object.
+    *
+    * @param targetOrigin
+    *   Specifies what the origin of targetWindow must be for the event to be dispatched, either as the literal string
+    *   "*" (indicating no preference) or as a URI. If at the time the event is scheduled to be dispatched the scheme,
+    *   hostname, or port of targetWindow's document does not match that provided in targetOrigin, the event will not be
+    *   dispatched; only if all three match will the event be dispatched. This mechanism provides control over where
+    *   messages are sent; for example, if postMessage() was used to transmit a password, it would be absolutely
+    *   critical that this argument be a URI whose origin is the same as the intended receiver of the message containing
+    *   the password, to prevent interception of the password by a malicious third party. Always provide a specific
+    *   targetOrigin, not *, if you know where the other window's document should be located. Failing to provide a
+    *   specific target discloses the data you send to any interested malicious site.
+    *
+    * @param transfer
+    *   A sequence of objects that are transferred with the message. The ownership of these objects is given to the
+    *   destination side and they are no longer usable on the sending side.
     */
-  def postMessage(message: js.Any, targetOrigin: String, transfer: js.Any = js.native): Unit = js.native
+  def postMessage(message: js.Any, targetOrigin: String,
+      transfer: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
 
   /** The Window.showModalDialog() creates and displays a modal dialog box containing a specified HTML document.
     *
@@ -4734,12 +4756,12 @@ trait MessagePort extends EventTarget {
   def close(): Unit = js.native
 
   /** Sends a message from the port, and optionally, transfers ownership of objects to other browsing contexts.
-    * @param message
-    *   The message you want to send through the channel. This can be of any basic data type. Multiple data items can be
-    *   sent as an array.
-    * @param ports
+    *
+    * @param transferList
+    *   Transferable objects to be transferred — these objects have their ownership transferred to the receiving
+    *   browsing context, so are no longer usable by the sending browsing context.
     */
-  def postMessage(message: js.Any, ports: js.Any = js.native): Unit = js.native
+  def postMessage(message: js.Any, transferList: js.UndefOr[js.Array[Transferable]] = js.native): Unit = js.native
 
   def start(): Unit = js.native
 }