Skip to main content

@idpass/data-collect-core / EventUpcasterService

Class: EventUpcasterService

Defined in: services/EventUpcasterService.ts:89

Service for managing event schema version migrations (upcasting).

When event schemas evolve over time, stored events may contain data in older formats. The EventUpcasterService applies a chain of transformations to bring event data from its stored schema version up to the current version before the event is applied to an entity.

Key behaviors:

  • Upcasters form a sequential chain: v1->v2, v2->v3, v3->v4, etc.
  • Events with no schemaVersion (undefined) are treated as version 1.
  • Event types with no registered upcasters pass data through unchanged.
  • Upcasters are pure functions that return new objects without mutating input.
  • Duplicate registrations (same eventType + fromVersion) throw an error.

Example​

const upcasterService = new EventUpcasterService();

upcasterService.registerUpcaster({
  eventType: "create-individual",
  fromVersion: 1,
  toVersion: 2,
  upcast(data) {
    return { ...data, fullName: data.name };
  },
});

// Upcast a v1 event to v2
const upcastedData = upcasterService.upcastEvent("create-individual", 1, { name: "Alice" });
// Result: { name: "Alice", fullName: "Alice" }

Constructors​

Constructor​

new EventUpcasterService(): EventUpcasterService

Returns​

EventUpcasterService

Methods​

registerUpcaster()​

registerUpcaster(upcaster): void

Defined in: services/EventUpcasterService.ts:99

Registers an upcaster for a specific event type and version transition.

Parameters​

upcaster​

EventUpcaster

The upcaster to register.

Returns​

void

Throws​

If an upcaster is already registered for the same eventType + fromVersion.

validateAllChains()​

validateAllChains(): void

Defined in: services/EventUpcasterService.ts:133

Validates all registered upcaster chains and throws if any have version gaps.

Should be called after all upcasters have been registered (e.g., at application startup) to catch configuration errors early.

Returns​

void

Throws​

If any event type has gaps in its upcaster chain.

finalizeRegistration()​

finalizeRegistration(): void

Defined in: services/EventUpcasterService.ts:153

Finalizes upcaster registration by validating all chains.

Call this after all upcasters have been registered to catch configuration errors (e.g., version gaps) at startup rather than at runtime.

Returns​

void

Throws​

If any event type has gaps in its upcaster chain.

getCurrentVersion()​

getCurrentVersion(eventType): number

Defined in: services/EventUpcasterService.ts:166

Returns the current (highest) schema version for an event type.

If no upcasters are registered for the event type, returns 1 (the implicit default version).

Parameters​

eventType​

string

The event type to query.

Returns​

number

The current schema version number.

upcastEvent()​

upcastEvent(eventType, schemaVersion, eventData): Record<string, unknown>

Defined in: services/EventUpcasterService.ts:195

Upcasts event data from its stored schema version to the current version.

Applies the full chain of upcasters sequentially, starting from the stored version up to the current version. If no upcasters are registered for the event type, or the event is already at the current version, the data is returned unchanged (but as a new object).

Parameters​

eventType​

string

The event type (e.g., "create-individual").

schemaVersion​

The stored schema version. Undefined is treated as version 1.

number | undefined

eventData​

Record<string, unknown>

The event data payload to upcast.

Returns​

Record<string, unknown>

The upcasted event data (always a new object, input is never mutated).

validateChain()​

validateChain(eventType): object

Defined in: services/EventUpcasterService.ts:247

Validates the upcaster chain for a given event type.

Checks that the chain has no gaps: every version from the lowest fromVersion to the highest toVersion has a corresponding upcaster. A gap means there is a missing upcaster for some intermediate version.

Parameters​

eventType​

string

The event type to validate.

Returns​

object

An object with:

  • valid: true if the chain is complete with no gaps.
  • gaps: array of fromVersion numbers that are missing.
  • versions: array of all version numbers referenced (fromVersions + final toVersion).
valid​

valid: boolean

gaps​

gaps: number[]

versions​

versions: number[]