Provides Classes and utilities for dispatching and listening to events.
Provides an EventDispatcher base class that adds the ability to dispatch events and attach handlers that should be called when such events are triggered. New event classes can be created by extending the AbstractEvent class provided in this module. This module also provides basic event classes BasicEvent and CommonEvent that are ready to be used with EventDispatcher.
seng-event also supports event capturing and bubbling phases, heavily inspired by existing event dispatching systems like the functionality described in the DOM Event W3 spec
yarn add seng-event
npm i -S seng-event
1. Extend the EventDispatcher class
EventDispatcher, your class gains the ability to dispatch events using
this.dispatchEvent(). Other code
can listen to events by calling the
addEventListener() method on your class. For more methods, see the generated
2. Create your own event class
Create an event class that defines the structure of the events you want to dispatch. This event class should extends the
AbstractEvent. There are multiple ways of doing this:
Manually extend AbstractEvent
Note: we recommend the above convention of putting the available event types as a static member on the event. However, you are free to use any string as an event type.
3. Dispatch events
;dog.addEventListenerDogEvent.types.RUN, runHandler;// dispatch an event (will execute runHandler and log 'Dog is running!')dog.dispatchEventnew DogEventDogEvent.types.RUN;
Binding your EventDispatcher child class to certain event classes
If you define which events your EventDispatcher is expected to dispatch, the class will have better typings on methods like
You can use a union type to allow for multiple event classes:
Adding data to your events
It is common to attach some data to an event that can be read from the event handler. You can implement this manually if you extend
AbstractEvent, but this can more easily be achieved with the
// creating and dispatching events in the `Dog` class:this.dispatchEventnew DogEventDogEvent.types.JUMP, ;
// accessing the datadog.addEventListenerDogEvent.types.JUMP,;
Cancellation, propagation and setTimestamp
The cancellation, bubbling and timestamp functionality of this libary are heavily inspired by the DOM Event W3 spec. These options can be enabled by passing
true to the
createEventClass util or
cancelable to true allows
preventDefault to be called on the event. Checking if
preventDefault() has been called is up to the implementer that calls
true enables event propagation for the event if the event is dispatched on an
EventDispatcher instance with a parent. See this page for a general guide on how event bubbling works.
;;;elementA.addEventListenerElementEvent.types.CLICK,;elementC.dispatchEventnew ElementEventElementEvent.types.CLICK; // logs "The element C has been clicked!"
This library also supports a capturing phase. You can listen to events in the capturing phase by setting the
useCapture parameter to
true in the
elementA.addEventListenerElementEvent.types.CLICK,console.log'Capture listener on A', true;elementA.addEventListenerElementEvent.types.CLICK,console.log'Bubbling listener on A';elementB.addEventListenerElementEvent.types.CLICK,console.log'Capture listener on B', true;elementB.addEventListenerElementEvent.types.CLICK,console.log'Bubbling listener on B';elementC.dispatchEventnew ElementEventElementEvent.types.CLICK;// logs in the following order:// Capture listener on A// Capture listener on B// Bubbling listener on B// Bubbling listener on A
true will cause a
timeStamp property to be set on the event which is a UNIX timestamp of the time the event was dispatched.
Isomorphic event classes
An isomorphic event class can have different data and options for each event
type. It can be created using the
In the above example, a
RUN and a
WALK event now have a
speed property on their event data, whereas the other events do not. In addition, all
WALK events are cancelable.
// OKthis.dispatchEventnew DogEventDogEvent.types.JUMP, ;this.dispatchEventnew DogEventDogEvent.types.BARK, ;this.dispatchEventnew DogEventDogEvent.types.WALK, ;// NOT OK (will give a compiler error)this.dispatchEventnew DogEventDogEvent.types.JUMP, ;this.dispatchEventnew DogEventDogEvent.types.RUN, ;
View the full generated documentation here.
Clone a copy of the repo:
git clone https://github.com/mediamonks/seng-event.git
Change to the seng-event directory:
Install dev dependencies:
Use one of the following main scripts:
yarn build # build this projectyarn dev # run compilers in watch mode, both for babel and typescriptyarn test # run the unit tests incl coverageyarn test:dev # run the unit tests in watch modeyarn lint # run eslint and tslint on this projectyarn doc # generate typedoc documentation
When installing this module, it adds a pre-commit hook, that runs lint and prettier commands before committing, so you can be sure that everything checks out.
MIT © MediaMonks