Error Handling

Working with ValidationError, domain exceptions, and error handling patterns

ValidationError

ValidationError is the standard error type thrown when validation fails. It contains structured information about all validation issues.

import { ValidationError } from "@woltz/rich-domain";

try {
  const user = new User({ name: "", email: "invalid" });
} catch (error) {
  if (ValidationError.isValidationError(error)) {
    console.log(error.message);
    // "Validation failed: Name is required, Invalid email format"

    console.log(error.issues);
    // [
    //   { path: ["name"], message: "Name is required" },
    //   { path: ["email"], message: "Invalid email format" }
    // ]
  }
}

ValidationError API

Properties

interface ValidationError extends Error {
  name: "ValidationError";
  message: string; // Summary of all errors
  issues: ValidationIssue[]; // Detailed error list
}

interface ValidationIssue {
  path: string[]; // Field path (e.g., ["address", "city"])
  message: string; // Error message
}

Methods

getMessages()

Get all error messages as a flat array:

const messages = error.getMessages();
// ["Name is required", "Invalid email format", "Age must be positive"]

getFormattedErrors()

Get errors formatted for UI/API consumption:

const fieldErrors = error.getFormattedErrors();
// [
//   { path: "name", message: "Name is required" },
//   { path: "email", message: "Invalid email format" }
// ]

Use this for form field bindings. The path is a dot-joined string (empty string for global errors).

getErrorsForPath(path)

Get errors for a specific field:

const nameErrors = error.getErrorsForPath("name");
// [{ path: ["name"], message: "Name is required" }]

const addressCityErrors = error.getErrorsForPath(["address", "city"]);
// [{ path: ["address", "city"], message: "City is required" }]

hasErrorsForPath(path)

Check if a field has errors:

if (error.hasErrorsForPath("email")) {
  // Show email field error
}

toJSON()

Serialize for API responses:

const json = error.toJSON();
// {
//   name: "ValidationError",
//   message: "Validation failed: ...",
//   issues: [...]
// }

Static Methods

isValidationError(error)

Type-safe check that works across module boundaries:

try {
  // ...
} catch (error) {
  if (ValidationError.isValidationError(error)) {
    // error is typed as ValidationError
    console.log(error.issues);
  }
}

Always use ValidationError.isValidationError() instead of instanceof for reliable detection across module boundaries.

Throwing Validation Errors

In Hooks

Use the throwValidationError helper:

import { throwValidationError } from "@woltz/rich-domain";

rules: (entity) => {
  if (entity.price < 0) {
    throwValidationError("price", "Price cannot be negative");
  }
};

Manually

Create and throw directly:

import { ValidationError, createValidationIssue } from "@woltz/rich-domain";

// Single issue
throw new ValidationError([
  createValidationIssue("email", "Email already exists"),
]);

// Multiple issues
throw new ValidationError([
  createValidationIssue("email", "Email already exists"),
  createValidationIssue("username", "Username already taken"),
]);

// Nested path
throw new ValidationError([
  createValidationIssue(["address", "zipCode"], "Invalid ZIP code"),
]);

Non-Throwing Mode

Configure entities to collect errors instead of throwing:

class UserSafe extends Aggregate<UserProps> {
  protected static validation = {
    schema: userSchema,
    config: {
      onCreate: true,
      onUpdate: true,
      throwOnError: false, // Collect errors
    },
  };
}

const user = new UserSafe({ name: "", email: "invalid" });

// Check for errors
if (user.hasValidationErrors) {
  const errors = user.validationErrors!;

  console.log(errors.getMessages());
  // ["Name is required", "Invalid email format"]

  console.log(errors.getFormattedErrors());
  // [{ path: "name", message: "..." }, { path: "email", message: "..." }]
}

Collecting Issues in rules (without throwing)

When throwOnError is false, use addValidationIssue inside rules to accumulate business rule violations:

rules: (entity) => {
  if (entity.age > 90) {
    entity.addValidationIssue("age", "Age cannot exceed 90 years");
  }
};

