0002-event-bus.adoc 2.08 KB
Newer Older
1 2 3 4
= ADR 0002: Event Bus

== Status

Dan Allen's avatar
Dan Allen committed
5
Deferred
6 7 8 9 10

== Context

Plugins should be able to participate in the documentation pipeline by registering event listeners.
This requires the use of an event bus into which pipeline components emit events.
Sarah White's avatar
Sarah White committed
11
Event listeners may perform supplemental tasks at strategic points in the pipeline or modify the state of the application data that is exposed to the listener.
12

Sarah White's avatar
Sarah White committed
13
An open question is whether methods on plugins should be called directly or whether plugins should be invoked through the event system by listening for events.
14 15 16 17 18 19 20 21 22 23

== Decision

Node provides an event-driven architecture, which means it has an event bus built right into its core.
All Antora needs to do is make use of it.

Node's event bus, called the EventEmitter, supports both synchronous and asynchronous publish-subscribe messaging (decouples producers and consumers through a standard interface).
Events are registered by name and additional arguments can be passed to the event listeners by the emitter.

We will leverage the built-in event bus in Node to make plugins easy to register.
24
When plugins get registered, they will be passed the event bus instance (i.e., EventEmitter instance) so they can use it to listen for events.
25 26 27

== Consequences

28 29
Listeners for an event are executed synchronously in the order in which they are registered.
The only exception is when a listener is configured to run immediately, in which case it's run asynchronously.
30 31 32 33 34
This could present a problem if plugins need to be registered in a particular order.
One possible workaround is for a plugin to use the prepend feature to add a listener at the top of the list.
But that's the extent of the control over ordering (append/prepend).

Using the Node event bus ties Antora components to the Node JavaScript environment.
35
This sacrifice in portability between JavaScript environments can be alleviated using a node module like https://yarnpkg.com/en/package/eventemitter3[EventEmitter3], which extends support to browser environments.
36
The downside of that approach is that plugins must also change to using that module in order to register events.