architex-js 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architex-js",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -11,7 +11,8 @@
     "./pipeline": "./src/pipeline/index.js",
     "./result": "./src/result/index.js",
     "./guards": "./src/guards/index.js",
-    "./repository": "./src/repository/index.js"
+    "./repository": "./src/repository/index.js",
+    "./events": "./src/events/index.js"
   },
   "description": "Architectural Toolbox for JavaScript - Providing high-level building blocks for robust systems.",
   "author": {

package/src/events/DomainEvent.js

@@ -0,0 +1,24 @@
+/**
+ * Base class for all Domain Events.
+ * Extend this class to define strongly-typed events in your domain.
+ *
+ * @example
+ * class UserCreated extends DomainEvent {
+ *   constructor(userId) {
+ *     super();
+ *     this.userId = userId;
+ *   }
+ * }
+ */
+class DomainEvent {
+    constructor() {
+        /** @type {string} Unique name of this event type */
+        this.eventName = this.constructor.name;
+        /** @type {Date} When the event was created */
+        this.occurredAt = new Date();
+        /** @type {string} Unique event id */
+        this.eventId = `${this.eventName}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
+}
+
+export { DomainEvent };

package/src/events/EventDispatcher.js

@@ -0,0 +1,100 @@
+import { DomainEvent } from "./DomainEvent.js";
+
+/**
+ * Dispatches domain events to registered handlers.
+ * Supports async handlers, multiple handlers per event, and wildcard listeners.
+ *
+ * @example
+ * const dispatcher = new EventDispatcher();
+ * dispatcher.on(UserCreated, async (event) => sendWelcomeEmail(event.userId));
+ * await dispatcher.dispatch(new UserCreated(42));
+ */
+class EventDispatcher {
+    constructor() {
+        /** @type {Map<string, Array<Function>>} */
+        this._handlers = new Map();
+        /** @type {Array<Function>} */
+        this._wildcards = [];
+    }
+
+    /**
+     * Registers a handler for a specific DomainEvent class.
+     * @param {typeof DomainEvent} EventClass - The event class (not an instance).
+     * @param {(event: DomainEvent) => void | Promise<void>} handler
+     * @returns {() => void} An unsubscribe function.
+     */
+    on(EventClass, handler) {
+        if (typeof EventClass !== 'function') {
+            throw new TypeError('EventDispatcher.on() expects an event class as first argument');
+        }
+        if (typeof handler !== 'function') {
+            throw new TypeError('EventDispatcher.on() expects a function as second argument');
+        }
+
+        const eventName = EventClass.name;
+
+        if (!this._handlers.has(eventName)) {
+            this._handlers.set(eventName, []);
+        }
+        this._handlers.get(eventName).push(handler);
+
+        return () => this.off(EventClass, handler);
+    }
+
+    /**
+     * Unregisters a handler for a specific event class.
+     * @param {typeof DomainEvent} EventClass
+     * @param {Function} handler
+     */
+    off(EventClass, handler) {
+        const eventName = EventClass.name;
+        const handlers = this._handlers.get(eventName);
+        if (handlers) {
+            const idx = handlers.indexOf(handler);
+            if (idx > -1) handlers.splice(idx, 1);
+        }
+    }
+
+    /**
+     * Registers a wildcard handler that receives ALL dispatched events.
+     * @param {(event: DomainEvent) => void | Promise<void>} handler
+     * @returns {() => void} An unsubscribe function.
+     */
+    onAny(handler) {
+        if (typeof handler !== 'function') {
+            throw new TypeError('EventDispatcher.onAny() expects a function');
+        }
+        this._wildcards.push(handler);
+        return () => {
+            const idx = this._wildcards.indexOf(handler);
+            if (idx > -1) this._wildcards.splice(idx, 1);
+        };
+    }
+
+    /**
+     * Dispatches a domain event to all registered handlers (in parallel).
+     * @param {DomainEvent} event - An instance of a DomainEvent subclass.
+     * @returns {Promise<void>}
+     */
+    async dispatch(event) {
+        if (!(event instanceof DomainEvent)) {
+            throw new TypeError('EventDispatcher.dispatch() expects a DomainEvent instance');
+        }
+
+        const eventHandlers = this._handlers.get(event.eventName) ?? [];
+        const allHandlers = [...eventHandlers, ...this._wildcards];
+
+        await Promise.all(allHandlers.map(handler => handler(event)));
+    }
+
+    /**
+     * Returns the number of handlers registered for a given event class.
+     * @param {typeof DomainEvent} EventClass
+     * @returns {number}
+     */
+    listenerCount(EventClass) {
+        return (this._handlers.get(EventClass.name) ?? []).length;
+    }
+}
+
+export { EventDispatcher };

package/src/events/index.js

@@ -0,0 +1,2 @@
+export * from "./DomainEvent.js";
+export * from "./EventDispatcher.js";

package/src/index.js

@@ -5,4 +5,5 @@ export * from "./exceptions/index.js";
 export * from "./pipeline/index.js";
 export * from "./result/index.js";
 export * from "./guards/index.js";
-export * from "./repository/index.js";
+export * from "./repository/index.js";
+export * from "./events/index.js";

package/test/events.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi } from 'vitest';
+import { DomainEvent } from '../src/events/DomainEvent.js';
+import { EventDispatcher } from '../src/events/EventDispatcher.js';
+
+class UserCreated extends DomainEvent {
+    constructor(userId) {
+        super();
+        this.userId = userId;
+    }
+}
+
+class OrderPlaced extends DomainEvent {
+    constructor(orderId) {
+        super();
+        this.orderId = orderId;
+    }
+}
+
+describe('DomainEvent', () => {
+    it('should set eventName to the class name', () => {
+        const event = new UserCreated(1);
+        expect(event.eventName).toBe('UserCreated');
+    });
+
+    it('should set occurredAt to current date', () => {
+        const before = new Date();
+        const event = new UserCreated(1);
+        const after = new Date();
+        expect(event.occurredAt >= before).toBe(true);
+        expect(event.occurredAt <= after).toBe(true);
+    });
+
+    it('should generate a unique eventId', () => {
+        const A = new UserCreated(1);
+        const B = new UserCreated(1);
+        expect(A.eventId).not.toBe(B.eventId);
+    });
+});
+
+describe('EventDispatcher', () => {
+    it('should call a registered handler when event is dispatched', async () => {
+        const dispatcher = new EventDispatcher();
+        const handler = vi.fn();
+        dispatcher.on(UserCreated, handler);
+
+        const event = new UserCreated(42);
+        await dispatcher.dispatch(event);
+
+        expect(handler).toHaveBeenCalledWith(event);
+        expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    it('should support multiple handlers for the same event', async () => {
+        const dispatcher = new EventDispatcher();
+        const h1 = vi.fn();
+        const h2 = vi.fn();
+        dispatcher.on(UserCreated, h1);
+        dispatcher.on(UserCreated, h2);
+
+        await dispatcher.dispatch(new UserCreated(1));
+
+        expect(h1).toHaveBeenCalled();
+        expect(h2).toHaveBeenCalled();
+    });
+
+    it('should not call handlers for a different event type', async () => {
+        const dispatcher = new EventDispatcher();
+        const handler = vi.fn();
+        dispatcher.on(OrderPlaced, handler);
+
+        await dispatcher.dispatch(new UserCreated(1));
+
+        expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('should call wildcard handlers for all events', async () => {
+        const dispatcher = new EventDispatcher();
+        const wildcard = vi.fn();
+        dispatcher.onAny(wildcard);
+
+        await dispatcher.dispatch(new UserCreated(1));
+        await dispatcher.dispatch(new OrderPlaced(2));
+
+        expect(wildcard).toHaveBeenCalledTimes(2);
+    });
+
+    it('should unsubscribe correctly via returned function', async () => {
+        const dispatcher = new EventDispatcher();
+        const handler = vi.fn();
+        const unsubscribe = dispatcher.on(UserCreated, handler);
+
+        unsubscribe();
+        await dispatcher.dispatch(new UserCreated(1));
+
+        expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('should report correct listenerCount', () => {
+        const dispatcher = new EventDispatcher();
+        dispatcher.on(UserCreated, () => { });
+        dispatcher.on(UserCreated, () => { });
+        expect(dispatcher.listenerCount(UserCreated)).toBe(2);
+    });
+
+    it('should throw if dispatch receives a non-DomainEvent', async () => {
+        const dispatcher = new EventDispatcher();
+        await expect(dispatcher.dispatch({ foo: 'bar' })).rejects.toThrow(TypeError);
+    });
+});