Issues from schema validation and addValidationIssue are merged into validationErrors.

Use throwValidationError when you want fail-fast behavior (always throws, regardless of throwOnError).

persistInvalidMutations

When throwOnError is false, this flag defines whether invalid updates are kept on the entity:

// Default: dirty / form mode — mutations apply, errors collected
config: {
  throwOnError: false,
}

// Freeze — block changes while invalid; revert failed updates
config: {
  throwOnError: false,
  persistInvalidMutations: false,
}

persistInvalidMutations: true (default)

• Property changes apply even when schema or rules fail.
• validationErrors reflects the latest validation of the current props (all fields).
• Matches form UX: what the user typed is what toJSON() returns.

const user = new UserSafe({ name: "Tarcisio", email: "[e-mail]", age: 91, ... });
// hasValidationErrors: age rule from create

user.changeName("New Name");
user.changeRole(new Role("User"));
user.removeAddress();

// toJSON() reflects applied mutations; age issue remains until fixed
expect(user.toJSON().name).toBe("New Name");
expect(user.hasValidationErrors).toBe(true);

persistInvalidMutations: false

• While validationErrors exists, further mutations are blocked (including delete).
• A single update that fails validation is reverted; errors are still recorded.

Before save() or exporting changes, validate !entity.hasValidationErrors when using dirty mode.

When to Use Non-Throwing Mode

Form Validation

Collect all errors to display to user at once

Import/Migration

Log errors but continue processing

Partial Validation

Allow incomplete entities during construction

Error Aggregation

Combine errors from multiple sources

API Error Responses

Express.js Example

import express from "express";
import { ValidationError } from "@woltz/rich-domain";

const app = express();

// Error handling middleware
app.use(
  (
    err: Error,
    req: express.Request,
    res: express.Response,
    next: express.NextFunction
  ) => {
    if (ValidationError.isValidationError(err)) {
      return res.status(400).json({
        error: "Validation Error",
        message: err.message,
        details: err.issues.map((issue) => ({
          field: issue.path.join("."),
          message: issue.message,
        })),
      });
    }

    // Other errors
    console.error(err);
    res.status(500).json({ error: "Internal Server Error" });
  }
);

// Route
app.post("/users", async (req, res, next) => {
  try {
    const user = new User(req.body);
    await userRepository.save(user);
    res.status(201).json(user.toJSON());
  } catch (error) {
    next(error); // Pass to error handler
  }
});

Response Format

{
  "error": "Validation Error",
  "message": "Validation failed: Name is required, Invalid email format",
  "details": [
    { "field": "name", "message": "Name is required" },
    { "field": "email", "message": "Invalid email format" }
  ]
}

---

Domain Exceptions

Beyond ValidationError, rich-domain provides a comprehensive set of domain exceptions for different error scenarios. All exceptions extend a common DomainException base class.

import {
  DomainError,
  EntityNotFoundError,
  EntityAlreadyExistsError,
  RepositoryError,
  PersistenceError,
  ConcurrencyError,
  // ... more
} from "@woltz/rich-domain";

Exception Hierarchy

DomainException (base)
├── DomainError
├── EntityNotFoundError
├── EntityAlreadyExistsError
├── InvalidValueObjectError
├── InvalidCriteriaError
├── RepositoryError
│   ├── PersistenceError
│   ├── ConcurrencyError
│   └── ConstraintViolationError
├── DomainEventError
│   └── EventHandlerError
├── TransactionError
├── MapperError
├── ConfigurationError
├── NotImplementedError
└── UnknownError

Common Properties

All domain exceptions share these properties:

interface DomainException extends Error {
  name: string; // Exception class name
  message: string; // Error message
  code: string; // Error code (e.g., "ENTITY_NOT_FOUND")
  timestamp: Date; // When the error occurred

  toJSON(): object; // Serialize for API responses
}

// Type checking (works across module boundaries)
DomainException.isDomainException(error); // boolean

---

