@zudojs/events 0.1.0 → 1.0.1

package/dist/eventRegistry/eventRegistry.store.js

@@ -3,13 +3,18 @@
  *
  * The registry owns event definitions and registered handlers.
  * It does not perform event dispatching. Dispatching belongs to
- * EventEmitter and higher-level routing belongs to EventBus.
+ * EventEmitter (which stores its handlers in a registry) and
+ * higher-level routing belongs to EventBus.
  */
-import { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, } from "../eventErrors/eventError.base.js";
-import { registryRegister, registryRegisterHandler, registryUnregister, registryUnregisterHandler, } from "./eventRegistry.registration.js";
+import { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, } from "../eventErrors/eventError.base.js";
+import { DEFAULT_MAX_HANDLERS_PER_PATTERN } from "./eventRegistry.type.js";
+import { normalizeRegistryEventType, registryRegister, registryRegisterHandler, registryUnregister, registryUnregisterHandler, } from "./eventRegistry.registration.js";
 import { getHandlersForEvent, getHandlersForType, getAllDefinitions, getAllHandlers, } from "./eventRegistry.queries.js";
 import { registryClear, registryDispose, registryNotify, } from "./eventRegistry.lifecycle.js";
-export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, };
+export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, };
+function defaultWarning(warning) {
+    console.warn(`[@zudojs/events] ${warning.message}`);
+}
 /**
  * Main event registry.
  */
