feat: automatic merging for concurrent container inserts in maps

crates/loro-common/src/lib.rs

@@ -73,6 +73,18 @@ pub fn check_root_container_name(name: &str) -> bool {
     !name.is_empty() && name.char_indices().all(|(_, x)| x != '/' && x != '\0')
 }
 
+/// Return whether the given name indicates a mergeable container.
+///
+/// Mergeable containers are special containers that use a Root Container ID format
+/// but have a parent. They are identified by having a `/` in their name, which is
+/// forbidden for user-created root containers.
+///
+/// The format is: `parent_container_id/key`
+#[inline]
+pub fn is_mergeable_container_name(name: &str) -> bool {
+    name.contains('/')
+}
+
 impl CompactId {
     pub fn new(peer: PeerID, counter: Counter) -> Self {
         Self {
@@ -584,6 +596,19 @@ mod container {
         pub fn is_unknown(&self) -> bool {
             matches!(self.container_type(), ContainerType::Unknown(_))
         }
+
+        /// Returns true if this is a mergeable container.
+        ///
+        /// Mergeable containers are special containers that use a Root Container ID format
+        /// but have a parent. They are identified by having a `/` in their name, which is
+        /// forbidden for user-created root containers.
+        #[inline]
+        pub fn is_mergeable(&self) -> bool {
+            match self {
+                ContainerID::Root { name, .. } => crate::is_mergeable_container_name(name),
+                ContainerID::Normal { .. } => false,
+            }
+        }
     }
 
     impl TryFrom<&str> for ContainerType {

crates/loro-internal/src/arena.rs

@@ -330,7 +330,8 @@ impl SharedArena {
     }
 
     pub fn get_parent(&self, child: ContainerIdx) -> Option<ContainerIdx> {
-        if self.get_container_id(child).unwrap().is_root() {
+        let id = self.get_container_id(child).unwrap();
+        if id.is_root() && !id.is_mergeable() {
             // TODO: PERF: we can speed this up by use a special bit in ContainerIdx to indicate
             // whether the target is a root container
             return None;

crates/loro-internal/src/encoding/value.rs

@@ -70,6 +70,8 @@ pub enum LoroValueKind {
     List,
     Map,
     ContainerType,
+    /// Root container type - used for mergeable containers
+    RootContainerType,
 }
 impl LoroValueKind {
     fn from_u8(kind: u8) -> Self {
@@ -84,6 +86,7 @@ impl LoroValueKind {
             7 => LoroValueKind::List,
             8 => LoroValueKind::Map,
             9 => LoroValueKind::ContainerType,
+            10 => LoroValueKind::RootContainerType,
             _ => unreachable!(),
         }
     }
@@ -100,6 +103,7 @@ impl LoroValueKind {
             LoroValueKind::List => 7,
             LoroValueKind::Map => 8,
             LoroValueKind::ContainerType => 9,
+            LoroValueKind::RootContainerType => 10,
         }
     }
 }
@@ -665,6 +669,23 @@ impl<'a> ValueReader<'a> {
 
                 LoroValue::Container(container_id)
             }
+            LoroValueKind::RootContainerType => {
+                // Read container type
+                let type_u8 = self.read_u8()?;
+                let container_type =
+                    ContainerType::try_from_u8(type_u8).unwrap_or(ContainerType::Unknown(type_u8));
+                // Read the root container name from the keys arena
+                let key_idx = self.read_usize()?;
+                let name = keys
+                    .get(key_idx)
+                    .ok_or(LoroError::DecodeDataCorruptionError)?
+                    .clone();
+                let container_id = ContainerID::Root {
+                    name,
+                    container_type,
+                };
+                LoroValue::Container(container_id)
+            }
         })
     }
 
@@ -777,6 +798,23 @@ impl<'a> ValueReader<'a> {
 
                         LoroValue::Container(container_id)
                     }
+                    LoroValueKind::RootContainerType => {
+                        // Read container type
+                        let type_u8 = self.read_u8()?;
+                        let container_type = ContainerType::try_from_u8(type_u8)
+                            .unwrap_or(ContainerType::Unknown(type_u8));
+                        // Read the root container name from the keys arena
+                        let name_key_idx = self.read_usize()?;
+                        let name = keys
+                            .get(name_key_idx)
+                            .ok_or(LoroError::DecodeDataCorruptionError)?
+                            .clone();
+                        let container_id = ContainerID::Root {
+                            name,
+                            container_type,
+                        };
+                        LoroValue::Container(container_id)
+                    }
                 };
 
                 task = match task {
@@ -1035,10 +1073,23 @@ impl ValueWriter {
                 (LoroValueKind::Map, len)
             }
             LoroValue::Binary(value) => (LoroValueKind::Binary, self.write_binary(value)),
-            LoroValue::Container(c) => (
-                LoroValueKind::ContainerType,
-                self.write_u8(c.container_type().to_u8()),
-            ),
+            LoroValue::Container(c) => match c {
+                ContainerID::Normal { container_type, .. } => (
+                    LoroValueKind::ContainerType,
+                    self.write_u8(container_type.to_u8()),
+                ),
+                ContainerID::Root {
+                    name,
+                    container_type,
+                } => {
+                    // For Root containers, we need to encode:
+                    // 1. The container type
+                    // 2. The name (via key register)
+                    let key_idx = registers.key_mut().register(name);
+                    let len = self.write_u8(container_type.to_u8()) + self.write_usize(key_idx);
+                    (LoroValueKind::RootContainerType, len)
+                }
+            },
         }
     }
 
@@ -1145,6 +1196,9 @@ fn get_loro_value_kind(value: &LoroValue) -> LoroValueKind {
         LoroValue::List(_) => LoroValueKind::List,
         LoroValue::Map(_) => LoroValueKind::Map,
         LoroValue::Binary(_) => LoroValueKind::Binary,
-        LoroValue::Container(_) => LoroValueKind::ContainerType,
+        LoroValue::Container(c) => match c {
+            ContainerID::Normal { .. } => LoroValueKind::ContainerType,
+            ContainerID::Root { .. } => LoroValueKind::RootContainerType,
+        },
     }
 }

