envigil 0.3.0

Keep vigil over your environment — load, parse, and validate env vars with zero dependencies.
Documentation
//! Declaration and resolution of a single environment variable.
//!
//! A [`VarBuilder`] describes how to parse, default, validate, and
//! flag one variable. It does **not** read from the environment

use crate::error::{Error, ValidationError};
use crate::validate::Validator;

/// A boxed parsing function: raw string → typed value.
type Parser<T> = Box<dyn Fn(&str) -> Result<T, String>>;

/// Declares one environment variable: parser, default, validators,
/// and flags.
///
/// # Examples
///
/// ```
/// use envigil::var::VarBuilder;
/// use envigil::validate;
///
/// let var = VarBuilder::new("PORT", |s| s.parse::<u16>().map_err(|e| e.to_string()))
///     .default(8080)
///     .validate(validate::range(1..=65535));
///
/// // Simulate a raw value from the environment:
/// let resolved = var.resolve(Some("3000")).unwrap();
/// assert_eq!(resolved, Some(3000));
///
/// // Missing value falls back to default:
/// let resolved = var.resolve(None).unwrap();
/// assert_eq!(resolved, Some(8080));
/// ```
pub struct VarBuilder<T> {
    name: String,
    parser: Parser<T>,
    default: Option<T>,
    required: bool,
    secret: bool,
    validators: Vec<Box<dyn Validator<T>>>,
}

