@zerotal/core 1.0.0

package/src/events/Emitter.ts

@@ -0,0 +1,280 @@
+/**
+ * The class-based, typed application event emitter: events are plain classes,
+ * listeners are classes with a `handle()` method, and dispatch can run async
+ * (fire-and-forget), synchronously, or be deferred to a queue.
+ */
+import { CallQueuedListener } from "./CallQueuedListener.ts";
+
+type EventClass<T extends object> = new (...args: unknown[]) => T;
+type ListenerClass<T extends object> = new (...args: unknown[]) => {
+  handle(event: T): Promise<void> | void;
+  queue?: boolean | string;
+  maxAttempts?: number;
+  retryDelay?: number;
+};
+
+/** A listener that opts into deferred execution by declaring a `queue` target. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- the event payload type is listener-specific and not known at this boundary.
+export interface QueuedListener<T = any> {
+  queue: boolean | string;
+  maxAttempts?: number;
+  retryDelay?: number;
+  handle(event: T): Promise<void> | void;
+}
+
+/**
+ * The class-based application event emitter: register listener classes against
+ * event classes, then dispatch event instances to them.
+ *
+ * Events are plain classes and listeners are classes exposing a
+ * `handle(event)` method. Dispatch can run concurrently and fire-and-forget
+ * ({@link Emitter.emit}), one-at-a-time ({@link Emitter.emitSync}), or be
+ * deferred to the queue when a listener declares a `queue` target and a queue
+ * manager is registered. Listener failures during {@link Emitter.emit} are
+ * isolated and logged, never rethrown to the caller.
+ *
+ * Reached in applications through the `Events` facade; construct directly only
+ * in tests or bespoke wiring.
+ *
+ * @example
+ * ```ts
+ * import { Emitter } from "@zerotal/core";
+ *
+ * class UserRegistered {
+ *   constructor(readonly userId: string) {}
+ * }
+ *
+ * class SendWelcomeEmail {
+ *   async handle(event: UserRegistered): Promise<void> {
+ *     // await mail.to(event.userId).send(new Welcome());
+ *   }
+ * }
+ *
+ * const emitter = new Emitter();
+ * emitter.on(UserRegistered, SendWelcomeEmail);
+ * await emitter.emit(new UserRegistered("u_123"));
+ * ```
+ */
+export class Emitter {
+  private _listeners = new Map<Function, ListenerClass<object>[]>();
+  private _listenerByName = new Map<string, ListenerClass<object>>();
+
+  // Holds the application so the emitter can resolve the queue manager lazily.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Application is typed elsewhere; depending on it here would create a cross-module cycle.
+  private _application: any;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see _application above.
+  constructor(application?: any) {
+    this._application = application;
+  }
+
+  // Broadcaster hook, owned per emitter (i.e. per application). @zerotal/broadcasting's
+  // provider installs it so emitting a broadcastable event (one with a `broadcastOn()`
+  // method) also broadcasts it, keeping core broadcasting-free via this indirection.
+  private _broadcaster: ((event: object) => void) | null = null;
+
+  /**
+   * Install the hook that broadcasts emitted events implementing `broadcastOn()`.
+   * Set by `@zerotal/broadcasting`'s provider on the application's emitter; apps
+   * never call this. Pass `null` to disable.
+   *
+   * @internal
+   */
+  setBroadcaster(fn: ((event: object) => void) | null): void {
+    this._broadcaster = fn;
+  }
+
+  private _maybeBroadcast(event: object): void {
+    if (!this._broadcaster) return;
+    if (typeof (event as { broadcastOn?: unknown }).broadcastOn !== "function") return;
+    try {
+      this._broadcaster(event);
+    } catch (error) {
+      console.error("[Zerotal] broadcaster hook failed:", error);
+    }
+  }
+
+  // ── Registration ──────────────────────────────────────────────────────
+
+  /**
+   * Register a listener class to run whenever the given event class is emitted.
+   * The same event may have many listeners; they run in registration order.
+   *
+   * @param eventClass     The event class to listen for.
+   * @param listenerClass  A class with a `handle(event)` method.
+   * @category Subscription
+   */
+  on<T extends object>(eventClass: EventClass<T>, listenerClass: ListenerClass<T>): void {
+    const existing = this._listeners.get(eventClass) ?? [];
+    existing.push(listenerClass as ListenerClass<object>);
+    this._listeners.set(eventClass, existing);
+
+    // A queued listener crosses the queue boundary as a bare class name, so the name→class
+    // index is how a worker finds it again. Two listeners sharing a name — `SendNotification`
+    // in two modules is not a stretch — silently overwrote each other, so every queued job
+    // for one ran the other's handler. There is no way to tell them apart after
+    // serialisation, so the collision is refused where it can still be pointed at.
+    const registered = this._listenerByName.get(listenerClass.name);
+    if (registered && registered !== listenerClass) {
+      throw new Error(
+        `[Zerotal] Two listener classes are both named "${listenerClass.name}".\n` +
+          `A queued listener is dispatched by class name, so the second registration would ` +
+          `silently take over the first one's jobs. Rename one of them.`,
+      );
+    }
+    this._listenerByName.set(listenerClass.name, listenerClass as ListenerClass<object>);
+  }
+
+  /**
+   * Remove a previously registered listener for the given event class. No-op if
+   * the listener was never registered.
+   *
+   * @category Subscription
+   */
+  off<T extends object>(eventClass: EventClass<T>, listenerClass: ListenerClass<T>): void {
+    const existing = this._listeners.get(eventClass);
+    if (!existing) return;
+    const updated = existing.filter((listener) => listener !== listenerClass);
+    if (updated.length === 0) {
+      this._listeners.delete(eventClass);
+    } else {
+      this._listeners.set(eventClass, updated);
+    }
+
+    // Drop the name index too, once nothing is listening through this class. Leaving it
+    // meant a de-registered listener still ran for every queued job that named it — `off()`
+    // looked like it worked and did not — and the index grew without bound.
+    const stillRegistered = [...this._listeners.values()].some((listeners) =>
+      listeners.includes(listenerClass as ListenerClass<object>),
+    );
+    if (!stillRegistered) this._listenerByName.delete(listenerClass.name);
+  }
+
+  // ── Dispatch ──────────────────────────────────────────────────────────
+
+  /**
+   * Dispatch an event to all its listeners concurrently, deferring any listener
+   * that declares a `queue` target to the queue manager when one is available.
+   * Listener failures are isolated and logged, never rethrown to the caller.
+   * Broadcastable events (those with a `broadcastOn()` method) are broadcast
+   * first, so they fire even when no listeners are registered.
+   *
+   * @param event  The event instance; its constructor selects the listeners.
+   * @returns Resolves once every listener has settled (queued ones once enqueued).
+   * @category Dispatch
+   */
+  async emit<T extends object>(event: T): Promise<void> {
+    // Broadcast first (synchronously) so it fires even for events with no listeners.
+    this._maybeBroadcast(event);
+
+    // A snapshot, not the live array: a listener that registers another listener for the
+    // same event otherwise extends the array being iterated. One emit ran handle() 100,000
+    // times that way.
+    const listenerClasses = [...(this._listeners.get(event.constructor as Function) ?? [])];
+
+    if (listenerClasses.length === 0) return;
+
+    await Promise.allSettled(
+      listenerClasses.map(async (ListenerClass) => {
+        const listener = new ListenerClass();
+
+        if (listener.queue) {
+          let queueManager;
+          if (typeof this._application?.container?.make === "function") {
+            try {
+              queueManager = await this._application.container.make("queue");
+            } catch {
+              // No queue manager is registered; fall through to synchronous execution.
+            }
+          }
+
+          if (queueManager) {
+            const job = new CallQueuedListener(
+              ListenerClass.name,
+              event.constructor.name,
+              event,
+              listener.queue,
+              listener.maxAttempts,
+              listener.retryDelay,
+            );
+            await queueManager.dispatch(job);
+            return;
+          }
+        }
+
+        // Run inline when the listener is not queued, or no queue manager exists.
+        try {
+          await listener.handle(event);
+        } catch (error) {
+          console.error(
+            `[Zerotal] Event listener ${ListenerClass.name} threw for ${event.constructor.name}:`,
+            error,
+          );
+        }
+      }),
+    );
+  }
+
+  /**
+   * Dispatch an event to its listeners one at a time, awaiting each in turn.
+   * Unlike {@link Emitter.emit}, listeners run inline (never queued) and a
+   * thrown error is not caught — it propagates to the caller.
+   *
+   * @param event  The event instance; its constructor selects the listeners.
+   * @category Dispatch
+   */
+  async emitSync<T extends object>(event: T): Promise<void> {
+    this._maybeBroadcast(event);
+
+    // A snapshot, not the live array: a listener that registers another listener for the
+    // same event otherwise extends the array being iterated. One emit ran handle() 100,000
+    // times that way.
+    const listenerClasses = [...(this._listeners.get(event.constructor as Function) ?? [])];
+
+    for (const ListenerClass of listenerClasses) {
+      const listener = new ListenerClass();
+      await listener.handle(event);
+    }
+  }
+
+  /**
+   * Run a deferred listener by name with its raw payload. Called by the queue
+   * worker, not application code.
+   *
+   * @param listenerName  The registered listener class name.
+   * @param eventPayload  The raw payload handed straight to `handle()` (for most
+   *                      listeners the payload is the event).
+   * @throws {Error} If no listener is registered under `listenerName`.
+   * @category Dispatch
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the payload type is listener-specific and lost across the queue boundary.
+  async dispatchQueuedListener(listenerName: string, eventPayload: any): Promise<void> {
+    const ListenerClass = this._listenerByName.get(listenerName);
+    if (!ListenerClass) {
+      throw new Error(`Listener ${listenerName} not found in Emitter registry.`);
+    }
+
+    const listener = new ListenerClass();
+
+    // Without an event-class registry we can't rebuild the original event, so we
+    // hand the listener the raw payload — for most listeners the payload is the event.
+    await listener.handle(eventPayload);
+  }
+
+  /**
+   * Whether any listener is registered for the given event class.
+   * @category Subscription
+   */
+  hasListeners<T extends object>(eventClass: EventClass<T>): boolean {
+    return (this._listeners.get(eventClass)?.length ?? 0) > 0;
+  }
+
+  /**
+   * Remove every registered listener.
+   * @category Subscription
+   */
+  clear(): void {
+    this._listeners.clear();
+    this._listenerByName.clear();
+  }
+}

