Class: ChangeTracker
Defined in: src/tracking/ChangeTracker.ts:12
Tracks changes made to entity instances to enable unit-of-work persistence via DbContext.saveChanges().
Keeps track of Added, Modified, Deleted, and Unchanged states and detects modified properties via reactive ES6 proxies.
Constructors
Constructor
new ChangeTracker():
ChangeTracker
Returns
ChangeTracker
Methods
entries()
entries():
EntityEntry<any>[]
Defined in: src/tracking/ChangeTracker.ts:21
Returns all entity entries currently tracked by this tracker.
Returns
EntityEntry<any>[]
Array of EntityEntry instances.
Usecase
Inspect tracked entities, check states, or identify pending modifications.
entry()
entry<
T>(entity):EntityEntry<T> |undefined
Defined in: src/tracking/ChangeTracker.ts:32
Looks up the tracked EntityEntry for a specific entity instance.
Type Parameters
| Type Parameter |
|---|
T extends object |
Parameters
| Parameter | Type | Description |
|---|---|---|
entity | T | The tracked entity instance or proxy. |
Returns
EntityEntry<T> | undefined
The corresponding EntityEntry or undefined if not tracked.
Usecase
Inspect property changes, original values, or state of a specific entity.
hasChanges()
hasChanges():
boolean
Defined in: src/tracking/ChangeTracker.ts:43
Checks whether there are any pending changes (Added, Modified, or Deleted entities) waiting to be saved.
Returns
boolean
true if uncommitted modifications exist, otherwise false.
Usecase
Determine whether a call to saveChanges() is needed.
clear()
clear():
void
Defined in: src/tracking/ChangeTracker.ts:57
Clears all tracked entities from the tracker.
Returns
void
Usecase
Reset change tracking state between tests or after rolling back changes.
add()
add<
T>(entity,metadata?):EntityEntry<T>
Defined in: src/tracking/ChangeTracker.ts:69
Marks a new entity as Added, scheduling it for an SQL INSERT on saveChanges().
Type Parameters
| Type Parameter |
|---|
T extends object |
Parameters
| Parameter | Type | Description |
|---|---|---|
entity | T | The entity object to insert. |
metadata? | EntityMetadata | Optional model metadata. |
Returns
EntityEntry<T>
The newly created EntityEntry.
Usecase
Enqueue a newly created entity to be persisted during the next saveChanges().
remove()
remove<
T>(entity,metadata?):EntityEntry<T>
Defined in: src/tracking/ChangeTracker.ts:89
Marks an entity as Deleted, scheduling it for an SQL DELETE on saveChanges().
Type Parameters
| Type Parameter |
|---|
T extends object |
Parameters
| Parameter | Type | Description |
|---|---|---|
entity | T | The entity object to remove. |
metadata? | EntityMetadata | Optional model metadata. |
Returns
EntityEntry<T>
The EntityEntry marked as Deleted.
Usecase
Enqueue an existing entity for deletion during the next saveChanges().
attach()
attach<
T>(entity,metadata?,state?):EntityEntry<T>
Defined in: src/tracking/ChangeTracker.ts:110
Attaches an existing entity to the tracker in a specified state (default: Unchanged).
Type Parameters
| Type Parameter |
|---|
T extends object |
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
entity | T | undefined | The entity instance to track. |
metadata? | EntityMetadata | undefined | Optional model metadata. |
state? | EntityState | EntityState.Unchanged | Initial entity state (defaults to EntityState.Unchanged). |
Returns
EntityEntry<T>
The tracked EntityEntry.
Usecase
Attach detached entities (e.g. deserialized from an API request) to be managed by the tracker.
track()
track<
T>(entity,metadata?,state?):T
Defined in: src/tracking/ChangeTracker.ts:140
Wraps an entity in a reactive ES6 Proxy that automatically marks the entity as Modified when any property changes.
Type Parameters
| Type Parameter |
|---|
T extends object |
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
entity | T | undefined | The entity to track. |
metadata? | EntityMetadata | undefined | Optional entity metadata. |
state? | EntityState | EntityState.Unchanged | Initial state (defaults to EntityState.Unchanged). |
Returns
T
A transparent Proxy around the entity.
Usecase
Enables effortless dirty checking — just modify properties on the returned object and call saveChanges().
Example
const user = changeTracker.track(existingUser);
user.email = 'new@example.com'; // automatically transitions state to Modified