DEV Community: minericefield

[DDD] Tactical Design Patterns Part 4: Consistency

minericefield — Thu, 10 Apr 2025 14:06:51 +0000

More than a year ago, I wrote about tactical design patterns in Domain-Driven Design (DDD).
I'm sorry. I'm not good at English.
This article is Part 4 of the series and focuses on patterns for maintaining consistency.

GitHub Repository

https://github.com/minericefield/ddd-onion-lit

Please refer to the beginning of Part 1 for other details regarding the architecture and themes.

Transaction Management

Referring to IDDD (Implementing Domain-Driven Design), we will review the design approach for transaction management.

Fundamentally, an aggregate defines the boundary of strong consistency.
A single command should modify only one aggregate.
- Reading from multiple aggregates is allowed, but only one should be changed per command.

At this stage, both the aggregates and commands are properly designed. Now, we just need to ensure transactional consistency in each use case that has side effects.

Transaction control should be handled at the Application Layer.
Its role is to coordinate the scenario flow.
Letting the Application Layer take charge of things like task progression and data consistency helps increase conceptual cohesion.

Interface Design

This time, we’ve prepared the following interface:

// application/shared/repository-transactor.ts
export abstract class RepositoryTransactor {
  abstract handle<T>(
    manipulation: () => Promise<T>,
  ): ReturnType<typeof manipulation>;
}

This interface abstracts away the entire transaction process, including things like commit and rollback.
By accepting operations with side effects (manipulation) and executing them as a transaction, it ensures atomicity and consistency in repository operations.

There may be situations where, when an exception occurs during a transaction, we need to instruct other external drivers or different stores to rollback or retry in a different way.
To avoid the misconception that this interface guarantees consistency across all such systems, we chose to name it RepositoryTransactor.

Thread-Local Storage

The simplest way to implement a Transactor is to directly assign a reference that can identify the connection or process of the data store to a thread-local store (like in Java), which can later be accessed in the repository implementation.
We’ll use node:async_hooks for this, and the implementation would probably look like the following:

export class TypeormRepositoryTransactor implements RepositoryTransactor {
  constructor(
    private readonly dataSource: DataSource,
    private readonly als: AsyncLocalStorage<EntityManager>,
  ) {}

  async handle<T>(
    manipulation: () => Promise<T>,
  ): ReturnType<typeof manipulation> {
    return this.dataSource.transaction((entityManager) => {
      return this.als.run(entityManager, manipulation);
    });
  }
}

On the other hand, there may be a need to consistently retain different types of information within the same scope throughout the entire request-response lifecycle.
In this application, we’ve decided to initialize the corresponding thread-local store at the beginning of each interaction, so that arbitrary data can be referenced and stored within it.
With that in mind, we’ll go ahead and implement the store and the Transactor.

// infrastructure/node-async-hooks/als-thread-context.ts
export class AlsThreadContext {
  constructor(private readonly als: AsyncLocalStorage<Map<string, any>>) {}

  run<T>(run: () => Promise<T>): Promise<T> {
    const threadId = Math.random().toString(32).substring(2);

    return this.als.run(new Map([['threadId', threadId]]), run);
  }

  get<T>(key: string): T | undefined {
    return this.als.getStore().get(key);
  }

  set(key: string, value: any) {
    this.als.getStore().set(key, value); // or enterWith
  }
}

We use a Map for the store, and while we're at it, we assign a random threadId.
(If the store is already initialized — for example, during event handling — it might also be interesting to push the previous context like a stack.)

It's also possible to implement similar functionality more easily by simply holding the store instance using request-scoped injection without relying on node:async_hooks.
However, in our case, the store is designed to be accessible when needed, even in headless applications, without being tied to specific operations.

We hook this into middleware like so:

// app.module.ts
export class AppModule implements NestModule {
  constructor(private readonly alsThreadContext: AlsThreadContext) {}

  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply((_req, _res, next) => {
        this.alsThreadContext.run(next);
      })
      .forRoutes('*');
  }
}

Transactor Implementation

We implement the Transactor using the store.

// infrastructure/mysql/typeorm/transactors/typeorm-repository-transactor.ts
export class TypeormRepositoryTransactor implements RepositoryTransactor {
  constructor(
    private readonly dataSource: DataSource,
    private readonly alsThreadContext: AlsThreadContext,
  ) {}

  async handle<T>(
    manipulation: () => Promise<T>,
  ): ReturnType<typeof manipulation> {
    return this.dataSource.transaction((entityManager) => {
      this.alsThreadContext.set(
        ENTITY_MANAGER_THREAD_CONTEXT_KEY,
        entityManager,
      );

      return manipulation();
    });
  }
}

Here, we store the EntityManager in the thread-local store.

Repository Implementation

We retrieve TypeORM repositories using the EntityManager.

First, we created a helper class to get TypeORM repositories from the EntityManager:

// infrastructure/mysql/typeorm/repositories/shared/get-typeorm-repositories.ts
export default class GetTypeormRepositories {
  constructor(
    private readonly threadContext: AlsThreadContext,
    private readonly dataSource: DataSource,
  ) {}

  handle<T extends readonly Models[keyof Models][]>(
    ...models: T
  ): { [K in keyof T]: Repository<InstanceType<T[K]>> } {
    const entityManager = this.threadContext.get<EntityManager>(
      ENTITY_MANAGER_THREAD_CONTEXT_KEY,
    );

    /**
     * map cannot recognize tuple types
     */
    return models.map((model) =>
      (entityManager ?? this.dataSource).getRepository(model),
    ) as { [K in keyof T]: Repository<InstanceType<T[K]>> };
  }
}

In the actual repository implementations, we use this helper to access the TypeORM repositories:

// infrastructure/mysql/typeorm/repositories/task.typeorm-repository.ts
export class TaskTypeormRepository implements TaskRepository {
  constructor(private readonly getRepositories: GetTypeormRepositories) {}

  async update(task: Task) {
    const [taskRepository, taskAssignmentRepository, taskCommentRepository] =
      this.getRepositories.handle(
        models.Task,
        models.TaskAssignment,
        models.TaskComment,
      );

    await taskRepository.update(task.id.value, { name: task.name.value });

    await taskAssignmentRepository.delete({ taskId: task.id.value });
    task.userId &&
      (await taskAssignmentRepository.save({
        taskId: task.id.value,
        userId: task.userId.value,
      }));

    await taskCommentRepository.delete({ taskId: task.id.value });
    await taskCommentRepository.save(
      task.comments.map((comment) => ({
        id: comment.id.value,
        userId: comment.userId.value,
        content: comment.content,
        postedAt: comment.postedAt,
        taskId: task.id.value,
      })),
    );
  }

  async find() {
    const [taskRepository] = this.getRepositories.handle(models.Task);
    const tasks = await taskRepository.find({
      relations: {
        taskAssignment: true,
        taskComments: true,
      },
    });
    return tasks.map((task) =>
      Task.reconstitute(
        new TaskId(task.id),
        new TaskName(task.name),
        task.taskComments.map(
          (taskComment) =>
            new Comment(
              new CommentId(taskComment.id),
              new UserId(taskComment.userId),
              taskComment.content,
              taskComment.postedAt,
            ),
        ),
        task.taskAssignment?.userId && new UserId(task.taskAssignment.userId),
      ),
    );
  }
}

Use Case Implementation

We’ll wrap the use case execution with the Transactor.

// application/task/create-task.usecase.ts
export class CreateTaskUseCase {
  constructor(
    private readonly taskRepository: TaskRepository,
    private readonly taskIdFactory: TaskIdFactory,
    private readonly repositoryTransactor: RepositoryTransactor,
  ) {}

  /**
   * @throws {TaskNameCharactersExceededException}
   */
  async handle(
    requestDto: CreateTaskUseCaseRequestDto,
  ): Promise<CreateTaskUseCaseResponseDto> {
    return this.repositoryTransactor.handle(async () => {
      /**
       * Create task.
       */
      const task = Task.create(
        await this.taskIdFactory.handle(),
        new TaskName(requestDto.taskName),
      );

      /**
       * Store it.
       */
      await this.taskRepository.insert(task);

      return new CreateTaskUseCaseResponseDto(task);
    });
  }
}

For now, we simply take the approach of wrapping the entire operation with the Transactor.
This guarantees that the aggregate’s state changes will be atomically persisted.
That concludes the section on transaction control.

Logging

This is a bit of a tangent, but since we’ve embedded a threadId into the store, let’s try injecting it into the logs.
It should be useful for tracing and monitoring.

// infrastructure/nestjs-common/nestjs-common-console-logger.ts
export class NestjsCommonConsoleLogger extends ConsoleLogger implements Logger {
  constructor(private readonly alsThreadContext: AlsThreadContext) {
    super();
  }

