Struct DirStorage 

pub struct DirStorage { /* private fields */ }

Directory-based entity storage with ACID guarantees and automatic migrations.

Manages one file per entity, providing:

• Atomicity: Updates are all-or-nothing via tmp file + atomic rename
• Consistency: Format validation on load/save
• Isolation: Each entity has its own file
• Durability: Explicit fsync before rename

Implementations

impl DirStorage

pub fn new( paths: AppPaths, domain_name: &str, migrator: Migrator, strategy: DirStorageStrategy, ) -> Result<Self, MigrationError>

Create a new DirStorage instance.

Arguments

• paths - Application paths manager
• domain_name - Domain-specific subdirectory name (e.g., “sessions”, “tasks”)
• migrator - Migrator instance with registered migration paths
• strategy - Storage strategy configuration

Behavior

• Resolves the base path using paths.data_dir()?.join(domain_name)
• Creates the directory if it doesn’t exist
• Does not load existing files (lazy loading)

Errors

Returns MigrationError::IoError if directory creation fails.

Example

let paths = AppPaths::new("myapp");
let storage = DirStorage::new(
    paths,
    "sessions",
    migrator,
    DirStorageStrategy::default(),
)?;

pub fn save<T>( &self, entity_name: &str, id: &str, entity: T, ) -> Result<(), MigrationError>

where T: Serialize,

Save an entity to a file.

Arguments

• entity_name - The entity name registered in the migrator
• id - The unique identifier for this entity (used as filename)
• entity - The entity to save

Process

1. Converts the entity to its latest versioned DTO
2. Serializes to the configured format (JSON/TOML)
3. Writes atomically using temporary file + rename

Errors

Returns error if:

• Entity name not registered in migrator
• ID contains invalid characters (for Direct encoding)
• Serialization fails
• File write fails

Example

let session = SessionEntity {
    id: "session-123".to_string(),
    user_id: "user-456".to_string(),
};
storage.save("session", "session-123", session)?;

pub fn load<D>(&self, entity_name: &str, id: &str) -> Result<D, MigrationError>

where D: DeserializeOwned,

Load an entity from a file.

Arguments

• entity_name - The entity name registered in the migrator
• id - The unique identifier for the entity

Process

1. Gets the file path using id_to_path
2. Reads the file content to a string
3. Deserializes the content to a serde_json::Value
4. Migrates the Value to the target domain type

Errors

Returns error if:

• Entity name not registered in migrator
• File not found
• Deserialization fails
• Migration fails

Example

let session: SessionEntity = storage.load("session", "session-123")?;

pub fn list_ids(&self) -> Result<Vec<String>, MigrationError>

List all entity IDs in the storage directory.

Returns

A sorted vector of entity IDs (decoded from filenames).

Errors

Returns error if:

• Directory read fails
• Filename decoding fails

Example

let ids = storage.list_ids()?;
for id in ids {
    println!("Found entity: {}", id);
}

pub fn load_all<D>( &self, entity_name: &str, ) -> Result<Vec<(String, D)>, MigrationError>

where D: DeserializeOwned,

Load all entities from the storage directory.

Arguments

• entity_name - The entity name registered in the migrator

Returns

A vector of (id, entity) tuples.

Errors

Returns error if any entity fails to load. This operation is atomic: if any load fails, the whole operation fails.

Example

let sessions: Vec<(String, SessionEntity)> = storage.load_all("session")?;
for (id, session) in sessions {
    println!("Loaded session {} for user {}", id, session.user_id);
}

pub fn exists(&self, id: &str) -> Result<bool, MigrationError>

Check if an entity exists.

Arguments

• id - The entity ID

Returns

true if the file exists and is a file, false otherwise.

Example

if storage.exists("session-123")? {
    println!("Session exists");
}

pub fn delete(&self, id: &str) -> Result<(), MigrationError>

Delete an entity file.

Arguments

• id - The entity ID

Behavior

This operation is idempotent: deleting a non-existent file is not an error.

Errors

Returns error if file deletion fails (but not if file doesn’t exist).

Example

storage.delete("session-123")?;

pub fn base_path(&self) -> &Path

Returns a reference to the base directory path.

Returns

A reference to the resolved base directory path where entities are stored.