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 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.
  • Audit Trail Management: Complete audit logging for compliance and debugging.
  • Sync Coordination: Timestamp tracking for multiple sync operations (local, remote, external).
  • Pagination Support: Efficient handling of large event datasets.
  • Tamper Detection: Cryptographic detection of unauthorized modifications via hash chains.

Architecture:

  • Uses IndexedDB object stores for events, audit logs, 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/data-collect-core';

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

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

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

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

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

clearStore()​

clearStore(): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:257

Clears all data from the events and audit log 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:283

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

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

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(cursor, pageSize?): Promise<{ events: FormSubmission[]; nextCursor: string | Date | null; }>

Defined in: storage/IndexedDbEventStorageAdapter.ts:391

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

Parameters​

cursor​

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

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

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

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

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

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

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

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

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

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

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

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

persistHashAnchor()​

persistHashAnchor(hash): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:752

Persists the latest hash anchor for tamper detection on restart.

Parameters​

hash​

string

The hash string to persist.

Returns​

Promise<void>

A Promise that resolves when the hash is persisted.

Implementation of​

EventStorageAdapter.persistHashAnchor

getPersistedHashAnchor()​

getPersistedHashAnchor(): Promise<string | null>

Defined in: storage/IndexedDbEventStorageAdapter.ts:772

Retrieves the previously persisted hash anchor, or null if none exists.

Returns​

Promise<string | null>

The persisted hash string, or null if no anchor has been saved.

Implementation of​

EventStorageAdapter.getPersistedHashAnchor

getAuditTrailByEntityGuid()​

getAuditTrailByEntityGuid(entityGuid): Promise<AuditLogEntry[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:796

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