error-rail 0.2.0

ErrorRail is a Error Handling library for the Rust language.
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

# error-rail

[![Crates.io Version](https://img.shields.io/crates/v/error-rail)](https://crates.io/crates/error-rail)
[![Documentation](https://docs.rs/error-rail/badge.svg)](https://docs.rs/error-rail)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**Composable, metadata-friendly error utilities for Rust.**

`error-rail` provides a middle ground between simple string errors and full-blown tracing systems. It allows you to attach rich, structured context to errors and collect multiple validation failures without early returns.

## Quick Start

> **New to error-rail?** Check out the [Quick Start Guide](QUICK_START.md) for a beginner-friendly introduction.

## Key Features

### 1. Structured Context

Wrap any error in `ComposableError` and attach layered metadata like messages, file locations, and tags.

```rust
use error_rail::{ComposableError, context, location, tag};

let err = ComposableError::<&str, u32>::new("db error")
    .with_context(tag!("database"))
    .with_context(location!())
    .with_context(context!("failed to connect"));
```

### 2. Validation Accumulation

Collect multiple errors instead of failing fast. Ideal for form validation or batch processing.

```rust
use error_rail::validation::Validation;

let v1 = Validation::<&str, i32>::valid(10);
let v2 = Validation::<&str, i32>::invalid("too small");
let combined: Validation<&str, Vec<i32>> = vec![v1, v2].into_iter().collect();

assert!(combined.is_invalid());
```

### 3. Ergonomic Traits

- **`IntoErrorContext`**: Convert your own types into error context.
- **`WithError`**: Transform error types while preserving success values.
- **`ErrorOps`**: Unified operations for recovery and mapping.

## Module Overview

- **`context`**: Core context types and pipeline builders.
- **`convert`**: Helpers to switch between `Result`, `Validation`, and `ComposableError`.
- **`macros`**: `context!`, `location!`, `tag!`, `metadata!`, `rail` for easy context creation.
- **`traits`**: Foundational traits (`ErrorCategory`, `ErrorOps`, etc.).
- **`types`**: `ComposableError` and related type aliases.
- **`validation`**: The `Validation` enum and accumulators.

## Installation

```sh
cargo add error-rail
```

## Examples

Run the bundled examples to see `error-rail` in action:

```sh
cargo run --example quick_start
cargo run --example readme_features
cargo run --example pipeline
cargo run --example validation_collect
```

## License

Apache-2.0