jaset

jaset (_just a strict event target_) is a simple, type-safe implementation of EventTarget with zero dependencies and select enhancements^✨ for a better developer experience — including short-form method names, event muting, an optional wildcard event type and more.

Installation

``sh
npm i jaset
`

See Package exports for a list of all package exports.

Usage

You can use jaset just like you would use EventTarget with the addition of providing an event map.

`ts
import EventTarget, { type EventMap } from "jaset"

class MyEventTarget extends EventTarget {}

type MyEventMap = EventMap<{
"my-event": MyEvent
}>

const myEventTarget = new MyEventTarget()

// ✅ "my-event" is a valid event type: No complaints.
myEventTarget.on("my-event", (event) => {
// ✅ event is MyEvent and not just any Event.
})

// ⛔️ "foo" is not a valid event type: TypeScript error.
myEventTarget.on("foo", (event) => {
// ...
})
`

$3

jaset supports events that extend Event.

`ts
class MyEvent extends Event {
constructor() {
super("my-event")
}
}
`

If you prefer to use CustomEvent, just use it directly in your event map.

`ts
type MyEventMap = EventMap<{
"my-event": CustomEvent
}>
`

$3

Documentation

`ts
myEventTarget.on("my-event", onMyEvent)
myEventTarget.addEventListener("my-event", onMyEvent)

function onMyEvent(event: MyEvent) {
// ...
}
`

> [!NOTE]
> Just like it is the case with EventTarget, an attempt to add the same event listener twice will be ignored without throwing an error.

#### Once

_Once_ event listeners are listeners that are only invoked once and then removed.

Documentation

`ts
myEventTarget.once("my-event", onMyEvent)
myEventTarget.addEventListener("my-event", onMyEvent, { once: true })
`

$3

Documentation

`ts
myEventTarget.emit(new MyEvent())
myEventTarget.dispatchEvent(new MyEvent())
`

$3

Documentation

`ts
myEventTarget.off("my-event", onMyEvent)
myEventTarget.removeEventListener("my-event", onMyEvent)
`

$3

You can remove all event listeners for a specific event type.

`ts
myEventTarget.clear("my-event")
`

$3

A Map of event types to event listeners is available via eventListeners:

`ts
myEventTarget.eventListeners
// Map
`

> [!NOTE]
> This map only contains active event listeners. Event types are removed once their last event listener is removed. Wildcard event listeners, if present, are also included in this map with an event type of "*".

$3

You can mute all events of a certain type, allowing you to prevent all event listeners from invoking until you unmute.

`ts
// Mute. 🔇
myEventTarget.mute("my-event")

// Ignored. 🙈
myEventTarget.emit(new MyEvent())

// Unmute. 🔊
myEventTarget.unmute("my-event")
`

A Set of all muted event types is available via mutedEventTypes:

`ts
myEventTarget.mutedEventTypes
// Set
`

$3

With the optional wildcard event type ("*") you can reference all event types at once. This is supported by all jaset methods, except emit() and dispatchEvent().

`ts
myEventTarget.on("*", onAnyEvent)
myEventTarget.off("*", onAnyEvent)
myEventTarget.clear("*")
myEventTarget.mute("*")
myEventTarget.unmute("*")

function onAnyEvent(event: MyEvent | MyOtherEvent) {
// Eyes on everyone. 👀
}
`

> [!IMPORTANT]
> The wildcard event type is disallowed by default for cleaner IntelliSense suggestions. You can allow it by setting the generic type parameter AllowWildcardEventType to true.

`ts
import EventTarget from "jaset"

class MyEventTarget extends EventTarget<
MyEventMap,
/ AllowWildcardEventType / true
> {}
`

$3

You can combine multiple event maps when extending the jaset event target.

`ts
import EventTarget, { type EventMap } from "jaset"

class MyEventTarget<
MyEventMap extends EventMap,
> extends EventTarget {}

type BaseEventMap = EventMap<{
"my-event": MyEvent
}>

class MyEventTargetExtension extends MyEventTarget {}

type ExtensionEventMap = EventMap<{
"my-other-event": MyOtherEvent
}>

const myEventTarget = new MyEventTargetExtension()

myEventTarget.on("my-event", () => {}) // ✅
myEventTarget.on("my-other-event", () => {}) // ✅
myEventTarget.on("foo", () => {}) // ⛔️
`

Combining event maps can be useful when designing an interface where clients should be able to extend the base event map you define.

You can prevent clients from being able to override entries from the base event map by utilizing Omit:

`ts
class MyEventTarget<
MyEventMap extends Omit, keyof BaseEventMap>,
> extends EventTarget {}
`

Package exports

The jaset package exports the following:

- Event target class

`ts
import EventTarget from "jaset"
// or
import { EventTarget } from "jaset"
`

- Map of event types to events (type only)

`ts
import type { EventMap } from "jaset"
`

Used for defining custom event maps.

`ts
type MyEventMap = EventMap<{
"my-event": MyEvent
}>
`

When the type parameter of EventMap is omitted, the event map becomes Record`.