@zudojs/events 0.0.1 → 1.0.0

package/README.md

@@ -11,32 +11,91 @@ npm install @zudojs/events
 ## Quick Start
 
 ```typescript
-import { createEventBus } from "@zudojs/events";
+import { createEventBus, defineEvent } from "@zudojs/events";
+
+interface UserCreated {
+  readonly id: string;
+  readonly name: string;
+}
 
 const bus = createEventBus();
 
+const UserCreatedEvent = defineEvent<"user.created", UserCreated>("user.created");
+
 bus.on("user.created", (event) => {
-  console.log("New user:", event.payload.id);
+  console.log("New user:", (event.payload as UserCreated).id);
 });
 
-await bus.emit({
+// Publish from an event definition …
+await bus.publish(UserCreatedEvent.create({ id: "123", name: "Alice" }));
+
+// … or from plain event input.
+await bus.publishEvent({
   type: "user.created",
-  payload: { id: "123", name: "Alice" },
+  payload: { id: "124", name: "Bob" },
 });
 ```
 
+`bus.emit()` accepts either a full `Event` or an `EventInput` and behaves like
+`publish` / `publishEvent` respectively.
+
 ## Features
 
-- Event bus with middleware pipeline
-- Event emitter with typed payloads
-- Event registry for documentation and validation
-- Wildcard event subscriptions
-- Async event handlers
-- Event replay and history
+- Event bus with a middleware pipeline (`use()`, constructor and per-publish middleware)
+- Sequential or parallel handler dispatch with `THROW` / `CONTINUE` error modes
+- Handler priorities, one-time handlers, per-handler timeouts
+- Wildcard subscriptions (`"user.*"`, `"*"`)
+- Event registry for typed definitions; handlers registered on the registry are dispatched by the bus
+- Deep-frozen events (`freezeEvents`, on by default) so handlers cannot alter what other handlers see
+- Listener-leak warnings (`maxListeners`) and an `onError` hook for fire-and-forget publishes
+- Typed error classes from `@zudojs/errors` (`EventHandlerError`, `EventMiddlewareError`, `EventDispatchAbortedError`, …)
+
+## Lifecycle
+
+```
+CREATED ──(first use / start)──▶ ACTIVE ◀──(start)── STOPPED
+                                   │                     ▲
+                                   └──────(stop)─────────┘
+                                   ▼
+                               DISPOSED
+```
+
+- A `CREATED` bus starts itself on the first `publish` / `on`.
+- `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`.
+
+## Publish results
+
+```typescript
+const result = await bus.publish(event);
+
+result.handled;        // true when at least one handler succeeded
+result.handlerCount;   // handlers invoked
+result.succeeded;      // handlers that completed
+result.failed;         // handlers that threw
+result.errors;         // EventHandlerError[] (cause = the raw thrown value)
+result.shortCircuited; // true when a middleware did not call next()
+```
+
+In the default `CONTINUE` error mode handler failures are collected in
+`result.errors` (and forwarded to the `onError` option). In `THROW` mode the first
+`EventHandlerError` rejects the publish. Errors thrown by a middleware itself are
+wrapped as `EventMiddlewareError`; handler errors and aborts pass through unwrapped.
+
+## Registry
+
+`bus.register(defineEvent("order.placed"))` records a definition; with
+`requireRegistration: true` the bus rejects unregistered types with
+`EventTypeNotFoundError`. `bus.unregister(type)` removes only the definition; pass
+`{ removeHandlers: true }` to also drop handlers subscribed to exactly that type.
+
+Event types are normalised (trimmed, lower-cased) everywhere, so `"User.Created"`
+and `"user.created"` refer to the same event.
 
 ## Use Cases
 
 - Decoupling application components
 - Audit logging and change tracking
 - Real-time notifications
-- CQRS event sourcing
+- CQRS event publishing (see `@zudojs/cqrs`)

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

