cloudiful-config

Small serde-based configuration helpers for local TOML, JSON, and JSONC files.

cloudiful-config focuses on the small but common path:

Read typed config from .toml, .json, or .jsonc.
Create a missing config file from T::default().
Apply environment variable overrides on top of defaults or file-backed config.
Save config back atomically as TOML or JSON.

It is intentionally narrower than crates like config-rs or Figment. This crate is for applications that already know which file to read and want a small read/write helper around Serde types.

Install

[dependencies]
cloudiful-config = "0.4.1"

Read modes

read(ConfigSource) stays the main entrypoint:

ConfigSource::File(path): read from disk, creating the file from T::default() if it does not exist yet.
ConfigSource::Env { prefix }: start from T::default() and apply matching environment variables.
ConfigSource::FileWithEnv { path, prefix }: read from disk first, then apply environment variables on top.

Use read_existing(path) when the file must already exist.

Use read_or_create_default(path) when you want the "create on first run" behavior explicitly without environment overrides.

Writing config

save_inferred(path, config) is the recommended write API. It infers the output format from the path extension:

.toml writes TOML
.json writes JSON
.jsonc also writes standard JSON

save(path, config, file_type) is still available for explicit format control, but the format must match the path extension. For example, JSON cannot be written to a .toml path.

All writes are atomic: the crate writes to a temporary file in the same directory and then renames it into place.

Environment variable rules

Keys must start with the configured prefix.
The suffix after the prefix is lowercased before matching fields.
__ creates nested objects.
Values are parsed as JSON literals first.
If JSON parsing fails, the raw value is treated as a string.
Arrays must be provided as full JSON values such as ["a","b"].
Array index syntax is not supported.

JSONC behavior

.jsonc inputs support // and /* ... */ comments while reading.