EventTarget, Observer, and toArray, last, etc

[jasnell]

With the current definition of the EventTarget integration, there's currently no mechanism for ending the stream of events, making things like await observer.toArray() or await observer.last() problematic if not used together with one of the limiting functions like observer.take(2). There really needs to be a way of signaling that the subscription to the event stream has concluded. This can be done, I think, with allowing the once and signal options to be passed into the EventTarget.prototype.on(...) options alongside capture and passive.

const ac = new AbortController();
const obs = eventTarget.on('foo', { signal: ac.signal, once: true });
const p = await obs.toArray();
// Only a single `foo` event will be passed along!
// Or, if ac.signal is tripped, the EventTarget listener is canceled and unregistered and the subscription is errored or completed
// Without these limiting options, the toArray() promise will never resolve

[domfarolino]

There really needs to be a way of signaling that the subscription to the event stream has concluded. This can be done, I think, with allowing the once and signal options to be passed into the EventTarget.prototype.on(...) options alongside capture and passive.

Note that the signal can already be passed in for all Promise-returning operators, which is the right place for it since it's a per-subscription signal. I really don't think you want to pass the signal into on(), which global for all subscriptions based on that Observable. If you did that, and aborted the signal once, then every single future invocation of subscribe() on that Observable would be dead, which is probably not what you want. Remember calling subscribe() on an Observable returned from on() is basically the same as calling addEventListener() under the hood, so to keep uniformity with addEventListener() you'd want to pass signals in at that level (i.e., per-addEventListener() call) — which amounts to per invocation of each Promise-returning operator.

Now as for once.... I could go either way, but I lean towards leaving it out of ObservableEventListenerOptions just because we have the cute and simple limiting/terminating operator take(1). It really doesn't seem too bad to have people do:

const controller = new AbortController();
eventTarget.on('foo').take(1).toArray({signal: controller.signal});

See https://github.com/WICG/observable/issues/65#issuecomment-1721017223, https://github.com/WICG/observable/issues/66, and to a lesser extent, https://github.com/WICG/observable/issues/75. Thoughts?

[Jamesernator]

// Or, if ac.signal is tripped, the EventTarget listener is canceled and unregistered and the subscription is errored or completed

Erroring and completing are quite different alternatives, like is the intention here to still get the array? If so my suggestion .takeUntil(abortSignal) would be good here:

const array = eventTarget.on("foo").takeUntil(ac.signal).toArray();

If the intention is just to reject the promise with the abort reason, then .toArray({ signal }) already does so as @domfarolino shows in the example.