Change Tracking - Rich Domain

What is Change Tracking?

Change tracking is implemented by BaseEntity, so it is available to both Entity and Aggregate. JavaScript Proxies observe property assignments and collection mutations, while snapshots are used to calculate create, update, and delete operations for nested entities. In normal DDD usage, call getChanges() on the aggregate root so the returned operations represent a single consistency and persistence boundary.

const order = new Order({
  id: Id.from("order-123"),
  status: "draft",
  items: [
    new OrderItem({ id: Id.from("item-1"), quantity: 2, unitPrice: 29.99 }),
  ],
});

// Make changes naturally
order.confirm();
order.items[0].updateQuantity(5);
order.addItem("prod-456", 1, 49.99);

// Get all changes with a single call
const changes = order.getChanges();

console.log(changes.hasUpdates()); // true - order status and item quantity changed
console.log(changes.hasCreates()); // true - new item added

Efficient Persistence

Persist detected updates instead of rewriting every child

Zero Boilerplate

Changes tracked automatically - no manual code needed

Correct Ordering

Creates and deletes ordered by object-graph depth

Batch Operations

Group changes by entity type for optimized database operations

Construction establishes the initial baseline. getChanges() reports mutations made after construction or after the most recent markAsClean()/markAsPersisted() call. It does not emit a create operation for the root object itself; repositories normally use isNew() for that decision.

Basic Usage

Getting Changes

const changes = order.getChanges();

// Check what changed
changes.hasCreates();  // Any new entities?
changes.hasUpdates();  // Any modified entities?
changes.hasDeletes();  // Any deleted entities?
changes.hasChanges();  // Any changes at all?
changes.isEmpty();     // No changes?

// Get count
changes.count;  // Total number of operations

Accessing Operations

// Get all creates (ordered root → leaf)
const creates = changes.creates();
// CreateOperation[]

// Get all updates (no specific order)
const updates = changes.updates();
// UpdateOperation[]

// Get all deletes (ordered leaf → root)
const deletes = changes.deletes();
// DeleteOperation[]

// Iterate over all operations
for (const op of changes.operations()) {
  console.log(op.type, op.entity, op.depth);
}

Filtering by Entity

Get changes for a specific entity type:

const itemChanges = changes.of("OrderItem");

// Access entities directly
itemChanges.creates;   // OrderItem[] - new items
itemChanges.deletes;   // OrderItem[] - deleted items
itemChanges.updates;   // Array<{ entity: OrderItem, changed: {...} }>

// Get IDs
itemChanges.createIds;  // string[]
itemChanges.updateIds;  // string[]
itemChanges.deleteIds;  // string[]

// Check for changes
itemChanges.hasCreates();
itemChanges.hasUpdates();
itemChanges.hasDeletes();

// Count
itemChanges.count;

Filtering by Relation

Use forRelation() to select operations associated with a property in the parent object:

const itemRelationChanges = changes.forRelation("items");

console.log(itemRelationChanges.hasChanges());
console.log(itemRelationChanges.getAffectedRelations()); // ["items"]

Excluding Entities

Use without() when you need the inverse of of() — all changes except one or more entity types. It returns a new AggregateChanges instance; the original is unchanged.

const profileChanges = changes.of("Profile");

if (profileChanges.hasUpdates()) {
  await this.context.factoryProfile.update({
    where: { factoryId: factory.id.value },
    data: this.registry.mapFields("Profile", profileChanges.updates[0].changed),
  });
}

const remaining = changes.without("Profile");

if (!remaining.isEmpty()) {
  await super.onUpdate(remaining, factory);
}

Pass a single entity name or an array to exclude multiple types:

changes.without("Profile");
changes.without(["Profile", "Tag"]);

This is useful in custom onUpdate implementations when one entity needs manual persistence (nested writes, custom PK, etc.) and the rest should go through PrismaBatchExecutor.

Resetting the Baseline

The component that successfully persists the object graph should reset its tracking baseline:

await persistChanges(order.getChanges());
order.markAsClean();

// Now tracking starts fresh
const changes = order.getChanges();
console.log(changes.isEmpty()); // true

markAsClean() recursively clears changes in nested entities without changing whether their IDs are new.

PrismaRepository.save() already calls markAsPersisted() after its mapper completes successfully. Do not add a second cleanup call when using that repository. For a custom repository or direct batch executor, reset the baseline only after persistence succeeds.

After First Save

When implementing a custom repository, call markAsPersisted() after the first successful INSERT. It clears tracking and marks the root and nested IDs as not new:

await insertAggregate(order);
order.markAsPersisted();

