export WebSocketStream, add docs and types (#3645)

docs/docs/api/WebSocket.md

@@ -1,7 +1,5 @@
 # Class: WebSocket
 
-> ⚠️ Warning: the WebSocket API is experimental.
-
 Extends: [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
 
 The WebSocket object provides a way to manage a WebSocket connection to a server, allowing bidirectional communication. The API follows the [WebSocket spec](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) and [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455).
@@ -10,7 +8,7 @@ The WebSocket object provides a way to manage a WebSocket connection to a server
 
 Arguments:
 
-* **url** `URL | string` - The url's protocol *must* be `ws` or `wss`.
+* **url** `URL | string`
 * **protocol** `string | string[] | WebSocketInit` (optional) - Subprotocol(s) to request the server use, or a [`Dispatcher`](./Dispatcher.md).
 
 ### Example:
@@ -36,6 +34,50 @@ import { WebSocket } from 'undici'
 const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
 ```
 
+# Class: WebSocketStream
+
+> ⚠️ Warning: the WebSocketStream API has not been finalized and is likely to change.
+
+See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocketStream) for more information.
+
+## `new WebSocketStream(url[, protocol])`
+
+Arguments:
+
+* **url** `URL | string`
+* **options** `WebSocketStreamOptions` (optional)
+
+### WebSocketStream Example
+
+```js
+const stream = new WebSocketStream('https://echo.websocket.org/')
+const { readable, writable } = await stream.opened
+
+async function read () {
+  /** @type {ReadableStreamReader} */
+  const reader = readable.getReader()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+
+    // do something with value
+  }
+}
+
+async function write () {
+  /** @type {WritableStreamDefaultWriter} */
+  const writer = writable.getWriter()
+  writer.write('Hello, world!')
+  writer.releaseLock()
+}
+
+read()
+
+setInterval(() => write(), 5000)
+
+```
+
 ## Read More
 
 - [MDN - WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)

index.js

@@ -148,6 +148,9 @@ module.exports.CloseEvent = CloseEvent
 module.exports.ErrorEvent = ErrorEvent
 module.exports.MessageEvent = MessageEvent
 
+module.exports.WebSocketStream = require('./lib/web/websocket/stream/websocketstream').WebSocketStream
+module.exports.WebSocketError = require('./lib/web/websocket/stream/websocketerror').WebSocketError
+
 module.exports.request = makeDispatcher(api.request)
 module.exports.stream = makeDispatcher(api.stream)
 module.exports.pipeline = makeDispatcher(api.pipeline)

test/wpt/runner/worker.mjs

@@ -14,15 +14,14 @@ import {
   CloseEvent,
   WebSocket,
   caches,
-  EventSource
+  EventSource,
+  WebSocketStream,
+  WebSocketError
 } from '../../../index.js'
 // TODO(@KhafraDev): export these in index.js
 import { Cache } from '../../../lib/web/cache/cache.js'
 import { CacheStorage } from '../../../lib/web/cache/cachestorage.js'
 import { webcrypto } from 'node:crypto'
-// TODO(@KhafraDev): move this import once its added to index
-import { WebSocketStream } from '../../../lib/web/websocket/stream/websocketstream.js'
-import { WebSocketError } from '../../../lib/web/websocket/stream/websocketerror.js'
 
 const { initScripts, meta, test, url, path } = workerData
 

types/websocket.d.ts

@@ -148,3 +148,36 @@ interface WebSocketInit {
   dispatcher?: Dispatcher,
   headers?: HeadersInit
 }
+
+interface WebSocketStreamOptions {
+  protocols?: string | string[]
+  signal?: AbortSignal
+}
+
+interface WebSocketCloseInfo {
+  closeCode: number
+  reason: string
+}
+
+interface WebSocketStream {
+  closed: Promise<WebSocketCloseInfo>
+  opened: Promise<{
+    extensions: string
+    protocol: string
+    readable: ReadableStream
+    writable: WritableStream
+  }>
+  url: string
+}
+
+export declare const WebSocketStream: {
+  prototype: WebSocketStream
+  new (url: string | URL, options?: WebSocketStreamOptions): WebSocketStream
+}
+
+interface WebSocketError extends Event, WebSocketCloseInfo {}
+
+export declare const WebSocketError: {
+  prototype: WebSocketError
+  new (type: string, init?: WebSocketCloseInfo): WebSocketError
+}