cdumay_result 1.0.2

A library to serialize and deserialize result using serde
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
152
153
154
155
156
157
158
159
160
161
162
163

# cdumay_result

[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
[![cdumay_result on crates.io](https://img.shields.io/crates/v/cdumay_result)](https://crates.io/crates/cdumay_result)
[![cdumay_result on docs.rs](https://docs.rs/cdumay_result/badge.svg)](https://docs.rs/cdumay_result)
[![Source Code Repository](https://img.shields.io/badge/Code-On%20GitHub-blue?logo=GitHub)](https://github.com/cdumay/cdumay_result)

A Rust library for standardizing operation results and their serialization using [serde](https://docs.serde.rs/serde/).
This crate provides a flexible and consistent way to handle operation results, including success and error cases,
with support for structured data, stdout/stderr outputs, and serialization.

### Features

- Structured result type with support for return values and output streams
- UUID generation for result tracking
- Integration with error handling systems
- Builder pattern for easy result construction

### Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
cdumay_result = "1.0"
serde_json = "1.0"  # For JSON serialization
cdumay_error = "1.0"  # For error handling
cdumay_error_standard = "1.0"  # For error example
cdumay_context = "1.0" # For context use
```

### Basic Usage

Here's a simple example of creating and using a successful result:

```rust
use cdumay_result::{ResultBuilder, Result};
use std::collections::BTreeMap;
use serde_value::Value;

// Creating a successful result with data
let result = ResultBuilder::default()
    .stdout("Operation completed successfully".into())
    .retval({
        let mut values = BTreeMap::new();
        values.insert("status".into(), Value::String("completed".into()));
        values.insert("count".into(), Value::U8(42.into()));
        values
    })
    .build();

// Serialize to JSON
println!("{}", serde_json::to_string_pretty(&result).unwrap());
```

### Context Usage

Here's a simple example of creating and using a successful result using `cdumay_context`:

```rust
use cdumay_result::{ResultBuilder, Result};
use cdumay_context::Context;
use std::collections::BTreeMap;
use serde_value::Value;

// Creating a context
let mut context = Context::new();
context.insert("status".into(), Value::String("completed".into()));
context.insert("count".into(), Value::U8(42.into()));

// Creating a successful result with data
let result = ResultBuilder::default()
    .stdout("Operation completed successfully".into())
    .retval(context.into())
    .build();

// Serialize to JSON
println!("{}", serde_json::to_string_pretty(&result).unwrap());
```

### Error Handling

Example using error handling with `cdumay_error_standard`:

```rust
use cdumay_result::Result;
use cdumay_error_standard::Unexpected;
use cdumay_error::{AsError, Error};
use serde_value::Value;

fn process_data() -> Result {
    // Simulate an error condition
    let error = Unexpected::new()
        .set_message("Failed to process data".into())
        .set_details({
            let mut details = std::collections::BTreeMap::new();
            details.insert(
                "error_type".into(),
                Value::String("processing_error".into())
            );
            details
        });

    // Convert error into Result
    Result::from(Error::from(error))
}
```

### Custom Result Builder

Example of using the builder pattern with custom data:

```rust
use cdumay_result::ResultBuilder;
use std::collections::BTreeMap;
use std::fmt::format;
use serde_value::Value;
use uuid::Uuid;

// Create a custom result with specific UUID
let result = ResultBuilder::default()
    .uuid( Uuid::parse_str("da1c7a76-33a8-448e-9ada-3a1b17c12279").unwrap())
    .stdout("Custom operation result".into())
    .retval({
        let mut data = BTreeMap::new();
        data.insert("custom_field".into(), Value::String("custom_value".into()));
        data
    })
    .build();

assert_eq!(format!("{}", result.uuid), "da1c7a76-33a8-448e-9ada-3a1b17c12279".to_string());
```

### JSON Output Format

The JSON output format for successful results looks like this:

```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "retcode": 0,
  "stdout": "Operation completed successfully",
  "stderr": null,
  "retval": {
    "status": "completed",
    "count": 42
  }
}
```

For error results:

```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "retcode": 1,
  "stdout": null,
  "stderr": "Failed to process data",
  "retval": {
    "error_type": "processing_error"
  }
}
```