package/src/events/EventFake.ts

@@ -0,0 +1,160 @@
+/**
+ * The testing counterpart to {@link Emitter}: records emitted events instead of
+ * running their listeners, so a test can assert that an action announced what it
+ * did without also running everything that reacts to it.
+ */
+import type { Application } from "../application/Application.ts";
+import { currentApp } from "../application/currentApp.ts";
+import type { Binding } from "../container/types.ts";
+import { Emitter } from "./Emitter.ts";
+
+/** An event's class, as the assertions receive it. */
+type EventClass<T extends object> = (abstract new (...args: never[]) => T) & {
+  readonly name: string;
+};
+
+/**
+ * Drop-in replacement for {@link Emitter} that captures emitted events instead
+ * of dispatching them to listeners. Install at the start of a test, restore
+ * after.
+ *
+ * Faking the emitter is what lets a test assert "publishing a post announces
+ * `PostPublished`" without the listeners for that event — mail, search
+ * indexing, cache invalidation — running as a side effect. To test a listener,
+ * do not fake: construct the listener and hand it an event directly.
+ *
+ * @example
+ * const events = EventFake.install();
+ *
+ * await post.publish();
+ *
+ * events.assertEmitted(PostPublished);
+ * events.assertEmitted(PostPublished, (e) => e.postId === post.id);
+ * events.assertNotEmitted(PostDeleted);
+ *
+ * events.restore(); // call in afterEach
+ */
+export class EventFake extends Emitter {
+  private readonly _emitted: object[] = [];
+
+  private constructor(
+    private readonly _app: Application,
+    private readonly _original: Binding<unknown> | undefined,
+  ) {
+    super();
+  }
+
+  /** Replace the `events` container binding with this fake. */
+  static install(): EventFake {
+    const app = currentApp();
+    const fake = new EventFake(app, app.container.registry.get("events"));
+    app.container.value("events", fake);
+    return fake;
+  }
+
+  /** Restore the original `events` binding. Call in afterEach. */
+  restore(): void {
+    if (this._original !== undefined) {
+      this._app.container.registry.set("events", this._original);
+    } else {
+      this._app.container.registry.delete("events");
+    }
+  }
+
+  // ── Emitter interface ─────────────────────────────────────────────────
+
+  /** Capture the event — its listeners do NOT run. */
+  override async emit<T extends object>(event: T): Promise<void> {
+    this._emitted.push(event);
+  }
+
+  /** Capture the event — its listeners do NOT run. */
+  override async emitSync<T extends object>(event: T): Promise<void> {
+    this._emitted.push(event);
+  }
+
+  /** Discard the captured events, and any listeners registered on the fake. */
+  override clear(): void {
+    super.clear();
+    this._emitted.length = 0;
+  }
+
+  // ── Inspection ────────────────────────────────────────────────────────
+
+  /** Every event captured, in emit order. */
+  emitted(): object[] {
+    return [...this._emitted];
+  }
+
+  /** The captured events of the given class, narrowed to its type. */
+  emittedOf<T extends object>(EventType: EventClass<T>): T[] {
+    return this._emitted.filter((e): e is T => e instanceof EventType);
+  }
+
+  // ── Assertions ────────────────────────────────────────────────────────
+
+  /**
+   * Assert an event of the given class was emitted, optionally one matching
+   * `filter`.
+   *
+   * @example
+   * events.assertEmitted(OrderPlaced);
+   * events.assertEmitted(OrderPlaced, (e) => e.total === 4999);
+   */
+  assertEmitted<T extends object>(EventType: EventClass<T>, filter?: (event: T) => boolean): void {
+    const matches = this.emittedOf(EventType);
+    if (matches.length === 0) {
+      throw new Error(
+        `assertEmitted: expected ${_name(EventType)} to be emitted, but ${this._summary()}`,
+      );
+    }
+    if (filter && !matches.some(filter)) {
+      throw new Error(
+        `assertEmitted: ${matches.length} ${_name(EventType)} event(s) were emitted, but none ` +
+          `matched the filter. Emitted: ${JSON.stringify(matches)}.`,
+      );
+    }
+  }
+
+  /** Assert no event of the given class was emitted. */
+  assertNotEmitted<T extends object>(
+    EventType: EventClass<T>,
+    filter?: (event: T) => boolean,
+  ): void {
+    const matches = this.emittedOf(EventType);
+    const offending = filter ? matches.filter(filter) : matches;
+    if (offending.length > 0) {
+      throw new Error(
+        `assertNotEmitted: expected no ${_name(EventType)} but ${offending.length} were emitted: ` +
+          `${JSON.stringify(offending)}.`,
+      );
+    }
+  }
+
+  /** Assert exactly `count` events of the given class were emitted. */
+  assertEmittedCount<T extends object>(EventType: EventClass<T>, count: number): void {
+    const actual = this.emittedOf(EventType).length;
+    if (actual !== count) {
+      throw new Error(
+        `assertEmittedCount: expected ${count} ${_name(EventType)} event(s) but got ${actual}.`,
+      );
+    }
+  }
+
+  /** Assert no events at all were emitted. */
+  assertNothingEmitted(): void {
+    if (this._emitted.length > 0) {
+      throw new Error(`assertNothingEmitted: ${this._summary()}`);
+    }
+  }
+
+  private _summary(): string {
+    if (this._emitted.length === 0) return "no events were emitted at all.";
+    const names = this._emitted.map((e) => e.constructor.name);
+    return `the events emitted were [${names.join(", ")}].`;
+  }
+}
+
+function _name(EventType: EventClass<object>): string {
+  return EventType.name;
+}

