metadata

Purpose

Defines the EventMetadata Zod schema for the distributed tracing and actor context attached to every domain event in the Suaveplan event-sourcing infrastructure. Metadata fields enable correlation of all events produced by a single user action, causation tracing between commands and their resulting events, and multi-tenant scoping of event streams — all without embedding these concerns in domain event payloads.

Features

EventMetadata schema — {correlationId, causationId?, userId?, tenantId?} with strict non-empty validation on all present string fields
correlationId required — enables log correlation and distributed trace aggregation across service boundaries
causationId optional — links this event to the specific command or event that caused it (event sourcing causal chain)
userId optional — identifies the human or service account that triggered the originating action
tenantId optional — scopes the event to a tenant in multi-tenant deployments
Full TypeScript inference via z.infer<> — no manual interface duplication
Zod v4 compatible

Usage: Basic Example

import { EventMetadata } from "@suaveplan/api-schemas/events";

const meta = EventMetadata.parse({
  correlationId: "corr_01J8ZGCZ7ECTFAKEUID123456",
  userId: "user_abc",
});

Usage: Advanced Example

import { EventMetadata } from "@suaveplan/api-schemas/events";

// Build metadata for an event triggered by a command
function buildEventMetadata(
  command: { correlationId: string; id: string },
  ctx: { userId?: string; tenantId?: string }
): EventMetadata {
  return EventMetadata.parse({
    correlationId: command.correlationId,
    causationId: command.id,
    userId: ctx.userId,
    tenantId: ctx.tenantId,
  });
}

API Reference

`EventMetadata`

Zod object schema — event tracing and actor context.

Field	Type	Description
`correlationId`	`string` (min 1)	Ties all events from one user action together
`causationId`	`string` (optional)	ID of the command/event that caused this event
`userId`	`string` (optional)	Actor who triggered the originating action
`tenantId`	`string` (optional)	Tenant scope for multi-tenant deployments

Type export: type EventMetadata = z.infer<typeof EventMetadata>

Implementation Notes

correlationId is the only required field because it is the primary key for grouping related events in log aggregation and tracing systems. All other fields are optional because not every event originates from an identifiable user action (e.g. scheduled jobs, system-initiated events) or requires tenant scoping. Optional fields that are present are validated as non-empty strings to prevent accidentally storing blank identifiers that would pollute trace data.

3.0 KiB Raw Blame History