@zudojs/events 1.1.0 → 1.3.0

package/README.md

@@ -71,6 +71,9 @@ CREATED ──(first use / start)──▶ ACTIVE ◀──(start)── STOPPED
 - `stop()` moves the bus to `STOPPED`; publishing or subscribing then throws
   `EventBusStoppedError` until `start()` is called. Handlers and definitions are kept.
 - `dispose()` is final; every operation throws `EventBusDisposedError`.
+- Both errors are defined in `@zudojs/errors` (as `EventError` subclasses) and
+  re-exported from `@zudojs/events`, so `instanceof` works whichever package you
+  import them from.
 
 ## Publish results
 
@@ -90,6 +93,33 @@ In the default `CONTINUE` error mode handler failures are collected in
 `EventHandlerError` rejects the publish. Errors thrown by a middleware itself are
 wrapped as `EventMiddlewareError`; handler errors and aborts pass through unwrapped.
 
+## Middleware
+
+`bus.use()` accepts everything the `middleware` constructor option does: a
+middleware function or `{ handle }` object, or a registered middleware from
+`createEventMiddleware()` or a builder helper (`validateEventMiddleware`,
+`beforeEvent`, `aroundEvent`, `timingEventMiddleware`, …). It returns a function
+that removes the middleware again.
+
+```typescript
+const remove = bus.use(validateEventMiddleware((event) => event.payload != null));
+```
+
+## Timeouts and aborts
+
+A handler registered with `timeoutMs` fails with `EventTimeoutError` when it
+does not settle in time, and the `context.signal` it received is aborted with
+that error as its `reason`, so a handler that listens to the signal can stop
+its work. Timing out one handler does not abort the dispatch or other handlers.
+
+Pass `signal` to `publish()` to abort a sequential dispatch. The publish rejects
+with `EventDispatchAbortedError` (carrying the partial `results` and `errors`)
+when the signal is aborted before a handler starts **or while any handler is
+running — including the last or only one**, even if that handler then returns
+normally. In `PARALLEL` mode every handler has already started, so only a
+signal that is aborted before dispatch begins rejects; handlers can still
+observe `context.signal`.
+
 ## Registry
 
 `bus.register(defineEvent("order.placed"))` records a definition; with

package/dist/eventBus/eventBus.core.d.ts

