Merge pull request #219 from greyblake/derive-unsafe

Derive unsafe

Author: greyblake

CHANGELOG.md

@@ -1,5 +1,6 @@
 ### v0.x.x - 2025-xx-xx
-- Update Rust edition: 2021 -> 2024
+- Introduce `derive_unsafe(..)` attribute to derive any arbitrary trait (requires `derive_unsafe` feature to be enabled).
+- Update Rust edition: 2021 -> 2024.
 - Improve error messages for `len_char_max` and `len_char_min` validators.
 
 ### v0.6.1 - 2025-02-09

Cargo.lock

@@ -10,6 +10,7 @@ members = [
 
     # All examples except "no_std_example" are tested in the test suite
     "examples/any_arbitrary",
+    "examples/derive_unsafe_example",
     "examples/float_arbitrary",
     "examples/float_sortable",
     "examples/integer_arbitrary",

Cargo.toml

@@ -5,10 +5,11 @@ Example: trim trailing spaces and lowercase an email address.
 * _Validator_ - a **fallible** operation, that checks if a piece of data matches some given rules.
 Example: ensure that an email address contains `@` character. Validators come with associated error variants.
 
-* _Guard_ - a generic term that covers both sanitizers and validators.
+* _Guard_ - an umbrella term that covers both sanitizers and validators.
 
 * _Inner Type_ - typically a simple type that is wrapped by a newtype.
 Example: consider `Email` type defined as `Email(String)`. We have say that `Email` has inner type `String`.
 
 * _Transparent trait_ - a trait that can be simply derived (e.g. `Debug`, `Clone`).
-* _Irregular trait_ a trait that requires a custom implementation to be generated (e.g. `TryFrom`).
+* _Irregular trait_ - a trait that requires a custom implementation to be generated (e.g. `TryFrom`).
+* _Unsafe trait_ - a trait that potentially may violate the constraints. Traits derive with `derive_unsafe(...)` are not validated by nutype.

GLOSSARY.md

@@ -21,6 +21,7 @@ Nutype is a proc macro that allows adding extra constraints like _sanitization_
 * [Quick start](#quick-start)
 * [Inner types](#inner-types) ([String](#string) | [Integer](#integer) | [Float](#float) | [Other](#other-inner-types-and-generics))
 * [Custom](#custom-sanitizers) ([sanitizers](#custom-sanitizers) | [validators](#custom-validators) | [errors](#custom-validation-with-a-custom-error-type))
+* [Deriving traits](#deriving-traits)
 * [Constants](#constants)
 * [Recipes](#recipes)
 * [Breaking constraints with new_unchecked](#breaking-constraints-with-new_unchecked)
@@ -346,6 +347,40 @@ struct Name(String);
 
 It's important to ensure that the type specified in the `error` attribute matches the error type returned by the validation function.
 
+
+## Deriving Traits
+
+There are two ways to derive traits for a `nutype`.
+
+### `derive`
+
+The recommended approach is to use the `derive(..)` attribute within the `#[nutype(..)]` macro:
+
+```rust
+#[nutype(derive(Debug))]
+pub struct Username(String);
+```
+
+When using `derive`, `nutype` ensures that the derived traits do not compromise the type's invariants (i.e., validation constraints).
+
+However, this approach has a limitation: only a predefined set of traits is supported. Deriving arbitrary third-party traits is not allowed via `derive`.
+
+### `derive_unsafe`
+
+To overcome this limitation, you can use the `derive_unsafe(..)` attribute (requires the corresponding feature flag to be enabled):
+
+```rust
+use derive_more::DerefMut;
+
+#[nutype(derive_unsafe(DerefMut))]
+pub struct Username(String);
+```
+
+This enables deriving arbitrary traits, including those from third-party crates.
+However, **use this with caution**: `nutype` cannot verify that these traits preserve the invariants of the type.
+It is the developer’s responsibility to ensure that the derived traits do not introduce ways to bypass validation (e.g., by allowing mutable access to the inner value).
+
+
 ## Constants
 
 You can mark a type with the `const_fn` flag. In that case, its `new` and `try_new` functions will be declared as `const`:
@@ -446,6 +481,7 @@ assert_eq!(name.into_inner(), " boo ");
 ## Feature flags
 
 * `arbitrary` - enables derive of [`arbitrary::Arbitrary`](https://docs.rs/arbitrary/latest/arbitrary/trait.Arbitrary.html).
+* `derive_unsafe` - enables `derive_unsafe` attribute to derive any arbitrary trait.
 * `new_unchecked` - enables generation of unsafe `::new_unchecked()` function.
 * `regex` - allows to use `regex = ` validation on string-based types. Note: your crate also has to explicitly have `regex` within its dependencies.
 * `serde` - integrations with [`serde`](https://crates.io/crates/serde) crate. Allows to derive `Serialize` and `Deserialize` traits.
@@ -490,6 +526,7 @@ Thank you.
 * [refinement](https://docs.rs/refinement/latest/refinement/) - Convenient creation of type-safe refinement types (based on generics).
 * [semval](https://github.com/slowtec/semval) - Semantic validation for Rust.
 * [validator](https://github.com/Keats/validator) - Simple validation for Rust structs (powered by macros).
+* [derive_more](https://github.com/JelteF/derive_more) - If you just need to derive traits on a newtype without extra logic.
 
 ## License
 

README.md

@@ -6,7 +6,7 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-nutype = { path = "../nutype", features = ["serde", "new_unchecked", "schemars08", "regex", "arbitrary"] }
+nutype = { path = "../nutype", features = ["serde", "new_unchecked", "schemars08", "regex", "arbitrary", "derive_unsafe"] }
 serde = "*"
 serde_json = "*"
 schemars = "*"

dummy/Cargo.toml

@@ -1,6 +1,9 @@
 use nutype::nutype;
 
-#[nutype(derive(Debug), validate(len_char_max = 5, len_char_min = 3))]
+#[nutype(
+    derive_unsafe(::std::fmt::Debug),
+    validate(len_char_max = 5, len_char_min = 3)
+)]
 struct Name(String);
 
 fn main() {

dummy/src/main.rs

@@ -0,0 +1,10 @@
+[package]
+name = "derive_unsafe_example"
+version = "0.1.0"
+edition = "2024"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+derive_more = { version = "2.0.1", features = ["deref", "deref_mut"] }
+nutype = { path = "../../nutype", features = ["derive_unsafe"] }

examples/derive_unsafe_example/Cargo.toml

@@ -0,0 +1,21 @@
+// WATCH OUT: derive_unsafe() allows to derive any trait even those that may create loopholes
+// in the validation and sanitization logic!
+use derive_more::{Deref, DerefMut};
+use nutype::nutype;
+
+#[nutype(
+    derive(Debug, AsRef),
+    derive_unsafe(Deref, DerefMut),
+    validate(greater_or_equal = 0.0, less_or_equal = 2.0)
+)]
+struct LlmTemperature(f64);
+
+fn main() {
+    let mut temperature = LlmTemperature::try_new(1.5).unwrap();
+
+    // This is not what nutype is designed for!
+    *temperature = 2.5;
+
+    // OH no, we've just violated the validation rule!
+    assert_eq!(temperature.as_ref(), &2.5);
+}

examples/derive_unsafe_example/src/main.rs

@@ -31,3 +31,4 @@ regex = ["nutype_macros/regex"]
 schemars08 = ["nutype_macros/schemars08"]
 new_unchecked = ["nutype_macros/new_unchecked"]
 arbitrary = ["nutype_macros/arbitrary"]
+derive_unsafe = ["nutype_macros/derive_unsafe"]