@zudojs/events 1.3.0 → 1.3.2

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
 
 ```

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.3.0",
+  "version": "1.3.2",
   "description": "Event-driven architecture with event bus, emitter, middleware, and registry for decoupled communication.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,9 +20,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zudojs/constants": "1.1.2",
-    "@zudojs/errors": "1.3.0",
-    "@zudojs/middleware": "1.1.0"
+    "@zudojs/constants": "1.1.3",
+    "@zudojs/errors": "1.3.1",
+    "@zudojs/middleware": "1.1.1"
   },
   "engines": {
     "node": ">=24.0.0"