eventfold-es 0.2.0

//! Aggregate trait and ReduceFn adapter.

use crate::command::CommandContext;
use serde::{Serialize, de::DeserializeOwned};
use uuid::Uuid;

/// A domain aggregate whose state is derived from its event history.
///
/// The implementing type itself serves as the aggregate's state.
/// State is built by folding domain events through the [`apply`](Aggregate::apply) method.
///
/// # Associated Types
///
/// - `Command`: the set of commands this aggregate can handle.
/// - `DomainEvent`: the set of events this aggregate can produce and apply.
/// - `Error`: command rejection / validation error.
///
/// # Contract
///
/// - [`handle`](Aggregate::handle) must be a pure decision function: no I/O, no side effects.
///   It validates a command against the current state and returns zero or more events.
/// - [`apply`](Aggregate::apply) must be a pure, total function. It takes ownership of
///   the current state and a reference to a domain event, returning the next state.
///   Unknown event variants should be ignored for forward compatibility.
pub trait Aggregate:
    Default + Clone + Serialize + DeserializeOwned + Send + Sync + 'static
{
    /// Identifies this aggregate type (e.g. "order"). Used as a directory name.
    const AGGREGATE_TYPE: &'static str;

    /// The set of commands this aggregate can handle.
    type Command: Send + 'static;

    /// The set of events this aggregate can produce and apply.
    type DomainEvent: Serialize + DeserializeOwned + Send + Sync + Clone + 'static;

    /// Command rejection / validation error type.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Validate a command against the current state and produce events.
    ///
    /// Returns `Ok(vec![])` if the command is a no-op.
    /// Returns `Err` to reject the command.
    fn handle(&self, cmd: Self::Command) -> Result<Vec<Self::DomainEvent>, Self::Error>;

    /// Apply a single event to produce the next state.
    ///
    /// Unknown event variants should be ignored (return `self` unchanged)
    /// to maintain forward compatibility.
    fn apply(self, event: &Self::DomainEvent) -> Self;
}

/// Inner reduce function used as a function pointer for `eventfold::ReduceFn<A>`.
///
/// Attempts to deserialize the event data into `A::DomainEvent`. On success,
/// delegates to `A::apply`. On failure (unknown or malformed event), returns
/// the state unchanged for forward compatibility.
fn reduce<A: Aggregate>(state: A, event: &eventfold::Event) -> A {
    // Attempt to interpret the raw eventfold event as a domain event.
    // The domain event uses adjacently tagged serde (`"type"` + `"data"`),
    // so we reconstruct the tagged JSON object from the eventfold fields.
    let tagged = if event.data.is_null() {
        // Fieldless variant: just `{"type": "VariantName"}`
        serde_json::json!({ "type": event.event_type })
    } else {
        // Variant with data: `{"type": "VariantName", "data": ...}`
        serde_json::json!({
            "type": event.event_type,
            "data": event.data,
        })
    };

    match serde_json::from_value::<A::DomainEvent>(tagged) {
        Ok(domain_event) => state.apply(&domain_event),
        // Unknown or malformed event type -- skip for forward compatibility.
        Err(_) => state,
    }
}

/// Build an `eventfold::ReduceFn<A>` that deserializes each `eventfold::Event`
/// into `A::DomainEvent` and delegates to `A::apply`.
///
/// Unknown or malformed events are silently skipped (state returned unchanged),
/// providing forward compatibility with new event types.
///
/// # Returns
///
/// A function pointer `fn(A, &eventfold::Event) -> A` suitable for use with
/// `eventfold::View::new` or `EventLog::builder().view()`.
///
/// # Examples
///
/// ```
/// use eventfold_es::{Aggregate, CommandContext};
/// ```
pub fn reducer<A: Aggregate>() -> eventfold::ReduceFn<A> {
    reduce::<A>
}

