# event-sourcing.schemas

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

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

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

## Usage: Advanced Example

```ts
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.