@velony/domain 2.0.0 → 3.1.0

package/README.md

@@ -8,13 +8,6 @@ A TypeScript library providing core building blocks for Domain-Driven Design (DD
 npm install @velony/domain
 ```
 
-## Features
-
-- **Type-safe** - Full TypeScript support with comprehensive type definitions
-- **DDD Patterns** - Implementations of core DDD tactical patterns
-- **Immutable** - Value objects and events are immutable by design
-- **Minimal dependencies** - Only depends on `uuid` for event ID generation
-
 ## Core Concepts
 
 ### Entity
@@ -112,7 +105,7 @@ console.log(age.toString()); // "25"
 The entry point to an aggregate that maintains consistency boundaries and manages domain events.
 
 ```typescript
-import { AggregateRoot, Id, DomainEvent } from '@velony/domain';
+import { AggregateRoot, Id, DomainEvent, DomainEventRegistry } from '@velony/domain';
 
 class OrderId extends Id<string> {
   static create(value: string): OrderId {
@@ -120,14 +113,18 @@ class OrderId extends Id<string> {
   }
 }
 
-class OrderPlacedEvent extends DomainEvent<{ total: number }> {
-  public readonly type = 'order.placed';
-
-  constructor(aggregateId: string, total: number) {
-    super(aggregateId, { total });
+// Register the event type in the registry
+declare module '@velony/domain' {
+  interface DomainEventRegistry {
+    'order.placed': {
+      aggregateId: OrderId;
+      payload: { total: number };
+    };
   }
 }
 
+class OrderPlacedEvent extends DomainEvent<'order.placed'> {}
+
 class Order extends AggregateRoot<OrderId> {
   constructor(
     id: OrderId,
@@ -138,7 +135,7 @@ class Order extends AggregateRoot<OrderId> {
 
   place(): void {
     this.pushDomainEvent(
-      new OrderPlacedEvent(this.id.toString(), this.total)
+      new OrderPlacedEvent('order.placed', this.id, { total: this.total })
     );
   }
 }
@@ -150,28 +147,41 @@ const events = order.pullDomainEvents();
 
 ### Domain Event
 
-Represents something significant that happened in the domain.
+Represents something significant that happened in the domain. Events use a type-safe registry pattern for compile-time validation.
 
 ```typescript
-import { DomainEvent } from '@velony/domain';
+import { DomainEvent, DomainEventRegistry, Id } from '@velony/domain';
 
-interface UserRegisteredPayload {
-  email: string;
-  name: string;
+class UserId extends Id<string> {
+  static create(value: string): UserId {
+    return new UserId(value);
+  }
 }
 
-class UserRegisteredEvent extends DomainEvent<UserRegisteredPayload> {
-  public readonly type = 'user.registered';
-
-  constructor(aggregateId: string, email: string, name: string) {
-    super(aggregateId, { email, name });
+// Register event types in the DomainEventRegistry
+declare module '@velony/domain' {
+  interface DomainEventRegistry {
+    'user.registered': {
+      aggregateId: UserId;
+      payload: {
+        email: string;
+        name: string;
+      };
+    };
   }
 }
 
-const event = new UserRegisteredEvent('user-123', 'john@example.com', 'John Doe');
+class UserRegisteredEvent extends DomainEvent<'user.registered'> {}
+
+const userId = UserId.create('user-123');
+const event = new UserRegisteredEvent('user.registered', userId, {
+  email: 'john@example.com',
+  name: 'John Doe'
+});
 console.log(event.id); // UUIDv7
 console.log(event.type); // "user.registered"
 console.log(event.occurredAt); // Date
+console.log(event.aggregateId); // UserId instance
 console.log(event.payload); // { email: "john@example.com", name: "John Doe" }
 ```
 
@@ -214,15 +224,29 @@ StoragePath.create('files//data'); // Error: Storage path contains invalid doubl
 
 ### `AggregateRoot<TIdentifier>`
 - Extends `Entity<TIdentifier>`
-- `pullDomainEvents(): DomainEvent<any, any>[]` - Retrieve and clear events
-- `pushDomainEvent(event: DomainEvent<any, any>): void` - Add event (protected)
+- `pullDomainEvents(): AnyDomainEvent[]` - Retrieve and clear events
+- `pushDomainEvent(event: AnyDomainEvent): void` - Add event (protected)
 
-### `DomainEvent<TPayload>`
+### `DomainEvent<TType>`
 - `id: string` - Unique event ID (UUIDv7)
-- `aggregateId: string` - ID of the aggregate that produced the event
-- `payload: TPayload` - Event-specific data
+- `type: TType` - Type identifier for the event (must be registered in DomainEventRegistry)
+- `aggregateId: DomainEventRegistry[TType]['aggregateId']` - ID of the aggregate that produced the event
+- `payload: DomainEventRegistry[TType]['payload']` - Event-specific data
 - `occurredAt: Date` - Timestamp of occurrence
-- `type: string` - Event type identifier (abstract, must be implemented)
+
+### `DomainEventRegistry`
+Interface for registering event types with their aggregate ID and payload types. Extend this interface using module augmentation to register new event types:
+
+```typescript
+declare module '@velony/domain' {
+  interface DomainEventRegistry {
+    'your.event.type': {
+      aggregateId: YourAggregateId;
+      payload: YourPayloadType;
+    };
+  }
+}
+```
 
 ## License
 

package/dist/aggregate-root.d.ts

@@ -1,4 +1,4 @@
-import { DomainEvent } from './domain-event';
+import { type AnyDomainEvent } from './domain-event';
 import { Entity } from './entity';
 import { Id } from './id';
 declare const AGGREGATE_ROOT_BRAND: unique symbol;
@@ -25,7 +25,7 @@ export declare abstract class AggregateRoot<TIdentifier extends Id<string | numb
      *
      * @returns An array of domain events that occurred within the aggregate
      */
-    pullDomainEvents(): DomainEvent<any>[];
+    pullDomainEvents(): AnyDomainEvent[];
     /**
      * Adds a domain event to the aggregate's event collection.
      * Protected to allow only the aggregate itself to record events.
@@ -33,6 +33,6 @@ export declare abstract class AggregateRoot<TIdentifier extends Id<string | numb
      * @param event - The domain event to add
      * @protected
      */
-    protected pushDomainEvent(event: DomainEvent<any>): void;
+    protected pushDomainEvent(event: AnyDomainEvent): void;
 }
 export {};

package/dist/aggregate-root.js.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate-root.js","sourceRoot":"","sources":["../src/aggregate-root.ts"],"names":[],"mappings":";;;AACA,qCAAkC;AAKlC;;;;;;;;GAQG;AACH,MAAsB,aAEpB,SAAQ,eAAmB;IACV,CAAC,oBAAoB,CAAC,CAAO;IAE9C;;;OAGG;IACK,aAAa,GAAuB,EAAE,CAAC;IAE/C;;;;;;OAMG;IACI,gBAAgB;QACrB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACO,eAAe,CAAC,KAAuB;QAC/C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;CACF;AAlCD,sCAkCC"}
+{"version":3,"file":"aggregate-root.js","sourceRoot":"","sources":["../src/aggregate-root.ts"],"names":[],"mappings":";;;AACA,qCAAkC;AAKlC;;;;;;;;GAQG;AACH,MAAsB,aAEpB,SAAQ,eAAmB;IACV,CAAC,oBAAoB,CAAC,CAAO;IAE9C;;;OAGG;IACK,aAAa,GAAqB,EAAE,CAAC;IAE7C;;;;;;OAMG;IACI,gBAAgB;QACrB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACO,eAAe,CAAC,KAAqB;QAC7C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;CACF;AAlCD,sCAkCC"}

package/dist/domain-event.d.ts

@@ -1,18 +1,28 @@
-export declare const DOMAIN_EVENT_BRAND: unique symbol;
+import { Id } from './id';
+declare const DOMAIN_EVENT_BRAND: unique symbol;
+/**
+ * Registry that maps event types to their aggregate and payload types.
+ * Extend this interface to register new event types.
+ */
+export interface DomainEventRegistry {
+    [key: string]: {
+        aggregateId: Id<string | number>;
+        payload: unknown;
+    };
+}
 /**
  * Abstract base class for domain events in Domain-Driven Design.
  * A domain event represents something that happened in the domain that
  * domain experts care about. Events are immutable and represent facts.
  *
- * @template TPayload - The type of the event payload containing event-specific data
+ * @template TType - The type identifier for the event (must be registered in DomainEventRegistry)
  */
-export declare abstract class DomainEvent<TPayload> {
+export declare abstract class DomainEvent<TType extends keyof DomainEventRegistry> {
     private readonly [DOMAIN_EVENT_BRAND];
     /**
-     * Static type identifier for the event class.
-     * Should be overridden in concrete event classes.
+     * Type identifier for the event.
      */
-    static readonly type: string;
+    readonly type: TType;
     /**
      * Unique identifier for this event instance (UUIDv7).
      * @readonly
@@ -22,12 +32,12 @@ export declare abstract class DomainEvent<TPayload> {
      * The identifier of the aggregate that produced this event.
      * @readonly
      */
-    readonly aggregateId: string;
+    readonly aggregateId: DomainEventRegistry[TType]['aggregateId'];
     /**
      * The data payload specific to this event.
      * @readonly
      */
-    readonly payload: TPayload;
+    readonly payload: DomainEventRegistry[TType]['payload'];
     /**
      * The timestamp when this event occurred.
      * @readonly
@@ -36,15 +46,16 @@ export declare abstract class DomainEvent<TPayload> {
     /**
      * Creates a new domain event.
      *
+     * @param type - The event type identifier
      * @param aggregateId - The ID of the aggregate that produced this event
      * @param payload - The event-specific data
-     * @protected
-     */
-    protected constructor(aggregateId: string, payload: TPayload);
-    /**
-     * Gets the type identifier for this event.
-     *
-     * @returns The event type string from the static type property
+     * @public
      */
-    get type(): string;
+    constructor(type: TType, aggregateId: DomainEventRegistry[TType]['aggregateId'], payload: DomainEventRegistry[TType]['payload']);
 }
+/**
+ * Union type representing any domain event registered in the DomainEventRegistry.
+ * Useful for type-safe collections and handlers that work with multiple event types.
+ */
+export type AnyDomainEvent = DomainEvent<keyof DomainEventRegistry>;
+export {};

package/dist/domain-event.js

@@ -7,15 +7,14 @@ const uuid_1 = require("uuid");
  * A domain event represents something that happened in the domain that
  * domain experts care about. Events are immutable and represent facts.
  *
- * @template TPayload - The type of the event payload containing event-specific data
+ * @template TType - The type identifier for the event (must be registered in DomainEventRegistry)
  */
 class DomainEvent {
-    [exports.DOMAIN_EVENT_BRAND];
+    [DOMAIN_EVENT_BRAND];
     /**
-     * Static type identifier for the event class.
-     * Should be overridden in concrete event classes.
+     * Type identifier for the event.
      */
-    static type;
+    type;
     /**
      * Unique identifier for this event instance (UUIDv7).
      * @readonly
@@ -39,24 +38,18 @@ class DomainEvent {
     /**
      * Creates a new domain event.
      *
+     * @param type - The event type identifier
      * @param aggregateId - The ID of the aggregate that produced this event
      * @param payload - The event-specific data
-     * @protected
+     * @public
      */
-    constructor(aggregateId, payload) {
+    constructor(type, aggregateId, payload) {
+        this.type = type;
         this.id = (0, uuid_1.v7)();
         this.aggregateId = aggregateId;
         this.occurredAt = new Date();
         this.payload = payload;
     }
-    /**
-     * Gets the type identifier for this event.
-     *
-     * @returns The event type string from the static type property
-     */
-    get type() {
-        return this.constructor.type;
-    }
 }
 exports.DomainEvent = DomainEvent;
 //# sourceMappingURL=domain-event.js.map

package/dist/domain-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"domain-event.js","sourceRoot":"","sources":["../src/domain-event.ts"],"names":[],"mappings":";;;AAAA,+BAAoC;AAIpC;;;;;;GAMG;AACH,MAAsB,WAAW;IACd,CAAC,0BAAkB,CAAC,CAAO;IAE5C;;;OAGG;IACI,MAAM,CAAU,IAAI,CAAS;IAEpC;;;OAGG;IACa,EAAE,CAAS;IAE3B;;;OAGG;IACa,WAAW,CAAS;IAEpC;;;OAGG;IACa,OAAO,CAAW;IAElC;;;OAGG;IACa,UAAU,CAAO;IAEjC;;;;;;OAMG;IACH,YAAsB,WAAmB,EAAE,OAAiB;QAC1D,IAAI,CAAC,EAAE,GAAG,IAAA,SAAM,GAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,IAAW,IAAI;QACb,OAAQ,IAAI,CAAC,WAA4C,CAAC,IAAI,CAAC;IACjE,CAAC;CACF;AAvDD,kCAuDC"}
+{"version":3,"file":"domain-event.js","sourceRoot":"","sources":["../src/domain-event.ts"],"names":[],"mappings":";;;AAAA,+BAAoC;AAgBpC;;;;;;GAMG;AACH,MAAsB,WAAW;IACd,CAAC,kBAAkB,CAAC,CAAO;IAE5C;;OAEG;IACa,IAAI,CAAQ;IAE5B;;;OAGG;IACa,EAAE,CAAS;IAE3B;;;OAGG;IACa,WAAW,CAA4C;IAEvE;;;OAGG;IACa,OAAO,CAAwC;IAE/D;;;OAGG;IACa,UAAU,CAAO;IAEjC;;;;;;;OAOG;IACH,YACE,IAAW,EACX,WAAsD,EACtD,OAA8C;QAE9C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,IAAA,SAAM,GAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAnDD,kCAmDC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velony/domain",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "description": "TypeScript library providing core building blocks for Domain-Driven Design (DDD) applications",
   "keywords": [
     "ddd",