@zudojs/events 0.0.1 → 1.0.0

package/dist/eventEmitter/eventEmitter.sequential.js

@@ -1,42 +1,49 @@
 /**
  * Sequential event handler dispatch for Zudojs.
  */
-import { executeEventHandler } from "../eventHandler/eventHandler.core.js";
+import { executeRegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
+import { createEventHandlerError } from "../eventErrors/eventError.base.js";
 import { EventErrorMode } from "./eventEmitter.type.js";
 import { createAbortError } from "./eventEmitter.abort.js";
 /**
  * Executes handlers sequentially.
  */
-export async function emitSequential(handlers, event, context, errorMode, results, errors, onOnceHandler) {
+export async function emitSequential(handlers, event, context, errorMode, results, errors, hooks) {
     for (const handler of handlers) {
         if (context.signal.aborted) {
-            throw createAbortError();
+            throw createAbortError(event, results, errors);
+        }
+        if (handler.once) {
+            if (!hooks.isRegistered(handler.id)) {
+                // Already consumed by an overlapping dispatch.
+                continue;
+            }
+            hooks.removeOnce(handler.id);
         }
         const started = performance.now();
         try {
-            const result = await executeEventHandler(handler.handler, event, context);
+            const result = await executeRegisteredEventHandler(handler, event, context);
             results.push({
                 handlerId: handler.id,
                 eventId: event.id,
+                ok: true,
                 result,
                 duration: performance.now() - started,
             });
-            if (handler.once) {
-                onOnceHandler(handler.id);
-            }
         }
         catch (error) {
-            const execution = {
+            results.push({
                 handlerId: handler.id,
                 eventId: event.id,
+                ok: false,
                 result: undefined,
                 duration: performance.now() - started,
                 error,
-            };
-            results.push(execution);
-            errors.push(error);
+            });
+            const wrapped = createEventHandlerError(handler.id, event.type, event.id, error);
+            errors.push(wrapped);
             if (errorMode === EventErrorMode.THROW) {
-                throw error;
+                throw wrapped;
             }
         }
     }

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

@@ -4,6 +4,7 @@
 import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
 import type { EventSubscription } from "../eventSubscription/eventSubscription.core.js";
+import type { EventHandlerStore, EventRegistryWarning } from "../eventRegistry/eventRegistry.type.js";
 export declare enum EventEmitterMode {
     SEQUENTIAL = "sequential",
     PARALLEL = "parallel"
@@ -13,9 +14,39 @@ export declare enum EventErrorMode {
     CONTINUE = "continue"
 }
 export interface EventEmitterOptions {
+    /**
+     * Dispatch mode. Defaults to SEQUENTIAL.
+     */
     readonly mode?: EventEmitterMode;
+    /**
+     * Error mode. Defaults to THROW.
+     */
     readonly errorMode?: EventErrorMode;
+    /**
+     * Deep-freeze events (including their payload) before they are
+     * handed to handlers so no handler can alter what other handlers
+     * see. Defaults to true. Note that freezing mutates the payload
+     * object passed in; clone it first if you need to keep it
+     * mutable elsewhere.
+     */
     readonly freezeEvents?: boolean;
+    /**
+     * Handler store to use. When omitted the emitter creates a
+     * private EventRegistry. EventBus passes its registry so that
+     * handlers registered on either side are dispatched.
+     */
+    readonly store?: EventHandlerStore;
+    /**
+     * Maximum handlers per event pattern before a leak warning is
+     * emitted (0 disables). Only applies to the private store.
+     * Defaults to 100.
+     */
+    readonly maxListeners?: number;
+    /**
+     * Receives leak warnings. Only applies to the private store.
+     * Defaults to console.warn.
+     */
+    readonly onWarning?: (warning: EventRegistryWarning) => void;
 }
 export interface EmitOptions {
     readonly mode?: EventEmitterMode;
@@ -26,16 +57,45 @@ export interface EmitOptions {
 export interface EventHandlerExecutionResult {
     readonly handlerId: string;
     readonly eventId: string;
+    /**
+     * True when the handler settled without throwing.
+     */
+    readonly ok: boolean;
     readonly result: unknown;
     readonly duration: number;
+    /**
+     * The raw value thrown by the handler when `ok` is false.
+     */
     readonly error?: unknown;
 }
 export interface EventEmitResult<TEvent extends Event = Event> {
     readonly event: TEvent;
+    /**
+     * True when at least one handler completed successfully.
+     */
     readonly handled: boolean;
+    /**
+     * One entry per invoked handler, in invocation order.
+     */
     readonly results: readonly EventHandlerExecutionResult[];
+    /**
+     * Handler failures wrapped as EventHandlerError (cause holds the
+     * raw thrown value).
+     */
     readonly errors: readonly unknown[];
+    /**
+     * Number of handlers that completed successfully.
+     */
+    readonly succeeded: number;
+    /**
+     * Number of handlers that threw.
+     */
+    readonly failed: number;
 }
+/**
+ * @deprecated Handlers are stored in an EventRegistry; this shape
+ * is kept for type compatibility only.
+ */
 export interface EmitterListener {
     readonly registration: RegisteredEventHandler;
     readonly subscription: EventSubscription;

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

@@ -1,8 +1,55 @@
 /**
  * @zudojs/events/eventErrors/eventError.base
  *
- * All event error types are centralized in @zudojs/errors.
- * This file re-exports them for backward compatibility.
+ * 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.
  */
-export { EventError, createEventError, isEventError, toEventError, EventPublishError, InvalidEventError, EventTypeNotFoundError, EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventDispatchAbortedError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventTimeoutError, EventMiddlewareError, EventSerializationError, EventDeserializationError, } from "@zudojs/errors";
+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";
+/**
+ * Options for EventDispatchAbortedError.
+ */
+export interface EventDispatchAbortedErrorOptions {
+    readonly eventType?: string;
+    readonly eventId?: string;
+    /**
+     * Execution results collected before the abort was observed.
+     */
+    readonly results?: readonly unknown[];
+    /**
+     * Handler errors collected before the abort was observed.
+     */
+    readonly errors?: readonly unknown[];
+}
+/**
+ * Error thrown when event dispatch is aborted through an
+ * AbortSignal. Carries the partial results and errors gathered
+ * before the abort was observed so callers can see what ran.
+ */
+export declare class EventDispatchAbortedError extends BaseEventDispatchAbortedError {
+    readonly results: readonly unknown[];
+    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

@@ -1,8 +1,69 @@
 /**
  * @zudojs/events/eventErrors/eventError.base
  *
- * All event error types are centralized in @zudojs/errors.
- * This file re-exports them for backward compatibility.
+ * 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.
  */
-export { EventError, createEventError, isEventError, toEventError, EventPublishError, InvalidEventError, EventTypeNotFoundError, EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventDispatchAbortedError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventTimeoutError, EventMiddlewareError, EventSerializationError, EventDeserializationError, } from "@zudojs/errors";
+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";
+/**
+ * Error thrown when event dispatch is aborted through an
+ * AbortSignal. Carries the partial results and errors gathered
+ * before the abort was observed so callers can see what ran.
+ */
+export class EventDispatchAbortedError extends BaseEventDispatchAbortedError {
+    results;
+    errors;
+    constructor(message = "Event dispatch was aborted.", options = {}) {
+        super(message, {
+            eventType: options.eventType,
+            eventId: options.eventId,
+        });
+        this.results = Object.freeze([...(options.results ?? [])]);
+        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/eventHandler/eventHandler.core.d.ts

@@ -94,6 +94,14 @@ export interface EventHandlerOptions {
      * Whether the handler should only execute once.
      */
     readonly once?: boolean;
+    /**
+     * Optional execution timeout in milliseconds.
+     *
+     * When the handler does not settle within this time the
+     * execution fails with EventTimeoutError. Defaults to no
+     * timeout.
+     */
+    readonly timeoutMs?: number;
 }
 /**
  * Complete registered event handler.
@@ -123,6 +131,10 @@ export interface RegisteredEventHandler<TEvent extends Event = Event> {
      * Optional description.
      */
     readonly description?: string;
+    /**
+     * Optional execution timeout in milliseconds.
+     */
+    readonly timeoutMs?: number;
     /**
      * Actual handler.
      */
@@ -157,6 +169,13 @@ export declare function isEventHandler(value: unknown): value is EventHandlerLik
  * represented as a function or an object.
  */
 export declare function executeEventHandler<TEvent extends Event>(handler: EventHandlerLike<TEvent>, event: TEvent, context: EventHandlerContext<TEvent>): Promise<EventHandlerResult>;
+/**
+ * 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.
+ */
+export declare function executeRegisteredEventHandler<TEvent extends Event>(registration: RegisteredEventHandler<TEvent>, event: TEvent, context: EventHandlerContext<TEvent>): Promise<EventHandlerResult>;
 /**
  * Determines whether a registered handler should process
  * a given event.

package/dist/eventHandler/eventHandler.core.js

@@ -4,7 +4,8 @@
  * Handlers are responsible for processing events.
  * They do not own event registration or event dispatching.
  */
-import { matchesEventType } from "../eventTypes/eventType.type.js";
+import { isValidEventTypePattern, matchesEventType, normalizeEventTypePattern, } from "../eventTypes/eventType.type.js";
+import { EventTimeoutError } from "../eventErrors/eventError.base.js";
 /**
  * Generates a handler identifier.
  */
@@ -37,17 +38,43 @@ export function createEventHandlerContext(event, options = {}) {
  * Creates a registered event handler.
  */
 export function createEventHandler(handler, options = {}) {
-    const eventType = options.eventType ?? "*";
     if (!isValidHandler(handler)) {
         throw new TypeError("Invalid event handler.");
     }
+    const rawPattern = options.eventType ?? "*";
+    let eventType;
+    try {
+        eventType = normalizeEventTypePattern(rawPattern);
+    }
+    catch {
+        throw new TypeError(`Invalid event type pattern "${String(rawPattern)}".`);
+    }
+    if (!isValidEventTypePattern(eventType)) {
+        throw new TypeError(`Invalid event type pattern "${String(rawPattern)}".`);
+    }
+    const priority = options.priority ?? 0;
+    if (typeof priority !== "number" || !Number.isFinite(priority)) {
+        throw new RangeError("Event handler priority must be a finite number.");
+    }
+    if (options.id !== undefined &&
+        (typeof options.id !== "string" || options.id.length === 0)) {
+        throw new TypeError("Event handler id must be a non-empty string.");
+    }
+    const timeoutMs = options.timeoutMs;
+    if (timeoutMs !== undefined &&
+        (typeof timeoutMs !== "number" ||
+            !Number.isFinite(timeoutMs) ||
+            timeoutMs <= 0)) {
+        throw new RangeError("Event handler timeoutMs must be a positive finite number.");
+    }
     return Object.freeze({
         id: options.id ?? createEventHandlerId(),
         eventType,
-        priority: options.priority ?? 0,
+        priority,
         enabled: options.enabled ?? true,
         once: options.once ?? false,
         description: options.description,
+        timeoutMs,
         handler,
     });
 }
@@ -87,6 +114,38 @@ export async function executeEventHandler(handler, event, context) {
     }
     return handler.handle(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.
+ */
+export async function executeRegisteredEventHandler(registration, event, context) {
+    const timeoutMs = registration.timeoutMs;
+    if (timeoutMs === undefined) {
+        return executeEventHandler(registration.handler, event, context);
+    }
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new EventTimeoutError(timeoutMs, {
+                eventType: event.type,
+                eventId: event.id,
+            }));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([
+            executeEventHandler(registration.handler, event, context),
+            timeout,
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
 /**
  * Determines whether a registered handler should process
  * a given event.
@@ -104,7 +163,11 @@ export function handlerMatchesEvent(handler, event) {
  * Registration order is preserved for equal priorities.
  */
 export function sortEventHandlers(handlers) {
-    return [...handlers].sort((first, second) => second.priority - first.priority);
+    return [...handlers].sort((first, second) => {
+        const a = Number.isFinite(first.priority) ? first.priority : 0;
+        const b = Number.isFinite(second.priority) ? second.priority : 0;
+        return b - a;
+    });
 }
 /**
  * Filters handlers that can process an event.

package/dist/eventMiddleware/eventMiddleware.builder.js

@@ -1,17 +1,8 @@
 /**
  * Event middleware builder functions for Zudojs.
  */
-import { EventMiddlewareError } from "../eventErrors/eventError.base.js";
+import { EventDispatchAbortedError, EventMiddlewareError, } from "../eventErrors/eventError.base.js";
 import { createEventMiddleware } from "./eventMiddleware.helper.js";
-/**
- * Creates an AbortError without relying on a runtime-specific
- * DOMException implementation.
- */
-function createAbortError() {
-    return new EventMiddlewareError("Event middleware execution was aborted.", {
-        cause: new Error("AbortSignal was aborted."),
-    });
-}
 /**
  * Creates a middleware that executes before downstream
  * middleware and handlers.
@@ -102,7 +93,10 @@ export function disableEventMiddleware(middleware) {
 export function abortableEventMiddleware(options = {}) {
     return beforeEvent(async (context) => {
         if (context.signal.aborted) {
-            throw createAbortError();
+            throw new EventDispatchAbortedError("Event dispatch was aborted.", {
+                eventType: context.event?.type,
+                eventId: context.event?.id,
+            });
         }
     }, options);
 }

package/dist/eventMiddleware/eventMiddleware.helper.js

@@ -1,7 +1,6 @@
 /**
  * Event middleware core helpers for Zudojs.
  */
-import { EventMiddlewareError } from "../eventErrors/eventError.base.js";
 /**
  * Generates a middleware identifier.
  */

package/dist/eventMiddleware/eventMiddleware.pipeline.d.ts

@@ -13,6 +13,11 @@ import type { EventMiddlewareContext, EventMiddlewareNext, RegisteredEventMiddle
  *     → handler
  *   ← middleware B
  * ← middleware A
+ *
+ * Only errors thrown by a middleware function itself are wrapped
+ * in EventMiddlewareError. Errors coming back through next() —
+ * handler failures, aborts, downstream middleware errors — are
+ * re-thrown untouched so callers can discriminate them.
  */
 export declare function executeEventMiddlewarePipeline<TEvent extends Event, TResult>(middleware: readonly RegisteredEventMiddleware<TEvent, TResult>[], context: EventMiddlewareContext<TEvent>, terminal: EventMiddlewareNext<TResult>): Promise<EventMiddlewarePipelineResult<TResult>>;
 //# sourceMappingURL=eventMiddleware.pipeline.d.ts.map

package/dist/eventMiddleware/eventMiddleware.pipeline.js

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

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

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

package/dist/eventRegistry/eventRegistry.lifecycle.js

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