/// Convert a domain event and command context into an `eventfold::Event`.
///
/// The `DomainEvent` must use `#[serde(tag = "type", content = "data")]` adjacently
/// tagged serialization. The `"type"` field becomes `eventfold::Event::event_type`
/// and the remaining payload becomes `eventfold::Event::data`.
///
/// # Arguments
///
/// * `domain_event` - Reference to the domain event to convert.
/// * `ctx` - Command context carrying actor, correlation ID, and metadata.
///
/// # Returns
///
/// An `eventfold::Event` populated with the event type, data, and any
/// context-derived metadata (actor, correlation ID, extra metadata).
///
/// # Errors
///
/// Returns `serde_json::Error` if the domain event cannot be serialized.
pub fn to_eventfold_event<A: Aggregate>(
    domain_event: &A::DomainEvent,
    ctx: &CommandContext,
) -> serde_json::Result<eventfold::Event> {
    // Serialize the domain event. Because of adjacently tagged serde, this
    // produces an object like `{"type": "Incremented"}` or
    // `{"type": "Added", "data": {"amount": 5}}`.
    let value = serde_json::to_value(domain_event)?;
    let obj = value
        .as_object()
        .expect("adjacently tagged enum must serialize to a JSON object");

    let event_type = obj["type"]
        .as_str()
        .expect("adjacently tagged enum must have a string 'type' field");

    // Data may be absent for fieldless variants.
    let data = obj.get("data").cloned().unwrap_or(serde_json::Value::Null);

    let mut event = eventfold::Event::new(event_type, data).with_id(Uuid::new_v4().to_string());

    // Propagate actor from the command context.
    if let Some(ref actor) = ctx.actor {
        event = event.with_actor(actor);
    }

    // Build metadata: start from ctx.metadata (if an Object), then merge
    // correlation_id. Only attach if non-empty.
    let mut meta_map = match ctx.metadata {
        Some(serde_json::Value::Object(ref map)) => map.clone(),
        _ => serde_json::Map::new(),
    };

    if let Some(ref cid) = ctx.correlation_id {
        meta_map.insert(
            "correlation_id".to_string(),
            serde_json::Value::String(cid.clone()),
        );
    }

    if let Some(ref device_id) = ctx.source_device {
        meta_map.insert(
            "source_device".to_string(),
            serde_json::Value::String(device_id.clone()),
        );
    }

    if !meta_map.is_empty() {
        event = event.with_meta(serde_json::Value::Object(meta_map));
    }

    Ok(event)
}

#[cfg(test)]
pub(crate) mod test_fixtures {
    use super::Aggregate;
    use serde::{Deserialize, Serialize};

    /// A simple counter aggregate used as a test fixture.
    #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
    pub(crate) struct Counter {
        pub value: u64,
    }

    /// Commands that can be issued to the `Counter` aggregate.
    pub(crate) enum CounterCommand {
        Increment,
        Decrement,
        Add(u64),
    }

    /// Domain events produced by the `Counter` aggregate.
    ///
    /// Uses adjacently tagged serialization (`"type"` + `"data"`) which is the
    /// convention for all `DomainEvent` types in this crate.
    #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
    #[serde(tag = "type", content = "data")]
    pub(crate) enum CounterEvent {
        Incremented,
        Decremented,
        Added { amount: u64 },
    }

    /// Errors that can occur when handling a `CounterCommand`.
    #[derive(Debug, thiserror::Error)]
    pub(crate) enum CounterError {
        #[error("cannot decrement: counter is already zero")]
        AlreadyZero,
    }

    impl Aggregate for Counter {
        const AGGREGATE_TYPE: &'static str = "counter";

        type Command = CounterCommand;
        type DomainEvent = CounterEvent;
        type Error = CounterError;

        fn handle(&self, cmd: Self::Command) -> Result<Vec<Self::DomainEvent>, Self::Error> {
            match cmd {
                CounterCommand::Increment => Ok(vec![CounterEvent::Incremented]),
                CounterCommand::Decrement => {
                    if self.value == 0 {
                        return Err(CounterError::AlreadyZero);
                    }
                    Ok(vec![CounterEvent::Decremented])
                }
                CounterCommand::Add(n) => Ok(vec![CounterEvent::Added { amount: n }]),
            }
        }

        fn apply(mut self, event: &Self::DomainEvent) -> Self {
            match event {
                CounterEvent::Incremented => self.value += 1,
                CounterEvent::Decremented => self.value -= 1,
                CounterEvent::Added { amount } => self.value += amount,
            }
            self
        }
    }
}

