@idpass/data-collect-core / EventStoreImpl
Class: EventStoreImpl
Defined in: components/EventStore.ts:179
Event store implementation providing tamper-evident event sourcing with hash chain integrity.
The EventStoreImpl is the core component for managing immutable event storage with cryptographic integrity verification. It uses an incremental hash chain where each event's hash includes the previous event's hash, providing O(1) append and O(n) full verification.
Key features:
- Immutable Event Storage: All events are stored as immutable records.
- Hash Chain Integrity: Each event hash includes the previous event's hash for tamper detection.
- Audit Trail Management: Complete audit logging for compliance and debugging.
- Sync Coordination: Timestamp tracking for multiple sync operations.
- Pagination Support: Efficient handling of large event datasets.
- Tamper Detection: Cryptographic detection of unauthorized modifications.
Architecture:
- Uses pluggable storage adapters for different persistence backends.
- Maintains the latest hash in the chain in memory for O(1) verification.
- Implements event sourcing patterns with append-only semantics.
- Supports multiple sync levels (LOCAL, REMOTE, EXTERNAL).
Examples
Basic usage:
const eventStore = new EventStoreImpl(storageAdapter);
await eventStore.initialize();
// Save an event
const eventId = await eventStore.saveEvent({
guid: 'event-456',
entityGuid: 'person-789',
type: 'create-individual',
data: { name: 'John Doe', age: 30 },
timestamp: new Date().toISOString(),
userId: 'user-123',
syncLevel: SyncLevel.LOCAL
});
// Verify integrity
const isValid = await eventStore.verifyHashChain();
Sync operations:
const lastSync = await eventStore.getLastRemoteSyncTimestamp();
const newEvents = await eventStore.getEventsSince(lastSync);
if (newEvents.length > 0) {
await eventStore.setLastRemoteSyncTimestamp(new Date().toISOString());
}
Implements
Constructors
Constructor
new EventStoreImpl(
storageAdapter,upcasterService?):EventStoreImpl
Defined in: components/EventStore.ts:194
Creates a new EventStoreImpl instance.
Parameters
storageAdapter
Storage adapter for persistence (IndexedDB, PostgreSQL, etc.).
upcasterService?
Optional upcaster service. When provided, saved events are stamped with the current schema version for their event type.
Returns
EventStoreImpl
Methods
updateSyncLevelFromEvents()
updateSyncLevelFromEvents(
events):Promise<void>
Defined in: components/EventStore.ts:205
Updates sync levels for multiple events.
Parameters
events
Array of form submissions to update.
Returns
Promise<void>
A Promise that resolves when sync levels are updated.
Implementation of
EventStore.updateSyncLevelFromEvents
closeConnection()
closeConnection():
Promise<void>
Defined in: components/EventStore.ts:214
Closes database connections and cleans up resources.
Returns
Promise<void>
A Promise that resolves when the connection is closed.
Implementation of
initialize()
initialize():
Promise<void>
Defined in: components/EventStore.ts:224
Initializes the event store and computes the hash chain from existing events.
Returns
Promise<void>
A Promise that resolves when the store is initialized.
Throws
When storage initialization fails.
Implementation of
saveEvent()
saveEvent(
form):Promise<string>
Defined in: components/EventStore.ts:295
Saves an event and extends the hash chain.
Parameters
form
Form submission/event to save.
Returns
Promise<string>
Unique identifier for the saved event.
Throws
When event storage fails.
Implementation of
getEvents()
getEvents():
Promise<FormSubmission[]>
Defined in: components/EventStore.ts:326
Retrieves all events from the event store.
Returns
Promise<FormSubmission[]>
Array of all form submissions/events.
Implementation of
getAllEvents()
getAllEvents():
Promise<FormSubmission[]>
Defined in: components/EventStore.ts:335
Retrieves all events in the store.
Returns
Promise<FormSubmission[]>
Array of all form submissions/events.
Implementation of
isEventExisted()
isEventExisted(
guid):Promise<boolean>
Defined in: components/EventStore.ts:345
Checks if an event with the given GUID exists.
Parameters
guid
string
The GUID of the event to check.
Returns
Promise<boolean>
true if the event exists, false otherwise.
Implementation of
getLatestHash()
getLatestHash():
string
Defined in: components/EventStore.ts:357
Gets the latest hash in the hash chain for integrity verification.
The hash represents the cryptographic fingerprint of all events in the store. Any modification to any event will cause the chain to break.
Returns
string
SHA256 hash of the latest chain link, or empty string if no events.
Implementation of
verifyHashChain()
verifyHashChain():
Promise<boolean>
Defined in: components/EventStore.ts:369
Verifies the integrity of the entire event hash chain.
Walks through all events and recomputes the hash chain from scratch. If the recomputed hash matches the stored latest hash, the chain is intact.
Returns
Promise<boolean>
true if the chain is intact, false if tampering is detected.
Implementation of
logAuditEntry()
logAuditEntry(
entry):Promise<void>
Defined in: components/EventStore.ts:384
Logs a single audit entry.
Parameters
entry
The audit log entry to save.
Returns
Promise<void>
A Promise that resolves when the entry is logged.
Implementation of
saveAuditLogs()
saveAuditLogs(
entries):Promise<void>
Defined in: components/EventStore.ts:394
Saves multiple audit log entries.
Parameters
entries
An array of audit log entries to save.
Returns
Promise<void>
A Promise that resolves when entries are saved.
Implementation of
clearStore()
clearStore():
Promise<void>
Defined in: components/EventStore.ts:403
Clears all data from the store (for testing).
Returns
Promise<void>
A Promise that resolves when the store is cleared.
Implementation of
deleteEventsForEntity()
deleteEventsForEntity(
entityGuid):Promise<number>
Defined in: components/EventStore.ts:422
Deletes all events whose entityGuid matches the given guid.
Delegates to the underlying storage adapter. Used during client-side scope-purge — see EventStorageAdapter.deleteEventsForEntity.
Note: Purge does NOT extend the hash chain. It is a local data- minimization operation, so the chain anchor is intentionally not updated; a subsequent rebuildHashChain on the next initialize would recompute from remaining events if needed.
Parameters
entityGuid
string
The entity guid whose events should be removed.
Returns
Promise<number>
The number of events deleted.
Implementation of
EventStore.deleteEventsForEntity
updateEventSyncLevel()
updateEventSyncLevel(
id,syncLevel):Promise<void>
Defined in: components/EventStore.ts:433
Updates the sync level of an event.
Parameters
id
string
The ID of the event to update.
syncLevel
The new sync level.
Returns
Promise<void>
A Promise that resolves when the sync level is updated.
Implementation of
EventStore.updateEventSyncLevel
updateAuditLogSyncLevel()
updateAuditLogSyncLevel(
entityId,syncLevel):Promise<void>
Defined in: components/EventStore.ts:444
Updates the sync level of an audit log entry.
Parameters
entityId
string
The ID of the entity associated with the audit log.
syncLevel
The new sync level.
Returns
Promise<void>
A Promise that resolves when the sync level is updated.
Implementation of
EventStore.updateAuditLogSyncLevel
getEventsSince()
getEventsSince(
timestamp):Promise<FormSubmission[]>
Defined in: components/EventStore.ts:454
Retrieves events created since a specific timestamp.
Parameters
timestamp
string | Date
The timestamp to filter events from.
Returns
Promise<FormSubmission[]>
An array of events created after the specified timestamp.
Implementation of
getEventsSincePagination()
getEventsSincePagination(
timestamp,limit):Promise<{events:FormSubmission[];nextCursor:string|Date|null; }>
Defined in: components/EventStore.ts:465
Retrieves events since a timestamp with pagination support.
Parameters
timestamp
string | Date
The timestamp to filter events from.
limit
number
The maximum number of events to return (default: 10).
Returns
Promise<{ events: FormSubmission[]; nextCursor: string | Date | null; }>
An object with an events array and a nextCursor for the next page.
Implementation of
EventStore.getEventsSincePagination
getAuditLogsSince()
getAuditLogsSince(
timestamp):Promise<AuditLogEntry[]>
Defined in: components/EventStore.ts:478
Retrieves audit logs created since a specific timestamp.
Parameters
timestamp
string
The timestamp to filter audit logs from.
Returns
Promise<AuditLogEntry[]>
An array of audit log entries created after the specified timestamp.
Implementation of
getLastRemoteSyncTimestamp()
getLastRemoteSyncTimestamp():
Promise<string>
Defined in: components/EventStore.ts:487
Retrieves the timestamp of the last remote synchronization.
Returns
Promise<string>
A Promise that resolves with the timestamp string.
Implementation of
EventStore.getLastRemoteSyncTimestamp
setLastRemoteSyncTimestamp()
setLastRemoteSyncTimestamp(
timestamp):Promise<void>
Defined in: components/EventStore.ts:497
Sets the timestamp of the last remote synchronization.
Parameters
timestamp
string
The timestamp string to set.
Returns
Promise<void>
A Promise that resolves when the timestamp is set.
Implementation of
EventStore.setLastRemoteSyncTimestamp
getLastLocalSyncTimestamp()
getLastLocalSyncTimestamp():
Promise<string>
Defined in: components/EventStore.ts:506
Retrieves the timestamp of the last local synchronization.
Returns
Promise<string>
A Promise that resolves with the timestamp string.
Implementation of
EventStore.getLastLocalSyncTimestamp
setLastLocalSyncTimestamp()
setLastLocalSyncTimestamp(
timestamp):Promise<void>
Defined in: components/EventStore.ts:516
Sets the timestamp of the last local synchronization.
Parameters
timestamp
string
The timestamp string to set.
Returns
Promise<void>
A Promise that resolves when the timestamp is set.
Implementation of
EventStore.setLastLocalSyncTimestamp
getLastPullExternalSyncTimestamp()
getLastPullExternalSyncTimestamp():
Promise<string>
Defined in: components/EventStore.ts:525
Retrieves the timestamp of the last external sync pull operation.
Returns
Promise<string>
A Promise that resolves with the timestamp string.
Implementation of
EventStore.getLastPullExternalSyncTimestamp
setLastPullExternalSyncTimestamp()
setLastPullExternalSyncTimestamp(
timestamp):Promise<void>
Defined in: components/EventStore.ts:535
Sets the timestamp of the last external sync pull operation.
Parameters
timestamp
string
The timestamp string to set.
Returns
Promise<void>
A Promise that resolves when the timestamp is set.
Implementation of
EventStore.setLastPullExternalSyncTimestamp
getLastPushExternalSyncTimestamp()
getLastPushExternalSyncTimestamp():
Promise<string>
Defined in: components/EventStore.ts:544
Retrieves the timestamp of the last external sync push operation.
Returns
Promise<string>
A Promise that resolves with the timestamp string.
Implementation of
EventStore.getLastPushExternalSyncTimestamp
setLastPushExternalSyncTimestamp()
setLastPushExternalSyncTimestamp(
timestamp):Promise<void>
Defined in: components/EventStore.ts:554
Sets the timestamp of the last external sync push operation.
Parameters
timestamp
string
The timestamp string to set.
Returns
Promise<void>
A Promise that resolves when the timestamp is set.
Implementation of
EventStore.setLastPushExternalSyncTimestamp
getLastScopeHash()
getLastScopeHash():
Promise<string|null>
Defined in: components/EventStore.ts:563
Retrieves the last advertised scope hash from the server.
Returns
Promise<string | null>
The hash string, or null when no scope has been observed yet.
Implementation of
setLastScopeHash()
setLastScopeHash(
hash):Promise<void>
Defined in: components/EventStore.ts:573
Persists the latest scope hash advertised by the server.
Parameters
hash
string
The hash string to persist.
Returns
Promise<void>
A Promise that resolves when the hash is persisted.
Implementation of
getLastScope()
getLastScope():
Promise<EffectiveScopeBody|null>
Defined in: components/EventStore.ts:582
Retrieves the last persisted effective scope body, or null if none.
Returns
Promise<EffectiveScopeBody | null>
A Promise that resolves with the parsed scope body, or null if absent.
Implementation of
setLastScope()
setLastScope(
scope):Promise<void>
Defined in: components/EventStore.ts:592
Persists the latest effective scope body advertised by the server.
Parameters
scope
The effective scope body to persist.
Returns
Promise<void>
A Promise that resolves when the body is persisted.
Implementation of
getAuditTrailByEntityGuid()
getAuditTrailByEntityGuid(
entityGuid):Promise<AuditLogEntry[]>
Defined in: components/EventStore.ts:602
Retrieves the complete audit trail for a specific entity.
Parameters
entityGuid
string
The global unique identifier of the entity.
Returns
Promise<AuditLogEntry[]>
An array of audit log entries in chronological order.
Implementation of
EventStore.getAuditTrailByEntityGuid
getMetadataValue()
getMetadataValue(
key):Promise<string|null>
Defined in: components/EventStore.ts:612
Read a generic metadata value scoped to this store's tenant. Returns
null when the key is absent.
Parameters
key
string
The metadata key.
Returns
Promise<string | null>
Implementation of
setMetadataValue()
setMetadataValue(
key,value):Promise<void>
Defined in: components/EventStore.ts:622
Persist (upsert) a metadata value under key.
Parameters
key
string
The metadata key.
value
string
The value to store.
Returns
Promise<void>
Implementation of
deleteMetadataValue()
deleteMetadataValue(
key):Promise<void>
Defined in: components/EventStore.ts:631
Delete the metadata row for key. No-op if absent.
Parameters
key
string
The metadata key to remove.
Returns
Promise<void>
Implementation of
EventStore.deleteMetadataValue
listMetadataKeys()
listMetadataKeys(
prefix):Promise<string[]>
Defined in: components/EventStore.ts:640
List metadata keys whose name starts with prefix (tenant-scoped).
Parameters
prefix
string
Key prefix to filter on.
Returns
Promise<string[]>