@hg-ts/domain 0.5.16 → 0.5.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hg-ts/domain",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "main": "dist/index.js",
   "type": "module",
   "exports": {
@@ -17,12 +17,12 @@
     "test:dev": "vitest watch"
   },
   "devDependencies": {
-    "@hg-ts-config/typescript": "0.5.16",
-    "@hg-ts/events": "0.5.16",
-    "@hg-ts/exception": "0.5.16",
-    "@hg-ts/linter": "0.5.16",
-    "@hg-ts/tests": "0.5.16",
-    "@hg-ts/types": "0.5.16",
+    "@hg-ts-config/typescript": "0.5.18",
+    "@hg-ts/events": "0.5.18",
+    "@hg-ts/exception": "0.5.18",
+    "@hg-ts/linter": "0.5.18",
+    "@hg-ts/tests": "0.5.18",
+    "@hg-ts/types": "0.5.18",
     "@types/node": "22.19.1",
     "@types/uuid": "10.0.0",
     "@vitest/coverage-v8": "4.0.14",
@@ -35,8 +35,8 @@
     "vitest": "4.0.14"
   },
   "peerDependencies": {
-    "@hg-ts/events": "0.5.16",
-    "@hg-ts/exception": "0.5.16",
+    "@hg-ts/events": "0.5.18",
+    "@hg-ts/exception": "0.5.18",
     "reflect-metadata": "*",
     "tslib": "*",
     "vitest": "*"

package/src/base.aggregate.ts

@@ -0,0 +1,91 @@
+import {
+	EventHandler,
+	getEventsToHandle,
+	getListenMethods,
+} from '@hg-ts/events';
+
+import { BaseEntity } from './base.entity.js';
+import { CreatedEventNotFoundException } from './created-event.not-found.exception.js';
+
+import {
+	AggregateCreatedEvent,
+	DomainEvent,
+	STORED_PROPERTY,
+} from './events/index.js';
+import type { Identifiable } from './types.js';
+
+const AGGREGATE_SYMBOL = Symbol('AGGREGATE_SYMBOL');
+export const AGGREGATE_EVENTS_SYMBOL = Symbol('AGGREGATE_EVENTS_SYMBOL');
+
+export abstract class BaseAggregate<Dto extends Identifiable> extends BaseEntity<Dto> {
+	protected readonly [AGGREGATE_SYMBOL]: string;
+	protected readonly [AGGREGATE_EVENTS_SYMBOL]: DomainEvent<any>[] = [];
+
+	protected constructor(params: Identifiable) {
+		super(params);
+
+		Object.defineProperty(this, AGGREGATE_SYMBOL, {
+			value: params.id,
+			configurable: false,
+			enumerable: false,
+			writable: true,
+		});
+	}
+
+	public getEvents(): DomainEvent<any>[] {
+		return this[AGGREGATE_EVENTS_SYMBOL];
+	}
+
+	public getNewEvets(): DomainEvent<any>[] {
+		return this[AGGREGATE_EVENTS_SYMBOL].filter(item => !item[STORED_PROPERTY]);
+	}
+
+	public static restoreFromEvents<
+		Dto extends Identifiable,
+		Aggregate extends BaseAggregate<Dto>,
+	>(
+		aggregateCtor: Class<Aggregate, [Dto]>,
+		createdEventCtor: Class<AggregateCreatedEvent<Omit<Dto, keyof Identifiable>>, any[]>,
+		events: DomainEvent<any>[],
+	): Aggregate {
+		const createdEvent = events.find(event => event instanceof createdEventCtor);
+		if (!createdEvent) {
+			throw new CreatedEventNotFoundException(aggregateCtor.name);
+		}
+
+		const aggregate = new aggregateCtor({
+			id: createdEvent.entityId,
+			...createdEvent.body,
+		} as Dto);
+
+		aggregate.applyEvents(events);
+
+		return aggregate;
+	}
+
+	protected applyEvents(events: DomainEvent<any>[]): void {
+		events.forEach(event => this.produceEvent(event));
+	}
+
+	protected produceEvent(event: DomainEvent<any>): void {
+		this.triggerListeners(event);
+
+		this[AGGREGATE_EVENTS_SYMBOL].push(event);
+	}
+
+	private triggerListeners(event: DomainEvent<any>): void {
+		const proto = Object.getPrototypeOf(this)!;
+		const listenMethods = getListenMethods(proto);
+
+		listenMethods.forEach(methodName => {
+			const method = (this as any)[methodName].bind(this) as EventHandler;
+			const eventsToHandle = getEventsToHandle(proto, methodName);
+
+			eventsToHandle.forEach(eventCtor => {
+				if (event instanceof eventCtor) {
+					method(event);
+				}
+			});
+		});
+	}
+}

package/src/base.entity.ts

@@ -0,0 +1,20 @@
+import type {
+	DtoSerializable,
+	Identifiable,
+} from './types.js';
+
+export abstract class BaseEntity<Dto extends Identifiable>
+implements Identifiable, DtoSerializable<Dto> {
+	public readonly id: string;
+
+	protected constructor(params: Identifiable) {
+		this.id = params.id;
+	}
+
+	public equals<T extends BaseEntity<Identifiable>>(entity: T): boolean {
+		return Object.getPrototypeOf(this)!.constructor === Object.getPrototypeOf(entity)!.constructor
+			&& this.id === entity.id;
+	}
+
+	public abstract toDto(): Dto;
+}

package/src/created-event.not-found.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from '@hg-ts/exception';
+
+export class CreatedEventNotFoundException extends BaseException {
+	public constructor(entityName: string) {
+		super(`Created event for entity "${entityName}" not found.`);
+	}
+}

package/src/events/aggregate-created.event.ts

@@ -0,0 +1,3 @@
+import { DomainEvent } from './domain.event.js';
+
+export abstract class AggregateCreatedEvent<Body> extends DomainEvent<Body> {}

package/src/events/domain.event.ts

@@ -0,0 +1,61 @@
+import {
+	BaseEvent,
+	BaseEventDto,
+	EventParams,
+} from '@hg-ts/events';
+import { v7 as uuid } from 'uuid';
+
+import type {
+	DtoSerializable,
+	Identifiable,
+} from '../types.js';
+
+export const STORED_PROPERTY = Symbol('Domain event stored');
+
+export type DomainEventDto = BaseEventDto & {
+	id: string;
+	entityName: string;
+	entityId: string;
+};
+
+export type DomainEventParams<Body = unknown> = EventParams<Body> & {
+	id?: string;
+	entityName: string;
+	entityId: string;
+	[STORED_PROPERTY]?: true;
+};
+
+
+export class DomainEvent<Body = unknown> extends BaseEvent<Body>
+	implements Identifiable, DtoSerializable<DomainEventDto> {
+	public readonly id: string;
+	public readonly entityName: string;
+	public readonly entityId: string;
+	public [STORED_PROPERTY]: boolean;
+
+	public constructor(params: DomainEventParams<Body>) {
+		super(params);
+
+		this.id = params.id ?? DomainEvent.generateId();
+
+		this.entityName = params.entityName;
+		this.entityId = params.entityId;
+		this[STORED_PROPERTY] = params[STORED_PROPERTY] ?? false;
+	}
+
+	public toDto(): DomainEventDto {
+		return {
+			id: this.id,
+			entityId: String(this.entityId),
+			entityName: this.entityName,
+			name: this.name,
+			body: this.body,
+			occurredOn: this.occurredOn,
+			traceId: this.traceId,
+		};
+	}
+
+	public static generateId(): string {
+		return uuid();
+	}
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export * from './aggregate-created.event.js';
+export * from './domain.event.js';

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export { BaseAggregate } from './base.aggregate.js';
+export * from './base.entity.js';
+
+export * from './events/domain.event.js';
+export * from './events/aggregate-created.event.js';

package/src/tests/aggregate.test.ts

@@ -0,0 +1,103 @@
+import {
+	Describe,
+	expect,
+	ExpectException,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+
+import { AGGREGATE_EVENTS_SYMBOL } from '../base.aggregate.js';
+import { CreatedEventNotFoundException } from '../created-event.not-found.exception.js';
+import { STORED_PROPERTY } from '../events/domain.event.js';
+
+import { ExampleCreatedEvent } from './example-created.event.js';
+import { ExampleUpdatedEvent } from './example-updated.event.js';
+import { ExampleAggregate } from './example.aggregate.js';
+
+@Describe()
+export class AggregateTest extends Suite {
+	@Test()
+	public simpleCreate(): void {
+		const aggregate = ExampleAggregate.create('original name');
+
+		const events = aggregate[AGGREGATE_EVENTS_SYMBOL];
+
+		expect(aggregate).toBeInstanceOf(ExampleAggregate);
+		expect(events).toBeInstanceOf(Array);
+		expect(events).toHaveLength(1);
+		expect(events[0]).toBeInstanceOf(ExampleCreatedEvent);
+		expect(events[0]![STORED_PROPERTY]).toBe(false);
+	}
+
+	@Test()
+	public equalsSuccess(): void {
+		const baseAggregate = ExampleAggregate.create('original name');
+		const cloneAggregate1 = new ExampleAggregate(baseAggregate.toDto());
+		const cloneAggregate2 = new ExampleAggregate(baseAggregate.toDto());
+
+		expect(baseAggregate.equals(baseAggregate)).toBeTruthy();
+		expect(cloneAggregate1.equals(cloneAggregate2)).toBeTruthy();
+	}
+
+	@Test()
+	public equalsFails(): void {
+		const aggregate = ExampleAggregate.create('original name');
+		const cloneAggregate = ExampleAggregate.create('original name');
+
+		expect(aggregate.equals(cloneAggregate)).toBeFalsy();
+	}
+
+	@Test()
+	public updateName(): void {
+		const aggregate = ExampleAggregate.create('original name');
+
+		aggregate.update('new name');
+
+		const events = aggregate[AGGREGATE_EVENTS_SYMBOL];
+
+		expect(events).toBeInstanceOf(Array);
+		expect(events).toHaveLength(2);
+		expect(events[0]).toBeInstanceOf(ExampleCreatedEvent);
+		expect(events[1]).toBeInstanceOf(ExampleUpdatedEvent);
+
+		expect(aggregate.toDto().name).toEqual('new name');
+	}
+
+	@Test()
+	public restoreCreated(): void {
+		const aggregate = ExampleAggregate.create('original name');
+		const originalEvents = aggregate[AGGREGATE_EVENTS_SYMBOL];
+
+		originalEvents.forEach(event => {
+			event[STORED_PROPERTY] = true;
+		});
+
+		const restored = ExampleAggregate.restoreFromEvents(ExampleAggregate, ExampleCreatedEvent, originalEvents);
+
+		expect(restored.toDto()).toMatchObject(aggregate.toDto());
+		expect(restored.getNewEvets()).toHaveLength(0);
+	}
+
+	@Test()
+	public restoreUpdated(): void {
+		const aggregate = ExampleAggregate.create('original name');
+		aggregate.update('new name');
+		const originalEvents = aggregate[AGGREGATE_EVENTS_SYMBOL];
+
+		originalEvents.forEach(event => {
+			event[STORED_PROPERTY] = true;
+		});
+
+		const restored = ExampleAggregate.restoreFromEvents(ExampleAggregate, ExampleCreatedEvent, originalEvents);
+
+		expect(restored.getEvents()).toHaveLength(originalEvents.length);
+		expect(restored.getEvents()[0]?.toDto().name).toBe(ExampleCreatedEvent.name);
+		expect(restored.toDto()).toMatchObject(aggregate.toDto());
+	}
+
+	@Test()
+	@ExpectException(CreatedEventNotFoundException)
+	public noCreatedEvent(): void {
+		ExampleAggregate.restoreFromEvents(ExampleAggregate, ExampleCreatedEvent, []);
+	}
+}

package/src/tests/example-created.event.ts

@@ -0,0 +1,11 @@
+import { AggregateCreatedEvent } from '../events/aggregate-created.event.js';
+
+export class ExampleCreatedEvent extends AggregateCreatedEvent<{ name: string }> {
+	public constructor(id: string, name: string) {
+		super({
+			entityId: id,
+			entityName: 'Example',
+			body: { name },
+		});
+	}
+}

package/src/tests/example-updated.event.ts

@@ -0,0 +1,11 @@
+import { DomainEvent } from '../events/domain.event.js';
+
+export class ExampleUpdatedEvent extends DomainEvent<{ name: string}> {
+	public constructor(id: string, name: string) {
+		super({
+			entityId: id,
+			entityName: 'Example',
+			body: { name },
+		});
+	}
+}

package/src/tests/example.aggregate.ts

@@ -0,0 +1,43 @@
+import { Listen } from '@hg-ts/events';
+import { BaseAggregate } from '../base.aggregate.js';
+import { ExampleCreatedEvent } from './example-created.event.js';
+import { ExampleUpdatedEvent } from './example-updated.event.js';
+
+type ExampleAggregateDto = {
+	id: string;
+	name: string;
+};
+
+export class ExampleAggregate extends BaseAggregate<ExampleAggregateDto> {
+	private name: string;
+
+	public constructor(dto: ExampleAggregateDto) {
+		super(dto);
+
+		this.name = dto.name;
+	}
+
+	public update(newName: string): void {
+		this.produceEvent(new ExampleUpdatedEvent(this.id, newName));
+	}
+
+	public toDto(): ExampleAggregateDto {
+		return {
+			id: this.id,
+			name: this.name,
+		};
+	}
+
+	public static create(name: string): ExampleAggregate {
+		const aggregate = new ExampleAggregate({ id: crypto.randomUUID(), name });
+
+		aggregate.produceEvent(new ExampleCreatedEvent(aggregate.id, name));
+
+		return aggregate;
+	}
+
+	@Listen(ExampleUpdatedEvent)
+	protected onUpdated(event: ExampleUpdatedEvent): void {
+		this.name = event.body.name;
+	}
+}

package/src/types.ts

@@ -0,0 +1,7 @@
+export type Identifiable = {
+    id: string;
+};
+
+export type DtoSerializable<Dto extends Identifiable> = {
+    toDto(): Dto;
+};