@idpass/data-collect-core / EventStoreImpl

Class: EventStoreImpl

Defined in: components/EventStore.ts:178

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

• EventStore

Constructors

Constructor

new EventStoreImpl(storageAdapter, upcasterService?): EventStoreImpl

Defined in: components/EventStore.ts:193

Creates a new EventStoreImpl instance.

Parameters

storageAdapter

EventStorageAdapter

Storage adapter for persistence (IndexedDB, PostgreSQL, etc.).

upcasterService?

EventUpcasterService

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:204

Updates sync levels for multiple events.

Parameters

events

FormSubmission[]

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:213

Closes database connections and cleans up resources.

Returns

Promise<void>

A Promise that resolves when the connection is closed.

Implementation of

EventStore.closeConnection

---

initialize()

initialize(): Promise<void>

Defined in: components/EventStore.ts:223

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

EventStore.initialize

---

saveEvent()

saveEvent(form): Promise<string>

Defined in: components/EventStore.ts:289

Saves an event and extends the hash chain.

Parameters

form

FormSubmission

Form submission/event to save.

Returns

Promise<string>

Unique identifier for the saved event.

Throws

When event storage fails.

Implementation of

EventStore.saveEvent

---

getEvents()

getEvents(): Promise<FormSubmission[]>

Defined in: components/EventStore.ts:320

Retrieves all events from the event store.

Returns

Promise<FormSubmission[]>

Array of all form submissions/events.

Implementation of

EventStore.getEvents

---

getAllEvents()

getAllEvents(): Promise<FormSubmission[]>

Defined in: components/EventStore.ts:329

Retrieves all events in the store.

Returns

Promise<FormSubmission[]>

Array of all form submissions/events.

Implementation of

EventStore.getAllEvents

---

isEventExisted()

isEventExisted(guid): Promise<boolean>

Defined in: components/EventStore.ts:339

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

EventStore.isEventExisted

---

getLatestHash()

getLatestHash(): string

Defined in: components/EventStore.ts:351

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

EventStore.getLatestHash

---

verifyHashChain()

verifyHashChain(): Promise<boolean>

Defined in: components/EventStore.ts:363

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

EventStore.verifyHashChain

---

logAuditEntry()

logAuditEntry(entry): Promise<void>

Defined in: components/EventStore.ts:378

Logs a single audit entry.

Parameters

entry

AuditLogEntry

The audit log entry to save.

Returns

Promise<void>

A Promise that resolves when the entry is logged.

Implementation of

EventStore.logAuditEntry

---

saveAuditLogs()

saveAuditLogs(entries): Promise<void>

Defined in: components/EventStore.ts:388

Saves multiple audit log entries.

Parameters

entries

AuditLogEntry[]

An array of audit log entries to save.

Returns

Promise<void>

A Promise that resolves when entries are saved.

Implementation of

EventStore.saveAuditLogs

---

clearStore()

clearStore(): Promise<void>

Defined in: components/EventStore.ts:397

Clears all data from the store (for testing).

Returns

Promise<void>

A Promise that resolves when the store is cleared.

Implementation of

EventStore.clearStore

---

updateEventSyncLevel()

updateEventSyncLevel(id, syncLevel): Promise<void>

Defined in: components/EventStore.ts:409

Updates the sync level of an event.

Parameters

id

string

The ID of the event to update.

syncLevel

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:420

Updates the sync level of an audit log entry.

Parameters

entityId

string

The ID of the entity associated with the audit log.

syncLevel

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:430

Retrieves events created since a specific timestamp.

Parameters

timestamp

The timestamp to filter events from.

string | Date

Returns

Promise<FormSubmission[]>

An array of events created after the specified timestamp.

Implementation of

EventStore.getEventsSince

---

getEventsSincePagination()

getEventsSincePagination(timestamp, limit): Promise<{ events: FormSubmission[]; nextCursor: string | Date | null; }>

Defined in: components/EventStore.ts:441

Retrieves events since a timestamp with pagination support.

Parameters

timestamp

The timestamp to filter events from.

string | Date

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:454

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

EventStore.getAuditLogsSince

---

getLastRemoteSyncTimestamp()

getLastRemoteSyncTimestamp(): Promise<string>

Defined in: components/EventStore.ts:463

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:473

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:482

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:492

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:501

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:511

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:520

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:530

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

---

getAuditTrailByEntityGuid()

getAuditTrailByEntityGuid(entityGuid): Promise<AuditLogEntry[]>

Defined in: components/EventStore.ts:540

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