Skip to main content

@idpass/data-collect-core / IndexedDbEventStorageAdapter

Class: IndexedDbEventStorageAdapter

Defined in: storage/IndexedDbEventStorageAdapter.ts:67

IndexedDB implementation of the EventStorageAdapter for browser-based event persistence.

This adapter provides tamper-evident event storage using the browser's IndexedDB API. It ensures the integrity of the event log through cryptographic methods (e.g., Merkle trees) and supports various event sourcing operations like audit trails, sync timestamp management, and efficient event retrieval.

Key features:

  • Immutable Event Storage: All events are stored as immutable records.
  • Merkle Tree Integrity: Cryptographic verification of event integrity using SHA256.
  • Audit Trail Management: Complete audit logging for compliance and debugging.
  • Sync Coordination: Timestamp tracking for multiple sync operations (local, remote, external).
  • Event Verification: Merkle proof generation and verification (though Merkle proof generation/verification logic is handled by EventStore, this adapter provides the storage for Merkle roots).
  • Pagination Support: Efficient handling of large event datasets.
  • Tamper Detection: Cryptographic detection of unauthorized modifications.

Architecture:

  • Uses IndexedDB object stores for events, audit logs, Merkle roots, and sync timestamps.
  • Employs multiple indexes for efficient querying of events and audit logs by GUID, entity GUID, and timestamp.
  • Provides ACID transaction support for data consistency.
  • Supports both single and multi-tenant deployments by prefixing database names with the tenant ID.

Example​

Basic usage:

import { IndexedDbEventStorageAdapter } from '@idpass/idpass-data-collect';

const adapter = new IndexedDbEventStorageAdapter('tenant-123');
await adapter.initialize();

// Save events
const eventsToSave = [{ guid: 'event-1', entityGuid: 'entity-1', timestamp: new Date().toISOString(), type: 'create-entity', data: {} }];
await adapter.saveEvents(eventsToSave);

// Retrieve events
const allEvents = await adapter.getEvents();
console.log('All events:', allEvents);

// Set and get sync timestamp
await adapter.setLastRemoteSyncTimestamp(new Date().toISOString());
const lastSync = await adapter.getLastRemoteSyncTimestamp();
console.log('Last remote sync:', lastSync);

Implements​

Constructors​

Constructor​

new IndexedDbEventStorageAdapter(tenantId): IndexedDbEventStorageAdapter

Defined in: storage/IndexedDbEventStorageAdapter.ts:71

Parameters​

tenantId​

string = ""

Returns​

IndexedDbEventStorageAdapter

Properties​

tenantId​

readonly tenantId: string = ""

Defined in: storage/IndexedDbEventStorageAdapter.ts:71

Methods​

closeConnection()​

closeConnection(): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:82

Closes the connection to the IndexedDB database.

Returns​

Promise<void>

A Promise that resolves when the connection is closed.

Implementation of​

EventStorageAdapter.closeConnection

initialize()​

initialize(): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:92

Initializes the IndexedDB database, creating object stores and indexes if they don't exist.

Returns​

Promise<void>

A Promise that resolves when the database is successfully initialized.

Throws​

If there is an error opening or upgrading the IndexedDB.

Implementation of​

EventStorageAdapter.initialize

saveEvents()​

