eidetica/store/

mod.rs

use crate::HeightStrategy;
use crate::crdt::{CRDT, Doc};
use crate::{Result, Transaction};
use async_trait::async_trait;

mod errors;
pub use errors::StoreError;

mod docstore;
pub use docstore::DocStore;

mod value_editor;
pub use value_editor::ValueEditor;

mod table;
pub use table::Table;

mod settings_store;
pub use settings_store::SettingsStore;

mod registry;
pub use registry::Registered;
pub use registry::Registry;
pub use registry::RegistryEntry;
pub use registry::SubtreeSettings;

mod password_store;
pub use password_store::{
    DEFAULT_ARGON2_M_COST, DEFAULT_ARGON2_P_COST, DEFAULT_ARGON2_T_COST, EncryptedFragment,
    EncryptionInfo, PasswordStore, PasswordStoreConfig,
};

#[cfg(feature = "y-crdt")]
mod ydoc;
#[cfg(feature = "y-crdt")]
pub use ydoc::{YDoc, YrsBinary};

/// A trait representing a named, CRDT-based data structure within a `Database`.
///
/// `Store` implementations define how data within a specific named partition of a `Database`
/// is structured, accessed, and modified. They work in conjunction with a `Transaction`
/// to stage changes before committing them as a single `Entry`.
///
/// Users typically interact with `Store` implementations obtained either via:
/// 1. `Database::get_store_viewer`: For read-only access to the current merged state.
/// 2. `Transaction::get_store`: For staging modifications within a transaction.
///
/// Store types must also implement [`Registered`] to provide their type identifier.
#[async_trait]
pub trait Store: Sized + Registered + Send + Sync {
    /// The CRDT data type used for local (staged) data in this store.
    ///
    /// This is the type stored within each individual Entry.
    type Data: CRDT;

    /// Creates a new `Store` handle associated with a specific transaction.
    ///
    /// This constructor is typically called internally by `Transaction::get_store` or
    /// `Database::get_store_viewer`. The resulting `Store` instance provides methods
    /// to interact with the data of the specified `subtree_name`, potentially staging
    /// changes within the provided `txn`.
    ///
    /// # Arguments
    /// * `txn` - The `Transaction` this `Store` instance will read from and potentially write to.
    /// * `subtree_name` - The name identifying this specific data partition within the `Database`.
    async fn new(txn: &Transaction, subtree_name: String) -> Result<Self>;

    /// Returns the name of this subtree.
    fn name(&self) -> &str;

    /// Returns a reference to the transaction this Store is associated with.
    ///
    /// This is used by the default implementations of `init()`, `get_config()`,
    /// and `set_config()` to access the index store.
    fn transaction(&self) -> &Transaction;

    /// Returns the default configuration for this Store type as a [`Doc`].
    ///
    /// This configuration is stored in the `_index` subtree when a new subtree is
    /// first created. The Store implementation owns the format and interpretation
    /// of this configuration data.
    ///
    /// The default implementation returns an empty `Doc`. Store implementations
    /// that require specific configuration should override this method.
    ///
    /// # Examples
    ///
    /// ```
    /// # use eidetica::{Store, store::DocStore};
    /// let config = DocStore::default_config();
    /// assert!(config.is_empty());
    /// ```
    fn default_config() -> Doc {
        Doc::new()
    }

    /// Initializes a new subtree and registers it in the `_index`.
    ///
    /// This method is called by `Transaction::get_store()` when accessing a subtree
    /// that doesn't yet exist in the `_index`. It creates the Store and registers
    /// its type and default configuration in the index.
    ///
    /// The default implementation:
    /// 1. Creates the Store using `Self::new()`
    /// 2. Registers it in `_index` with `Self::type_id()` and `Self::default_config()`
    ///
    /// Store implementations can override this to customize initialization behavior.
    ///
    /// # Arguments
    /// * `txn` - The `Transaction` this `Store` instance will operate within.
    /// * `subtree_name` - The name identifying this specific data partition.
    ///
    /// # Returns
    /// A `Result<Self>` containing the initialized Store.
    async fn init(txn: &Transaction, subtree_name: String) -> Result<Self> {
        let store = Self::new(txn, subtree_name).await?;
        store.set_config(Self::default_config()).await?;
        Ok(store)
    }

    /// Gets the current configuration for this Store from the `_index` subtree.
    ///
    /// # Returns
    /// A `Result<Doc>` containing the configuration document.
    ///
    /// # Errors
    /// Returns an error if the subtree is not registered in `_index`.
    async fn get_config(&self) -> Result<Doc> {
        let index = self.transaction().get_index().await?;
        let info = index.get_entry(self.name()).await?;
        Ok(info.config)
    }

    /// Sets the configuration for this Store in the `_index` subtree.
    ///
    /// This method updates the `_index` with the Store's type ID and the provided
    /// configuration. It's called automatically by `init()` and can be used to
    /// update configuration during a transaction.
    ///
    /// # Arguments
    /// * `config` - The configuration document to store.
    ///
    /// # Returns
    /// A `Result<()>` indicating success or failure.
    async fn set_config(&self, config: Doc) -> Result<()> {
        let index = self.transaction().get_index().await?;
        index
            .set_entry(self.name(), Self::type_id(), config)
            .await?;
        Ok(())
    }

    /// Gets the height strategy for this Store from the `_index` subtree.
    ///
    /// Returns `None` if no strategy is set (meaning the subtree inherits
    /// from the database-level height strategy).
    ///
    /// # Returns
    /// A `Result<Option<HeightStrategy>>` containing the strategy if set.
    ///
    /// # Errors
    /// Returns an error if the subtree is not registered in `_index`.
    async fn get_height_strategy(&self) -> Result<Option<HeightStrategy>> {
        let index = self.transaction().get_index().await?;
        let settings = index.get_subtree_settings(self.name()).await?;
        Ok(settings.height_strategy)
    }

    /// Sets the height strategy for this Store in the `_index` subtree.
    ///
    /// Pass `None` to inherit from the database-level strategy,
    /// or `Some(strategy)` for independent height calculation.
    ///
    /// # Arguments
    /// * `strategy` - The height strategy to use, or None for inheritance.
    ///
    /// # Returns
    /// A `Result<()>` indicating success or failure.
    ///
    /// # Errors
    /// Returns an error if the subtree is not registered in `_index`.
    async fn set_height_strategy(&self, strategy: Option<HeightStrategy>) -> Result<()> {
        let index = self.transaction().get_index().await?;
        let mut settings = index.get_subtree_settings(self.name()).await?;
        settings.height_strategy = strategy;
        index.set_subtree_settings(self.name(), settings).await
    }

    /// Returns the local (staged) data for this store from the current transaction.
    ///
    /// This is a convenience method that retrieves data staged in the transaction
    /// for this store's subtree. Returns `Ok(None)` if no data has been staged.
    fn local_data(&self) -> Result<Option<Self::Data>> {
        self.transaction().get_local_data::<Self::Data>(self.name())
    }
}