  log(message: any) {
    super.log({
      threadId: this.alsThreadContext.get('threadId'),
      message: message,
    });
  }

It's quite minimal in functionality, but we’ve built a simple logger that outputs the threadId alongside the message.

Let’s insert some sample logs:

{
  "threadId": "131j1fffra",
  "message": "Request url: /tasks/061a7db5-2d24-416e-9564-d1813db2cb91, method: GET"
}
{
  "threadId": "131j1fffra",
  "message": "task found in FindTaskUseCase: task name: Review the project documentation"
}
{
  "threadId": "131j1fffra",
  "message": "Response time: 95ms"
}

The first and last logs are output from the presentation layer's interceptor.
The middle one is from the use case in the application layer.
Now, thanks to the threadId, we can trace the entire interaction.

Consistency Across Aggregates

Consistency between different aggregates is ensured through eventual consistency.
As an example, let’s add the following requirements and implement a simple scenario:

When a user is newly created, onboarding tasks are assigned.
The onboarding tasks are:
- Create your GitHub account
- Review the project documentation

Domain Event

First, we’ve prepared a domain event for user creation.

// domain/user/user-created.domain-event.ts
export class UserCreated extends DomainEvent {
  constructor(readonly userId: UserId) {
    super();
  }

  get name() {
    return UserCreated.name;
  }
}

Event Publishing

Event Publishing Infrastructure

For this example, we’ve chosen to use @nestjs/event-emitter as a fixed event publishing mechanism.

// domain/shared/domain-event-publisher.ts
export abstract class DomainEventPublisher {
  abstract handle(...domainEvents: DomainEvent[]): void;
}

// infrastructure/nestjs-event-emitter/nestjs-event-emitter-domain-event-publisher.ts
export class NestjsEventEmitterDomainEventPublisher
  implements DomainEventPublisher
{
  constructor(private readonly eventEmitter: EventEmitter2) {}

  handle(...domainEvents: DomainEvent[]) {
    domainEvents.forEach((domainEvent) => {
      this.eventEmitter.emitAsync(domainEvent.name, domainEvent);
    });
  }
}

In a real-world application, depending on the event, it may be necessary to transform it into a public language and send it to other contexts or external systems.

When to Generate and Publish Events

There are various options for when to publish events and how to implement it.

Publishing events directly from entities.
- For example, when user.changeName is executed, it internally generates and publishes a UserChangedName event.
  - In some cases, the event is generated and published via a static method inside the domain event class.
  - In others, the entity simply creates the event, and passes it to a publisher.
- This approach can be combined with an ORM that supports automatic change tracking (dirty checking) via implicit copies.
- While it allows for maintaining the purity of the domain model, it also has some drawbacks:
  - Performance overhead
  - Difficulty in testing and debugging
  - It may not work well when coordinating across multiple contexts or with asynchronous processing
Storing events in entities and deferring publication until a later stage
- This approach avoids the drawbacks mentioned above.
- For example, in the dotnet sample code, domain events are published together with entity persistence.
  - In the repository pattern, this means that events are published from the repository.
  - In either case, both approaches align well with the pattern of accumulating events within the entity.

In our case, we’ll take a simple approach:
Let the entity accumulate events, and publish them from the application service.

This stays true to the original responsibility of the repository.
If, for some reason, events ever need to be published synchronously before the transaction is committed (which is generally not desirable), this approach makes it easier to support.
There is a risk of forgetting to publish the events, but this approach makes the flow easier to trace.

Storing Domain Events

We added a minimal mechanism for storing domain events in the User aggregate root.
(There's no clearing of events implemented for now.)

// domain/shared/domain-events-storable-aggregate-root.ts
export abstract class DomainEventStorableAggregateRoot<T extends DomainEvent> {
  private _events: T[] = [];

  get events(): T[] {
    return [...this._events];
  }

  protected addEvent(event: T) {
    this._events = [...this._events, event];
  }
}

// domain/user/user.aggregate-root.ts
export class User extends DomainEventStorableAggregateRoot<
  UserFooBar | UserCreated
> {
  private constructor(
    readonly id: UserId,
    readonly name: string,
    readonly emailAddress: UserEmailAddress,
  ) {
    super();
  }

  static create(id: UserId, name: string, emailAddress: UserEmailAddress) {
    const user = new User(id, name, emailAddress);
    user.addEvent(new UserCreated(id));
    return user;
  }

  static reconstitute(
    id: UserId,
    name: string,
    emailAddress: UserEmailAddress,
  ) {
    return new User(id, name, emailAddress);
  }
}

The call to user.addEvent(new UserCreated(id)) is made inside static create.

Triggering Event Publication from the Application Service

We call domainEventPublisher from the application service:

// application/user/create-user.usecase.ts
export class CreateUserUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly userIdFactory: UserIdFactory,
    private readonly userEmailAddressIsNotDuplicated: UserEmailAddressIsNotDuplicated,
    private readonly repositoryTransactor: RepositoryTransactor,
    private readonly domainEventPublisher: DomainEventPublisher,
  ) {}

  /**
   * @throws {InvalidUserEmailAddressFormatException}
   * @throws {DuplicatedUserEmailAddressException}
   */
  async handle(
    requestDto: CreateUserUseCaseRequestDto,
  ): Promise<CreateUserUseCaseResponseDto> {
    return this.repositoryTransactor.handle(async () => {
      /**
       * Create userEmailAddress.
       */
      const userEmailAddress = new UserEmailAddress(requestDto.emailAddress);
      await this.userEmailAddressIsNotDuplicated.handle(userEmailAddress);

      /**
       * Create user.
       */
      const user = User.create(
        await this.userIdFactory.handle(),
        requestDto.name,
        userEmailAddress,
      );

      /**
       * Store it.
       */
      await this.userRepository.insert(user);

      /**
       * Publish domain events.
       */
      this.domainEventPublisher.handle(...user.events);

      return new CreateUserUseCaseResponseDto(user);
    });
  }
}

Although domainEventPublisher uses emitAsync (with asynchronous handlers),
you could also explicitly call it outside of repositoryTransactor to emphasize that publishing is decoupled from the transaction.

Handling Events

In IDDD, events are received by adapters and passed into application services
(since IDDD follows the hexagonal architecture).
We’ll follow a similar approach here.

Below is the application service that creates onboarding tasks:

// application/task/create-onboarding-tasks.usecse.ts
export class CreateOnboardingTasksUseCase {
  constructor(
    private readonly taskRepository: TaskRepository,
    private readonly userRepository: UserRepository,
    private readonly createOnboardingTasks: CreateOnboardingTasks,
    private readonly repositoryTransactor: RepositoryTransactor,
    private readonly logger: Logger,
  ) {}

  /**
   * @throws {NotFoundApplicationException}
   */
  async handle(
    requestDto: CreateOnboardingTasksUseCaseRequestDto,
  ): Promise<CreateOnboardingTasksUseCaseResponseDto> {
    return this.repositoryTransactor.handle(async () => {
      /**
       * Find user.
       */
      const userId = new UserId(requestDto.userId);
      if (!(await this.userRepository.findOneById(userId))) {
        throw new NotFoundApplicationException('User not found.');
      }

      /**
       * Create onboarding tasks.
       */
      const tasks = await this.createOnboardingTasks.handle(userId);
      await this.taskRepository.insertMany(tasks);

      this.logger.log(`Onboarding tasks created for user id: ${userId.value}`);

      return new CreateOnboardingTasksUseCaseResponseDto(tasks);
    });
  }
}

The onboarding tasks are generated via a domain service, and finally persisted.

Now we invoke the application service from an event listener:

// infrastructure/nestjs-event-emitter/nestjs-event-emitter-user-created-domain-event-listener.ts
export class NestjsEventEmitterUserCreatedDomainEventListener {
  constructor(
    private readonly createOnboardingTasksUseCase: CreateOnboardingTasksUseCase,
    private readonly alsThreadContext: AlsThreadContext,
  ) {}

  @OnEvent(UserCreated.name, { async: true, promisify: true })
  async handle(userCreated: UserCreated) {
    return this.alsThreadContext.run(async () => {
      await this.createOnboardingTasksUseCase.handle({
        userId: userCreated.userId.value,
      });
    });
  }
}

With this setup, we’ve achieved consistency across multiple aggregates using eventual consistency.

Resources

[DDD] Tactical Design Patterns Part 3: Presentation/Infrastructure Layer

minericefield — Tue, 16 Jan 2024 14:57:32 +0000

I will be applying Domain-Driven Design (DDD) tactical design patterns in this article.
I'm sorry. I'm not good at English.
It is divided into the following sections:

Domain Layer
Application Layer
Presentation/Infrastructure Layer (this article)
Consistency

To keep the description of source code in the article compact, I will be implementing it from a bottom-up approach.

GitHub Repository

https://github.com/minericefield/ddd-onion-lit

Please refer to the beginning of Part 1 for other details regarding the architecture and themes.

Presentation / Infrastructure Layer

