error-stack 0.5.0

A context-aware error-handling library that supports arbitrary attached user data
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
149
150
151

[announcement post]: https://hash.dev/blog/announcing-error-stack
[crates.io]: https://crates.io/crates/error-stack
[libs.rs]: https://lib.rs/crates/error-stack
[rust-version]: https://www.rust-lang.org
[documentation]: https://docs.rs/error-stack
[license]: https://github.com/hashintel/hash/blob/main/libs/error-stack/LICENSE.md
[discord]: https://hash.ai/discord?utm_medium=organic&utm_source=github_readme_hash-repo_error-stack

[![crates.io](https://img.shields.io/crates/v/error-stack)][crates.io]
[![libs.rs](https://img.shields.io/badge/libs.rs-error--stack-orange)][libs.rs]
[![rust-version](https://img.shields.io/static/v1?label=Rust&message=1.63.0/nightly-2024-07-08&color=blue)][rust-version]
[![documentation](https://img.shields.io/docsrs/error-stack)][documentation]
[![license](https://img.shields.io/crates/l/error-stack)][license]
[![discord](https://img.shields.io/discord/840573247803097118)][discord]

[Open issues](https://github.com/hashintel/hash/issues?q=is%3Aissue+is%3Aopen+label%3AA-error-stack) / [Discussions](https://github.com/hashintel/hash/discussions?discussions_q=label%3AA-error-stack)

# error-stack

**`error-stack` is a context-aware error-handling library that supports arbitrary attached user data.**

Read our [announcement post] for the story behind its origins.

The library enables building a `Report` around an error as it propagates:

```rust
use core::fmt;

use error_stack::{Context, Report, Result, ResultExt};

#[derive(Debug)]
struct ParseExperimentError;

impl fmt::Display for ParseExperimentError {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str("invalid experiment description")
    }
}

impl Context for ParseExperimentError {}

fn parse_experiment(description: &str) -> Result<(u64, u64), ParseExperimentError> {
    let value = description
        .parse::<u64>()
        .attach_printable_lazy(|| format!("{description:?} could not be parsed as experiment"))
        .change_context(ParseExperimentError)?;

    Ok((value, 2 * value))
}

#[derive(Debug)]
struct ExperimentError;

impl fmt::Display for ExperimentError {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str("experiment error: could not run experiment")
    }
}

impl Context for ExperimentError {}

fn start_experiments(
    experiment_ids: &[usize],
    experiment_descriptions: &[&str],
) -> Result<Vec<u64>, ExperimentError> {
    let experiments = experiment_ids
        .iter()
        .map(|exp_id| {
            let description = experiment_descriptions.get(*exp_id).ok_or_else(|| {
                Report::new(ExperimentError)
                    .attach_printable(format!("experiment {exp_id} has no valid description"))
            })?;

            let experiment = parse_experiment(description)
                .attach_printable(format!("experiment {exp_id} could not be parsed"))
                .change_context(ExperimentError)?;

            Ok(move || experiment.0 * experiment.1)
        })
        .collect::<Result<Vec<_>, ExperimentError>>()
        .attach_printable("unable to set up experiments")?;

    Ok(experiments.iter().map(|experiment| experiment()).collect())
}

fn main() -> Result<(), ExperimentError> {
    let experiment_ids = &[0, 2];
    let experiment_descriptions = &["10", "20", "3o"];
    start_experiments(experiment_ids, experiment_descriptions)?;

    Ok(())
}
```

This will most likely result in an error and print

<pre>
Error: <b>experiment error: could not run experiment</b>
&#x251C;&#x2574;at <i>examples/demo.rs:50:18</i>
&#x251C;&#x2574;unable to set up experiments
&#x2502;
&#x251C;&#x2500;&#x25B6; <b>invalid experiment description</b>
&#x2502;   &#x251C;&#x2574;at <i>examples/demo.rs:20:10</i>
&#x2502;   &#x2570;&#x2574;experiment 2 could not be parsed
&#x2502;
&#x2570;&#x2500;&#x25B6; <b>invalid digit found in string</b>
    &#x251C;&#x2574;at <i>examples/demo.rs:19:10</i>
    &#x251C;&#x2574;backtrace with 31 frames (1)
    &#x2570;&#x2574;&quot;3o&quot; could not be parsed as experiment

&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;&#x2501;

backtrace no. 1
   0: std::backtrace_rs::backtrace::libunwind::trace
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5
   1: std::backtrace_rs::backtrace::trace_unsynchronized
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
   2: std::backtrace::Backtrace::create
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/std/src/backtrace.rs:331:13
   3: core::ops::function::FnOnce::call_once
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/core/src/ops/function.rs:250:5
   4: core::bool::&lt;impl bool&gt;::then
             at /rustc/f3623871cfa0763c95ebd6ceafaa6dc2e44ca68f/library/core/src/bool.rs:60:24
   5: error_stack::report::Report&lt;C&gt;::from_frame
             at ./src/report.rs:286:25
   6: error_stack::report::Report&lt;C&gt;::new
             at ./src/report.rs:272:9
   7: error_stack::context::&lt;impl core::convert::From&lt;C&lt; for error_stack::report::Report&lt;C&gt;&gt;::from
             at ./src/context.rs:83:9
   8: &lt;core::result::Result&lt;T,C&lt; as error_stack::result::ResultExt&lt;::attach_printable_lazy
             at ./src/result.rs:158:31
   9: demo::parse_experiment
             at demo.rs:17:17
  10: demo::start_experiments::{{closure}}
             at demo.rs:48:30
   (<b>For this example:</b> additional frames have been removed)
</pre>

## Usage

Please see the [documentation].

For more examples of `error-stack` in use, please check out the [examples](https://github.com/hashintel/hash/tree/main/libs/error-stack/examples) folder.

## Contributors

`error-stack` was created and is maintained by [HASH](https://hash.dev/). As an open-source project, we gratefully accept external contributions and have published a [contributing guide](https://github.com/hashintel/hash/blob/main/.github/CONTRIBUTING.md) that outlines the process. If you have questions, please reach out to us on our [Discord server](https://hash.ai/discord?utm_medium=organic&utm_source=github_readme_hash-repo_libs-error-stack-readme).

## License

`error-stack` is available under a number of different open-source licenses. Please see the [LICENSE] file to review your options.