`NodeEventTarget` is not exported

[Mesteery]

Subsystem

events

Additional information

Is it normal that NodeEventTarget is documented but not exported, nor global?

[jasnell]

Yeah, that's intentional. We really should decide what we want to do with it. /cc @addaleax

[jimmywarting]

May i ask why it was created in the first place?
I'm not a huge fan of nodejs only features - like to write code that is more cross compatible...

[addaleax]

The intention here is to have a migration path for existing EventEmitter instances to become EventTarget instances, and to have the ability to use EventTargets in a way that is idiomatic for Node.js.

[Semigradsky]

No plans to exporting NodeEventTarget?

[unilynx]

Doesn't look like someone is working on a 'polyfill' for it either - https://www.npmjs.com/search?q=nodeeventtarget

However the only reason I wanted a NodeEventTarget is 'once', but addEventListener has a 'once' option too. with both signal and once options I wonder whether it's that useful

@Semigradsky what are you missing in EventTarget ?

[Semigradsky]

what are you missing in EventTarget ?

I just found this comment:

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/eaaf5e44d4c874c4f7e38210cc62d053292f3b13/types/node/events.d.ts#L39-L41

[thw0rted]

I think I actually wrote that comment, or at least the preface that your link points to -- the commented out interface likely came from existing code in the previous "events" module definition.

The core issue here is that the event module documentation is confusing. It says that NodeEventTarget is a "class", but as far as I can tell it's never exposed. The same is true of "classes" EventTarget and CustomEvent -- require('node:events') just returns the EventEmitter constructor.

There has been some discussion over on the DefinitelyTyped issue tracker about which "type-space" definitions should be exported by @types/node. For example, RequestInit is a "dictionary" defined in the Fetch spec -- there is no RequestInit defined at runtime, anywhere (browser or server), but Microsoft shipped a RequestInit interface in lib-dom and it's been generally useful to library authors, so it probably makes sense for Node to ship it as well, as part of fetch support.

That might apply here. @types/node could export the shape of NodeEventTarget as an interface, but at the moment that would be confusing because Node documents it as a class, and does not exist at runtime. Would it be helpful if the commented-out interface was just uncommented in @types/node so that you could import type {NodeEventTarget} from 'node:events'? If so, the DT maintainers might accept a PR -- just link to this issue as explanation.

Of course, that's not exactly what the OP was asking for. If there actually is a NodeEventTarget class / constructor-function which is internally maintained and used by Node, and somebody would find it useful to have the ability to invoke it or inherit from it, maybe they can speak up here?

[unilynx]

The same is true of "classes" EventTarget and CustomEvent

They're not exported by node:events but they're in the global namespace. extending from EventTarget and then using addEventListener and then dispatchEvent-ing a CustomEvent work for me in node

[thw0rted]

Ah, that helps a lot, thanks. Apparently I misunderstood the docs -- they give the impression that each top level sidebar link describes a single module, and all the functions and classes in the corresponding page are exports from the module. Sometimes that's true, but sometimes they're talking about global entities that are used by / returned from the module's functions and classes. This probably isn't the issue to complain about that.

[piotr-cz]

The same is true of "classes" EventTarget and CustomEvent

They're not exported by node:events but they're in the global namespace. extending from EventTarget and then using addEventListener and then dispatchEvent-ing a CustomEvent work for me in node

Since which version?

This is the output for nodejs v18.18.2 and v20.10.0:

node -e 'console.log(typeof EventTarget)'
function

node -e 'console.log(typeof NodeEventTarget)'
undefined

[unilynx]

The same is true of "classes" EventTarget and CustomEvent

They're not exported by node:events but they're in the global namespace. extending from EventTarget and then using addEventListener and then dispatchEvent-ing a CustomEvent work for me in node

Since which version?

This is the output for nodejs v18.18.2 and v20.10.0:

I was talking about EventTarget, not NodeEventTarget. So apparently EventTarget is available on all versions that are still in support (18+)

Most of the things I personally might need from NodeEventTarget (Eg once) area already covered by the new options added to addEventListener.

[rotu]

I was confused by this too. Reading the documentation, it seemed like NodeEventTarget was a feature-rich, viable alternative to EventEmitter, intercompatible with the web EventTarget API and without the special handling for error events.

Definitely could use a mention in the docs that this is an internal API.

It also seems like NodeEventTarget is not very widely used internally. What's the direction it's taking? Is it more likely to be adopted internally or deprecated?

[Renegade334]

It also seems like NodeEventTarget is not very widely used internally. What's the direction it's taking? Is it more likely to be adopted internally or deprecated?

I'm wondering the same. As far as I can tell, it's only ever been used in one place (MessagePort) and that change was made over four years ago.