json_state 0.1.0

/// State management module for persisting application state in memory and on disk.
/// 
/// This module provides functionality to create, store, retrieve, and delete
/// application states using both in-memory storage and filesystem persistence.
/// Each state has a unique identifier and can store arbitrary JSON data.
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::HashMap;
use std::fs::{self, File};
use std::io::{self, Write};
use std::path::Path;
use uuid::Uuid;

/// Represents a single state with a unique identifier and JSON payload.
///
/// Each `State` instance contains:
/// - A UUID that uniquely identifies the state
/// - A JSON value that represents the state's data
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct State {
    /// Unique identifier for the state
    id: Uuid,
    /// JSON data payload containing the state information
    payload: Value,
}

impl State {
    /// Creates a new state with the provided JSON payload and a randomly generated UUID.
    ///
    /// # Arguments
    ///
    /// * `payload` - A JSON value containing the state data
    ///
    /// # Returns
    ///
    /// A new `State` instance with a unique ID and the specified payload
    ///
    /// # Examples
    ///
    /// ```
    /// use serde_json::json;
    /// use state::State;
    ///
    /// let state = State::new(json!({
    ///     "name": "John",
    ///     "age": 30,
    ///     "settings": {
    ///         "theme": "dark",
    ///         "notifications": true
    ///     }
    /// }));
    /// ```
    pub fn new(payload: Value) -> Self {
        State {
            id: Uuid::new_v4(),
            payload,
        }
    }

    /// Returns a reference to the state's unique identifier.
    ///
    /// # Returns
    ///
    /// A reference to the UUID that identifies this state
    ///
    /// # Examples
    ///
    /// ```
    /// use serde_json::json;
    /// use state::State;
    ///
    /// let state = State::new(json!({"name": "John"}));
    /// let id = state.get_id();
    /// println!("State ID: {}", id);
    /// ```
    pub fn get_id(&self) -> &Uuid {
        &self.id
    }
    
    /// Returns a reference to the state's payload.
    ///
    /// # Returns
    ///
    /// A reference to the JSON value containing the state data
    ///
    /// # Examples
    ///
    /// ```
    /// use serde_json::json;
    /// use state::State;
    ///
    /// let state = State::new(json!({"name": "John"}));
    /// let payload = state.get_payload();
    /// println!("Name: {}", payload["name"]);
    /// ```
    pub fn get_payload(&self) -> &Value {
        &self.payload
    }
}

/// Manages multiple state objects with persistence capabilities.
///
/// `StateManager` provides functionality to:
/// - Save states to both memory and filesystem
/// - Load states from memory or filesystem
/// - Delete states from both memory and filesystem
/// - Load all states from a directory
#[derive(Default)]
pub struct StateManager {
    /// Directory path where state files are stored
    pub dir: String,
    /// In-memory storage of states indexed by their UUID
    pub states: HashMap<Uuid, State>,
}

impl StateManager {
    /// Creates a new `StateManager` with the specified directory for persistence.
    ///
    /// # Arguments
    ///
    /// * `dir` - The directory path where state files will be stored
    ///
    /// # Returns
    ///
    /// A new `StateManager` instance initialized with the specified directory
    ///
    /// # Examples
    ///
    /// ```
    /// use state::StateManager;
    ///
    /// let manager = StateManager::new("states".to_string());
    /// ```
    pub fn new(dir: String) -> Self {
        StateManager {
            dir,
            states: HashMap::new(),
        }
    }

    /// Saves a state to both in-memory storage and the filesystem.
    ///
    /// # Arguments
    ///
    /// * `state` - The state to save
    ///
    /// # Returns
    ///
    /// An `io::Result` indicating success or containing an error if the filesystem operation failed
    ///
    /// # Examples
    ///
    /// ```
    /// use serde_json::json;
    /// use state::{State, StateManager};
    ///
    /// let mut manager = StateManager::new("states".to_string());
    /// let state = State::new(json!({"name": "John"}));
    /// manager.save(state).expect("Failed to save state");
    /// ```
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The directory cannot be created
    /// - The state file cannot be written
    pub fn save(&mut self, state: State) -> io::Result<()> {
        // Save in memory (HashMap)
        self.states.insert(state.get_id().clone(), state.clone());

        // Save to file system
        self.save_to_file_system(&state)?;  // Save the specific state to the file system

        Ok(())
    }

    /// Loads a state by its ID, first checking in-memory storage then the filesystem.
    ///
    /// # Arguments
    ///
    /// * `id` - The UUID of the state to load
    ///
    /// # Returns
    ///
    /// An `io::Result` containing:
    /// - `Some(State)` if the state was found
    /// - `None` if the state was not found
    /// - An error if the filesystem operation failed
    ///
    /// # Examples
    ///
    /// ```
    /// use state::StateManager;
    ///
    /// let manager = StateManager::new("states".to_string());
    /// match manager.load(&state_id) {
    ///     Ok(Some(state)) => println!("State found: {:?}", state),
    ///     Ok(None) => println!("State not found"),
    ///     Err(e) => println!("Error loading state: {}", e),
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The state file exists but cannot be read
    /// - The state file contains invalid JSON
    pub fn load(&self, id: &Uuid) -> io::Result<Option<State>> {
        // Check memory first
        if let Some(state) = self.states.get(id) {
            return Ok(Some(state.clone()));
        }

        // If not in memory, load from file system
        self.load_from_file_system(id)
    }

