@zudojs/events 0.0.1 → 1.0.0

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[];

package/dist/eventRegistry/eventRegistry.store.js

@@ -3,13 +3,18 @@
  *
  * 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 { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, } from "../eventErrors/eventError.base.js";
-import { registryRegister, registryRegisterHandler, registryUnregister, registryUnregisterHandler, } from "./eventRegistry.registration.js";
+import { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, } from "../eventErrors/eventError.base.js";
+import { DEFAULT_MAX_HANDLERS_PER_PATTERN } from "./eventRegistry.type.js";
+import { normalizeRegistryEventType, registryRegister, registryRegisterHandler, registryUnregister, registryUnregisterHandler, } from "./eventRegistry.registration.js";
 import { getHandlersForEvent, getHandlersForType, getAllDefinitions, getAllHandlers, } from "./eventRegistry.queries.js";
 import { registryClear, registryDispose, registryNotify, } from "./eventRegistry.lifecycle.js";
-export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, };
+export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, };
+function defaultWarning(warning) {
+    console.warn(`[@zudojs/events] ${warning.message}`);
+}
 /**
  * Main event registry.
  */
@@ -17,23 +22,34 @@ export class EventRegistry {
     definitions = new Map();
     handlers = new Map();
     listeners = new Set();
+    warnedPatterns = new Set();
     options;
     disposed = false;
     constructor(options = {}) {
+        const maxHandlersPerPattern = options.maxHandlersPerPattern ?? DEFAULT_MAX_HANDLERS_PER_PATTERN;
+        if (typeof maxHandlersPerPattern !== "number" ||
+            !Number.isFinite(maxHandlersPerPattern) ||
+            maxHandlersPerPattern < 0) {
+            throw new RangeError("maxHandlersPerPattern must be a non-negative finite number.");
+        }
         this.options = {
             allowDuplicateDefinitions: options.allowDuplicateDefinitions ?? false,
-            allowDuplicateHandlerIds: options.allowDuplicateHandlerIds ?? false,
+            onDuplicateHandlerId: options.onDuplicateHandlerId ??
+                (options.allowDuplicateHandlerIds ? "replace" : "throw"),
+            maxHandlersPerPattern,
+            onWarning: options.onWarning ?? defaultWarning,
+            onError: options.onError,
         };
     }
     register(definition) {
         return registryRegister(definition, this.definitions, this.options, () => this.ensureActive(), (c) => this.notify(c));
     }
     registerHandler(eventType, handler, options = {}) {
-        return registryRegisterHandler(eventType, handler, options, this.handlers, this.options, () => this.ensureActive(), (c) => this.notify(c));
+        return registryRegisterHandler(eventType, handler, options, this.handlers, this.options, () => this.ensureActive(), (c) => this.notify(c), this.warnedPatterns);
     }
     get(eventType) {
         this.ensureActive();
-        return this.definitions.get(eventType);
+        return this.definitions.get(normalizeRegistryEventType(eventType));
     }
     require(eventType) {
         const definition = this.get(eventType);
@@ -44,14 +60,14 @@ export class EventRegistry {
     }
     has(eventType) {
         this.ensureActive();
-        return this.definitions.has(eventType);
+        return this.definitions.has(normalizeRegistryEventType(eventType));
     }
     unregister(eventType) {
         return registryUnregister(eventType, this.definitions, () => this.ensureActive(), (c) => this.notify(c));
     }
     getHandler(handlerId) {
         this.ensureActive();
-        return this.handlers.get(handlerId);
+        return this.handlers.get(handlerId)?.registration;
     }
     requireHandler(handlerId) {
         const handler = this.getHandler(handlerId);
@@ -64,8 +80,16 @@ export class EventRegistry {
         this.ensureActive();
         return this.handlers.has(handlerId);
     }
+    /**
+     * Returns the subscription created for a handler id, if the
+     * handler is still registered.
+     */
+    getHandlerSubscription(handlerId) {
+        this.ensureActive();
+        return this.handlers.get(handlerId)?.subscription;
+    }
     unregisterHandler(handlerId) {
-        return registryUnregisterHandler(handlerId, this.handlers, () => this.ensureActive(), (c) => this.notify(c));
+        return registryUnregisterHandler(handlerId, this.handlers, () => this.ensureActive());
     }
     getDefinitions() {
         this.ensureActive();
@@ -98,6 +122,7 @@ export class EventRegistry {
     }
     clear() {
         registryClear(this.definitions, this.handlers, () => this.ensureActive(), (c) => this.notify(c));
+        this.warnedPatterns.clear();
     }
     dispose() {
         registryDispose(this.disposed, this.definitions, this.handlers, this.listeners, () => this.ensureActive(), (c) => this.notify(c));
@@ -107,11 +132,11 @@ export class EventRegistry {
         return this.disposed;
     }
     notify(change) {
-        registryNotify(change, this.listeners);
+        registryNotify(change, this.listeners, this.options.onError);
     }
     ensureActive() {
         if (this.disposed) {
-            throw new Error("EventRegistry has already been disposed.");
+            throw new EventRegistryDisposedError();
         }
     }
 }

package/dist/eventRegistry/eventRegistry.type.d.ts

@@ -1,11 +1,73 @@
 /**
  * Event registry type definitions for Zudojs.
  */
-import type { EventDefinition, EventType } from "../eventTypes/eventDefinition.type.js";
-import type { RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
+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";
+/**
+ * Policy applied when a handler is registered with an id that
+ * is already in use.
+ *
+ * - "throw"   → DuplicateEventHandlerError (default)
+ * - "replace" → the previous handler is unregistered (its
+ *               subscription is cancelled) and the new one stored
+ */
+export type DuplicateHandlerIdPolicy = "throw" | "replace";
+/**
+ * Default number of handlers allowed per event pattern before a
+ * leak warning is emitted.
+ */
+export declare const DEFAULT_MAX_HANDLERS_PER_PATTERN = 100;
+/**
+ * Warning emitted when a registry limit is exceeded.
+ */
+export interface EventRegistryWarning {
+    readonly type: "handler.limit";
+    readonly pattern: EventTypePattern;
+    readonly count: number;
+    readonly limit: number;
+    readonly message: string;
+}
+/**
+ * Context passed to onError hooks.
+ */
+export interface EventRegistryErrorContext {
+    readonly source: "observer";
+    readonly change?: EventRegistryChange;
+}
 export interface EventRegistryOptions {
+    /**
+     * Allow re-registering an event type. The previous definition
+     * is replaced.
+     */
     readonly allowDuplicateDefinitions?: boolean;
+    /**
+     * @deprecated Use `onDuplicateHandlerId: "replace"`. When true,
+     * registering a handler id that already exists replaces the
+     * previous handler (it never allowed two handlers to coexist).
+     */
     readonly allowDuplicateHandlerIds?: boolean;
+    /**
+     * What to do when a handler id is already registered.
+     * Defaults to "throw".
+     */
+    readonly onDuplicateHandlerId?: DuplicateHandlerIdPolicy;
+    /**
+     * Maximum handlers per event pattern before a leak warning is
+     * emitted through `onWarning` (or console.warn). Use 0 to
+     * disable. Defaults to 100.
+     */
+    readonly maxHandlersPerPattern?: number;
+    /**
+     * Receives limit warnings. Defaults to console.warn.
+     */
+    readonly onWarning?: (warning: EventRegistryWarning) => void;
+    /**
+     * Receives errors thrown by registry observers, which are
+     * otherwise swallowed so they cannot break registry mutations.
+     */
+    readonly onError?: (error: unknown, context: EventRegistryErrorContext) => void;
 }
 export declare enum EventRegistryChangeType {
     EVENT_REGISTERED = "event.registered",
@@ -25,4 +87,27 @@ export interface RegisteredEventDefinition<TType extends EventType = EventType,
     readonly definition: EventDefinition<TType, TPayload>;
     readonly registeredAt: Date;
 }
+/**
+ * Internal handler entry: the registration plus the subscription
+ * handed to the caller, so the registry can cancel it.
+ */
+export interface EventHandlerEntry {
+    readonly registration: RegisteredEventHandler;
+    readonly subscription: EventSubscription;
+}
+/**
+ * Minimal handler store contract used by EventEmitter.
+ *
+ * EventRegistry implements it; the emitter stores its handlers in
+ * a registry so that a bus has a single source of truth for
+ * handlers.
+ */
+export interface EventHandlerStore {
+    registerHandler<TEvent extends Event = Event>(eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options?: Omit<EventHandlerOptions, "eventType">): EventSubscription;
+    unregisterHandler(handlerId: string): boolean;
+    hasHandler(handlerId: string): boolean;
+    getHandlers(): readonly RegisteredEventHandler[];
+    getHandlersForEvent(event: Event): readonly RegisteredEventHandler[];
+    readonly handlerCount: number;
+}
 //# sourceMappingURL=eventRegistry.type.d.ts.map

package/dist/eventRegistry/eventRegistry.type.js

@@ -1,6 +1,11 @@
 /**
  * Event registry type definitions for Zudojs.
  */
+/**
+ * Default number of handlers allowed per event pattern before a
+ * leak warning is emitted.
+ */
+export const DEFAULT_MAX_HANDLERS_PER_PATTERN = 100;
 export var EventRegistryChangeType;
 (function (EventRegistryChangeType) {
     EventRegistryChangeType["EVENT_REGISTERED"] = "event.registered";

package/dist/eventSubscription/eventSubscription.core.d.ts

@@ -135,6 +135,11 @@ export declare class EventSubscriptionGroup implements EventSubscription {
     remove(subscription: EventSubscription): boolean;
     /**
      * Unsubscribes every subscription in the group.
+     *
+     * Every subscription is attempted even if one throws; the
+     * failures are then re-thrown together as an AggregateError and
+     * the failed subscriptions stay in the group so the call can be
+     * retried.
      */
     unsubscribe(): void;
     /**