# suwrap
> Explicit, contextual replacement for `unwrap()`.
`suwrap` is a tiny utility crate that provides a disciplined alternative to
`unwrap()` and `expect()`.
It makes invariant failures explicit and consistently contextual.
---
## ✨ Why?
`unwrap()` and `expect()` panic without structured meaning.
They:
- Hide the invariant being enforced
- Lose domain context
- Create inconsistent panic messages
- Encourage casual failure handling
`suwrap` enforces **explicit invariant naming** and consistent failure style.
---
## 📦 Installation
Add to your `Cargo.toml`:
```toml
[dependencies]
suwrap = "0.1"
```
---
## 🔥 Basic Usage
### Instead of this:
```rust
let user = maybe_user.unwrap();
```
### Write this:
```rust
use suwrap::SafeUnwrap;
let user = maybe_user.sunwrap("user must exist");
```
If the invariant fails, it panics with a structured message:
```
[INVARIANT VIOLATION]
Context: user must exist
```
---
## 🧠 Option Example
```rust
use suwrap::SafeUnwrap;
let config = std::env::var("DATABASE_URL")
.ok()
.sunwrap("DATABASE_URL must be set");
```
---
## 🧠 Result Example
```rust
use suwrap::SafeUnwrap;
let file = std::fs::read_to_string("config.toml")
.sunwrap("config file must be readable");
```
---
## 🎯 Design Principles
- No silent unwrap
- Explicit invariant description
- Zero runtime cost beyond panic formatting
- Minimal API surface
- No dependencies
---
## 🛡 Philosophy
`sunwrap()` is not error handling.
It is **invariant enforcement**.
Use it when:
- Failure means programmer bug
- The program should stop
- The condition must always hold
Do **not** use it for recoverable errors.
---
## 📄 License
MIT OR Apache-2.0