Crate evento_core

Expand description

Core types and traits for the Evento event sourcing library.

This crate provides the foundational abstractions for building event-sourced applications with Evento. It defines the core traits, types, and builders used throughout the framework.

§Features

macro (default) - Procedural macros from evento-macro
group - Multi-executor support via EventoGroup
rw - Read-write split executor pattern via Rw
sqlite, mysql, postgres - Database support via sqlx
fjall - Embedded key-value storage with Fjall

§Core Concepts

§Events

Events are immutable facts that represent something that happened in your domain. The Event struct stores serialized event data with metadata:

// Define events using the aggregator macro
#[evento::aggregator]
pub enum BankAccount {
    AccountOpened { owner_id: String, initial_balance: i64 },
    MoneyDeposited { amount: i64 },
}

§Executor

The Executor trait abstracts event storage and retrieval. Implementations handle persisting events, querying, and managing subscriptions.

§Aggregator Builder

Use create() or aggregator() to build and commit events:

use evento::metadata::Metadata;

let id = evento::create()
    .event(&AccountOpened { owner_id: "user1".into(), initial_balance: 1000 })?
    .metadata(&Metadata::default())?
    .commit(&executor)
    .await?;

§Projections

Build read models by subscribing to events. See the projection module.

§Cursor-based Pagination

GraphQL-style pagination for querying events. See the cursor module.

§Modules

context - Type-safe request context for storing arbitrary data
cursor - Cursor-based pagination types and traits
metadata - Standard event metadata types
projection - Projections, subscriptions, and event handlers

§Example

use evento::{Executor, metadata::Metadata, cursor::Args, ReadAggregator};

// Create and persist an event
let id = evento::create()
    .event(&AccountOpened { owner_id: "user1".into(), initial_balance: 1000 })?
    .metadata(&Metadata::default())?
    .commit(&executor)
    .await?;

// Query events with pagination
let events = executor.read(
    Some(vec![ReadAggregator::id("myapp/Account", &id)]),
    None,
    Args::forward(10, None),
).await?;

Re-exports§

pub use projection::RoutingKey;

Modules§

context: Type-safe context for storing request-scoped data.
cursor: Cursor-based pagination for event queries.
metadata: Standard event metadata types.
projection: Projections and event subscriptions.

Structs§

AggregatorBuilder: Builder for creating and committing events.
ArchivedEventCursor: An archived EventCursor
Event: A stored event in the event store.
EventCursor: Cursor data for event pagination.
EventCursorResolver: The resolver for an archived EventCursor
Evento: Type-erased wrapper around any Executor implementation.
ReadAggregator: Filter for querying events by aggregator.

Enums§

WriteError: Errors that can occur when writing events.

Traits§

Executor: Core trait for event storage backends.

Functions§

aggregator: Creates a builder for an existing aggregate.
create: Creates a new aggregate with an auto-generated ULID.

Attribute Macros§

aggregator: Transforms an enum into individual event structs with trait implementations.
debug_handler: Debug variant of [handler] that writes generated code to a file.
debug_snapshot: Debug variant of [snapshot] that writes generated code to a file.
handler: Creates an event handler from an async function.
snapshot: Implements the Snapshot trait for projection state restoration.