Entity & Aggregate Exceptions

DomainError

General-purpose exception for business rule violations:

import { DomainError } from "@woltz/rich-domain";

class Order extends Aggregate<OrderProps> {
  confirm() {
    if (this.items.length === 0) {
      throw new DomainError("Cannot confirm an empty order");
    }

    if (this.status !== "draft") {
      throw new DomainError(
        "Only draft orders can be confirmed",
        "ORDER_NOT_DRAFT" // Optional custom code
      );
    }

    this.props.status = "confirmed";
  }
}

EntityNotFoundError

When an entity or aggregate cannot be found:

import { EntityNotFoundError } from "@woltz/rich-domain";

class UserRepository {
  async findByIdOrFail(id: string): Promise<User> {
    const user = await this.findById(id);

    if (!user) {
      throw new EntityNotFoundError("User", id);
      // Message: "User with id 'abc-123' not found"
      // Code: "ENTITY_NOT_FOUND"
    }

    return user;
  }
}

// With custom message
throw new EntityNotFoundError(
  "User",
  id,
  "The requested user account does not exist"
);

EntityAlreadyExistsError

When trying to create an entity that already exists:

import { EntityAlreadyExistsError } from "@woltz/rich-domain";

class UserService {
  async createUser(email: string, name: string): Promise<User> {
    const existing = await this.userRepo.findByEmail(email);

    if (existing) {
      throw new EntityAlreadyExistsError("User", existing.id.value);
      // Message: "User with id 'abc-123' already exists"
    }

    return new User({ email, name });
  }
}

---

Repository & Persistence Exceptions

RepositoryError

Base exception for repository operations:

import { RepositoryError } from "@woltz/rich-domain";

throw new RepositoryError("Failed to connect to database");

PersistenceError

When a database operation fails:

import { PersistenceError } from "@woltz/rich-domain";

class UserRepository {
  async save(user: User): Promise<void> {
    try {
      await this.db.user.upsert({ ... });
    } catch (error) {
      throw new PersistenceError(
        "save",                    // Operation name
        "Database connection lost", // Message
        error as Error             // Original error (cause)
      );
    }
  }
}

// Access details
catch (error) {
  if (error instanceof PersistenceError) {
    console.log(error.operation); // "save"
    console.log(error.cause);     // Original database error
  }
}

ConcurrencyError

For optimistic locking conflicts:

import { ConcurrencyError } from "@woltz/rich-domain";

class OrderRepository {
  async save(order: Order): Promise<void> {
    const result = await this.db.order.updateMany({
      where: {
        id: order.id.value,
        version: order.version, // Optimistic lock
      },
      data: {
        ...orderData,
        version: { increment: 1 },
      },
    });

    if (result.count === 0) {
      throw new ConcurrencyError("Order", order.id.value);
      // Message: "Concurrency conflict detected for Order with id 'order-123'"
    }
  }
}

ConstraintViolationError

When a database constraint is violated:

import { ConstraintViolationError } from "@woltz/rich-domain";

class UserRepository {
  async save(user: User): Promise<void> {
    try {
      await this.db.user.create({ data: userData });
    } catch (error) {
      if (isPrismaUniqueConstraintError(error)) {
        throw new ConstraintViolationError(
          "users_email_unique",
          "A user with this email already exists"
        );
      }
      throw error;
    }
  }
}

---

Other Exceptions

InvalidValueObjectError

When a Value Object receives invalid data, it throws automatically with schema validation:

import { ValueObject, InvalidValueObjectError } from "@woltz/rich-domain";
import { z } from "zod";

const emailSchema = z.string().email("Invalid email format");

class Email extends ValueObject<string> {
  protected static validation = {
    schema: emailSchema,
  };
}

try {
  const email = new Email("not-an-email");
} catch (error) {
  if (error instanceof InvalidValueObjectError) {
    console.log(error.message); // "Invalid email format"
    console.log(error.value); // "not-an-email"
  }
}

InvalidCriteriaError

When a Criteria query is invalid:

import { InvalidCriteriaError } from "@woltz/rich-domain";

// Thrown automatically by Criteria when:
// - Invalid operator for field type
// - Invalid quantifier value

// Example: manually throwing
if (!allowedFields.includes(field)) {
  throw new InvalidCriteriaError(
    `Field '${field}' is not allowed for filtering`,
    field
  );
}

TransactionError

When a transaction operation fails:

import { TransactionError } from "@woltz/rich-domain";

class UnitOfWork {
  async commit(): Promise<void> {
    try {
      await this.db.$transaction(this.operations);
    } catch (error) {
      throw new TransactionError(
        "commit",
        "Failed to commit transaction",
        error as Error
      );
    }
  }
}

MapperError

When mapping between domain and persistence fails:

import { MapperError } from "@woltz/rich-domain";

class UserToDomainMapper {
  build(record: UserRecord): User {
    try {
      return new User({
        id: Id.from(record.id),
        name: record.name,
        email: record.email,
      });
    } catch (error) {
      throw new MapperError(
        "toDomain",
        "User",
        "Failed to map user record to domain",
        error as Error
      );
    }
  }
}

DomainEventError & EventHandlerError

For event-related failures:

import { DomainEventError, EventHandlerError } from "@woltz/rich-domain";

// General event error
throw new DomainEventError("Failed to publish event", "UserCreatedEvent");

// Handler-specific error
throw new EventHandlerError(
  "SendWelcomeEmailHandler",
  "UserCreatedEvent",
  originalError
);

Utility Exceptions

import {
  NotImplementedError,
  ConfigurationError,
  UnknownError,
} from "@woltz/rich-domain";

// Feature not yet implemented
throw new NotImplementedError("Bulk import");

// Missing or invalid configuration
throw new ConfigurationError("Database URL is required", "DATABASE_URL");

// Wrap unknown errors
throw new UnknownError("An unexpected error occurred", originalError);

---

Handling Domain Exceptions

Centralized Error Handler

import {
  ValidationError,
  EntityNotFoundError,
  EntityAlreadyExistsError,
  ConcurrencyError,
  DomainError,
} from "@woltz/rich-domain";

function handleError(error: Error, res: Response) {
  // Validation errors → 400
  if (ValidationError.isValidationError(error)) {
    return res.status(400).json({
      error: "Validation Error",
      message: error.message,
      details: error.issues,
    });
  }

  // Not found → 404
  if (error instanceof EntityNotFoundError) {
    return res.status(404).json({
      error: "Not Found",
      message: error.message,
      entityType: error.entityType,
      entityId: error.entityId,
    });
  }

  // Already exists → 409
  if (error instanceof EntityAlreadyExistsError) {
    return res.status(409).json({
      error: "Conflict",
      message: error.message,
    });
  }

  // Concurrency conflict → 409
  if (error instanceof ConcurrencyError) {
    return res.status(409).json({
      error: "Conflict",
      message: "Resource was modified by another request",
      code: error.code,
    });
  }

  // Domain errors → 422
  if (error instanceof DomainError) {
    return res.status(422).json({
      error: "Unprocessable Entity",
      message: error.message,
      code: error.code,
    });
  }

  // Unknown errors → 500
  console.error("Unhandled error:", error);
  return res.status(500).json({
    error: "Internal Server Error",
    message: "An unexpected error occurred",
  });
}

Exception Reference Table

Exception	HTTP Status	When to Use
ValidationError	400	Invalid input data
InvalidCriteriaError	400	Invalid query parameters
EntityNotFoundError	404	Resource not found
EntityAlreadyExistsError	409	Duplicate resource
ConcurrencyError	409	Optimistic lock conflict
ConstraintViolationError	409	Database constraint failed
DomainError	422	Business rule violation
InvalidValueObjectError	422	Invalid value object
PersistenceError	500	Database error
TransactionError	500	Transaction failed
MapperError	500	Mapping failed
ConfigurationError	500	Configuration missing