Due to the nature of these layers, implementations primarily focus on framework-specific details. However, in DDD, specifics about framework functionalities are not crucial.
Let's just roughly go through and confirm these layers.

Presentation Layer (User Interface Layer)

We decided to expose an HTTP REST-like interface.

Exception Filters

NestJS provides Exception filters to handle exceptions and respond to users appropriately. Exception filters fall under the responsibility of the presentation layer. While there may be cases where exceptions received from application services are handled individually, we will define some common behaviors using these filters.

@Catch(ValidationDomainException)
export class ValidationDomainExceptionFilter implements ExceptionFilter {
  catch(exception: ValidationDomainException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const statusCode = HttpStatus.BAD_REQUEST;

    response
      .status(statusCode)
      .json({ statusCode, message: exception.message });
  }
}

@Catch(UnexpectedDomainException)
export class UnexpectedDomainExceptionFilter implements ExceptionFilter {
  catch(exception: UnexpectedDomainException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const statusCode = HttpStatus.INTERNAL_SERVER_ERROR;

    Logger.error(exception.message, exception.stack, exception.cause);

    response
      .status(statusCode)
      .json({ statusCode, message: 'An unexpected error ocurred.' });
  }
}

In these exception filters, we first map the exceptions to HttpStatus. If we receive ValidationDomainException as is, we decide it's appropriate to map it to BAD_REQUEST (400) in the HTTP world. Additionally, we determine that exposing the error message as is is acceptable and include it in the response.
There might be cases where you want to assign different status codes depending on specific endpoints or exceptions or where you don't want to show the error message as is (e.g., adding a message prompting the end user to re-enter). Generally, domain layer exceptions only provide error messages necessary for domain layer representation and do not consider specific end-user details. In such cases, you would catch exceptions inline in the implementation of each endpoint or prepare specific filters to create responses.
In the UnexpectedDomainExceptionFilter, which handles unexpected exceptions, we log an error, and for end-users, we conceal the details. In case internal information that could pose a vulnerability is included, we hide the details.

@Catch()
export class AllExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const statusCode = HttpStatus.INTERNAL_SERVER_ERROR;

    Logger.error(exception);

    response
      .status(statusCode)
      .json({ statusCode, message: 'An unexpected error occurred.' });
  }
}

This filter handles all other exceptions that couldn't be captured by the specific filters mentioned earlier. Similar to the UnexpectedDomainException, it assigns INTERNAL_SERVER_ERROR (500) and logs an error
(this filter rather, becomes a filter for truly unexpected exceptions).

Maintaining Sessions Using Cookies

export class UserSessionCookie {
  private static readonly COOKIE_NAME = 'ddd-onion-lit_usid';
  private static readonly COOKIE_MAX_AGE = 1000 * 60 * 60 * 24 * 30;

  constructor(private readonly configService: ConfigService) {}

  get(request: Request): SessionId | undefined {
    return request.cookies[UserSessionCookie.COOKIE_NAME];
  }

  set(response: Response, sessionId: SessionId) {
    response.cookie(UserSessionCookie.COOKIE_NAME, sessionId, {
      httpOnly: true,
      secure: this.configService.get('NODE_ENV') === 'production',
      maxAge: UserSessionCookie.COOKIE_MAX_AGE,
    });
  }
}

We decided to use cookies for exchanging sessions with the HTTP client. As long as you can handle get and set for cookies, it should be fine.

Authorization Guard

export class AuthGuard implements CanActivate {
  constructor(
    private readonly userSessionCookie: UserSessionCookie,
    private readonly availableUserSessionProvider: AvailableUserSessionProvider,
  ) {}

  async canActivate(context: ExecutionContext) {
    const httpContext = context.switchToHttp();
    const req = httpContext.getRequest<Request>();

    const sessionId = this.userSessionCookie.get(req);
    if (!sessionId) throw new UnauthorizedException('Authentication required.');

    const userSession =
      await this.availableUserSessionProvider.handle(sessionId);
    if (!userSession)
      throw new UnauthorizedException('Authentication required.');

    req.userSession = userSession;

    return true;
  }
}

NestJS provides Guards to protect routes. In the context of DDD, it might be more accurate to say that it protects application services rather than individual routes, but actually it is very useful.

Get the session ID from the cookie.
Obtain available user session information from the session ID.
Attach user session information to the HTTP request context.

If any of these steps fail, an UnauthorizedException will be thrown.

Login Controller

Now that the necessary shared resources are available, we'll create controllers on a path-by-path basis.

@UseFilters(...filters)
@Controller('login')
export class LoginController {
  constructor(
    private readonly loginUseCase: LoginUseCase,
    private readonly userSessionCookie: UserSessionCookie,
  ) {}

  @ApiOkResponse()
  @Post()
  @HttpCode(200)
  async login(
    @Body()
    request: LoginRequest,
    @Res()
    response: Response,
  ) {
    const { sessionId } = await this.loginUseCase.handle({
      emailAddress: request.emailAddress,
    });

    this.userSessionCookie.set(response, sessionId);

    response.send();
  }
}

Upon a successful login use case, we store the session ID in the cookie.

Task Controller

@UseFilters(...filters)
@UseGuards(AuthGuard)
@Controller('tasks')
export class TaskController {
  constructor(
    private readonly findTasksUseCase: FindTasksUseCase,
    private readonly findTaskUseCase: FindTaskUseCase,
    private readonly createTaskUseCase: CreateTaskUseCase,
    private readonly addCommentUseCase: AddCommentUseCase,
    private readonly assignUserUseCase: AssignUserUseCase,
  ) {}

  @ApiOkResponse({ type: [TaskListItem] })
  @Get()
  async find(): Promise<TaskListItem[]> {
    const { tasks } = await this.findTasksUseCase.handle();

    return tasks;
  }

  @ApiOkResponse({ type: TaskDetails })
  @Get(':id')
  async findOne(@Param('id') id: string): Promise<TaskDetails> {
    const { task } = await this.findTaskUseCase.handle({ id });

    return {
      ...task,
      comments: task.comments.map((comment) => ({
        ...comment,
        postedAt: new Date(
          comment.postedAt.year,
          comment.postedAt.month - 1,
          comment.postedAt.date,
          comment.postedAt.hours,
          comment.postedAt.minutes,
        ).toLocaleString(),
      })),
    };
  }

  @ApiCreatedResponse({ type: TaskCreatedId })
  @Post()
  async create(
    @Body()
    request: CreateTaskRequest,
  ): Promise<TaskCreatedId> {
    const { id } = await this.createTaskUseCase.handle({
      taskName: request.name,
    });

    return {
      id,
    };
  }

  @ApiNoContentResponse()
  @Put(':id/comment')
  @HttpCode(204)
  async addComment(
    @Param('id') id: string,
    @Body()
    request: AddCommentRequest,
    @Req()
    { userSession }: Request,
  ) {
    await this.addCommentUseCase.handle({
      taskId: id,
      userSession: userSession,
      comment: request.comment,
    });
  }

  @ApiNoContentResponse()
  @Put(':id/assign')
  @HttpCode(204)
  async assignUser(
    @Param('id') id: string,
    @Body()
    request: AssignUserRequest,
  ) {
    await this.assignUserUseCase.handle({
      taskId: id,
      userId: request.userId,
    });
  }
}

All endpoints under /tasks are protected by the AuthGuard.
This controller executes use cases based on the path and HTTP method, returning appropriate responses to the user.
There are some user interface validation implemented.

export class CreateTaskRequest {
  @IsString()
  @MinLength(1)
  @ApiProperty()
  readonly name!: string;
}

This is the request body when creating a new task. The IsString decorator provided by class-validator rejects all types other than strings, including undefined or null.
The task name value object does not consider the possibility of values other than strings.

export class TaskName {
  constructor(value: string) {
    if (value.length > TaskName.TASK_NAME_CHARACTERS_LIMIT) {
      throw new TaskNameCharactersExceededException(
        TaskName.TASK_NAME_CHARACTERS_LIMIT,
      );
    }
    this._value = value;
  }
}

Implementing extremely defensive validations as shown below not only makes the domain object unnecessarily complex but also makes the actual business rules less clear.

constructor(value: string) {
  if (value === undefined) {
    throw new UnexpectedDomainException();
  }
  if (value === null) {
    throw new UnexpectedDomainException();
  }
  if (typeof value !== 'string') {
    throw new UnexpectedDomainException();
  }
  if (value.length === 0) {
    throw new UnexpectedDomainException();
  }
  if (value.length > TaskName.MAX_TASK_NAME_LENGTH) {
    throw new TaskNameCharactersExceededException(
      TaskName.TASK_NAME_CHARACTERS_LIMIT,
    );
  }
  this._value = value;
}

In the presentation layer, we perform coarse-grained validation, protecting the domain and application layers.
Note that introducing business rule validation in the presentation layer has both pros and cons, but it is not recommended in IDDD.

