@zudojs/events 0.1.0 → 1.0.1

package/dist/eventMiddleware/eventMiddleware.pipeline.js

@@ -1,7 +1,7 @@
 /**
  * Event middleware pipeline execution for Zudojs.
  */
-import { EventMiddlewareError, toEventError, } from "../eventErrors/eventError.base.js";
+import { EventDispatchAbortedError, EventMiddlewareError, toEventError, } from "../eventErrors/eventError.base.js";
 import { sortEventMiddleware, executeEventMiddleware, } from "./eventMiddleware.helper.js";
 /**
  * Executes a middleware pipeline.
@@ -13,6 +13,11 @@ import { sortEventMiddleware, executeEventMiddleware, } from "./eventMiddleware.
  *     → handler
  *   ← middleware B
  * ← middleware A
+ *
+ * Only errors thrown by a middleware function itself are wrapped
+ * in EventMiddlewareError. Errors coming back through next() —
+ * handler failures, aborts, downstream middleware errors — are
+ * re-thrown untouched so callers can discriminate them.
  */
 export async function executeEventMiddlewarePipeline(middleware, context, terminal) {
     const started = performance.now();
@@ -21,7 +26,7 @@ export async function executeEventMiddlewarePipeline(middleware, context, termin
     let index = -1;
     const dispatch = async (currentIndex) => {
         if (context.signal.aborted) {
-            throw createAbortError();
+            throw createAbortError(context);
         }
         if (currentIndex === activeMiddleware.length) {
             return terminal();
@@ -39,6 +44,13 @@ export async function executeEventMiddlewarePipeline(middleware, context, termin
         }
         const middlewareStarted = performance.now();
         let nextCalled = false;
+        /**
+         * Errors that surfaced through next() belong to downstream
+         * code, not to this middleware; they must pass through
+         * unwrapped.
+         */
+        let downstreamThrew = false;
+        let downstreamError;
         const next = async () => {
             if (nextCalled) {
                 throw new EventMiddlewareError(`Middleware "${current.id}" called next() more than once.`, {
@@ -48,7 +60,14 @@ export async function executeEventMiddlewarePipeline(middleware, context, termin
                 });
             }
             nextCalled = true;
-            return dispatch(currentIndex + 1);
+            try {
+                return await dispatch(currentIndex + 1);
+            }
+            catch (error) {
+                downstreamThrew = true;
+                downstreamError = error;
+                throw error;
+            }
         };
         try {
             const result = await executeEventMiddleware(current.middleware, context, next);
@@ -60,7 +79,11 @@ export async function executeEventMiddlewarePipeline(middleware, context, termin
             return result;
         }
         catch (error) {
-            if (error instanceof EventMiddlewareError) {
+            if (downstreamThrew && error === downstreamError) {
+                throw error;
+            }
+            if (error instanceof EventMiddlewareError ||
+                error instanceof EventDispatchAbortedError) {
                 throw error;
             }
             throw new EventMiddlewareError(`Event middleware "${current.id}" failed.`, {
@@ -82,12 +105,13 @@ export async function executeEventMiddlewarePipeline(middleware, context, termin
     };
 }
 /**
- * Creates an AbortError without relying on a runtime-specific
- * DOMException implementation.
+ * Creates the abort error thrown when the pipeline observes an
+ * aborted signal.
  */
-function createAbortError() {
-    return new EventMiddlewareError("Event middleware execution was aborted.", {
-        cause: new Error("AbortSignal was aborted."),
+function createAbortError(context) {
+    return new EventDispatchAbortedError("Event dispatch was aborted.", {
+        eventType: context.event?.type,
+        eventId: context.event?.id,
     });
 }
 //# sourceMappingURL=eventMiddleware.pipeline.js.map

package/dist/eventRegistry/eventRegistry.lifecycle.d.ts

@@ -2,18 +2,23 @@
  * Event registry lifecycle methods for Zudojs.
  */
 import type { EventType } from "../eventTypes/eventDefinition.type.js";
-import type { RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
-import type { EventRegistryChange, EventRegistryListener, RegisteredEventDefinition } from "./eventRegistry.type.js";
+import type { EventHandlerEntry, EventRegistryChange, EventRegistryErrorContext, EventRegistryListener, RegisteredEventDefinition } from "./eventRegistry.type.js";
 /**
  * Clears all handlers and definitions from the registry.
+ *
+ * Every handler subscription is cancelled, so subscriptions held
+ * by callers report `active: false` afterwards.
  */
-export declare function registryClear(definitions: Map<EventType, RegisteredEventDefinition>, handlers: Map<string, RegisteredEventHandler>, ensureActive: () => void, notify: (change: EventRegistryChange) => void): void;
+export declare function registryClear(definitions: Map<EventType, RegisteredEventDefinition>, handlers: Map<string, EventHandlerEntry>, ensureActive: () => void, notify: (change: EventRegistryChange) => void): void;
 /**
  * Disposes the registry.
  */
-export declare function registryDispose(disposed: boolean, definitions: Map<EventType, RegisteredEventDefinition>, handlers: Map<string, RegisteredEventHandler>, listeners: Set<EventRegistryListener>, ensureActive: () => void, notify: (change: EventRegistryChange) => void): void;
+export declare function registryDispose(disposed: boolean, definitions: Map<EventType, RegisteredEventDefinition>, handlers: Map<string, EventHandlerEntry>, listeners: Set<EventRegistryListener>, ensureActive: () => void, notify: (change: EventRegistryChange) => void): void;
 /**
  * Notifies registry listeners.
+ *
+ * Observer failures never break registry mutations; they are
+ * forwarded to the `onError` hook when one is configured.
  */
-export declare function registryNotify(change: EventRegistryChange, listeners: Set<EventRegistryListener>): void;
+export declare function registryNotify(change: EventRegistryChange, listeners: Set<EventRegistryListener>, onError?: (error: unknown, context: EventRegistryErrorContext) => void): void;
 //# sourceMappingURL=eventRegistry.lifecycle.d.ts.map

package/dist/eventRegistry/eventRegistry.lifecycle.js

@@ -1,16 +1,20 @@
 /**
  * Event registry lifecycle methods for Zudojs.
  */
-import { registryUnregister, registryUnregisterHandler, } from "./eventRegistry.registration.js";
+import { registryUnregister } from "./eventRegistry.registration.js";
 /**
  * Clears all handlers and definitions from the registry.
+ *
+ * Every handler subscription is cancelled, so subscriptions held
+ * by callers report `active: false` afterwards.
  */
 export function registryClear(definitions, handlers, ensureActive, notify) {
     ensureActive();
-    const handlerIds = [...handlers.keys()];
-    for (const handlerId of handlerIds) {
-        registryUnregisterHandler(handlerId, handlers, ensureActive, notify);
+    const entries = [...handlers.values()];
+    for (const entry of entries) {
+        entry.subscription.unsubscribe();
     }
+    handlers.clear();
     const eventTypes = [...definitions.keys()];
     for (const eventType of eventTypes) {
         registryUnregister(eventType, definitions, ensureActive, notify);
@@ -28,17 +32,26 @@ export function registryDispose(disposed, definitions, handlers, listeners, ensu
 }
 /**
  * Notifies registry listeners.
+ *
+ * Observer failures never break registry mutations; they are
+ * forwarded to the `onError` hook when one is configured.
  */
-export function registryNotify(change, listeners) {
+export function registryNotify(change, listeners, onError) {
     for (const listener of listeners) {
         try {
             listener(change);
         }
-        catch {
-            /**
-             * Registry observers must not be able to break
-             * registry mutations.
-             */
+        catch (error) {
+            if (onError) {
+                try {
+                    onError(error, { source: "observer", change });
+                }
+                catch {
+                    /**
+                     * A failing error hook must not break the mutation either.
+                     */
+                }
+            }
         }
     }
 }

package/dist/eventRegistry/eventRegistry.queries.d.ts

@@ -3,21 +3,30 @@
  */
 import type { Event, EventType } from "../eventTypes/eventDefinition.type.js";
 import type { RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
-import type { RegisteredEventDefinition } from "./eventRegistry.type.js";
+import type { EventHandlerEntry, RegisteredEventDefinition } from "./eventRegistry.type.js";
 /**
- * Returns handlers matching an event.
+ * Returns enabled handlers matching an event, sorted by priority,
+ * exactly as the emitter would dispatch them.
+ *
+ * The event's type is normalized before matching, mirroring
+ * getHandlersForType(). Handler patterns are normalized when they
+ * are registered, so an event whose `type` preserves its original
+ * casing (as CQRS domain events do) still routes to the handlers
+ * that registered for it. Only the routing key is normalized; the
+ * event object handed to handlers is left untouched.
  */
-export declare function getHandlersForEvent(handlers: Map<string, RegisteredEventHandler>, event: Event): readonly RegisteredEventHandler[];
+export declare function getHandlersForEvent(handlers: Map<string, EventHandlerEntry>, event: Event): readonly RegisteredEventHandler[];
 /**
- * Returns handlers matching an event type.
+ * Returns enabled handlers matching an event type, sorted by
+ * priority. The type is normalized before matching.
  */
-export declare function getHandlersForType(handlers: Map<string, RegisteredEventHandler>, eventType: EventType): readonly RegisteredEventHandler[];
+export declare function getHandlersForType(handlers: Map<string, EventHandlerEntry>, eventType: EventType): readonly RegisteredEventHandler[];
 /**
  * Returns all event definitions as an array.
  */
 export declare function getAllDefinitions(definitions: Map<EventType, RegisteredEventDefinition>): readonly RegisteredEventDefinition[];
 /**
- * Returns all handlers as an array.
+ * Returns all handlers as an array (registration order).
  */
-export declare function getAllHandlers(handlers: Map<string, RegisteredEventHandler>): readonly RegisteredEventHandler[];
+export declare function getAllHandlers(handlers: Map<string, EventHandlerEntry>): readonly RegisteredEventHandler[];
 //# sourceMappingURL=eventRegistry.queries.d.ts.map

package/dist/eventRegistry/eventRegistry.queries.js

@@ -1,24 +1,33 @@
 /**
  * Event registry query functions for Zudojs.
  */
-import { normalizeEventType, matchesEventType, } from "../eventTypes/eventType.type.js";
+import { getMatchingEventHandlers } from "../eventHandler/eventHandler.core.js";
+import { normalizeRegistryEventType } from "./eventRegistry.registration.js";
 /**
- * Returns handlers matching an event.
+ * Returns enabled handlers matching an event, sorted by priority,
+ * exactly as the emitter would dispatch them.
+ *
+ * The event's type is normalized before matching, mirroring
+ * getHandlersForType(). Handler patterns are normalized when they
+ * are registered, so an event whose `type` preserves its original
+ * casing (as CQRS domain events do) still routes to the handlers
+ * that registered for it. Only the routing key is normalized; the
+ * event object handed to handlers is left untouched.
  */
 export function getHandlersForEvent(handlers, event) {
-    return [...handlers.values()].filter((handler) => {
-        if (!handler.enabled) {
-            return false;
-        }
-        return matchesEventType(event.type, handler.eventType);
-    });
+    const type = normalizeRegistryEventType(event.type);
+    const routed = event.type === type ? event : { ...event, type };
+    return getMatchingEventHandlers(getAllHandlers(handlers), routed);
 }
 /**
- * Returns handlers matching an event type.
+ * Returns enabled handlers matching an event type, sorted by
+ * priority. The type is normalized before matching.
  */
 export function getHandlersForType(handlers, eventType) {
-    const type = normalizeEventType(eventType);
-    return [...handlers.values()].filter((handler) => matchesEventType(type, handler.eventType));
+    const type = normalizeRegistryEventType(eventType);
+    return getMatchingEventHandlers(getAllHandlers(handlers), {
+        type,
+    });
 }
 /**
  * Returns all event definitions as an array.
@@ -27,9 +36,9 @@ export function getAllDefinitions(definitions) {
     return [...definitions.values()];
 }
 /**
- * Returns all handlers as an array.
+ * Returns all handlers as an array (registration order).
  */
 export function getAllHandlers(handlers) {
-    return [...handlers.values()];
+    return [...handlers.values()].map((entry) => entry.registration);
 }
 //# sourceMappingURL=eventRegistry.queries.js.map

package/dist/eventRegistry/eventRegistry.registration.d.ts

@@ -3,9 +3,14 @@
  */
 import type { Event, EventDefinition, EventType } from "../eventTypes/eventDefinition.type.js";
 import type { EventTypePattern } from "../eventTypes/eventType.type.js";
-import type { EventHandlerLike, EventHandlerOptions, RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
+import type { EventHandlerLike, EventHandlerOptions } from "../eventHandler/eventHandler.core.js";
 import type { EventSubscription } from "../eventSubscription/eventSubscription.core.js";
-import type { EventRegistryChange, RegisteredEventDefinition } from "./eventRegistry.type.js";
+import type { DuplicateHandlerIdPolicy, EventHandlerEntry, EventRegistryChange, EventRegistryWarning, RegisteredEventDefinition } from "./eventRegistry.type.js";
+/**
+ * Normalizes an event type for registry lookups, converting
+ * validation failures into InvalidEventError.
+ */
+export declare function normalizeRegistryEventType(eventType: string): EventType;
 /**
  * Registers an event definition.
  */
@@ -15,15 +20,17 @@ export declare function registryRegister<TType extends EventType, TPayload>(defi
 /**
  * Registers a handler.
  */
-export declare function registryRegisterHandler<TEvent extends Event = Event>(eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, handlerOptions: Omit<EventHandlerOptions, "eventType">, handlers: Map<string, RegisteredEventHandler>, options: {
-    allowDuplicateHandlerIds: boolean;
-}, ensureActive: () => void, notify: (change: EventRegistryChange) => void): EventSubscription;
+export declare function registryRegisterHandler<TEvent extends Event = Event>(eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, handlerOptions: Omit<EventHandlerOptions, "eventType">, handlers: Map<string, EventHandlerEntry>, options: {
+    onDuplicateHandlerId: DuplicateHandlerIdPolicy;
+    maxHandlersPerPattern: number;
+    onWarning: (warning: EventRegistryWarning) => void;
+}, ensureActive: () => void, notify: (change: EventRegistryChange) => void, warnedPatterns: Set<string>): EventSubscription;
 /**
  * Unregisters an event definition.
  */
 export declare function registryUnregister(eventType: EventType, definitions: Map<EventType, RegisteredEventDefinition>, ensureActive: () => void, notify: (change: EventRegistryChange) => void): boolean;
 /**
- * Unregisters a handler.
+ * Unregisters a handler by id, cancelling its subscription.
  */
-export declare function registryUnregisterHandler(handlerId: string, handlers: Map<string, RegisteredEventHandler>, ensureActive: () => void, notify: (change: EventRegistryChange) => void): boolean;
+export declare function registryUnregisterHandler(handlerId: string, handlers: Map<string, EventHandlerEntry>, ensureActive: () => void): boolean;
 //# sourceMappingURL=eventRegistry.registration.d.ts.map

package/dist/eventRegistry/eventRegistry.registration.js

@@ -1,26 +1,57 @@
 /**
  * Event registry registration methods for Zudojs.
  */
+import { normalizeEventType } from "../eventTypes/eventType.type.js";
 import { createEventHandler } from "../eventHandler/eventHandler.core.js";
-import { isValidEventType, isValidEventTypePattern, normalizeEventType, } from "../eventTypes/eventType.type.js";
 import { createEventSubscription } from "../eventSubscription/eventSubscription.core.js";
-import { DuplicateEventDefinitionError, DuplicateEventHandlerError, } from "../eventErrors/eventError.base.js";
+import { DuplicateEventDefinitionError, DuplicateEventHandlerError, InvalidEventError, } from "../eventErrors/eventError.base.js";
 import { EventRegistryChangeType } from "./eventRegistry.type.js";
+/**
+ * Normalizes an event type for registry lookups, converting
+ * validation failures into InvalidEventError.
+ */
+export function normalizeRegistryEventType(eventType) {
+    try {
+        return normalizeEventType(eventType);
+    }
+    catch (error) {
+        throw new InvalidEventError(`Invalid event type "${String(eventType)}".`, {
+            eventType: typeof eventType === "string" ? eventType : undefined,
+            cause: error,
+        });
+    }
+}
 /**
  * Registers an event definition.
  */
 export function registryRegister(definition, definitions, options, ensureActive, notify) {
     ensureActive();
-    const type = normalizeEventType(definition.type);
-    if (!isValidEventType(type)) {
-        throw new TypeError(`Invalid event type "${definition.type}".`);
+    if (typeof definition !== "object" ||
+        definition === null ||
+        typeof definition.type !== "string" ||
+        typeof definition.create !== "function") {
+        throw new InvalidEventError("Event definition must be created with defineEvent().");
     }
+    const type = normalizeRegistryEventType(definition.type);
     if (definitions.has(type) && !options.allowDuplicateDefinitions) {
         throw new DuplicateEventDefinitionError(type);
     }
+    /**
+     * The stored definition always stamps the normalized type so
+     * events it creates are publishable under the registered type.
+     */
+    const normalizedDefinition = definition.type === type
+        ? definition
+        : Object.freeze({
+            type: type,
+            create: (payload, createOptions) => ({
+                ...definition.create(payload, createOptions),
+                type,
+            }),
+        });
     const registered = Object.freeze({
         type: type,
-        definition,
+        definition: normalizedDefinition,
         registeredAt: new Date(),
     });
     definitions.set(type, registered);
@@ -34,43 +65,96 @@ export function registryRegister(definition, definitions, options, ensureActive,
 /**
  * Registers a handler.
  */
-export function registryRegisterHandler(eventType, handler, handlerOptions, handlers, options, ensureActive, notify) {
+export function registryRegisterHandler(eventType, handler, handlerOptions, handlers, options, ensureActive, notify, warnedPatterns) {
     ensureActive();
-    if (!isValidEventTypePattern(eventType)) {
-        throw new TypeError(`Invalid event type pattern "${eventType}".`);
-    }
-    const normalizedPattern = eventType === "*"
-        ? "*"
-        : eventType.endsWith(".*")
-            ? `${normalizeEventType(eventType.slice(0, -2))}.*`
-            : normalizeEventType(eventType);
+    /**
+     * createEventHandler validates the handler, the pattern and the
+     * options, and normalizes the pattern.
+     */
     const registration = createEventHandler(handler, {
         ...handlerOptions,
-        eventType: normalizedPattern,
+        eventType,
     });
-    if (handlers.has(registration.id) && !options.allowDuplicateHandlerIds) {
-        throw new DuplicateEventHandlerError(registration.id);
+    const existing = handlers.get(registration.id);
+    if (existing) {
+        if (options.onDuplicateHandlerId === "throw") {
+            throw new DuplicateEventHandlerError(registration.id);
+        }
+        existing.subscription.unsubscribe();
     }
-    handlers.set(registration.id, registration);
+    const subscription = createEventSubscription(() => {
+        /**
+         * Identity check: only remove the entry if it still belongs
+         * to this registration. A replacement registered under the
+         * same id must not be removed by the old subscription. No
+         * ensureActive here so teardown after dispose is a no-op.
+         */
+        if (handlers.get(registration.id)?.registration !== registration) {
+            return;
+        }
+        handlers.delete(registration.id);
+        notify({
+            type: EventRegistryChangeType.HANDLER_UNREGISTERED,
+            eventType: registration.eventType,
+            handler: registration,
+            timestamp: new Date(),
+        });
+    }, {
+        id: registration.id,
+        description: registration.description,
+    });
+    handlers.set(registration.id, { registration, subscription });
+    checkHandlerLimit(registration.eventType, handlers, options.maxHandlersPerPattern, options.onWarning, warnedPatterns);
     notify({
         type: EventRegistryChangeType.HANDLER_REGISTERED,
-        eventType: normalizedPattern,
+        eventType: registration.eventType,
         handler: registration,
         timestamp: new Date(),
     });
-    return createEventSubscription(() => {
-        registryUnregisterHandler(registration.id, handlers, ensureActive, notify);
-    }, {
-        id: registration.id,
-        description: registration.description,
-    });
+    return subscription;
+}
+/**
+ * Emits a leak warning (once per pattern) when the number of
+ * handlers for a pattern exceeds the configured limit.
+ */
+function checkHandlerLimit(pattern, handlers, limit, onWarning, warnedPatterns) {
+    if (limit <= 0 || warnedPatterns.has(pattern)) {
+        return;
+    }
+    let count = 0;
+    for (const entry of handlers.values()) {
+        if (entry.registration.eventType === pattern) {
+            count++;
+        }
+    }
+    if (count <= limit) {
+        return;
+    }
+    warnedPatterns.add(pattern);
+    const warning = {
+        type: "handler.limit",
+        pattern,
+        count,
+        limit,
+        message: `Possible event handler leak: ${count} handlers registered for ` +
+            `"${pattern}" (limit ${limit}). Unsubscribe handlers you no longer ` +
+            "need or raise maxHandlersPerPattern / maxListeners.",
+    };
+    try {
+        onWarning(warning);
+    }
+    catch {
+        /**
+         * A failing warning hook must not break registration.
+         */
+    }
 }
 /**
  * Unregisters an event definition.
  */
 export function registryUnregister(eventType, definitions, ensureActive, notify) {
     ensureActive();
-    const type = normalizeEventType(eventType);
+    const type = normalizeRegistryEventType(eventType);
     const removed = definitions.delete(type);
     if (removed) {
         notify({
@@ -82,23 +166,18 @@ export function registryUnregister(eventType, definitions, ensureActive, notify)
     return removed;
 }
 /**
- * Unregisters a handler.
+ * Unregisters a handler by id, cancelling its subscription.
  */
-export function registryUnregisterHandler(handlerId, handlers, ensureActive, notify) {
+export function registryUnregisterHandler(handlerId, handlers, ensureActive) {
     ensureActive();
-    const handler = handlers.get(handlerId);
-    if (!handler) {
+    const entry = handlers.get(handlerId);
+    if (!entry) {
         return false;
     }
-    const removed = handlers.delete(handlerId);
-    if (removed) {
-        notify({
-            type: EventRegistryChangeType.HANDLER_UNREGISTERED,
-            eventType: handler.eventType,
-            handler,
-            timestamp: new Date(),
-        });
-    }
-    return removed;
+    /**
+     * The subscription callback removes the entry and notifies.
+     */
+    entry.subscription.unsubscribe();
+    return !handlers.has(handlerId);
 }
 //# sourceMappingURL=eventRegistry.registration.js.map

package/dist/eventRegistry/eventRegistry.store.d.ts

@@ -3,22 +3,24 @@
  *
  * The registry owns event definitions and registered handlers.
  * It does not perform event dispatching. Dispatching belongs to
- * EventEmitter and higher-level routing belongs to EventBus.
+ * EventEmitter (which stores its handlers in a registry) and
+ * higher-level routing belongs to EventBus.
  */
 import type { Event, EventDefinition, EventType } from "../eventTypes/eventDefinition.type.js";
 import type { EventTypePattern } from "../eventTypes/eventType.type.js";
 import type { EventHandlerLike, EventHandlerOptions, RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
 import type { EventSubscription } from "../eventSubscription/eventSubscription.core.js";
-import { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError } from "../eventErrors/eventError.base.js";
-import type { EventRegistryOptions, EventRegistryListener, RegisteredEventDefinition } from "./eventRegistry.type.js";
-export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, };
+import { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError } from "../eventErrors/eventError.base.js";
+import type { EventHandlerStore, EventRegistryOptions, EventRegistryListener, RegisteredEventDefinition } from "./eventRegistry.type.js";
+export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, };
 /**
  * Main event registry.
  */
-export declare class EventRegistry {
+export declare class EventRegistry implements EventHandlerStore {
     private readonly definitions;
     private readonly handlers;
     private readonly listeners;
+    private readonly warnedPatterns;
     private readonly options;
     private disposed;
     constructor(options?: EventRegistryOptions);
@@ -31,6 +33,11 @@ export declare class EventRegistry {
     getHandler(handlerId: string): RegisteredEventHandler | undefined;
     requireHandler(handlerId: string): RegisteredEventHandler;
     hasHandler(handlerId: string): boolean;
+    /**
+     * Returns the subscription created for a handler id, if the
+     * handler is still registered.
+     */
+    getHandlerSubscription(handlerId: string): EventSubscription | undefined;
     unregisterHandler(handlerId: string): boolean;
     getDefinitions(): readonly RegisteredEventDefinition[];
     getHandlers(): readonly RegisteredEventHandler[];