ts-events

A simple Emitter/Receiver library for Typescript.

Setup

> npm install @nealrame/ts-events

API

createEmitterReceiver

Get a pair of emitter and receiver.

Synopsys

function createEmitterReceiver<T extends TEventMap>(): [TEmitter<T>, IReceiver<T>]

Example

interface MyEvents {
    "event1": number
    "event2": string
}
const [emit, receiver] = createEmitterReceiver<MyEvents>()

receiver.on("event1", data => { /* ... */ })   // called every time event1 is emitted
receiver.once("event2", data => { /* ... */ }) // called once

emit("event1", 42)
emit("event2", "foo")

TEventMap

An EventMap type is used to type subscriptions to events as well as their emissions.

type MyEvents = {
    event1: string
    event2: {
        x: number
        y: number
    }
}
const [emit, receiver] = createEmitterReceiver<MyEvents>()

receiver.on("event1", data => {
    console.log(data.toUpperCase())
}) // Ok

receiver.once("event2", data => {
    console.log(data.z)
}) // Error: Property 'z' does not exist on type '{ x: number; y: number; }'.

emit(event1, "test") // Ok

emit(event2, {
    x: 1,
    z: 2,
}) // Error: Argument of type '{ w: number; y: number; }' is not assignable to parameter of type '{ x: number; y: number; }'

If no EventMap type is specified, there will be no type checking.

const [emit, receiver] = createEmitterReceiver()

receiver.on("event1", data => { ... })   // data type is any
receiver.once("event2", data => { ... }) // data type is any

emit(event1, { r: 0xb4, g: 0xd4, b: 0x55 })
emit(event2, 3.14)

TEmitter

Synopsis

function emit(event, data)

Example

const [emit, receiver] = createEmitterReceiver<{
    event1: number
}>()

emit("event1", 3.14)

IReceiver

on

Subscribe to a given event.

Synopsis

function on(event, callback): EventListenerUnsubscribeCallback

Parameters

• event: an event name
• callback: a callback function

Return

A function to end subscription to the event.

Example

const [emitter, receiver] = createEmitterReceiver<{
    event1: number
}>()

const callback = (value: number) => console.log(value)

const unsubscribe = receiver.on("event1", callback)

unsubscribe() // end event1 subscription

once

Subscribe to a given event once.

Synopsis

function once(event, callback): EventListenerUnsubscribeCallback

Parameters

• event: an event name
• callback: a callback function

Return

A function to end subscription to the event.

Example

const [emitter, receiver] = createEmitterReceiver<{
    event1: number
}>()

const callback = (value: number) => console.log(value)

const unsubscribe = receiver.once("event1", callback)

unsubscribe() // end event1 subscription

off

Synopsis

function off(): void
function off(event): void
function off(event, callback): void

Parameters

• event: an event name
• callback: a callback function

Example

const [emitter, receiver] = createEmitterReceiver<{
    event1: number
    event2: number
}>()

const callback10 = (value: number) => console.log(value)
const callback11 = (value: number) => console.log(value)
const callback12 = (value: number) => console.log(value)
const callback20 = (value: number) => console.log(value)

receiver.on("event1", callback10)
receiver.on("event1", callback11)
receiver.on("event1", callback12)

receiver.on("event2", callback20)

receiver.off("event1", callback10) // after this callback11 and callback12 still being called
receiver.off("event1") // after this no more callbacks will be called for event1
receiver.off() //after this no more callbacks will be called for any events

connect

Connect a set of events of a receiver to handlers using a mapping.

Synopsis

function connect(eventHandlers): void

Parameters

• eventHandlers: map events to handlers

Example

type MyEvents = {
    event1: string
    event2: {
        x: number
        y: number
    }
    event3: number
}
const [emit, receiver] = createEmitterReceiver<MyEvents>()

receiver.connect({
    event1(value: string) {
        console.log("event1", value)
    },
    event2({ x, y }) {
        console.log("event2", x, y)
    }
})

disconnect

Disconnect a set of events of a receiver from handlers using a mapping.

Synopsis

function disconnect(eventHandlers): void

Parameters

• eventHandlers: map events to handlers

Example

type MyEvents = {
    event1: string
    event2: {
        x: number
        y: number
    }
    event3: number
}
const [emit, receiver] = createEmitterReceiver<MyEvents>()
const eventHandlers = {
    event1(value: string) {
        console.log("event1", value)
    },
    event2({ x, y }) {
        console.log("event2", x, y)
    }
}

receiver.connect(eventHandlers)
receiver.disconnect(eventHandlers)