Event Mapping

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

An in Depth Example

This guide also has an in depth example of a working application built with EventFabric. Combining DDD, CQRS and Event Sourcing.

Check out the In Depth Example page to learn how everything is connected and works out in a real-world application.

How Events Are Stored

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

// Original EventFabric 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 EventFabric events in EventSourcingDB:

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

EventFabricEventMetadata

Metadata that EventFabric attaches to events stored in EventSourcingDB:

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

Converting EventFabric Events to EventSourcingDB

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

import { nimbusEventToEventSourcingDBEventCandidate } from "@eventfabric-cqrs/eventsourcingdb";

const eventCandidate = nimbusEventToEventSourcingDBEventCandidate(nimbusEvent);

The conversion maps the following properties:

EventFabric 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 EventFabric

The eventSourcingDBEventToEventFabricEvent function converts an EventSourcingDB event back into a EventFabric event:

import { eventSourcingDBEventToNimbusEvent } from "@eventfabric-cqrs/eventsourcingdb";
import type { Event } from "eventsourcingdb";

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

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

The function supports generic typing for specific event types:

import { Event } from "@eventfabric-cqrs/core";
import { eventSourcingDBEventToNimbusEvent } from "@eventfabric-cqrs/eventsourcingdb";

const event = eventSourcingDBEventToNimbusEvent<Event>(eventSourcingDBEvent);

Handling Non-EventFabric Events

If the EventSourcingDB event was not written by EventFabric (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 "@eventfabric-cqrs/eventsourcingdb";

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