console.log(order.isNew()); // false
console.log(order.getChanges().isEmpty()); // true

order.updateStatus("confirmed");
await updateAggregate(order);
order.markAsClean();

markAsPersisted() changes ID state; it does not perform an INSERT by itself. The repository or mapper decides how isNew() affects persistence.

Batch Operations

Use toBatchOperations() to group changes by entity, relation, and parent metadata:

toBatchOperations() is a data transformation only. It does not execute a transaction, map domain fields to database columns, or decide whether a relation is owned or referenced. A persistence adapter must handle those concerns.

const batch = changes.toBatchOperations();

// Deletes are grouped and ordered leaf → root
for (const del of batch.deletes) {
  console.log(del.entity, del.ids, {
    parentId: del.parentId,
    parentEntity: del.parentEntity,
    relationField: del.relationField,
  });
}

// Creates are grouped and ordered parent → child
for (const create of batch.creates) {
  for (const item of create.items) {
    console.log(create.entity, item.data, {
      parentId: item.parentId,
      parentEntity: item.parentEntity,
      relationField: item.relationField,
    });
  }
}

// Updates are grouped by entity and are not depth-sorted
for (const update of batch.updates) {
  for (const item of update.items) {
    console.log(update.entity, item.id, item.changedFields);
  }
}

The ordering reflects the tracked object graph:

Deletes: Children first, then parents
Creates: Parents first, then children
Updates: Grouped by entity without depth ordering

This ordering helps an adapter satisfy foreign keys, but it cannot guarantee database correctness by itself. Relationship configuration and transaction handling still belong to the adapter.

Operation Ordering

The library orders create and delete operations by their depth in the tracked object graph. Depth 0 is the object on which getChanges() is called. The tracker can emit an update for that root, but it does not emit a create or delete for the root itself.

Deletes: Leaf → Root

Children must be deleted before parents to avoid FK violations:

// Given changes below an Order root:
// OrderItem
// └── ItemDiscount

const deletes = changes.deletes();
// Returns in order:
// 1. ItemDiscount (depth: 2)
// 2. OrderItem (depth: 1)
// The Order root itself is saved by its repository.

Creates: Root → Leaf

Parents must be created before children so FKs can reference them:

const creates = changes.creates();
// Returns in order:
// 1. OrderItem (depth: 1)
// 2. ItemDiscount (depth: 2)

Updates: Any Order

Updates are returned in detection order and grouped by entity in batch output:

const updates = changes.updates();
// No depth ordering guarantee

Working with Collections

Collections of Entity/Aggregate instances produce item-level create, update, and delete operations. Arrays containing only primitive values are reported as an update to the property of their owning entity.

Adding Items

const order = new Order({
  id: Id.from("order-123"),
  items: [],
});

order.addItem("prod-1", 2, 29.99);
order.addItem("prod-2", 1, 49.99);

const itemChanges = order.getChanges().of("OrderItem");
console.log(itemChanges.creates.length); // 2

Removing Items

const order = new Order({
  id: Id.from("order-123"),
  items: [
    new OrderItem({ id: Id.from("item-1"), ... }),
    new OrderItem({ id: Id.from("item-2"), ... }),
  ],
});

order.removeItem(Id.from("item-1"));

const itemChanges = order.getChanges().of("OrderItem");
console.log(itemChanges.deleteIds); // ["item-1"]

Updating Items

const order = new Order({
  id: Id.from("order-123"),
  items: [
    new OrderItem({ id: Id.from("item-1"), quantity: 2, ... }),
  ],
});

order.items[0].updateQuantity(5);

const itemChanges = order.getChanges().of("OrderItem");
console.log(itemChanges.updates[0].changed); // { quantity: 5 }

Mixed Operations

// Create, update, and delete in the same transaction
order.addItem("prod-new", 1, 39.99);        // Create
order.items[0].updateQuantity(10);          // Update
order.removeItem(Id.from("item-old"));      // Delete

const itemChanges = order.getChanges().of("OrderItem");
console.log(itemChanges.creates.length); // 1
console.log(itemChanges.updates.length); // 1
console.log(itemChanges.deletes.length); // 1

Working with Single Entities (1:1)

Setting an Entity

const user = new User({
  id: Id.from("user-1"),
  address: null,
});

user.setAddress(new Address({
  street: "123 Main St",
  city: "New York",
}));

const addressChanges = user.getChanges().of("Address");
console.log(addressChanges.hasCreates()); // true

Removing an Entity

const user = new User({
  id: Id.from("user-1"),
  address: new Address({ id: Id.from("addr-1"), ... }),
});

user.removeAddress();

