elemental-shared
Version-aware async persistence with explicit migrations.
elemental-shared keeps storage, migration, and runtime state separate. Stored
data can use an old shape, or an enum of every supported shape, while the
application works with one current type. The loader handles version validation,
migration, runtime normalization, and save decisions.
Why elemental-shared
| Concern | Type |
|---|---|
| Read a schema version | Versioned |
| Normalize a runtime value to a version | VersionControlled |
| Convert between stored and current representations | Migrator<Stored, Current> |
| Load and save one representation | Persistor<V> |
| Coordinate versions, migration, and persistence | Loader<M, S, V, P> |
The stored and current representations may be different types. Stored V1, V2, and V3 payloads can therefore migrate into the same current runtime type, without the persistor needing to understand migrations.
Features
- Cross-type migrations in both directions.
- Same-type migrations through
NoMigrator. - Async access through
Loader. - JSON and TOML file persistence.
- In-memory and no-op persistors.
- Typed errors through
thiserror. - Cross-platform storage locations through
Scope.
Installation
[]
= "1"
= "0.2"
= { = "1", = ["derive"] }
= { = "1", = ["macros", "rt-multi-thread"] }
json is enabled by default. Enable TOML persistence explicitly:
[]
= { = "0.2", = ["toml"] }
Quick Start
Use NoMigrator when the stored data already has the current shape.
use ;
use ;
async
The final argument to Profile::load is the current schema version. The loader
stamps that version on the runtime value and validates the version encoded by
the migrator before saving it.
Missing storage creates GameConfig::default() at the target version. The
default is written only when set() is called.
Cross-Type Migration
Use an enum when old configs and the current config have different shapes.
Profile<Versions> is the stored representation; the runtime value stays
clean.
use ;
use ;
;
async
The migrator converts the stored shape and may preserve the version it read.
The loader stamps the runtime value with the target version. encode must
return a stored value with the target version; otherwise the loader returns
Error::EncodedVersionMismatch.
#[serde(deny_unknown_fields)] keeps the untagged enum unambiguous when a newer
version adds fields. If two versions have exactly the same shape, use an
explicit tagged envelope instead of relying on untagged deserialization.
Version Behavior
| Stored state | Loader behavior |
|---|---|
| Missing | Create the default current value at the target version; do not save |
| Version newer than target | Return an error |
| Version equal to target | Migrate to the current type; do not rewrite |
| Version older than target | Migrate, encode, validate, and save |
Loader::set() encodes the current value, validates the encoded version, and
saves it. The write lock is held through encoding and saving.
[!WARNING] A slow serialization or storage backend blocks readers while
set()holds the write lock. Keep persistence calls reasonably short or move them behind a dedicated persistor.
Persistors
| API | Feature | Behavior |
|---|---|---|
json_persistor |
json (default) |
Reads and writes JSON files |
toml_persistor |
toml |
Reads and writes TOML files |
NoPersistor |
Always | Always loads None and discards saves |
MemoryPersistor |
Always | Stores a shared in-memory value |
JSON and TOML persistors use CustomPersistor and PersistorIO internally.
Implement Persistor<V> directly for databases, network storage, encryption,
or other backends.
MemoryPersistor is useful for tests, previews, and temporary workflows:
use ;
let persistor = new;
let observer = persistor.clone;
let saved = observer.load.await?;
Cloned handles share the same value. This is not durable storage.
Storage Scopes
File persistors resolve paths as <base>/.elemental/<id>.<suffix>.
| Scope | Base directory |
|---|---|
Scope::Document |
User documents |
Scope::Home |
User home directory |
Scope::Config |
Platform config directory |
Scope::ConfigLocal |
Platform local config directory |
Scope::Dot |
Current directory |
Scope::Directory(path) |
Supplied directory |
For example, Scope::Config with the id profile and the default JSON suffix
produces a path such as ~/.config/.elemental/profile.json on Linux.
API Summary
Core traits
Loader
load.await?;
loader.get.await;
loader.set.await?;
loader.cloned.await;
Loader holds Arc<RwLock<V>> internally. get and cloned take a read
lock; set takes a write lock. A loader can be cloned when its migrator and
persistor are cloneable.
Versioned wrappers
Profile<C> stores a versioned application config:
Store<V> is the generic equivalent:
Both provide a load helper that accepts a migrator, persistor, and target
version.
Error Handling
All fallible APIs return elemental_shared::error::Result<T>. The error enum
covers:
- Filesystem I/O.
- JSON or TOML serialization and deserialization.
- Missing platform base paths.
- Stored versions newer than the supported target.
- Mismatches between encoded and target versions.
Testing
Run the crate tests:
The tests cover no-op loading and a V1/V2/V3 cross-type migration, including
verification that upgraded values are persisted through MemoryPersistor.
Related Crates
elemental-coreelemental-driverelemental-kit
For the full design rationale, see DESIGN.md.