Struct Tree

pub struct Tree { /* private fields */ }

A tree CRDT backed by a Yrs document.

Tree implements NodeApi, forwarding the calls to the root node of the tree, allowing you to add nodes to the root node without calling root().

Tree Poisoning

When the underlying Yrs document is updated, the tree automatically updates its state in response. If the library detects that the Yrs document is malformed in a way that cannot be reconciled, it will mark the tree as “poisoned.”

Once a tree is poisoned, any operations on the tree that rely on the Yrs document will fail with a TreePoisoned error. Operations that only rely on the tree’s cached state will continue to succeed, but will not reflect the latest state of the Yrs document.

You can receive a notification when a tree is poisoned by subscribing to the tree’s events via Tree::on_change.

Implementations

impl Tree

pub fn new(doc: Arc<Doc>, tree_name: &str) -> Result<Arc<Self>>

Creates a new tree in the Yjs doc with the given container name. The tree will take over the map at the given name in the Yrs doc, and it should not be modified manually after creation.

Examples found in repository

examples/sync.rs (line 10)

fn main() -> Result<(), Box<dyn Error>> {
    let doc1 = Arc::new(yrs::Doc::new());
    let doc2 = Arc::new(yrs::Doc::new());

    let tree1 = Tree::new(doc1.clone(), "test")?;
    let tree2 = Tree::new(doc2.clone(), "test")?;

    let node1 = tree1.create_child_with_id("1")?;
    let node2 = tree1.create_child_with_id("2")?;
    let node3 = node1.create_child_with_id("3")?;
    let node4 = node2.create_child_with_id("4")?;
    node3.move_to(&node2, Some(0))?;
    node1.move_after(&node2)?;
    node4.move_before(&node3)?;

    println!("Tree 1: \n{}", tree1);
    println!("Syncing Yjs documents...\n");

    let txn = doc1.transact();
    let update = txn.encode_state_as_update_v1(&Default::default());
    drop(txn);

    doc2.transact_mut()
        .apply_update(Update::decode_v1(&update).unwrap())?;

    println!("Tree 2: \n{}", tree2);

    Ok(())
}

examples/basic.rs (line 7)

fn main() -> Result<(), Box<dyn Error>> {
    let doc = Arc::new(yrs::Doc::new());
    let tree = Tree::new(doc.clone(), "test")?;

    let _sub = tree.on_change(|e| match e {
        TreeEvent::TreeUpdated(tree) => {
            println!("{}", tree);
        }
        TreeEvent::TreePoisoned(_tree, err) => {
            println!("Tree is poisoned: {}", err);
        }
    });

    println!("Add 1 to ROOT");
    let node1 = tree.create_child_with_id("1")?;
    println!("Add 2 to ROOT");
    let node2 = tree.create_child_with_id("2")?;
    println!("Add 3 to 1");
    let node3 = node1.create_child_with_id("3")?;
    println!("Add 4 to 2");
    let node4 = node2.create_child_with_id("4")?;

    println!("Move 3 to 2, index 0");
    node3.move_to(&node2, Some(0))?;

    println!("Move 1 after 2");
    node1.move_after(&node2)?;

    println!("Move 4 before 3");
    node4.move_before(&node3)?;

    println!("Set data on 1: my_key = my_value");
    node1.set("my_key", "my_value")?;

    let val = node1.get_as::<String>("my_key")?;
    println!("Get data from 1: my_key = {}", val);

    Ok(())
}

examples/sync_reconcile.rs (line 10)

fn main() -> Result<(), Box<dyn Error>> {
    let doc1 = Arc::new(yrs::Doc::new());
    let doc2 = Arc::new(yrs::Doc::new());

    let tree1 = Tree::new(doc1.clone(), "test")?;
    let tree2 = Tree::new(doc2.clone(), "test")?;

    let node1 = tree1.create_child_with_id("1")?;
    let node2 = tree1.create_child_with_id("2")?;
    let node3 = node1.create_child_with_id("3")?;
    let node4 = node2.create_child_with_id("4")?;
    node3.move_to(&node2, Some(0))?;
    node1.move_after(&node2)?;
    node4.move_before(&node3)?;

    sync_docs(&doc1, &doc2)?;

    // Simulate a cycle created by disparate clients
    let node3_left = tree1.get_node("3").unwrap();
    let node4_left = tree1.get_node("4").unwrap();
    node3_left.move_to(&node4_left, None)?;

    let node3_right = tree2.get_node("3").unwrap();
    let node4_right = tree2.get_node("4").unwrap();
    node4_right.move_to(&node3_right, None)?;

    println!("Tree 1: \n{}", tree1);
    println!("Tree 2: \n{}", tree2);

    println!("Syncing docs...\n");
    sync_docs(&doc1, &doc2)?;

    println!("Tree 1: \n{}", tree1);
    println!("Tree 2: \n{}", tree2);

    Ok(())
}

pub fn is_poisoned(&self) -> bool

Returns true if the tree is poisoned.

pub fn get_poisoned_reason(&self) -> Option<TreeError>

Returns the reason the tree is poisoned, if it is poisoned.

pub fn root(self: &Arc<Self>) -> Arc<Node>

Returns the root node of the tree.

pub fn has_node(self: &Arc<Self>, id: impl Into<NodeId>) -> bool

Returns true if the tree has a node with the given ID.

pub fn get_node(self: &Arc<Self>, id: impl Into<NodeId>) -> Option<Arc<Node>>

Returns the node with the given ID.

Examples found in repository

