netabase_store 0.0.8

//! Unified backend store trait for consistent database initialization.
//!
//! This trait provides a standard interface for creating and opening databases
//! across all backends, replacing the previous `BackendConstructor` pattern.

use crate::error::NetabaseError;
use crate::traits::definition::NetabaseDefinitionTrait;
use std::path::Path;

/// Unified interface for database backend initialization.
///
/// All database backends should implement this trait to provide consistent
/// constructor APIs: `new()`, `open()`, and `temp()`.
///
/// # Type Parameters
///
/// * `D` - The definition type (generated by `#[netabase_definition_module]`)
/// * `Config` - Backend-specific configuration type
///
/// # Examples
///
/// ```no_run
/// # use netabase_store::traits::backend_store::BackendStore;
/// # use netabase_store::config::FileConfig;
/// # use netabase_store::databases::sled_store::SledStore;
/// # use netabase_store::netabase_definition_module;
/// # #[netabase_definition_module(MyDef, MyKeys)]
/// # mod models {
/// #     use netabase_store::{NetabaseModel, netabase};
/// #     #[derive(NetabaseModel, Clone, Debug, PartialEq,
/// #              bincode::Encode, bincode::Decode,
/// #              serde::Serialize, serde::Deserialize)]
/// #     #[netabase(MyDef)]
/// #     pub struct User {
/// #         #[primary_key]
/// #         pub id: u64,
/// #         pub name: String,
/// #     }
/// # }
/// # use models::*;
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// use netabase_store::traits::backend_store::BackendStore;
/// // Unified API across all backends via BackendStore trait
/// let temp_dir = tempfile::tempdir()?;
/// let config = FileConfig::new(temp_dir.path().join("my_store.db"));
/// let store = <SledStore<MyDef> as BackendStore<MyDef>>::new(config.clone())?;
///
/// // Or open existing
/// let store = <SledStore<MyDef> as BackendStore<MyDef>>::open(config)?;
///
/// // Temporary store
/// let temp_store = <SledStore<MyDef> as BackendStore<MyDef>>::temp()?;
/// # Ok(())
/// # }
/// ```
pub trait BackendStore<D: NetabaseDefinitionTrait>: Sized {
    /// Backend-specific configuration type
    type Config;

    /// Create a new database, removing any existing data.
    ///
    /// This method will:
    /// - Delete any existing database at the configured path
    /// - Create a fresh database
    /// - Initialize all required tables/trees
    ///
    /// # Errors
    ///
    /// Returns `NetabaseError` if:
    /// - Cannot delete existing database
    /// - Cannot create new database
    /// - I/O errors occur
    fn new(config: Self::Config) -> Result<Self, NetabaseError>;

    /// Open an existing database or create if it doesn't exist.
    ///
    /// This is the most commonly used method. It will:
    /// - Open the database if it exists
    /// - Create a new database if it doesn't exist
    /// - Perform any necessary migrations
    ///
    /// # Errors
    ///
    /// Returns `NetabaseError` if:
    /// - Cannot open or create database
    /// - Database is corrupted (some backends support repair)
    /// - I/O errors occur
    fn open(config: Self::Config) -> Result<Self, NetabaseError>;

    /// Create a temporary database that is automatically cleaned up.
    ///
    /// The temporary database will be:
    /// - Created in the system's temp directory
    /// - Automatically deleted when dropped (best effort)
    /// - Suitable for testing and ephemeral use
    ///
    /// # Errors
    ///
    /// Returns `NetabaseError` if:
    /// - Cannot create temporary location
    /// - Cannot initialize database
    fn temp() -> Result<Self, NetabaseError>;
}

/// Helper trait for backends that support path-based configuration.
///
/// This provides convenient shortcuts for the most common case.
pub trait PathBasedBackend<D: NetabaseDefinitionTrait>: BackendStore<D> {
    /// Create a new database at the specified path.
    fn at_path<P: AsRef<Path>>(path: P) -> Result<Self, NetabaseError>;
}