Entities & Aggregates

What are Entities and Aggregates?

Entities and Aggregates are domain objects defined by their identity, not by their attributes. Two objects with the same attributes but different IDs are considered distinct objects. The main difference lies in their architectural role, not in their change tracking implementation:

Entity: Domain object with identity that normally lives inside an Aggregate
Aggregate: Root entity that defines a consistency boundary and is the entry point for repositories and domain events

Entity

Objects with identity that live inside Aggregates. Not accessed directly through repositories.

Aggregate

Root of a cluster of related entities. Models the consistency boundary persisted by a repository.

Key Differences

Feature	Entity	Aggregate
Has identity	Yes	Yes
Participates in persistence	Yes	Yes
Defines a consistency boundary	No	Yes
Repository root in the core API	No	Yes
Can contain and manage child entities	Yes	Yes
Can record domain events	No	Yes
Tracks its own and nested changes	Yes	Yes
Can technically be nested in an object	Yes	Yes

Entity and Aggregate both inherit change tracking from BaseEntity. Therefore, either one can technically contain and track nested entities. The distinction is architectural: repositories in the core API operate on aggregate roots, and only Aggregate provides domain-event management.

Although nesting one Aggregate inside another is technically supported by the object graph tracker, it usually crosses aggregate boundaries. Prefer referencing another aggregate root by Id. Persistence adapters may treat an embedded aggregate as an owned child unless its relationship is configured as a reference.

Creating Entities

Entities are identity-bearing domain objects, typically used as part of an Aggregate. They have the same validation, serialization, and change tracking capabilities inherited from BaseEntity, but they do not manage domain events:

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

interface OrderItemProps {
  id: Id;
  productId: string;
  quantity: number;
  unitPrice: number;
}

class OrderItem extends Entity<OrderItemProps> {
  get productId() {
    return this.props.productId;
  }

  get quantity() {
    return this.props.quantity;
  }

  get subtotal() {
    return this.props.quantity * this.props.unitPrice;
  }

  updateQuantity(quantity: number) {
    if (quantity <= 0) {
      throw new DomainError("Quantity must be positive");
    }
    this.props.quantity = quantity;
  }
}

// New entity (auto-generated ID)
const item = new OrderItem({
  productId: "prod-123",
  quantity: 2,
  unitPrice: 49.99,
});

console.log(item.isNew()); // true

// Existing entity (from database)
const existingItem = new OrderItem({
  id: Id.from("item-456"),
  productId: "prod-123",
  quantity: 2,
  unitPrice: 49.99,
});

console.log(existingItem.isNew()); // false

Creating Aggregates

Aggregates are the root of a cluster of entities and define consistency boundaries:

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

interface OrderProps {
  id: Id;
  customerId: string;
  status: "draft" | "confirmed" | "shipped" | "delivered";
  items: OrderItem[];
  shippingAddress: Address;
  createdAt: Date;
}

class Order extends Aggregate<OrderProps> {
  get customerId() {
    return this.props.customerId;
  }

  get status() {
    return this.props.status;
  }

  get items() {
    return this.props.items;
  }

  get total() {
    return this.props.items.reduce((sum, item) => sum + item.subtotal, 0);
  }

  addItem(productId: string, quantity: number, unitPrice: number) {
    if (this.props.status !== "draft") {
      throw new DomainError("Cannot modify confirmed order");
    }
    this.props.items.push(new OrderItem({ productId, quantity, unitPrice }));
  }

  removeItem(itemId: Id) {
    if (this.props.status !== "draft") {
      throw new DomainError("Cannot modify confirmed order");
    }
    this.props.items = this.props.items.filter(
      (item) => !item.id.equals(itemId)
    );
  }

  confirm() {
    if (this.props.items.length === 0) {
      throw new DomainError("Cannot confirm empty order");
    }
    this.props.status = "confirmed";
  }

  ship() {
    if (this.props.status !== "confirmed") {
      throw new DomainError("Order must be confirmed before shipping");
    }
    this.props.status = "shipped";
  }
}

Identity & Equality

Both Entities and Aggregates are compared by ID, not by attributes:

