Documentation / @zerotal/core / index / FrameworkEvents

Variable: FrameworkEvents

const FrameworkEvents: object

Defined in: events/FrameworkEvents.ts:49

The framework instrumentation event bus — subscribe with on, fire with emit. Separate from the class-based Emitter used for application events: this bus is synchronous, static, and carries the framework's own lifecycle signals (QueryExecuted, RequestHandled, JobRan, …) that observability packages subscribe to.

Type Declaration

Dispatch

emit()

emit<E>(event): void

Emit a framework event synchronously to all registered handlers — both those subscribed by class identity and those subscribed by the event's kind string. Errors from handlers are swallowed — subscribers must never affect the caller.

Type Parameters

E

E extends object

Parameters

event

E

The event instance; its constructor (and kind) select the handlers.

Returns

void

Subscription

on()

on<E>(target, handler): () => void

Subscribe to a framework event. Returns an unsubscribe function — call it in provider.onStopping() to avoid handler leaks.

Pass the event class to listen by identity (the usual case, when you own or can import the class), or a string kind to listen without importing the class — the way a decoupled observer (telemetry, the monitor) subscribes to a satellite package's events.

Type Parameters

E

E extends object

Parameters

target

string | ((...args) => E)

The event class to listen for, or its string _kindOf | kind.

handler

Handler<E>

Synchronous callback invoked with each emitted instance.

Returns

A function that removes this subscription when called.

() => void

clear()

clear(): void

Remove all subscriptions. Call in tests to reset state between suites.

Returns

void

handlerCount()

handlerCount(): number

Total number of registered handlers across all event types (class- and kind-keyed). Intended for tests to assert subscriptions were cleaned up.

Returns

number

The count of live handlers across every event type.

Example

import { FrameworkEvents, QueryExecuted } from "@zerotal/core";

// In a provider's onBooting(): watch every SQL query.
const off = FrameworkEvents.on(QueryExecuted, (e) => {
  if (e.durationMs > 100) console.warn(`slow query (${e.durationMs}ms): ${e.sql}`);
});

// In onStopping(): unsubscribe to avoid handler leaks.
off();