§reference

Entity

An entity is saved and versioned like a model, but emits no events and has no dates. Use one for rows whose changes nobody outside this service needs to hear about: lookup tables, idempotency markers, notifications already described by the event that caused them. #[entity] turns a plain struct into one.

Declaring an entity

use ekbatan::{Error, Id, entity};

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum NotificationState {
    Pending,
    Sent,
    Failed,
    Deleted,
}

#[entity(id = Id<Notification>, state = NotificationState, validate = Notification::validate)]
pub struct Notification {
    pub wallet_id: Uuid,
    pub kind: String,
    pub recipient: String,
    pub message: String,
}

impl Notification {
    fn validate(&self) -> Result<(), Error> {
        if self.recipient.trim().is_empty() {
            return Err(Error::Invalid("recipient cannot be blank".to_owned()));
        }
        if self.message.trim().is_empty() {
            return Err(Error::Invalid("message cannot be blank".to_owned()));
        }
        Ok(())
    }
}

#[entity(...)] takes the same arguments as #[model]: id = ... and state = ..., both required, and validate = path, optional. The same rules apply to the struct: named fields, no generic parameters, no field called base.

When an entity needs no lifecycle of its own, ekbatan::GenericState has the two states most need, Active and Deleted, written as ACTIVE and DELETED (as_str() and parse()):

#[entity(id = Id<Currency>, state = GenericState)]
pub struct Currency {
    pub code: String,
    pub display_name: String,
}

What #[entity] writes

The same as #[model], minus events and dates:

// ekbatan::Entity
fn copy(&self) -> Self::Builder;
fn state(&self) -> Self::State;

Persistable gives id(), version(), next_version(), model_name(), and is_model(), which is false.

The trait methods need their trait in scope: use ekbatan::{Entity, Persistable};. Without the import, name the trait in the call: ekbatan::Entity::state(&notification).

Differences from Model

modelentity
emits eventsyesno
created_date / updated_dateyesno
version, optimistic lockingyesyes
state, soft deletion (DELETED)yesyes
staged on the planyesyes
in the event logone row per eventonly the action’s own row, with no event

No events. The builder has no with_event, so there is no way to attach one. Writing an entity emits nothing. The action that wrote it is still recorded: if it emitted no events at all, it writes its one row with the event columns empty. The log is of units of work, not only of events.

No dates. An entity is current state, not history. If it needs to know when it last changed, that change is probably worth telling others about, which makes it a model.

Changing an entity

The same as a model: copy(), set what changed, build(). With no event to attach, a change simply returns the new value:

impl Notification {
    pub fn mark_sent(&self) -> Result<Notification, Error> {
        self.copy().state(NotificationState::Sent).build()
    }
}

build() checks that every field is set and the version is at least 1, then runs validate.

A new one, with a random id:

NotificationBuilder::new()
    .id(Id::random())
    .state(NotificationState::Pending)
    .wallet_id(wallet_id)
    .kind(kind.to_owned())
    .recipient(recipient.to_owned())
    .message(message.to_owned())
    .with_initial_version()
    .build()?

Id::random() is a random (version 4) UUID; Id::of(uuid) wraps one you have. An entity can use ShardedId too, when it lives on several shards.

Equality

The derived PartialEq compares the base - id, state and version - and every field of yours.

Builder API

new(), id(...), state(...), version(...), with_initial_version(), increase_version(), copy_base(&other), one setter per field, and build(). The date and event setters of a model’s builder are not on it.

See also