dot-event

dot-event

Prop-based asynchronous event emitter.

Install

npm install --save dot-event

Emitter

import Emitter from "dot-event"
const emitter = new Emitter()

Emit

emitter.on(() => {})
emitter.emit()

Cheatsheet

Terms	Functions
Emitter	emit, emitAny, emitOn, emitAnyOn
Subscriber	on, onAny, once, onceEmitted, onceAny, onceAnyEmitted
Setter	op

Subscribers and emitters take one, some, or none of these arguments:

Argument type	Description	Emitter	Subscriber
String	Preposition (before, after)		✔
String	Operation	✔	✔
String	Props (period-separated ids)	✔	✔
Object	Subscription options	✔	✔
Function	Subscription listener		✔

All the features together:

// Define operations
emitter.op("create")

// Subscriber
emitter.on(
  "before",         // Preposition
  "create",         // Operation
  "my.prop.id",     // Props
  { x: true }       // Subscription options
  ({ x, y }) => {}, // Subscription listener
)

// Emitter
emitter.emit(
  "create",     // Operation
  "my.prop.id", // Props
  { y: true }   // Susbcription options
)

// Emitter shortcut
emitter.create("my.prop.id", { y: true })

Subscription listeners can be asynchronous. Emitters return a promise that resolves once listeners resolve concurrently.

Subscription listeners receive a single object argument. The object contains subscription options and an event property with extra info.

There are some features we haven't covered, so keep reading...

Emit options

emitter.on(({ hello }) => {})
emitter.emit({ hello: "world" })

You may define default options from the subscriber as well:

emitter.on(({ hello }) => {}, { hello: "world" })
emitter.emit()

Emit once

emitter.once(() => {})
emitter.emit() // emits
emitter.emit() // doesn't emit

Emit once emitted

Fire immediately if previously emitted:

emitter.emit()
emitter.onceEmitted(() => {}) // emits immediately

Subscribe before or after

Subscribe to before or after the main emit:

emitter.on("before", () => {})
emitter.on(() => {})
emitter.on("after", () => {})
emitter.emit()

Emit prop

Any subscriber can use a prop identifier:

emitter.on("hello", () => {})
emitter.emit("hello") // emits
emitter.emit() // doesn't emit

Emit any

Subscribe to any prop change:

emitter.onAny(() => {})
emitter.emit("hello") // emits
emitter.emit("hello.world") // emits

Subscribe to any prop change within a prop:

emitter.onAny("hello", () => {})
emitter.emit("hello.world") // emits
emitter.emit() // doesn't emit

Emit once any

emitter.onceAny("hello", () => {})
emitter.emit("hello.world") // emits
emitter.emit("hello.world") // doesn't emit

Emit once any emitted

Subscribe to any prop change within a prop, and fire immediately if previously emitted:

emitter.emit("hello.world")
emitter.onceAnyEmitted("hello", () => {}) // emits immediately

Emit operation

An "operation" is another way to segment your events.

Define your operation (only do this once):

emitter.op("create")

Operations add a nifty shortcut function:

emitter.on("create", () => {})
emitter.emit("create") // emits
emitter.create() // emit with shortcut

Subscriber shorthand

Build lots of subscribers at once:

emitter.on([
  [() => {}],
  ["hello.world", () => {}],
  ["create", "hello.world", () => {}],
  ["after", "create", "hello.world", () => {}],
])