serdeio 0.6.0

Tiny IO utility library for Rust to serialize/deserialize Serde compatible structs
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

<img src="logo_wide.png" alt="SerdeIO Logo" width="600">

[![Crates.io](https://img.shields.io/crates/v/serdeio)](https://crates.io/crates/serdeio)
[![Documentation](https://docs.rs/serdeio/badge.svg)](https://docs.rs/serdeio)
[![License](https://img.shields.io/crates/l/serdeio)](https://github.com/lucidfrontier45/serdeio/blob/main/LICENSE)

A lightweight Rust library for seamless serialization/deserialization of Serde-compatible structs across JSON, JSON Lines, CSV, YAML, MessagePack, and TOML formats.

# Install


```sh
cargo add serdeio
```

SerdeIO supports JSON and JSON Lines formats by default. Additional formats can be enabled with feature flags:

```sh
# For CSV support

cargo add serdeio --features csv

# For YAML support

cargo add serdeio --features yaml

# For MessagePack support

cargo add serdeio --features messagepack

# For TOML support

cargo add serdeio --features toml

# For both CSV and YAML

cargo add serdeio --features csv,yaml
```

# Supported Formats


| Format      | Extensions                   | Single Record | Multiple Records | Feature Flag  |
| ----------- | ---------------------------- | ------------- | ---------------- | ------------- |
| JSON        | `.json`                      | ✓             | ✓                | (default)     |
| JSON Lines  | `.jsonl`, `.jsl`             | ✗             | ✓                | (default)     |
| CSV         | `.csv`                       | ✗             | ✓                | `csv`         |
| YAML        | `.yaml`, `.yml`              | ✓             | ✓                | `yaml`        |
| MessagePack | `.msgpack`, `.mpack`, `.mpk` | ✓             | ✓                | `messagepack` |
| TOML        | `.toml`                      | ✓             | ✗                | `toml`        |

# Features


- **Lightweight**: Minimal dependencies with feature-gated optional formats
- **Auto-detection**: File format automatically determined from extensions (case-insensitive)
- **Iterator support**: Efficient streaming writes without collecting into vectors
- **Serde-compatible**: Works with any struct that implements Serde traits
- **Flexible**: Supports both single records and collections across formats

# Performance


- Uses `BufReader`/`BufWriter` internally for optimal I/O performance
- Iterator-based writing enables memory-efficient streaming without allocations
- Format detection and parsing optimized for common use cases

# API Overview


SerdeIO provides 8 main functions for reading and writing data:

**Reader-based functions:**
- `read_record_from_reader<T>(reader, data_format)` - Read a single record from any `Read` implementation
- `read_records_from_reader<T>(reader, data_format)` - Read multiple records as `Vec<T>` from any `Read`
- `write_record_to_writer<T>(writer, record, data_format)` - Write a single record to any `Write`
- `write_records_to_writer<T>(writer, records, data_format)` - Write multiple records using an iterator

**File-based functions:**
- `read_record_from_file<T>(path, data_format?)` - Read a single record, auto-detecting format from file extension
- `read_records_from_file<T>(path, data_format?)` - Read multiple records, auto-detecting format from file extension
- `write_record_to_file<T>(path, record, data_format?)` - Write a single record, auto-detecting format from file extension
- `write_records_to_file<T>(path, records, data_format?)` - Write multiple records, accepts any iterator or collection

Note: Some formats like CSV and JSON Lines only support multiple records (`Vec<T>`). File-based functions accept an optional `DataFormat` override; if not provided or set to `Auto`, the format is inferred from the file extension.

# Examples


## Reading and Writing Multiple Records (Common Use Case)


This example reads a JSON file containing multiple user records and converts it to JSON Lines format:

```rust
use anyhow::{Context, Result as AnyResult};
use serde::{Deserialize, Serialize};
use serdeio::{read_records_from_file, write_records_to_writer, DataFormat};

#[derive(Debug, Deserialize, Serialize)]

struct User {
    id: u32,
    name: String,
    age: u8,
    items: Vec<String>,
}

pub fn main() -> AnyResult<()> {
    let input_file_path = "examples/users.json";

    // Read JSON file to memory (format auto-detected from .json extension)
    let users: Vec<User> = read_records_from_file(input_file_path, DataFormat::Auto)
        .context("Failed to read records from file")?;

    // Write to stdout in JSON Lines format
    let writer = std::io::stdout();
    write_records_to_writer(writer, users.iter(), DataFormat::JsonLines)?;

    Ok(())
}
```

# API Reference


For complete API documentation, visit [docs.rs/serdeio](https://docs.rs/serdeio).

Key types:
- `DataFormat` - Enum for specifying data formats
- `Error` - Comprehensive error type with format-specific variants

# Contributing


Contributions are welcome! Please:
- Run tests with `cargo test`
- Format code with `cargo fmt`
- Check with `cargo clippy`
- Follow the existing code style and patterns

# License


SerdeIO is licensed under the MIT License.