bus.emit("case:closed", payload)
bus.on("case:closed", handler)

Use an event bus for notifications, integration boundaries, and fire-and-observe signals.
Do not use it as the default state propagation mechanism.

Siapa owner state setelah event terjadi?
Siapa yang boleh mutate?
Apa invariant-nya?
Apa yang terjadi jika subscriber gagal?
Apa yang terjadi jika event datang dua kali?
Apa yang terjadi jika subscriber belum mounted?
Apa ordering guarantee-nya?

bus.emit("user:changed", user)

bus.on("user:changed", (user) => {
  setCurrentUser(user)
})

const currentUser = useUserStore((s) => s.currentUser)

<AuthProvider user={user}>
  <App />
</AuthProvider>

const userQuery = useCurrentUserQuery()

bus.emit("toast:show", {
  variant: "success",
  message: "Case has been assigned",
})

bus.emit("analytics:user-action", {
  action: "case_assignment_submitted",
  caseId,
})

bus.emit("case:assignment-completed", {
  caseId,
  assigneeId,
})

Jika event bus dipakai agar dua sibling berbicara, coba lift state.
Jika dipakai agar deep child membaca config, coba context.
Jika dipakai untuk server data, coba query cache.
Jika dipakai untuk frequently changing UI state, coba external store.
Jika dipakai untuk multi-step workflow, coba reducer/state machine.
Jika dipakai agar component mana pun bisa mutate apa pun, desain sedang bocor.

bus.emit("update", data)
bus.emit("change", value)
bus.emit("refresh")
bus.emit("modal")

bus.emit("case.assignment.completed", payload)
bus.emit("toast.show.requested", payload)
bus.emit("shell.sidebar.refreshRequested", payload)
bus.emit("analytics.userAction.recorded", payload)

<bounded-context>.<thing>.<fact-or-request>

case.assignment.completed
case.assignment.failed
toast.show.requested
modal.confirmation.requested
shell.navigation.blocked
analytics.userAction.recorded

completed = already happened
requested = asking some owner to do something
failed = already failed
changed = ambiguous; avoid unless the event contract is precise

bus.emit("case.assignment.completed", caseDetail)

bus.emit("case.assignment.completed", {
  caseId,
  assigneeId,
  assignedAt,
  correlationId,
})

type Unsubscribe = () => void

type EventMap = {
  "toast.show.requested": {
    variant: "success" | "error" | "info"
    message: string
  }
  "case.assignment.completed": {
    caseId: string
    assigneeId: string
    correlationId: string
  }
  "analytics.userAction.recorded": {
    action: string
    entity?: string
    entityId?: string
  }
}

type EventName = keyof EventMap

type Handler<T> = (payload: T) => void

export function createEventBus<Events extends Record<string, unknown>>() {
  const listeners = new Map<keyof Events, Set<Handler<any>>>()

  function on<Name extends keyof Events>(
    name: Name,
    handler: Handler<Events[Name]>
  ): Unsubscribe {
    let handlers = listeners.get(name)

    if (!handlers) {
      handlers = new Set()
      listeners.set(name, handlers)
    }

    handlers.add(handler)

    return () => {
      handlers?.delete(handler)
      if (handlers?.size === 0) {
        listeners.delete(name)
      }
    }
  }

  function emit<Name extends keyof Events>(
    name: Name,
    payload: Events[Name]
  ) {
    const handlers = listeners.get(name)

    if (!handlers) return

    // Snapshot protects iteration from subscription changes during emit.
    for (const handler of Array.from(handlers)) {
      handler(payload)
    }
  }

  function listenerCount(name?: keyof Events) {
    if (name) return listeners.get(name)?.size ?? 0

    let count = 0
    for (const handlers of listeners.values()) {
      count += handlers.size
    }
    return count
  }

  return { on, emit, listenerCount }
}

export const appEvents = createEventBus<EventMap>()

appEvents.emit("toast.show.requested", {
  variant: "success",
  message: "Case assigned",
})

import { useEffect, useRef } from "react"

function useLatest<T>(value: T) {
  const ref = useRef(value)
  ref.current = value
  return ref
}

export function useEventBus<Events extends Record<string, unknown>, Name extends keyof Events>(
  bus: {
    on: (name: Name, handler: (payload: Events[Name]) => void) => () => void
  },
  name: Name,
  handler: (payload: Events[Name]) => void
) {
  const latestHandler = useLatest(handler)

  useEffect(() => {
    return bus.on(name, (payload) => {
      latestHandler.current(payload)
    })
  }, [bus, name, latestHandler])
}