The kinds of validation found in the User Interface are not the kinds that belong in the domain model (only). As discussed in Entities (5), we still want to limit coarse-grained validations that express deep business knowledge only to the model.
(Implementing Domain-Driven Design)

User Creation Commander

The authority and method for creating users have not been decided yet. However, for now:

The application runs on a private server accessible only to some administrators.
Taking advantage of this, administrators log in to the server and create users via the command line using Nest Commander.

@Command({
  name: 'CreateUser',
  description: 'Create user by name and email address.',
})
export class CreateUserCommander extends CommandRunner {
  constructor(private readonly createUserUseCase: CreateUserUseCase) {
    super();
  }

  async run(nameAndEmailAddress: string[]) {
    const [name, emailAddress] = nameAndEmailAddress;

    const { id } = await this.createUserUseCase.handle({
      name,
      emailAddress,
    });
    Logger.log(`User successfully created. id: ${id}`);
  }
}

It passes the parameters received from the input stream to the create user use case.
(Command Example)

yarn start:commander CreateUser Michael test@example.com

Application services are designed to be independent of a specific user interface, so they can be flexibly adapted to meet your needs.

Infrastructure Layer

In this layer, we will create the concrete implementations requested by the Domain and Application layers.

ID Factories

export class TaskIdUuidV4Factory implements TaskIdFactory {
  handle() {
    return new TaskId(v4());
  }
}

export class UserIdUuidV4Factory implements UserIdFactory {
  handle() {
    return new UserId(v4());
  }
}

export class CommentIdUuidV4Factory implements CommentIdFactory {
  handle() {
    return new CommentId(v4());
  }
}

It has been decided to use uuid Version 4 for all of them. Noteworthy is the CommentId, which serves as the identifier for entities within the boundary, meaning local identifiers. For this case, there is no necessity to use uuid.
Evans used positions such as front-left, rear-left, front- right, and rear-right to identify the wheels of a car. However, unlike wheels, no straightforward, real-world, understandable means of identification for CommentId came to my mind, so the uuid framework was adopted as a convenient and easy generation method.

User Session In-Memory Storage

export class UserSessionInMemoryStorage implements UserSessionStorage {
  private readonly value: Map<SessionId, UserSession> = new Map();

  async get(sessionId: SessionId) {
    const userSession = this.value.get(sessionId);

    return userSession;
  }

  async set(userSession: UserSession) {
    const sessionId = Math.random().toString();
    this.value.set(sessionId, userSession);

    return sessionId;
  }
}

This is the implementation class for user session storage. At the current stage, the actual storage to be used has not been determined. For now, an in-memory storage is defined for debugging and testing purposes. The session ID is generated as a simple random number for now.

Data Model & OR Mapper

We decided to use MySQL for a database. and TypeOrm for ORM. The ER diagram is provided below.

For example, the task_assignments table holds information about user assignments to tasks. While in DDD, there is a pattern to design denormalized tables that reflect the structure of domain objects more directly, but this time, a more conventional table design was chosen.
TypeOrm models:

Task TypeORM Repository

export class TaskTypeormRepository implements TaskRepository {
  constructor(
    @InjectRepository(TaskTypeormModel)
    private readonly taskRepository: Repository<TaskTypeormModel>,
    @InjectRepository(TaskAssignmentTypeormModel)
    private readonly taskAssignmentRepository: Repository<TaskAssignmentTypeormModel>,
    @InjectRepository(TaskCommentTypeormModel)
    private readonly taskCommentRepository: Repository<TaskCommentTypeormModel>,
  ) {}

  async insert(task: Task) {
    await this.taskRepository.save({
      id: task.id.value,
      name: task.name.value,
      taskAssignment: task.userId && {
        taskId: task.id.value,
        userId: task.userId.value,
      },
      taskComments: task.comments.value.map((comment) => ({
        id: comment.id.value,
        userId: comment.userId.value,
        content: comment.content,
        postedAt: comment.postedAt,
      })),
    });
  }

  async update(task: Task) {
    await this.taskRepository.update(task.id.value, { name: task.name.value });

    await this.taskAssignmentRepository.delete({ taskId: task.id.value });
    task.userId &&
      (await this.taskAssignmentRepository.save({
        taskId: task.id.value,
        userId: task.userId.value,
      }));

    await this.taskCommentRepository.delete({ taskId: task.id.value });
    await this.taskCommentRepository.save(
      task.comments.value.map((comment) => ({
        id: comment.id.value,
        userId: comment.userId.value,
        content: comment.content,
        postedAt: comment.postedAt,
        taskId: task.id.value,
      })),
    );
  }

  async find() {
    const tasks = await this.taskRepository.find({
      relations: {
        taskAssignment: true,
        taskComments: true,
      },
    });
    return tasks.map((task) =>
      Task.reconstitute(
        new TaskId(task.id),
        new TaskName(task.name),
        task.taskComments.map(
          (taskComment) =>
            new Comment(
              new CommentId(taskComment.id),
              new UserId(taskComment.userId),
              taskComment.content,
              taskComment.postedAt,
            ),
        ),
        task.taskAssignment?.userId && new UserId(task.taskAssignment.userId),
      ),
    );
  }

  findOneById () ...
}

This class is responsible for persisting and reconstituting the task aggregate root.
The early generated entity ID is directly assigned as the primary key. However, using a UUID directly as a primary key can adversely affect performance in the case of InnoDB. Especially in cases where handling vast amounts of data, or in practical scenarios, it is advisable to assign the early-generated ID to a different column, such as public_id, and use an auto-incrementing sequential number as the primary key.
In the update method, all data corresponding to the child objects of the aggregate are deleted before being added again. While other approaches, such as adding only the necessary data or deleting only the data that needs to be removed, are possible, deleting and re-adding data is still a simpler method.

Find Tasks TypeORM Query Service

export class FindTasksTypeormQueryService implements FindTasksQueryService {
  constructor(private readonly dataSource: DataSource) {}

  async handle() {
    const tasks = await this.dataSource.query<
      { id: string; name: string; userName?: string }[]
    >(
      'SELECT tasks.id as id, tasks.name as name, users.name as userName FROM tasks LEFT JOIN task_assignments ON task_assignments.task_id = tasks.id LEFT JOIN users ON users.id = task_assignments.user_id',
    );

    return { tasks };
  }
}

This is the implementation of a query service optimized for retrieving a list of tasks. Queries are run directly via TypeORM DataSource. It selects only the necessary columns.

Thank you

If there is a next time, I would like to summarize about transactions and consistency.

Resources

[DDD] Tactical Design Patterns Part 2: Application Layer

minericefield — Tue, 16 Jan 2024 14:56:17 +0000

I will be applying Domain-Driven Design (DDD) tactical design patterns in this article.
I'm sorry. I'm not good at English.
It is divided into the following sections:

Domain Layer
Application Layer (this article)
Presentation/Infrastructure Layer
Consistency

To keep the description of source code in the article compact, I will be implementing it from a bottom-up approach.

GitHub Repository

https://github.com/minericefield/ddd-onion-lit

Please refer to the beginning of Part 1 for other details regarding the architecture and themes. I'll also attach a use case model diagram related to the main topic of the application layer here.

Application Layer

The main responsibility of the application layer is to coordinate the flow of scenarios while delegating business logic to domain objects.

Exceptions

Similar to the previous implementation from the bottom up, we will define shared exception classes that will serve as common objects.

export class NotFoundApplicationException extends Error {}

export class AuthenticationFailedApplicationException extends Error {}

export class UnexpectedApplicationException extends Error {}

Similar to domain layer exceptions, they do not depend on specific protocols. They are simple abstract exceptions that may occur in the application layer.

User Session

export type SessionId = string;
export type UserSession = {
  readonly userId: UserId;
};

export abstract class UserSessionStorage {
  abstract get(sessionId: SessionId): Promise<UserSession | undefined>;
  abstract set(userSession: UserSession): Promise<SessionId>;
}

For this project, I have defined resources related to sessions in the application layer. The reasons for this decision include:

There is no particularly complex business logic required for authentication and authorization.
From the domain perspective, any information that should be held in a session is considered acceptable.
Therefore, the focus is on designing for the realization of use cases.

The above considerations led to the definition in application/shared/user-session. Additionally, we assumed that this session is created only after successful authentication.
In the implementation of use cases that require authentication, there are two possible patterns: one that accepts a session ID and another that directly receives a user session.

UseCaseWithSessionId(sessionId?: SessionId) {
  const authenticatedUserSession = AvailableUserSessionAdapter.get(sessionId);

  if (authenticatedUserSession) {
    // do something
  } else {
    // do something
  }
}

UseCaseWithAuthenticatedUserSession(authenticatedUserSession: UserSession) {
  // do something
}

This time, I decided to implement use cases based on the latter pattern, assuming that the user is already logged in, and a valid user session is directly provided. The reasons for this choice include:

