seng-event
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
Installation
yarn add seng-event
or
npm i -S seng-event
Basic usage
1. Extend the EventDispatcher class
By extending 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
API Docs
;
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
base class AbstractEvent
. There are multiple ways of doing this:
createEventClass()
utiltiy
Use the ;
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 dispatchEvent
and addEventListener
:
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 createEventClass
util:
// 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 AbstractEvent
constructor:
Cancellation
Setting cancelable
to true allows preventDefault
to be called on the event. Checking if preventDefault()
has been called is up to the implementer that calls dispatchEvent()
:
;this.dispatchEventevent;if !event.defaultPrevented
Bubbling
Setting bubbling
to 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 addEventListener
method:
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
setTimestamp
Setting setTimestamp
to 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 createIsomorphicEventClass
util:
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, ;
dog.addEventListenerDogEvent.types.JUMP, ;dog.addEventListenerDogEvent.types.WALK, ;
API documentation
View the full generated documentation here.
Building
In order to build seng-event, ensure that you have Git and Node.js installed.
Clone a copy of the repo:
git clone https://github.com/mediamonks/seng-event.git
Change to the seng-event directory:
cd seng-event
Install dev dependencies:
yarn
Use one of the following main scripts:
yarn build # build this project yarn dev # run compilers in watch mode, both for babel and typescript yarn test # run the unit tests incl coverage yarn test:dev # run the unit tests in watch mode yarn lint # run eslint and tslint on this project yarn 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.
Contribute
View CONTRIBUTING.md
Changelog
View CHANGELOG.md
Authors
View AUTHORS.md
LICENSE
MIT © MediaMonks