#[cfg(test)]
mod tests {
    use super::Aggregate;
    use super::test_fixtures::{Counter, CounterCommand, CounterError, CounterEvent};

    #[test]
    fn handle_increment() {
        let counter = Counter::default();
        let events = counter.handle(CounterCommand::Increment).unwrap();
        assert_eq!(events, vec![CounterEvent::Incremented]);
    }

    #[test]
    fn handle_decrement_nonzero() {
        let counter = Counter { value: 5 };
        let events = counter.handle(CounterCommand::Decrement).unwrap();
        assert_eq!(events, vec![CounterEvent::Decremented]);
    }

    #[test]
    fn handle_decrement_at_zero() {
        let counter = Counter::default();
        let result = counter.handle(CounterCommand::Decrement);
        assert!(result.is_err());
        // Verify the specific error variant via its message.
        let err = result.unwrap_err();
        assert!(
            matches!(err, CounterError::AlreadyZero),
            "expected AlreadyZero, got: {err}"
        );
    }

    #[test]
    fn handle_add() {
        let counter = Counter::default();
        let events = counter.handle(CounterCommand::Add(5)).unwrap();
        assert_eq!(events, vec![CounterEvent::Added { amount: 5 }]);
    }

    #[test]
    fn apply_incremented() {
        let counter = Counter::default().apply(&CounterEvent::Incremented);
        assert_eq!(counter.value, 1);
    }

    #[test]
    fn apply_decremented() {
        let counter = Counter { value: 3 }.apply(&CounterEvent::Decremented);
        assert_eq!(counter.value, 2);
    }

    #[test]
    fn apply_added() {
        let counter = Counter::default().apply(&CounterEvent::Added { amount: 5 });
        assert_eq!(counter.value, 5);
    }

    #[test]
    fn handle_then_apply_roundtrip() {
        let counter = Counter::default();
        let events = counter.handle(CounterCommand::Increment).unwrap();
        // Fold all produced events through `apply` to derive the final state.
        let final_state = events
            .iter()
            .fold(Counter::default(), |state, event| state.apply(event));
        assert_eq!(final_state.value, 1);
    }

    // --- reducer / to_eventfold_event bridge tests ---

    use super::{reducer, to_eventfold_event};
    use crate::command::CommandContext;

    #[test]
    fn reducer_roundtrip_increment() {
        let event =
            to_eventfold_event::<Counter>(&CounterEvent::Incremented, &CommandContext::default())
                .unwrap();

        let state = reducer::<Counter>()(Counter::default(), &event);
        assert_eq!(state.value, 1);
    }

    #[test]
    fn reducer_roundtrip_added() {
        let event = to_eventfold_event::<Counter>(
            &CounterEvent::Added { amount: 5 },
            &CommandContext::default(),
        )
        .unwrap();

        let state = reducer::<Counter>()(Counter::default(), &event);
        assert_eq!(state.value, 5);
    }

    #[test]
    fn reducer_unknown_event_skipped() {
        // An event type that Counter does not recognize should leave state
        // unchanged, providing forward compatibility.
        let event = eventfold::Event::new("UnknownType", serde_json::json!({}));
        let state = reducer::<Counter>()(Counter::default(), &event);
        assert_eq!(state.value, 0);
    }

    #[test]
    fn context_propagates_actor() {
        let ctx = CommandContext::default().with_actor("user-1");
        let event = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();

        assert_eq!(event.actor, Some("user-1".into()));
    }

    #[test]
    fn context_propagates_correlation_id() {
        let ctx = CommandContext::default().with_correlation_id("req-abc");
        let event = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();

        // The correlation_id should appear inside the event's meta object.
        let meta = event.meta.expect("meta should be present");
        assert_eq!(meta["correlation_id"], "req-abc");
    }