crates/loro-internal/src/handler.rs

@@ -4151,6 +4151,141 @@ impl MapHandler {
             }),
         }
     }
+
+    pub fn get_mergeable_list(&self, key: &str) -> LoroResult<ListHandler> {
+        self.get_or_create_mergeable_container(
+            key,
+            Handler::new_unattached(ContainerType::List)
+                .into_list()
+                .unwrap(),
+        )
+    }
+
+    pub fn get_mergeable_map(&self, key: &str) -> LoroResult<MapHandler> {
+        self.get_or_create_mergeable_container(
+            key,
+            Handler::new_unattached(ContainerType::Map)
+                .into_map()
+                .unwrap(),
+        )
+    }
+
+    pub fn get_mergeable_movable_list(&self, key: &str) -> LoroResult<MovableListHandler> {
+        self.get_or_create_mergeable_container(
+            key,
+            Handler::new_unattached(ContainerType::MovableList)
+                .into_movable_list()
+                .unwrap(),
+        )
+    }
+
+    pub fn get_mergeable_text(&self, key: &str) -> LoroResult<TextHandler> {
+        self.get_or_create_mergeable_container(
+            key,
+            Handler::new_unattached(ContainerType::Text)
+                .into_text()
+                .unwrap(),
+        )
+    }
+
+    pub fn get_mergeable_tree(&self, key: &str) -> LoroResult<TreeHandler> {
+        self.get_or_create_mergeable_container(
+            key,
+            Handler::new_unattached(ContainerType::Tree)
+                .into_tree()
+                .unwrap(),
+        )
+    }
+
+    #[cfg(feature = "counter")]
+    pub fn get_mergeable_counter(&self, key: &str) -> LoroResult<counter::CounterHandler> {
+        self.get_or_create_mergeable_container(
+            key,
+            Handler::new_unattached(ContainerType::Counter)
+                .into_counter()
+                .unwrap(),
+        )
+    }
+
+    pub fn get_or_create_mergeable_container<C: HandlerTrait>(
+        &self,
+        key: &str,
+        child: C,
+    ) -> LoroResult<C> {
+        // Extract just the name portion from the parent container ID.
+        // For Root containers, we use the name directly (without the "cid:root-" prefix).
+        // For Normal containers, we format as "counter@peer:type".
+        let parent_name = match self.id() {
+            ContainerID::Root { name, .. } => name.to_string(),
+            ContainerID::Normal {
+                peer,
+                counter,
+                container_type,
+            } => format!("{}@{}:{}", counter, peer, container_type),
+        };
+        let name = format!("{}/{}", parent_name, key);
+        let expected_id = ContainerID::Root {
+            name: name.into(),
+            container_type: child.kind(),
+        };
+
+        // Check if exists
+        if let Some(ValueOrHandler::Handler(h)) = self.get_(key) {
+            if h.id() == expected_id {
+                if let Some(c) = C::from_handler(h) {
+                    return Ok(c);
+                } else {
+                    unreachable!("Container type mismatch for same ID");
+                }
+            }
+        }
+
+        // Create
+        match &self.inner {
+            MaybeDetached::Detached(_) => Err(LoroError::MisuseDetachedContainer {
+                method: "get_or_create_mergeable_container",
+            }),
+            MaybeDetached::Attached(a) => a.with_txn(|txn| {
+                self.insert_mergeable_container_with_txn(txn, key, child, expected_id)
+            }),
+        }
+    }
+
+    pub fn insert_mergeable_container_with_txn<H: HandlerTrait>(
+        &self,
+        txn: &mut Transaction,
+        key: &str,
+        child: H,
+        container_id: ContainerID,
+    ) -> LoroResult<H> {
+        let inner = self.inner.try_attached_state()?;
+
+        // Insert into Map
+        txn.apply_local_op(
+            inner.container_idx,
+            crate::op::RawOpContent::Map(crate::container::map::MapSet {
+                key: key.into(),
+                value: Some(LoroValue::Container(container_id.clone())),
+            }),
+            EventHint::Map {
+                key: key.into(),
+                value: Some(LoroValue::Container(container_id.clone())),
+            },
+            &inner.doc,
+        )?;
+
+        // Attach
+        let ans = child.attach(txn, inner, container_id)?;
+
+        // Set Parent in Arena
+        let child_idx = ans.idx();
+        inner
+            .doc
+            .arena
+            .set_parent(child_idx, Some(inner.container_idx));
+
+        Ok(ans)
+    }
 }
 
 fn with_txn<R>(doc: &LoroDoc, f: impl FnOnce(&mut Transaction) -> LoroResult<R>) -> LoroResult<R> {

crates/loro-internal/src/state.rs

@@ -876,7 +876,7 @@ impl DocState {
         let roots = self.arena.root_containers(flag);
         let ans: loro_common::LoroMapValue = roots
             .into_iter()
-            .map(|idx| {
+            .filter_map(|idx| {
                 let id = self.arena.idx_to_id(idx).unwrap();
                 let ContainerID::Root {
                     name,
@@ -885,7 +885,11 @@ impl DocState {
                 else {
                     unreachable!()
                 };
-                (name.to_string(), LoroValue::Container(id))
+                // Skip mergeable containers - they should not appear at the root level
+                if id.is_mergeable() {
+                    return None;
+                }
+                Some((name.to_string(), LoroValue::Container(id)))
             })
             .collect();
         LoroValue::Map(ans)
@@ -905,6 +909,10 @@ impl DocState {
             let id = self.arena.idx_to_id(root_idx).unwrap();
             match &id {
                 loro_common::ContainerID::Root { name, .. } => {
+                    // Skip mergeable containers - they should not appear at the root level
+                    if id.is_mergeable() {
+                        continue;
+                    }
                     let v = self.get_container_deep_value(root_idx);
                     if (should_hide_empty_root_container || deleted_root_container.contains(&id))
                         && v.is_empty_collection()
@@ -931,6 +939,10 @@ impl DocState {
             let id = self.arena.idx_to_id(root_idx).unwrap();
             match id.clone() {
                 loro_common::ContainerID::Root { name, .. } => {
+                    // Skip mergeable containers - they should not appear at the root level
+                    if id.is_mergeable() {
+                        continue;
+                    }
                     ans.insert(
                         name.to_string(),
                         self.get_container_deep_value_with_id(root_idx, Some(id)),