Events

Overview

Katal includes a lightweight event bus for synchronous and asynchronous listeners.

Quick Start

import { Application } from "katal";

const app = new Application({ port: 3000 });

app.on<{ userId: string }>("user.created", async (payload) => {
    console.log("send welcome email", payload.userId);
});

app.once("app.ready", () => {
    console.log("App became ready");
});

await app.emit("user.created", { userId: "u-123" });
app.emitSync("app.ready", undefined);

API

app.on(eventName, listener)

Register a persistent listener.

app.once(eventName, listener)

Register a listener that runs only once.

app.off(eventName, listener?)

Remove a specific listener or all listeners for an event.

await app.emit(eventName, payload)

Emit asynchronously. Supports both sync and async listeners.

app.emitSync(eventName, payload)

Emit synchronously. Throws if a listener returns a Promise.

Access via Container

const events = app.resolve("events");

Notes

  • Listener execution order follows registration order.
  • emit awaits each listener sequentially.
  • Use emitSync only for strictly synchronous flows.
  • Errors thrown inside listeners propagate to the emit caller.

See Also