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 replaying events. Use the [projection] module for loading aggregate state:

use evento::projection::Projection;

#[evento::projection]
#[derive(Debug)]
pub struct AccountView {
    pub balance: i64,
}

#[evento::handler]
async fn on_deposited(
    event: Event<MoneyDeposited>,
    projection: &mut AccountView,
) -> anyhow::Result<()> {
    projection.balance += event.data.amount;
    Ok(())
}

let result = Projection::<AccountView, _>::new::<BankAccount>("account-123")
    .handler(on_deposited())
    .execute(&executor)
    .await?;

§Subscriptions

Process events continuously in real-time. See the [subscription] module:

use evento::subscription::SubscriptionBuilder;

#[evento::subscription]
async fn on_deposited<E: Executor>(
    context: &Context<'_, E>,
    event: Event<MoneyDeposited>,
) -> anyhow::Result<()> {
    // Perform side effects
    Ok(())
}

let subscription = SubscriptionBuilder::<Sqlite>::new("deposit-processor")
    .handler(on_deposited())
    .routing_key("accounts")
    .start(&executor)
    .await?;

§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 for loading aggregate state
[subscription] - Continuous event processing with subscriptions

§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 subscription::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.
subscription: Continuous event subscriptions.

Structs§

AggregatorBuilder: Builder for creating and committing events.
Event: A stored event in the event store.
EventCursor: Cursor data for event pagination.
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§

Aggregator: Trait for aggregate types.
AggregatorEvent: Trait for event types.
AggregatorExecutor
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.
hash_ids: Creates a new builder for the given aggregate IDs.

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.
handler: Creates a projection handler from an async function.
projection: Adds a cursor: String field and implements ProjectionCursor.
subscription: Creates a subscription handler for specific events.
subscription_all: Creates a subscription handler that processes all events of an aggregate type.

Derive Macros§

Cursor: Derive macro for generating cursor structs and trait implementations.