deepslate 0.3.1

//! Event handler priority ordering.
//!
//! Mirrors Velocity's `PostOrder` concept: handlers with higher priority values
//! execute first. Named constants provide the standard ordering tiers.

/// Priority level for event handlers.
///
/// Higher values execute first. Handlers at the same priority level execute in
/// registration order.
///
/// Standard tiers are provided as associated constants. Custom values can be
/// used for fine-grained ordering between tiers.
///
/// # Execution Order
///
/// ```text
/// FIRST (128) -> EARLY (64) -> NORMAL (0) -> LATE (-64) -> LAST (-128)
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PostOrder(i16);

impl PostOrder {
    /// Executes first, before all other tiers.
    pub const FIRST: Self = Self(128);

    /// Executes early, after FIRST but before NORMAL.
    pub const EARLY: Self = Self(64);

    /// Default priority. Most handlers should use this.
    pub const NORMAL: Self = Self(0);

    /// Executes late, after NORMAL but before LAST.
    pub const LATE: Self = Self(-64);

    /// Executes last, after all other tiers. Useful for "final say" handlers
    /// or monitoring/logging.
    pub const LAST: Self = Self(-128);

    /// Create a custom priority. Higher values execute first.
    #[must_use]
    pub const fn custom(value: i16) -> Self {
        Self(value)
    }

    /// Get the raw priority value.
    #[must_use]
    pub const fn value(self) -> i16 {
        self.0
    }
}

impl Default for PostOrder {
    fn default() -> Self {
        Self::NORMAL
    }
}

/// Observer phase within the event dispatch pipeline.
///
/// Observers receive a shared (`&E`) reference to the event, meaning they
/// cannot modify it. This makes them suitable for logging, metrics, and
/// other read-only side effects.
///
/// # Dispatch Order
///
/// ```text
/// Pre observers → Handlers (mutable, priority-ordered) → Post observers
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Phase {
    /// Runs before any mutable handler. Sees the event in its initial state.
    Pre,
    /// Runs after all mutable handlers. Sees the event in its final state.
    Post,
}