skills/docs/networking/events/event-sourcing/src/schemas/event-sourcing.schemas.md

event-sourcing.schemas

(no submodules)

Purpose

Provides Zod validation schemas for all public wire-format types in @suaveplan/event-sourcing. These schemas are used at integration boundaries — when deserialising events from persistence layers, validating snapshot data, and parsing upcaster registrations — to ensure structural integrity before domain logic runs.

Features

• DomainEventSchema — validates the full event envelope including version, metadata, and typed occurredAt
• SnapshotSchema — validates aggregate snapshots before loading into aggregates
• EventMetadataSchema — validates event metadata with passthrough for unknown keys
• MemoryEventStoreOptionsSchema — validates store construction options
• UpcasterOptionsSchema — validates upcaster registration including the migration function

Usage: Basic Example

import { DomainEventSchema } from "@suaveplan/event-sourcing";

const raw = JSON.parse(storedJson);
const event = DomainEventSchema.parse({ ...raw, occurredAt: new Date(raw.occurredAt) });

Usage: Advanced Example

import { SnapshotSchema } from "@suaveplan/event-sourcing";
import z from "zod";

const MyStateSchema = z.object({ balance: z.number() });

const snapshot = SnapshotSchema.extend({
  state: MyStateSchema,
}).parse(rawSnapshot);

// snapshot.state is typed as { balance: number }

API Reference

DomainEventSchema

Validates { id, aggregateId, aggregateType, type, version, payload, metadata, occurredAt }. Version must be a positive integer. occurredAt must be a Date.

SnapshotSchema

Validates { aggregateId, aggregateType, version, state, takenAt }. Version is non-negative integer.

EventMetadataSchema

Validates optional causationId, correlationId, actor and passes through unknown keys.

MemoryEventStoreOptionsSchema

Optional schema; validates maxStreamLength as positive integer if present.

UpcasterOptionsSchema

Validates { eventType, fromVersion, toVersion, upcast }. fromVersion must be non-negative; toVersion must be positive.

Implementation Notes

All schemas use .passthrough() on metadata to avoid stripping custom keys. The payload and state fields use z.unknown() since the concrete shape depends on the event type — callers may extend the schema for stricter validation.