Struct Transaction 

pub struct Transaction { /* private fields */ }

Represents a single, atomic transaction for modifying a Database.

An Transaction encapsulates a mutable EntryBuilder being constructed. Users interact with specific Store instances obtained via Transaction::get_store to stage changes. All staged changes across different subtrees within the transaction are recorded in the internal EntryBuilder.

When commit() is called, the transaction:

1. Finalizes the EntryBuilder by building an immutable Entry
2. Calculates the entry’s content-addressable ID
3. Ensures the correct parent links are set based on the tree’s state
4. Removes any empty subtrees that didn’t have data staged
5. Signs the entry if authentication is configured
6. Persists the resulting immutable Entry to the backend

Transaction instances are typically created via Database::new_transaction().

Implementations

impl Transaction

pub fn get_settings(&self) -> Result<SettingsStore>

Get a SettingsStore handle for the settings subtree within this transaction.

This method returns a SettingsStore that provides specialized access to the _settings subtree, allowing you to read and modify settings data within this atomic transaction. The DocStore automatically merges historical settings from the database with any staged changes in this transaction.

Returns

Returns a Result<SettingsStore> that can be used to:

• Read current settings values (including both historical and staged data)
• Stage new settings changes within this transaction
• Access nested settings structures

Example

let txn = database.new_transaction().await?;
let settings = txn.get_settings()?;

// Read a setting
if let Ok(name) = settings.get_name().await {
    println!("Database name: {}", name);
}

// Modify a setting
settings.set_name("Updated Database Name").await?;

Errors

Returns an error if:

• Unable to create the SettingsStore for the settings subtree
• Operation has already been committed

pub async fn get_index(&self) -> Result<Registry>

Gets a handle to the Index for managing subtree registry and metadata.

The Index provides access to the _index subtree, which stores metadata about all subtrees in the database including their type identifiers and configurations.

Returns

A Result<Registry> containing the handle for managing the index.

Errors

Returns an error if:

• Unable to create the Registry for the _index subtree
• Operation has already been committed

pub async fn get_store<T>( &self, subtree_name: impl Into<String> + Send, ) -> Result<T>

where T: Store + Send,

Gets a handle to a specific Store for modification within this transaction.

This method creates and returns an instance of the specified Store type T, associated with this Transaction. The returned Store handle can be used to stage changes (e.g., using DocStore::set). These changes are recorded within this Transaction.

If this is the first time this subtree is accessed within the transaction, its parent tips will be fetched and stored.

Type Parameters

• T - The concrete Store implementation type to create.

Arguments

• subtree_name - The name of the subtree to get a modification handle for.

Returns

A Result<T> containing the Store handle.

pub fn get_local_data<T>( &self, subtree_name: impl AsRef<str>, ) -> Result<Option<T>>

where T: Data,

Gets the currently staged data for a specific subtree within this transaction.

This is intended for use by Store implementations to retrieve the data they have staged locally within the Transaction before potentially merging it with historical data.

Type Parameters

• T - The data type (expected to be a CRDT) to deserialize the staged data into.

Arguments

• subtree_name - The name of the subtree whose staged data is needed.

Returns

A Result<Option<T>>:

Behavior

• If the subtree doesn’t exist or has no data, returns Ok(None)
• If the subtree exists but has empty data (empty string or whitespace), returns Ok(None)
• Otherwise deserializes the JSON data to type T and returns Ok(Some(T))

Errors

Returns an error if the transaction has already been committed or if the subtree data exists but cannot be deserialized to type T.

pub async fn commit(self) -> Result<ID>

Commits the transaction, finalizing and persisting the entry to the backend.

This method:

1. Takes ownership of the EntryBuilder from the internal Option
2. Removes any empty subtrees
3. Adds metadata if appropriate
4. Sets authentication if configured
5. Builds the immutable Entry using EntryBuilder::build()
6. Signs the entry if authentication is configured
7. Validates authentication if present
8. Calculates the entry’s content-addressable ID
9. Persists the entry to the backend
10. Returns the ID of the newly created entry

After commit, the transaction cannot be used again, as the internal EntryBuilder has been consumed.

Returns

A Result<ID> containing the ID of the committed entry.

Trait Implementations

impl Clone for Transaction

fn clone(&self) -> Transaction

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.