const addressChanges = user.getChanges().of("Address");
console.log(addressChanges.deleteIds); // ["addr-1"]

Updating an Entity

const user = new User({
  id: Id.from("user-1"),
  address: new Address({ id: Id.from("addr-1"), street: "Old St", ... }),
});

user.address.changeStreet("New Street");

const addressChanges = user.getChanges().of("Address");
console.log(addressChanges.updates[0].changed); // { street: "New Street" }

Replacing an Entity

const user = new User({
  id: Id.from("user-1"),
  address: new Address({ id: Id.from("addr-1"), ... }),
});

// Replace with completely new address (different ID)
user.setAddress(new Address({
  street: "789 Pine Rd",
  city: "Boston",
}));

const addressChanges = user.getChanges().of("Address");
console.log(addressChanges.hasDeletes()); // true - old address
console.log(addressChanges.hasCreates()); // true - new address

Deeply Nested Changes

Change tracking recursively follows nested BaseEntity instances and has no fixed depth limit:

// Structure: User → Post → Comment → Like
const user = new User({
  id: Id.from("user-1"),
  posts: [
    new Post({
      id: Id.from("post-1"),
      comments: [
        new Comment({
          id: Id.from("comment-1"),
          likes: [],
        }),
      ],
    }),
  ],
});

// Add a like (depth 3)
user.posts[0].comments[0].addLike(new Like({ ... }));

// Update comment (depth 2)
user.posts[0].comments[0].changeText("Updated");

// Add new comment (depth 2)
user.posts[0].addComment(new Comment({ ... }));

const changes = user.getChanges();
console.log(changes.of("Comment").hasCreates()); // true
console.log(changes.of("Comment").hasUpdates()); // true
console.log(changes.of("Like").hasCreates());    // true

Circular entity references are rejected during change comparison. Across aggregate boundaries, prefer storing another aggregate’s Id instead of an object reference.

Cascading Deletes

When a parent is removed from the tracked graph, its nested entities are also reported as delete operations:

const user = new User({
  posts: [
    new Post({
      id: Id.from("post-1"),
      comments: [
        new Comment({ id: Id.from("comment-1"), likes: [...] }),
        new Comment({ id: Id.from("comment-2"), likes: [] }),
      ],
    }),
  ],
});

// Remove post from the tracked object graph
user.removePost(Id.from("post-1"));

const changes = user.getChanges();
console.log(changes.of("Post").deleteIds);    // ["post-1"]
console.log(changes.of("Comment").deleteIds); // ["comment-1", "comment-2"]
console.log(changes.of("Like").deleteIds);    // [...]

// Batch operations place deeper deletes first
const batch = changes.toBatchOperations();
// Order: Like → Comment → Post (leaf to root)

This is a cascade in the generated change set, not a database-level ON DELETE CASCADE. The adapter still decides whether a relation is owned and should be deleted or is a reference that should only be disconnected.

Cascading Creates

When a parent with nested entities is added after the baseline, the parent and its nested children are reported as creates:

user.addPost(new Post({
  title: "New Post",
  comments: [
    new Comment({
      text: "First comment",
      likes: [
        new Like({ ... }),
        new Like({ ... }),
      ],
    }),
  ],
}));

const changes = user.getChanges();
console.log(changes.of("Post").creates.length);    // 1
console.log(changes.of("Comment").creates.length); // 1
console.log(changes.of("Like").creates.length);    // 2

// Batch operations place shallower creates first
const batch = changes.toBatchOperations();
// Order: Post → Comment → Like (root to leaf)

Entities already present during construction are part of the baseline and are not reported as creates merely because their IDs are new.

Change History

getHistory() returns low-level writes observed by the entity’s tracker:

order.updateStatus("confirmed");

const history = order.getHistory();
console.log(history[0]);
// {
//   path: "status",
//   previousValue: "draft",
//   currentValue: "confirmed",
//   timestamp: 1710000000000
// }

History entries are useful for debugging, but they are not the same as AggregateChanges: multiple writes may collapse into one update operation, and changes reverted back to the baseline may produce no persistence operation.

Change history is in-memory diagnostic state, not a durable audit log. Persist explicit domain events or audit records when auditability is required.

Collections with Entities

Use entities when collection items need independent create, update, and delete operations. Value Objects remain appropriate for immutable values that are persisted as part of their owner:

class TagReference extends Entity<{ id: Id; tagId: string; name: string }> {
  get tagId() { return this.props.tagId; }
  get name() { return this.props.name; }
}