const item1 = new OrderItem({
  id: Id.from("item-1"),
  productId: "prod-123",
  quantity: 2,
  unitPrice: 49.99,
});

const item2 = new OrderItem({
  id: Id.from("item-1"),
  productId: "prod-999", // different attributes
  quantity: 10,
  unitPrice: 99.99,
});

const item3 = new OrderItem({
  id: Id.from("item-2"), // different ID
  productId: "prod-123",
  quantity: 2,
  unitPrice: 49.99,
});

item1.equals(item2); // true - same ID
item1.equals(item3); // false - different IDs
item1.equals("item-1"); // true - can compare with string
item1.equals(Id.from("item-1")); // true - can compare with Id

Validation

Both support validation with Standard Schema-compatible validators such as Zod:

import { z } from "zod";
import {
  Aggregate,
  DomainError,
  Entity,
  EntityHooks,
  EntityValidation,
  Id,
} from "@woltz/rich-domain";

// Entity validation
const orderItemSchema = z.object({
  id: z.custom<Id>((val) => val instanceof Id),
  productId: z.string().min(1),
  quantity: z.number().int().positive(),
  unitPrice: z.number().positive(),
});

type OrderItemProps = z.infer<typeof orderItemSchema>;

class OrderItem extends Entity<OrderItemProps> {
  protected static validation: EntityValidation<OrderItemProps> = {
    schema: orderItemSchema,
    config: {
      onCreate: true,
      onUpdate: true,
      throwOnError: true,
    },
  };
}

// Aggregate validation with business rules
const orderSchema = z.object({
  id: z.custom<Id>((val) => val instanceof Id),
  customerId: z.string().min(1),
  status: z.enum(["draft", "confirmed", "shipped", "delivered"]),
  items: z.array(z.custom<OrderItem>((val) => val instanceof OrderItem)),
  shippingAddress: z.custom<Address>((val) => val instanceof Address),
  createdAt: z.date(),
});

type OrderProps = z.infer<typeof orderSchema>;

class Order extends Aggregate<OrderProps> {
  protected static validation: EntityValidation<OrderProps> = {
    schema: orderSchema,
    config: {
      onCreate: true,
      onUpdate: true,
      throwOnError: true,
    },
  };

  protected static hooks: EntityHooks<OrderProps, Order> = {
    rules: (order) => {
      // Business rule: shipped orders must have at least one item
      if (order.status === "shipped" && order.items.length === 0) {
        throw new DomainError("Shipped orders must have items");
      }
    },
  };
}

Optional Input Properties

Sometimes you need properties that are required in the entity but optional when constructing it, because they’re generated internally via hooks. Use the second generic parameter to specify optional input fields:

import { z } from "zod";
import { Aggregate, Id, EntityValidation, EntityHooks } from "@woltz/rich-domain";

const userSchema = z.object({
  id: z.custom<Id>((val) => val instanceof Id),
  email: z.string().email(),
  password: z.string().min(8), // Required in schema
  name: z.string(),
  createdAt: z.date(), // Required in schema
});

type UserProps = z.infer<typeof userSchema>;

// Make 'password' and 'createdAt' optional in constructor
class User extends Aggregate<UserProps, "password" | "createdAt"> {
  protected static validation: EntityValidation<UserProps> = {
    schema: userSchema,
  };

  protected static hooks: EntityHooks<UserProps, User> = {
    onBeforeCreate: (props) => {
      // Generate password if not provided
      if (!props.password) {
        props.password = generateEncryptedPassword();
      }
      // Set createdAt if not provided
      if (!props.createdAt) {
        props.createdAt = new Date();
      }
    },
  };

  get email() {
    return this.props.email;
  }

  get password() {
    return this.props.password;
  }
}

// ✅ Works without password and createdAt
const user = new User({
  email: "user@example.com",
  name: "John Doe",
});

// ✅ Also works with explicit values
const userWithPassword = new User({
  email: "user@example.com",
  name: "John Doe",
  password: "custom-password-12345678",
});

Fields marked as optional input are still required in the entity and validated by the schema. The difference is they’re optional when calling new User() because they’ll be generated in onBeforeCreate.

