@noodleseed/one 0.22.0 → 0.23.0

package/node_modules/undici/docs/docs/api/EventSource.md

@@ -1,14 +1,15 @@
 # EventSource
 
-> ⚠️ Warning: the EventSource API is experimental.
+<!--introduced_in=v6.5.0-->
+<!--type=module-->
+<!-- source_link=lib/web/eventsource/eventsource.js -->
 
-Undici exposes a WHATWG spec-compliant implementation of [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
-for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
+> Stability: 1 - Experimental
 
-## Instantiating EventSource
-
-Undici exports an EventSource class. You can instantiate the EventSource as
-follows:
+`EventSource` is a [WHATWG-conformant][] implementation of the
+[server-sent events][] interface. It opens a persistent HTTP connection to a
+server that responds with the `text/event-stream` content type and dispatches
+the events it receives without closing the connection.
 
 ```mjs
 import { EventSource } from 'undici'
@@ -19,11 +20,266 @@ eventSource.onmessage = (event) => {
 }
 ```
 
-## Receiving events from a server
+Constructing an `EventSource` for the first time emits a one-time
+`ExperimentalWarning` with the code `'UNDICI-ES'`. The interface is also
+installed onto `globalThis` as `globalThis.EventSource`.
+
+## Class: `EventSource`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Extends: {EventTarget}
+
+The `EventSource` interface receives server-sent events over an HTTP
+connection. Instances are created with the [`new EventSource()`](#new-eventsourceurl-eventsourceinitdict)
+constructor and emit [`'open'`](#event-open), [`'message'`](#event-message), and
+[`'error'`](#event-error) events.
+
+### `new EventSource(url[, eventSourceInitDict])`
+
+<!-- YAML
+added: v6.5.0
+-->
 
-EventSource connects to an HTTP endpoint that responds with a `text/event-stream`
-content type. The connection stays open and receives events as the server writes
-them.
+> Stability: 1 - Experimental
+
+* `url` {string|URL} The URL of the event stream. Relative URLs are resolved
+  against the environment's base URL.
+* `eventSourceInitDict` {Object} (optional)
+  * `withCredentials` {boolean} When `true`, the request is made with the
+    credentials mode set to `include` and CORS attribute state set to
+    `use-credentials`; otherwise the credentials mode is `same-origin`.
+    **Default:** `false`.
+  * `dispatcher` {Dispatcher} The dispatcher used for the underlying request.
+    **Default:** the global dispatcher.
+
+    > Stability: 0 - Deprecated. Use `node.dispatcher` instead.
+  * `node` {Object} undici-specific extensions to the standard
+    `EventSourceInit` dictionary.
+    * `dispatcher` {Dispatcher} The dispatcher used for the underlying request.
+      **Default:** the global dispatcher.
+    * `reconnectionTime` {number} The reconnection time, in milliseconds, to
+      wait before re-establishing a dropped connection. The server may override
+      this value with a `retry` field. **Default:** `3000`.
+
+Creates a new `EventSource` and immediately begins connecting to `url`. The
+request is sent with the `Accept: text/event-stream` header, a cache mode of
+`no-store`, and an initiator type of `other`.
+
+If `url` cannot be parsed, a `SyntaxError` `DOMException` is thrown.
+
+```mjs
+import { EventSource } from 'undici'
+
+const eventSource = new EventSource('http://localhost:3000', {
+  withCredentials: true
+})
+```
+
+A custom [`Dispatcher`][] can be supplied to control the underlying request, for
+example to add request headers:
+
+```mjs
+import { EventSource, Agent } from 'undici'
+
+class CustomHeaderAgent extends Agent {
+  dispatch (opts) {
+    opts.headers['x-custom-header'] = 'hello world'
+    return super.dispatch(...arguments)
+  }
+}
+
+const eventSource = new EventSource('http://localhost:3000', {
+  node: {
+    dispatcher: new CustomHeaderAgent()
+  }
+})
+```
+
+### `eventSource.close()`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Returns: {undefined}
+
+Closes the connection, if any, aborts the underlying request, and sets
+[`eventSource.readyState`](#eventsourcereadystate) to `CLOSED`. Once closed, the
+`EventSource` does not attempt to reconnect. Calling `close()` on an already
+closed `EventSource` has no effect.
+
+### `eventSource.readyState`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+A read-only number representing the state of the connection. It is one of the
+following constants:
+
+* [`EventSource.CONNECTING`](#eventsourceconnecting) (`0`) — the connection has
+  not yet been established, or it was closed and is being re-established.
+* [`EventSource.OPEN`](#eventsourceopen) (`1`) — the connection is open and
+  events are being dispatched as they are received.
+* [`EventSource.CLOSED`](#eventsourceclosed) (`2`) — the connection is not open
+  and is not being re-established.
+
+### `eventSource.url`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {string}
+
+A read-only string providing the URL of the event stream, after resolution
+against the environment's base URL.
+
+### `eventSource.withCredentials`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {boolean}
+
+A read-only boolean indicating whether the `EventSource` was instantiated with
+CORS credentials (`true`), or not (`false`, the default). It reflects the
+`withCredentials` option passed to the constructor.
+
+### `eventSource.onopen`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler that is invoked when an [`'open'`](#event-open) event is
+dispatched. Assigning a function registers it as the handler; assigning `null`
+removes the current handler.
+
+### `eventSource.onmessage`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler that is invoked when a [`'message'`](#event-message) event is
+dispatched. Assigning a function registers it as the handler; assigning `null`
+removes the current handler.
+
+### `eventSource.onerror`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler that is invoked when an [`'error'`](#event-error) event is
+dispatched. Assigning a function registers it as the handler; assigning `null`
+removes the current handler.
+
+### `EventSource.CONNECTING`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+The numeric constant `0`, representing the `CONNECTING`
+[`readyState`](#eventsourcereadystate). It is defined as a read-only,
+non-writable property on both the `EventSource` constructor and instances.
+
+### `EventSource.OPEN`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+The numeric constant `1`, representing the `OPEN`
+[`readyState`](#eventsourcereadystate). It is defined as a read-only,
+non-writable property on both the `EventSource` constructor and instances.
+
+### `EventSource.CLOSED`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number}
+
+The numeric constant `2`, representing the `CLOSED`
+[`readyState`](#eventsourcereadystate). It is defined as a read-only,
+non-writable property on both the `EventSource` constructor and instances.
+
+### Event: `'open'`
+
+<!-- YAML
+added: v6.5.0
+-->
+
+> Stability: 1 - Experimental
+
+Emitted when the connection is established and the
+[`readyState`](#eventsourcereadystate) becomes `OPEN`. The listener receives an
+{Event}.
+
+```mjs
+import { EventSource } from 'undici'
+
+const eventSource = new EventSource('http://localhost:3000')
+eventSource.addEventListener('open', () => {
+  console.log('connection opened')
+})
+```
+
+### Event: `'message'`
+
+<!-- YAML
+added: v6.15.0
+-->
+
+> Stability: 1 - Experimental
+
+Emitted when a message that has no explicit `event` field is received. The
+listener receives a {MessageEvent} whose `data`, `lastEventId`, and `origin`
+properties are populated from the server-sent event. Named events (those with an
+`event` field) are dispatched under their own type and must be subscribed to with
+[`addEventListener()`][].
 
 ```mjs
 import { createServer } from 'node:http'
@@ -49,44 +305,50 @@ const server = createServer((request, response) => {
 server.listen(3000, () => {
   const eventSource = new EventSource('http://localhost:3000')
 
+  // Named event, delivered under its own type.
   eventSource.addEventListener('ping', (event) => {
     console.log('ping:', event.data)
   })
 
+  // Unnamed event, delivered as 'message'.
   eventSource.onmessage = (event) => {
     console.log('message:', event.data)
   }
-
-  eventSource.onerror = () => {
-    eventSource.close()
-    server.close()
-  }
 })
 ```
 
-The `message` event receives events without an explicit `event:` field. Use
-`addEventListener()` to subscribe to named events.
+### Event: `'error'`
 
-## Using a custom Dispatcher
+<!-- YAML
+added: v6.5.0
+changes:
+  - version: v7.11.0
+    pr-url: https://github.com/nodejs/undici/pull/4247
+    description: The connection is no longer re-established after a network
+                 error; the `EventSource` is closed instead.
+-->
 
-Undici allows you to set your own Dispatcher in the EventSource constructor.
+> Stability: 1 - Experimental
 
-An example which allows you to modify the request headers is:
+Emitted when the connection fails or is interrupted. The listener receives an
+{Event}. When the failure is recoverable, the `EventSource` transitions back to
+`CONNECTING` and retries after the reconnection time; when it is not, the
+`EventSource` transitions to `CLOSED` and does not reconnect.
 
 ```mjs
-import { EventSource, Agent } from 'undici'
+import { EventSource } from 'undici'
 
-class CustomHeaderAgent extends Agent {
-  dispatch (opts) {
-    opts.headers['x-custom-header'] = 'hello world'
-    return super.dispatch(...arguments)
+const eventSource = new EventSource('http://localhost:3000')
+eventSource.onerror = () => {
+  if (eventSource.readyState === EventSource.CLOSED) {
+    console.log('connection closed')
+  } else {
+    console.log('reconnecting')
   }
 }
-
-const eventSource = new EventSource('http://localhost:3000', {
-  dispatcher: new CustomHeaderAgent()
-})
 ```
 
-More information about the EventSource API can be found on
-[MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
+[WHATWG-conformant]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`addEventListener()`]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+[server-sent events]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events