@zudojs/events 0.1.0 → 1.0.1

package/dist/eventEmitter/eventEmitter.parallel.js

@@ -1,35 +1,53 @@
 /**
  * Parallel event handler dispatch for Zudojs.
+ *
+ * All handlers start together; an AbortSignal that fires after
+ * the handlers have started cannot stop them. Handlers can observe
+ * `context.signal` to cooperate. Only a signal that is already
+ * aborted when dispatch begins rejects the emit.
  */
-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 concurrently.
  */
-export async function emitParallel(handlers, event, context, errorMode, results, errors, onOnceHandler) {
-    const executions = handlers.map(async (handler) => {
-        if (context.signal.aborted) {
-            throw createAbortError();
+export async function emitParallel(handlers, event, context, errorMode, results, errors, hooks) {
+    if (context.signal.aborted) {
+        throw createAbortError(event, results, errors);
+    }
+    /**
+     * Consume once-handlers synchronously before anything starts so
+     * 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;
         }
+        hooks.removeOnce(handler.id);
+        return true;
+    });
+    const executions = runnable.map(async (handler) => {
         const started = performance.now();
         try {
-            const result = await executeEventHandler(handler.handler, event, context);
-            const execution = {
+            const result = await executeRegisteredEventHandler(handler, event, context);
+            return {
                 handlerId: handler.id,
                 eventId: event.id,
+                ok: true,
                 result,
                 duration: performance.now() - started,
             };
-            if (handler.once) {
-                onOnceHandler(handler.id);
-            }
-            return execution;
         }
         catch (error) {
             return {
                 handlerId: handler.id,
                 eventId: event.id,
+                ok: false,
                 result: undefined,
                 duration: performance.now() - started,
                 error,
@@ -39,8 +57,8 @@ export async function emitParallel(handlers, event, context, errorMode, results,
     const settled = await Promise.all(executions);
     for (const result of settled) {
         results.push(result);
-        if (result.error !== undefined) {
-            errors.push(result.error);
+        if (!result.ok) {
+            errors.push(createEventHandlerError(result.handlerId, event.type, event.id, result.error));
         }
     }
     if (errors.length > 0 && errorMode === EventErrorMode.THROW) {

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

@@ -5,8 +5,24 @@ import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { EventHandlerContext, RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
 import type { EventHandlerExecutionResult } from "./eventEmitter.type.js";
 import { EventErrorMode } from "./eventEmitter.type.js";
+/**
+ * Callbacks the dispatch strategies use to interact with the
+ * handler store.
+ */
+export interface DispatchHooks {
+    /**
+     * Returns whether a handler is still registered.
+     */
+    readonly isRegistered: (handlerId: string) => boolean;
+    /**
+     * Removes a once-handler. Called before the handler runs so a
+     * throwing or concurrently dispatched once-handler never fires
+     * twice.
+     */
+    readonly removeOnce: (handlerId: string) => void;
+}
 /**
  * Executes handlers sequentially.
  */
-export declare function emitSequential<TEvent extends Event>(handlers: readonly RegisteredEventHandler<TEvent>[], event: TEvent, context: EventHandlerContext<TEvent>, errorMode: EventErrorMode, results: EventHandlerExecutionResult[], errors: unknown[], onOnceHandler: (handlerId: string) => void): Promise<void>;
+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>;
 //# sourceMappingURL=eventEmitter.sequential.d.ts.map

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