class Like extends Entity<{
  id: Id;
  postId: string;
  userId: string;
  createdAt: Date;
}> {
  get postId() { return this.props.postId; }
  get userId() { return this.props.userId; }
}

How Entity Tracking Works

Entities are tracked by their ID:

const user = new User({
  id: Id.from("user-1"),
  tags: [
    new TagReference({
      id: Id.from("tag-ref-1"),
      tagId: "tag-1",
      name: "JavaScript"
    }),
    new TagReference({
      id: Id.from("tag-ref-2"),
      tagId: "tag-2",
      name: "TypeScript"
    }),
  ],
});

// Remove a tag
user.removeTag("tag-1");

// Add a new tag
user.addTag(new TagReference({
  id: new Id(),
  tagId: "tag-3",
  name: "Node.js"
}));

const changes = user.getChanges();
const tagChanges = changes.of("TagReference");

console.log(tagChanges.deletes.length); // 1
console.log(tagChanges.creates.length); // 1

Nested Entities Example

const comment = new Comment({
  id: Id.from("comment-1"),
  text: "Great post!",
  likes: [
    new Like({
      id: new Id(),
      postId: "post-1",
      userId: "user-1",
      createdAt: new Date()
    }),
    new Like({
      id: new Id(),
      postId: "post-1",
      userId: "user-2",
      createdAt: new Date()
    }),
  ],
});

// Remove a specific like
comment.removeLike("post-1", "user-2");

const changes = comment.getChanges();
const likeChanges = changes.of("Like");

console.log(likeChanges.deletes.length); // 1

Type-Safe Changes

For better TypeScript support, define an entity map:

type OrderEntities = {
  Order: Order;
  OrderItem: OrderItem;
  ItemDiscount: ItemDiscount;
  Address: Address;
};

// Get typed changes
const changes = order.getChanges<OrderEntities>();

// Now 'of' has autocomplete
const itemChanges = changes.of("OrderItem");
//                              ^? "Order" | "OrderItem" | "ItemDiscount" | "Address"

// Returns are properly typed
itemChanges.creates.forEach((item) => {
  console.log(item.quantity); // item is OrderItem
});

Helper Method Pattern

class Order extends Aggregate<OrderProps> {
  getTypedChanges() {
    type Entities = {
      Order: Order;
      OrderItem: OrderItem;
      ItemDiscount: ItemDiscount;
    };
    return this.getChanges<Entities>();
  }
}

// Usage
const changes = order.getTypedChanges();
const items = changes.of("OrderItem"); // Fully typed!

We strongly recommend defining a getTypedChanges() helper method directly in your Aggregate class. This provides a cleaner API and avoids repeating the entity map every time:

class Order extends Aggregate<OrderProps> {
  getTypedChanges() {
    interface Entities {
      OrderItem: OrderItem;
      ItemDiscount: ItemDiscount;
    }
    return this.getChanges<Entities>();
  }
}

// Usage - clean and type-safe
const changes = order.getTypedChanges();
const items = changes.of("OrderItem"); // Autocomplete works!

Entity-map keys must match the runtime class names stored in operations. For example, an Address instance produces the entity name "Address", not the property name "shippingAddress".

Persistence Example with Prisma

PrismaToPersistence uses PrismaBatchExecutor for updates by default. The executor understands relation metadata, schema mappings, owned collections, and reference collections, while PrismaRepository.save() resets the aggregate with markAsPersisted() after persistence:

class OrderService {
  constructor(private readonly orderRepo: OrderRepository) {}

  async confirmOrder(orderId: string): Promise<void> {
    const order = await this.orderRepo.findById(orderId);
    if (!order) throw new Error("Order not found");

    order.confirm();

    const changes = order.getTypedChanges();
    if (changes.isEmpty()) return;

    await this.orderRepo.save(order);

    console.log(order.getChanges().isEmpty()); // true
  }
}

Override PrismaToPersistence.onUpdate() only when part of the graph needs custom persistence. Use without() to pass the remaining operations to the default executor.

API Reference

BaseEntity Tracking

These methods are available on both Entity and Aggregate:

Method	Returns	Description
`getChanges<TEntityMap>()`	`AggregateChanges<TEntityMap>`	Calculate operations since the current baseline
`getHistory()`	`HistoryEntry[]`	Copy of low-level writes observed by the tracker
`markAsClean()`	`void`	Recursively establish a new baseline
`markAsPersisted()`	`void`	Recursively establish a new baseline and mark IDs as not new

AggregateChanges

