@zudojs/events 1.2.0 → 1.3.1

package/README.md

@@ -50,13 +50,39 @@ await bus.publishEvent({
 - 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.*"`, `"*"`)
+- Wildcard subscriptions (`"user.*"`, `"*"`) — multi-level, see [Wildcard patterns](#wildcard-patterns)
 - 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: handlers receive a frozen *copy* (`createFrozenEventSnapshot`), so the publisher's own objects are never frozen, and Map, Set and Date values (including `event.timestamp`) become read-only variants that throw on mutation. Class instances are passed by reference.
 - A handler unsubscribed by an earlier handler in the same dispatch, or left over after the bus is disposed mid-dispatch, does not run
 - Listener-leak warnings (`maxListeners`, reported through `onWarning` or, by default, `process.emitWarning` with type `ZudojsEventsWarning`) and an `onError` hook for fire-and-forget publishes
 - Typed error classes from `@zudojs/errors` (`EventHandlerError`, `EventMiddlewareError`, `EventDispatchAbortedError`, …)
 
+## Wildcard patterns
+
+A handler's event type can be an exact type, a namespace wildcard, or the
+catch-all `"*"`:
+
+| Pattern | Matches | Does not match |
+|---------|---------|----------------|
+| `"task.created"` | `task.created` | `task.created.v2`, `task` |
+| `"task.*"` | `task`, `task.created`, `task.sub.created` (any depth) | `tasks.created`, `order.created` |
+| `"*"` | every event | — |
+
+A namespace wildcard is **multi-level**: `"task.*"` matches every event
+under `task` at any depth, plus the bare `task` event, like a prefix match
+on whole segments. There is no single-level form — `"task.*.created"`,
+`"task.cre*"` and other positions are rejected as invalid patterns. To
+handle only direct children, filter in the handler:
+
+```typescript
+import { getEventTypeSegments } from "@zudojs/events";
+
+bus.on("task.*", (event) => {
+  if (getEventTypeSegments(event.type).length !== 2) return; // task.x only
+  // ...
+});
+```
+
 ## Lifecycle
 
 ```
@@ -71,6 +97,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 +119,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/dist/eventTypes/eventType.type.d.ts

@@ -55,6 +55,10 @@ export declare function isValidEventType(value: unknown): value is EventType;
  * Supported forms are an exact event type, a namespace wildcard
  * ("user.*") and the catch-all "*". Wildcards in any other
  * position ("user.*.created", "user.cre*") are rejected.
+ *
+ * A namespace wildcard is multi-level: "user.*" matches every event
+ * under "user" at any depth, and "user" itself (see matchesEventType).
+ * There is no single-level form.
  */
 export declare function isValidEventTypePattern(value: unknown): value is EventTypePattern;
 /**
@@ -112,8 +116,16 @@ export declare function normalizeEventTypePattern(pattern: string): EventTypePat
  * "user.created" matches "user.*"
  * "user"         matches "user.*" (a namespace pattern also
  *                matches the bare namespace event)
+ * "user.profile.updated" matches "user.*" (multi-level: the
+ *                wildcard covers every depth below the namespace)
  * "user.created" matches "*"
  * "order.created" does not match "user.*"
+ * "username.set" does not match "user.*" (segments, not prefixes)
+ *
+ * A "*" segment stands for the rest of the type, not for one segment,
+ * and there is no single-level wildcard. To handle only direct children,
+ * subscribe to "user.*" and check
+ * `getEventTypeSegments(event.type).length === 2` in the handler.
  *
  * Both arguments are expected to be normalized (see
  * normalizeEventType / normalizeEventTypePattern); no
@@ -133,10 +145,13 @@ export declare function isChildEventType(type: EventType, parent: EventType): bo
 /**
  * Creates a wildcard pattern for an event namespace.
  *
+ * The pattern is multi-level: it matches every event type under the
+ * namespace at any depth, and the bare namespace itself.
+ *
  * Example:
  *
  * createEventTypePattern("user")
- * → "user.*"
+ * → "user.*" (matches "user", "user.created", "user.profile.updated")
  */
 export declare function createEventTypePattern(namespace: string): EventTypePattern;
 /**

package/dist/eventTypes/eventType.type.js

@@ -38,6 +38,10 @@ export function isValidEventType(value) {
  * Supported forms are an exact event type, a namespace wildcard
  * ("user.*") and the catch-all "*". Wildcards in any other
  * position ("user.*.created", "user.cre*") are rejected.
+ *
+ * A namespace wildcard is multi-level: "user.*" matches every event
+ * under "user" at any depth, and "user" itself (see matchesEventType).
+ * There is no single-level form.
  */
 export function isValidEventTypePattern(value) {
     if (value === "*") {
@@ -164,8 +168,16 @@ export function normalizeEventTypePattern(pattern) {
  * "user.created" matches "user.*"
  * "user"         matches "user.*" (a namespace pattern also
  *                matches the bare namespace event)
+ * "user.profile.updated" matches "user.*" (multi-level: the
+ *                wildcard covers every depth below the namespace)
  * "user.created" matches "*"
  * "order.created" does not match "user.*"
+ * "username.set" does not match "user.*" (segments, not prefixes)
+ *
+ * A "*" segment stands for the rest of the type, not for one segment,
+ * and there is no single-level wildcard. To handle only direct children,
+ * subscribe to "user.*" and check
+ * `getEventTypeSegments(event.type).length === 2` in the handler.
  *
  * Both arguments are expected to be normalized (see
  * normalizeEventType / normalizeEventTypePattern); no
@@ -201,10 +213,13 @@ export function isChildEventType(type, parent) {
 /**
  * Creates a wildcard pattern for an event namespace.
  *
+ * The pattern is multi-level: it matches every event type under the
+ * namespace at any depth, and the bare namespace itself.
+ *
  * Example:
  *
  * createEventTypePattern("user")
- * → "user.*"
+ * → "user.*" (matches "user", "user.created", "user.profile.updated")
  */
 export function createEventTypePattern(namespace) {
     const normalized = normalizeEventType(namespace);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/events",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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"
   },