@creacore/event-ts

Description

The library event-ts is a standalone typescript library for managing events. It makes heavy use of type system in order to provide helpful hints and compilation errors. It provides a decorator @Event to create new event classes and a static class EventManager to listen, dispatch and manage all events.

Link

Setting Up
- npm
- git & build
Examples
- Simple
- More...
API

Setting up

npm

The easiest way to install is to use npm :

npm install @creacore/event-ts

you need to activate the typescript decorator in your tsconfig.js:

"experimentalDecorators": true

you can now import the component in you typescript file

import {Event, EventManager} from "@creacore/event-ts";

git and build

you can also clone the project from github

git clone https://github.com/creacore-team/event-ts.git

and compile with npm

npm run build

or with typescript compiler only

tsc

In order to user event-ts in a browser the library need to be browserify.

npm run build-browser

create the file event-ts.js in the folder browser with the main declaraction of the library store in a variable EVENTTS.

Examples

Simple examples

Here is a simple example of how to use @creacore/event-ts.

import {Event, EventManager} from "@creacore/event-ts";

@Event()
class MyEvent
{
    constructor(public readonly myParameter:string){}
}

EventManager.addEventListener(MyEvent,(ev) => {
    console.log("Event : " + ev.myParameter )
});

EventManager.dispatchEvent(new MyEvent("Hello world !"));

This example will output in the console when compiled and run:

Event : Hello world !

When using a IDE supporting typescript, usefull suggestion will show up

Other examples

More examples are available in the examples directory. You can build the examples provided in repository by simply run

npm run build-examples

Examples sources are in examples/src directory and the built examples are found under the example/build directory once they have been compiled and can be run with node.

API

@Event

In order to define a class as an event, it must be decorated with @Event decorator. This decorator takes an object as a parameter that fulfill the EventParameter interface and configure the main behavior of the event. Note that all properties of EventParameter are optional.

Note that the decorator add three parameters to your classes :

emitter : the object emitter of the event or null
queued : a boolean which is true if the event has been queued before being dispatched
following : a boolean which is true if the event has been trigger because of a follow rule

Your event class should never define the properties emitter, queued and following itself ! They will be erased when the event is dispatched Your event class should never define the static properties eventName, hasBeenEventify, async, queued, removeDuplicate, testDuplicate and followers itself ! They will be erased when the decorator is applied

// An event with no parameter
@Event()
class MyEvent
{
    constructor(public readonly value:number){}
}

// An event with parameter
@Event({async:false})
class AnotherEvent
{
    // constructor can be omitted if trivial
}

Event decorator parameters : `EventParameter` interface

The decorator @Event take (or not) an EventParameter = {async, queued, tag, removeDuplicate, testDuplicate} as argument which can contain 5 optionals parameters.

async : boolean

If async is defined at true, the event is triggered asynchronously. If omitted, default is false. Note that this parameter can be overridden when the event is dispatched.
queued : "Always" | "Never" | "Default"
- Always : the event is always queued and is dispatched only when the queue is flushed, even asynchronous event are queued with this parameter active
- Never : the event is never queued, even when the queue is enabled
- Default : the synchronous event is queued only when the queue is enabled while the asynchronous event are not queued, when omitted this is the default.
tag : string

This tag is added at the beginning of the auto-generated event name. This is useful when you want to track your events to debug code (see the eventName parameter of TriggerDispatchEvent).
removeDuplicate : boolean

If true, when events are queued the duplicated event are removed (the last added is kept). The default value is true (if no testDuplicate is specified two events are considered identical if they are instances of the same event classes and have the same emitter, no matter their parameters).
testDuplicate :(e1:any, e2:any) => boolean

Two events are considered equals if they have the same name (they are instance of the same event class) and have the same emitter and if the function testDuplicate return true. If omitted, by default the function testDuplicate return true no matter the parameters of the class.

EventManager (class)

Methods:

`addEventListener`

The method addEventListener allow to subscribe to an event. It takes 2 mandatory parameters and one optional.

EventManager.addEventListener(eventCtor, callback, emitter?):id

eventCtor

The class name of you event (this is actually the constructor of you event class after the application of the Event decorator). This determines the event to which you subscribe.
callback

Function that is called each time your event is dispatched. The callback take as argument an instance of the Event class you are listening to with three additional parameters :
- emitter : Object
  
  The Object emitter, the default type is object but if you specified an emitter as the third argument of addEventListener the type is the same.
- queued : boolean
  
  A boolean value which is true if the event has been queued before to be dispatched.
- following : boolean
  
  A boolean value which is true if the event has been dispatched because it is following another event.
emitter : Object (optional) Object that must be the emitter of the event to trigger the callback. If emitter is undefined all emitters trigger the callback.
id : Object (return value)

Object that can be used as an id to refer to the link between the event and the callback (the exact type is ObjectCallbackGeneric but it should never be used otherwise than an id).

`deleteEventListener`

The method deleteEventListener allow to unsubscribe to an event. It takes 2 mandatory parameters and one optional.

EventManager.deleteEventListener(eventCtor, id):success

eventCtor

Class name of you event (this is actually the constructor of you event class - after the application of the decorator event). This determines the event to which you subscribe.
id : Object

Object that refer to the link between the event and the callback (the exact type is ObjectCallbackGeneric but it should never be used otherwise than an id).
success : boolean (return value)

The return value, true if the unsubscription is successfull, false otherwise.

`dispatchEvent`

The method dispatchEvent allow to unsubscribe to an event. It takes 1 mandatory parameters and 3 optional.

EventManager.dispatchEvent(event, emitter?, async?, bypassQueue?) : success

event : Event

An instance of the class event that you want to dispatch.
emitter : Object (optional)

The emitter of the event. If an event subscriber have specified an emitter, it will be triggered only if this is the same emitter. If omitted the default value is undefined and only subscriber without specific emitter can catch the event.
async : boolean (optional)

Specified if the event is launch synchronously or asynchronously. If omitted (default value undefined), the synchronicity is the one defined in the event class, this is a way to override the default event class behavior at dispatching time.
bypassQueue : boolean (optional)

This parameter allow to bypass the queue when it has been manually enabled (see enableQueue). Note that if the event queued id defined as Always bypassQueue is ignore.
success : boolean (return value)

The return value, true if the dispatching was successfull, false otherwise.

`enableQueue`

EventManager.enableQueue({removeDuplicate, dontQueueAsync, autoFlushAfter, stackEnableCall}) : void

`disableQueue`

EventManager.disableQueue(autoflush, force) : nevent

`flushQueue`

EventManager.flushQueue(eventCtor) : nevent

`clearQueue`

EventManager.clearQueue() : void

`compressQueue`

EventManager.compressQueue(keep, erase, sameEmitters:boolean = true) : void

`follow`

EventManager.follow(eventACtor , eventBCtor, eventTransformer, emitter) : id

`unfollow`

EventManager.unfollow(id) : void