@idpass/data-collect-core / IndexedDbEventStorageAdapter

Class: IndexedDbEventStorageAdapter

Defined in: storage/IndexedDbEventStorageAdapter.ts:68

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

• EventStorageAdapter

Constructors

Constructor

new IndexedDbEventStorageAdapter(tenantId?): IndexedDbEventStorageAdapter

Defined in: storage/IndexedDbEventStorageAdapter.ts:72

Parameters

tenantId?

string = ""

Returns

IndexedDbEventStorageAdapter

Properties

tenantId

readonly tenantId: string = ""

Defined in: storage/IndexedDbEventStorageAdapter.ts:72

Methods

closeConnection()

closeConnection(): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:83

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

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

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

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

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

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

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

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

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

Retrieves events that have occurred since a specified timestamp.

Parameters

timestamp

string | Date

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

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

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

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

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

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

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

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

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

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

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

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

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

---

getLastScopeHash()

getLastScopeHash(): Promise<string | null>

Defined in: storage/IndexedDbEventStorageAdapter.ts:726

Retrieves the last advertised scope hash from the server, or null if never seen.

Returns

Promise<string | null>

A Promise that resolves with the scope hash string, or null if no hash exists.

Throws

If IndexedDB is not initialized or the retrieval operation fails.

Implementation of

EventStorageAdapter.getLastScopeHash

---

setLastScopeHash()

setLastScopeHash(hash): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:748

Persists the latest scope hash (called after a successful pull).

Parameters

hash

string

The scope hash string to save.

Returns

Promise<void>

A Promise that resolves when the hash is successfully saved.

Throws

If IndexedDB is not initialized or the save operation fails.

Implementation of

EventStorageAdapter.setLastScopeHash

---

getLastScope()

getLastScope(): Promise<EffectiveScopeBody | null>

Defined in: storage/IndexedDbEventStorageAdapter.ts:769

Retrieves the last persisted effective scope body (areaIds/entityTypes/timeWindow + hash), or null if none has been observed yet. Stored as a JSON string under the "scope_body" key in the syncTimestamp object store.

Returns

Promise<EffectiveScopeBody | null>

A Promise that resolves with the parsed scope body, or null if absent.

Throws

If IndexedDB is not initialized or the retrieval fails.

Implementation of

EventStorageAdapter.getLastScope

---

setLastScope()

setLastScope(scope): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:803

Persists the latest effective scope body advertised by the server. Called after a successful pull, alongside setLastScopeHash. The body is stored as a JSON string under the "scope_body" key in the syncTimestamp object store. Resolves on transaction.oncomplete so callers see the write committed before the Promise settles.

Parameters

scope

EffectiveScopeBody

The effective scope body to persist.

Returns

Promise<void>

A Promise that resolves when the body is successfully saved.

Throws

If IndexedDB is not initialized or the save operation fails.

Implementation of

EventStorageAdapter.setLastScope

---

deleteEventsForEntity()

deleteEventsForEntity(entityGuid): Promise<number>

Defined in: storage/IndexedDbEventStorageAdapter.ts:829

Deletes all events whose entityGuid matches the given guid.

Used during client-side scope-purge — when an entity falls outside the effective sync scope, its events would otherwise be orphans. This is a local data-minimization operation; it does NOT generate delete-entity events and is invisible to the server.

Parameters

entityGuid

string

The entity guid whose events should be removed.

Returns

Promise<number>

A Promise that resolves with the number of events deleted.

Throws

If IndexedDB is not initialized or the deletion fails.

Implementation of

EventStorageAdapter.deleteEventsForEntity

---

isEventExisted()

isEventExisted(guid): Promise<boolean>

Defined in: storage/IndexedDbEventStorageAdapter.ts:861

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

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

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

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

---

getMetadataValue()

getMetadataValue(key): Promise<string | null>

Defined in: storage/IndexedDbEventStorageAdapter.ts:970

Generic key-value metadata accessor. Reuses the existing syncTimestamp object store, which is already a { id, value } key/value table — the same store that holds scope-hash, push-watermark, hash-anchor, etc. Returns null when the key is absent (do not return empty-string sentinel — empty string is a legitimate stored value).

Parameters

key

string

The metadata key.

Returns

Promise<string | null>

The stored value, or null if the key does not exist.

Implementation of

EventStorageAdapter.getMetadataValue

---

setMetadataValue()

setMetadataValue(key, value): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:993

Persist (upsert) a metadata value under key in the syncTimestamp store. Resolves on transaction.oncomplete so callers see the write committed before the Promise settles.

Parameters

key

string

The metadata key.

value

string

The value to store.

Returns

Promise<void>

Implementation of

EventStorageAdapter.setMetadataValue

---

deleteMetadataValue()

deleteMetadataValue(key): Promise<void>

Defined in: storage/IndexedDbEventStorageAdapter.ts:1012

Delete the metadata row for key. No-op if absent. Resolves on transaction.oncomplete.

Parameters

key

string

The metadata key to remove.

Returns

Promise<void>

Implementation of

EventStorageAdapter.deleteMetadataValue

---

listMetadataKeys()

listMetadataKeys(prefix): Promise<string[]>

Defined in: storage/IndexedDbEventStorageAdapter.ts:1036

List metadata keys whose name starts with prefix. Uses a key-range cursor over the syncTimestamp object store (whose keyPath is id) so the scan visits only the prefix-matching subset of the keyspace instead of walking every row. The upper bound prefix + "￿" exploits the fact that no DataCollect-issued metadata key contains U+FFFF.

Resolves on transaction.oncomplete.

Parameters

prefix

string

Key prefix to filter on (e.g. "cr:").

Returns

Promise<string[]>

Implementation of

EventStorageAdapter.listMetadataKeys