Typed, async, and promiseable events for Deno.
deno cache -r https://deno.land/x/mutevents/mod.ts
import { EventEmitter } from "https://deno.land/x/mutevents/mod.ts";
interface AnimalEvents {
death: string
}
class Animal extends EventEmitter<AnimalEvents> {
async die(){
return await this.emit("death", "I'm dead!")
}
}
const animal = new Animal()
animal.on(["death"], (text) => console.log(text))
const [msg, cancelled] = await animal.die()
if(cancelled) console.error(cancelled)type EventPriority =
"before" | "normal" | "after";
type EventResult<T, K extends keyof T> =
[data: T[K], cancelled?: Cancelled]
type EventListener<V> =
(x: V) => unknown | Promise<unknown>
// Emit an event with the given args, returns a Cancelled object if cancelled
emitter.emit(event, data): Promise<EventResult>
// Synchronously emit an event with the given args, returns a Cancelled object if (synchronously) cancelled
emitter.emitSync(event, data): EventResult
// Add a listener on the given event and priority, returns a removal function
emitter.on([event, priority], ...listeners: EventListener[]): () => void
// Add a listener that removes itself when executed, returns a removal function
emitter.once([event, priority], ...listeners: EventListener[]): () => void
// Abortable promise that resolves (with the result) when the given event type is emitted
emitter.wait([event, priority], filter: (data) => boolean): Abortable (Promise)
// Abortable promise that rejects (with the result) when the given event type is emitted
emitter.error([event, priority], filter: (data) => boolean): Abortable (Promise)
// Shortcut for creating an event listener that reemits the data on the given event type
emitter.reemit(event): EventListener
// Shortcut for creating an event listener that synchronously reemits the data on the given event type
emitter.reemitSync(event): EventListenerTypes are useful with TypeScript autocompletion and compiler warnings. Plus, they allow you to inherit events from a superclass.
We define a generic type Animal with a "death" event type
interface AnimalEvents {
death: void // No arguments passed
}Using inheritance
class Animal<E extends AnimalEvents = AnimalEvents> extends EventEmitter<E> {
async die(){
return await this.emit("death", undefined)
}
}Or a field
class Animal<E extends AnimalEvents = AnimalEvents> {
events: new EventEmitter<E>()
// ...
}Then we define a type Dog that extends Animal with a "woof" event type.
interface DogEvents extends AnimalEvents /*<- This is important*/ {
woof: string // Argument type of the "woof" event
}
class Dog extends Animal<DogEvents> {
async woof(text: string){
return await this.emit("woof", text)
}
}Dog can now emit two event types: "woof" and "death"
In order to avoid memory leaks, you must clean up your garbage!
You can achieve this by running the removal functions.
One method to do so is to call them all once a certain event happens (usually a "close", "quit", "finish" event that happens once)
class Connection extends EventEmitter<{
message: string
close: undefined
}> {}
const offmessage = connection.on(["message"],
(text) => console.log(text))
connection.once(["close"], offmessage)You can also call multiple removal functions at once
type Location = [number, number, number]
class Player extends EventEmitter<{
spawn: Location
death: Location
quit: Location
}> {}
const offspawn = player.on(["spawn"],
([x, y, z]) => console.log("Spawn:", x, y, z))
const offdeath = player.on(["death"],
([x, y, z]) => console.log("Death:", x, y, z))
player.once(["quit"], offspawn, offdeath)An event listener can have a priority:
- "before"
- "normal"
- "after"
The priority must be defined in the array after the event name. If no priority is defined, "normal" will be used.
Example
dog.on(["woof"], () => console.log("Normal"));
dog.on(["woof", "after"], () => console.log("Last"));
dog.on(["woof", "before"], () => console.log("First"));When multiple listeners are on the same priority, the first defined will be the first executed.
dog.on(["woof", "before"], () => console.log("First"));
dog.on(["woof", "before"], () => console.log("Last"));Any event can be cancelled by any listener. The listener needs to throw something. The next listener will not be executed, and the emit() will also throw.
If you want to cancel an event without throwing an error, there is a special Cancelled object with an optional reason field. Such object will not be thrown on the emitter side.
dog.on(["woof"], () => {
throw new Cancelled("...");
});
dog.on(["woof"], () => {
console.log("This won't be displayed")
});You can check for cancellation on the emitter side
const [data, cancelled] = await dog.emit("woof");
if (cancelled) console.error("cancelled")Or rethrow it
const [data, cancelled] = await dog.emit("woof");
if (cancelled) throw cancelled;See test/connection.ts and test/bingo.ts
You can wait for an event and resolve/reject when it happens.
await emitter.wait("event") // Will resolve when "event" is emitted
await emitter.error("event") // Will reject when "event" is emittedSuch promises are abortables, so you can race them and abort them when done.
// @test/connection.ts
// Wait for a message until the connection is closed
// Removing both listeners when one of them fullfills
async read() {
const message = this.wait("message")
const close = this.error("close")
return await Abort.race([message, close])
}You can also race them with a timeout from https://deno.land/x/timeout
Since Timeout uses Abortable, all listeners are removed when the delay is exceeded
// @test/connection.ts
// Wait for a message until the connection is closed OR the delay is exceeded
// Removing both listeners and clearing the timeout when one of them fullfills
// Throws TimeoutError if the delay is exceeded
async request() {
const response = this.wait("message")
const close = this.error("close")
return await Timeout.race([response, close], 1000)
}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent