📄 $eventbus – Event Communication API

The $eventbus enables decoupled communication between different parts of your plugin and the entire application.

It is based on a lightweight EventEmitter pattern.

---

🧠 Core Concept

Instead of directly calling functions across modules:

👉 emit events → listen → react

---

🔧 Basic Usage

$eventbus.on("myEvent", (payload) => {
  console.log(payload)
})

$eventbus.emit("myEvent", { foo: "bar" })

---

🌍 Global vs Local

Plugin-local events

$eventbus.on(...)
$eventbus.emit(...)

• scoped to your plugin
• no global side effects

---

Global events

$eventbus.global.on(...)
$eventbus.global.emit(...)

• shared across all plugins
• automatically enriched with sender info

$eventbus.global.emit("ui/addToSnackbar", {
  message: "Hello",
})

Payload becomes:

{
  sender: "<pluginKey>",
  data: { message: "Hello" }
}

---

📡 API Methods

on

const remove = $eventbus.on("event", callback)

• registers listener
• returns cleanup function

---

emit

$eventbus.emit("event", payload)

• triggers all listeners

---

once

$eventbus.once("event", callback)

• triggers only once
• auto-removes listener
• timeout fallback (~5s)

---

removeListener

remove()

• unregisters listener

---

🔁 Typical Patterns

UI communication

$eventbus.global.emit("ui/addToSnackbar", {
  message: "Saved!",
  color: "green",
})

---

Cross-component sync

$eventbus.on("todoUpdated", () => {
  execute()
})

---

One-time event

$eventbus.once("initDone", () => {
  console.log("Initialized")
})

---

🧠 Event Validation

• Events can be restricted via whitelist
• Wildcards are supported
• Invalid events may throw errors

---

🧠 Mental Model

• $eventbus = internal messaging system
• decouples components and services
• avoids tight coupling

---

⚖️ When to Use $eventbus

Use it for:

• UI interactions (snackbars, dialogs)
• cross-component communication
• plugin-wide events
• global app events

---

🚫 Important Notes

• Events are not reactive
• No persistence (fire-and-forget)
• Overuse can make flow hard to trace

---

🧠 Key Takeaway

$eventbus enables flexible, decoupled communication

👉 Think: emit → listen → react