The core concern of this product is the user's activities related to tasks, and the authentication requirements are relatively simple.
- There are no specific behaviors for roles or non-logged-in states.
- The specification is simple: if not logged in, no operations can be performed.
Keeping use cases simple for such basic requirements is preferable.

While there might be concerns about the concept of Session itself being impure for the application layer, it is acceptable since Session is nothing more than an abstract concept representing a maintains of connections. So having it in the application layer won't be a problem.

Application Services

Now that we have prepared shared objects, let's proceed to implement individual application services. Since there are similar implementations, I'll provide an introduction to just a few.

Find Users Use Case

export class FindUsersUseCaseResponseDto {
  readonly users: {
    id: string;
    name: string;
    emailAddress: string;
  }[];

  constructor(users: User[]) {
    this.users = users.map(({ id, name, emailAddress }) => ({
      id: id.value,
      name: name,
      emailAddress: emailAddress.value,
    }));
  }
}

export class FindUsersUseCase {
  constructor(private readonly userRepository: UserRepository) {}

  async handle(): Promise<FindUsersUseCaseResponseDto> {
    const users = await this.userRepository.find();

    return new FindUsersUseCaseResponseDto(users);
  }
}

I have implemented the simple use case for retrieving a list of users. It involves fetching a set of users, repackaging them into a DTO, and returning them. The repackaging is not mandatory; you can return domain objects directly. However, for this time, I adhere to the policy of always repackaging the return values from use cases into DTOs (not exposing domain objects to use case clients).

Increasing Layer Cohesion

The primary reason for introducing the rule of repackaging into DTOs is to avoid the application service clients calling the behavior of domain objects. The responsibility of invoking the behavior of domain objects lies within the application layer. Strictly separating responsibilities across layers and increasing the cohesion of layers is crucial.
The following example illustrates an inappropriate implementation that arose from the practice of exposing domain objects.

"If there is a behavior to format the posting date that can be called in the presentation layer, it would be convenient." This kind of thinking can lead to a violation of the responsibility of the domain layer.

class Comment {
  constructor(
    readonly postedAt: Date,
  ) {}

  get postedAtForEndUser() {
    return this.postedAt.toLocaleString();
  }
}

Calling the behavior of domain objects in the presentation layer violates the responsibility of the presentation layer.

@Get()
async getComment() {
  const comment = GetCommentUseCase.handle();

  return {
    ...comment,
    postedAt: comment.postedAtForEndUser
  };
}

While the domain layer should focus on expressing business logic, there is a potential for developers to be tempted towards incorrect implementations like the one above
(Conversely, it is possible to opt for the operation of exposing domain objects, trusting the development team to have the self-discipline to avoid falling into such serious anti-patterns).

Let's consider another extreme example.

// application layer
ApplicationService () {
  domainObject.doA();

  return domainObject;
}

// presentation layer
ApplicationServiceClient () {
  domainObject = ApplicationService();

  domainObject.doB();

  return Response.NoContent
}

(Adopting a collection-oriented repository, assuming that changes to domainObject due to behavior calls will be persisted as is.)

This represents a state known as "low cohesion, high coupling". A single scenario realized by doA and doB cannot be completed within the application service. From the perspective of high coupling, the challenge of replacing ApplicationServiceClient is often a central concern. While this perspective is important, what's even more crucial is that implementing such code makes the system difficult to understand and challenging to maintain.
When discussing cohesion, the focus tends to be on the cohesion of specific classes or executable files. Certainly, striving to specialize classes for specific concerns and consolidating them into smaller units is a general best practice in object-oriented programming. It is something we should indeed strive for. However, in DDD, in addition to that, emphasizing the increase in cohesion of layers (modules) becomes extremely important.

Create User Use Case

export interface CreateUserUseCaseRequestDto {
  readonly name: string;
  readonly emailAddress: string;
}

export class CreateUserUseCaseResponseDto {
  readonly id: string;

  constructor(user: User) {
    this.id = user.id.value;
  }
}

We've defined a DTO similar to the find user use case. The response is set to return the ID of the newly created user.
One thing to note is the naming of CreateUserUseCaseRequestDto. It might feel odd to have "DTO" in the name for a request. This is simply because I wanted to manage both input and output in the same file named create-user.usecase.dto.ts and opted for the term "DTO" in the request to achieve that. Other alternatives like CreateUserCommand or CreateUserUseCaseRequestParams could also be suitable.

export class CreateUserUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly userIdFactory: UserIdFactory,
    private readonly userEmailAddressIsNotDuplicated: UserEmailAddressIsNotDuplicated,
  ) {}

  /**
   * @throws {InvalidUserEmailAddressFormatException}
   * @throws {DuplicatedUserEmailAddressException}
   */
  async handle(
    requestDto: CreateUserUseCaseRequestDto,
  ): Promise<CreateUserUseCaseResponseDto> {
    /**
     * Create userEmailAddress.
     */
    const userEmailAddress = new UserEmailAddress(requestDto.emailAddress);
    await this.userEmailAddressIsNotDuplicated.handle(userEmailAddress);

    /**
     * Create user.
     */
    const user = new User(
      await this.userIdFactory.handle(),
      requestDto.name,
      userEmailAddress,
    );

    /**
     * Store it.
     */
    await this.userRepository.insert(user);

    return new CreateUserUseCaseResponseDto(user);
  }
}

The main part of the use case is to check for duplicate email addresses and then persist the newly created user.
One aspect that we have to think is how exceptions from the domain layer are handled. The application service is responsible for handling domain exceptions, and there are various approaches:

Throwing them as is.
Repackaging and throwing as application layer exceptions.
Continuing the process in some way.
- (Ultimately, the result is likely to end up in the error path in most cases.)

For simplicity in this example, I chose to throw exceptions as a direct violation of business rules. I debated whether to explicitly use try catch but opted for simplicity in the sample code. I've documented the exceptions that might be thrown in the JsDoc (since exceptions thrown are not always immediately visible to the client).

Login Use Case

export interface LoginUseCaseRequestDto {
  readonly emailAddress: string;
}

export class LoginUseCaseResponseDto {
  constructor(readonly sessionId: SessionId) {}
}

Believe it or not, the current situation allows logging in only with an email address. Details regarding the password, such as formatting or encryption specifications, are not yet finalized, and modeling for it has been postponed.

export class LoginUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly userSessionStorage: UserSessionStorage,
  ) {}

  /**
   * @throws {AuthenticationFailedApplicationException}
   */
  async handle(
    requestDto: LoginUseCaseRequestDto,
  ): Promise<LoginUseCaseResponseDto> {
    /**
     * Create userEmailAddress.
     */
    let userEmailAddress: UserEmailAddress;
    try {
      userEmailAddress = new UserEmailAddress(requestDto.emailAddress);
    } catch (error: unknown) {
      if (error instanceof InvalidUserEmailAddressFormatException) {
        throw new AuthenticationFailedApplicationException('Login failed.', {
          cause: error,
        });
      }

      throw error;
    }

    /**
     * Find user.
     */
    const user =
      await this.userRepository.findOneByEmailAddress(userEmailAddress);
    if (!user) {
      throw new AuthenticationFailedApplicationException('Login failed.');
    }

    /**
     * Create session.
     */
    const sessionId = await this.userSessionStorage.set({
      userId: user.id,
    });

    return new LoginUseCaseResponseDto(sessionId);
  }
}

The flow is simple: upon a successful login, a session is created, and the session ID is returned to the use case client. The session ID itself is a general concept that doesn't depend on any specific technical details, allowing the use case client to handle it as needed based on its own implementation.
The part that might be confusing is the creation of the email address value object. In the context of the login scenario, an exception for email address format violation seems unnatural. Therefore, I've rethrown the format violation as an authentication failed exception for a more appropriate representation of the error.
On the other hand, you could delegate this responsibility to the use case client. Considering this as a presentation layer concern, especially in terms of how errors are presented to end-users, is also a valid perspective.
This time, I interpreted that in the login scenario, a format violation of the email address is simply an authentication failure, regardless of how the error is presented to the end user.

Create Task Use Case

export interface CreateTaskUseCaseRequestDto {
  readonly taskName: string;
}

export class CreateTaskUseCaseResponseDto {
  readonly id: string;

  constructor(task: Task) {
    this.id = task.id.value;
  }
}

export class CreateTaskUseCase {
  constructor(
    private readonly taskRepository: TaskRepository,
    private readonly taskIdFactory: TaskIdFactory,
  ) {}

  /**
   * @throws {TaskNameCharactersExceededException}
   */
  async handle(
    requestDto: CreateTaskUseCaseRequestDto,
  ): Promise<CreateTaskUseCaseResponseDto> {
    /**
     * Create task.
     */
    const task = Task.create(
      await this.taskIdFactory.handle(),
      new TaskName(requestDto.taskName),
    );

    /**
     * Store it.
     */
    await this.taskRepository.insert(task);

    return new CreateTaskUseCaseResponseDto(task);
  }
}