@@ -8,8 +8,8 @@ import type { EventSubscription } from "../eventSubscription/eventSubscription.c
 import { EventEmitter } from "../eventEmitter/eventEmitter.core.js";
 import { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
 import { EventError } from "../eventErrors/eventError.base.js";
-import type { EventMiddlewareLike, EventMiddlewareOptions } from "../eventMiddleware/eventMiddleware.type.js";
-import type { EventBusOptions, PublishOptions, EventPublishResult, EventBusListener } from "./eventBus.type.js";
+import type { EventMiddlewareOptions } from "../eventMiddleware/eventMiddleware.type.js";
+import type { EventBusMiddlewareItem, EventBusOptions, PublishOptions, EventPublishResult, EventBusListener } from "./eventBus.type.js";
 import { EventBusState } from "./eventBus.type.js";
 export { EventBusState } from "./eventBus.type.js";
 /**
@@ -40,7 +40,12 @@ export declare class EventBus {
     once<TEvent extends Event = Event>(eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options?: Omit<EventHandlerOptions, "eventType" | "once">): EventSubscription;
     onAny<TEvent extends Event = Event>(handler: EventHandlerLike<TEvent>, options?: Omit<EventHandlerOptions, "eventType">): EventSubscription;
     off(subscription: EventSubscription): boolean;
-    use(middleware: EventMiddlewareLike, options?: EventMiddlewareOptions): () => void;
+    /**
+     * Adds bus middleware: a middleware function or object, or a
+     * registered middleware from createEventMiddleware() or a builder
+     * helper such as validateEventMiddleware().
+     */
+    use(middleware: EventBusMiddlewareItem, options?: EventMiddlewareOptions): () => void;
     publish<TEvent extends Event>(event: TEvent, options?: PublishOptions): Promise<EventPublishResult<TEvent>>;
     publishEvent<TPayload>(input: EventInput<TPayload>, options?: PublishOptions): Promise<EventPublishResult<Event<TPayload>>>;
     /**

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, {
@@ -98,6 +100,11 @@ export class EventBus {
     off(subscription) {
         return busOff(this.emitter, subscription, () => this.ensureNotDisposed());
     }
+    /**
+     * Adds bus middleware: a middleware function or object, or a
+     * registered middleware from createEventMiddleware() or a builder
+     * helper such as validateEventMiddleware().
+     */
     use(middleware, options = {}) {
         this.ensureNotDisposed();
         return busUse(this.busMiddleware, middleware, options);
@@ -235,16 +242,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.registration.d.ts

@@ -5,7 +5,7 @@ import type { Event, EventDefinition, EventType } from "../eventTypes/eventDefin
 import type { EventTypePattern } from "../eventTypes/eventType.type.js";
 import type { EventHandlerLike, EventHandlerOptions } from "../eventHandler/eventHandler.core.js";
 import type { EventSubscription } from "../eventSubscription/eventSubscription.core.js";
-import type { EventMiddlewareLike, EventMiddlewareOptions, RegisteredEventMiddleware } from "../eventMiddleware/eventMiddleware.type.js";
+import type { EventMiddlewareOptions, RegisteredEventMiddleware } from "../eventMiddleware/eventMiddleware.type.js";
 import type { RegisteredEventDefinition } from "../eventRegistry/eventRegistry.type.js";
 import type { EventBusMiddlewareItem } from "./eventBus.type.js";
 /**
@@ -39,8 +39,15 @@ export declare function busOff(emitter: {
  * Adds middleware to the bus. The middleware is validated
  * eagerly (invalid middleware or a non-finite priority throw
  * here, not on the next publish).
+ *
+ * Accepts the same items as the `middleware` constructor option: a
+ * plain middleware function or object, or a registered middleware
+ * made by createEventMiddleware() or a builder helper such as
+ * validateEventMiddleware(). For a registered middleware its own id,
+ * description, priority and enabled flag are kept unless `options`
+ * overrides them.
  */
-export declare function busUse(busMiddleware: RegisteredEventMiddleware[], middleware: EventMiddlewareLike, options?: EventMiddlewareOptions): () => void;
+export declare function busUse(busMiddleware: RegisteredEventMiddleware[], middleware: EventBusMiddlewareItem, options?: EventMiddlewareOptions): () => void;
 /**
  * Determines whether a value is an already registered middleware
  * (created by createEventMiddleware or a builder helper).

package/dist/eventBus/eventBus.registration.js

@@ -42,9 +42,23 @@ export function busOff(emitter, subscription, ensureNotDisposed) {
  * Adds middleware to the bus. The middleware is validated
  * eagerly (invalid middleware or a non-finite priority throw
  * here, not on the next publish).
+ *
+ * Accepts the same items as the `middleware` constructor option: a
+ * plain middleware function or object, or a registered middleware
+ * made by createEventMiddleware() or a builder helper such as
+ * validateEventMiddleware(). For a registered middleware its own id,
+ * description, priority and enabled flag are kept unless `options`
+ * overrides them.
  */
 export function busUse(busMiddleware, middleware, options = {}) {
-    const registered = createEventMiddleware(middleware, options);
+    const registered = isRegisteredEventMiddleware(middleware)
+        ? createEventMiddleware(middleware.middleware, {
+            id: options.id ?? middleware.id,
+            description: options.description ?? middleware.description,
+            priority: options.priority ?? middleware.priority,
+            enabled: options.enabled ?? middleware.enabled,
+        })
+        : createEventMiddleware(middleware, options);
     busMiddleware.push(registered);
     return () => {
         const idx = busMiddleware.indexOf(registered);

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

@@ -1,6 +1,7 @@
 /**
  * Event bus type definitions for Zudojs.
  */
+import type { EventHandlerError } from "@zudojs/errors";
 import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { EventEmitterMode, EventErrorMode } from "../eventEmitter/eventEmitter.type.js";
 import type { EventMiddlewareLike, RegisteredEventMiddleware } from "../eventMiddleware/eventMiddleware.type.js";
@@ -36,6 +37,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;
@@ -88,7 +94,11 @@ export interface EventPublishResult<TEvent extends Event = Event> {
      */
     readonly failed: number;
     readonly results: readonly unknown[];
-    readonly errors: readonly unknown[];
+    /**
+     * Handler failures, each wrapped as EventHandlerError (its
+     * `cause` is the raw thrown value).
+     */
+    readonly errors: readonly EventHandlerError[];
     /**
      * True when a middleware did not call next(), so no handler ran.
      */

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.parallel.d.ts

@@ -8,11 +8,12 @@
  */
 import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { EventHandlerContext, RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
+import { type EventHandlerError } from "../eventErrors/eventError.base.js";
 import type { EventHandlerExecutionResult } from "./eventEmitter.type.js";
 import { EventErrorMode } from "./eventEmitter.type.js";
 import type { DispatchHooks } from "./eventEmitter.sequential.js";
 /**
  * Executes handlers concurrently.
  */
-export declare function emitParallel<TEvent extends Event>(handlers: readonly RegisteredEventHandler<TEvent>[], event: TEvent, context: EventHandlerContext<TEvent>, errorMode: EventErrorMode, results: EventHandlerExecutionResult[], errors: unknown[], hooks: DispatchHooks): Promise<void>;
+export declare function emitParallel<TEvent extends Event>(handlers: readonly RegisteredEventHandler<TEvent>[], event: TEvent, context: EventHandlerContext<TEvent>, errorMode: EventErrorMode, results: EventHandlerExecutionResult[], errors: EventHandlerError[], hooks: DispatchHooks): Promise<void>;
 //# sourceMappingURL=eventEmitter.parallel.d.ts.map

package/dist/eventEmitter/eventEmitter.parallel.js

@@ -7,7 +7,7 @@
  * aborted when dispatch begins rejects the emit.
  */
 import { executeRegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
-import { createEventHandlerError } from "../eventErrors/eventError.base.js";
+import { createEventHandlerError, } from "../eventErrors/eventError.base.js";
 import { EventErrorMode } from "./eventEmitter.type.js";
 import { createAbortError } from "./eventEmitter.abort.js";
 /**

package/dist/eventEmitter/eventEmitter.sequential.d.ts

@@ -3,6 +3,7 @@
  */
 import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { EventHandlerContext, RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
+import { type EventHandlerError } from "../eventErrors/eventError.base.js";
 import type { EventHandlerExecutionResult } from "./eventEmitter.type.js";
 import { EventErrorMode } from "./eventEmitter.type.js";
 /**
@@ -23,6 +24,11 @@ export interface DispatchHooks {
 }
 /**
  * Executes handlers sequentially.
+ *
+ * Rejects with EventDispatchAbortedError when the dispatch signal is
+ * aborted before a handler starts or while any handler — including
+ * the last or only one — is running, even if that handler then
+ * returns normally.
  */
-export declare function emitSequential<TEvent extends Event>(handlers: readonly RegisteredEventHandler<TEvent>[], event: TEvent, context: EventHandlerContext<TEvent>, errorMode: EventErrorMode, results: EventHandlerExecutionResult[], errors: unknown[], hooks: DispatchHooks): Promise<void>;
+export declare function emitSequential<TEvent extends Event>(handlers: readonly RegisteredEventHandler<TEvent>[], event: TEvent, context: EventHandlerContext<TEvent>, errorMode: EventErrorMode, results: EventHandlerExecutionResult[], errors: EventHandlerError[], hooks: DispatchHooks): Promise<void>;
 //# sourceMappingURL=eventEmitter.sequential.d.ts.map

package/dist/eventEmitter/eventEmitter.sequential.js

@@ -2,11 +2,16 @@
  * Sequential event handler dispatch for Zudojs.
  */
 import { executeRegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
-import { createEventHandlerError } from "../eventErrors/eventError.base.js";
+import { createEventHandlerError, } from "../eventErrors/eventError.base.js";
 import { EventErrorMode } from "./eventEmitter.type.js";
 import { createAbortError } from "./eventEmitter.abort.js";
 /**
  * Executes handlers sequentially.
+ *
+ * Rejects with EventDispatchAbortedError when the dispatch signal is
+ * aborted before a handler starts or while any handler — including
+ * the last or only one — is running, even if that handler then
+ * returns normally.
  */
 export async function emitSequential(handlers, event, context, errorMode, results, errors, hooks) {
     for (const handler of handlers) {
@@ -49,5 +54,12 @@ export async function emitSequential(handlers, event, context, errorMode, result
             }
         }
     }
+    // The check at the top of the loop only runs before the *next*
+    // handler, so an abort during the last (or only) handler used to
+    // resolve as a normal, successful dispatch — while the same abort
+    // with a handler still to come rejected.
+    if (context.signal.aborted) {
+        throw createAbortError(event, results, errors);
+    }
 }
 //# sourceMappingURL=eventEmitter.sequential.js.map

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

@@ -1,6 +1,7 @@
 /**
  * Event emitter type definitions for Zudojs.
  */
+import type { EventHandlerError } from "@zudojs/errors";
 import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
 import type { EventSubscription } from "../eventSubscription/eventSubscription.core.js";
@@ -42,6 +43,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`).
@@ -82,7 +88,7 @@ export interface EventEmitResult<TEvent extends Event = Event> {
      * Handler failures wrapped as EventHandlerError (cause holds the
      * raw thrown value).
      */
-    readonly errors: readonly unknown[];
+    readonly errors: readonly EventHandlerError[];
     /**
      * Number of handlers that completed successfully.
      */

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

@@ -2,11 +2,12 @@
  * @zudojs/events/eventErrors/eventError.base
  *
  * Event error types are centralized in @zudojs/errors and
- * re-exported here. A few event-bus specific errors that the
- * errors package does not define yet live in this file.
+ * re-exported here, including EventBusStoppedError and
+ * EventBusDisposedError. EventDispatchAbortedError is extended here
+ * to carry the partial results of an aborted dispatch.
  */
-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";
+import { EventDispatchAbortedError as BaseEventDispatchAbortedError } 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, EventBusDisposedError, EventBusStoppedError, } from "@zudojs/errors";
 /**
  * Options for EventDispatchAbortedError.
  */
@@ -32,24 +33,4 @@ export declare class EventDispatchAbortedError extends BaseEventDispatchAbortedE
     readonly errors: readonly unknown[];
     constructor(message?: string, options?: EventDispatchAbortedErrorOptions);
 }
-/**
- * Error thrown when an EventBus is used after dispose().
- */
-export declare class EventBusDisposedError extends EventError {
-    constructor();
-}
-/**
- * Error thrown when publishing or subscribing on a stopped
- * EventBus. Call start() to resume.
- */
-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

@@ -2,11 +2,12 @@
  * @zudojs/events/eventErrors/eventError.base
  *
  * Event error types are centralized in @zudojs/errors and
- * re-exported here. A few event-bus specific errors that the
- * errors package does not define yet live in this file.
+ * re-exported here, including EventBusStoppedError and
+ * EventBusDisposedError. EventDispatchAbortedError is extended here
+ * to carry the partial results of an aborted dispatch.
  */
-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";
+import { EventDispatchAbortedError as BaseEventDispatchAbortedError } 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, EventBusDisposedError, EventBusStoppedError, } from "@zudojs/errors";
 /**
  * Error thrown when event dispatch is aborted through an
  * AbortSignal. Carries the partial results and errors gathered
@@ -24,46 +25,4 @@ export class EventDispatchAbortedError extends BaseEventDispatchAbortedError {
         this.errors = Object.freeze([...(options.errors ?? [])]);
     }
 }
-/**
- * Error thrown when an EventBus is used after dispose().
- */
-export class EventBusDisposedError extends EventError {
-    constructor() {
-        super("Event bus has already been disposed.", {
-            code: ErrorCode.LIFECYCLE_DISPOSED,
-            statusCode: 500,
-            expose: false,
-            isOperational: false,
-        });
-    }
-}
-/**
- * Error thrown when publishing or subscribing on a stopped
- * EventBus. Call start() to resume.
- */
-export class EventBusStoppedError extends EventError {
-    constructor(operation) {
-        super(`Cannot ${operation} on a stopped event bus. Call start() first.`, {
-            code: ErrorCode.LIFECYCLE_STATE,
-            statusCode: 500,
-            expose: false,
-            isOperational: true,
-            metadata: { operation },
-        });
-    }
-}
-/**
- * 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/eventHandler/eventHandler.core.d.ts

@@ -172,8 +172,15 @@ export declare function executeEventHandler<TEvent extends Event>(handler: Event
 /**
  * Executes a registered handler, applying its timeout when one
  * is configured. A timed-out execution rejects with
- * EventTimeoutError; the underlying handler keeps running but its
- * eventual result is ignored.
+ * EventTimeoutError and aborts the `context.signal` the handler
+ * received (its `reason` is that EventTimeoutError), so a handler
+ * that observes the signal can stop its work. A handler that
+ * ignores the signal keeps running, but its eventual result is
+ * ignored.
+ *
+ * The handler's signal also follows the dispatch signal: aborting
+ * the publish aborts it too. Timing out one handler does not abort
+ * the dispatch or any other handler.
  */
 export declare function executeRegisteredEventHandler<TEvent extends Event>(registration: RegisteredEventHandler<TEvent>, event: TEvent, context: EventHandlerContext<TEvent>): Promise<EventHandlerResult>;
 /**

package/dist/eventHandler/eventHandler.core.js

@@ -117,8 +117,15 @@ export async function executeEventHandler(handler, event, context) {
 /**
  * Executes a registered handler, applying its timeout when one
  * is configured. A timed-out execution rejects with
- * EventTimeoutError; the underlying handler keeps running but its
- * eventual result is ignored.
+ * EventTimeoutError and aborts the `context.signal` the handler
+ * received (its `reason` is that EventTimeoutError), so a handler
+ * that observes the signal can stop its work. A handler that
+ * ignores the signal keeps running, but its eventual result is
+ * ignored.
+ *
+ * The handler's signal also follows the dispatch signal: aborting
+ * the publish aborts it too. Timing out one handler does not abort
+ * the dispatch or any other handler.
  */
 export async function executeRegisteredEventHandler(registration, event, context) {
     const timeoutMs = registration.timeoutMs;
@@ -126,17 +133,24 @@ export async function executeRegisteredEventHandler(registration, event, context
         return executeEventHandler(registration.handler, event, context);
     }
     let timer;
+    const deadline = new AbortController();
+    const handlerContext = Object.freeze({
+        ...context,
+        signal: AbortSignal.any([context.signal, deadline.signal]),
+    });
     const timeout = new Promise((_resolve, reject) => {
         timer = setTimeout(() => {
-            reject(new EventTimeoutError(timeoutMs, {
+            const error = new EventTimeoutError(timeoutMs, {
                 eventType: event.type,
                 eventId: event.id,
-            }));
+            });
+            deadline.abort(error);
+            reject(error);
         }, timeoutMs);
     });
     try {
         return await Promise.race([
-            executeEventHandler(registration.handler, event, context),
+            executeEventHandler(registration.handler, event, handlerContext),
             timeout,
         ]);
     }

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.3.0",
   "description": "Event-driven architecture with event bus, emitter, middleware, and registry for decoupled communication.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,15 +20,15 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/middleware": "1.0.2"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/middleware": "1.1.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
-    "vitest": "^4.1.11",
+    "vitest": "^5.0.1",
     "typescript": "7.0.2"
   },
   "license": "MIT",
@@ -45,7 +45,7 @@
     "event-bus",
     "pubsub"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-events",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },