validatable 0.1.0

Define validated data types once and share them between the frontend and backend of isomorphic Rust web applications, with plain, input, and form representations
Documentation
//! Field family markers and type-level field selection.
//!
//! A *field family* selects which concrete representation a field takes in a
//! data type that is generic over [`FieldFamily`]:
//!
//! * [`Plain`] — the validated domain value (e.g. `u32`)
//! * [`Input`] — the raw, unvalidated input (e.g. `String`)
//! * [`Form`] — the editable form state with a validation result attached
//!   (e.g. `Edit<String>`)
//!
//! The [`Field`] and [`FieldWith`] type aliases resolve a field type for a
//! given family, so a single struct definition expands to three related
//! types: `T<Plain>`, `T<Input>`, and `T<Form>`.

use std::fmt::Debug;

use super::DefaultInputType;

/// The bound every field type (`P`, `E`, `I`) must satisfy.
///
/// This is `PartialEq + Clone + Debug`, plus `Serialize + DeserializeOwned`
/// when the `serde` feature is enabled (off by default).
#[cfg(feature = "serde")]
pub trait FieldBounds:
    PartialEq + Clone + Debug + serde::Serialize + serde::de::DeserializeOwned
{
}
#[cfg(feature = "serde")]
impl<T> FieldBounds for T where
    T: PartialEq + Clone + Debug + serde::Serialize + serde::de::DeserializeOwned
{
}

/// The bound every field type (`P`, `E`, `I`) must satisfy.
///
/// This is `PartialEq + Clone + Debug`, plus `Serialize + DeserializeOwned`
/// when the `serde` feature is enabled (off by default).
#[cfg(not(feature = "serde"))]
pub trait FieldBounds: PartialEq + Clone + Debug {}
#[cfg(not(feature = "serde"))]
impl<T> FieldBounds for T where T: PartialEq + Clone + Debug {}

/// Field family of validated domain values.
///
/// `T<Plain>` is the plain, validated representation of `T`. A value of a
/// `Plain` type is only obtained by validating a `T<Form>` or `T<Input>`
/// (or by deserializing from trusted storage), so holding a `T<Plain>`
/// means the data has passed validation.
#[derive(PartialEq, Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Plain;

/// Field family of raw, unvalidated input values.
///
/// `T<Input>` is `T<Form>` without the per-field validation results. It is
/// intended for input without a UI, such as the payload of an API request
/// sent from the frontend to the backend.
#[derive(PartialEq, Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Input;

/// Field family of editable form states.
///
/// `T<Form>` represents the state of an input form while the user is editing
/// a `T`. Each field holds its raw input (numbers are edited as strings, for
/// example) together with the latest validation result (see [`Edit`](crate::Edit)).
#[derive(PartialEq, Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Form;

/// Maps a field family to the concrete type of a field.
///
/// This is implemented by the three marker types [`Plain`], [`Input`], and
/// [`Form`]. The generic associated type picks one of the three candidate
/// types `P` (plain), `E` (form) and `I` (input).
///
/// All candidate types must satisfy [`FieldBounds`]; this bound is currently
/// a prerequisite for every field type used with this crate.
pub trait FieldFamily {
    /// The field type selected by this family, given the candidate types `P`
    /// (plain), `E` (form) and `I` (input).
    type Type<P, E, I>: FieldBounds
    where
        P: FieldBounds,
        E: FieldBounds,
        I: FieldBounds;
}
impl FieldFamily for Plain {
    type Type<P, E, I>
        = P
    where
        P: FieldBounds,
        E: FieldBounds,
        I: FieldBounds;
}
impl FieldFamily for Form {
    type Type<P, E, I>
        = E
    where
        P: FieldBounds,
        E: FieldBounds,
        I: FieldBounds;
}
impl FieldFamily for Input {
    type Type<P, E, I>
        = I
    where
        P: FieldBounds,
        E: FieldBounds,
        I: FieldBounds;
}

/// A field whose plain, form, and input types are given explicitly.
///
/// `FieldWith<F, P, E, I>` resolves to `P` when `F` is [`Plain`], to `E` when
/// `F` is [`Form`], and to `I` when `F` is [`Input`]. Use this instead of
/// [`Field`] when a type needs form/input representations different from the
/// defaults declared by its [`DefaultInputType`] implementation.
pub type FieldWith<F, P, E, I> = <F as FieldFamily>::Type<P, E, I>;

/// A field of plain type `P`, using `P`'s default form and input types.
///
/// The form and input representations are taken from `P`'s
/// [`DefaultInputType`] implementation. For example `u32` declares
/// `InputType = String` and `FormType = Edit<String>`, so:
///
/// ```
/// use validatable::*;
///
/// let plain: Field<Plain, u32> = 42u32;
/// let input: Field<Input, u32> = "42".to_string();
/// let form: Field<Form, u32> = Edit::from_input("42".to_string());
/// # let _ = (plain, input, form);
/// ```
pub type Field<F, P> =
    FieldWith<F, P, <P as DefaultInputType>::FormType, <P as DefaultInputType>::InputType>;