Creates a new task from the task name using Task.create and persists it.

Add Comment Use Case

export interface AddCommentUseCaseRequestDto {
  readonly taskId: string;
  readonly userSession: UserSession;
  readonly comment: string;
}

export class AddCommentUseCaseResponseDto {
  readonly id: string;

  constructor(comment: Comment) {
    this.id = comment.id.value;
  }
}

In this case, userSession is defined as input to identify the commenter.

export class AddCommentUseCase {
  constructor(
    private readonly taskRepository: TaskRepository,
    private readonly commentIdFactory: CommentIdFactory,
  ) {}

  /**
   * @throws {NotFoundApplicationException}
   * @throws {CommentNumberExceededException}
   */
  async handle(
    requestDto: AddCommentUseCaseRequestDto,
  ): Promise<AddCommentUseCaseResponseDto> {
    /**
     * Find task.
     */
    const task = await this.taskRepository.findOneById(
      new TaskId(requestDto.taskId),
    );
    if (!task) {
      throw new NotFoundApplicationException('Task not found.');
    }

    /**
     * Create comment.
     */
    const comment = new Comment(
      await this.commentIdFactory.handle(),
      requestDto.userSession.userId,
      requestDto.comment,
      new Date(),
    );

    /**
     * Add comment to task.
     */
    task.addComment(comment);

    /**
     * Store it.
     */
    await this.taskRepository.update(task);

    return new AddCommentUseCaseResponseDto(comment);
  }
}

Checks for the existence of the target task, adds a comment, and persists it.

Find Tasks Use Case

For the task list, we decide to display only ID, Task Name, and Assigned User Name.

export interface FindTasksUseCaseResponseDto {
  readonly tasks: {
    id: string;
    name: string;
    userName?: string;
  }[];
}

Now that we've defined the DTO, let's move on to implementing the use case. However, if we were to use only the repository, we'd need to retrieve each task and user separately. This would require mapping the user names assigned to each task. Concerns arise about decreased readability due to looping and potential performance issues due to unnecessary data retrieval.
To address this, we introduce a query service to retrieve only the necessary data.

Find Tasks Query Service

export abstract class FindTasksQueryService {
  abstract handle(): Promise<FindTasksQueryServiceResponseDto>;
}

export interface FindTasksQueryServiceResponseDto {
  readonly tasks: {
    id: string;
    name: string;
    userName?: string;
  }[];
}

Since the reference model is requested by individual use cases, it is defined in the application layer (it could also be defined in the same file as the use case). Although input for the query service is not defined in this case, query services are particularly useful for complex search requirements spanning multiple aggregates or implementing pagination.

export class FindTasksUseCase {
  constructor(private readonly findTasksQueryService: FindTasksQueryService) {}

  async handle(): Promise<FindTasksUseCaseResponseDto> {
    const { tasks } = await this.findTasksQueryService.handle();

    return { tasks };
  }
}

The use case simply calls the query service.

User Session Provider

export class AvailableUserSessionProvider {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly userSessionStorage: UserSessionStorage,
  ) {}

  async handle(sessionId: SessionId): Promise<UserSession | undefined> {
    const userSession = await this.userSessionStorage.get(sessionId);
    if (!userSession) {
      return;
    }

    if (!(await this.userRepository.findOneById(userSession.userId))) {
      return;
    }

    return userSession;
  }
}

This is responsible for retrieving a user session based on a session ID. It also performs a validity check on the associated user ID. While it doesn't represent a specific use case, it's deemed necessary as an application service.
In this implementation, the simplicity of the application layer is prioritized, and the need for authentication is considered implicit knowledge at the implementation level of each use case. Although it may not be apparent from the use case interface, it's expected that the use case client (presentation layer) uses this user session provider to protect the execution of use cases.

Resources

[DDD] Tactical Design Patterns Part 1: Domain Layer

minericefield — Tue, 16 Jan 2024 14:55:29 +0000

I will be applying Domain-Driven Design (DDD) tactical design patterns in this article.
I'm sorry. I'm not good at English.
It is divided into the following sections:

To keep the description of source code in the article compact, I will be implementing it from a bottom-up approach.

GitHub Repository

https://github.com/minericefield/ddd-onion-lit

Language & Framework

TypeScript & NestJS

Architecture

Onion Architecture

Situation

An organization has decided to create a task management application for internal use (though this situation is unusual to apply DDD).
Though focusing on tactical design patterns, I have prepared a simple use case diagram and a simple domain model diagram.

Something like a use case model diagram

Users can perform several basic operations on tasks. It may seem unusual, but I haven't included features such as changing the progress status of tasks or setting deadlines. I omitted them because it didn't appear there would be much to learn from implementing those features in the sample code.
Regarding the actor responsible for creating users, we don't have a clear understanding yet. For now, there is a consensus to avoid a situation where everyone can freely create users.
Agilely, we will proceed with the implementation while leaving notes and discussion memos in diagrams for undecided aspects. However, an unknown actor is a quite rare situation.

Something like a domain model diagram

I have documented various constraints, along with the behavior and multiplicity of each entity. The specification of limiting comments on a task to 20 may seem a bit unusual, but I included it as a valuable constraint to emphasize the learning theme.
Ideally, I would have liked to provide details about value objects, but I have omitted them this time.
The domain model diagram will be created after developing the use case diagram. This is because lacking a clear understanding of the use cases makes it challenging to conduct appropriate domain modeling. However, the representations in the domain model diagram will capture fundamental invariants that extend beyond specific use cases.

Directory Structure

While I'd like to proceed with the implementation starting from the domain layer, let's first check the directory structure to have a rough idea of the architecture.

src
 ┣ application
 ┃ ┣ auth
 ┃ ┣ shared
 ┃ ┣ task
 ┃ ┗ user
 ┣ domain
 ┃ ┣ shared
 ┃ ┣ task
 ┃ ┗ user
 ┣ infrastructure
 ┃ ┣ in-memory
 ┃ ┣ mysql
 ┃ ┗ uuid
 ┗ presentation
   ┣ http
   ┗ nest-commander

The structure follows an Onion Architecture ("presentation" can also be named as "user-interface").
Some may suggest organizing it in a feature-based slice when using NestJS (such as having src/task/domain or src/task/application). While that is also a valid approach, this time I referred to the module structure of IDDD for inspiration.
com.saasovation.agilepm.domain.model.product
No concepts of organizations like com.saasovation or context boundaries like agilepm are present. If I were to insist, the product aligns directly with the context of task management. What I took inspiration from are the modules that follow, such as domain and application. Within these, specific top-level module and aggregates come into play.

Domain Layer

This is where we express the business logic.

Exceptions

I've defined common exception classes for the domain layer.

export class ValidationDomainException extends Error {}

export class UnexpectedDomainException extends Error {}

For now, I've introduced validation and unexpected exceptions. These are simple extensions of standard exceptions. Domain layer exceptions primarily point to violations of business rules.
While these exceptions don't have a direct relationship with the domain model, they will become necessary in the implementation of the domain layer. These are concepts that do not depend on specific protocols etc.
Unexpected exceptions might be used alongside defensive programming practices. However, particularly in the domain layer, it's crucial to avoid being overly defensive, as it could blur the representation of business rules. Their usage might be quite limited.

User Email Address Value Object

export class UserEmailAddress {
  private static readonly USER_EMAIL_ADDRESS_PATTERN =
    /^[a-zA-Z0-9_+-]+(\.[a-zA-Z0-9_+-]+)*@([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]*\.)+[a-zA-Z]{2,}$/;

  private _value: string;

  constructor(value: string) {
    if (!UserEmailAddress.USER_EMAIL_ADDRESS_PATTERN.test(value)) {
      throw new InvalidUserEmailAddressFormatException();
    }
    this._value = value;
  }

  get value() {
    return this._value;
  }
}

export class InvalidUserEmailAddressFormatException extends ValidationDomainException {
  constructor() {
    super(`Invalid email address format.`);
  }
}

I have created a value object for the user's email address. This is a minimal implementation that provides only validation and encapsulation of the value. The constructor is made public as is.

Let's go through this implementation because there seem to be some strange points.

Is a private setter necessary for the value?

In IDDD, a private setter was provided for each property of domain objects, and validation was performed within the setter (self-delegation). Especially in the case of domain objects with multiple constructors or properties, encapsulating the constraints of each property within setters through self-delegation would result in a simpler and more extensible implementation.
This time, I didn't provide a private setter because there wasn't a particular advantage to self-delegation, and I opted for simplicity by only providing a constructor.

Is a specific exception class necessary?

I provided a specific exception class (InvalidUserEmailAddressFormatException) to indicate a format violation of the email address. However, this is not a mandatory concept in DDD.
I just referenced the implementation of creating specific exception classes for particular exceptions from the "Good Code, Bad Code: Think like a software engineer".