@@ -17,23 +22,34 @@ export class EventRegistry {
     definitions = new Map();
     handlers = new Map();
     listeners = new Set();
+    warnedPatterns = new Set();
     options;
     disposed = false;
     constructor(options = {}) {
+        const maxHandlersPerPattern = options.maxHandlersPerPattern ?? DEFAULT_MAX_HANDLERS_PER_PATTERN;
+        if (typeof maxHandlersPerPattern !== "number" ||
+            !Number.isFinite(maxHandlersPerPattern) ||
+            maxHandlersPerPattern < 0) {
+            throw new RangeError("maxHandlersPerPattern must be a non-negative finite number.");
+        }
         this.options = {
             allowDuplicateDefinitions: options.allowDuplicateDefinitions ?? false,
-            allowDuplicateHandlerIds: options.allowDuplicateHandlerIds ?? false,
+            onDuplicateHandlerId: options.onDuplicateHandlerId ??
+                (options.allowDuplicateHandlerIds ? "replace" : "throw"),
+            maxHandlersPerPattern,
+            onWarning: options.onWarning ?? defaultWarning,
+            onError: options.onError,
         };
     }
     register(definition) {
         return registryRegister(definition, this.definitions, this.options, () => this.ensureActive(), (c) => this.notify(c));
     }
     registerHandler(eventType, handler, options = {}) {
-        return registryRegisterHandler(eventType, handler, options, this.handlers, this.options, () => this.ensureActive(), (c) => this.notify(c));
+        return registryRegisterHandler(eventType, handler, options, this.handlers, this.options, () => this.ensureActive(), (c) => this.notify(c), this.warnedPatterns);
     }
     get(eventType) {
         this.ensureActive();
-        return this.definitions.get(eventType);
+        return this.definitions.get(normalizeRegistryEventType(eventType));
     }
     require(eventType) {
         const definition = this.get(eventType);
@@ -44,14 +60,14 @@ export class EventRegistry {
     }
     has(eventType) {
         this.ensureActive();
-        return this.definitions.has(eventType);
+        return this.definitions.has(normalizeRegistryEventType(eventType));
     }
     unregister(eventType) {
         return registryUnregister(eventType, this.definitions, () => this.ensureActive(), (c) => this.notify(c));
     }
     getHandler(handlerId) {
         this.ensureActive();
-        return this.handlers.get(handlerId);
+        return this.handlers.get(handlerId)?.registration;
     }
     requireHandler(handlerId) {
         const handler = this.getHandler(handlerId);
@@ -64,8 +80,16 @@ export class EventRegistry {
         this.ensureActive();
         return this.handlers.has(handlerId);
     }
+    /**
+     * Returns the subscription created for a handler id, if the
+     * handler is still registered.
+     */
+    getHandlerSubscription(handlerId) {
+        this.ensureActive();
+        return this.handlers.get(handlerId)?.subscription;
+    }
     unregisterHandler(handlerId) {
-        return registryUnregisterHandler(handlerId, this.handlers, () => this.ensureActive(), (c) => this.notify(c));
+        return registryUnregisterHandler(handlerId, this.handlers, () => this.ensureActive());
     }
     getDefinitions() {
         this.ensureActive();
@@ -98,6 +122,7 @@ export class EventRegistry {
     }
     clear() {
         registryClear(this.definitions, this.handlers, () => this.ensureActive(), (c) => this.notify(c));
+        this.warnedPatterns.clear();
     }
     dispose() {
         registryDispose(this.disposed, this.definitions, this.handlers, this.listeners, () => this.ensureActive(), (c) => this.notify(c));
@@ -107,11 +132,11 @@ export class EventRegistry {
         return this.disposed;
     }
     notify(change) {
-        registryNotify(change, this.listeners);
+        registryNotify(change, this.listeners, this.options.onError);
     }
     ensureActive() {
         if (this.disposed) {
-            throw new Error("EventRegistry has already been disposed.");
+            throw new EventRegistryDisposedError();
         }
     }
 }

package/dist/eventRegistry/eventRegistry.type.d.ts

@@ -1,11 +1,73 @@
 /**
  * Event registry type definitions for Zudojs.
  */
-import type { EventDefinition, EventType } from "../eventTypes/eventDefinition.type.js";
-import type { RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
+import type { Event, EventDefinition, EventType } from "../eventTypes/eventDefinition.type.js";
+import type { EventTypePattern } from "../eventTypes/eventType.type.js";
+import type { EventHandlerLike, EventHandlerOptions, RegisteredEventHandler } from "../eventHandler/eventHandler.core.js";
+import type { EventSubscription } from "../eventSubscription/eventSubscription.core.js";
+/**
+ * Policy applied when a handler is registered with an id that
+ * is already in use.
+ *
+ * - "throw"   → DuplicateEventHandlerError (default)
+ * - "replace" → the previous handler is unregistered (its
+ *               subscription is cancelled) and the new one stored
+ */
+export type DuplicateHandlerIdPolicy = "throw" | "replace";
+/**
+ * Default number of handlers allowed per event pattern before a
+ * leak warning is emitted.
+ */
+export declare const DEFAULT_MAX_HANDLERS_PER_PATTERN = 100;
+/**
+ * Warning emitted when a registry limit is exceeded.
+ */
+export interface EventRegistryWarning {
+    readonly type: "handler.limit";
+    readonly pattern: EventTypePattern;
+    readonly count: number;
+    readonly limit: number;
+    readonly message: string;
+}
+/**
+ * Context passed to onError hooks.
+ */
+export interface EventRegistryErrorContext {
+    readonly source: "observer";
+    readonly change?: EventRegistryChange;
+}
 export interface EventRegistryOptions {
+    /**
+     * Allow re-registering an event type. The previous definition
+     * is replaced.
+     */
     readonly allowDuplicateDefinitions?: boolean;
+    /**
+     * @deprecated Use `onDuplicateHandlerId: "replace"`. When true,
+     * registering a handler id that already exists replaces the
+     * previous handler (it never allowed two handlers to coexist).
+     */
     readonly allowDuplicateHandlerIds?: boolean;
+    /**
+     * What to do when a handler id is already registered.
+     * Defaults to "throw".
+     */
+    readonly onDuplicateHandlerId?: DuplicateHandlerIdPolicy;
+    /**
+     * Maximum handlers per event pattern before a leak warning is
+     * emitted through `onWarning` (or console.warn). Use 0 to
+     * disable. Defaults to 100.
+     */
+    readonly maxHandlersPerPattern?: number;
+    /**
+     * Receives limit warnings. Defaults to console.warn.
+     */
+    readonly onWarning?: (warning: EventRegistryWarning) => void;
+    /**
+     * Receives errors thrown by registry observers, which are
+     * otherwise swallowed so they cannot break registry mutations.
+     */
+    readonly onError?: (error: unknown, context: EventRegistryErrorContext) => void;
 }
 export declare enum EventRegistryChangeType {
     EVENT_REGISTERED = "event.registered",
@@ -25,4 +87,27 @@ export interface RegisteredEventDefinition<TType extends EventType = EventType,
     readonly definition: EventDefinition<TType, TPayload>;
     readonly registeredAt: Date;
 }
+/**
+ * Internal handler entry: the registration plus the subscription
+ * handed to the caller, so the registry can cancel it.
+ */
+export interface EventHandlerEntry {
+    readonly registration: RegisteredEventHandler;
+    readonly subscription: EventSubscription;
+}
+/**
+ * Minimal handler store contract used by EventEmitter.
+ *
+ * EventRegistry implements it; the emitter stores its handlers in
+ * a registry so that a bus has a single source of truth for
+ * handlers.
+ */
+export interface EventHandlerStore {
+    registerHandler<TEvent extends Event = Event>(eventType: EventTypePattern, handler: EventHandlerLike<TEvent>, options?: Omit<EventHandlerOptions, "eventType">): EventSubscription;
+    unregisterHandler(handlerId: string): boolean;
+    hasHandler(handlerId: string): boolean;
+    getHandlers(): readonly RegisteredEventHandler[];
+    getHandlersForEvent(event: Event): readonly RegisteredEventHandler[];
+    readonly handlerCount: number;
+}
 //# sourceMappingURL=eventRegistry.type.d.ts.map

package/dist/eventRegistry/eventRegistry.type.js

@@ -1,6 +1,11 @@
 /**
  * Event registry type definitions for Zudojs.
  */
+/**
+ * Default number of handlers allowed per event pattern before a
+ * leak warning is emitted.
+ */
+export const DEFAULT_MAX_HANDLERS_PER_PATTERN = 100;
 export var EventRegistryChangeType;
 (function (EventRegistryChangeType) {
     EventRegistryChangeType["EVENT_REGISTERED"] = "event.registered";

package/dist/eventSubscription/eventSubscription.core.d.ts

@@ -135,6 +135,11 @@ export declare class EventSubscriptionGroup implements EventSubscription {
     remove(subscription: EventSubscription): boolean;
     /**
      * Unsubscribes every subscription in the group.
+     *
+     * Every subscription is attempted even if one throws; the
+     * failures are then re-thrown together as an AggregateError and
+     * the failed subscriptions stay in the group so the call can be
+     * retried.
      */
     unsubscribe(): void;
     /**

package/dist/eventSubscription/eventSubscription.core.js

@@ -146,17 +146,31 @@ export class EventSubscriptionGroup {
     }
     /**
      * Unsubscribes every subscription in the group.
+     *
+     * Every subscription is attempted even if one throws; the
+     * failures are then re-thrown together as an AggregateError and
+     * the failed subscriptions stay in the group so the call can be
+     * retried.
      */
     unsubscribe() {
         if (!this.active) {
             return;
         }
-        this.currentState = EventSubscriptionState.CANCELLED;
         const subscriptions = [...this.subscriptions];
-        this.subscriptions.clear();
+        const failures = [];
         for (const subscription of subscriptions) {
-            subscription.unsubscribe();
+            try {
+                subscription.unsubscribe();
+                this.subscriptions.delete(subscription);
+            }
+            catch (error) {
+                failures.push(error);
+            }
         }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `${failures.length} of ${subscriptions.length} subscriptions failed to unsubscribe.`);
+        }
+        this.currentState = EventSubscriptionState.CANCELLED;
     }
     /**
      * Returns all subscriptions in the group.

package/dist/eventTypes/eventDefinition.type.d.ts

@@ -95,9 +95,10 @@ export interface Event<TPayload = EventPayload> {
  */
 export interface EventInput<TPayload = EventPayload> {
     /**
-     * Optional event identifier.
+     * Optional event identifier. Plain strings are accepted and
+     * branded on the created event.
      */
-    readonly id?: EventId;
+    readonly id?: EventId | string;
     /**
      * Event type.
      */
@@ -115,9 +116,9 @@ export interface EventInput<TPayload = EventPayload> {
      */
     readonly source?: EventSource;
     /**
-     * Optional correlation identifier.
+     * Optional correlation identifier. Plain strings are accepted.
      */
-    readonly correlationId?: EventCorrelationId;
+    readonly correlationId?: EventCorrelationId | string;
     /**
      * Optional causation identifier.
      */
@@ -148,6 +149,12 @@ export declare function isEvent(value: unknown): value is Event;
 export declare function createEventId(): EventId;
 /**
  * Creates an immutable event.
+ *
+ * The event type is normalized (trimmed, lower-cased, separators
+ * collapsed) and validated; invalid types, ids and timestamps
+ * throw InvalidEventError. The top-level event object is frozen;
+ * the payload is left as supplied (use deepFreeze / the emitter's
+ * freezeEvents option for deep immutability).
  */
 export declare function createEvent<TPayload = EventPayload>(input: EventInput<TPayload>): Event<TPayload>;
 /**

package/dist/eventTypes/eventDefinition.type.js

@@ -6,6 +6,8 @@
  *
  * This module intentionally contains no dispatching logic.
  */
+import { InvalidEventError } from "../eventErrors/eventError.base.js";
+import { normalizeEventType } from "./eventType.type.js";
 /**
  * Determines whether an unknown value satisfies the Event
  * contract.
@@ -32,17 +34,39 @@ export function createEventId() {
  * Normalizes an event timestamp.
  */
 function normalizeTimestamp(timestamp) {
-    if (timestamp instanceof Date) {
-        return new Date(timestamp.getTime());
+    if (timestamp === undefined) {
+        return new Date();
     }
-    if (typeof timestamp === "number") {
-        const date = new Date(timestamp);
-        if (Number.isNaN(date.getTime())) {
-            throw new TypeError("Invalid event timestamp.");
-        }
-        return date;
+    const date = timestamp instanceof Date
+        ? new Date(timestamp.getTime())
+        : typeof timestamp === "number"
+            ? new Date(timestamp)
+            : undefined;
+    if (date === undefined || Number.isNaN(date.getTime())) {
+        throw new InvalidEventError("Invalid event timestamp.");
+    }
+    return date;
+}
+/**
+ * Normalizes and validates an event type, converting validation
+ * failures into InvalidEventError.
+ */
+function normalizeInputType(type, eventId) {
+    if (typeof type !== "string" || type.trim().length === 0) {
+        throw new InvalidEventError("Event type must be a non-empty string.", {
+            eventId,
+        });
+    }
+    try {
+        return normalizeEventType(type);
+    }
+    catch (error) {
+        throw new InvalidEventError(`Invalid event type "${type}".`, {
+            eventType: type,
+            eventId,
+            cause: error,
+        });
     }
-    return new Date();
 }
 /**
  * Freezes event metadata.
@@ -57,14 +81,24 @@ function normalizeMetadata(metadata) {
 }
 /**
  * Creates an immutable event.
+ *
+ * The event type is normalized (trimmed, lower-cased, separators
+ * collapsed) and validated; invalid types, ids and timestamps
+ * throw InvalidEventError. The top-level event object is frozen;
+ * the payload is left as supplied (use deepFreeze / the emitter's
+ * freezeEvents option for deep immutability).
  */
 export function createEvent(input) {
-    if (typeof input.type !== "string" || input.type.trim().length === 0) {
-        throw new TypeError("Event type must be a non-empty string.");
+    if (typeof input !== "object" || input === null) {
+        throw new InvalidEventError("Event input must be an object.");
+    }
+    if (input.id !== undefined && typeof input.id !== "string") {
+        throw new InvalidEventError("Event id must be a string.");
     }
+    const type = normalizeInputType(input.type, input.id);
     const event = {
         id: input.id ?? createEventId(),
-        type: input.type,
+        type,
         payload: input.payload,
         timestamp: normalizeTimestamp(input.timestamp),
         source: input.source,
@@ -78,15 +112,13 @@ export function createEvent(input) {
  * Creates a typed event definition.
  */
 export function defineEvent(type) {
-    if (type.trim().length === 0) {
-        throw new TypeError("Event type must be a non-empty string.");
-    }
+    const normalized = normalizeInputType(type);
     return Object.freeze({
-        type,
+        type: normalized,
         create(payload, options = {}) {
             return createEvent({
                 ...options,
-                type,
+                type: normalized,
                 payload,
             });
         },

package/dist/eventTypes/eventPayload.type.d.ts

@@ -93,6 +93,11 @@ export declare function createJsonEventPayload<const TPayload extends JsonEventP
 export declare function cloneEventPayload<TPayload extends EventPayload>(payload: TPayload): TPayload;
 /**
  * Deeply freezes an event payload.
+ *
+ * Cyclic and shared references are handled (each object is
+ * visited once), and an already frozen parent is still traversed
+ * so that unfrozen children are frozen too. ArrayBuffer views are
+ * left untouched because they cannot be frozen.
  */
 export declare function deepFreeze<T>(value: T): T;
 /**

package/dist/eventTypes/eventPayload.type.js

@@ -24,6 +24,17 @@ export function isObjectEventPayload(value) {
  * event payload.
  */
 export function isJsonEventPayload(value) {
+    return isJsonValue(value, new WeakSet(), 0);
+}
+/**
+ * Maximum nesting depth accepted by isJsonEventPayload.
+ */
+const MAX_JSON_PAYLOAD_DEPTH = 256;
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isJsonValue(value, visited, depth) {
     if (value === null ||
         typeof value === "string" ||
         typeof value === "boolean") {
@@ -32,13 +43,31 @@ export function isJsonEventPayload(value) {
     if (typeof value === "number") {
         return Number.isFinite(value);
     }
-    if (Array.isArray(value)) {
-        return value.every((item) => isJsonEventPayload(item));
+    if (typeof value !== "object") {
+        return false;
     }
-    if (typeof value === "object") {
-        return Object.values(value).every((item) => isJsonEventPayload(item));
+    if (depth > MAX_JSON_PAYLOAD_DEPTH) {
+        return false;
+    }
+    if (visited.has(value)) {
+        // A cycle can never be serialized to JSON.
+        return false;
+    }
+    visited.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.every((item) => isJsonValue(item, visited, depth + 1));
+        }
+        if (!isPlainObject(value)) {
+            // Date, Map, Set, class instances, typed arrays, ... are not
+            // JSON values even though JSON.stringify may accept them.
+            return false;
+        }
+        return Object.values(value).every((item) => isJsonValue(item, visited, depth + 1));
+    }
+    finally {
+        visited.delete(value);
     }
-    return false;
 }
 /**
  * Creates a payload object from an input object.
@@ -87,36 +116,47 @@ export function cloneEventPayload(payload) {
 }
 /**
  * Deeply freezes an event payload.
+ *
+ * Cyclic and shared references are handled (each object is
+ * visited once), and an already frozen parent is still traversed
+ * so that unfrozen children are frozen too. ArrayBuffer views are
+ * left untouched because they cannot be frozen.
  */
 export function deepFreeze(value) {
-    if (value === null || typeof value !== "object") {
-        return value;
+    freezeRecursively(value, new WeakSet());
+    return value;
+}
+function freezeRecursively(value, visited) {
+    if ((typeof value !== "object" && typeof value !== "function") ||
+        value === null) {
+        return;
+    }
+    if (visited.has(value)) {
+        return;
     }
-    if (Object.isFrozen(value)) {
-        return value;
+    visited.add(value);
+    if (ArrayBuffer.isView(value)) {
+        return;
     }
     const object = value;
     for (const key of Reflect.ownKeys(object)) {
-        const child = object[key];
-        if (child !== null &&
-            typeof child === "object" &&
-            !Object.isFrozen(child)) {
-            deepFreeze(child);
+        const descriptor = Object.getOwnPropertyDescriptor(object, key);
+        if (descriptor && "value" in descriptor) {
+            freezeRecursively(descriptor.value, visited);
         }
     }
-    return Object.freeze(value);
+    Object.freeze(value);
 }
 /**
  * Removes undefined properties from an object payload.
  */
 export function stripUndefinedValues(payload) {
-    const result = {};
-    for (const [key, value] of Object.entries(payload)) {
-        if (value !== undefined) {
-            result[key] = value;
-        }
-    }
-    return result;
+    /**
+     * Object.fromEntries defines every entry as an own data
+     * property, so a key such as "__proto__" (e.g. from JSON.parse)
+     * is copied as data instead of replacing the result's prototype.
+     */
+    return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
 }
 /**
  * Merges two object payloads.

package/dist/eventTypes/eventType.type.d.ts

@@ -6,6 +6,8 @@
  * and strongly typed event-type helpers.
  */
 import type { Event, EventType } from "../eventTypes/eventDefinition.type.js";
+import type { EventPayloadMap } from "./eventPayload.type.js";
+export type { EventPayloadMap } from "./eventPayload.type.js";
 /**
  * A collection of event types.
  */
@@ -20,10 +22,6 @@ export type EventTypeList = readonly EventType[];
  * "*"
  */
 export type EventTypePattern = EventType | `${string}.*` | "*";
-/**
- * Type-safe mapping between event types and payloads.
- */
-export type EventPayloadMap = Record<EventType, unknown>;
 /**
  * Extracts the event type keys from a payload map.
  */
@@ -39,7 +37,9 @@ export type EventUnion<TMap extends EventPayloadMap> = {
 /**
  * Validates an event type string.
  *
- * Zudojs event types use dot-separated lowercase names.
+ * Zudojs event types use dot-separated lowercase names. Wildcards
+ * are not part of an event type; they are only valid in patterns
+ * (see isValidEventTypePattern).
  *
  * Examples:
  *
@@ -51,6 +51,10 @@ export type EventUnion<TMap extends EventPayloadMap> = {
 export declare function isValidEventType(value: unknown): value is EventType;
 /**
  * Validates an event type pattern.
+ *
+ * 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.
  */
 export declare function isValidEventTypePattern(value: unknown): value is EventTypePattern;
 /**
@@ -92,6 +96,13 @@ export declare function getEventAction(type: EventType): string;
  * Returns all segments in an event type.
  */
 export declare function getEventTypeSegments(type: EventType): readonly string[];
+/**
+ * Normalizes an event type pattern.
+ *
+ * "*" is returned unchanged, "User.*" becomes "user.*" and any
+ * other value is normalized as an event type.
+ */
+export declare function normalizeEventTypePattern(pattern: string): EventTypePattern;
 /**
  * Checks whether an event type matches a pattern.
  *
@@ -99,8 +110,14 @@ export declare function getEventTypeSegments(type: EventType): readonly string[]
  *
  * "user.created" matches "user.created"
  * "user.created" matches "user.*"
+ * "user"         matches "user.*" (a namespace pattern also
+ *                matches the bare namespace event)
  * "user.created" matches "*"
  * "order.created" does not match "user.*"
+ *
+ * Both arguments are expected to be normalized (see
+ * normalizeEventType / normalizeEventTypePattern); no
+ * normalization happens here.
  */
 export declare function matchesEventType(type: EventType, pattern: EventTypePattern): boolean;
 /**