@zudojs/events 1.2.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

@@ -100,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);

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";
@@ -93,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.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";
@@ -87,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, EventListenerLimitExceededError, 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,17 +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);
-}
 //# 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, EventListenerLimitExceededError, 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,32 +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 },
-        });
-    }
-}
 //# sourceMappingURL=eventError.base.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/events",
-  "version": "1.2.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.1",
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/middleware": "1.0.3"
+    "@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"
   },