Specific and descriptive exception classes contribute to improvement of readability and error identification.
They allow encapsulation of behavior specific to individual exceptions.
- Setting error messages.
- Providing metadata useful for debugging.
- (However, be careful not to make it feel unnatural in the representation of the domain layer).

Furthermore, particularly for domain layer exceptions, it's beneficial to have them easily identifiable. This is because many use cases invoke behaviors from multiple domain objects. While it's not advisable to be overly concerned about external layers when implementing the domain layer, providing specific exception classes enables use cases or their clients to flexibly respond based on the received exception.

Is the term "Validation" appropriate?

The InvalidUserEmailAddressFormatException extends ValidationDomainException, but the term "Validation" might not be precisely suitable. In IDDD, validation was categorized as guards for each property, distinctly separated from validation. A guard, in this case, is an assertion about the validity of each parameters, and the following code snippet aligns with this concept:

if (!UserEmailAddress.USER_EMAIL_ADDRESS_PATTERN.test(value)) {
  throw new InvalidUserEmailAddressFormatException();
}

In IDDD, exceptions thrown by guards were IllegalArgumentException, indicating that the argument is invalid. The concept of validation, did not appear here.
Validation typically refers to cross-object validation, such as deferred validation traversing all properties within an entity. This validation's implementation details are placed as a separate resource, distinct from domain objects.
But this time, I have chosen a simple approach, broadly expressing any concept that validates individual values or other invariants as "Validation". Additionally, I have not included what is conventionally referred to as a validator in IDDD (In IDDD, a validator, unlike guards that immediately throw exceptions, traverses the object, aggregates all errors, and notifies them collectively).

A few other implementation patterns

Equality Check

Implementing the behavior of equality checking is a common practice, and it comes with several benefits:

Clients can confirm equality without needing in-depth knowledge of the internal structure of the value object.
Maintainability will be raised.
By overriding comparison operators, you can express comparisons between value objects naturally (Not available in TypeScript).
- Something like FooValueObjectA == FooValueObjectB.
- Value objects represent conceptually unified "values," and such a representation feels more natural.

While the email address created in this example is a simple value object with only one primitive property, the format of value objects can vary.

class Name {
  constructor(
    private readonly firstName: string,
    private readonly lastName: string,
  ) {}

  equals(name: Name) {
    return this.firstName === name.firstName && this.lastName === name.lastName;
  }
}

If clients repeatedly reference properties directly for comparisons, there's a risk of oversight when adding properties to the value object. In contrast, by using equals, modifications can be consolidated in one place.
(For example, if a middle name is added)

class Name {
  constructor(
    private readonly firstName: string,
    private readonly lastName: string,
    private readonly middleName: string,
  ) {}

  equals(name: Name) {
    return (
      this.firstName === name.firstName &&
      this.lastName === name.lastName &&
      this.middleName === name.middleName // Compare by middlename.
    );
  }
}

This time, I have only implemented the minimum behavior required in the source for value objects. However, equality verification based on property (and type) comparison is one of the fundamental characteristics of value objects. In practice, you might implement the behavior of equality verification, e.g., by preparing a layer supertype with equality verification behavior.

Avoiding Validation during Reconstitution

During creation of a new object, a FACTORY should simply balk when an invariant isn’t met, but a more flexible response may be necessary in reconstitution. If an object already exists somewhere in the system (such as in the database), this fact cannot be ignored.
(Domain-Driven Design: Tackling Complexity in the Heart of Software)

Addressing this issue can be approached in various ways. One example is delegating the responsibility of validation to the factory.

class UserEmailAddress {
  private static readonly USER_EMAIL_ADDRESS_PATTERN =
    /^[a-zA-Z0-9_+-]+(\.[a-zA-Z0-9_+-]+)*@([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]*\.)+[a-zA-Z]{2,}$/;

  constructor(readonly value: string) {}

  static assertEmailAddressPatternValid(value: string) {
    if (!UserEmailAddress.USER_EMAIL_ADDRESS_PATTERN.test(value)) {
      throw new InvalidUserEmailAddressFormatException();
    }
  }
}

class CreateUser {
  handle(emailAddress: string) {
    UserEmailAddress.assertEmailAddressPatternValid(emailAddress);

    return new User(new UserEmailAddress(emailAddress));
  }
}

class ReconstituteUser {
  handle(emailAddress: string) {
    return new User(new UserEmailAddress(emailAddress));
  }
}

In the reconstitution factory (ReconstituteUser), validation is omitted.
Alternatively, each value object class itself can hold factory interfaces for both creation and reconstitution.

class UserEmailAddress {
  private static readonly USER_EMAIL_ADDRESS_PATTERN =
    /^[a-zA-Z0-9_+-]+(\.[a-zA-Z0-9_+-]+)*@([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]*\.)+[a-zA-Z]{2,}$/;

  private constructor(readonly value: string) {}

  static create(value: string) {
    if (!UserEmailAddress.USER_EMAIL_ADDRESS_PATTERN.test(value)) {
      throw new InvalidUserEmailAddressFormatException();
    }

    return new UserEmailAddress(value);
  }

  static reconstitute(value: string) {
    return new UserEmailAddress(value);
  }
}

However, the reconstitute as an interface within the value object class itself may feel somewhat impure. It might make sense for aggregate roots to have an interface called reconstitute. This is because reconstitution is basically the concept of reassembling aggregate roots. The distinction between the creation and reconfiguration of objects inside the boundary is just an implementation that may be needed in the process, and it may be prohibited to have it as an interface for the value object class itself.
In any case, it may be necessary to consider validation during reconstitution.

(The term "invariant")

While the email address format, as seen in my example, can be broadly regarded as part of the invariants, the term "invariant" is less commonly used in this this kind of context. It is more frequently employed when describing intricate business rules that need to be consistently maintained within an aggregate.

User ID Value Object

Next, I created a value object for the user ID.

export class UserId {
  _userIdBrand!: never;

  constructor(readonly value: string) {}
}

For now, the only expectation for a user ID is uniqueness; there are no other specific requirements.
In languages with a structural type system, like TypeScript, it can be beneficial to use a brand property for such simple entity IDs.
In IDDD, the generation of user IDs was handled by the Repository. The implementation class of the Repository can generate IDs using specific persistence mechanisms or data store functions or as seen in the sample code, use a bulit-in module. But some may find it slightly awkward that a LevelDBRepository doesn't utilize LevelDB functionalities in this approach. And it may be preferable that the return value of the repository always be the aggregate root.
This time, I have opted to generate IDs through a factory.

export abstract class UserIdFactory {
  abstract handle(): UserId;
}

The implementation of the UserIdFactory could be functionalities such as RDB features or UUID frameworks. This allows choosing the most suitable implementation for the requirements.

class RdbUserIdFactory implements UserIdFactory {
  handle(): UserId {
    // Use RDB
  }
}

class UuidFrameworkUserIdFactory implements UserIdFactory {
  handle(): UserId {
    // Use UUID framework
  }
}

User Aggregate Root

Now that the internal objects within the boundary are in place, let's create the aggregate root.

export class User {
  constructor(
    readonly id: UserId,
    readonly name: string,
    readonly emailAddress: UserEmailAddress,
  ) {}
}

Currently, the user has no specific behavior. A user is an entity with an identifier called "id" and also serves as the aggregate root. The constructor is public and expects domain objects to be passed directly. Therefore, external resources outside the aggregate will create internal objects within the boundary and pass them to the exposed constructor. This time, for simple aggregate roots like this, we generate them following this construction approach.

User Repository

Now that we have the aggregate root, let's create the corresponding repository. Several necessary interfaces are declared:

export abstract class UserRepository {
  abstract insert(user: User): Promise<void>;
  abstract find(): Promise<User[]>;
  abstract findOneById(id: UserId): Promise<User | undefined>;
  abstract findOneByEmailAddress(
    userEmailAddress: UserEmailAddress,
  ): Promise<User | undefined>;
}

This abstract class outlines the essential behavior that the UserRepository should provide.

Email Address Duplication Check Domain Service

Confirming duplication by asking the email address or the user itself is not feasible as a modeling approach. Users don't have knowledge of email addresses other than their own, nor should they.

export class UserEmailAddressIsNotDuplicated {
  constructor(private readonly userRepository: UserRepository) {}

  /**
   * @throws {DuplicatedUserEmailAddressException}
   */
  async handle(userEmailAddress: UserEmailAddress) {
    if (await this.userRepository.findOneByEmailAddress(userEmailAddress)) {
      throw new DuplicatedUserEmailAddressException();
    }
  }
}

export class DuplicatedUserEmailAddressException extends ValidationDomainException {
  constructor() {
    super(`User email address is duplicated.`);
  }
}