Common Use Cases:

Auto-generated passwords or tokens
Timestamps (createdAt, updatedAt)
Computed identifiers
Default configurations

Consistency Boundaries

Immediate Consistency

Model aggregate methods so their invariants are valid before persistence.

Eventual Consistency

Coordinate changes across aggregate boundaries with domain events or application services.

Rich Domain supplies the building blocks, but it does not automatically define your invariants or open a database transaction. The application and persistence adapter remain responsible for executing a save inside the required transactional boundary.

Change Tracking

Both entities and aggregates track changes to their own properties and nested BaseEntity instances. In normal DDD usage, call getChanges() on the aggregate root so the result represents the persistence boundary:

const order = new Order({
  id: Id.from("order-123"),
  customerId: "cust-456",
  status: "draft",
  items: [
    new OrderItem({
      id: Id.from("item-1"),
      productId: "prod-a",
      quantity: 2,
      unitPrice: 29.99,
    }),
    new OrderItem({
      id: Id.from("item-2"),
      productId: "prod-b",
      quantity: 1,
      unitPrice: 19.99,
    }),
  ],
  shippingAddress: new Address({
    street: "123 Main",
    city: "NYC",
    zipCode: "10001",
  }),
  createdAt: new Date(),
});

// Make changes after the initial tracking baseline
order.addItem("prod-c", 1, 49.99); // Create
order.items[0].updateQuantity(5); // Update
order.removeItem(Id.from("item-2")); // Delete

// Get all changes
const changes = order.getChanges();

console.log(changes.hasCreates()); // true
console.log(changes.hasUpdates()); // true
console.log(changes.hasDeletes()); // true

// Group and order operations for a persistence adapter
const batch = changes.toBatchOperations();

console.log(batch.deletes[0].ids); // ["item-2"]
console.log(batch.creates[0].items[0].parentId); // "order-123"
console.log(batch.updates[0].items[0].changedFields); // { quantity: 5 }

Construction establishes the initial tracking baseline. getChanges() reports mutations made after construction or after markAsClean(); it does not emit a create operation for the root object itself. Repositories use isNew() to decide whether the aggregate root requires an INSERT.

Domain Events

Aggregates can emit domain events for cross-aggregate communication:

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

type OrderConfirmedPayload = {
  orderId: string;
  customerId: string;
  total: number;
};

class OrderConfirmedEvent extends DomainEvent<OrderConfirmedPayload> {}

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

    this.props.status = "confirmed";

    this.addDomainEvent(new OrderConfirmedEvent({
      orderId: this.id.value,
      customerId: this.customerId,
      total: this.total,
    }));
  }
}

// Persist first, then publish. dispatchAll() clears events after publishing.
await orderRepository.save(order);
await order.dispatchAll(eventBus);

See more in Domain Events

Serialization

Both can be converted to JSON for APIs or persistence:

const item = new OrderItem({
  id: Id.from("item-123"),
  productId: "prod-456",
  quantity: 3,
  unitPrice: 29.99,
});

const itemJson = item.toJSON();
// {
//   id: "item-123",
//   productId: "prod-456",
//   quantity: 3,
//   unitPrice: 29.99
// }

const orderJson = order.toJSON();
// {
//   id: "order-123",
//   customerId: "cust-456",
//   status: "confirmed",
//   items: [
//     { id: "item-1", productId: "prod-a", quantity: 2, unitPrice: 29.99 }
//   ],
//   shippingAddress: { street: "123 Main", city: "NYC", zipCode: "10001" },
//   createdAt: "2024-01-15T10:30:00.000Z"
// }

​What are Entities and Aggregates?

Entity

Aggregate

​Key Differences

​Creating Entities

​Creating Aggregates

​Identity & Equality

​Validation

​Optional Input Properties

​Consistency Boundaries

Immediate Consistency

Eventual Consistency

​Change Tracking

​Domain Events

​Serialization

What are Entities and Aggregates?

Key Differences

Creating Entities

Creating Aggregates

Identity & Equality

Validation

Optional Input Properties

Consistency Boundaries

Change Tracking

Domain Events

Serialization