Revisiting globalThis as an EventTargetΒ #51372
Description
In browsers, deno, bun, workers and other runtimes, globalThis implements the Web platform standard EventTarget API. While there are differences in the specific events emitted at the global scope, the unhandledrejection and rejectionhandled events are common to all of these runtimes. In Node.js our globalThis, of course, does not implement EventTarget and implements unhandled rejection events using EventEmitter instead. This ends up causing some interop headaches for library authors who have to special case handling of these events across runtimes.
We've discussed this before but I'd like to re-open the discussion for consideration around the questions:
- Should Node.js
globalThisimplementEventTarget - Should we emit the Web standard
unhandledrejectionandrejectionhandledevents onglobalThisand either (a) deprecate or (b) mark as legacy the equivalent events onprocess? - Should we support other Web standard events on
globalThisincluding:beforeunload(equivalent toprocess'beforeExitevent)error(equivalent toprocess'uncaughtExceptioneventloadmessage(equivalent toprocess'messageevent)messageerror- etc
@nodejs/tsc @nodejs/web-standards
Context: this came up in a WinterCG discussion around whether interoperable/consistent handling of unhandled errors and rejections should be covered by the WinterCG common minimum API spec.
Activity
KhafraDev commentedon Jan 4, 2024
I'm a +1 and I have a PR that implementes this already #45993
jasnell commentedon Jan 4, 2024
Yep, I was previously -1 on that change because I do think it would introduce some confusion but I've reconsidered my point of view and I think I'm +0 on it... that is, I'm open to it but I still have a number of reservations.
mcollina commentedon Jan 4, 2024
Iβm -1 as I think it would add more confusion. None of those mechanisms are correct for library authors.
Most libraries should not touch global objects, because they can conflict in behaviors.
For library authors, the problem is that more often you want to βexecute something only if OBJ was not GCedβ to avoid memory leaks on global objects. This is currently hacky, widespread and problematic with the use of FinalizationRegistry.
Application builders should use these events, not library authors. Application builders target a specific runtime, so there is not much of a compatibility issue to discuss.
jasnell commentedon Jan 4, 2024
I disagree. We have application builders targeting multiple runtimes that have explicitly raised these kinds of compat issues.
Also, "libraries should not touch global objects" is obviously incorrect when it comes to other kinds of globals (
URL,crypto.subtle,Buffer, etc).GeoffreyBooth commentedon Jan 4, 2024
What is an "application builder"? There are plenty of full-stack frameworks that explicitly target multiple runtimes, like SvelteKit has adapters to run in Node or Cloudflare etc. I'm sure the SvelteKit authors would appreciate as much similarity between those targets as possible.
eligrey commentedon Jan 4, 2024
Supporting
messagein this way sounds dangerous unless Node's message events are fully compatible with browser MessageEvents.mcollina commentedon Jan 5, 2024
Most of those do not allow changing configuration that alter how the process work or is set up.
The problem I'm describing happens when installing custom behavior. Most libraries out there would not install an
uncaughtExceptionorexitorbeforeExithandlers, because they will actually leak memory in most situations. Most of the times adding those in libraries introduce unexpected behaviors for the end users.mcollina commentedon Jan 5, 2024
A developer that creates an application, vs one that creates a library to be installed.
I've done a quick skim of SvelteKit repo and I haven't found an "uncaughtException" event handler for example. Could you point me to a real-world examples of the complexities of handling this case for those libraries.
mcollina commentedon Jan 5, 2024
This is an interesting use case, and I never tried to build one. Could you make an example of the compatibility problems?
joyeecheung commentedon Jan 10, 2024
I think we should only implement the events that are exposed to Worker/global scopes in https://html.spec.whatwg.org/multipage/indices.html#events-2 .
messageandmessageerrorwould make sense,unhandledrejection/rejectionhandled/errorless so, andbeforeunload/loadshouldn't be there. In general, exposing things that are available to Window but not to Worker in the spec can be problematic, because Node.js mostly implement worker scope things but not the window scope things.jimmywarting commentedon Jan 22, 2026
I think it would be valuable to implement a MVP and iterate from there. Just make globalThis inherit EventTarget and do nothing else with it. Do not dispatch ANY event to it. not even those that is emitted on eventemitter.
Just take small baby step. It might be useless at first but it will involve in the feature