web / lib/services/id-generation

lib/services/id-generation

Provides a service for generating unique identifiers for events.

This service is responsible for creating consistent and unique IDs for event records based on a dataset’s configured ID strategy. It supports several strategies:

external: Uses a unique ID provided in the source data.
computed: Generates a hash from a specified set of fields in the data.
auto: Generates a unique ID and a content hash for duplicate detection.
hybrid: Attempts to use an external ID first and falls back to a computed ID.

The service includes helpers for extracting values from nested objects and sanitizing IDs.

Classes

IdGenerationService

Constructors

Constructor

new IdGenerationService(): IdGenerationService

Returns

IdGenerationService

Methods

generateEventId()

static generateEventId(data, dataset): object

Parameters

data

unknown

dataset

Dataset

Returns

object

uniqueId

uniqueId: string

sourceId?

optional sourceId: string

contentHash?

optional contentHash: string

strategy

strategy: string

error?

optional error: string

Functions

generateUniqueId()

generateUniqueId(data, idStrategy): string

Parameters

data

unknown

idStrategy

{ type: "external" \| "computed" \| "auto" \| "hybrid"; externalIdPath?: string \| null; computedIdFields?: object[] \| null; duplicateStrategy?: "update" \| "version" \| "skip" \| null; }

type

"external" | "computed" | "auto" | "hybrid"

How to generate unique IDs for events

externalIdPath?

string | null

JSON path to ID field (e.g., ‘id’ or ‘metadata.uuid’)

computedIdFields?

object[] | null

Fields to combine for unique hash

duplicateStrategy?

"update" | "version" | "skip" | null

What to do when duplicate is found

| undefined

Returns

string