feat: declare fetch override support symbol on class

Author: rexxars

README.md

@@ -153,12 +153,12 @@ Use a package like [`undici`](https://github.com/nodejs/undici) that supports HT
 
 ```ts
 // npm install undici --save
-import {Agent, fetch} from "undici";
+import {Agent, fetch} from 'undici'
 
 const http2Dispatcher = new Agent({allowH2: true})
 
 const es = new EventSource('https://my-server.com/sse', {
-  fetch: (url, init) => fetch(url, { ...init, dispatcher: http2Dispatcher })
+  fetch: (url, init) => fetch(url, {...init, dispatcher: http2Dispatcher}),
 })
 ```
 
@@ -181,6 +181,31 @@ await fetch('https://my-server.com/sse', {
 })
 ```
 
+#### Feature checking
+
+For library authors, you may want to feature-check if an EventSource implementation supports passing a custom `fetch` implementation (such as this library does). We declare (from 4.1.0 and onwards) a non-enumerable symbol on the EventSource class to indicate this, named `eventsource.supports-fetch-override`. It can be used downstream such as:
+
+```ts
+function yourLibrary(options) {
+  const OurEventSource = options.polyfills.EventSource || globalThis.EventSource
+
+  if (OurEventSource && Symbol.for('eventsource.supports-fetch-override') in OurEventSource) {
+    // We can safely assume this supports overriding/specifying `fetch`!
+    const es = new OurEventSource('https://some.url', {
+      fetch: (input, init) =>
+        fetch(input, {
+          ...init,
+          headers: {
+            ...(init.headers || {}),
+            'x-some-header': 'foo',
+          },
+        }),
+    })
+    // …
+  }
+}
+```
+
 ## License
 
 MIT-licensed. See [LICENSE](LICENSE).

src/EventSource.ts

@@ -577,6 +577,15 @@ export class EventSource extends EventTarget {
   }
 }
 
+// Provides a way to detect that the EventSource implementation supports passing `fetch`
+// that can be used to customize the request, eg custom headers and similar.
+Object.defineProperty(EventSource, Symbol.for('eventsource.supports-fetch-override'), {
+  value: true,
+  writable: false,
+  configurable: false,
+  enumerable: false,
+})
+
 /**
  * According to spec, when constructing a URL:
  * > 1. Let baseURL be environment's base URL, if environment is a Document object

test/tests.ts

@@ -768,5 +768,12 @@ export function registerTests(options: {
     await deferClose(es)
   })
 
+  test('has non-enumarable `eventsource.supports-fetch-override` symbol', async () => {
+    const supportsFetchOverride = Symbol.for('eventsource.supports-fetch-override')
+    expect(Object.getOwnPropertySymbols(OurEventSource).includes(supportsFetchOverride)).toBe(true)
+    expect(Object.keys(OurEventSource).includes('supports-fetch-override')).toBe(false)
+    expect(Symbol.for('eventsource.supports-fetch-override') in OurEventSource)
+  })
+
   return runner
 }