    /// Deletes a state by its ID from both in-memory storage and the filesystem.
    ///
    /// # Arguments
    ///
    /// * `id` - The UUID of the state to delete
    ///
    /// # Returns
    ///
    /// An `io::Result` indicating success or containing an error if the filesystem operation failed
    ///
    /// # Examples
    ///
    /// ```
    /// use state::StateManager;
    ///
    /// let mut manager = StateManager::new("states".to_string());
    /// manager.delete(&state_id).expect("Failed to delete state");
    /// ```
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The state file exists but cannot be deleted
    pub fn delete(&mut self, id: &Uuid) -> io::Result<()> {
        // Remove from memory (HashMap)
        self.states.remove(id);

        // Remove from file system
        self.delete_from_file_system(id)?;

        Ok(())
    }

    /// Creates a `StateManager` by loading all state files from the specified directory.
    ///
    /// # Arguments
    ///
    /// * `dir` - The directory path to load state files from
    ///
    /// # Returns
    ///
    /// An `io::Result` containing a new `StateManager` with all states loaded from the directory
    ///
    /// # Examples
    ///
    /// ```
    /// use state::StateManager;
    ///
    /// let manager = StateManager::load_from_dir("states").expect("Failed to load states");
    /// println!("Loaded {} states", manager.states.len());
    /// ```
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The directory cannot be read
    /// - A state file contains invalid JSON
    /// - A state file cannot be read
    pub fn load_from_dir(dir: &str) -> std::io::Result<Self> {
        let mut states = HashMap::new();

        // Create directory if it doesn't exist
        if !Path::new(dir).exists() {
            fs::create_dir_all(dir)?;  // create dir if missing
            return Ok(Self {
                dir: dir.to_string(),
                states,
            });
        }

        // Only process files with .json extension AND matching UUID pattern
        for entry in fs::read_dir(dir)? {
            let entry = entry?; 
            let path = entry.path();
            
            // Check if it's a .json file
            if path.extension().map(|e| e == "json").unwrap_or(false) {
                // Get the filename without extension
                if let Some(filename) = path.file_stem() {
                    // Try to parse the filename as UUID
                    if let Ok(id) = Uuid::parse_str(&filename.to_string_lossy()) {
                        let json = fs::read_to_string(&path)?;
                        if let Ok(state) = serde_json::from_str::<State>(&json) {
                            // Validate that the ID in the filename matches the ID in the content
                            if *state.get_id() == id {
                                states.insert(id, state);
                            }
                        }
                    }
                }
            }
        }

        Ok(Self {
            dir: dir.to_string(),
            states,
        })
    }

    /// Clears all state files from the specified directory.
    ///
    /// # Arguments
    ///
    /// * `dir` - The directory path to clear
    ///
    /// # Returns
    ///
    /// An `io::Result` indicating success or containing an error if the operation failed
    ///
    /// # Examples
    ///
    /// ```
    /// use state::StateManager;
    ///
    /// StateManager::clear_dir("states").expect("Failed to clear states directory");
    /// ```
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The directory cannot be read or modified
    pub fn clear_dir(dir: &str) -> io::Result<()> {
        if Path::new(dir).exists() {
            fs::remove_dir_all(dir)?;
        }
        fs::create_dir_all(dir)?;
        Ok(())
    }

    /// Saves a single state to the filesystem.
    ///
    /// # Arguments
    ///
    /// * `state` - The state to save to the filesystem
    ///
    /// # Returns
    ///
    /// An `io::Result` indicating success or containing an error if the operation failed
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The directory does not exist and cannot be created
    /// - The state file cannot be created or written
    /// - The state cannot be serialized to JSON
    fn save_to_file_system(&self, state: &State) -> io::Result<()> {
        // Ensure the directory exists
        if !Path::new(&self.dir).exists() {
            fs::create_dir_all(&self.dir)?;
        }
        
        let file_path = format!("{}/{}.json", self.dir, state.get_id());  // Save the state by ID
        let json = serde_json::to_string_pretty(state)?;  // Serialize the state
        let mut file = File::create(file_path)?;  // Create the file
        file.write_all(json.as_bytes())?;  // Write the state to the file

        Ok(())
    }

    /// Loads a state from the filesystem by its ID.
    ///
    /// # Arguments
    ///
    /// * `id` - The UUID of the state to load
    ///
    /// # Returns
    ///
    /// An `io::Result` containing:
    /// - `Some(State)` if the state file was found and loaded successfully
    /// - `None` if the state file was not found
    /// - An error if the state file exists but cannot be read or contains invalid JSON
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The state file exists but cannot be read
    /// - The state file contains invalid JSON
    fn load_from_file_system(&self, id: &Uuid) -> std::io::Result<Option<State>> {
        let file_path = format!("{}/{}.json", self.dir, id);

        // Check if the file exists
        if Path::new(&file_path).exists() {
            let json = fs::read_to_string(&file_path)?;  // Read the file content
            let state: State = serde_json::from_str(&json)?;  // Deserialize the state
            Ok(Some(state))  // Return the state
        } else {
            Ok(None)  // If the file does not exist, return None
        }
    }

    /// Deletes a state file from the filesystem by its ID.
    ///
    /// # Arguments
    ///
    /// * `id` - The UUID of the state file to delete
    ///
    /// # Returns
    ///
    /// An `io::Result` indicating success or containing an error if the operation failed
    ///
    /// # Errors
    ///
    /// This function will return an error if:
    /// - The state file exists but cannot be deleted
    fn delete_from_file_system(&self, id: &Uuid) -> io::Result<()> {
        let file_path = format!("{}/{}.json", self.dir, id);
        if Path::new(&file_path).exists() {
            fs::remove_file(file_path)?;  // Remove the file
        }
        Ok(())
    }
}