saveEvents(events): Promise<string[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:134

Saves an array of FormSubmission events to the event store.

Parameters​

events​

FormSubmission[]

An array of FormSubmission objects to save.

Returns​

Promise<string[]>

A Promise that resolves with an array of GUIDs of the saved events.

Throws​

If IndexedDB is not initialized or the save operation fails.

Implementation of​

EventStorageAdapter.saveEvents

getEvents()​

getEvents(): Promise<FormSubmission[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:162

Retrieves all FormSubmission events from the event store.

Returns​

Promise<FormSubmission[]>

A Promise that resolves with an array of all FormSubmission events.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getEvents

saveAuditLog()​

saveAuditLog(entries): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:195

Saves an array of AuditLogEntry entries to the audit log store.

Parameters​

entries​

AuditLogEntry[]

An array of AuditLogEntry objects to save.

Returns​

Promise<void>

A Promise that resolves when the audit log entries are successfully saved.

Throws​

If IndexedDB is not initialized or the save operation fails.

Implementation of​

EventStorageAdapter.saveAuditLog

getAuditLog()​

getAuditLog(): Promise<AuditLogEntry[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:218

Retrieves all AuditLogEntry entries from the audit log store.

Returns​

Promise<AuditLogEntry[]>

A Promise that resolves with an array of all AuditLogEntry entries.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getAuditLog

saveMerkleRoot()​

saveMerkleRoot(root): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:251

Saves the Merkle root to the Merkle root store.

Parameters​

root​

string

The Merkle root string to save.

Returns​

Promise<void>

A Promise that resolves when the Merkle root is successfully saved.

Throws​

If IndexedDB is not initialized or the save operation fails.

Implementation of​

EventStorageAdapter.saveMerkleRoot

getMerkleRoot()​

getMerkleRoot(): Promise<string>

Defined in: storage/IndexedDbEventStorageAdapter.ts:281

Retrieves the stored Merkle root.

Returns​

Promise<string>

A Promise that resolves with the Merkle root string, or an empty string if no root exists.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getMerkleRoot

clearStore()​

clearStore(): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:305

Clears all data from the events, audit log, and Merkle root stores.

Returns​

Promise<void>

A Promise that resolves when all stores are cleared.

Throws​

If IndexedDB is not initialized or the clear operation fails.

Implementation of​

EventStorageAdapter.clearStore

updateEventSyncLevel()​

updateEventSyncLevel(id, syncLevel): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:337

Updates the syncLevel for events associated with a given entityGuid.

Parameters​

id​

string

The GUID of the event whose sync level needs to be updated.

syncLevel​

SyncLevel

The new SyncLevel to set for the events.

Returns​

Promise<void>

A Promise that resolves when the update is complete.

Throws​

If IndexedDB is not initialized or the update operation fails.

Implementation of​

EventStorageAdapter.updateEventSyncLevel

updateAuditLogSyncLevel()​

updateAuditLogSyncLevel(entityGuId, syncLevel): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:373

Updates the syncLevel for audit log entries associated with a given entityGuid.

Parameters​

entityGuId​

string

The GUID of the entity whose associated audit log entries' sync levels need to be updated.

syncLevel​

SyncLevel

The new SyncLevel to set for the audit log entries.

Returns​

Promise<void>

A Promise that resolves when the update is complete.

Throws​

If IndexedDB is not initialized or the update operation fails.

Implementation of​

EventStorageAdapter.updateAuditLogSyncLevel

getEventsSince()​

getEventsSince(timestamp): Promise<FormSubmission[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:408

Retrieves events that have occurred since a specified timestamp.

Parameters​

timestamp​

The timestamp (ISO 8601 string or Date object) from which to retrieve events (exclusive).

string | Date

Returns​

Promise<FormSubmission[]>

A Promise that resolves with an array of FormSubmission events, sorted by timestamp in ascending order.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getEventsSince

getEventsSincePagination()​

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

Defined in: storage/IndexedDbEventStorageAdapter.ts:445

Retrieves events that have occurred since a specified timestamp with pagination.

Parameters​

timestamp​

The timestamp (ISO 8601 string or Date object) from which to retrieve events (exclusive).

string | Date

pageSize​

number = 10

The maximum number of events to retrieve in a single page. Defaults to 10.

Returns​

Promise<{ events: FormSubmission[]; nextCursor: string | Date | null; }>

A Promise that resolves with an object containing an array of FormSubmission events and the nextCursor for pagination.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getEventsSincePagination

getAuditLogsSince()​

getAuditLogsSince(timestamp): Promise<AuditLogEntry[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:494

Retrieves audit log entries that have occurred since a specified timestamp.

Parameters​

timestamp​

string

The timestamp (ISO 8601 string) from which to retrieve audit logs (exclusive).

Returns​

Promise<AuditLogEntry[]>

A Promise that resolves with an array of AuditLogEntry entries, sorted by timestamp in descending order.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getAuditLogsSince

updateSyncLevelFromEvents()​

updateSyncLevelFromEvents(events): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:528

Updates the sync level for a batch of events based on their GUIDs.

Parameters​

events​

FormSubmission[]

An array of FormSubmission objects, each containing the GUID and the new syncLevel.

Returns​

Promise<void>

A Promise that resolves when all specified events' sync levels are updated.

Throws​

If IndexedDB is not initialized or the update operation fails.

Implementation of​

EventStorageAdapter.updateSyncLevelFromEvents

getLastRemoteSyncTimestamp()​

getLastRemoteSyncTimestamp(): Promise<string>

Defined in: storage/IndexedDbEventStorageAdapter.ts:568

Retrieves the timestamp of the last successful remote synchronization.

Returns​

Promise<string>

A Promise that resolves with the timestamp string, or an empty string if no timestamp exists.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getLastRemoteSyncTimestamp

setLastRemoteSyncTimestamp()​

setLastRemoteSyncTimestamp(timestamp): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:592

Sets the timestamp of the last successful remote synchronization.

Parameters​

timestamp​

string

The timestamp string to save.

Returns​

Promise<void>

A Promise that resolves when the timestamp is successfully saved.

Throws​

If IndexedDB is not initialized or the save operation fails.

Implementation of​

EventStorageAdapter.setLastRemoteSyncTimestamp

getLastLocalSyncTimestamp()​

getLastLocalSyncTimestamp(): Promise<string>

Defined in: storage/IndexedDbEventStorageAdapter.ts:613

Retrieves the timestamp of the last successful local synchronization.

Returns​

Promise<string>

A Promise that resolves with the timestamp string, or an empty string if no timestamp exists.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getLastLocalSyncTimestamp

setLastLocalSyncTimestamp()​

setLastLocalSyncTimestamp(timestamp): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:637

Sets the timestamp of the last successful local synchronization.

Parameters​

timestamp​

string

The timestamp string to save.

Returns​

Promise<void>

A Promise that resolves when the timestamp is successfully saved.

Throws​

If IndexedDB is not initialized or the save operation fails.

Implementation of​

EventStorageAdapter.setLastLocalSyncTimestamp

getLastPullExternalSyncTimestamp()​

getLastPullExternalSyncTimestamp(): Promise<string>

Defined in: storage/IndexedDbEventStorageAdapter.ts:658

Retrieves the timestamp of the last successful external pull synchronization.

Returns​

Promise<string>

A Promise that resolves with the timestamp string, or an empty string if no timestamp exists.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getLastPullExternalSyncTimestamp

setLastPullExternalSyncTimestamp()​

setLastPullExternalSyncTimestamp(timestamp): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:682

Sets the timestamp of the last successful external pull synchronization.

Parameters​

timestamp​

string

The timestamp string to save.

Returns​

Promise<void>

A Promise that resolves when the timestamp is successfully saved.

Throws​

If IndexedDB is not initialized or the save operation fails.

Implementation of​

EventStorageAdapter.setLastPullExternalSyncTimestamp

getLastPushExternalSyncTimestamp()​

getLastPushExternalSyncTimestamp(): Promise<string>

Defined in: storage/IndexedDbEventStorageAdapter.ts:703

Retrieves the timestamp of the last successful external push synchronization.

Returns​

Promise<string>

A Promise that resolves with the timestamp string, or an empty string if no timestamp exists.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getLastPushExternalSyncTimestamp

setLastPushExternalSyncTimestamp()​

setLastPushExternalSyncTimestamp(timestamp): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:727

Sets the timestamp of the last successful external push synchronization.

Parameters​

timestamp​

string

The timestamp string to save.

Returns​

Promise<void>

A Promise that resolves when the timestamp is successfully saved.

Throws​

If IndexedDB is not initialized or the save operation fails.

Implementation of​

EventStorageAdapter.setLastPushExternalSyncTimestamp

isEventExisted()​

isEventExisted(guid): Promise<boolean>

Defined in: storage/IndexedDbEventStorageAdapter.ts:749

Checks if an event with the given GUID exists in the event store.

Parameters​

guid​

string

The GUID of the event to check.

Returns​

Promise<boolean>

A Promise that resolves to true if the event exists, false otherwise.

Throws​

If IndexedDB is not initialized or the operation fails.

Implementation of​

EventStorageAdapter.isEventExisted

getAuditTrailByEntityGuid()​

getAuditTrailByEntityGuid(entityGuid): Promise<AuditLogEntry[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:776

Retrieves the audit trail for a specific entity, identified by its entityGuid.

Parameters​

entityGuid​

string

The GUID of the entity to retrieve the audit trail for.

Returns​

Promise<AuditLogEntry[]>

A Promise that resolves with an array of AuditLogEntry entries, sorted by timestamp in descending order.

Throws​

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of​

EventStorageAdapter.getAuditTrailByEntityGuid