app-json-settings 2.0.0

App settings as JSON format stored in file and available via read-by-key and write-by-key. Aims a tiny settings manager with reasonably few dependencies.
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

# App JSON Settings

![Rust](https://img.shields.io/badge/Rust-%23CE412B?style=flat&logo=rust&logoColor=white)
[![crates.io](https://img.shields.io/crates/v/app-json-settings?label=latest)](https://crates.io/crates/app-json-settings)
[![Documentation](https://docs.rs/app-json-settings/badge.svg?version=latest)](https://docs.rs/app-json-settings/latest)
[![License](https://img.shields.io/github/license/nabbisen/app-json-settings-rs)](https://github.com/nabbisen/app-json-settings-rs/blob/main/LICENSE)
[![Dependency Status](https://deps.rs/crate/app-json-settings/latest/status.svg)](https://deps.rs/crate/app-json-settings)

**Typed application settings storage for Rust.**

`app-json-settings` persists a Rust struct as your application configuration.
You do not manipulate JSON manually and you do not manage config file paths yourself.

The library focuses on safe, minimal, cross-platform configuration handling.

## Quick start

```ini
# Cargo.toml
[dependencies]
serde = { version = "1", features = ["derive"] }
app-json-settings = "2"
```

```rust
use app_json_settings::ConfigManager;

#[derive(serde::Serialize, serde::Deserialize, Default)]
struct Settings {
    volume: u32,
}

fn save() -> app_json_settings::Result<()> {
    ConfigManager::new().save(&Settings { volume: 100 })?;
    Ok(())
}

fn load() -> app_json_settings::Result<()> {
    let settings = ConfigManager::<Settings>::new().load_or_default()?;
    println!("{}", settings.volume);
    Ok(())
}
```

---

## Why this library

Writing config handling code repeatedly leads to:

* fragile first-run initialization
* manual path handling per OS
* read → modify → write mistakes
* string-key based settings

This crate removes those concerns and lets the struct be the configuration.

## Design goals

* Minimal API surface
* Predictable behavior
* No runtime dependencies beyond Serde
* Works for CLI, GUI, mobile, and server applications

This crate is not a general database or dynamic settings system.
It is a typed persistent configuration layer.

---

## Features

### Safe configuration I/O

* Load and save settings with minimal code
* `load_or_default()` prevents first-run crashes
* `update()` provides safe read-modify-write

### Typed serialization

* Uses your own struct as the configuration model
* No string keys
* Compile-time refactor safety
* Serde `Serialize` / `Deserialize` supported

### JSON focused

* JSON only (intentionally)
* Selectable output:

  * compact
  * pretty
* Suitable for mobile I/O constraints while still human-readable

### Cross-platform support

The library internally resolves platform-specific config directories:

* Windows → `%APPDATA%`
* macOS → `~/Library/Application Support`
* Linux / Unix → `$XDG_CONFIG_HOME` or `~/.config`

No platform conditional code is required in your application.

---

## Customization

```rust
let config = ConfigManager::<Settings>::new()
    .with_filename("user.json")
    .disable_pretty_json();
```

Options:

* custom directory
* custom file name
* compact or pretty JSON output

## Partial update

You usually do not need to manually load and save.

```rust
config.update(|s| {
    s.volume = 200;
})?;
```

`update()` guarantees a safe read-modify-write cycle.

---

## Choosing the right API

| Function            | When to use                             |
| ------------------- | --------------------------------------- |
| `load()`            | Config file must already exist          |
| `load_or_default()` | Normal application startup              |
| `save()`            | Replace entire configuration            |
| `update()`          | Modify part of the configuration safely |

---

## Open-source, with care

This project is lovingly built and maintained by volunteers. We hope it helps streamline your work. Please understand that the project has its own direction — while we welcome feedback, it might not fit every edge case 🌱

## Acknowledgements

Depends on the crates of [serde](https://serde.rs/), [serde_json](https://github.com/serde-rs/json) .