dot-event v3.2.2

dot-event

Javascript event emitter, foundation of everything.

What is it?

Dot-event creates interfaces for listening to and emitting events.

Dot-event listeners can be synchronous or asynchronous, accept arguments, and return values.

Dot-event has a tiny footprint (<1 kb compressed and gzipped).

Write less code

Event listeners may emit any event through the dot argument, resulting in less require calls and easy access to functionality across your application.

Event id & props

Dot-event optionally uses event id and prop string(s) to add identifying context to an emit. Props pay off with logging, store updates, and even dom element ids.

Dynamic composition

Dot-event uses a composer function pattern to add event listeners. This pattern works very well with dynamic imports to create dot-event instances with dynamic functionality.

State

Dot-event provides basic state via the dot.state object. On this object we built an immutable store that leverages props and is only ~1 kb compressed and gzipped.

SSR-ready

Its simple to wait for all dot-event listeners before rendering the final version of your server side page.

Setup

const dot = require("dot-event")()

Basics

dot.on(() => {}) // listener
dot() // emitter

Return value

dot.on(() => "value")
dot() // "value"

Async return value

dot.on(async () => "value")
dot().then(result => /* "value" */)

Event id

The event id is the first string argument to dot.on or dot.any.

dot.on("myEvent", () => "value")
dot("myEvent") // "value"

ℹ️ The listener function receives the event id as its fourth argument.

Listener arguments

No matter what is passed to the dot emitter, listener functions always receive five arguments:

Props

String arguments after the event id are prop identifiers.

dot.on("myEvent", "prop", prop => prop)
dot("myEvent", "prop") // [ "prop" ]

ℹ️ The listener function receives the prop array as its first argument.

Emit argument

The last non-prop argument becomes the emit argument (arg).

dot.on((prop, arg) => arg)
dot({ option: true }) // { option: true }

ℹ️ The listener function receives the emit argument as its second argument.

Signal argument

dot.on((prop, arg, dot, eventId, signal) => {
  signal.cancel = true
  return "value"
})
dot.on(() => "never called")
dot() // "value"

ℹ️ There is one other signal, signal.value, which you can set instead of using return in your listener function.

Any

dot.any(() => "!")
dot("myEvent", "prop") // "!"

Any with event id

dot.any("myEvent", prop => prop)
dot("myEvent", "prop") // [ "prop" ]
dot.myEvent("prop") // <-- cool helper function!

ℹ️ Dot-event creates a helper function only if dot.any receives an event id with no props.

Any with props

dot.any("myEvent", "prop", "prop2", props => props)
dot("myEvent") // noop
dot("myEvent", "prop") // noop
dot("myEvent", "prop", "prop2") // [ "prop", "prop2" ]
dot("myEvent", "prop", "prop2", "prop3") // [ "prop", "prop2", "prop3" ]

Composer pattern

A common pattern is for composers to define listeners that respond to any props of a particular event id.

export default function(dot) {
  dot.any("myEvent", myEvent)
}

async function myEvent(prop, arg, dot) {
  prop = prop.concat(["myEvent"])
  await dot.otherEvent(prop)
}

ℹ️ Another common pattern illustrated here is to append a prop id before passing them along to another emit.

Dynamic imports

dot.add(import("./myEvent"))

ℹ️ You might need to run node with --experimental-modules to enable dynamic imports server side.

Wait for pending events

await Promise.all([...dot.state.events])

ℹ️ dot.state.events is a Set of promises.

Dot composers