Method	Returns	Description
`creates()`	`CreateOperation[]`	All creates, ordered root → leaf
`updates()`	`UpdateOperation[]`	All updates
`deletes()`	`DeleteOperation[]`	All deletes, ordered leaf → root
`of(entity)`	`EntityChanges<T>`	Filter changes by entity name
`forRelation(relation)`	`AggregateChanges`	New instance filtered by relation field
`without(entity \| entities)`	`AggregateChanges`	New instance excluding the given entity/entities
`toBatchOperations()`	`BatchOperations`	Group changes for bulk operations
`hasCreates()`	`boolean`	Has any creates
`hasUpdates()`	`boolean`	Has any updates
`hasDeletes()`	`boolean`	Has any deletes
`hasChanges()`	`boolean`	Has any operations
`isEmpty()`	`boolean`	No operations
`getAffectedEntities()`	`string[]`	List of entity names with changes
`getAffectedRelations()`	`string[]`	List of relation fields with changes
`operations()`	`Generator`	Iterate all operations in order
`toArray()`	`Operation[]`	All operations as array
`rawOperations`	`Operation[]`	Copy of operations without ordering
`clone()`	`AggregateChanges`	Independent copy of the operation list
`clear()`	`void`	Clear this result object’s operations
`count`	`number`	Total number of operations

AggregateChanges.clear() only mutates that result object. It does not reset the entity tracker; a later entity.getChanges() will calculate the changes again. Use entity.markAsClean() to establish a new baseline.

EntityChanges

Property/Method	Returns	Description
`creates`	`T[]`	Created entities
`updates`	`Array<{entity: T, changed: Record}>`	Updated entities with changes
`deletes`	`T[]`	Deleted entities
`createIds`	`string[]`	IDs of created entities
`updateIds`	`string[]`	IDs of updated entities
`deleteIds`	`string[]`	IDs of deleted entities
`hasCreates()`	`boolean`	Has any creates
`hasUpdates()`	`boolean`	Has any updates
`hasDeletes()`	`boolean`	Has any deletes
`hasChanges()`	`boolean`	Has any operations
`isEmpty()`	`boolean`	No operations
`rawOperations`	`Operation<T>[]`	Copy of the filtered raw operations
`count`	`number`	Total operations

BatchOperations

interface BatchOperations {
  deletes: Array<{
    entity: string;
    depth: number;
    ids: string[];
    parentId?: string;
    parentEntity?: string;
    relationField?: string;
    items?: Array<{
      id: string;
      relationField?: string;
    }>;
  }>;

  creates: Array<{
    entity: string;
    depth: number;
    parentEntity?: string;
    relationField?: string;
    items: Array<{
      data: any;
      parentId?: string;
      parentEntity?: string;
      relationField?: string;
    }>;
  }>;

  updates: Array<{
    entity: string;
    items: Array<{
      id: string;
      changedFields: Record<string, any>;
    }>;
  }>;
}

​What is Change Tracking?

Efficient Persistence

Zero Boilerplate

Correct Ordering

Batch Operations

​Basic Usage

​Getting Changes

​Accessing Operations

​Filtering by Entity

​Filtering by Relation

​Excluding Entities

​Resetting the Baseline

​After First Save

​Batch Operations

​Operation Ordering

​Deletes: Leaf → Root

​Creates: Root → Leaf

​Updates: Any Order

​Working with Collections

​Adding Items

​Removing Items

​Updating Items

​Mixed Operations

​Working with Single Entities (1:1)

​Setting an Entity

​Removing an Entity

​Updating an Entity

​Replacing an Entity

​Deeply Nested Changes

​Cascading Deletes

​Cascading Creates

​Change History

​Collections with Entities

​How Entity Tracking Works

​Nested Entities Example

​Type-Safe Changes

​Helper Method Pattern

​Persistence Example with Prisma

​API Reference

​BaseEntity Tracking

​AggregateChanges

​EntityChanges

​BatchOperations

What is Change Tracking?

Basic Usage

Getting Changes

Accessing Operations

Filtering by Entity

Filtering by Relation

Excluding Entities

Resetting the Baseline

After First Save

Batch Operations

Operation Ordering

Deletes: Leaf → Root

Creates: Root → Leaf

Updates: Any Order

Working with Collections

Adding Items

Removing Items

Updating Items

Mixed Operations

Working with Single Entities (1:1)

Setting an Entity

Removing an Entity

Updating an Entity

Replacing an Entity

Deeply Nested Changes

Cascading Deletes

Cascading Creates

Change History

Collections with Entities

How Entity Tracking Works

Nested Entities Example

Type-Safe Changes

Helper Method Pattern

Persistence Example with Prisma

API Reference

BaseEntity Tracking

AggregateChanges

EntityChanges

BatchOperations