export function useEventBus<Events extends Record<string, unknown>, Name extends keyof Events>(
  bus: {
    on: (name: Name, handler: (payload: Events[Name]) => void) => () => void
  },
  name: Name,
  handler: (payload: Events[Name]) => void
) {
  const handlerRef = useRef(handler)
  handlerRef.current = handler

  useEffect(() => {
    return bus.on(name, (payload) => {
      handlerRef.current(payload)
    })
  }, [bus, name])
}

useEffect(() => {
  bus.on("toast.show.requested", showToast)
}, [])

useEffect(() => {
  return bus.on("toast.show.requested", showToast)
}, [])

subscribe -> unsubscribe -> subscribe

export const appEvents = createEventBus<AppEvents>()

const EventBusContext = createContext<AppEventBus | null>(null)

export function EventBusProvider({ children }: { children: React.ReactNode }) {
  const busRef = useRef<AppEventBus | null>(null)

  if (!busRef.current) {
    busRef.current = createEventBus<AppEvents>()
  }

  return (
    <EventBusContext.Provider value={busRef.current}>
      {children}
    </EventBusContext.Provider>
  )
}

export function useAppEvents() {
  const bus = useContext(EventBusContext)
  if (!bus) throw new Error("useAppEvents must be used within EventBusProvider")
  return bus
}

function ToastBridge() {
  const [toasts, setToasts] = useState<Toast[]>([])
  const bus = useAppEvents()

  useEventBus(bus, "toast.show.requested", (event) => {
    setToasts((current) => [
      ...current,
      {
        id: crypto.randomUUID(),
        variant: event.variant,
        message: event.message,
      },
    ])
  })

  return <ToastViewport toasts={toasts} />
}

The bus transports intent.
The bridge owns state.

type ToastState = {
  toasts: Toast[]
}

type ToastAction =
  | { type: "toastQueued"; toast: Toast }
  | { type: "toastDismissed"; toastId: string }

function toastReducer(state: ToastState, action: ToastAction): ToastState {
  switch (action.type) {
    case "toastQueued":
      return { toasts: [...state.toasts, action.toast] }
    case "toastDismissed":
      return { toasts: state.toasts.filter((t) => t.id !== action.toastId) }
    default:
      return state
  }
}

function ToastBridge() {
  const [state, dispatch] = useReducer(toastReducer, { toasts: [] })
  const bus = useAppEvents()

  useEventBus(bus, "toast.show.requested", (event) => {
    dispatch({
      type: "toastQueued",
      toast: {
        id: crypto.randomUUID(),
        variant: event.variant,
        message: event.message,
      },
    })
  })

  return <ToastViewport toasts={state.toasts} onDismiss={(id) => dispatch({ type: "toastDismissed", toastId: id })} />
}

type EventEnvelope<Name extends string, Payload> = {
  name: Name
  payload: Payload
  emittedAt: number
  correlationId?: string
}

type EventObserver<Events extends Record<string, unknown>> = <Name extends keyof Events>(
  envelope: EventEnvelope<Name & string, Events[Name]>
) => void

export function createObservableEventBus<Events extends Record<string, unknown>>(options?: {
  observers?: EventObserver<Events>[]
}) {
  const listeners = new Map<keyof Events, Set<(payload: any) => void>>()
  const observers = options?.observers ?? []

  function emit<Name extends keyof Events>(name: Name, payload: Events[Name]) {
    const envelope: EventEnvelope<Name & string, Events[Name]> = {
      name: name as Name & string,
      payload,
      emittedAt: Date.now(),
      correlationId:
        typeof payload === "object" && payload && "correlationId" in payload
          ? String((payload as any).correlationId)
          : undefined,
    }

    for (const observe of observers) {
      observe(envelope)
    }

    for (const handler of Array.from(listeners.get(name) ?? [])) {
      handler(payload)
    }
  }

  function on<Name extends keyof Events>(name: Name, handler: (payload: Events[Name]) => void) {
    let set = listeners.get(name)
    if (!set) {
      set = new Set()
      listeners.set(name, set)
    }
    set.add(handler)
    return () => set?.delete(handler)
  }

  return { emit, on }
}

bus.emit("toast.show.requested", payload)
// all handlers run before this line finishes

queueMicrotask(() => handler(payload))