    #[test]
    fn fieldless_variant_roundtrip() {
        // Incremented has no fields. Verify to_eventfold_event produces a
        // valid event that the reducer can fold back into state.
        let event =
            to_eventfold_event::<Counter>(&CounterEvent::Incremented, &CommandContext::default())
                .unwrap();

        // Verify the event_type is correct and data is null (no payload).
        assert_eq!(event.event_type, "Incremented");
        assert!(event.data.is_null());

        // Round-trip through the reducer.
        let state = reducer::<Counter>()(Counter::default(), &event);
        assert_eq!(state.value, 1);
    }

    // --- UUID v4 event ID tests ---

    #[test]
    fn to_eventfold_event_assigns_uuid_v4_id() {
        let event =
            to_eventfold_event::<Counter>(&CounterEvent::Incremented, &CommandContext::default())
                .unwrap();

        // The event must carry a Some(id) that is a valid UUID v4 string.
        let id = event.id.expect("event.id should be Some");

        // Parse with the uuid crate to validate format and version.
        let parsed = uuid::Uuid::parse_str(&id)
            .unwrap_or_else(|e| panic!("event id '{id}' is not a valid UUID: {e}"));
        assert_eq!(
            parsed.get_version(),
            Some(uuid::Version::Random),
            "event id '{id}' is not UUID v4 (version = {:?})",
            parsed.get_version()
        );

        // Also verify the lowercase hyphenated format matches the canonical
        // UUID v4 regex from the acceptance criteria.
        assert_eq!(id, parsed.as_hyphenated().to_string());
    }

    #[test]
    fn to_eventfold_event_produces_distinct_ids() {
        let ctx = CommandContext::default();
        let event_a = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();
        let event_b = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();

        // Two successive calls must produce different IDs.
        assert_ne!(
            event_a.id, event_b.id,
            "successive events must have distinct ids"
        );
    }

    #[test]
    fn context_propagates_source_device() {
        let ctx = CommandContext::default().with_source_device("device-xyz");
        let event = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();

        let meta = event.meta.expect("meta should be present");
        assert_eq!(meta["source_device"], "device-xyz");
    }

    #[test]
    fn context_propagates_source_device_and_correlation_id() {
        let ctx = CommandContext::default()
            .with_correlation_id("req-abc")
            .with_source_device("device-xyz");
        let event = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();

        let meta = event.meta.expect("meta should be present");
        assert_eq!(meta["correlation_id"], "req-abc");
        assert_eq!(meta["source_device"], "device-xyz");
    }

    #[test]
    fn context_merges_source_device_with_existing_metadata() {
        let ctx = CommandContext::default()
            .with_metadata(serde_json::json!({"foo": "bar", "level": 3}))
            .with_source_device("device-xyz");
        let event = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();

        let meta = event.meta.expect("meta should be present");
        assert_eq!(meta["foo"], "bar");
        assert_eq!(meta["level"], 3);
        assert_eq!(meta["source_device"], "device-xyz");
    }

    #[test]
    fn all_none_context_produces_no_meta() {
        // When source_device, correlation_id, and metadata are all None,
        // the resulting event should have meta == None (no empty object).
        let ctx = CommandContext::default();
        assert!(ctx.source_device.is_none());
        assert!(ctx.correlation_id.is_none());
        assert!(ctx.metadata.is_none());

        let event = to_eventfold_event::<Counter>(&CounterEvent::Incremented, &ctx).unwrap();
        assert!(
            event.meta.is_none(),
            "meta should be None when all context fields are None, got: {:?}",
            event.meta
        );
    }

    #[test]
    fn reducer_applies_event_with_no_id() {
        // Simulate a pre-existing log entry that has no id field (id: None).
        // The reducer must still apply it correctly.
        let event_with_id_none = eventfold::Event::new("Incremented", serde_json::Value::Null);
        assert!(event_with_id_none.id.is_none(), "precondition: id is None");

        // Known event type advances state.
        let state = reducer::<Counter>()(Counter::default(), &event_with_id_none);
        assert_eq!(state.value, 1);

        // Unknown event type leaves state unchanged.
        let unknown_event = eventfold::Event::new("SomeFutureEvent", serde_json::json!({}));
        assert!(unknown_event.id.is_none(), "precondition: id is None");
        let state = reducer::<Counter>()(Counter::default(), &unknown_event);
        assert_eq!(state.value, 0);
    }
}