@zudojs/events 1.0.1 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Event-driven architecture with event bus, emitter, middleware, and registry for decoupled communication.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-events](https://zudojs.oyinlola.site/docs/packages-events) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-events.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -46,8 +52,9 @@ await bus.publishEvent({
 - Handler priorities, one-time handlers, per-handler timeouts
 - Wildcard subscriptions (`"user.*"`, `"*"`)
 - Event registry for typed definitions; handlers registered on the registry are dispatched by the bus
-- Deep-frozen events (`freezeEvents`, on by default) so handlers cannot alter what other handlers see
-- Listener-leak warnings (`maxListeners`) and an `onError` hook for fire-and-forget publishes
+- Deep-frozen events (`freezeEvents`, on by default) so handlers cannot alter what other handlers see: handlers receive a frozen *copy* (`createFrozenEventSnapshot`), so the publisher's own objects are never frozen, and Map, Set and Date values (including `event.timestamp`) become read-only variants that throw on mutation. Class instances are passed by reference.
+- A handler unsubscribed by an earlier handler in the same dispatch, or left over after the bus is disposed mid-dispatch, does not run
+- Listener-leak warnings (`maxListeners`, reported through `onWarning` or, by default, `process.emitWarning` with type `ZudojsEventsWarning`) and an `onError` hook for fire-and-forget publishes
 - Typed error classes from `@zudojs/errors` (`EventHandlerError`, `EventMiddlewareError`, `EventDispatchAbortedError`, …)
 
 ## Lifecycle

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;
@@ -52,7 +57,7 @@ export interface EventBusOptions {
     readonly requireRegistration?: boolean;
     readonly middleware?: readonly EventBusMiddlewareItem[];
     /**
-     * Receives leak warnings. Defaults to console.warn.
+     * Receives leak warnings. Defaults to `process.emitWarning` (type `ZudojsEventsWarning`).
      */
     readonly onWarning?: (warning: EventRegistryWarning) => void;
     /**

package/dist/eventEmitter/eventEmitter.core.js

@@ -6,7 +6,7 @@
  * bus and its registry share one set of handlers.
  */
 import { createEvent, isEvent } from "../eventTypes/eventDefinition.type.js";
-import { deepFreeze } from "../eventTypes/eventPayload.type.js";
+import { createFrozenEventSnapshot } from "../eventTypes/eventSnapshot.freeze.js";
 import { createEventHandlerContext } from "../eventHandler/eventHandler.core.js";
 import { EventSubscriptionGroup } from "../eventSubscription/eventSubscription.core.js";
 import { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
@@ -32,6 +32,7 @@ export class EventEmitter {
             options.store ??
                 new EventRegistry({
                     maxHandlersPerPattern: options.maxListeners,
+                    enforceHandlerLimit: options.enforceHandlerLimit,
                     onWarning: options.onWarning,
                 });
     }
@@ -68,8 +69,12 @@ export class EventEmitter {
         }
         const mode = options.mode ?? this.options.mode;
         const errorMode = options.errorMode ?? this.options.errorMode;
-        const dispatched = this.options.freezeEvents ? deepFreeze(event) : event;
-        const handlers = this.store.getHandlersForEvent(dispatched);
+        const handlers = this.store.getHandlersForEvent(event);
+        // Handlers receive a frozen COPY: freezing the event in place froze
+        // the publisher's own objects, even when nobody was subscribed.
+        const dispatched = this.options.freezeEvents && handlers.length > 0
+            ? createFrozenEventSnapshot(event)
+            : event;
         const context = createEventHandlerContext(dispatched, {
             signal: options.signal,
             metadata: options.metadata,
@@ -87,7 +92,17 @@ export class EventEmitter {
             };
         }
         const hooks = {
-            isRegistered: (handlerId) => this.store.hasHandler(handlerId),
+            // A bus disposed mid-dispatch has no registered handlers left.
+            isRegistered: (handlerId) => {
+                if (this.disposed)
+                    return false;
+                try {
+                    return this.store.hasHandler(handlerId);
+                }
+                catch {
+                    return false;
+                }
+            },
             removeOnce: (handlerId) => {
                 this.store.unregisterHandler(handlerId);
             },

package/dist/eventEmitter/eventEmitter.parallel.js

@@ -22,12 +22,12 @@ export async function emitParallel(handlers, event, context, errorMode, results,
      * an overlapping dispatch cannot invoke them a second time.
      */
     const runnable = handlers.filter((handler) => {
-        if (!handler.once) {
-            return true;
-        }
         if (!hooks.isRegistered(handler.id)) {
             return false;
         }
+        if (!handler.once) {
+            return true;
+        }
         hooks.removeOnce(handler.id);
         return true;
     });

package/dist/eventEmitter/eventEmitter.sequential.js

@@ -13,11 +13,13 @@ export async function emitSequential(handlers, event, context, errorMode, result
         if (context.signal.aborted) {
             throw createAbortError(event, results, errors);
         }
+        // Checked for every handler, not only once-handlers: a handler
+        // unsubscribed (or a bus disposed) by an earlier handler in this
+        // same dispatch must not run.
+        if (!hooks.isRegistered(handler.id)) {
+            continue;
+        }
         if (handler.once) {
-            if (!hooks.isRegistered(handler.id)) {
-                // Already consumed by an overlapping dispatch.
-                continue;
-            }
             hooks.removeOnce(handler.id);
         }
         const started = performance.now();

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

@@ -42,9 +42,14 @@ 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 console.warn.
+     * Defaults to `process.emitWarning` (type `ZudojsEventsWarning`).
      */
     readonly onWarning?: (warning: EventRegistryWarning) => void;
 }

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/eventMiddleware/eventMiddleware.pipeline.d.ts

@@ -1,5 +1,6 @@
 /**
- * Event middleware pipeline execution for Zudojs.
+ * Event middleware pipeline execution for Zudojs, built on `compose` from
+ * `@zudojs/middleware`.
  */
 import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { EventMiddlewareContext, EventMiddlewareNext, RegisteredEventMiddleware, EventMiddlewarePipelineResult } from "./eventMiddleware.type.js";

package/dist/eventMiddleware/eventMiddleware.pipeline.js

@@ -1,8 +1,10 @@
 /**
- * Event middleware pipeline execution for Zudojs.
+ * Event middleware pipeline execution for Zudojs, built on `compose` from
+ * `@zudojs/middleware`.
  */
+import { compose } from "@zudojs/middleware";
 import { EventDispatchAbortedError, EventMiddlewareError, toEventError, } from "../eventErrors/eventError.base.js";
-import { sortEventMiddleware, executeEventMiddleware, } from "./eventMiddleware.helper.js";
+import { sortEventMiddleware, executeEventMiddleware } from "./eventMiddleware.helper.js";
 /**
  * Executes a middleware pipeline.
  *
@@ -21,47 +23,37 @@ import { sortEventMiddleware, executeEventMiddleware, } from "./eventMiddleware.
  */
 export async function executeEventMiddlewarePipeline(middleware, context, terminal) {
     const started = performance.now();
-    const activeMiddleware = sortEventMiddleware(middleware.filter((item) => item.enabled));
     const executions = [];
-    let index = -1;
-    const dispatch = async (currentIndex) => {
-        if (context.signal.aborted) {
-            throw createAbortError(context);
-        }
-        if (currentIndex === activeMiddleware.length) {
-            return terminal();
-        }
-        if (currentIndex <= index) {
-            throw new EventMiddlewareError("Event middleware called next() more than once.", {
-                eventType: context.event?.type,
-                eventId: context.event?.id,
-            });
-        }
-        index = currentIndex;
-        const current = activeMiddleware[currentIndex];
-        if (!current) {
-            return terminal();
-        }
+    const stages = sortEventMiddleware(middleware.filter((item) => item.enabled))
+        .map((current) => toStage(current, executions));
+    const run = compose(stages, async (ctx) => {
+        throwIfAborted(ctx);
+        return terminal();
+    }, { maxDepth: Number.POSITIVE_INFINITY });
+    const result = await run(context);
+    return { result, executions, duration: performance.now() - started };
+}
+/**
+ * Adapts one registered middleware to the shared composer: checks the
+ * abort signal, rejects a second next() with an EventMiddlewareError,
+ * records the execution, and wraps only the middleware's own errors.
+ */
+function toStage(current, executions) {
+    return async (context, advance) => {
+        throwIfAborted(context);
         const middlewareStarted = performance.now();
+        const eventType = context.event?.type;
+        const eventId = context.event?.id;
         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.`, {
-                    middlewareId: current.id,
-                    eventType: context.event?.type,
-                    eventId: context.event?.id,
-                });
+                throw new EventMiddlewareError(`Middleware "${current.id}" called next() more than once.`, { middlewareId: current.id, eventType, eventId });
             }
             nextCalled = true;
             try {
-                return await dispatch(currentIndex + 1);
+                return await advance();
             }
             catch (error) {
                 downstreamThrew = true;
@@ -79,39 +71,29 @@ export async function executeEventMiddlewarePipeline(middleware, context, termin
             return result;
         }
         catch (error) {
-            if (downstreamThrew && error === downstreamError) {
-                throw error;
-            }
-            if (error instanceof EventMiddlewareError ||
+            if ((downstreamThrew && error === downstreamError) ||
+                error instanceof EventMiddlewareError ||
                 error instanceof EventDispatchAbortedError) {
                 throw error;
             }
             throw new EventMiddlewareError(`Event middleware "${current.id}" failed.`, {
                 middlewareId: current.id,
-                eventType: context.event?.type,
-                eventId: context.event?.id,
-                cause: toEventError(error, {
-                    eventType: context.event?.type,
-                    eventId: context.event?.id,
-                }),
+                eventType,
+                eventId,
+                cause: toEventError(error, { eventType, eventId }),
             });
         }
     };
-    const result = await dispatch(0);
-    return {
-        result,
-        executions,
-        duration: performance.now() - started,
-    };
 }
 /**
- * Creates the abort error thrown when the pipeline observes an
- * aborted signal.
+ * Throws the abort error when the pipeline observes an aborted signal.
  */
-function createAbortError(context) {
-    return new EventDispatchAbortedError("Event dispatch was aborted.", {
-        eventType: context.event?.type,
-        eventId: context.event?.id,
-    });
+function throwIfAborted(context) {
+    if (context.signal.aborted) {
+        throw 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

@@ -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,13 +7,20 @@
  * 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";
 import { registryClear, registryDispose, registryNotify, } from "./eventRegistry.lifecycle.js";
 export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, };
+/**
+ * Default leak-warning sink: Node's process warning channel (the same one
+ * `EventEmitter` uses for `MaxListenersExceededWarning`), which honours
+ * `--no-warnings` and `process.on("warning")`, instead of writing to the
+ * console directly. A no-op where `process.emitWarning` is unavailable.
+ */
 function defaultWarning(warning) {
-    console.warn(`[@zudojs/events] ${warning.message}`);
+    emitEventsWarning(warning.message, EVENT_HANDLER_LIMIT_WARNING_CODE);
 }
 /**
  * Main event registry.
@@ -37,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

@@ -55,12 +55,22 @@ export interface EventRegistryOptions {
     readonly onDuplicateHandlerId?: DuplicateHandlerIdPolicy;
     /**
      * Maximum handlers per event pattern before a leak warning is
-     * emitted through `onWarning` (or console.warn). Use 0 to
+     * emitted through `onWarning` (or `process.emitWarning`). Use 0 to
      * disable. Defaults to 100.
      */
     readonly maxHandlersPerPattern?: number;
     /**
-     * Receives limit warnings. Defaults to console.warn.
+     * 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`).
      */
     readonly onWarning?: (warning: EventRegistryWarning) => void;
     /**

package/dist/eventTypes/eventSnapshot.freeze.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Immutable event snapshots.
+ *
+ * The emitter used to deep-freeze the event IN PLACE, which froze the
+ * publisher's own objects (a later `cart.total = 20` threw) and left
+ * Map, Set and Date internals mutable, because `Object.freeze` does not
+ * reach them. A snapshot is a frozen COPY: the caller's graph is never
+ * touched, and Map, Set and Date are copied into read-only variants
+ * whose mutators throw.
+ */
+/** A Date whose setters throw. */
+export declare class FrozenEventDate extends Date {
+}
+/** A Map whose mutators throw once construction has finished. */
+export declare class FrozenEventMap<K, V> extends Map<K, V> {
+    set(): this;
+    delete(): boolean;
+    clear(): void;
+}
+/** A Set whose mutators throw once construction has finished. */
+export declare class FrozenEventSet<T> extends Set<T> {
+    add(): this;
+    delete(): boolean;
+    clear(): void;
+}
+/**
+ * Returns a deeply frozen copy of `value`, leaving `value` untouched.
+ *
+ * Plain objects, arrays and errors are copied (own properties, including
+ * a `__proto__` data key, are defined rather than assigned) and frozen.
+ * Map, Set and Date become {@link FrozenEventMap}, {@link FrozenEventSet}
+ * and {@link FrozenEventDate}, which still pass `instanceof Map` / `Set`
+ * / `Date` but throw on mutation. Class instances and other exotic
+ * objects are passed by reference. Cycles are preserved.
+ */
+export declare function createFrozenEventSnapshot<T>(value: T): T;
+//# sourceMappingURL=eventSnapshot.freeze.d.ts.map

package/dist/eventTypes/eventSnapshot.freeze.js

@@ -0,0 +1,117 @@
+/**
+ * Immutable event snapshots.
+ *
+ * The emitter used to deep-freeze the event IN PLACE, which froze the
+ * publisher's own objects (a later `cart.total = 20` threw) and left
+ * Map, Set and Date internals mutable, because `Object.freeze` does not
+ * reach them. A snapshot is a frozen COPY: the caller's graph is never
+ * touched, and Map, Set and Date are copied into read-only variants
+ * whose mutators throw.
+ */
+/** Throws the TypeError every read-only mutator raises. */
+function readOnly(kind) {
+    throw new TypeError(`Cannot modify a frozen event ${kind}.`);
+}
+/** A Date whose setters throw. */
+export class FrozenEventDate extends Date {
+}
+for (const key of Object.getOwnPropertyNames(Date.prototype)) {
+    if (key.startsWith("set")) {
+        Object.defineProperty(FrozenEventDate.prototype, key, {
+            value: () => readOnly("Date"),
+            configurable: true,
+            writable: true,
+        });
+    }
+}
+/** A Map whose mutators throw once construction has finished. */
+export class FrozenEventMap extends Map {
+    set() {
+        return readOnly("Map");
+    }
+    delete() {
+        return readOnly("Map");
+    }
+    clear() {
+        readOnly("Map");
+    }
+}
+/** A Set whose mutators throw once construction has finished. */
+export class FrozenEventSet extends Set {
+    add() {
+        return readOnly("Set");
+    }
+    delete() {
+        return readOnly("Set");
+    }
+    clear() {
+        readOnly("Set");
+    }
+}
+/** Whether a value is a plain object (literal or null-prototype). */
+function isPlainRecord(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function snapshot(value, seen) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (seen.has(value))
+        return seen.get(value);
+    if (value instanceof Date) {
+        const copy = Object.freeze(new FrozenEventDate(value.getTime()));
+        seen.set(value, copy);
+        return copy;
+    }
+    if (value instanceof Map) {
+        const copy = new FrozenEventMap();
+        seen.set(value, copy);
+        for (const [key, item] of value) {
+            Map.prototype.set.call(copy, key, snapshot(item, seen));
+        }
+        return Object.freeze(copy);
+    }
+    if (value instanceof Set) {
+        const copy = new FrozenEventSet();
+        seen.set(value, copy);
+        for (const item of value) {
+            Set.prototype.add.call(copy, snapshot(item, seen));
+        }
+        return Object.freeze(copy);
+    }
+    const isArray = Array.isArray(value);
+    const isError = value instanceof Error;
+    // Instances of other classes (and exotic built-ins such as typed
+    // arrays, RegExp, URL) cannot be copied faithfully — private fields and
+    // internal slots do not survive — so they are passed by reference.
+    if (!isArray && !isError && !isPlainRecord(value))
+        return value;
+    const copy = isArray
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    seen.set(value, copy);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor)
+            continue;
+        if ("value" in descriptor) {
+            descriptor.value = snapshot(descriptor.value, seen);
+        }
+        Object.defineProperty(copy, key, descriptor);
+    }
+    return Object.freeze(copy);
+}
+/**
+ * Returns a deeply frozen copy of `value`, leaving `value` untouched.
+ *
+ * Plain objects, arrays and errors are copied (own properties, including
+ * a `__proto__` data key, are defined rather than assigned) and frozen.
+ * Map, Set and Date become {@link FrozenEventMap}, {@link FrozenEventSet}
+ * and {@link FrozenEventDate}, which still pass `instanceof Map` / `Set`
+ * / `Date` but throw on mutation. Class instances and other exotic
+ * objects are passed by reference. Cycles are preserved.
+ */
+export function createFrozenEventSnapshot(value) {
+    return snapshot(value, new Map());
+}
+//# sourceMappingURL=eventSnapshot.freeze.js.map

package/dist/eventTypes/index.d.ts

@@ -6,4 +6,5 @@
 export { type EventId, type EventType, type EventTimestamp, type EventSource, type EventCorrelationId, type EventCausationId, type EventPayload, type Event, type EventInput, type EventDefinition, isEvent, createEventId, createEvent, defineEvent, withEventMetadata, createDerivedEvent, getEventType, getEventPayload, describeEvent, } from "./eventDefinition.type.js";
 export { type ObjectEventPayload, type PrimitiveEventPayload, type JsonEventPayload, type EventPayloadMap, type PayloadOf, type PayloadMap, type EventPayloadFactory, type EventPayloadOptions, isPrimitiveEventPayload, isObjectEventPayload, isJsonEventPayload, createEventPayload, createObjectEventPayload, createJsonEventPayload, cloneEventPayload, deepFreeze, stripUndefinedValues, mergeEventPayloads, staticPayload, definePayloadFactory, validateEventPayload, describeEventPayload, } from "./eventPayload.type.js";
 export { type EventTypeList, type EventTypePattern, type EventTypeOf, type EventUnion, isValidEventType, isValidEventTypePattern, normalizeEventType, normalizeEventTypePattern, tryNormalizeEventType, assertEventType, createEventType, createEventTypePattern, getEventNamespace, getEventAction, getEventTypeSegments, matchesEventType, isSameEventNamespace, isChildEventType, eventMatchesType, filterEventsByType, defineEventTypes, defineEventType, } from "./eventType.type.js";
+export { createFrozenEventSnapshot, FrozenEventDate, FrozenEventMap, FrozenEventSet, } from "./eventSnapshot.freeze.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/eventTypes/index.js

@@ -6,4 +6,5 @@
 export { isEvent, createEventId, createEvent, defineEvent, withEventMetadata, createDerivedEvent, getEventType, getEventPayload, describeEvent, } from "./eventDefinition.type.js";
 export { isPrimitiveEventPayload, isObjectEventPayload, isJsonEventPayload, createEventPayload, createObjectEventPayload, createJsonEventPayload, cloneEventPayload, deepFreeze, stripUndefinedValues, mergeEventPayloads, staticPayload, definePayloadFactory, validateEventPayload, describeEventPayload, } from "./eventPayload.type.js";
 export { isValidEventType, isValidEventTypePattern, normalizeEventType, normalizeEventTypePattern, tryNormalizeEventType, assertEventType, createEventType, createEventTypePattern, getEventNamespace, getEventAction, getEventTypeSegments, matchesEventType, isSameEventNamespace, isChildEventType, eventMatchesType, filterEventsByType, defineEventTypes, defineEventType, } from "./eventType.type.js";
+export { createFrozenEventSnapshot, FrozenEventDate, FrozenEventMap, FrozenEventSet, } from "./eventSnapshot.freeze.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/events",
-  "version": "1.0.1",
+  "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,8 +20,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1"
+    "@zudojs/constants": "1.1.1",
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/middleware": "1.0.3"
   },
   "engines": {
     "node": ">=24.0.0"