@zudojs/events 1.1.0 → 1.2.0

package/dist/eventBus/eventBus.core.js

@@ -7,6 +7,7 @@ import { EventErrorMode } from "../eventEmitter/eventEmitter.type.js";
 import { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
 import { normalizeRegistryEventType } from "../eventRegistry/eventRegistry.registration.js";
 import { EventBusDisposedError, EventBusStoppedError, EventError, toEventError, } from "../eventErrors/eventError.base.js";
+import { warnObserverError } from "../eventErrors/eventWarning.helper.js";
 import { EventBusState } from "./eventBus.type.js";
 export { EventBusState } from "./eventBus.type.js";
 import { busOn, busOnce, busOnAny, busOff, busUse, registerMiddlewareItem, } from "./eventBus.registration.js";
@@ -34,6 +35,7 @@ export class EventBus {
         this.registry = new EventRegistry({
             ...options.registry,
             maxHandlersPerPattern: options.emitter?.maxListeners,
+            enforceHandlerLimit: options.emitter?.enforceHandlerLimit,
             onWarning: options.onWarning,
             onError: options.onError
                 ? (error, context) => options.onError?.(error, {
@@ -235,16 +237,23 @@ export class EventBus {
             catch (error) {
                 /**
                  * Observers must never be able to break event bus
-                 * operations; failures go to the onError hook.
+                 * operations; failures go to the onError hook, or to Node's
+                 * process warning channel when no hook is configured, so a
+                 * broken observer is never silently discarded.
                  */
-                try {
-                    this.options.onError?.(error, {
-                        source: "observer",
-                        event: event.event,
-                    });
+                if (this.options.onError) {
+                    try {
+                        this.options.onError(error, {
+                            source: "observer",
+                            event: event.event,
+                        });
+                    }
+                    catch {
+                        // Ignore failures of the error hook itself.
+                    }
                 }
-                catch {
-                    // Ignore failures of the error hook itself.
+                else {
+                    warnObserverError(error, "An event bus observer", this.listeners);
                 }
             }
         }

package/dist/eventBus/eventBus.type.d.ts

@@ -36,6 +36,11 @@ export interface EventBusOptions {
          * emitted (0 disables). Defaults to 100.
          */
         readonly maxListeners?: number;
+        /**
+         * Refuse a registration that would exceed `maxListeners` instead of
+         * warning about it. Defaults to `false`.
+         */
+        readonly enforceHandlerLimit?: boolean;
     };
     readonly registry?: {
         readonly allowDuplicateDefinitions?: boolean;

package/dist/eventEmitter/eventEmitter.core.js

@@ -32,6 +32,7 @@ export class EventEmitter {
             options.store ??
                 new EventRegistry({
                     maxHandlersPerPattern: options.maxListeners,
+                    enforceHandlerLimit: options.enforceHandlerLimit,
                     onWarning: options.onWarning,
                 });
     }

package/dist/eventEmitter/eventEmitter.type.d.ts

@@ -42,6 +42,11 @@ export interface EventEmitterOptions {
      * Defaults to 100.
      */
     readonly maxListeners?: number;
+    /**
+     * Refuse a registration that would exceed `maxListeners` instead of warning
+     * about it. Only applies to the private store. Defaults to `false`.
+     */
+    readonly enforceHandlerLimit?: boolean;
     /**
      * Receives leak warnings. Only applies to the private store.
      * Defaults to `process.emitWarning` (type `ZudojsEventsWarning`).

package/dist/eventErrors/eventError.base.d.ts

@@ -6,7 +6,7 @@
  * errors package does not define yet live in this file.
  */
 import { EventError, EventDispatchAbortedError as BaseEventDispatchAbortedError } from "@zudojs/errors";
-export { EventError, createEventError, isEventError, toEventError, EventPublishError, InvalidEventError, EventTypeNotFoundError, EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventTimeoutError, EventMiddlewareError, EventSerializationError, EventDeserializationError, } from "@zudojs/errors";
+export { EventError, createEventError, isEventError, toEventError, EventPublishError, InvalidEventError, EventTypeNotFoundError, EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventListenerLimitExceededError, EventTimeoutError, EventMiddlewareError, EventSerializationError, EventDeserializationError, } from "@zudojs/errors";
 /**
  * Options for EventDispatchAbortedError.
  */
@@ -45,11 +45,4 @@ export declare class EventBusDisposedError extends EventError {
 export declare class EventBusStoppedError extends EventError {
     constructor(operation: string);
 }
-/**
- * Error thrown when the listener limit of an emitter or registry
- * is exceeded and the limit is configured to be enforced.
- */
-export declare class EventListenerLimitExceededError extends EventError {
-    constructor(pattern: string, limit: number);
-}
 //# sourceMappingURL=eventError.base.d.ts.map

package/dist/eventErrors/eventError.base.js

@@ -6,7 +6,7 @@
  * errors package does not define yet live in this file.
  */
 import { ErrorCode, EventError, EventDispatchAbortedError as BaseEventDispatchAbortedError, } from "@zudojs/errors";
-export { EventError, createEventError, isEventError, toEventError, EventPublishError, InvalidEventError, EventTypeNotFoundError, EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventTimeoutError, EventMiddlewareError, EventSerializationError, EventDeserializationError, } from "@zudojs/errors";
+export { EventError, createEventError, isEventError, toEventError, EventPublishError, InvalidEventError, EventTypeNotFoundError, EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventListenerLimitExceededError, EventTimeoutError, EventMiddlewareError, EventSerializationError, EventDeserializationError, } from "@zudojs/errors";
 /**
  * Error thrown when event dispatch is aborted through an
  * AbortSignal. Carries the partial results and errors gathered
@@ -52,18 +52,4 @@ export class EventBusStoppedError extends EventError {
         });
     }
 }
-/**
- * Error thrown when the listener limit of an emitter or registry
- * is exceeded and the limit is configured to be enforced.
- */
-export class EventListenerLimitExceededError extends EventError {
-    constructor(pattern, limit) {
-        super(`Listener limit of ${limit} exceeded for event pattern "${pattern}".`, {
-            code: ErrorCode.LIFECYCLE_STATE,
-            statusCode: 500,
-            expose: false,
-            metadata: { pattern, limit },
-        });
-    }
-}
 //# sourceMappingURL=eventError.base.js.map

package/dist/eventErrors/eventWarning.helper.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Process-level warning sink for @zudojs/events.
+ *
+ * @module eventErrors/eventWarning
+ */
+/** Warning code for a registry or emitter handler-limit breach. */
+export declare const EVENT_HANDLER_LIMIT_WARNING_CODE = "ZUDOJS_EVENTS_HANDLER_LIMIT";
+/** Warning code for a bus or registry observer that threw. */
+export declare const EVENT_OBSERVER_ERROR_WARNING_CODE = "ZUDOJS_EVENTS_OBSERVER_ERROR";
+/**
+ * Emits a diagnostic on Node's process warning channel — the same one
+ * `EventEmitter` uses for `MaxListenersExceededWarning`, so it honours
+ * `--no-warnings` and `process.on("warning")` instead of writing to the
+ * console. A no-op where `process.emitWarning` is unavailable.
+ *
+ * @param message - The warning text, emitted with a package prefix.
+ * @param code - The machine-readable warning code.
+ */
+export declare function emitEventsWarning(message: string, code: string): void;
+/**
+ * Default sink for an observer that threw: with no `onError` hook
+ * configured the failure would otherwise be swallowed entirely.
+ *
+ * Emitted at most once per scope, the way the handler-limit warning is
+ * emitted at most once per pattern, so a broken observer on a busy bus
+ * reports itself without flooding the warning channel.
+ *
+ * @param error - The value the observer threw.
+ * @param source - A short description of which observer channel failed.
+ * @param scope - The bus or registry the observer belongs to.
+ */
+export declare function warnObserverError(error: unknown, source: string, scope: object): void;
+//# sourceMappingURL=eventWarning.helper.d.ts.map

package/dist/eventErrors/eventWarning.helper.js

@@ -0,0 +1,49 @@
+/**
+ * Process-level warning sink for @zudojs/events.
+ *
+ * @module eventErrors/eventWarning
+ */
+/** Warning code for a registry or emitter handler-limit breach. */
+export const EVENT_HANDLER_LIMIT_WARNING_CODE = "ZUDOJS_EVENTS_HANDLER_LIMIT";
+/** Warning code for a bus or registry observer that threw. */
+export const EVENT_OBSERVER_ERROR_WARNING_CODE = "ZUDOJS_EVENTS_OBSERVER_ERROR";
+/**
+ * Emits a diagnostic on Node's process warning channel — the same one
+ * `EventEmitter` uses for `MaxListenersExceededWarning`, so it honours
+ * `--no-warnings` and `process.on("warning")` instead of writing to the
+ * console. A no-op where `process.emitWarning` is unavailable.
+ *
+ * @param message - The warning text, emitted with a package prefix.
+ * @param code - The machine-readable warning code.
+ */
+export function emitEventsWarning(message, code) {
+    const emit = globalThis.process?.emitWarning;
+    emit?.(`[@zudojs/events] ${message}`, {
+        type: "ZudojsEventsWarning",
+        code,
+    });
+}
+/** Scopes that have already reported a failing observer. */
+const warnedObserverScopes = new WeakSet();
+/**
+ * Default sink for an observer that threw: with no `onError` hook
+ * configured the failure would otherwise be swallowed entirely.
+ *
+ * Emitted at most once per scope, the way the handler-limit warning is
+ * emitted at most once per pattern, so a broken observer on a busy bus
+ * reports itself without flooding the warning channel.
+ *
+ * @param error - The value the observer threw.
+ * @param source - A short description of which observer channel failed.
+ * @param scope - The bus or registry the observer belongs to.
+ */
+export function warnObserverError(error, source, scope) {
+    if (warnedObserverScopes.has(scope))
+        return;
+    warnedObserverScopes.add(scope);
+    const detail = error instanceof Error ? error.message : String(error);
+    emitEventsWarning(`${source} threw and was ignored: ${detail}. ` +
+        "Configure the `onError` option to handle observer failures. " +
+        "This warning is emitted once.", EVENT_OBSERVER_ERROR_WARNING_CODE);
+}
+//# sourceMappingURL=eventWarning.helper.js.map

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

@@ -18,7 +18,9 @@ export declare function registryDispose(disposed: boolean, definitions: Map<Even
  * Notifies registry listeners.
  *
  * Observer failures never break registry mutations; they are
- * forwarded to the `onError` hook when one is configured.
+ * forwarded to the `onError` hook when one is configured, and to
+ * Node's process warning channel when one is not, so a broken
+ * observer is never silently discarded.
  */
 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

@@ -2,6 +2,7 @@
  * Event registry lifecycle methods for Zudojs.
  */
 import { registryUnregister } from "./eventRegistry.registration.js";
+import { warnObserverError } from "../eventErrors/eventWarning.helper.js";
 /**
  * Clears all handlers and definitions from the registry.
  *
@@ -34,7 +35,9 @@ 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.
+ * forwarded to the `onError` hook when one is configured, and to
+ * Node's process warning channel when one is not, so a broken
+ * observer is never silently discarded.
  */
 export function registryNotify(change, listeners, onError) {
     for (const listener of listeners) {
@@ -52,6 +55,9 @@ export function registryNotify(change, listeners, onError) {
                      */
                 }
             }
+            else {
+                warnObserverError(error, "An event registry observer", listeners);
+            }
         }
     }
 }

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

@@ -23,6 +23,7 @@ export declare function registryRegister<TType extends EventType, TPayload>(defi
 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;
+    enforceHandlerLimit?: boolean;
     onWarning: (warning: EventRegistryWarning) => void;
 }, ensureActive: () => void, notify: (change: EventRegistryChange) => void, warnedPatterns: Set<string>): EventSubscription;
 /**

package/dist/eventRegistry/eventRegistry.registration.js

@@ -4,7 +4,7 @@
 import { normalizeEventType } from "../eventTypes/eventType.type.js";
 import { createEventHandler } from "../eventHandler/eventHandler.core.js";
 import { createEventSubscription } from "../eventSubscription/eventSubscription.core.js";
-import { DuplicateEventDefinitionError, DuplicateEventHandlerError, InvalidEventError, } from "../eventErrors/eventError.base.js";
+import { DuplicateEventDefinitionError, DuplicateEventHandlerError, EventListenerLimitExceededError, InvalidEventError, } from "../eventErrors/eventError.base.js";
 import { EventRegistryChangeType } from "./eventRegistry.type.js";
 /**
  * Normalizes an event type for registry lookups, converting
@@ -104,7 +104,7 @@ export function registryRegisterHandler(eventType, handler, handlerOptions, hand
         description: registration.description,
     });
     handlers.set(registration.id, { registration, subscription });
-    checkHandlerLimit(registration.eventType, handlers, options.maxHandlersPerPattern, options.onWarning, warnedPatterns);
+    checkHandlerLimit(registration.eventType, handlers, options.maxHandlersPerPattern, options.onWarning, warnedPatterns, options.enforceHandlerLimit === true, registration.id);
     notify({
         type: EventRegistryChangeType.HANDLER_REGISTERED,
         eventType: registration.eventType,
@@ -114,11 +114,19 @@ export function registryRegisterHandler(eventType, handler, handlerOptions, hand
     return subscription;
 }
 /**
- * Emits a leak warning (once per pattern) when the number of
- * handlers for a pattern exceeds the configured limit.
+ * Reports a pattern whose handler count has passed the configured limit.
+ *
+ * Warns once per pattern by default. Under `enforceHandlerLimit` it instead
+ * removes the handler just registered and throws
+ * {@link EventListenerLimitExceededError}, so a refused registration leaves
+ * the registry exactly as it was — and it throws on every breach, not only
+ * the first, because each one is a separate fault.
  */
-function checkHandlerLimit(pattern, handlers, limit, onWarning, warnedPatterns) {
-    if (limit <= 0 || warnedPatterns.has(pattern)) {
+function checkHandlerLimit(pattern, handlers, limit, onWarning, warnedPatterns, enforce, registrationId) {
+    if (limit <= 0) {
+        return;
+    }
+    if (!enforce && warnedPatterns.has(pattern)) {
         return;
     }
     let count = 0;
@@ -130,6 +138,10 @@ function checkHandlerLimit(pattern, handlers, limit, onWarning, warnedPatterns)
     if (count <= limit) {
         return;
     }
+    if (enforce) {
+        handlers.delete(registrationId);
+        throw new EventListenerLimitExceededError(pattern, count, limit);
+    }
     warnedPatterns.add(pattern);
     const warning = {
         type: "handler.limit",

package/dist/eventRegistry/eventRegistry.store.js

@@ -7,6 +7,7 @@
  * higher-level routing belongs to EventBus.
  */
 import { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, } from "../eventErrors/eventError.base.js";
+import { EVENT_HANDLER_LIMIT_WARNING_CODE, emitEventsWarning, } from "../eventErrors/eventWarning.helper.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";
@@ -19,11 +20,7 @@ export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateE
  * console directly. A no-op where `process.emitWarning` is unavailable.
  */
 function defaultWarning(warning) {
-    const emit = globalThis.process?.emitWarning;
-    emit?.(`[@zudojs/events] ${warning.message}`, {
-        type: "ZudojsEventsWarning",
-        code: "ZUDOJS_EVENTS_HANDLER_LIMIT",
-    });
+    emitEventsWarning(warning.message, EVENT_HANDLER_LIMIT_WARNING_CODE);
 }
 /**
  * Main event registry.
@@ -47,6 +44,7 @@ export class EventRegistry {
             onDuplicateHandlerId: options.onDuplicateHandlerId ??
                 (options.allowDuplicateHandlerIds ? "replace" : "throw"),
             maxHandlersPerPattern,
+            enforceHandlerLimit: options.enforceHandlerLimit ?? false,
             onWarning: options.onWarning ?? defaultWarning,
             onError: options.onError,
         };

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

@@ -59,6 +59,16 @@ export interface EventRegistryOptions {
      * disable. Defaults to 100.
      */
     readonly maxHandlersPerPattern?: number;
+    /**
+     * Refuse a registration that would exceed `maxHandlersPerPattern` instead of
+     * warning about it. Defaults to `false`.
+     *
+     * The default is a one-shot warning, which reports a suspected leak without
+     * interrupting a working application. Set this where a breached limit is a
+     * fault you would rather fail on: `register` then throws
+     * `EventListenerLimitExceededError` and the handler is not registered.
+     */
+    readonly enforceHandlerLimit?: boolean;
     /**
      * Receives limit warnings. Defaults to `process.emitWarning` (type `ZudojsEventsWarning`).
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/events",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Event-driven architecture with event bus, emitter, middleware, and registry for decoupled communication.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,9 +20,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/middleware": "1.0.2"
+    "@zudojs/constants": "1.1.1",
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/middleware": "1.0.3"
   },
   "engines": {
     "node": ">=24.0.0"