type-lib 1.0.0

Validation and type constraint library. Declare domain types with invariants enforced at construction. Parse-dont-validate pattern as a first-class citizen. Zero-overhead wrappers with derive macros.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# type-lib v1.0.0 — Stable

**1.0 is here.** The public API is frozen under SemVer: parse-dont-validate domain
types built from a small, composable core, with zero runtime overhead. There are
no code changes from `0.9.0` — this release is the stability commitment, the final
benchmark numbers, and the documentation that says so.

## What is type-lib?

A validation and type-constraint library for Rust. You declare domain types whose
invariants are enforced **once**, at construction, and proven by the type system
thereafter — so code that receives a validated value never re-checks it. Wrappers
are zero-overhead, the core is `no_std`-friendly, and rules are reusable and
composable.

```rust
use type_lib::combinator::And;
use type_lib::rules::{LenRange, Trimmed};
use type_lib::Refined;

type Username = Refined<String, And<Trimmed, LenRange<3, 16>>>;

let user = Username::new("alice".to_owned());
assert!(user.is_ok());
assert!(Username::new("  x  ".to_owned()).is_err());
```

With the `derive` feature, the same rule backs a named domain type:

```rust
use type_lib::combinator::And;
use type_lib::rules::{LenRange, Trimmed};
use type_lib::Validated;

#[derive(Validated)]
#[valid(And<Trimmed, LenRange<3, 16>>)]
pub struct Username(String);
```

## The 1.0 surface

- **Foundation** — [`Validator`] (a type-level rule), [`Refined<T, V>`] (a
  `#[repr(transparent)]` wrapper proven to satisfy `V`), and [`ValidationError`]
  (a `Copy`, allocation-free error).
- **Built-in rules** — length (`NonEmpty`, `MinLen`, `MaxLen`, `LenRange` over the
  `HasLength` trait), numeric (`Positive`, `NonNegative`, `Negative`,
  `NonPositive`, `InRange`), and string (`Ascii`, `Alphanumeric`, `Trimmed`).
- **Combinators** — `And`, `Or`, `Not`, composing rules at the type level.
- **Derive** — `#[derive(Validated)]` with `#[valid(<Validator>)]`, behind the
  `derive` feature.
- **`prelude`** and the `VERSION` constant.

## Stability promise

`v1.0.0` is covered by [Semantic Versioning](https://semver.org/):

- No breaking change ships without a `2.0`.
- New rules, combinators, and trait impls arrive as additive `1.x` minor releases.
- Bug fixes are patch releases.
- The error **codes** returned by the built-in rules (`"non_empty"`, `"max_len"`,
  `"in_range"`, `"trimmed"`, `"not"`, …) are stable across `1.x`; only
  human-readable messages may be reworded.
- [`Validator`] and `HasLength` are intentionally open (not sealed) — implementing
  them for your own rules and containers is a supported, stable extension point.

MSRV is **Rust 1.75**, and a change to it will be treated as a minor-version bump.

## Performance

Validation is the only runtime cost; the wrapper adds none. Final Criterion means
(Windows x86_64, Rust stable 1.95, `cargo bench --bench validation`):

| Operation | Time |
|---|---|
| `Refined::new` — `Ascii` on a short `&str` | ~1.01 ns |
| `Refined::new` — `LenRange<3, 16>` on a `&str` | ~2.39 ns |
| `Refined::new` — `InRange<0, 100>` on an `i32` | ~2.58 ns |
| `Refined::get` | ~0.23 ns |
| `Refined` `Deref` | ~0.23 ns |

The accessors compile down to a field read; `Refined<T, V>` is the same size as
`T`.

## Breaking changes

**None.** `v1.0.0` is identical in behaviour and API to `v0.9.0`.

## Verification

Run on Windows x86_64 (Rust stable 1.95 and MSRV 1.75.0) and on Linux (WSL2
Ubuntu); identical commands pass via the CI matrix (Linux/macOS/Windows ×
{stable, 1.75.0}):

```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo clippy --no-default-features --lib --tests -- -D warnings
cargo test --workspace --all-features
cargo test --no-default-features
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --no-default-features
cargo bench --bench validation
```

All green. Counts at this tag:

- `--all-features`: 26 unit + 4 derive + 6 other integration + 8 property + 38 doctests.
- `--no-default-features`: 26 unit + 6 integration + 8 property + 37 doctests.

The published `type-lib` crate has no runtime dependencies by default; the
`derive` feature adds `syn` / `quote` / `proc-macro2` at build time.

## Installation

```toml
[dependencies]
type-lib = "1.0.0"

# with the derive macro
type-lib = { version = "1.0.0", features = ["derive"] }

# no_std (core API + borrowed-value rules)
type-lib = { version = "1.0.0", default-features = false }
```

MSRV: Rust 1.75.

## Documentation

- [README](https://github.com/jamesgober/type-lib/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/type-lib/blob/main/docs/API.md)
- [CHANGELOG](https://github.com/jamesgober/type-lib/blob/main/CHANGELOG.md)

## Thanks

To everyone who kicked the tyres through the `0.x` series. Onward to `1.x`.

---

**Full diff:** [`v0.9.0...v1.0.0`](https://github.com/jamesgober/type-lib/compare/v0.9.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/type-lib/blob/main/CHANGELOG.md#100---2026-05-27).