@idpass/data-collect-core / SnapshotService
Class: SnapshotService
Defined in: services/SnapshotService.ts:76
Service for managing entity snapshots in the event sourcing system.
Snapshots are point-in-time captures of entity state that optimize event replay performance. Instead of replaying all events from the beginning, the system can load the latest snapshot and only replay events that occurred after it.
Key features:
- Automatic snapshot creation when event count exceeds threshold
- Batch snapshot creation for entire tenants
- Snapshot pruning to limit storage usage
- Entity rebuild from snapshot + incremental event replay
Constructors
Constructor
new SnapshotService(
connectionString,eventApplierService,tenantId?):SnapshotService
Defined in: services/SnapshotService.ts:81
Parameters
connectionString
string
eventApplierService
tenantId?
string = "default"
Returns
SnapshotService
Methods
initialize()
initialize():
Promise<void>
Defined in: services/SnapshotService.ts:94
Initializes the entity_snapshots table in the database.
Returns
Promise<void>
createSnapshot()
createSnapshot(
entityGuid):Promise<SnapshotRecord|null>
Defined in: services/SnapshotService.ts:127
Creates a snapshot of the current state of an entity.
The snapshot captures the entity's modified state and the sequence number of the most recent event for that entity.
Parameters
entityGuid
string
The GUID of the entity to snapshot.
Returns
Promise<SnapshotRecord | null>
The created snapshot record, or null if the entity was not found.
getLatestSnapshot()
getLatestSnapshot(
entityGuid):Promise<SnapshotRecord|null>
Defined in: services/SnapshotService.ts:187
Retrieves the most recent snapshot for an entity.
Parameters
entityGuid
string
The GUID of the entity.
Returns
Promise<SnapshotRecord | null>
The latest snapshot record, or null if none exists.
shouldSnapshot()
shouldSnapshot(
entityGuid,threshold?):Promise<boolean>
Defined in: services/SnapshotService.ts:220
Checks whether an entity has accumulated enough events since the last snapshot to warrant a new one.
Parameters
entityGuid
string
The GUID of the entity.
threshold?
number = DEFAULT_SNAPSHOT_THRESHOLD
Number of events after which a snapshot is recommended (default 50).
Returns
Promise<boolean>
True if the entity should have a new snapshot created.
createSnapshotsForTenant()
createSnapshotsForTenant(
tenantId?,threshold?):Promise<BatchSnapshotResult>
Defined in: services/SnapshotService.ts:249
Creates snapshots for all entities in a tenant that have accumulated enough events since their last snapshot.
Parameters
tenantId?
string
The tenant ID to process (uses instance tenantId if not provided).
threshold?
number = DEFAULT_SNAPSHOT_THRESHOLD
Event count threshold for snapshot creation (default 50).
Returns
Promise<BatchSnapshotResult>
Summary of the batch operation.
pruneSnapshots()
pruneSnapshots(
entityGuid,keepCount?):Promise<number>
Defined in: services/SnapshotService.ts:296
Prunes old snapshots for an entity, keeping only the N most recent ones.
Parameters
entityGuid
string
The GUID of the entity.
keepCount?
number = 3
Number of most recent snapshots to keep (default 3).
Returns
Promise<number>
Number of snapshots deleted.
rebuildFromSnapshot()
rebuildFromSnapshot(
entityGuid):Promise<EntityDoc|null>
Defined in: services/SnapshotService.ts:338
Rebuilds an entity's state from the latest snapshot plus incremental event replay.
This method:
- Loads the latest snapshot for the entity.
- Finds all events that occurred after the snapshot's event sequence.
- Replays those events on top of the snapshot state.
- Returns the rebuilt entity state.
If no snapshot exists, replays all events from the beginning.
Parameters
entityGuid
string
The GUID of the entity to rebuild.
Returns
Promise<EntityDoc | null>
The rebuilt entity state, or null if no events exist.
getSnapshotCount()
getSnapshotCount(
entityGuid):Promise<number>
Defined in: services/SnapshotService.ts:444
Gets the total number of snapshots for an entity.
Parameters
entityGuid
string
The GUID of the entity.
Returns
Promise<number>
The number of snapshots.
clearStore()
clearStore():
Promise<void>
Defined in: services/SnapshotService.ts:461
Clears all snapshots for the current tenant.
Returns
Promise<void>
closeConnection()
closeConnection():
Promise<void>
Defined in: services/SnapshotService.ts:470
Closes the database connection pool.
Returns
Promise<void>