examples/sync_reconcile.rs (line 24)

fn main() -> Result<(), Box<dyn Error>> {
    let doc1 = Arc::new(yrs::Doc::new());
    let doc2 = Arc::new(yrs::Doc::new());

    let tree1 = Tree::new(doc1.clone(), "test")?;
    let tree2 = Tree::new(doc2.clone(), "test")?;

    let node1 = tree1.create_child_with_id("1")?;
    let node2 = tree1.create_child_with_id("2")?;
    let node3 = node1.create_child_with_id("3")?;
    let node4 = node2.create_child_with_id("4")?;
    node3.move_to(&node2, Some(0))?;
    node1.move_after(&node2)?;
    node4.move_before(&node3)?;

    sync_docs(&doc1, &doc2)?;

    // Simulate a cycle created by disparate clients
    let node3_left = tree1.get_node("3").unwrap();
    let node4_left = tree1.get_node("4").unwrap();
    node3_left.move_to(&node4_left, None)?;

    let node3_right = tree2.get_node("3").unwrap();
    let node4_right = tree2.get_node("4").unwrap();
    node4_right.move_to(&node3_right, None)?;

    println!("Tree 1: \n{}", tree1);
    println!("Tree 2: \n{}", tree2);

    println!("Syncing docs...\n");
    sync_docs(&doc1, &doc2)?;

    println!("Tree 1: \n{}", tree1);
    println!("Tree 2: \n{}", tree2);

    Ok(())
}

pub fn on_change( &self, callback: impl Fn(&TreeEvent) + Send + Sync + 'static, ) -> Subscription

Returns a subscription to the tree’s events. When dropped, the subscription is automatically cancelled.

Examples found in repository

examples/basic.rs (lines 9-16)

fn main() -> Result<(), Box<dyn Error>> {
    let doc = Arc::new(yrs::Doc::new());
    let tree = Tree::new(doc.clone(), "test")?;

    let _sub = tree.on_change(|e| match e {
        TreeEvent::TreeUpdated(tree) => {
            println!("{}", tree);
        }
        TreeEvent::TreePoisoned(_tree, err) => {
            println!("Tree is poisoned: {}", err);
        }
    });

    println!("Add 1 to ROOT");
    let node1 = tree.create_child_with_id("1")?;
    println!("Add 2 to ROOT");
    let node2 = tree.create_child_with_id("2")?;
    println!("Add 3 to 1");
    let node3 = node1.create_child_with_id("3")?;
    println!("Add 4 to 2");
    let node4 = node2.create_child_with_id("4")?;

    println!("Move 3 to 2, index 0");
    node3.move_to(&node2, Some(0))?;

    println!("Move 1 after 2");
    node1.move_after(&node2)?;

    println!("Move 4 before 3");
    node4.move_before(&node3)?;

    println!("Set data on 1: my_key = my_value");
    node1.set("my_key", "my_value")?;

    let val = node1.get_as::<String>("my_key")?;
    println!("Get data from 1: my_key = {}", val);

    Ok(())
}

Trait Implementations

impl Clone for Tree

fn clone(&self) -> Tree

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Tree

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Tree

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl NodeApi for Tree

Tree implements NodeApi, forwarding the calls to the root node of the tree

fn id(self: &Arc<Self>) -> &NodeId

Returns the ID of the node.

fn create_child(self: &Arc<Self>) -> Result<Arc<Node>>

Creates a new child node with a generated ID.

fn create_child_at(self: &Arc<Self>, index: usize) -> Result<Arc<Node>>

Creates a new child node with a generated ID at the given index in the parent’s children.

fn create_child_with_id( self: &Arc<Self>, id: impl Into<NodeId>, ) -> Result<Arc<Node>>

Creates a new child node with the given ID at the end of the parent’s children.

fn create_child_with_id_at( self: &Arc<Self>, id: impl Into<NodeId>, index: usize, ) -> Result<Arc<Node>>

Creates a new child node with the given ID at the given index in the parent’s children.

fn move_to( self: &Arc<Self>, _parent: &Node, _index: Option<usize>, ) -> Result<()>

Moves the node to the given parent, placing it in that parent’s children at the given index.

fn move_before(self: &Arc<Self>, _other: &Arc<Node>) -> Result<()>

Moves the node before the given node.

fn move_after(self: &Arc<Self>, _other: &Arc<Node>) -> Result<()>

Moves the node after the given node.

fn children(self: &Arc<Self>) -> Vec<Arc<Node>>

Returns the children of the node.

fn parent(self: &Arc<Self>) -> Option<Arc<Node>>

Returns the parent of the node.

fn ancestors(self: &Arc<Self>) -> Vec<Arc<Node>>

Returns the ancestors of the node, starting with the node’s parent and ending at the root node.

fn descendants(self: &Arc<Self>, order: TraversalOrder) -> Vec<Arc<Node>>

Returns the descendants of the node. Equivalent to self.traverse(order).skip(1).collect().

fn siblings(self: &Arc<Self>) -> Vec<Arc<Node>>

Returns the siblings of the node.

fn depth(self: &Arc<Self>) -> usize

Returns the depth of the node. The root node has a depth of 0; all other nodes have a depth of 1 plus the depth of their parent.

fn delete(self: &Arc<Self>, strategy: DeleteStrategy) -> Result<()>

Deletes the node from the tree.

fn traverse(self: &Arc<Self>, order: TraversalOrder) -> TreeIter

Returns an iterator over the node and its descendants in the given order.

impl PartialEq for Tree

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.