@@ -14,6 +14,11 @@ import { EventBusState } from "./eventBus.type.js";
 export { EventBusState } from "./eventBus.type.js";
 /**
  * High-level event bus.
+ *
+ * Lifecycle: CREATED → ACTIVE ⇄ STOPPED → DISPOSED. A CREATED bus
+ * starts itself on first use; a STOPPED bus rejects publishing and
+ * subscribing until start() is called; a DISPOSED bus rejects
+ * everything.
  */
 export declare class EventBus {
     private readonly emitter;
@@ -24,6 +29,11 @@ export declare class EventBus {
     private state;
     constructor(options?: EventBusOptions);
     start(): this;
+    /**
+     * Stops the bus. Publishing and subscribing throw
+     * EventBusStoppedError until start() is called again; handlers
+     * and definitions are kept.
+     */
     stop(): this;
     register<TType extends EventType, TPayload>(definition: EventDefinition<TType, TPayload>): import("../index.js").RegisteredEventDefinition<TType, TPayload>;
     on<TEvent extends Event = Event>(eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options?: Omit<EventHandlerOptions, "eventType">): EventSubscription;
@@ -33,10 +43,22 @@ export declare class EventBus {
     use(middleware: EventMiddlewareLike, 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>>>;
-    emit<TEvent extends Event>(event: TEvent, options?: PublishOptions): Promise<EventPublishResult<TEvent>>;
+    /**
+     * Publishes an event or event input. A full Event is published
+     * as is; an EventInput ({ type, payload, ... }) is turned into
+     * an event first.
+     */
+    emit<TPayload>(input: Event<TPayload> | EventInput<TPayload>, options?: PublishOptions): Promise<EventPublishResult<Event<TPayload>>>;
     getDefinition<TType extends EventType, TPayload = unknown>(eventType: TType): import("../index.js").RegisteredEventDefinition<TType, TPayload> | undefined;
     hasEvent(eventType: EventType): boolean;
-    unregister(eventType: EventType): boolean;
+    /**
+     * Removes an event definition. Handlers are not affected unless
+     * `removeHandlers` is true, in which case every handler whose
+     * pattern is exactly this event type is unregistered too.
+     */
+    unregister(eventType: EventType, options?: {
+        readonly removeHandlers?: boolean;
+    }): boolean;
     getRegistry(): EventRegistry;
     getEmitter(): EventEmitter;
     getDefinitions(): readonly import("../index.js").RegisteredEventDefinition<string, unknown>[];
@@ -48,6 +70,10 @@ export declare class EventBus {
     subscribe(listener: EventBusListener): () => void;
     dispose(): void;
     toError(error: unknown, event?: Event): EventError;
+    private publishDependencies;
+    /**
+     * Auto-starts a CREATED bus; rejects a STOPPED or DISPOSED one.
+     */
     private ensureUsable;
     private ensureNotDisposed;
     private notify;

package/dist/eventBus/eventBus.core.js

@@ -1,16 +1,22 @@
 /**
  * Event bus core class for Zudojs.
  */
+import { isEvent } from "../eventTypes/eventDefinition.type.js";
 import { EventEmitter } from "../eventEmitter/eventEmitter.core.js";
 import { EventErrorMode } from "../eventEmitter/eventEmitter.type.js";
 import { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
-import { EventError, toEventError } from "../eventErrors/eventError.base.js";
+import { EventBusDisposedError, EventBusStoppedError, EventError, toEventError, } from "../eventErrors/eventError.base.js";
 import { EventBusState } from "./eventBus.type.js";
 export { EventBusState } from "./eventBus.type.js";
 import { busOn, busOnce, busOnAny, busOff, busUse, registerMiddlewareItem, } from "./eventBus.registration.js";
 import { busPublish, busPublishEvent } from "./eventBus.publish.js";
 /**
  * High-level event bus.
+ *
+ * Lifecycle: CREATED → ACTIVE ⇄ STOPPED → DISPOSED. A CREATED bus
+ * starts itself on first use; a STOPPED bus rejects publishing and
+ * subscribing until start() is called; a DISPOSED bus rejects
+ * everything.
  */
 export class EventBus {
     emitter;
@@ -22,11 +28,27 @@ export class EventBus {
     constructor(options = {}) {
         this.options = {
             requireRegistration: options.requireRegistration ?? false,
+            onError: options.onError,
         };
-        this.registry = new EventRegistry(options.registry);
+        this.registry = new EventRegistry({
+            ...options.registry,
+            maxHandlersPerPattern: options.emitter?.maxListeners,
+            onWarning: options.onWarning,
+            onError: options.onError
+                ? (error, context) => options.onError?.(error, {
+                    source: context.source,
+                })
+                : undefined,
+        });
+        /**
+         * The emitter stores its handlers in the bus registry so
+         * handlers registered through either surface are dispatched.
+         */
         this.emitter = new EventEmitter({
-            ...options.emitter,
+            mode: options.emitter?.mode,
             errorMode: options.emitter?.errorMode ?? EventErrorMode.CONTINUE,
+            freezeEvents: options.emitter?.freezeEvents,
+            store: this.registry,
         });
         this.busMiddleware = (options.middleware ?? []).map((m, index) => registerMiddlewareItem(m, index));
     }
@@ -42,12 +64,17 @@ export class EventBus {
         });
         return this;
     }
+    /**
+     * Stops the bus. Publishing and subscribing throw
+     * EventBusStoppedError until start() is called again; handlers
+     * and definitions are kept.
+     */
     stop() {
         this.ensureNotDisposed();
         if (this.state !== EventBusState.ACTIVE) {
             return this;
         }
-        this.state = EventBusState.CREATED;
+        this.state = EventBusState.STOPPED;
         this.notify({
             type: "stopped",
             timestamp: new Date(),
@@ -55,17 +82,17 @@ export class EventBus {
         return this;
     }
     register(definition) {
-        this.ensureUsable();
+        this.ensureUsable("register");
         return this.registry.register(definition);
     }
     on(eventType, handler, options = {}) {
-        return busOn(this.emitter, eventType, handler, options, () => this.ensureUsable());
+        return busOn(this.emitter, eventType, handler, options, () => this.ensureUsable("subscribe"));
     }
     once(eventType, handler, options = {}) {
-        return busOnce(this.emitter, eventType, handler, options, () => this.ensureUsable());
+        return busOnce(this.emitter, eventType, handler, options, () => this.ensureUsable("subscribe"));
     }
     onAny(handler, options = {}) {
-        return busOnAny(this.emitter, handler, options, () => this.ensureUsable());
+        return busOnAny(this.emitter, handler, options, () => this.ensureUsable("subscribe"));
     }
     off(subscription) {
         return busOff(this.emitter, subscription, () => this.ensureNotDisposed());
@@ -75,41 +102,63 @@ export class EventBus {
         return busUse(this.busMiddleware, middleware, options);
     }
     async publish(event, options = {}) {
-        return busPublish(event, options, this.emitter, this.registry, this.busMiddleware, this.options.requireRegistration, () => this.ensureUsable(), (e) => this.notify(e));
+        return busPublish(event, options, this.publishDependencies());
     }
     async publishEvent(input, options = {}) {
-        return busPublishEvent(input, options, this.emitter, this.registry, this.busMiddleware, this.options.requireRegistration, () => this.ensureUsable(), (e) => this.notify(e));
-    }
-    async emit(event, options = {}) {
-        return this.publish(event, options);
+        return busPublishEvent(input, options, this.publishDependencies());
+    }
+    /**
+     * Publishes an event or event input. A full Event is published
+     * as is; an EventInput ({ type, payload, ... }) is turned into
+     * an event first.
+     */
+    async emit(input, options = {}) {
+        if (isEvent(input)) {
+            return this.publish(input, options);
+        }
+        return this.publishEvent(input, options);
     }
     getDefinition(eventType) {
-        this.ensureUsable();
+        this.ensureNotDisposed();
         return this.registry.get(eventType);
     }
     hasEvent(eventType) {
-        this.ensureUsable();
+        this.ensureNotDisposed();
         return this.registry.has(eventType);
     }
-    unregister(eventType) {
-        this.ensureUsable();
-        return this.registry.unregister(eventType);
+    /**
+     * Removes an event definition. Handlers are not affected unless
+     * `removeHandlers` is true, in which case every handler whose
+     * pattern is exactly this event type is unregistered too.
+     */
+    unregister(eventType, options = {}) {
+        this.ensureNotDisposed();
+        const removed = this.registry.unregister(eventType);
+        if (options.removeHandlers) {
+            const definition = this.registry.getHandlersForType(eventType);
+            for (const handler of definition) {
+                if (handler.eventType !== "*" && !handler.eventType.endsWith(".*")) {
+                    this.registry.unregisterHandler(handler.id);
+                }
+            }
+        }
+        return removed;
     }
     getRegistry() {
-        this.ensureUsable();
+        this.ensureNotDisposed();
         return this.registry;
     }
     getEmitter() {
-        this.ensureUsable();
+        this.ensureNotDisposed();
         return this.emitter;
     }
     getDefinitions() {
-        this.ensureUsable();
+        this.ensureNotDisposed();
         return this.registry.getDefinitions();
     }
     getHandlers() {
-        this.ensureUsable();
-        return this.emitter.getRegistrations();
+        this.ensureNotDisposed();
+        return this.registry.getHandlers();
     }
     getState() {
         return this.state;
@@ -121,7 +170,7 @@ export class EventBus {
         return this.registry.eventCount;
     }
     get handlerCount() {
-        return this.emitter.listenerCount;
+        return this.registry.handlerCount;
     }
     subscribe(listener) {
         this.ensureNotDisposed();
@@ -145,17 +194,32 @@ export class EventBus {
             eventId: event?.id,
         });
     }
-    ensureUsable() {
+    publishDependencies() {
+        return {
+            emitter: this.emitter,
+            registry: this.registry,
+            busMiddleware: this.busMiddleware,
+            requireRegistration: this.options.requireRegistration,
+            ensureUsable: () => this.ensureUsable("publish"),
+            notify: (e) => this.notify(e),
+            onError: this.options.onError,
+        };
+    }
+    /**
+     * Auto-starts a CREATED bus; rejects a STOPPED or DISPOSED one.
+     */
+    ensureUsable(operation) {
         this.ensureNotDisposed();
+        if (this.state === EventBusState.STOPPED) {
+            throw new EventBusStoppedError(operation);
+        }
         if (this.state === EventBusState.CREATED) {
             this.start();
         }
     }
     ensureNotDisposed() {
         if (this.state === EventBusState.DISPOSED) {
-            throw new EventError("Event bus has already been disposed.", {
-                code: "EVENT_BUS_DISPOSED",
-            });
+            throw new EventBusDisposedError();
         }
     }
     notify(event) {
@@ -163,11 +227,20 @@ export class EventBus {
             try {
                 listener(event);
             }
-            catch {
+            catch (error) {
                 /**
-                 * Observers must never be able to break
-                 * event bus operations.
+                 * Observers must never be able to break event bus
+                 * operations; failures go to the onError hook.
                  */
+                try {
+                    this.options.onError?.(error, {
+                        source: "observer",
+                        event: event.event,
+                    });
+                }
+                catch {
+                    // Ignore failures of the error hook itself.
+                }
             }
         }
     }

package/dist/eventBus/eventBus.publish.d.ts

@@ -2,16 +2,34 @@
  * Event bus publish methods for Zudojs.
  */
 import type { Event, EventInput } from "../eventTypes/eventDefinition.type.js";
-import { EventEmitter } from "../eventEmitter/eventEmitter.core.js";
-import { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
+import type { EventEmitter } from "../eventEmitter/eventEmitter.core.js";
+import type { EventEmitResult } from "../eventEmitter/eventEmitter.type.js";
+import type { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
 import type { RegisteredEventMiddleware } from "../eventMiddleware/eventMiddleware.type.js";
-import type { PublishOptions, EventPublishResult, EventBusEvent } from "./eventBus.type.js";
+import type { PublishOptions, EventPublishResult, EventBusEvent, EventBusErrorContext } from "./eventBus.type.js";
+/**
+ * Dependencies the publish functions need from the bus.
+ */
+export interface BusPublishDependencies {
+    readonly emitter: EventEmitter;
+    readonly registry: EventRegistry;
+    readonly busMiddleware: readonly RegisteredEventMiddleware[];
+    readonly requireRegistration: boolean;
+    readonly ensureUsable: () => void;
+    readonly notify: (e: EventBusEvent) => void;
+    readonly onError?: (error: unknown, context: EventBusErrorContext) => void;
+}
+/**
+ * Determines whether a middleware pipeline result is the emit
+ * result produced by the terminal handler dispatch.
+ */
+export declare function isEventEmitResult(value: unknown): value is EventEmitResult;
 /**
  * Publishes an event through the bus.
  */
-export declare function busPublish<TEvent extends Event>(event: TEvent, options: PublishOptions, emitter: EventEmitter, registry: EventRegistry, busMiddleware: RegisteredEventMiddleware[], requireRegistration: boolean, ensureUsable: () => void, notify: (e: EventBusEvent) => void): Promise<EventPublishResult<TEvent>>;
+export declare function busPublish<TEvent extends Event>(event: TEvent, options: PublishOptions, deps: BusPublishDependencies): Promise<EventPublishResult<TEvent>>;
 /**
  * Creates and publishes an event from input data.
  */
-export declare function busPublishEvent<TPayload>(input: EventInput<TPayload>, options: PublishOptions, emitter: EventEmitter, registry: EventRegistry, busMiddleware: RegisteredEventMiddleware[], requireRegistration: boolean, ensureUsable: () => void, notify: (e: EventBusEvent) => void): Promise<EventPublishResult<Event<TPayload>>>;
+export declare function busPublishEvent<TPayload>(input: EventInput<TPayload>, options: PublishOptions, deps: BusPublishDependencies): Promise<EventPublishResult<Event<TPayload>>>;
 //# sourceMappingURL=eventBus.publish.d.ts.map

package/dist/eventBus/eventBus.publish.js

@@ -1,78 +1,118 @@
 /**
  * Event bus publish methods for Zudojs.
  */
-import { createEvent } from "../eventTypes/eventDefinition.type.js";
-import { EventEmitter } from "../eventEmitter/eventEmitter.core.js";
-import { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
-import { EventDispatchAbortedError, EventError, toEventError, } from "../eventErrors/eventError.base.js";
+import { createEvent, isEvent } from "../eventTypes/eventDefinition.type.js";
+import { EventDispatchAbortedError, EventTypeNotFoundError, InvalidEventError, } from "../eventErrors/eventError.base.js";
 import { createEventMiddlewareContext } from "../eventMiddleware/eventMiddleware.helper.js";
 import { executeEventMiddlewarePipeline } from "../eventMiddleware/eventMiddleware.pipeline.js";
 import { registerMiddlewareItem } from "./eventBus.registration.js";
+/**
+ * Determines whether a middleware pipeline result is the emit
+ * result produced by the terminal handler dispatch.
+ */
+export function isEventEmitResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.handled === "boolean" &&
+        Array.isArray(value.results) &&
+        Array.isArray(value.errors));
+}
 /**
  * Publishes an event through the bus.
  */
-export async function busPublish(event, options, emitter, registry, busMiddleware, requireRegistration, ensureUsable, notify) {
-    ensureUsable();
+export async function busPublish(event, options, deps) {
+    deps.ensureUsable();
+    if (!isEvent(event)) {
+        throw new InvalidEventError("publish() requires an Event (use publishEvent() for event input).");
+    }
     if (options.signal?.aborted) {
         throw new EventDispatchAbortedError("Event dispatch was aborted.", {
-            eventType: event?.type,
-            eventId: event?.id,
-        });
-    }
-    if (requireRegistration && !registry.has(event.type)) {
-        throw new EventError(`Event type "${event.type}" is not registered.`, {
             eventType: event.type,
             eventId: event.id,
         });
     }
+    if (deps.requireRegistration && !deps.registry.has(event.type)) {
+        throw new EventTypeNotFoundError(event.type);
+    }
     const allMiddleware = [
-        ...busMiddleware,
-        ...(options.middleware ?? []).map((m, index) => registerMiddlewareItem(m, index + busMiddleware.length)),
+        ...deps.busMiddleware,
+        ...(options.middleware ?? []).map((m, index) => registerMiddlewareItem(m, index, "publish-mw")),
     ];
     const middlewareContext = createEventMiddlewareContext(event, {
         signal: options.signal,
         metadata: options.metadata,
     });
     const terminal = async () => {
-        return emitter.emit(event, {
+        return deps.emitter.emit(event, {
             mode: options.mode,
             errorMode: options.errorMode,
             signal: options.signal,
             metadata: options.metadata,
         });
     };
-    let result;
-    let middlewareResult;
+    let emitResult;
+    let middlewareExecutions;
     if (allMiddleware.length > 0) {
         const pipelineResult = await executeEventMiddlewarePipeline(allMiddleware, middlewareContext, terminal);
-        result = pipelineResult.result;
-        middlewareResult = {
-            result: pipelineResult.result,
-            executions: pipelineResult.executions,
-        };
+        middlewareExecutions = pipelineResult.executions;
+        if (isEventEmitResult(pipelineResult.result)) {
+            emitResult = pipelineResult.result;
+        }
     }
     else {
-        result = await terminal();
+        emitResult = await terminal();
     }
-    notify({
+    deps.notify({
         type: "published",
         event,
         timestamp: new Date(),
     });
+    if (emitResult === undefined) {
+        /**
+         * A middleware short-circuited (did not call next()); no
+         * handler ran.
+         */
+        return {
+            event,
+            handled: false,
+            handlerCount: 0,
+            succeeded: 0,
+            failed: 0,
+            results: [],
+            errors: [],
+            shortCircuited: true,
+            middlewareExecutions,
+        };
+    }
+    if (deps.onError && emitResult.errors.length > 0) {
+        for (const error of emitResult.errors) {
+            try {
+                deps.onError(error, { source: "handler", event });
+            }
+            catch {
+                /**
+                 * A failing error hook must not break publishing.
+                 */
+            }
+        }
+    }
     return {
-        event,
-        handled: result.handled,
-        handlerCount: result.results.length,
-        results: result.results.map((execution) => execution.result),
-        errors: result.errors,
-        middlewareExecutions: middlewareResult?.executions,
+        event: emitResult.event,
+        handled: emitResult.handled,
+        handlerCount: emitResult.results.length,
+        succeeded: emitResult.succeeded,
+        failed: emitResult.failed,
+        results: emitResult.results.map((execution) => execution.result),
+        errors: emitResult.errors,
+        shortCircuited: false,
+        middlewareExecutions,
     };
 }
 /**
  * Creates and publishes an event from input data.
  */
-export async function busPublishEvent(input, options, emitter, registry, busMiddleware, requireRegistration, ensureUsable, notify) {
+export async function busPublishEvent(input, options, deps) {
     const event = createEvent(input);
-    return busPublish(event, options, emitter, registry, busMiddleware, requireRegistration, ensureUsable, notify);
+    return busPublish(event, options, deps);
 }
 //# sourceMappingURL=eventBus.publish.js.map

package/dist/eventBus/eventBus.registration.d.ts

@@ -6,30 +6,29 @@ 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 { RegisteredEventDefinition } from "../eventRegistry/eventRegistry.type.js";
+import type { EventBusMiddlewareItem } from "./eventBus.type.js";
 /**
  * Registers an event definition on the given registry.
  */
 export declare function busRegister<TType extends EventType, TPayload>(registry: {
-    register: Function;
-}, definition: EventDefinition<TType, TPayload>, ensureUsable: () => void): any;
+    register: (definition: EventDefinition<TType, TPayload>) => RegisteredEventDefinition<TType, TPayload>;
+}, definition: EventDefinition<TType, TPayload>, ensureUsable: () => void): RegisteredEventDefinition<TType, TPayload>;
+interface HandlerSource {
+    on: <TEvent extends Event = Event>(eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType">) => EventSubscription;
+}
 /**
  * Registers a handler on the emitter.
  */
-export declare function busOn<TEvent extends Event = Event>(emitter: {
-    on: (eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType">) => EventSubscription;
-}, eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType"> | undefined, ensureUsable: () => void): EventSubscription;
+export declare function busOn<TEvent extends Event = Event>(emitter: HandlerSource, eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType"> | undefined, ensureUsable: () => void): EventSubscription;
 /**
  * Registers a one-time handler.
  */
-export declare function busOnce<TEvent extends Event = Event>(emitter: {
-    on: (eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType">) => EventSubscription;
-}, eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType" | "once"> | undefined, ensureUsable: () => void): EventSubscription;
+export declare function busOnce<TEvent extends Event = Event>(emitter: HandlerSource, eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType" | "once"> | undefined, ensureUsable: () => void): EventSubscription;
 /**
  * Registers a wildcard handler.
  */
-export declare function busOnAny<TEvent extends Event = Event>(emitter: {
-    on: (eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType">) => EventSubscription;
-}, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType"> | undefined, ensureUsable: () => void): EventSubscription;
+export declare function busOnAny<TEvent extends Event = Event>(emitter: HandlerSource, handler: EventHandlerLike<TEvent>, options: Omit<EventHandlerOptions, "eventType"> | undefined, ensureUsable: () => void): EventSubscription;
 /**
  * Removes a handler.
  */
@@ -37,11 +36,23 @@ export declare function busOff(emitter: {
     off: (subscription: EventSubscription) => boolean;
 }, subscription: EventSubscription, ensureNotDisposed: () => void): boolean;
 /**
- * Adds middleware to the bus.
+ * Adds middleware to the bus. The middleware is validated
+ * eagerly (invalid middleware or a non-finite priority throw
+ * here, not on the next publish).
  */
 export declare function busUse(busMiddleware: RegisteredEventMiddleware[], middleware: EventMiddlewareLike, options?: EventMiddlewareOptions): () => void;
+/**
+ * Determines whether a value is an already registered middleware
+ * (created by createEventMiddleware or a builder helper).
+ */
+export declare function isRegisteredEventMiddleware(value: unknown): value is RegisteredEventMiddleware;
 /**
  * Normalizes a middleware item into a RegisteredEventMiddleware.
+ *
+ * `prefix` keeps generated ids stable per source ("bus-mw" for
+ * constructor middleware, "publish-mw" for per-publication
+ * middleware).
  */
-export declare function registerMiddlewareItem(item: EventMiddlewareLike, index: number): RegisteredEventMiddleware;
+export declare function registerMiddlewareItem(item: EventBusMiddlewareItem, index: number, prefix?: string): RegisteredEventMiddleware;
+export {};
 //# sourceMappingURL=eventBus.registration.d.ts.map