reliakit-primitives

Type-safe primitives for constrained and reliability-oriented Rust values.

reliakit-primitives provides small owned wrapper types for values that should satisfy common constraints before they move through an application or library boundary.

The crate has no dependencies and forbids unsafe code.

The goal is not to parse every domain-specific format perfectly. The goal is to make common invariants explicit in types, keep validation close to input boundaries, and avoid passing unchecked strings and numbers through public APIs.

What This Crate Does

This crate turns common validated values into explicit Rust types.

Instead of passing unchecked String, u16, u64, or f64 values through your code, construct a primitive once and let function signatures carry the invariant:

use reliakit_primitives::{Email, NonEmptyStr, Port};

fn configure_service(name: NonEmptyStr, contact: Email, port: Port) {
    // These values have already passed their basic validation rules.
}

let name = NonEmptyStr::new("api")?;
let contact = Email::new("ops@example.com")?;
let port = Port::new(8080)?;

configure_service(name, contact, port);

This is useful at boundaries such as configuration loading, request parsing, CLI input, test fixtures, and library APIs.

When To Use It

Use this crate when a value has simple validity rules that should be checked once and then carried as a typed value:

• names and identifiers that must not be empty,
• strings with minimum or maximum character lengths,
• slugs, email addresses, HTTP URLs, or hex strings,
• percentages, ports, positive integers, or positive floats,
• byte sizes that should display consistently,
• semantic version strings,
• UUIDs in canonical format,
• human-readable durations like 1h30m or 500ms.

When Not To Use It

Use a domain-specific validator, parser, serializer, or schema library when a value needs rules beyond these small general-purpose primitives.

For example, Email is a basic structural validator, not a full RFC 5321 or deliverability checker. HttpUrl checks for an HTTP(S) scheme and a non-empty host, but it is not a complete URL parser.

Installation

[dependencies]
reliakit-primitives = "0.4"

For no_std environments:

[dependencies]
reliakit-primitives = { version = "0.4", default-features = false, features = ["alloc"] }

Examples

Non-empty strings

use reliakit_primitives::NonEmptyStr;

let name = NonEmptyStr::new("service-api")?;

Bounded strings

use reliakit_primitives::BoundedStr;

type Username = BoundedStr<3, 32>;

let username = Username::new("satyakwok")?;

Numeric primitives

use reliakit_primitives::{ByteSize, Percent, Port};

let limit = ByteSize::from_mb(10);
let threshold = Percent::new(80)?;
let port = Port::new(3000)?;

Text primitives

use reliakit_primitives::{Email, HttpUrl, Slug};

let slug = Slug::new("service-api")?;
let email = Email::new("ops@example.com")?;
let url = HttpUrl::new("https://example.com/health")?;

assert_eq!(email.domain(), "example.com");
assert!(url.is_https());

Structured values

use reliakit_primitives::{HumanDuration, SemVer, Uuid};

let version = SemVer::parse("1.2.3-beta.1+build.5")?;
let request_id = Uuid::parse("550e8400-e29b-41d4-a716-446655440000")?;
let timeout = HumanDuration::parse("1m30s")?;

assert!(version.is_pre_release());
assert_eq!(request_id.version(), 4);
assert_eq!(timeout.as_duration().as_secs(), 90);

SemVer implements Rust's total Ord consistently with Eq. Build metadata is used as a final tie-breaker for ordering so BTreeSet, BTreeMap, sorting, and binary search behave correctly. Use SemVer::cmp_precedence when you need SemVer precedence rules that ignore build metadata.

Error handling

All fallible constructors return PrimitiveResult<T>, an alias for Result<T, PrimitiveError>.

use reliakit_primitives::{NonEmptyStr, PrimitiveError, PrimitiveErrorKind};

let err = NonEmptyStr::new("   ").unwrap_err();
assert_eq!(err, PrimitiveError::Empty);
assert_eq!(err.kind(), PrimitiveErrorKind::Empty);

Use PrimitiveErrorKind when you need stable programmatic matching without depending on display text.

Available Types

Strings

Numbers

Collections

Structured Values

Networking

Feature Flags

no_std

The crate supports no_std. Building with --no-default-features (no std, no alloc) provides the allocation-free primitives:

• numeric: Percent, PercentageF64, Port, PositiveInt, PositiveFloat, ByteSize,
• Uuid, MacAddress, Cidr, and HumanDuration (parsing and Display do not allocate),
• the error types (PrimitiveError, PrimitiveErrorKind, PrimitiveResult).

Enabling alloc adds the owned, allocation-backed types: Slug, Email, HttpUrl, HexString, Base64, Base32, Identifier, Hostname, NonEmptyStr, BoundedStr, NonEmptyVec, and SemVer. The default std build enables alloc for normal application use:

reliakit-primitives = { version = "0.4", default-features = false, features = ["alloc"] }

Safety

This crate is #![forbid(unsafe_code)].

Minimum Supported Rust Version

Rust 1.85 and newer. No nightly features are used.

Status

Active. The crate is published for real use and follows normal Rust crate versioning. APIs may still receive compatible refinements before a 1.0 release.

Contributing

See CONTRIBUTING.md.

License

Licensed under the MIT License.