Events

Some concerns cut across every bloc: “user logged out → reset all session-scoped state,” “workspace switched → every open panel should re-sync.” watch/onSystemEvent describe a single container’s own lifecycle; they are the wrong tool for “broadcast this and let whoever cares react.” defineEvent/emitEvent/onEvent are the typed pub/sub for exactly that, and this.on(...) is the owner-scoped form that ties a subscription to a container’s lifetime.

This replaces “walk every live instance and call a magic method if present” bus patterns: dispatch cost here is O(subscribers for that token), never O(all live instances), and every handler is typed to the token’s payload.

defineEvent(name)

Create a typed event token.

function defineEvent<P = void>(name: string): EventToken<P>;

Parameter	Type	Required	Description
name	string	yes	A human-readable identifier for the event, used in error messages and logs.

Returns: an EventToken<P> — an opaque handle carrying the payload type P. Define tokens once, at module scope, and import them wherever you emit or listen.

import { defineEvent } from '@blac/core';

// A payload-carrying token
const UserLoggedOut = defineEvent<{ userId: string }>('UserLoggedOut');

// A payload-less token
const AppResumed = defineEvent('AppResumed');

emitEvent(token, payload?)

Broadcast an event to every current subscriber of that token.

function emitEvent<P>(
  token: EventToken<P>,
  ...payload: 0 extends 1 & P // isAny
    ? [payload?: unknown]
    : [P] extends [void]
      ? []
      : [P]
): void;

Parameter	Type	Required	Description
token	EventToken<P>	yes	The token to dispatch on.
payload	P	when P is not void	Typed payload. Omitting it for a payload-carrying token is a compile error.

Returns: void.

Behavior. Dispatch is synchronous and runs subscribers in registration order. It costs nothing if there are no subscribers — emitEvent on a token nobody listens to is a cheap no-op, not a registry walk. Each handler runs in its own try/catch: a throwing handler is isolated (it logs to console.error and the remaining handlers still run — no handler is ever silently skipped by another’s bug). Re-entrant emitEvent/onEvent calls from inside a handler are safe: dispatch iterates a snapshot of the subscriber set taken at the start of the call, so a handler that subscribes a new listener during dispatch does not get that listener invoked for the in-flight emit.

import { defineEvent, emitEvent } from '@blac/core';

const UserLoggedOut = defineEvent<{ userId: string }>('UserLoggedOut');

emitEvent(UserLoggedOut, { userId: 'user-42' });

const AppResumed = defineEvent('AppResumed');

emitEvent(AppResumed); // void payload — no second argument

onEvent(token, handler)

Subscribe to an event from outside a container (scripts, tests, other infrastructure).

function onEvent<P>(token: EventToken<P>, handler: (payload: P) => void): () => void;

Parameter	Type	Required	Description
token	EventToken<P>	yes	The token to listen for.
handler	(payload: P) => void	yes	Called with the typed payload on emit.

Returns: a () => void unsubscribe function. Calling it more than once is safe (idempotent).

import { defineEvent, emitEvent, onEvent } from '@blac/core';

const UserLoggedOut = defineEvent<{ userId: string }>('UserLoggedOut');

const off = onEvent(UserLoggedOut, ({ userId }) => {
  console.log('logged out:', userId);
});

emitEvent(UserLoggedOut, { userId: 'user-42' });

off(); // stop listening

this.on(token, handler) — the owner-scoped form

Inside a container, prefer this.on(...) over the standalone onEvent: the subscription is automatically torn down when the container disposes, so there is no manual off to remember in consumer code.

import { Cubit, defineEvent } from '@blac/core';

const UserLoggedOut = defineEvent<{ userId: string }>('UserLoggedOut');

interface SessionState {
  userId: string | null;
}

class SessionCubit extends Cubit<SessionState> {
  constructor() {
    super({ userId: null });

    // Auto-unsubscribed on dispose — no manual teardown needed here.
    this.on(UserLoggedOut, () => {
      this.update(() => ({ userId: null }));
    });
  }
}

Behavior. this.on is protected — only callable from inside the class. It listens on this container’s own registry (the one it was constructed in), not whichever registry happens to be ambient, so a container always reacts to events on the bus of the registry it belongs to — this matters for test isolation (withTestRegistry/blacTestSetup). A disposed container never receives events: dispose fires its 'dispose' handlers (which includes the unsubscribe registered by this.on) before anything else runs, so the subscription is already gone by the time any later emit happens. A keepAlive container keeps receiving events for as long as it stays alive — nothing special to do.

Dispatch semantics

• Ordering. Handlers for a token run in the order they were registered.
• Isolation. A throwing handler does not stop the others; the error is logged and dispatch continues.
• Cost. O(subscribers for the token). Emitting an event with zero subscribers costs nothing extra — there is no per-instance walk anywhere in the path.
• Re-entrancy. emitEvent called from inside a handler runs synchronously and completes before the outer dispatch resumes. A handler that registers a new onEvent/this.on during dispatch is not called for the emit that’s already in flight.
• Registry isolation. Subscriptions are scoped per registry, so two independent test registries (withTestRegistry, blacTestSetup) never see each other’s subscribers.

See also

• System Events — per-instance lifecycle hooks (onSystemEvent), the counterpart for a container’s own state/dispose/hydration transitions
• Bloc Communication — depend() and cross-bloc composition for concerns that aren’t cross-cutting broadcasts
• Testing core logic — withTestRegistry/blacTestSetup and why event subscriptions are isolated per registry