Email address duplication confirmation is expressed through a domain service (defining only the abstraction is also an option). Clients will use this domain service to check for duplication before generating the user aggregate root.
It's common to see domain services that return a boolean result for duplication checks. While Evans suggests that domain services should return domain objects, in cases like this domain service, returning a boolean might be more natural and straightforward as an interface.
The reason I chose to throw an exception in this implementation is to express that email address duplication is a clear violation of a business rule. Using a boolean return value might lack expressive power in representing a business rule violation, and it might force the client side into a somewhat procedural implementation.
On the other hand, using void is also somewhat awkward. Therefore, considering:

A Result type to represent business rule violations
A some kind of universal domain object to represent the existence or duplication status

could be a good alternative for return value.

Enforcing Invariants with a Factory

It might be an option to generate the user aggregate root through a factory, enforcing invariants.

export class UserFactory {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly userIdFactory: UserIdFactory,
  ) {}

  async handle(name: string, emailAddress: string) {
    const userEmailAddress = new UserEmailAddress(emailAddress);
    if (await this.userRepository.findOneByEmailAddress(userEmailAddress)) {
      throw new DuplicatedUserEmailAddressException();
    }

    const userId = this.userIdFactory.handle();

    return new User(userId, name, userEmailAddress);
  }
}

I've created a concrete factory that focuses on generating a new user based on a name and email address for simplicity. In real practice, factories are more often abstracted to handle tasks like ID generation and querying persistence infrastructure.
The reasons for introducing a factory and the implementation methods vary, but enforcing invariants is a crucial theme in the context of factories. It's worth noting that there are two main types of factories:

Factories representing ubiquitous language
Factories necessary for implementation

In this case, the UserFactory falls into the category of Factories necessary for implementation.
In the case of the former domain service, the knowledge that "email addresses must not be duplicated" is appropriately expressed and encapsulated in the domain layer. However, the situation of "checking for duplication in the domain service before generating a user" still represents a leakage of responsibility from the domain layer, and clients are forced into an unstable procedural implementation. By encapsulating the generation process, including enforcing invariants, within the factory, such situations can be avoided.

(Protecting Access Using Modules)

Modules help organize related concepts into easily understandable structures, reduce the coupling between modules, and provide functionality to restrict access to available resources. In Java, modules can be implemented using packages, and in C#, using namespaces. However, TypeScript doesn't have these features. Ideally, we would like to define modules and restrict the invocation of aggregate root generation methods so that they can only be called from factories.

Next, I will create the domain.task module.

Comment ID Value Object

export class CommentId {
  _commentIdBrand!: never;

  constructor(readonly value: string) {}
}

export abstract class CommentIdFactory {
  abstract handle(): CommentId;
}

Same implementation as UserId.

Comment Entity

export class Comment {
  constructor(
    readonly id: CommentId,
    readonly userId: UserId,
    readonly content: string,
    readonly postedAt: Date,
  ) {}
}

Comments have a UserId (objects within the boundary can hold references to other aggregate roots). Expressing the association with the aggregate root through ID references is a technique introduced in IDDD. It can make entities more compact and easy to handle while also contributing to performance improvements.
Here, a dependency across modules has occurred (although the module itself has not been implemented in TypeScript, a directory structure resembling modules is used for representation).

import { UserId } from '../../user/user-id.value-object';

However, this is an acceptable dependency. There are some alternatives, but none of them are recommended. Let's briefly go through them.

Place UserId in shared

Placing any shared object in the shared directory can make it unclear what concept the resource originates from. UserId should be a resource explicitly included in the user module. The shared directory is intended for more abstract shared objects or universal concepts that are not related to a specific domain.

Place a concrete generic EntityId in shared and have each entity use it directly

Something like this.

class EntityId {
  constructor(readonly value: string) {}
}

class User {
  constructor(
    readonly id: EntityId,
  ) {}
}

class Comment {
  constructor(
    readonly userId: EntityId,
  ) {}
}

However, couldn’t the team have achieved loose coupling among these elements by the use of a generic identity type,
(...) True, the team could have achieved looser coupling. However, it would also have opened up the potential for bugs in code where each Identity type could not be distinguished from the others.
(Implementing Domain-Driven Design)

As mentioned in IDDD, we might pass the wrong type of ID.

Considering the reasons mentioned above, it's acceptable to directly couple UserId.

Comment Entity First-Class Collection

export class Comments {
  private static readonly COMMENT_NUMBER_LIMIT = 20;

  constructor(private readonly _value: Comment[]) {}

  get value() {
    return [...this._value].sort(
      (commentA, commentB) =>
        -(commentA.postedAt.getTime() - commentB.postedAt.getTime()),
    );
  }

  add(comment: Comment) {
    if (this._value.length >= Comments.COMMENT_NUMBER_LIMIT) {
      throw new CommentNumberExceededException(Comments.COMMENT_NUMBER_LIMIT);
    }

    return new Comments([...this._value, comment]);
  }
}

export class CommentNumberExceededException extends ValidationDomainException {
  constructor(commentNumberLimit: number) {
    super(`Can't add more than ${commentNumberLimit} comments.`);
  }
}

The invariant conditions related to the collection of comments can be directly expressed by the task entity. However, encapsulating them in a first-class collection can achieve better cohesion, resulting in a simpler and more understandable implementation of the task entity.

Always want to see the list of comments in descending order

get value() {
  return [...this._value].sort(
    (commentA, commentB) =>
      -(commentA.postedAt.getTime() - commentB.postedAt.getTime()),
  );
}

In general, we prefer not to express display-related responsibilities in domain objects. However, in this case, the requirement is to always have comments in descending order, not limited to a specific user interface. And with minimal control over the order. For tasks like transforming domain objects into a specific structure that can be exposed externally or converting them into a format that is easy for specific end-users to read, these responsibilities might belong to DTOs or the presentation layer.
This time, I chose to implement the requirement for descending order directly within the first-class collection, treating it as a high-level requirement outlined on the domain model diagram.
There might be feeling some resistance to giving get value such behavior, so it could also be a good idea to define other getters.

get value() {
  return [...this._value];
}

get inDescendingOrder() {
  return [...this._value].sort(
    (commentA, commentB) =>
      -(commentA.postedAt.getTime() - commentB.postedAt.getTime()),
  );
}

The maximum number of comments for one task is 20

add(comment: Comment) {
  if (this._value.length >= Comments.COMMENT_NUMBER_LIMIT) {
    throw new CommentNumberExceededException(Comments.COMMENT_NUMBER_LIMIT);
  }

  return new Comments([...this._value, comment]);
}

If there are already 20 comments, an exception is thrown when trying to add a new one.

Task Name Value Object

export class TaskName {
  private static readonly TASK_NAME_CHARACTERS_LIMIT = 50;

  private _value: string;

  constructor(value: string) {
    if (value.length > TaskName.TASK_NAME_CHARACTERS_LIMIT) {
      throw new TaskNameCharactersExceededException(
        TaskName.TASK_NAME_CHARACTERS_LIMIT,
      );
    }
    this._value = value;
  }

  get value() {
    return this._value;
  }
}

export class TaskNameCharactersExceededException extends ValidationDomainException {
  constructor(taskNameCharactersLimit: number) {
    super(
      `Task name can't be longer than ${taskNameCharactersLimit} characters.`,
    );
  }
}

If the task name exceeds 50 characters, an exception will be thrown.

Task ID Value Object

export class TaskId {
  _taskIdBrand!: never;

  constructor(readonly value: string) {}
}

export abstract class TaskIdFactory {
  abstract handle(): TaskId;
}

Same implementation as other entity ids.

Task Aggregate Root

export class Task {
  private constructor(
    readonly id: TaskId,
    readonly name: TaskName,
    private _comments: Comments,
    private _userId?: UserId,
  ) {}

  get comments() {
    return this._comments.value;
  }

  get userId() {
    return this._userId;
  }

  static create(id: TaskId, name: TaskName) {
    return new Task(id, name, new Comments([]));
  }

  static reconstitute(
    id: TaskId,
    name: TaskName,
    comments: Comment[],
    userId?: UserId,
  ) {
    return new Task(id, name, new Comments(comments), userId);
  }

  addComment(comment: Comment) {
    this._comments = this._comments.add(comment);
  }

  assignUser(userId: UserId) {
    this._userId = userId;
  }
}

The Task aggregate root encompasses various behaviors that align with the ubiquitous language:

Adding a comment - addComment
Assigning a user - assignUser

The constructor is made private, and interfaces for creation and reconstitution are provided:

Creation - static create
- No comments
- Not assigned to anyone
Reconstitution - static reconstitute
- This requires self-discipline, as it should ideally be used only by the repository.

Task Repository

export abstract class TaskRepository {
  abstract insert(task: Task): Promise<void>;
  abstract update(task: Task): Promise<void>;
  abstract find(): Promise<Task[]>;
  abstract findOneById(id: TaskId): Promise<Task | undefined>;
}

A repository corresponding to the aggregate root is defined for tasks.