package/src/events/FrameworkEvents.ts

@@ -0,0 +1,252 @@
+/**
+ * Lightweight synchronous event bus for framework instrumentation.
+ *
+ * ORM, Mail, Cache, and Queue emit lifecycle events here.
+ * Infrastructure packages (DevTools, Logging, Metrics) subscribe to react.
+ *
+ * Handlers fire synchronously in the emitter's call stack — keep them fast
+ * and side-effect-free (buffer pushes, counter increments). For I/O or heavy
+ * work, dispatch a queue job from inside the handler instead.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic "any event class" constructor bound; the args are never read through this type
+type EventCtor = new (...args: any[]) => object;
+type Handler<E> = (event: E) => void;
+
+// Events are keyed two ways: by class identity (subscribe with the class) and by
+// a stable string "kind" (subscribe with the string). Code that owns an event
+// subscribes with the class; a decoupled observer that must not import the class
+// — telemetry, the monitor — subscribes by kind. An event's kind is its optional
+// `static kind`, defaulting to the class name.
+const _byClass = new Map<EventCtor, Set<Handler<object>>>();
+const _byKind = new Map<string, Set<Handler<object>>>();
+
+/** The stable string key for an event class: its `static kind`, or its class name. */
+function _kindOf(ctor: EventCtor): string {
+  return (ctor as { kind?: string }).kind ?? ctor.name;
+}
+
+/**
+ * The framework instrumentation event bus — subscribe with `on`, fire with
+ * `emit`. Separate from the class-based {@link Emitter} used for application
+ * events: this bus is synchronous, static, and carries the framework's own
+ * lifecycle signals ({@link QueryExecuted}, {@link RequestHandled},
+ * {@link JobRan}, …) that observability packages subscribe to.
+ *
+ * @example
+ * ```ts
+ * 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();
+ * ```
+ */
+export const FrameworkEvents = {
+  /**
+   * 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.
+   *
+   * @param target   The event class to listen for, or its string {@link _kindOf | kind}.
+   * @param handler  Synchronous callback invoked with each emitted instance.
+   * @returns A function that removes this subscription when called.
+   * @category Subscription
+   */
+  on<E extends object>(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic "any event class" constructor bound
+    target: (new (...args: any[]) => E) | string,
+    handler: Handler<E>,
+  ): () => void {
+    const handlers = ((): Set<Handler<object>> => {
+      if (typeof target === "string") {
+        const existing = _byKind.get(target);
+        if (existing) return existing;
+        const set = new Set<Handler<object>>();
+        _byKind.set(target, set);
+        return set;
+      }
+      const ctor = target as EventCtor;
+      const existing = _byClass.get(ctor);
+      if (existing) return existing;
+      const set = new Set<Handler<object>>();
+      _byClass.set(ctor, set);
+      return set;
+    })();
+    handlers.add(handler as Handler<object>);
+    return () => {
+      handlers.delete(handler as Handler<object>);
+    };
+  },
+
+  /**
+   * 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.
+   *
+   * @param event  The event instance; its constructor (and kind) select the handlers.
+   * @category Dispatch
+   */
+  emit<E extends object>(event: E): void {
+    const ctor = event.constructor as EventCtor;
+    const classHandlers = _byClass.get(ctor);
+    const kindHandlers = _byKind.get(_kindOf(ctor));
+    if (!classHandlers?.size && !kindHandlers?.size) return;
+    const fire = (handler: Handler<object>): void => {
+      try {
+        handler(event);
+      } catch {
+        // Subscriber errors must never propagate back to the emitting code.
+      }
+    };
+    if (classHandlers) for (const handler of classHandlers) fire(handler);
+    if (kindHandlers) for (const handler of kindHandlers) fire(handler);
+  },
+
+  /**
+   * Remove all subscriptions. Call in tests to reset state between suites.
+   * @category Subscription
+   */
+  clear(): void {
+    _byClass.clear();
+    _byKind.clear();
+  },
+
+  /**
+   * Total number of registered handlers across all event types (class- and
+   * kind-keyed). Intended for tests to assert subscriptions were cleaned up.
+   *
+   * @returns The count of live handlers across every event type.
+   * @category Subscription
+   */
+  handlerCount(): number {
+    let count = 0;
+    for (const handlers of _byClass.values()) count += handlers.size;
+    for (const handlers of _byKind.values()) count += handlers.size;
+    return count;
+  },
+};
+
+// ── Framework event types ─────────────────────────────────────────────────────
+
+// ── Application lifecycle ──────────────────────────────────────────────────────
+
+/**
+ * Emitted once when the application finishes booting — all providers registered
+ * and booted and conventions wired. `durationMs` is the wall-clock boot time, so
+ * observers (Health page, telemetry, logger) can surface startup cost.
+ *
+ * @category Application lifecycle
+ * @example
+ * ```ts
+ * FrameworkEvents.on(AppBooted, (e) => {
+ *   console.log(`booted in ${e.durationMs}ms (${e.providerCount} providers)`);
+ * });
+ * ```
+ */
+export class AppBooted {
+  constructor(
+    readonly durationMs: number,
+    /** Application environment, e.g. "web" | "worker" | "console" | "test" | "repl". */
+    readonly environment: string,
+    /** Number of active service providers that booted. */
+    readonly providerCount: number,
+  ) {}
+}
+
+/**
+ * Emitted after a complete HTTP request–response cycle.
+ * Fired by Application after the middleware pipeline resolves.
+ *
+ * @category HTTP
+ * @example
+ * ```ts
+ * FrameworkEvents.on(RequestHandled, (e) => {
+ *   metrics.observe("http.duration_ms", e.durationMs);
+ * });
+ * ```
+ */
+export class RequestHandled {
+  constructor(
+    /** HttpContext — typed as object to avoid cross-package circular deps. */
+    readonly ctx: object,
+    readonly startMs: number,
+    readonly durationMs: number,
+  ) {}
+}
+
+// ── HTTP ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Emitted after an outgoing HTTP request made through the `Http` client
+ * completes or finally fails. Powers outgoing-dependency dashboards (per-host
+ * call counts, p95 latency, error rate). `status` is 0 when the request never
+ * got a response (network error / timeout).
+ *
+ * @category HTTP
+ */
+export class OutgoingRequestCompleted {
+  constructor(
+    readonly host: string,
+    readonly method: string,
+    readonly url: string,
+    readonly status: number,
+    readonly durationMs: number,
+    readonly ok: boolean,
+  ) {}
+}
+
+/**
+ * Emitted after an HTTP request fails (an error propagated out of the pipeline).
+ * Fired by the route dispatcher and the server fallback catch blocks.
+ *
+ * @category HTTP
+ */
+export class RequestFailed {
+  constructor(
+    /** HttpContext — typed as object to avoid cross-package circular deps. */
+    readonly ctx: object,
+    readonly startMs: number,
+    readonly durationMs: number,
+    readonly error: string,
+    readonly status: number,
+  ) {}
+}
+
+/**
+ * Emitted when a middleware short-circuits the pipeline (skips downstream).
+ * @category HTTP
+ */
+export class MiddlewareSkipped {
+  constructor(
+    readonly name: string,
+    readonly reason: string,
+    readonly ctx: object,
+  ) {}
+}
+
+// ── Console / commands ────────────────────────────────────────────────────────
+
+/**
+ * Emitted after a console (Artisan-style) command finishes — whether run from the
+ * CLI or in-process via `Artisan.call()`. Powers the panel's Commands feed.
+ *
+ * @category Console
+ */
+export class CommandRan {
+  constructor(
+    readonly name: string,
+    readonly durationMs: number,
+    readonly exitCode: number,
+    readonly ok: boolean,
+    readonly error?: string,
+  ) {}
+}