Eventer
A simple JS typed event system, similar to the native one (i.e. reinventing the wheel).
Docs are available at the project page.
Table of Contents
Installation
Using NPM
npm i @aliser/eventer
Usage
Setup
import Eventer from '@aliser/eventer';
/**
A type describing your events, where:
* - propertyName — an event name, a string.
* - propertyValue — an object with data expected in by the event or an empty object, if event has no data.
*/
type Events = {
hello: { // event with data
msg: string
},
bye: { } // event without data, — is dataless
}
/*
* Create a listener that accepts data with the data type specified. If event has no data, don't specify anything.
*/
const helloListener = ({ msg }: Events['hello']) => {
console.log(msg);
}
const byeListener = () => {
console.log('Bye, world!');
}
- Use
Eventer
in class through inheritance
class Foo extends Eventer<Events> {
constructor() {
super();
}
}
const foo = new Foo();
// add <helloListener> listener to <hello> event
foo.addEventListener('hello', helloListener);
// fire <hello> event with some data
foo.dispatchEvent('hello', { msg: 'Hello, world!' });
// > Hello, world!
// remove <helloListener> from <hello> event
foo.removeEventListener('hello', helloListener);
// fire <hello> event with some data, again
foo.dispatchEvent('hello', { msg: 'Hello, world!' });
// no message is printed
- Or create
Eventer
instance
const eventer = new Eventer<Events>();
// add <helloListener> listener to <hello> event
eventer.addEventListener('hello', helloListener);
// fire <hello> event with some data
eventer.dispatchEvent('hello', { msg: 'Hello, world!' });
// > Hello, world!
// remove <helloListener> from <hello> event
eventer.removeEventListener('hello', helloListener);
// fire <hello> event with some data, again
eventer.dispatchEvent('hello', { msg: 'Hello, world!' });
// no message is printed
Features
Setup
import Eventer from '@aliser/eventer';
type Events = {
hello: {
msg: string
},
bye: { }
}
const eventer = new Eventer<Events>();
const helloListener = ({ msg }: Events['hello']) => {
console.log(msg);
}
const byeListener = () => {
console.log('Bye, World!');
}
Basics
eventer.addEventListener('hello', helloListener);
eventer.dispatchEvent('hello', { msg: 'Hello, World!' });
// > Hello, World!
eventer.removeEventListener('hello', helloListener);
// =============
// or use chaining!
eventer
.addEventListener('hello', helloListener)
.dispatchEvent('hello', { msg: 'Hello, World!' }) // > Hello, World!
.removeEventListener('hello', helloListener);
Firing events just once
eventer.addEventListener('hello', helloListener, { once: true });
eventer.dispatchEvent('hello', { msg: 'Hello, World!' });
// > Hello, World!
eventer.dispatchEvent('hello', { msg: 'Hello, World!' });
// nothing is printed, no error is thrown
Firing events without listeners
Doesn't throw any errors.
eventer.dispatchEvent('bye');
// nothing is printed, no error is thrown
Removing never-added listeners
Doesn't throw any errors.
eventer.removeEventListener('hello', helloListener);
// nothing is printed, no error is thrown
Type-checking
Adding listeners
Adding a listener to an event that doesn't exist.
eventer.addEventListener('someEvent', helloListener);
/* ^^^^^^^^^^^
* error: Argument of type '"someEvent"' is not assignable to parameter of type '"hello" | "bye"'.
*/
Adding a listener that expects data to an event that doesn't provide any data.
eventer.addEventListener('bye', helloListener);
/* ^^^^^^^^^^^^^
* error: Argument of type '({ msg }: Events['hello']) => void' is not assignable to parameter of type '() => void'.
*/
Adding a listener that expects different data from that passed in by the event.
const someEventListener = ({ counter }: { counter: number }) => {
console.log('The total count is: ' + counter);
}
eventer.addEventListener('hello', someEventListener);
/* ^^^^^^^^^^^^^^^^^
* error: Argument of type '({ counter }: { counter: number; }) => void' is not assignable to parameter of type '(data: { msg: string; }) => void'.
Types of parameters '__0' and 'data' are incompatible.
Property 'counter' is missing in type '{ msg: string; }' but required in type '{ counter: number; }'.
*/
Removing listeners
Removing a listener that expects data from an event that doesn't provide any data.
eventer.removeEventListener('bye', helloListener);
/* ^^^^^^^^^^^^^
* error: Argument of type '({ msg }: Events['hello']) => void' is not assignable to parameter of type '() => void'.
*/
Removing a listener from an event that doesn't exist.
eventer.removeEventListener('someEvent', helloListener);
/* ^^^^^^^^^^^
* error: Argument of type '"someEvent"' is not assignable to parameter of type '"hello" | "bye"'.
*/
Firing events
Firing an event that requires data without providing any data.
In this case, because no data is given, Typescript checks againts events that have no data and will show errors depending on how these events are defined:
-
Events
has no dataless events.
type Events = {
hello: {
msg: string
},
someEventWithData: {
counter: number
}
}
. . .
eventer.dispatchEvent('hello');
/* ^^^^^^^
* error: Argument of type 'string' is not assignable to parameter of type 'never'.
*/
-
Events
has one or more dataless events.
type Events = {
hello: {
msg: string
},
bye: { }, // first dataless event
someEvent: { }, // second dataless event
someEventWithData: {
counter: number
}
}
. . .
eventer.dispatchEvent('hello');
/* ^^^^^^^
* error: Argument of type '"hello"' is not assignable to parameter of type '"bye" | "someEvent"'.
*/
Firing an event that requires data with wrong data.
eventer.dispatchEvent('hello', { total: 127 });
/* ^^^^^^^^^^
* error: Argument of type '{ total: number; }' is not assignable to parameter of type '{ msg: string; }'.
Object literal may only specify known properties, and 'total' does not exist in type '{ msg: string; }'.
*/
Firing an event that doesn't need data with any data.
In a case where data is provided — in this case — Typescript filters through all events where data is required and checks againts what was found using event names:
-
Events
has no events with data.
type Events = {
bye: { },
strangeEvent: { }
}
. . .
eventer.dispatchEvent('bye', { total: 127 });
/* ^^^^^
* error: Argument of type 'string' is not assignable to parameter of type 'never'.
*/
-
Events
has one or more events with data.
type Events = {
hello: { // event with data 1
msg: string
},
eventWithData: { // event with data 2
data: number
}
bye: { }
}
. . .
eventer.dispatchEvent('bye', { total: 127 });
/* ^^^^^
* error: Argument of type '"bye"' is not assignable to parameter of type '"hello" | "eventWithData"'.
*/
Firing an event that doesn't exist.
Typescript will search for event with a given name and show other events with or without data — depending on whether it was provided.
- No data is provided.
eventer.dispatchEvent('someEvent');
/* ^^^^^^^^^^^
* error: Argument of type '"someEvent"' is not assignable to parameter of type '"bye"'.
*/
- Some data is provided.
eventer.dispatchEvent('someEvent', { someData: 'beep boop' });
/* ^^^^^^^^^^^
* error: Argument of type '"someEvent"' is not assignable to parameter of type '"hello"'.
*/