Stop polyfilling existing globals

[kettanaito]

Basic info:

• Node.js version: v18+
• jsdom version: any JSDOM version

Issue

JSDOM is polyfilling a bunch of already existing global APIs, which leads to all sorts of issues when the underlying code expects those APIs to be actual.

All the issues I'm describing are transient. They are likely not reproducible in an isolated JSDOM environment since JSDOM creates an illusion of "globals" working instead of actually relying on the environment's globals that already exist.

While JSDOM aims to emulate the browser, most of my (and others') pain of working with JSDOM rises from it ignoring that it's still being run in Node.js. It must respect Node.js globals to create a functional, complete environment.

Example 1: AbortSignal doesn't extend EventTarget

• See fix(fetch): raise AbortSignal max event listeners nodejs/undici#1910 (comment)

import { implementation as AbortSignal } from 'jsdom/lib/jsdom/living/aborting/AbortSignal-impl'

it('AbortSignal extends EventTarget', () => {
  expect(AbortSignal instanceof EventTarget).toBe(true)
})

Root cause: JSDOM extends its own EventTarget implementation. This is incorrect and harmful. No child classes of the custom EventTargetImpl in JSDOM will be treated as valid events in Node.js. It will throw right here, among other places:

• https://github.com/nodejs/node/blob/544cfc5ef151bca8d625fbccc581200a77b00bc0/lib/events.js#L943

Example 2: Custom Event

JSDOM implements a custom EventImpl instead of relying on the global Event class. No derives events will be considered valid events by Node.js.

Example: try dispatching an Event on an EventTarget instance.

import { implementation as Event } from 'jsdom/lib/jsdom/living/events/Event-impl'
// Valid global EventTarget in Node.js
const target = new EventTarget()

target.dispatchEvent(new Event('hello'))

This will throw right over here in Node.js:

• https://github.com/nodejs/node/blob/544cfc5ef151bca8d625fbccc581200a77b00bc0/lib/internal/event_target.js#L751

Because custom Event implementation from JSDOM is not a valid Event in Node.js.

Minimal reproduction case

I've provided two reproduction cases above. Please see those. I can submit a test suite that fails with JSDOM due to it not respecting Node.js globals.

How does similar code behave in browsers?

Both browsers and Node.js correctly rely on and execute global functions. I expect JSDOM not to rob me of those either.

[kettanaito]

Please consider removing custom implementations of things that already exist in Node.js. Those are harmful, and they are already causing real issues, and will cause more and more issues as Node.js aims to align itself with the browser APIs.

Instead, properly rely on the globals that implement the same specification in both the browser and Node.js. That includes Event and EventTarget just as two specific examples. This has to be adopted globally to prevent runtime incompatibilities, which are plentiful with JSDOM.

[domenic]

You seem to have misunderstood the purpose of the jsdom project.

[kettanaito]

@domenic, apologies if that's the case. I just see little value in polyfilling global APIs that exist in both the browser and Node.js. If only those polyfills weren't harmful in practice, wasting quite a bit of time on things that mustn't require time at all.

[stevenpollack]

You seem to have misunderstood the purpose of the jsdom project.

Asking for a friend: what is the purpose of this project, again?

[lennerd]

So JSdom really has no way to disable some of the polyfills to use the ones in Node? This makes some tests very difficualt or even impossible to write.

[victorhahncastell]

I agree with the reporter that this behaviour is unexpected and makes life hell in testing -- which is obviously a major use case of JSDOM and usually performed using NodeJS.

The fact that JSDOM's Buffers are neither compatible with NodeJS' nor even based on Uint8Array basically means I need to introduce extra code just to ensure that JSDOM's strange Buffers never sneak into my objects.

[badams-atlas]

Hey @kettanaito

How did you work a round this issue? I'm running into a similar problem.

TypeError: The "event" argument must be an instance of Event. Received an instance of MessageEvent

Note: I'm using vitest rather than jest.

[kettanaito]

@badams-atlas I stopped using jsdom and tested that functionality in a Node.js environment instead. You can also test it in the real browser, using tools like Vitest Browser Mode.

[schwartzadev]

How did you work a round this issue? I'm running into a similar problem.

TypeError: The "event" argument must be an instance of Event. Received an instance of MessageEvent

Note: I'm using vitest rather than jest.

Are there any updates here? I'm seeing the same issue upon updating from node v18 to v22 and it looks like we're stuck on node v22.2.0 because of this issue.

Edit: we're also using vitest

[diego-aquino]

Are there any updates here? I'm seeing the same issue upon updating from node v18 to v22 and it looks like we're stuck on node v22.2.0 because of this issue.

Edit: we're also using vitest

@schwartzadev, I was stuck on this error as well and I ended up creating a BroadcastChannel mock to use in our tests, as I found no other solution.

This is the implementation I made (it runs in our vitest setup files). By no means this is a complete BroadcastChannel, but it meets our current test requirements. Extend at will.

tests/setup.ts

type BroadcastChannelListener = (event: MessageEvent<unknown>) => void

interface BroadcastChannelListenerWithChannel {
  channel: BroadcastChannelMock
  listener: BroadcastChannelListener
}

type BroadcastChannelListenersByType = Map<string, Set<BroadcastChannelListenerWithChannel>>

export class BroadcastChannelMock {
  private static listenersByNameAndType = new Map<string, BroadcastChannelListenersByType>()

  private isActive = true

  constructor(private name: string) {}

  private get listenersByType() {
    const listenersByType =
      BroadcastChannelMock.listenersByNameAndType.get(this.name) ??
      new Map<string, Set<BroadcastChannelListenerWithChannel>>()

    BroadcastChannelMock.listenersByNameAndType.set(this.name, listenersByType)

    return listenersByType
  }

  postMessage(data: unknown) {
    for (const [type, listeners] of this.listenersByType.entries()) {
      for (const { channel, listener } of listeners) {
        if (channel === this || !channel.isActive) {
          continue
        }

        const event = new MessageEvent(type, { data })
        listener(event)
      }
    }
  }

  addEventListener(event: string, listener: BroadcastChannelListener) {
    const listeners = this.listenersByType.get(event) ?? new Set()
    this.listenersByType.set(event, listeners)

    listeners.add({ channel: this, listener })
  }

  removeEventListener(event: string, listener: BroadcastChannelListener) {
    const listeners = this.listenersByType.get(event)

    for (const listenerWithChannel of listeners ?? []) {
      if (listenerWithChannel.listener === listener) {
        listeners?.delete(listenerWithChannel)
      }
    }
  }

  close() {
    this.isActive = false
  }

  static clear() {
    for (const listenersByType of this.listenersByNameAndType.values()) {
      for (const listeners of listenersByType.values()) {
        listeners.clear()
      }
      listenersByType.clear()
    }

    this.listenersByNameAndType.clear()
  }
}

globalThis.BroadcastChannel = BroadcastChannelMock as unknown as typeof BroadcastChannel

afterEach(() => {
  BroadcastChannelMock.clear()
})

[AndrewBogdanovTSS]

Can this issue be reopened as proper solution is not yet available?

[MarcMcIntosh]

Updated to node v24 and started getting this error when running tests

In the case of an unhandled error, no tags will be "provided" or "invalidated". TypeError: RequestInit: Expected signal ("AbortSignal {}") to be an instance of AbortSignal.
    at Object.webidl.errors.exception (node:internal/deps/undici/undici:4096:14)
    at Object.AbortSignal (node:internal/deps/undici/undici:4338:31)
    at node:internal/deps/undici/undici:10747:41
    at node:internal/deps/undici/undici:4389:16
    at Object.RequestInit (node:internal/deps/undici/undici:4371:21)
    at new Request (node:internal/deps/undici/undici:10111:34)
    at Object.construct (file:///home/runner/work/refact/refact/refact-agent/gui/node_modules/@mswjs/interceptors/src/interceptors/ClientRequest/utils/recordRawHeaders.ts:185:33)
    at file:///home/runner/work/refact/refact/refact-agent/gui/node_modules/@reduxjs/toolkit/src/query/fetchBaseQuery.ts:224:21
    at processTicksAndRejections (node:internal/process/task_queues:105:5)
    at Object.queryFn (/home/runner/work/refact/refact/refact-agent/gui/src/services/refact/ping.ts:15:26)

[Finesse]

This is what I have to do to prevent JSDOM from overwriting some APIs:

// init.js — the file set in `setupFilesAfterEnv` of `jest.config.js`

import { Buffer } from 'node:buffer';
import { webcrypto as crypto } from 'node:crypto';
import { CompressionStream, DecompressionStream } from 'node:stream/web';
import { TextDecoder, TextEncoder } from 'node:util';

// These APIs are available in the Node.js global scope, but JSDOM removes or breaks them, so we need to retrieve them
Object.assign(global, {
  TextEncoder,
  TextDecoder,
  CompressionStream,
  DecompressionStream,
  Uint8Array: Object.getPrototypeOf(Object.getPrototypeOf(Buffer.from(''))).constructor, // The JSDOM's implementation isn't compatible with 'node:crypto'
});
Object.defineProperty(global, 'crypto', {
  value: crypto,
  configurable: true,
});

[domenic]

To be clear, jsdom does not override or touch any globals. You may be using some sort of third-party library or test framework which does that, but our code has nothing to do with that.