liveBook · Manning

Error type

As explained in Clean Applications with Hexagonal Architecture

An error represented by a distinct type so that its category and handling behavior are explicit.

A void command says it returns no data, but says nothing about failure; callers must discover exceptions elsewhere. Returning Either<Error, Void> makes command failures explicit, while queries can return Either<Error, R>. The command still returns no business data, preserving Command-Query Separation. section 4.0 section 4.3.1

Typed errors support explicit failure handling at two points:

  • Command validation can return an Error containing multiple validation failures, such as missing article and author IDs. section 4.3.3
  • A use-case handler can return success or a typed error while chaining repository and domain operations. section 4.4.1
Listing 4.8 PublishArticleCommand with full Error-based validation
public final class PublishArticleCommand implements Command {
 
  private final String articleId;
  private final String authorId;
 
  private PublishArticleCommand(
    final String articleId, #A
    final String authorId) {
    this.articleId = articleId;
    this.authorId = authorId;
  }
 
  public static Either<Error, PublishArticleCommand>
    validateThenCreate( #B
      final String articleId,
      final String authorId) {
      final List<ValidationError> errors = new ArrayList<>();
 
      if (articleId == null) errors.add(
        new ValidationError.Mandatory("articleId")); #C
      if (authorId == null) errors.add(
        new ValidationError.Mandatory("authorId"));
 
      return errors.isEmpty()
        ? Either.right(
            new PublishArticleCommand(articleId, authorId))
        : Either.left(
            new Error.ValidationErrors(errors)); #D
  }
 
  public String articleId() { return this.articleId; }
  public String authorId() { return this.authorId; }
 
}

The PublishArticleCommand listing shows validation failures collected and returned through Either<Error, PublishArticleCommand>. section 4.3.3

Listing 4.10 PublishArticleHandler implementing the use case directly
@ApplicationService #A
@RequiredArgsConstructor
final class PublishArticleHandler implements PublishArticleUseCase {
 
  private final ArticleRepository articleRepository; #B
 
  @Override
  public Either<Error, Void> handle(final PublishArticleCommand command) {
    return this.articleRepository
      .readById(command.articleId()) #C
    .flatMap(article -> article.publish(command.authorId())) #D
    .flatMap(article -> this.articleRepository.save(article)); #E
  }
 
}

The handler listing shows typed errors flowing through repository and domain operations to the caller. section 4.4.1

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Defines an Error hierarchy and demonstrates validation aggregation and handler propagation without detailing the hierarchy's full design.
Examples
Uses PublishArticleCommand validation for missing IDs and a publication handler that chains repository and domain operations.
What you can do after
Apply it via Vavr's Either to return explicit failures from commands and use-case handlers.
How it connects
Connects typed errors to Either, command-query separation, and use-case handlers.

Also explained in

Compare how 6 books explain error type →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.