@actualwave/event-dispatcher
Version:
EventDispatcher is a JavaScript class that adds events support to custom objects.
126 lines (107 loc) • 6.22 kB
Markdown
# EventDispatcher
[](https://travis-ci.org/burdiuz/js-event-dispatcher)
[](https://coveralls.io/github/burdiuz/js-event-dispatcher?branch=master)
Just another EventDispatcher/[EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) implementation.
## Installation
Easy to install with [npm](https://www.npmjs.com/) package manager
```javascript
npm install --save @actualwave/event-dispatcher
```
with [yarn](https://yarnpkg.com/) package manager
```javascript
yarn add @actualwave/event-dispatcher
```
## Usage
> Note: EventDispatcher distribution package contains package wrapped into UMD wrapper, so it can be used with any AMD module loader, nodejs `require()` or without any.
To start using EventDispatcher, just instantiate it on its own
```javascript
class MyClass {
constructor() {
this._dispatcher = new EventDispatcher();
}
addListener(handler) {
this._dispatcher.addEventListener('didSomething', handler);
}
doSomething() {
this._dispatcher.dispatchEvent('didSomething');
}
}
```
extend it with your class
```javascript
class MyClass extends EventDispatcher {
doSomething() {
this.dispatchEvent('didSomething');
}
}
```
After instantiating `MyClass`, every call of `doSomething()` will fire event `didSomething` and every listener attached to this event will be called with event object as argument.
```javascript
var myObj = new MyClass();
myObj.addEventListener('didSomething', function(event) {
console.log('My Listener', event.type);
});
myObj.doSomething();
```
When adding listeners they will be executed in same order as they where added. To change order you can use optional `priority` argument to `addEventListener()` method.
```javascript
myObj.addEventListener('didSomething', function(event) {
console.log('Prioritized Listener', event.type);
}, 1);
myObj.doSomething();
```
By default priority is set to 0, and you can specify higher priority >0 or lower <0, only integer values are allowed.
To fire event you should use `dispatchEvent()` method, it can be used in three ways:
You can pass only event type string. In this case event object will be created by `EventDispatcher`
```javascript
var dispatcher = new EventDispatcher();
dispatcher.dispatchEvent('eventType');
```
With event type you can specify any data, as second argument, that should be passed with event
```javascript
dispatcher.addEventListener('eventType', function(event) {
console.log('My Listener', event.type, event.data);
});
dispatcher.dispatchEvent('eventType', {myData: 'something'});
```
Also you can pass event object, it must contain `type:String` property
```javascript
dispatcher.dispatchEvent({type: 'eventType', data: 'data is optional'});
```
If you want full control of events that fire from your EventDispatcher, you can specify event pre-processor function that will be called for each event before it fired. This function should return same or new event object.
```javascript
function eventPreprocessor(event){
event.data = event.data || {};
return event;
}
var dispatcher = new EventDispatcher(eventPreprocessor);
dispatcher.dispatchEvent('eventType');
```
`eventPreprocessor()` function will be called with event object and returned object will be used.
Example available in project's `example` folder. To try example first run server
```javascript
npm run server
```
And then go to [http://localhost:8081/index.html](http://localhost:8081/index.html)
## API
### EventDispatcher
* **addEventListener**(eventType:String, listener:Function, priority:int=0):void - Add listener to event type. Additionally priority can be set, higher values allow call listeners before others, lower -- after. Same listener can be added to event type using different priorities. By default, 0.
* **hasEventListener**(eventType:String):void - Check if listener was added to event type.
* **removeEventListener**(eventType:String, listener:Function):void - Remove event listener from event of specified type.
* **removeAllEventListeners**(eventType:String):void - Remove all listeners from event of specified type.
* **dispatchEvent**(eventType:String, data:Object=null):void - Dispatch event of `eventType` and pass `data`. Will create object of built-in class Event and pass it as first argument to listeners.
* **dispatchEvent**(event:Object):void - Event object that should be fired, can be any object. Only requirement -- it must contain field `type` with event type.
EventDispatcher constructor accepts optional argument `eventPreprocessor(event:Object):Object`, function that receive event object as argument and should return same or new/changed event object that will be passed to event listeners.
### Event
Built-in class to represent dispatched event.
Objects of Event class are used when dispatchEvent() method is called with `eventType`.
* **type**:String - Event type.
* **data**:Object - Data object passed to `EventDispatcher.dispatchEvent()` method.
* **preventDefault**():void - Will change "prevented" flag from FALSE to TRUE, it can be requested via `isDefaultPrevented()` method.
* **isDefaultPrevented**():Boolean - Will return TRUE if `preventDefault()` was called.
Any event(instance of built-in Event class or any other object passed as event) gains additional methods when its being dispatched. After cycle finished, these methods will be removed from event object.
* **stopPropagation**():void - Stop event propagation after processing all listeners of same priority.
* **stopImmediatePropagation**():void - Stop event propagation on current listener.
## Claude / AI Agent Skill
This package includes a `SKILL.md` file ([Agent Skills](https://agentskills.io/) format) that teaches AI coding assistants how to use the library. When installed as an npm dependency, the skill is available at `node_modules/@actualwave/event-dispatcher/dist/SKILL.md` and can be loaded by Claude Code or any compatible agent to get accurate, up-to-date usage guidance without relying on training data.
> Written with [StackEdit](https://stackedit.io/).