@veloxts/events 0.8.0 → 0.8.2

package/dist/domain/emitter.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DomainEventEmitter
+ *
+ * Typed in-process event emitter for domain events. Used internally by the
+ * procedure builder's `.emits()` method and by `ctx.events.emit()` for
+ * imperative usage.
+ *
+ * Listeners receive `event.data` (the typed payload), not the event instance.
+ * Sequential listeners run first (in registration order), then concurrent
+ * listeners run via Promise.allSettled. Listener errors are caught and logged
+ * — they must never propagate to the caller, since the mutation already succeeded.
+ */
+import type { DomainEvent, DomainEventClass } from './event.js';
+export interface ListenerOptions {
+    /**
+     * When true, this listener executes in registration order, awaiting
+     * completion before the next sequential listener starts.
+     *
+     * Sequential listeners all complete before concurrent listeners begin.
+     *
+     * @default false
+     */
+    sequential?: boolean;
+    /**
+     * Placeholder — stored but not yet implemented.
+     *
+     * TODO (v1.1): Implement automatic retry logic for retryable listeners
+     * using an exponential back-off strategy with configurable attempts.
+     *
+     * @default false
+     */
+    retryable?: boolean;
+}
+/**
+ * Typed in-process domain event emitter.
+ *
+ * @example
+ * ```typescript
+ * const emitter = new DomainEventEmitter();
+ *
+ * emitter.on(OrderCreatedEvent, async (data) => {
+ *   await sendConfirmationEmail(data.orderId);
+ * });
+ *
+ * // In a mutation:
+ * await emitter.emit(new OrderCreatedEvent({ orderId: 'order-123', total: 99.99 }));
+ * ```
+ */
+export declare class DomainEventEmitter {
+    /**
+     * Registry keyed by `name`. Each value is an array of listener entries
+     * typed as `ListenerEntry<Record<string, unknown>>` so they can be stored
+     * together in one map — we narrow the type at registration/retrieval time.
+     */
+    private readonly _listeners;
+    /**
+     * Register a typed listener for a domain event class.
+     *
+     * The handler receives `event.data` — the typed payload — not the event
+     * instance itself.
+     *
+     * @param eventClass  - The domain event class (used as the key via `.name`).
+     * @param handler     - Called with the event's `data` payload on each emit.
+     * @param options     - `{ sequential?, retryable? }`
+     */
+    on<TData extends Record<string, unknown>>(eventClass: DomainEventClass<TData>, handler: (data: TData) => void | Promise<void>, options?: ListenerOptions): void;
+    /**
+     * Remove a previously registered listener.
+     *
+     * @param eventClass - The domain event class the listener was registered for.
+     * @param handler    - The exact handler reference passed to `on()`.
+     */
+    off<TData extends Record<string, unknown>>(eventClass: DomainEventClass<TData>, handler: (data: TData) => void | Promise<void>): void;
+    /**
+     * Fire a domain event to all registered listeners.
+     *
+     * Execution order:
+     * 1. Sequential listeners run first, in registration order (each awaited).
+     * 2. Concurrent listeners run together via Promise.allSettled.
+     *
+     * Errors from any listener are caught and logged — they never propagate
+     * to the caller. The mutation that triggered the event already succeeded.
+     *
+     * @param event - The domain event instance to dispatch.
+     */
+    emit<TData extends Record<string, unknown>>(event: DomainEvent<TData>): Promise<void>;
+}

package/dist/domain/emitter.js

