# validatable
Define a data type once and share it — with validation — between the
frontend and backend of an isomorphic Rust web application.
A type deriving `Validatable` is generic over a *field family* and expands
into three synchronized representations:
* **`T<Plain>`** — the validated domain value.
* **`T<Input>`** — the raw input, e.g. an API request payload.
* **`T<Form>`** — the form state while editing, with a validation result per
field.
The only ways to obtain a `T<Plain>` are validating a `T<Form>` or
`T<Input>`, or deserializing from trusted storage — so "this data has been
validated" becomes a guarantee of the type system, *for invariants that live
entirely inside one field*. A `Validated` field is safe to make `pub`: its
only constructor is validation, so a struct literal can only place an
already-valid value there. But `T<Plain>` itself is a struct, and a struct
literal is a constructor too — if its fields are `pub` (a common pattern
when building API payloads), any invariant that spans more than one field
can be violated by assembling independently valid field values into a
combination that was never actually validated together, regardless of
whether `CustomValidate` / `#[validatable(custom_validate)]` checks that
combination during a real `validate()` call. Keep the fields of a type with
cross-field invariants private — and expose read accessors instead —
whenever those invariants must hold unconditionally.
## Example
```rust
use validatable::*;
// A reusable validated string type: trimmed, then 1..=20 characters.
type UserName = Validated<String, Chain<Trim, LengthRange<1, 20>>>;
#[derive(Validatable, PartialEq, Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
struct User<F: FieldFamily> {
name: Field<F, UserName>,
age: Field<F, u8>,
active: Field<F, bool>,
}
// Frontend: the user edits a `User<Form>`.
let mut form = User::<Form>::default();
form.name.input(" Alice ".to_string());
form.age.input("17".to_string());
form.active.input(true);
// Validation yields a `User<Plain>` on success.
let user: User<Plain> = form.validate().expect("form is valid");
assert_eq!(user.name.to_string(), "Alice"); // trimmed by `Trim`
assert_eq!(user.age, 17);
// On failure it returns `None` and writes a message into each offending field.
form.age.input("seventeen".to_string());
assert_eq!(form.validate(), None);
assert_eq!(
form.age.message,
Some(Message::BadFormat(Format::UnsignedInteger))
);
// UI-less input (e.g. an API request payload) uses `User<Input>`.
let input = User::<Input> {
name: "Bob".to_string(),
age: "42".to_string(),
active: true,
};
let user: User<Plain> = input.validate().expect("input is valid");
// `User<Plain>` serializes as ordinary data for storage or transfer,
// with the `serde` feature enabled.
#[cfg(feature = "serde")]
{
let json = serde_json::to_string(&user).unwrap();
assert_eq!(json, r#"{"name":"Bob","age":42,"active":true}"#);
}
```
The single definition of `User` above produces these three concrete types:
| `name` | `UserName` | `String` | `Edit<String>` |
| `age` | `u8` | `String` | `Edit<String>` |
| `active` | `bool` | `bool` | `Edit<bool>` |
## The three representations
### `T<Plain>`
The validated value, plain and simple.
* On the backend:
* validate a submitted `T<Form>` or `T<Input>` into a `T<Plain>` and work
safely with that,
* serialize `T<Plain>` data into storage,
* restore `T<Plain>` data from trusted storage.
* On the frontend:
* receive `T<Plain>` data from the backend (detail and list views), and
turn it into a form with `.into_form()` when editing starts.
### `T<Form>`
The state of an input form while the user edits a `T`. Each field holds its
input in an editable representation — a numeric field is a `String` the user
can type into — together with the latest validation result (`Edit<I>` with
`value`, `message`, and `edited`). `form.validate()` checks every field,
stores a `Message` on each invalid one, and returns the `T<Plain>` when the
whole form is valid. The `edited` flag is set by `Edit::input` and lets the
UI suppress error messages on fields the user has not touched yet.
### `T<Input>`
`T<Form>` stripped of the validation results: input without a UI, mainly for
sending data to the backend through an API. A typical endpoint receives a
`T<Input>` and responds with `Result<T<Plain>, T<Form>>`, so the client
learns exactly which fields failed:
```rust
// Backend endpoint: validate the payload, return per-field errors on failure.
fn create_user(input: User<Input>) -> Result<User<Plain>, User<Form>> {
let mut form = input.into_form();
match form.validate() {
Some(user) => Ok(user),
None => Err(form),
}
}
```
## Validated primitive values
`Validated<T, VI, VP>` attaches type-level validators to a single value:
`VI` validates (and may transform) the raw input before parsing, `VP`
validates the parsed value. Validators are zero-sized types composed with
`Chain` / `And` / `Or` / `Not`:
```rust
type UserName = Validated<String, Chain<Trim, LengthRange<1, 20>>>;
type Quantity = Validated<u32, Trim, UnsignedValueRange<5, 100>>;
type Rating = Validated<f64, True, FloatValueRangeX1000<0, 5_000>>; // 0.0..=5.0
type Hex = Validated<NonEmptyString, AllChars<CharClassAsciiHexdigit>>;
```
`NonEmptyString` (re-exported from
[`non-empty-string`](https://crates.io/crates/non-empty-string)) can serve as
the plain type when the value must not be empty: the input is validated as a
`String` and non-emptiness is enforced when it is parsed, so empty input
fails with `Message::Empty` even when the validators accept it.
Built-in validators include:
* `LengthMin` / `LengthMax` / `LengthRange` — string length in characters
(`chars().count()`, not bytes)
* `SignedValueMin/Max/Range`, `UnsignedValueMin/Max/Range` — integer bounds
* `FloatValueMinX1000/MaxX1000/RangeX1000` — float bounds given as integers
scaled by 1000 (const generics cannot be floats); beware of values not
exactly representable in the target float type
* `AllChars<C>` — all characters must belong to a character class
(`CharClassAsciiDigit`, `CharClassAlphanumeric`, `CharClassJust<'x'>`, …,
composable with `And` / `Or` / `Not`); an empty string passes vacuously —
use `NonEmptyString` as the plain type or add `LengthMin<1>` when content
is required
* `Trim`, `TrimChars<C>`, `RemoveChars<C>` — **transforming** validators
that change the value (the validated result may differ from the input)
* `Variant<N>` — a no-op marker that makes otherwise identical types
distinct:
```rust
type Name = Validated<NonEmptyString, Chain<AllChars<CharClassAscii>, Variant<1>>>;
type Id = Validated<NonEmptyString, Chain<AllChars<CharClassAscii>, Variant<2>>>;
```
Custom rules implement the `Validator` trait; custom field types implement
`ValidatableValue`.
## Nested types and collections
Derived types nest: a `Validatable` type — or a `Vec` of one — is a field
like any other, and every representation nests accordingly. The form of the
`Order` below contains an `Address<Form>` and one `OrderLine<Form>` per row,
so an "add line" button in the UI just pushes a default sub-form:
```rust
use validatable::*;
type Name = Validated<String, Chain<Trim, LengthRange<1, 40>>>;
type Zip = Validated<String, Chain<AllChars<CharClassAsciiDigit>, LengthRange<7, 7>>>;
type Quantity = Validated<u32, Trim, UnsignedValueRange<1, 99>>;
#[derive(Validatable, PartialEq, Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
struct Address<F: FieldFamily> {
city: Field<F, Name>,
zip: Field<F, Zip>,
}
#[derive(Validatable, PartialEq, Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
struct OrderLine<F: FieldFamily> {
product: Field<F, Name>,
quantity: Field<F, Quantity>,
}
#[derive(Validatable, PartialEq, Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
struct Order<F: FieldFamily> {
shipping: Address<F>, // nested: an `Address<Form>` inside an `Order<Form>`
lines: Vec<OrderLine<F>>, // repeated rows: `Vec<OrderLine<Form>>`
}
let mut form = Order::<Form>::default(); // `lines` starts empty
form.shipping.city.input("Osaka".to_string());
form.shipping.zip.input("5300001".to_string());
// The user clicks "add line": push a fresh sub-form and edit it.
form.lines.push(OrderLine::<Form>::default());
form.lines[0].product.input("Coffee beans".to_string());
form.lines[0].quantity.input("2".to_string());
form.lines.push(OrderLine::<Form>::default());
form.lines[1].product.input("Paper filter".to_string());
form.lines[1].quantity.input("0".to_string());
// Validation walks the whole tree; the error lands on the exact field.
assert_eq!(form.validate(), None);
assert_eq!(
form.lines[1].quantity.message,
Some(Message::ValueExceedMin("1".to_string()))
);
form.lines[1].quantity.input("3".to_string());
let order: Order<Plain> = form.validate().expect("form is valid");
// The validated tree serializes as ordinary nested data,
// with the `serde` feature enabled.
#[cfg(feature = "serde")]
{
let json = serde_json::to_string(&order).unwrap();
assert_eq!(
json,
r#"{"shipping":{"city":"Osaka","zip":"5300001"},"lines":[{"product":"Coffee beans","quantity":2},{"product":"Paper filter","quantity":3}]}"#
);
}
```
Swap `Vec` for `NonEmpty` or `BoundedVec` when the number of rows must be
constrained (e.g. an order needs at least one line).
## Derive reference
`#[derive(Validatable)]` supports two kinds of types:
* **Family mode** — a struct or enum with exactly one generic parameter
bound by `FieldFamily`. Fields written as `Field<F, T>`,
`FieldWith<F, Plain, Form, Input>`, or a nested derived type `Inner<F>`
switch representation per family; all other fields stay the same in all
three representations. For enums, the default input is the **first
variant**.
* **Newtype mode** — a single-field tuple struct such as
`struct UserId(Validated<u64, Trim>);`, which forwards validation to the
inner type so the newtype can be used as a field.
Attributes:
* `#[validatable(custom_validate)]` on the type routes `validate()` through
your `CustomValidate` impl on `T<Form>`, for cross-field rules
(implemented with `validate_by`, which first runs the derived per-field
validation). The rule only holds for values that actually went through
`validate()`: `T<Plain>` is a struct, so if its fields are `pub`, a
struct literal is just another constructor, and it can assemble a
combination of independently valid field values that this rule never
checked. Keep the fields private when the invariant must hold
unconditionally.
* `#[validatable(default = expr)]` on a field overrides the default input
value used by `T<Form>::default()` / `T<Input>::default()`.
Do not also write `#[derive(Default)]` on a type deriving `Validatable`:
the derive already implements `Default` for `T<Form>` and `T<Input>`, and a
second, derived `Default` impl for the same generic type conflicts with it
(`E0119`).
Collections compose: `Vec<T>`, `NonEmpty<T>` (re-exported from
[`nonempty`](https://crates.io/crates/nonempty)), and
`BoundedVec<T, MIN, MAX>` (length checked at validation time, `MIN <= MAX`
checked at compile time) of validatable elements are validatable themselves.
## Deserialization is not validation
`Deserialize` implementations in this crate restore data **without running
any validators**. Deserialization is a conversion intended for trusted
sources — your own storage, your own backend. Data from untrusted sources
must be received as `T<Input>` / `T<Form>` and validated explicitly. Note
that a plain type's own `Deserialize` implementation still applies its own
constraints: deserializing an empty string into a
`Validated<NonEmptyString, …>` fails, for example, because `NonEmptyString`
itself rejects it.
## Requirements
Field types are currently expected to satisfy
`PartialEq + Clone + Debug`, plus `Serialize + DeserializeOwned` when the
`serde` feature is enabled — see `FieldBounds`.
## Feature flags
* `serde` (off by default) — derives/implements `Serialize` and
`Deserialize` for the crate's own types (`Edit`, `Message`, `Format`,
`BoundedVec`, `ValidatedValue`, the family markers) and requires field
types to implement them too.
## License
Licensed under either of
* Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>)
* MIT license (<http://opensource.org/licenses/MIT>)
at your option. See [LICENSE](LICENSE) for the full text of both licenses.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.