Powerful event emitter.
npm install --save dot-eventPart of the beauty of the dot-event API is that it can shrink down to incredibly simple functionality.
Here we have the simplest possible subscriber and emitter:
import dotEvent from "dot-event"
const events = dotEvent()
events.on(() => {
/* do something */
})
events.emit()Subscription listeners can be asynchronous:
events.on(async () => {})
await events.emit()The emitter returns a promise that waits for all listeners to resolve concurrently.
Use dot-props to maintain distinct subscriptions:
events.on("emit.hello.world", () => {})
events.emit("hello.world") // emits
events.emit() // doesn't emitDot-props come in handy with the onAny subscriber, which subscribes to a dot-prop and its child props:
events.onAny("emit.hello", () => {})
events.emit("hello") // emits
events.emit("hello.world") // emits
events.emit() // doesn't emitYou might be confused why this subscription prop is emit.hello:
events.on("emit.hello", () => {})
events.emit("hello") // emitsThis is because emit is an "operation", and you can have more than one.
First, define your custom operation:
events.setOp("create")Then use it:
events.on("create", () => {})
events.create() // emits the create operationSubscription listeners receive a single object argument. To add to that object, pass an object to the emitter:
events.on(({ hello }) => {
/* hello === "world" */
})
events.emit({ hello: "world" })The listener argument also contains an event property with extra information, such as the emitter arguments:
events.on(({ event }) => {
/* event.args === [true] */
})
events.emit(true)Subscribe to before or after the main subscription listener:
events.on("before", () => {
/* 1 */
})
events.on(() => {
/* 2 */
})
events.on("after", () => {
/* 3 */
})
events.emit()Subscribe to any emit:
events.onAny(() => {})
events.emit() // emits
events.emit("hello") // emits
events.emit("hello.world") // emitsWhen used with a dot-prop, it subscribes to any child prop emit:
events.onAny("emit.hello", () => {})
events.emit("hello") // emits
events.emit("hello.world") // emits
events.emit() // doesn't emitLike on, but emit immediately if a previous emit occurred:
events.emit()
events.onEmitted(() => {}) // emits immediately
events.emit() // emitsLike onAny, but emit immediately if a previous emit occurred:
events.emit("hello.world")
events.onAnyEmitted("emit.hello", () => {}) // emits immediately
events.emit("hello.world") // emits
events.emit() // doesn't emitevents.once(() => {})
events.emit() // emits
events.emit() // doesn't emitLike once, but emit immediately if a previous emit occurred:
events.emit()
events.onceEmitted(() => {}) // emits immediately
events.emit() // doesn't emitA combination of once and onAny:
events.onceAny("emit.hello", () => {})
events.emit("hello.world") // emits
events.emit("hello.world") // doesn't emitA combination of once, onAny, and onEmitted:
events.emit("hello.world")
events.onceAnyEmitted("emit.hello", () => {}) // emits immediately
events.emit("hello.world") // doesn't emitBuild lots of dot-prop subscriptions at once:
events.on({
"emit.hello": () => {},
"emit.hello.world": () => {},
})| Function | Features | Empty | Props | Wildcard | Prop variable | Wildcard op |
|---|---|---|---|---|---|---|
after |
Subscribes to after emit | ✗ | ✗ | ✗ | ✗ | ✗ |
before |
Subscribes to before emit | ✗ | ✗ | ✗ | ✗ | ✗ |
emit |
Emits | ✗ | ✗ | ✗ | ✗ | ✗ |
on |
Subscribes | ✗ | ✗ | ✗ | ✗ | ✗ |
onAny |
Subscribes to child props | ✓ | ✓ | ✓ | ✓ | ✓ |
onAnyEmitted |
Subscribes to child prop Emit immediately if emitted |
✓ | ✓ | ✓ | ✓ | ✓ |
onEmitted |
Emit immediately if emitted | ✗ | ✗ | ✗ | ✗ | ✗ |
once |
Subscribes once Returns promise |
✗ | ✗ | ✗ | ✗ | ✗ |
onceAny |
Subscribes to child props once Returns promise |
✓ | ✓ | ✓ | ✓ | ✓ |
onceAnyEmitted |
Subscribes to child props once Emit immediately if emitted Returns promise |
✓ | ✓ | ✓ | ✓ | ✓ |
onceEmitted |
Subscribes to child props once Emit immediately if emitted Returns promise |
✗ | ✗ | ✗ | ✗ | ✗ |
withOptions |
Adds options to emit Adds options to subscribe |
✗ | ✗ | ✗ | ✗ | ✗ |