statekit 0.3.1

An immutable state-machine for validating predefined transitions.
Documentation
use crate::StateError;

/// A validated state name within a machine.
///
/// A `StateName` is guaranteed to be non-empty, not whitespace-only,
/// and to contain no leading or trailing Unicode whitespace.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub(crate) struct StateName(String);

impl StateName {
    /// Returns the state name as a string slice.
    pub(crate) fn as_str(&self) -> &str {
        &self.0
    }

    /// Consumes the state name and returns its owned string.
    pub(crate) fn into_string(self) -> String {
        self.0
    }
}

impl TryFrom<&str> for StateName {
    type Error = StateError;
    fn try_from(value: &str) -> Result<Self, Self::Error> {
        validate_state_name(value)?;

        Ok(Self(value.to_owned()))
    }
}

impl TryFrom<String> for StateName {
    type Error = StateError;
    fn try_from(value: String) -> Result<Self, Self::Error> {
        validate_state_name(&value)?;

        Ok(Self(value))
    }
}

/// Validates a state name against the crate's naming invariants.
fn validate_state_name(value: &str) -> Result<(), StateError> {
    let trimmed = value.trim();

    if trimmed.is_empty() {
        return Err(StateError::EmptyState);
    }

    if value != trimmed {
        return Err(StateError::AmbiguousStateName {
            state: value.to_owned(),
        });
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn try_from_str_valid_state_succeeds() {
        let state = StateName::try_from("in progress").unwrap();

        assert_eq!(state.as_str(), "in progress");
    }

    #[test]
    fn try_from_string_valid_state_succeeds() {
        let state = StateName::try_from(String::from("queued")).unwrap();

        assert_eq!(state.as_str(), "queued");
    }

    #[test]
    fn try_from_rejects_leading_whitespace() {
        let result = StateName::try_from(" queued");

        assert_eq!(
            result,
            Err(StateError::AmbiguousStateName {
                state: " queued".to_owned()
            })
        );
    }

    #[test]
    fn validate_state_name_one_word_returns_ok() {
        let result = validate_state_name("something");

        assert!(result.is_ok());
    }

    #[test]
    fn validate_state_name_two_words_returns_ok() {
        let result = validate_state_name("something else");

        assert!(result.is_ok());
    }

    #[test]
    fn validate_state_name_empty_returns_error() {
        let result = validate_state_name("");

        assert_eq!(result, Err(StateError::EmptyState));
    }

    #[test]
    fn validate_state_name_whitespace_returns_error() {
        let result = validate_state_name(" \n\t");

        assert_eq!(result, Err(StateError::EmptyState));
    }

    #[test]
    fn validate_state_name_leading_whitespace_returns_error() {
        let result = validate_state_name("\n\t something");

        assert_eq!(
            result,
            Err(StateError::AmbiguousStateName {
                state: "\n\t something".to_owned()
            })
        );
    }

    #[test]
    fn validate_state_name_trailing_whitespace_returns_error() {
        let result = validate_state_name("something\n\t ");

        assert_eq!(
            result,
            Err(StateError::AmbiguousStateName {
                state: "something\n\t ".to_owned()
            })
        );
    }

    #[test]
    fn validate_state_name_unicode_leading_whitespace_returns_error() {
        let result = validate_state_name("\u{00A0}queued");

        assert_eq!(
            result,
            Err(StateError::AmbiguousStateName {
                state: "\u{00A0}queued".to_owned()
            })
        );
    }
}