@zudojs/events 1.0.1 → 1.1.0

package/README.md

@@ -2,6 +2,12 @@
 
 Event-driven architecture with event bus, emitter, middleware, and registry for decoupled communication.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-events](https://zudojs.oyinlola.site/docs/packages-events) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-events.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -46,8 +52,9 @@ await bus.publishEvent({
 - 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
+- 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`, …)
 
 ## Lifecycle

package/dist/eventBus/eventBus.type.d.ts

@@ -52,7 +52,7 @@ export interface EventBusOptions {
     readonly requireRegistration?: boolean;
     readonly middleware?: readonly EventBusMiddlewareItem[];
     /**
-     * Receives leak warnings. Defaults to console.warn.
+     * Receives leak warnings. Defaults to `process.emitWarning` (type `ZudojsEventsWarning`).
      */
     readonly onWarning?: (warning: EventRegistryWarning) => void;
     /**

package/dist/eventEmitter/eventEmitter.core.js

@@ -6,7 +6,7 @@
  * bus and its registry share one set of handlers.
  */
 import { createEvent, isEvent } from "../eventTypes/eventDefinition.type.js";
-import { deepFreeze } from "../eventTypes/eventPayload.type.js";
+import { createFrozenEventSnapshot } from "../eventTypes/eventSnapshot.freeze.js";
 import { createEventHandlerContext } from "../eventHandler/eventHandler.core.js";
 import { EventSubscriptionGroup } from "../eventSubscription/eventSubscription.core.js";
 import { EventRegistry } from "../eventRegistry/eventRegistry.store.js";
@@ -68,8 +68,12 @@ export class EventEmitter {
         }
         const mode = options.mode ?? this.options.mode;
         const errorMode = options.errorMode ?? this.options.errorMode;
-        const dispatched = this.options.freezeEvents ? deepFreeze(event) : event;
-        const handlers = this.store.getHandlersForEvent(dispatched);
+        const handlers = this.store.getHandlersForEvent(event);
+        // Handlers receive a frozen COPY: freezing the event in place froze
+        // the publisher's own objects, even when nobody was subscribed.
+        const dispatched = this.options.freezeEvents && handlers.length > 0
+            ? createFrozenEventSnapshot(event)
+            : event;
         const context = createEventHandlerContext(dispatched, {
             signal: options.signal,
             metadata: options.metadata,
@@ -87,7 +91,17 @@ export class EventEmitter {
             };
         }
         const hooks = {
-            isRegistered: (handlerId) => this.store.hasHandler(handlerId),
+            // A bus disposed mid-dispatch has no registered handlers left.
+            isRegistered: (handlerId) => {
+                if (this.disposed)
+                    return false;
+                try {
+                    return this.store.hasHandler(handlerId);
+                }
+                catch {
+                    return false;
+                }
+            },
             removeOnce: (handlerId) => {
                 this.store.unregisterHandler(handlerId);
             },

package/dist/eventEmitter/eventEmitter.parallel.js

@@ -22,12 +22,12 @@ export async function emitParallel(handlers, event, context, errorMode, results,
      * an overlapping dispatch cannot invoke them a second time.
      */
     const runnable = handlers.filter((handler) => {
-        if (!handler.once) {
-            return true;
-        }
         if (!hooks.isRegistered(handler.id)) {
             return false;
         }
+        if (!handler.once) {
+            return true;
+        }
         hooks.removeOnce(handler.id);
         return true;
     });

package/dist/eventEmitter/eventEmitter.sequential.js

@@ -13,11 +13,13 @@ export async function emitSequential(handlers, event, context, errorMode, result
         if (context.signal.aborted) {
             throw createAbortError(event, results, errors);
         }
+        // Checked for every handler, not only once-handlers: a handler
+        // unsubscribed (or a bus disposed) by an earlier handler in this
+        // same dispatch must not run.
+        if (!hooks.isRegistered(handler.id)) {
+            continue;
+        }
         if (handler.once) {
-            if (!hooks.isRegistered(handler.id)) {
-                // Already consumed by an overlapping dispatch.
-                continue;
-            }
             hooks.removeOnce(handler.id);
         }
         const started = performance.now();

package/dist/eventEmitter/eventEmitter.type.d.ts

@@ -44,7 +44,7 @@ export interface EventEmitterOptions {
     readonly maxListeners?: number;
     /**
      * Receives leak warnings. Only applies to the private store.
-     * Defaults to console.warn.
+     * Defaults to `process.emitWarning` (type `ZudojsEventsWarning`).
      */
     readonly onWarning?: (warning: EventRegistryWarning) => void;
 }

package/dist/eventMiddleware/eventMiddleware.pipeline.d.ts

@@ -1,5 +1,6 @@
 /**
- * Event middleware pipeline execution for Zudojs.
+ * Event middleware pipeline execution for Zudojs, built on `compose` from
+ * `@zudojs/middleware`.
  */
 import type { Event } from "../eventTypes/eventDefinition.type.js";
 import type { EventMiddlewareContext, EventMiddlewareNext, RegisteredEventMiddleware, EventMiddlewarePipelineResult } from "./eventMiddleware.type.js";

package/dist/eventMiddleware/eventMiddleware.pipeline.js

@@ -1,8 +1,10 @@
 /**
- * Event middleware pipeline execution for Zudojs.
+ * Event middleware pipeline execution for Zudojs, built on `compose` from
+ * `@zudojs/middleware`.
  */
+import { compose } from "@zudojs/middleware";
 import { EventDispatchAbortedError, EventMiddlewareError, toEventError, } from "../eventErrors/eventError.base.js";
-import { sortEventMiddleware, executeEventMiddleware, } from "./eventMiddleware.helper.js";
+import { sortEventMiddleware, executeEventMiddleware } from "./eventMiddleware.helper.js";
 /**
  * Executes a middleware pipeline.
  *
@@ -21,47 +23,37 @@ import { sortEventMiddleware, executeEventMiddleware, } from "./eventMiddleware.
  */
 export async function executeEventMiddlewarePipeline(middleware, context, terminal) {
     const started = performance.now();
-    const activeMiddleware = sortEventMiddleware(middleware.filter((item) => item.enabled));
     const executions = [];
-    let index = -1;
-    const dispatch = async (currentIndex) => {
-        if (context.signal.aborted) {
-            throw createAbortError(context);
-        }
-        if (currentIndex === activeMiddleware.length) {
-            return terminal();
-        }
-        if (currentIndex <= index) {
-            throw new EventMiddlewareError("Event middleware called next() more than once.", {
-                eventType: context.event?.type,
-                eventId: context.event?.id,
-            });
-        }
-        index = currentIndex;
-        const current = activeMiddleware[currentIndex];
-        if (!current) {
-            return terminal();
-        }
+    const stages = sortEventMiddleware(middleware.filter((item) => item.enabled))
+        .map((current) => toStage(current, executions));
+    const run = compose(stages, async (ctx) => {
+        throwIfAborted(ctx);
+        return terminal();
+    }, { maxDepth: Number.POSITIVE_INFINITY });
+    const result = await run(context);
+    return { result, executions, duration: performance.now() - started };
+}
+/**
+ * Adapts one registered middleware to the shared composer: checks the
+ * abort signal, rejects a second next() with an EventMiddlewareError,
+ * records the execution, and wraps only the middleware's own errors.
+ */
+function toStage(current, executions) {
+    return async (context, advance) => {
+        throwIfAborted(context);
         const middlewareStarted = performance.now();
+        const eventType = context.event?.type;
+        const eventId = context.event?.id;
         let nextCalled = false;
-        /**
-         * Errors that surfaced through next() belong to downstream
-         * code, not to this middleware; they must pass through
-         * unwrapped.
-         */
         let downstreamThrew = false;
         let downstreamError;
         const next = async () => {
             if (nextCalled) {
-                throw new EventMiddlewareError(`Middleware "${current.id}" called next() more than once.`, {
-                    middlewareId: current.id,
-                    eventType: context.event?.type,
-                    eventId: context.event?.id,
-                });
+                throw new EventMiddlewareError(`Middleware "${current.id}" called next() more than once.`, { middlewareId: current.id, eventType, eventId });
             }
             nextCalled = true;
             try {
-                return await dispatch(currentIndex + 1);
+                return await advance();
             }
             catch (error) {
                 downstreamThrew = true;
@@ -79,39 +71,29 @@ export async function executeEventMiddlewarePipeline(middleware, context, termin
             return result;
         }
         catch (error) {
-            if (downstreamThrew && error === downstreamError) {
-                throw error;
-            }
-            if (error instanceof EventMiddlewareError ||
+            if ((downstreamThrew && error === downstreamError) ||
+                error instanceof EventMiddlewareError ||
                 error instanceof EventDispatchAbortedError) {
                 throw error;
             }
             throw new EventMiddlewareError(`Event middleware "${current.id}" failed.`, {
                 middlewareId: current.id,
-                eventType: context.event?.type,
-                eventId: context.event?.id,
-                cause: toEventError(error, {
-                    eventType: context.event?.type,
-                    eventId: context.event?.id,
-                }),
+                eventType,
+                eventId,
+                cause: toEventError(error, { eventType, eventId }),
             });
         }
     };
-    const result = await dispatch(0);
-    return {
-        result,
-        executions,
-        duration: performance.now() - started,
-    };
 }
 /**
- * Creates the abort error thrown when the pipeline observes an
- * aborted signal.
+ * Throws the abort error when the pipeline observes an aborted signal.
  */
-function createAbortError(context) {
-    return new EventDispatchAbortedError("Event dispatch was aborted.", {
-        eventType: context.event?.type,
-        eventId: context.event?.id,
-    });
+function throwIfAborted(context) {
+    if (context.signal.aborted) {
+        throw new EventDispatchAbortedError("Event dispatch was aborted.", {
+            eventType: context.event?.type,
+            eventId: context.event?.id,
+        });
+    }
 }
 //# sourceMappingURL=eventMiddleware.pipeline.js.map

package/dist/eventRegistry/eventRegistry.store.js

@@ -12,8 +12,18 @@ import { normalizeRegistryEventType, registryRegister, registryRegisterHandler,
 import { getHandlersForEvent, getHandlersForType, getAllDefinitions, getAllHandlers, } from "./eventRegistry.queries.js";
 import { registryClear, registryDispose, registryNotify, } from "./eventRegistry.lifecycle.js";
 export { DuplicateEventDefinitionError, EventDefinitionNotFoundError, DuplicateEventHandlerError, EventHandlerNotFoundError, EventRegistryDisposedError, };
+/**
+ * Default leak-warning sink: Node's process warning channel (the same one
+ * `EventEmitter` uses for `MaxListenersExceededWarning`), which honours
+ * `--no-warnings` and `process.on("warning")`, instead of writing to the
+ * console directly. A no-op where `process.emitWarning` is unavailable.
+ */
 function defaultWarning(warning) {
-    console.warn(`[@zudojs/events] ${warning.message}`);
+    const emit = globalThis.process?.emitWarning;
+    emit?.(`[@zudojs/events] ${warning.message}`, {
+        type: "ZudojsEventsWarning",
+        code: "ZUDOJS_EVENTS_HANDLER_LIMIT",
+    });
 }
 /**
  * Main event registry.

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

@@ -55,12 +55,12 @@ export interface EventRegistryOptions {
     readonly onDuplicateHandlerId?: DuplicateHandlerIdPolicy;
     /**
      * Maximum handlers per event pattern before a leak warning is
-     * emitted through `onWarning` (or console.warn). Use 0 to
+     * emitted through `onWarning` (or `process.emitWarning`). Use 0 to
      * disable. Defaults to 100.
      */
     readonly maxHandlersPerPattern?: number;
     /**
-     * Receives limit warnings. Defaults to console.warn.
+     * Receives limit warnings. Defaults to `process.emitWarning` (type `ZudojsEventsWarning`).
      */
     readonly onWarning?: (warning: EventRegistryWarning) => void;
     /**

package/dist/eventTypes/eventSnapshot.freeze.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Immutable event snapshots.
+ *
+ * The emitter used to deep-freeze the event IN PLACE, which froze the
+ * publisher's own objects (a later `cart.total = 20` threw) and left
+ * Map, Set and Date internals mutable, because `Object.freeze` does not
+ * reach them. A snapshot is a frozen COPY: the caller's graph is never
+ * touched, and Map, Set and Date are copied into read-only variants
+ * whose mutators throw.
+ */
+/** A Date whose setters throw. */
+export declare class FrozenEventDate extends Date {
+}
+/** A Map whose mutators throw once construction has finished. */
+export declare class FrozenEventMap<K, V> extends Map<K, V> {
+    set(): this;
+    delete(): boolean;
+    clear(): void;
+}
+/** A Set whose mutators throw once construction has finished. */
+export declare class FrozenEventSet<T> extends Set<T> {
+    add(): this;
+    delete(): boolean;
+    clear(): void;
+}
+/**
+ * Returns a deeply frozen copy of `value`, leaving `value` untouched.
+ *
+ * Plain objects, arrays and errors are copied (own properties, including
+ * a `__proto__` data key, are defined rather than assigned) and frozen.
+ * Map, Set and Date become {@link FrozenEventMap}, {@link FrozenEventSet}
+ * and {@link FrozenEventDate}, which still pass `instanceof Map` / `Set`
+ * / `Date` but throw on mutation. Class instances and other exotic
+ * objects are passed by reference. Cycles are preserved.
+ */
+export declare function createFrozenEventSnapshot<T>(value: T): T;
+//# sourceMappingURL=eventSnapshot.freeze.d.ts.map

package/dist/eventTypes/eventSnapshot.freeze.js

@@ -0,0 +1,117 @@
+/**
+ * Immutable event snapshots.
+ *
+ * The emitter used to deep-freeze the event IN PLACE, which froze the
+ * publisher's own objects (a later `cart.total = 20` threw) and left
+ * Map, Set and Date internals mutable, because `Object.freeze` does not
+ * reach them. A snapshot is a frozen COPY: the caller's graph is never
+ * touched, and Map, Set and Date are copied into read-only variants
+ * whose mutators throw.
+ */
+/** Throws the TypeError every read-only mutator raises. */
+function readOnly(kind) {
+    throw new TypeError(`Cannot modify a frozen event ${kind}.`);
+}
+/** A Date whose setters throw. */
+export class FrozenEventDate extends Date {
+}
+for (const key of Object.getOwnPropertyNames(Date.prototype)) {
+    if (key.startsWith("set")) {
+        Object.defineProperty(FrozenEventDate.prototype, key, {
+            value: () => readOnly("Date"),
+            configurable: true,
+            writable: true,
+        });
+    }
+}
+/** A Map whose mutators throw once construction has finished. */
+export class FrozenEventMap extends Map {
+    set() {
+        return readOnly("Map");
+    }
+    delete() {
+        return readOnly("Map");
+    }
+    clear() {
+        readOnly("Map");
+    }
+}
+/** A Set whose mutators throw once construction has finished. */
+export class FrozenEventSet extends Set {
+    add() {
+        return readOnly("Set");
+    }
+    delete() {
+        return readOnly("Set");
+    }
+    clear() {
+        readOnly("Set");
+    }
+}
+/** Whether a value is a plain object (literal or null-prototype). */
+function isPlainRecord(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function snapshot(value, seen) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (seen.has(value))
+        return seen.get(value);
+    if (value instanceof Date) {
+        const copy = Object.freeze(new FrozenEventDate(value.getTime()));
+        seen.set(value, copy);
+        return copy;
+    }
+    if (value instanceof Map) {
+        const copy = new FrozenEventMap();
+        seen.set(value, copy);
+        for (const [key, item] of value) {
+            Map.prototype.set.call(copy, key, snapshot(item, seen));
+        }
+        return Object.freeze(copy);
+    }
+    if (value instanceof Set) {
+        const copy = new FrozenEventSet();
+        seen.set(value, copy);
+        for (const item of value) {
+            Set.prototype.add.call(copy, snapshot(item, seen));
+        }
+        return Object.freeze(copy);
+    }
+    const isArray = Array.isArray(value);
+    const isError = value instanceof Error;
+    // Instances of other classes (and exotic built-ins such as typed
+    // arrays, RegExp, URL) cannot be copied faithfully — private fields and
+    // internal slots do not survive — so they are passed by reference.
+    if (!isArray && !isError && !isPlainRecord(value))
+        return value;
+    const copy = isArray
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    seen.set(value, copy);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor)
+            continue;
+        if ("value" in descriptor) {
+            descriptor.value = snapshot(descriptor.value, seen);
+        }
+        Object.defineProperty(copy, key, descriptor);
+    }
+    return Object.freeze(copy);
+}
+/**
+ * Returns a deeply frozen copy of `value`, leaving `value` untouched.
+ *
+ * Plain objects, arrays and errors are copied (own properties, including
+ * a `__proto__` data key, are defined rather than assigned) and frozen.
+ * Map, Set and Date become {@link FrozenEventMap}, {@link FrozenEventSet}
+ * and {@link FrozenEventDate}, which still pass `instanceof Map` / `Set`
+ * / `Date` but throw on mutation. Class instances and other exotic
+ * objects are passed by reference. Cycles are preserved.
+ */
+export function createFrozenEventSnapshot(value) {
+    return snapshot(value, new Map());
+}
+//# sourceMappingURL=eventSnapshot.freeze.js.map

package/dist/eventTypes/index.d.ts

@@ -6,4 +6,5 @@
 export { type EventId, type EventType, type EventTimestamp, type EventSource, type EventCorrelationId, type EventCausationId, type EventPayload, type Event, type EventInput, type EventDefinition, isEvent, createEventId, createEvent, defineEvent, withEventMetadata, createDerivedEvent, getEventType, getEventPayload, describeEvent, } from "./eventDefinition.type.js";
 export { type ObjectEventPayload, type PrimitiveEventPayload, type JsonEventPayload, type EventPayloadMap, type PayloadOf, type PayloadMap, type EventPayloadFactory, type EventPayloadOptions, isPrimitiveEventPayload, isObjectEventPayload, isJsonEventPayload, createEventPayload, createObjectEventPayload, createJsonEventPayload, cloneEventPayload, deepFreeze, stripUndefinedValues, mergeEventPayloads, staticPayload, definePayloadFactory, validateEventPayload, describeEventPayload, } from "./eventPayload.type.js";
 export { type EventTypeList, type EventTypePattern, type EventTypeOf, type EventUnion, isValidEventType, isValidEventTypePattern, normalizeEventType, normalizeEventTypePattern, tryNormalizeEventType, assertEventType, createEventType, createEventTypePattern, getEventNamespace, getEventAction, getEventTypeSegments, matchesEventType, isSameEventNamespace, isChildEventType, eventMatchesType, filterEventsByType, defineEventTypes, defineEventType, } from "./eventType.type.js";
+export { createFrozenEventSnapshot, FrozenEventDate, FrozenEventMap, FrozenEventSet, } from "./eventSnapshot.freeze.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/eventTypes/index.js

@@ -6,4 +6,5 @@
 export { isEvent, createEventId, createEvent, defineEvent, withEventMetadata, createDerivedEvent, getEventType, getEventPayload, describeEvent, } from "./eventDefinition.type.js";
 export { isPrimitiveEventPayload, isObjectEventPayload, isJsonEventPayload, createEventPayload, createObjectEventPayload, createJsonEventPayload, cloneEventPayload, deepFreeze, stripUndefinedValues, mergeEventPayloads, staticPayload, definePayloadFactory, validateEventPayload, describeEventPayload, } from "./eventPayload.type.js";
 export { isValidEventType, isValidEventTypePattern, normalizeEventType, normalizeEventTypePattern, tryNormalizeEventType, assertEventType, createEventType, createEventTypePattern, getEventNamespace, getEventAction, getEventTypeSegments, matchesEventType, isSameEventNamespace, isChildEventType, eventMatchesType, filterEventsByType, defineEventTypes, defineEventType, } from "./eventType.type.js";
+export { createFrozenEventSnapshot, FrozenEventDate, FrozenEventMap, FrozenEventSet, } from "./eventSnapshot.freeze.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/events",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Event-driven architecture with event bus, emitter, middleware, and registry for decoupled communication.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,8 +20,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/middleware": "1.0.2"
   },
   "engines": {
     "node": ">=24.0.0"