Keep emit synchronous, but make handlers small.
Use explicit async work inside subscriber if needed.

for (const handler of handlers) {
  handler(payload)
}

handler(payload)

for (const handler of handlers) {
  try {
    handler(payload)
  } catch (error) {
    reportEventHandlerError({ eventName: name, error })
  }
}

The error policy is part of the event bus contract.
Never leave it accidental.

const user = await bus.request("user.current.get", {})

const user = useCurrentUser()

const auth = useAuthCapability()
const user = auth.getCurrentUserSnapshot()

const userQuery = useCurrentUserQuery()

shellEvents.emit("tenant.changed", {
  tenantId,
  correlationId,
})

shellEvents.on("tenant.changed", ({ tenantId }) => {
  queryClient.clear()
  featureStore.resetForTenant(tenantId)
})

shellEvents.emit("featureA.internalFilter.changed", filter)

Use event bus for shell-level facts and coarse integration events.
Do not use it for another feature's internal component state.

useEventBus(bus, "case.assignment.completed", ({ caseId }) => {
  queryClient.invalidateQueries({ queryKey: ["case", caseId] })
  queryClient.invalidateQueries({ queryKey: ["case-list"] })
})

useEventBus(bus, "case.updated", (caseDetail) => {
  setLocalCase(caseDetail)
})

Event says: something changed.
Cache decides: what data becomes stale.
Query decides: when/how to refetch.
Component reads: from cache.

type EventMeta = {
  correlationId: string
  source: "case-page" | "sidebar" | "shell"
}

it("notifies subscribers", () => {
  const bus = createEventBus<{
    "toast.show.requested": { message: string }
  }>()

  const received: string[] = []

  const unsubscribe = bus.on("toast.show.requested", (event) => {
    received.push(event.message)
  })

  bus.emit("toast.show.requested", { message: "Saved" })
  unsubscribe()
  bus.emit("toast.show.requested", { message: "Ignored" })

  expect(received).toEqual(["Saved"])
})

it("renders toast when toast event is emitted", async () => {
  const bus = createEventBus<AppEvents>()

  render(
    <EventBusContext.Provider value={bus}>
      <ToastBridge />
    </EventBusContext.Provider>
  )

  act(() => {
    bus.emit("toast.show.requested", {
      variant: "success",
      message: "Saved",
    })
  })

  expect(screen.getByText("Saved")).toBeInTheDocument()
})

Test event transport separately from UI state ownership.

1. Why are props/context/store/query cache not enough?
2. Is this event a request or a fact?
3. Who owns the resulting state?
4. Is the payload small and versionable?
5. What happens if no subscriber exists?
6. What happens if two subscribers exist?
7. What happens if handler throws?
8. Is event ordering important?
9. Can the event be emitted twice safely?
10. Is this observable in logs/devtools/tests?

No component prop/context shows dependency, but behavior changes when an event fires.

Move state to explicit owner: component, context, external store, or query cache.

One action emits event A, which causes event B, which causes event C.

Move orchestration into reducer/state machine/workflow service.

Handler fires multiple times after navigation.

Always return unsubscribe from Effect.

Subscriber sees old props/state.

Use latest-ref pattern or resubscribe intentionally with correct dependencies.

Event emitted before bridge mounts; event disappears.

If event must be durable, it is not an event bus problem. Use state/store/queue/cache.

App only works if subscriber X runs before subscriber Y.

Make ordering explicit in a coordinator, reducer, or state machine.

Event payload is entire domain aggregate or API response.

Emit stable identifiers and minimal fact context.

bus.emit("filter.changed", filter)

<SearchPage>
  <FilterPanel value={filter} onChange={setFilter} />
  <ResultTable filter={filter} />
</SearchPage>

bus.emit("permission.check", { action, resource })

const permissions = usePermissions()
const canAssign = permissions.can("case.assign", caseView)

bus.emit("selection.changed", selection)

const selection = useSelectionStore((s) => s.selection)
const select = useSelectionStore((s) => s.select)

bus.emit("case.updated", updatedCase)

bus.emit("case.updated", { caseId })
queryClient.invalidateQueries({ queryKey: ["case", caseId] })

bus.emit("wizard.next")
bus.emit("wizard.validation.failed")
bus.emit("wizard.submitted")

send({ type: "NEXT" })
send({ type: "VALIDATION_FAILED", errors })
send({ type: "SUBMIT" })

Events announce.
Owners decide.
State renders.