@@ -0,0 +1,133 @@
+/**
+ * DomainEventEmitter
+ *
+ * Typed in-process event emitter for domain events. Used internally by the
+ * procedure builder's `.emits()` method and by `ctx.events.emit()` for
+ * imperative usage.
+ *
+ * Listeners receive `event.data` (the typed payload), not the event instance.
+ * Sequential listeners run first (in registration order), then concurrent
+ * listeners run via Promise.allSettled. Listener errors are caught and logged
+ * — they must never propagate to the caller, since the mutation already succeeded.
+ */
+import { createLogger } from '@veloxts/core';
+const log = createLogger('events');
+// =============================================================================
+// DomainEventEmitter
+// =============================================================================
+/**
+ * Typed in-process domain event emitter.
+ *
+ * @example
+ * ```typescript
+ * const emitter = new DomainEventEmitter();
+ *
+ * emitter.on(OrderCreatedEvent, async (data) => {
+ *   await sendConfirmationEmail(data.orderId);
+ * });
+ *
+ * // In a mutation:
+ * await emitter.emit(new OrderCreatedEvent({ orderId: 'order-123', total: 99.99 }));
+ * ```
+ */
+export class DomainEventEmitter {
+    /**
+     * Registry keyed by `name`. Each value is an array of listener entries
+     * typed as `ListenerEntry<Record<string, unknown>>` so they can be stored
+     * together in one map — we narrow the type at registration/retrieval time.
+     */
+    _listeners = new Map();
+    // ---------------------------------------------------------------------------
+    // on()
+    // ---------------------------------------------------------------------------
+    /**
+     * Register a typed listener for a domain event class.
+     *
+     * The handler receives `event.data` — the typed payload — not the event
+     * instance itself.
+     *
+     * @param eventClass  - The domain event class (used as the key via `.name`).
+     * @param handler     - Called with the event's `data` payload on each emit.
+     * @param options     - `{ sequential?, retryable? }`
+     */
+    on(eventClass, handler, options = {}) {
+        const { sequential = false, retryable = false } = options;
+        const key = eventClass.name;
+        if (!this._listeners.has(key)) {
+            this._listeners.set(key, []);
+        }
+        // Cast: we store all handlers as (data: Record<string, unknown>) => … but
+        // they are only invoked with the correctly-typed payload for their key.
+        const entry = {
+            handler: handler,
+            sequential,
+            retryable,
+        };
+        this._listeners.get(key)?.push(entry);
+    }
+    // ---------------------------------------------------------------------------
+    // off()
+    // ---------------------------------------------------------------------------
+    /**
+     * Remove a previously registered listener.
+     *
+     * @param eventClass - The domain event class the listener was registered for.
+     * @param handler    - The exact handler reference passed to `on()`.
+     */
+    off(eventClass, handler) {
+        const key = eventClass.name;
+        const entries = this._listeners.get(key);
+        if (!entries)
+            return;
+        const filtered = entries.filter((entry) => entry.handler !== handler);
+        if (filtered.length === 0) {
+            this._listeners.delete(key);
+        }
+        else {
+            this._listeners.set(key, filtered);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // emit()
+    // ---------------------------------------------------------------------------
+    /**
+     * Fire a domain event to all registered listeners.
+     *
+     * Execution order:
+     * 1. Sequential listeners run first, in registration order (each awaited).
+     * 2. Concurrent listeners run together via Promise.allSettled.
+     *
+     * Errors from any listener are caught and logged — they never propagate
+     * to the caller. The mutation that triggered the event already succeeded.
+     *
+     * @param event - The domain event instance to dispatch.
+     */
+    async emit(event) {
+        const key = event.constructor.name;
+        const entries = this._listeners.get(key);
+        if (!entries || entries.length === 0)
+            return;
+        const sequential = entries.filter((e) => e.sequential);
+        const concurrent = entries.filter((e) => !e.sequential);
+        // --- Sequential listeners (in registration order) ---
+        for (const entry of sequential) {
+            try {
+                await entry.handler(event.data);
+            }
+            catch (err) {
+                // Listener errors must never propagate — the mutation already succeeded.
+                // Log the error and continue to the next listener.
+                log.error(`Sequential listener for "${key}" threw an error:`, err);
+            }
+        }
+        // --- Concurrent listeners (all at once) ---
+        if (concurrent.length > 0) {
+            const results = await Promise.allSettled(concurrent.map((entry) => entry.handler(event.data)));
+            for (const result of results) {
+                if (result.status === 'rejected') {
+                    log.error(`Concurrent listener for "${key}" threw an error:`, result.reason);
+                }
+            }
+        }
+    }
+}

package/dist/domain/event.d.ts

@@ -0,0 +1,65 @@
+/**
+ * DomainEvent Base Class
+ *
+ * Abstract base class for internal server-side domain events used in
+ * business logic (e.g., OrderCreated, UserRegistered). These are distinct
+ * from broadcast events (WebSocket/SSE) which are client-facing.
+ */
+/**
+ * Abstract base class for all domain events.
+ *
+ * Domain events represent meaningful occurrences within the business domain
+ * (e.g., "OrderCreated", "OrderFulfilled"). They carry typed payloads and
+ * support optional correlation IDs for distributed tracing.
+ *
+ * @example
+ * ```typescript
+ * interface OrderCreatedData {
+ *   orderId: string;
+ *   customerId: string;
+ *   total: number;
+ * }
+ *
+ * class OrderCreatedEvent extends DomainEvent<OrderCreatedData> {}
+ *
+ * const event = new OrderCreatedEvent(
+ *   { orderId: 'order-123', customerId: 'cust-456', total: 99.99 },
+ *   { correlationId: 'req-abc' }
+ * );
+ *
+ * console.log(OrderCreatedEvent.name); // 'OrderCreatedEvent'
+ * ```
+ */
+export declare abstract class DomainEvent<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /** The typed payload carried by this event. */
+    readonly data: TData;
+    /** The date/time at which this event was instantiated. */
+    readonly timestamp: Date;
+    /** Optional correlation ID for distributed tracing across services. */
+    readonly correlationId?: string;
+    constructor(data: TData, options?: {
+        correlationId?: string;
+    });
+}
+/**
+ * Type representing the constructor signature of a concrete DomainEvent subclass.
+ *
+ * Use this when you need to hold a reference to an event class itself
+ * (e.g., to register listeners or dispatch by class reference).
+ *
+ * @example
+ * ```typescript
+ * function on<TData extends Record<string, unknown>>(
+ *   EventClass: DomainEventClass<TData>,
+ *   handler: (event: DomainEvent<TData>) => void,
+ * ): void {
+ *   // register handler keyed by EventClass.name
+ * }
+ * ```
+ */
+export type DomainEventClass<TData extends Record<string, unknown> = Record<string, unknown>> = {
+    new (data: TData, options?: {
+        correlationId?: string;
+    }): DomainEvent<TData>;
+    readonly name: string;
+};

package/dist/domain/event.js

@@ -0,0 +1,48 @@
+/**
+ * DomainEvent Base Class
+ *
+ * Abstract base class for internal server-side domain events used in
+ * business logic (e.g., OrderCreated, UserRegistered). These are distinct
+ * from broadcast events (WebSocket/SSE) which are client-facing.
+ */
+// =============================================================================
+// DomainEvent
+// =============================================================================
+/**
+ * Abstract base class for all domain events.
+ *
+ * Domain events represent meaningful occurrences within the business domain
+ * (e.g., "OrderCreated", "OrderFulfilled"). They carry typed payloads and
+ * support optional correlation IDs for distributed tracing.
+ *
+ * @example
+ * ```typescript
+ * interface OrderCreatedData {
+ *   orderId: string;
+ *   customerId: string;
+ *   total: number;
+ * }
+ *
+ * class OrderCreatedEvent extends DomainEvent<OrderCreatedData> {}
+ *
+ * const event = new OrderCreatedEvent(
+ *   { orderId: 'order-123', customerId: 'cust-456', total: 99.99 },
+ *   { correlationId: 'req-abc' }
+ * );
+ *
+ * console.log(OrderCreatedEvent.name); // 'OrderCreatedEvent'
+ * ```
+ */
+export class DomainEvent {
+    /** The typed payload carried by this event. */
+    data;
+    /** The date/time at which this event was instantiated. */
+    timestamp;
+    /** Optional correlation ID for distributed tracing across services. */
+    correlationId;
+    constructor(data, options) {
+        this.data = data;
+        this.timestamp = new Date();
+        this.correlationId = options?.correlationId;
+    }
+}

package/dist/domain/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Domain Events — barrel export
+ *
+ * Re-exports the DomainEvent base class, its class type, and the
+ * DomainEventEmitter with its listener options.
+ */
+export { DomainEventEmitter, type ListenerOptions as DomainListenerOptions } from './emitter.js';
+export { DomainEvent, type DomainEventClass } from './event.js';

package/dist/domain/index.js

@@ -0,0 +1,8 @@
+/**
+ * Domain Events — barrel export
+ *
+ * Re-exports the DomainEvent base class, its class type, and the
+ * DomainEventEmitter with its listener options.
+ */
+export { DomainEventEmitter } from './emitter.js';
+export { DomainEvent } from './event.js';

package/dist/index.d.ts

@@ -37,6 +37,7 @@
  * @packageDocumentation
  */
 export { type ChannelAuthSigner, createChannelAuthSigner } from './auth.js';
+export { DomainEvent, type DomainEventClass, DomainEventEmitter, type DomainListenerOptions, } from './domain/index.js';
 export { createSseDriver, DRIVER_NAME as SSE_DRIVER } from './drivers/sse.js';
 export { createWsDriver, DRIVER_NAME as WS_DRIVER } from './drivers/ws.js';
 export { createEventsManager, createManagerFromDriver, type EventsManager, events, } from './manager.js';

package/dist/index.js

@@ -38,6 +38,8 @@
  */
 // Auth
 export { createChannelAuthSigner } from './auth.js';
+// Domain Events
+export { DomainEvent, DomainEventEmitter, } from './domain/index.js';
 // Drivers
 export { createSseDriver, DRIVER_NAME as SSE_DRIVER } from './drivers/sse.js';
 export { createWsDriver, DRIVER_NAME as WS_DRIVER } from './drivers/ws.js';

package/dist/manager.js

@@ -5,6 +5,7 @@
  * Wraps the underlying driver with a clean, Laravel-inspired interface.
  */
 import { createLogger } from '@veloxts/core';
+import { DomainEventEmitter } from './domain/emitter.js';
 const log = createLogger('events');
 /**
  * Create an events manager with the specified driver.
@@ -55,6 +56,7 @@ export async function createEventsManager(options = {}) {
  * @returns Events manager instance
  */
 export function createManagerFromDriver(driver) {
+    const domainEmitter = new DomainEventEmitter();
     const manager = {
         driver,
         async broadcast(channel, event, data, except) {
@@ -104,6 +106,18 @@ export function createManagerFromDriver(driver) {
         async channels() {
             return driver.getChannels();
         },
+        // -------------------------------------------------------------------------
+        // Domain Event Methods
+        // -------------------------------------------------------------------------
+        async emit(event) {
+            await domainEmitter.emit(event);
+        },
+        on(eventClass, handler, options) {
+            domainEmitter.on(eventClass, handler, options);
+        },
+        off(eventClass, handler) {
+            domainEmitter.off(eventClass, handler);
+        },
         async close() {
             await driver.close();
         },

package/dist/types.d.ts

@@ -5,6 +5,8 @@
  * Uses discriminated unions for type-safe driver configuration.
  */
 import type { FastifyRequest } from 'fastify';
+import type { ListenerOptions as DomainListenerOptions } from './domain/emitter.js';
+import type { DomainEvent, DomainEventClass } from './domain/event.js';
 /**
  * Channel type determines access control.
  * - public: Anyone can subscribe
@@ -285,4 +287,45 @@ export interface EventsManager {
      * Close the manager and clean up resources.
      */
     close(): Promise<void>;
+    /**
+     * Emit a domain event to all registered listeners.
+     *
+     * Domain events are in-process events for business logic (e.g., OrderCreated,
+     * UserRegistered). They are distinct from broadcast events (WebSocket/SSE)
+     * which are client-facing.
+     *
+     * @example
+     * ```typescript
+     * await ctx.events.emit(new OrderCreatedEvent({
+     *   orderId: '123',
+     *   total: 99.99,
+     * }));
+     * ```
+     */
+    emit<TData extends Record<string, unknown>>(event: DomainEvent<TData>): Promise<void>;
+    /**
+     * Register a typed listener for a domain event class.
+     *
+     * The handler receives `event.data` — the typed payload — not the event
+     * instance itself.
+     *
+     * @param eventClass - The domain event class to listen for.
+     * @param handler    - Called with the event's `data` payload on each emit.
+     * @param options    - `{ sequential?, retryable? }`
+     *
+     * @example
+     * ```typescript
+     * events.on(OrderCreatedEvent, async (data) => {
+     *   await sendConfirmationEmail(data.orderId);
+     * });
+     * ```
+     */
+    on<TData extends Record<string, unknown>>(eventClass: DomainEventClass<TData>, handler: (data: TData) => void | Promise<void>, options?: DomainListenerOptions): void;
+    /**
+     * Remove a previously registered domain event listener.
+     *
+     * @param eventClass - The domain event class the listener was registered for.
+     * @param handler    - The exact handler reference passed to `on()`.
+     */
+    off<TData extends Record<string, unknown>>(eventClass: DomainEventClass<TData>, handler: (data: TData) => void | Promise<void>): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/events",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Real-time event broadcasting for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,7 @@
     "superjson": "2.2.6",
     "ws": "8.19.0",
     "zod": "4.3.6",
-    "@veloxts/core": "0.8.0"
+    "@veloxts/core": "0.8.2"
   },
   "peerDependencies": {
     "fastify": "^5.7.4",
@@ -42,14 +42,14 @@
     }
   },
   "devDependencies": {
-    "@types/node": "25.2.3",
+    "@types/node": "25.5.0",
     "@types/ws": "8.18.1",
-    "@vitest/coverage-v8": "4.0.18",
-    "fastify": "5.7.4",
-    "ioredis": "5.9.3",
+    "@vitest/coverage-v8": "4.1.0",
+    "fastify": "5.8.2",
+    "ioredis": "5.10.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.18",
-    "@veloxts/testing": "0.8.0"
+    "vitest": "4.1.0",
+    "@veloxts/testing": "0.8.2"
   },
   "publishConfig": {
     "access": "public"