impl<T> VarBuilder<T>
where
    T: Clone + 'static,
{
    /// Create a variable declaration.
    ///
    /// `parser` converts the raw string into `T`. Return
    /// `Err(message)` with a lowercase description on failure.
    pub fn new(
        name: impl Into<String>,
        parser: impl Fn(&str) -> Result<T, String> + 'static,
    ) -> Self {
        Self {
            name: name.into(),
            parser: Box::new(parser),
            default: None,
            required: false,
            secret: false,
            validators: Vec::new(),
        }
    }

    /// Provide a fallback value when the variable is not set.
    pub fn default(mut self, value: T) -> Self {
        self.default = Some(value);
        self
    }

    /// Mark the variable as mandatory. If it is absent and no
    /// default is set, resolution fails with [`Error::missing`].
    pub fn required(mut self) -> Self {
        self.required = true;
        self
    }

    /// Mark the variable as sensitive. The flag is readable via
    /// [`is_secret`](Self::is_secret) so the caller can wrap the
    /// value in [`Secret`](crate::Secret).
    pub fn secret(mut self) -> Self {
        self.secret = true;
        self
    }

    /// Add a validator.
    ///
    /// # Examples
    ///
    /// ```
    /// use envigil::var::VarBuilder;
    /// use envigil::validate;
    ///
    /// let var = VarBuilder::new("PORT", |s| s.parse::<u16>().map_err(|e| e.to_string()))
    ///     .validate(validate::range(1..=65535));
    ///
    /// assert!(var.resolve(Some("99999")).is_err());
    /// ```
    pub fn validate(mut self, validator: impl Validator<T> + 'static) -> Self {
        self.validators.push(Box::new(validator));
        self
    }

    /// Add a closure validator.
    ///
    /// # Examples
    ///
    /// ```
    /// use envigil::var::VarBuilder;
    ///
    /// let var = VarBuilder::new("WORKERS", |s| s.parse::<u32>().map_err(|e| e.to_string()))
    ///     .validate_with(|n| {
    ///         if *n > 0 { Ok(()) }
    ///         else { Err("must be positive".to_owned()) }
    ///     });
    ///
    /// assert!(var.resolve(Some("0")).is_err());
    /// ```
    pub fn validate_with(mut self, f: impl Fn(&T) -> Result<(), String> + 'static) -> Self {
        self.validators.push(Box::new(f));
        self
    }

    /// The variable name.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Whether the variable was marked secret.
    pub fn is_secret(&self) -> bool {
        self.secret
    }

    /// Resolve a raw environment value into a typed result.
    ///
    /// - `Some(raw)` → parse → validate → `Ok(Some(value))`
    /// - `None` + default → `Ok(Some(default))`
    /// - `None` + required → `Err(Error::missing)`
    /// - `None` + optional → `Ok(None)`
    pub fn resolve(&self, raw: Option<&str>) -> Result<Option<T>, Error> {
        let value = match raw {
            Some(s) => {
                let parsed = (self.parser)(s).map_err(|msg| Error::parse(&self.name, s, msg))?;
                self.run_validators(&parsed)?;
                parsed
            }
            None => {
                if let Some(d) = &self.default {
                    d.clone()
                } else if self.required {
                    return Err(Error::missing(&self.name));
                } else {
                    return Ok(None);
                }
            }
        };

        Ok(Some(value))
    }

    fn run_validators(&self, value: &T) -> Result<(), Error> {
        let mut errors = Vec::new();

        for v in &self.validators {
            if let Err(msg) = v.validate(value) {
                errors.push(ValidationError::new(&self.name, msg));
            }
        }

        if errors.is_empty() {
            Ok(())
        } else {
            Err(Error::validation(errors))
        }
    }

    /// Prepend a prefix to the variable name.
    ///
    /// ```
    /// use envigil::VarBuilder;
    ///
    /// let var = VarBuilder::new("PORT", |s| s.parse::<u16>().map_err(|e| e.to_string()))
    ///     .prefixed("APP_");
    ///
    /// assert_eq!(var.name(), "APP_PORT");
    /// ```
    pub fn prefixed(mut self, prefix: &str) -> Self {
        if !prefix.is_empty() {
            self.name = format!("{prefix}{}", self.name);
        }
        self
    }
}

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

    fn port_var() -> VarBuilder<u16> {
        VarBuilder::new("PORT", |s| s.parse::<u16>().map_err(|e| e.to_string()))
    }

    #[test]
    fn resolves_raw_value() {
        let var = port_var();
        assert_eq!(var.resolve(Some("3000")).unwrap(), Some(3000));
    }

    #[test]
    fn falls_back_to_default() {
        let var = port_var().default(8080);
        assert_eq!(var.resolve(None).unwrap(), Some(8080));
    }

    #[test]
    fn missing_required_is_error() {
        let var = port_var().required();
        let err = var.resolve(None).unwrap_err();
        assert!(matches!(err.kind(), crate::error::ErrorKind::Missing { name } if name == "PORT"));
    }

    #[test]
    fn missing_optional_is_none() {
        let var = port_var();
        assert_eq!(var.resolve(None).unwrap(), None);
    }

    #[test]
    fn parse_error_includes_name_and_raw() {
        let var = port_var();
        let err = var.resolve(Some("abc")).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("PORT"), "message: {msg}");
        assert!(msg.contains("abc"), "message: {msg}");
    }

    #[test]
    fn validation_error() {
        let var = port_var().validate(validate::range(1..=65535));
        let err = var.resolve(Some("0")).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("PORT"), "message: {msg}");
        assert!(msg.contains("out of range"), "message: {msg}");
    }

    #[test]
    fn multiple_validators_accumulate() {
        let var = VarBuilder::new("EMAIL", |s| Ok(s.to_owned()))
            .validate(validate::not_empty())
            .validate(validate::contains("@"));

        let err = var.resolve(Some("")).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("2 errors"), "message: {msg}");
    }

    #[test]
    fn validate_with_closure() {
        let var = VarBuilder::new("N", |s| s.parse::<u32>().map_err(|e| e.to_string()))
            .validate_with(|n| {
                if *n % 2 == 0 {
                    Ok(())
                } else {
                    Err("must be even".to_owned())
                }
            });

        assert!(var.resolve(Some("4")).unwrap().is_some());
        assert!(var.resolve(Some("3")).is_err());
    }

    #[test]
    fn secret_flag() {
        let var = VarBuilder::new("TOKEN", |s| Ok(s.to_owned())).secret();
        assert!(var.is_secret());
        assert!(!port_var().is_secret());
    }

    #[test]
    fn name_accessor() {
        assert_eq!(port_var().name(), "PORT");
    }

    #[test]
    fn default_overrides_missing_but_not_present() {
        let var = port_var().default(8080);
        // Present value wins over default:
        assert_eq!(var.resolve(Some("9090")).unwrap(), Some(9090));
    }
}