EventEmitter API

[ChALkeR]

Moved from #1785 (comment)

Some modules use the internal _events object. It's not a good thing, and that probably means that EventEmitter is missing some API methods.

Also lib/_stream_readable.js uses the internal _events object of lib/events.js, which is ok, but not very nice. What makes that a bit worse is that lib/_stream_readable.js is also packaged as an external readable-stream module.

Samples of _events usage:

• readable-stream/lib/_stream_readable.js:
  1. if (!dest._events || !dest._events.error)
  2. else if (isArray(dest._events.error))
  3. dest._events.error.unshift(onerror);
  4. dest._events.error = [onerror, dest._events.error];
• dicer/lib/Dicer.js:
  1. if (this._events.preamble)
  2. if ((start + i) < end && this._events.trailer)
  3. if (this._events[ev])
• busboy/lib/types/multipart.js:
  1. if (!boy._events.file) {
• ultron/index.js:
  1. for (event in this.ee._events) { if (this.ee._events.hasOwnProperty(event)) {

It looks to me that there should be methods in EventEmitter to:

• Get a list of all events from an EventEmmiter that currently have listeners. This is what ultron module does, and I do not see an API for that. Getting a list of events could also be usable for debugging.

  Implemented by @jasnell in events: add eventNames() method #5617, will be available in 6.0.

• (optional) Check if there are any listeners for a specific event. Like EventEmitter.listenerCount but using a prototype, like EventEmitter.prototype.listeners but returning just the count. This is what seems to be most commonly used.

  It has a valid API EventEmitter.listenerCount, but why isn't it inside the prototype? That makes it a bit harder to find and that could be the reason behind modules using this._events.whatever to count (or check the presense of) the event listeners.

  That's since 75305f3. @trevnorris

  Solved by events: deprecate static listenerCount function #2349.

• (optional) To prepend an event. Does the documentation specify the order in which the events are executed, btw?

  This is what the internal lib/_stream_readable.js and the readable-stream module do.

  Implemented by @jasnell in events: add ability to prepend event listeners #6032.

[ChALkeR]

From #1785 (comment) discussion:
@mscdex @chrisdickinson @sam-github @Qard

[targos]

Existing discussion about EventEmitter#listenerCount: #734

[ChALkeR]

@chrisdickinson

readable-stream is directly vendored from core's streams. Core has a need for prepending events – userland does not (with the exception of readable-stream, which doesn't seem like a good excuse to add it.)

Actually, it does. readable-stream is a widely used (actually, that's a bad thing) module that uses internal iojs API. That, for example, blocks the internal EventEmmiter API changes, see #1785 (comment).

Either the usage of _events by the readable-stream module should be fixed, or the whole situaton where everyone uses readable-stream module (that is pretty much abadonware atm) should be somehow fixed.

[chrisdickinson]

@ChALkeR It doesn't block changing the API, it blocks changing _events. We can always shim it back in using a getter/setter property.

[ChALkeR]

@chrisdickinson Ok, I might have misphrased that. I meant the internal details of the EventEmmiter module. Yes, a shim would fix that. And it will be needed in the current situation once #1785 (or something else that changed _events) get pulled. But doesn't a shim for an internal object look a bit …strange? The root of problem here is that modules have to use the internal _events object to do stuff.

If you don't want to expose an API to do what readable-stream does (see 3.) — fine, that could be understandable (well, because that's technically a hack now).

But I see nothing wrong in adding an API endpoint that allows getting a list of all events that have listeners (see 1.).

[chrisdickinson]

But doesn't a shim for an internal object look a bit …strange?

It's a cowpath, for better or worse. It'd be interesting to get some metrics on how pervasive its use is in the ecosystem, but given readable-stream's dependency on it I'm inclined to say it's probably worth preserving (vs. patching out of the ecosystem.) Updating all libraries dependent on readable-stream of any version would be a pretty intense exercise.

With regards to "getting a list of event topic names with listeners" from an EventEmitter – outside of Ultron, are there any other modules that make use of _events for this purpose? If so, it's probably OK to add an EventEmitter.getEventNames(ee) API.

[trevnorris]

@ChALkeR Reason it wasn't placed on the prototype is because EE is inherited by everything, and it was decided at the time that adding a new method could break compatibility. (IIRC there was a module pointed out that uses that same method name)

[Qard]

A possible way around that is a non-prototype method like
events.getEventNames(emitter).
On May 27, 2015 6:20 PM, "Trevor Norris" notifications@github.com wrote:

@ChALkeR https://github.com/ChAlKeR Reason it wasn't placed on the
prototype is because EE is inherited by everything, and it was decided at
the time that adding a new method could break compatibility. (IIRC there
was a module pointed out that uses that same method name)

—
Reply to this email directly or view it on GitHub
#1817 (comment).

[rektide]

I showed up in nodejs/io.js to grieve about not having a real way to do @ChALkeR's #1 use case. I had written up streaming-heart-mother to kind-of/sort-of work around this: it listens to newListener events and exposes an enumeration of them via a knownEvents property. (It also monkey-patches .emit to look for events happening with no subscribers)

This has been a very longstanding issue I've had with the DOM's EventTarget interface, and which EventEmitter repeated- the un-introspectability, the inability to see what's happening on the target site without getting there first and monkey-patching the hay out of it to keep a record for yourself. A good, reflective first-class system would put this right and expose the key information about the object, not retain it from the programmers: looking at _events is a completely incorrect hack that is just a faster, better, clearner version of (my, others) filthy monkey patching.

(There's GetEventListeners, which is something available in Developer Tools, which seems 1/3rd as pleasant still as emitter._events)

The EventEmitter.prototype API ought be amended so differing implementations of events can successfully cooperate together. _events was never specified, and isn't the right interface- EventEmitter.prototype.getEventNames feels to me much closer to the desired interface. Doing events.getEventNames would only make things 100x worse than the current state by obliterating a internal but well-known contract of the object and replacing it with a static method specific to the implementation: this would be the opposite of what is prescribed in a slot-based/predicated language.

It's high time EventTarget's original high treason against good JS object-ness be corrected.

[rektide]

There is still one use case I'd like to be able to solve- both dynamic writers and dynamic listeners. For example: if there's a emitter that knows how to read from a variety of kafka queues, and listeners that might want to pick certain queues (listen to events) if the name matches some predicate, then both sides are waiting for the other to either emit or listen, and neither knows whether to tentatively begin bindings/offering itself first. It's a wait-locked situation. It's "solvable" by having the emitter either once or periodically emit zero-sized content events, by being proactive, and letting monkey-patch logic let the listener-side see these emits happening, but just as _events is a coordination point that developers ought to have reach into, so to is emit a source-of-information that enriches the environment.

So in contrast to my Streaming Heart Mother v1.1, which can convey knownEvents on the emitter, a fantastic, out of this world awesome api would be able to let both producers find all listeners, and listeners explore all possible emits systems. It's a dual that I'd like to see filled, of allowing both sides of the emitter to express what capabilities are about (possible emitters, as well as listed listeners). But I get that perhaps this might better be reserved for a higher level collaboration api.

[ChALkeR]

Ah, and @3rd-Eden for ultron.

[ChALkeR]

About (3), there are modules for that:

1. https://www.npmjs.com/package/on-first. Uses _events internally, basically the same code as in readable-stream. But this module isn't popular and there are no packages that depend on that, it seems.
2. https://www.npmjs.com/package/overshadow-listeners Also not popular and 0 dependants, but what is intresting here — it applies a different kind of hack that does not involve _events and uses only the existing public EventEmmiter API. Works by reattaching and attaching existing listeners.

Maybe the readable-stream could be ported away from using _events directly to use the same method as overshadow-listeners uses? That could remove the need in (3) completely.

[chrisdickinson]

@rektide If we added such a reflection API, we'd likely put it on the constructor itself (a la EE.listenerCount, for the same reasons.) While I feel your pain about the impurity of having what should be a per-instance method available only as a static method that operates on instances, in this case avoiding breaking downstream code trumps aesthetic concerns.

@ChALkeR Even if we fix readable-stream such that _events are no longer used directly, we still have to release those changes in a patch release. Then we have to run through each of the 612 dependents of readable-stream and find the ones that have pinned the dep, and issue a PR to the new version (& make a release.) Then for each of the dependents of those dependents, we have to issue a PR for every pinned dep there. It's probably going to be more expedient to shim the _events API, treating it as a discouraged, but paved, cowpath.

[ChALkeR]

@chrisdickinson Shimming _events is required in the current situaton if #1785 or something else breaking _events gets merged.

But to remove the bloat in the long-term, usage of _events in modules (including readable-stream) should be reduced as soon as possible.

Maybe if we do that now and if EventEmmiter internal structure would be changed in, for example, 4.0 — it could be fine to avoid shimming _events.

Edit: There is another PR that breaks the internal _events api: #914.