@zudojs/events 0.0.1 → 1.0.0

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 (depth > MAX_JSON_PAYLOAD_DEPTH) {
+        return false;
+    }
+    if (visited.has(value)) {
+        // A cycle can never be serialized to JSON.
+        return false;
     }
-    if (typeof value === "object") {
-        return Object.values(value).every((item) => isJsonEventPayload(item));
+    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,24 +116,36 @@ 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.

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;
 /**

package/dist/eventTypes/eventType.type.js

@@ -8,7 +8,9 @@
 /**
  * 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:
  *
@@ -28,10 +30,14 @@ export function isValidEventType(value) {
     if (normalized.length > 255) {
         return false;
     }
-    return /^[a-z0-9_]+(?:[.-][a-z0-9_*]+)*$/.test(normalized);
+    return /^[a-z0-9_]+(?:[.-][a-z0-9_]+)*$/.test(normalized);
 }
 /**
  * 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 function isValidEventTypePattern(value) {
     if (value === "*") {
@@ -56,26 +62,21 @@ export function isValidEventTypePattern(value) {
  * 4. Removes leading/trailing separators
  */
 export function normalizeEventType(type) {
+    if (typeof type !== "string") {
+        throw new TypeError(`Invalid event type: "${String(type)}".`);
+    }
     const lower = type.trim().toLowerCase();
     let result = "";
     let lastWasDot = false;
-    let leadingDots = true;
     for (let i = 0; i < lower.length; i++) {
         const ch = lower[i];
-        if (ch === "/" || ch === "\\" || ch === ":") {
-            if (!lastWasDot) {
-                result += ".";
-                lastWasDot = true;
-            }
-        }
-        else if (ch === ".") {
+        if (ch === "/" || ch === "\\" || ch === ":" || ch === ".") {
             if (!lastWasDot) {
                 result += ".";
                 lastWasDot = true;
             }
         }
         else {
-            leadingDots = false;
             result += ch;
             lastWasDot = false;
         }
@@ -139,6 +140,21 @@ export function getEventAction(type) {
 export function getEventTypeSegments(type) {
     return type.split(".");
 }
+/**
+ * Normalizes an event type pattern.
+ *
+ * "*" is returned unchanged, "User.*" becomes "user.*" and any
+ * other value is normalized as an event type.
+ */
+export function normalizeEventTypePattern(pattern) {
+    if (pattern === "*") {
+        return "*";
+    }
+    if (typeof pattern === "string" && pattern.trim().endsWith(".*")) {
+        return `${normalizeEventType(pattern.trim().slice(0, -2))}.*`;
+    }
+    return normalizeEventType(pattern);
+}
 /**
  * Checks whether an event type matches a pattern.
  *
@@ -146,8 +162,14 @@ export function getEventTypeSegments(type) {
  *
  * "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 function matchesEventType(type, pattern) {
     if (pattern === "*") {

package/dist/eventTypes/index.d.ts

@@ -4,6 +4,6 @@
  * Event type definitions and payload types.
  */
 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 PayloadOf, type PayloadMap, type EventPayloadFactory, type EventPayloadOptions, isPrimitiveEventPayload, isObjectEventPayload, isJsonEventPayload, createEventPayload, validateEventPayload, } from "./eventPayload.type.js";
-export { type EventTypeList, type EventTypePattern, type EventTypeOf, type EventUnion, isValidEventType, isValidEventTypePattern, normalizeEventType, createEventType, getEventNamespace, } from "./eventType.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";
 //# sourceMappingURL=index.d.ts.map

package/dist/eventTypes/index.js

@@ -4,6 +4,6 @@
  * Event type definitions and payload types.
  */
 export { isEvent, createEventId, createEvent, defineEvent, withEventMetadata, createDerivedEvent, getEventType, getEventPayload, describeEvent, } from "./eventDefinition.type.js";
-export { isPrimitiveEventPayload, isObjectEventPayload, isJsonEventPayload, createEventPayload, validateEventPayload, } from "./eventPayload.type.js";
-export { isValidEventType, isValidEventTypePattern, normalizeEventType, createEventType, getEventNamespace, } from "./eventType.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";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/events",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Event-driven architecture with event bus, emitter, middleware, and registry for decoupled communication.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,18 +13,22 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
+  "sideEffects": false,
   "dependencies": {
-    "@zudojs/errors": "0.0.1",
-    "@zudojs/constants": "0.0.1"
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/constants": "1.0.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
     "vitest": "^4.1.11",
-    "typescript": "^7.0.2"
+    "typescript": "7.0.2"
   },
   "license": "MIT",
   "publishConfig": {
@@ -37,13 +41,17 @@
     "pubsub"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/events"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rm -rf dist"