Event Mapping

The event mapping utilities convert between Nimbus events and EventSourcingDB events. When writing events, Nimbus metadata (correlation ID, data schema) is preserved alongside the payload. When reading events back, the original Nimbus event structure is restored.

How Events Are Stored

When a Nimbus event is written to EventSourcingDB, its data field is wrapped in a structure that preserves Nimbus-specific metadata:

// Original Nimbus event data
{
    email: "john@example.com",
    firstName: "John",
    lastName: "Doe",
}

// Stored in EventSourcingDB as
{
    payload: {
        email: "john@example.com",
        firstName: "John",
        lastName: "Doe",
    },
    nimbusMeta: {
        correlationid: "01JKXYZ...",
        dataschema: "https://example.com/schemas/user-invited",
    },
}

Types

EventData

The wrapper structure used to store Nimbus events in EventSourcingDB:

type EventData = {
    payload: Record<string, unknown>;
    nimbusMeta: NimbusEventMetadata;
};

NimbusEventMetadata

Metadata that Nimbus attaches to events stored in EventSourcingDB:

type NimbusEventMetadata = {
    correlationid: string;
    dataschema?: string;
};

Converting Nimbus Events to EventSourcingDB

The nimbusEventToEventSourcingDBEventCandidate function converts a Nimbus event into an EventSourcingDB event candidate:

import { nimbusEventToEventSourcingDBEventCandidate } from "@nimbus/eventsourcingdb";

const eventCandidate = nimbusEventToEventSourcingDBEventCandidate(nimbusEvent);

The conversion maps the following properties:

Nimbus Event	EventSourcingDB Event Candidate
source	source
subject	subject
type	type
data	data.payload
correlationid	data.nimbusMeta.correlationid
dataschema	data.nimbusMeta.dataschema

TIP

You typically don't need to call this function directly. The writeEvents function handles the conversion internally.

Converting EventSourcingDB Events to Nimbus

The eventSourcingDBEventToNimbusEvent function converts an EventSourcingDB event back into a Nimbus event:

import { eventSourcingDBEventToNimbusEvent } from "@nimbus/eventsourcingdb";
import type { Event } from "eventsourcingdb";

const handleEvent = (eventSourcingDBEvent: Event) => {
    const nimbusEvent = eventSourcingDBEventToNimbusEvent(eventSourcingDBEvent);

    console.log(nimbusEvent.correlationid); // Restored from nimbusMeta
    console.log(nimbusEvent.data); // Original payload
};

The function supports generic typing for specific event types:

import { Event } from "@nimbus/core";
import { eventSourcingDBEventToNimbusEvent } from "@nimbus/eventsourcingdb";

const event = eventSourcingDBEventToNimbusEvent<Event>(eventSourcingDBEvent);

Handling Non-Nimbus Events

If the EventSourcingDB event was not written by Nimbus (i.e., it does not contain the nimbusMeta wrapper), the function gracefully handles this by:

• Treating the entire data field as the payload
• Generating a new correlation ID using ULID

Type Guard

The isEventData type guard checks whether event data conforms to the EventData structure:

import { isEventData } from "@nimbus/eventsourcingdb";

if (isEventData(event.data)) {
    // event.data is typed as EventData
    console.log(event.data.payload);
    console.log(event.data.nimbusMeta.correlationid);
}