reliakit-primitives 0.2.0

Reusable type-safe primitives for constrained and reliability-oriented Rust values.
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
142
143
144
145
146
147
148

<p align="center">
  <img src="https://raw.githubusercontent.com/satyakwok/reliakit/main/assets/reliakit-logo.png" alt="Reliakit" width="400">
</p>

# reliakit-primitives

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

[![Crates.io](https://img.shields.io/crates/v/reliakit-primitives.svg)](https://crates.io/crates/reliakit-primitives)
[![Crates.io Downloads](https://img.shields.io/crates/d/reliakit-primitives.svg)](https://crates.io/crates/reliakit-primitives)
[![Docs.rs](https://docs.rs/reliakit-primitives/badge.svg)](https://docs.rs/reliakit-primitives)
[![CI](https://github.com/satyakwok/reliakit/actions/workflows/ci.yml/badge.svg)](https://github.com/satyakwok/reliakit/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/satyakwok/reliakit/branch/main/graph/badge.svg)](https://codecov.io/gh/satyakwok/reliakit)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/satyakwok/reliakit/blob/main/LICENSE)

`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.

## 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

Do not use this crate as a replacement for domain-specific validation, parsing, serialization, or schema libraries. The types here are intentionally small and general.

## Installation

```toml
[dependencies]
reliakit-primitives = "0.2"
```

For `no_std` environments:

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

## Examples

### Non-empty strings

```rust
use reliakit_primitives::NonEmptyStr;

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

### Bounded strings

```rust
use reliakit_primitives::BoundedStr;

type Username = BoundedStr<3, 32>;

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

### Numeric primitives

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

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

## Available Types

### Strings

| Type | Description |
|---|---|
| `NonEmptyStr` | Owned string that is not empty and not whitespace-only |
| `BoundedStr<MIN, MAX>` | Owned string constrained by character length |
| `Slug` | Lowercase alphanumeric + hyphens, URL-safe |
| `Email` | Basic structural email validation |
| `HttpUrl` | URL that must start with `http://` or `https://` |
| `HexString` | Hexadecimal characters with optional `0x`/`0X` prefix |

### Numbers

| Type | Description |
|---|---|
| `Percent` | Integer percentage from `0` to `100` inclusive |
| `PercentageF64` | Float percentage from `0.0` to `100.0` inclusive |
| `Port` | TCP/UDP port from `1` to `65535` inclusive |
| `PositiveInt` | `u64` strictly greater than zero |
| `PositiveFloat` | Finite `f64` strictly greater than zero |
| `ByteSize` | Byte size value with human-readable display output |

### Collections

| Type | Description |
|---|---|
| `NonEmptyVec<T>` | `Vec<T>` guaranteed to contain at least one element |

### Structured Values

| Type | Description |
|---|---|
| `SemVer` | Semantic version (`1.2.3`, `2.0.0-beta.1`, `1.0.0+build`) |
| `Uuid` | UUID in `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` format |
| `HumanDuration` | Duration parsed from `1h`, `30m`, `45s`, `500ms`, or combinations |

## Feature Flags

| Flag | Default | Description |
|---|---|---|
| `std` | yes | Enables `std::error::Error` for `PrimitiveError` |
| `alloc` | no | Enables allocation-backed types without `std` |

## `no_std`

The crate supports `no_std` environments when `std` feature is disabled and `alloc` is available.

## Safety

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

## Minimum Supported Rust Version

Rust stable. No nightly features are used.

## Status

Active. The `0.2.x` API is considered stable for the current set of types.

## Contributing

See [CONTRIBUTING.md](https://github.com/satyakwok/reliakit/blob/main/CONTRIBUTING.md).

## License

Licensed under the [MIT License](https://github.com/satyakwok/reliakit/blob/main/LICENSE).