From 83023b73bdb986f8681c97bbfa434256f4454976 Mon Sep 17 00:00:00 2001
From: Zixuan Chen <remch183@outlook.com>
Date: Sat, 1 Feb 2025 17:31:34 +0800
Subject: [PATCH] docs: refine map.set docs

---
 crates/loro-wasm/src/lib.rs | 9 +++++++--
 crates/loro/src/lib.rs      | 3 +++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/crates/loro-wasm/src/lib.rs b/crates/loro-wasm/src/lib.rs
index 398d2608..deb829ea 100644
--- a/crates/loro-wasm/src/lib.rs
+++ b/crates/loro-wasm/src/lib.rs
@@ -5945,6 +5945,7 @@ interface LoroMovableList<T = unknown> {
      */
     setContainer<C extends Container>(pos: number, child: C): T extends C ? T : C;
 }
+
 interface LoroMap<T extends Record<string, unknown> = Record<string, unknown>> {
     new(): LoroMap<T>;
     /**
@@ -5998,9 +5999,13 @@ interface LoroMap<T extends Record<string, unknown> = Record<string, unknown>> {
      */
     get<Key extends keyof T>(key: Key): T[Key];
     /**
-     * Set the key with the value.
+     *  Set the key with the value.
      *
-     *  If the value of the key is exist, the old value will be updated.
+     *  If the key already exists, its value will be updated. If the key doesn't exist,
+     *  a new key-value pair will be created.
+     *
+     *  > **Note**: When calling `map.set(key, value)` on a LoroMap, if `map.get(key)` already returns `value`, 
+     *  > the operation will be a no-op (no operation recorded) to avoid unnecessary updates.
      *
      *  @example
      *  ```ts
diff --git a/crates/loro/src/lib.rs b/crates/loro/src/lib.rs
index 48fcb93d..e619faf8 100644
--- a/crates/loro/src/lib.rs
+++ b/crates/loro/src/lib.rs
@@ -1373,6 +1373,9 @@ impl LoroMap {
     }
 
     /// Insert a key-value pair into the map.
+    ///
+    /// > **Note**: When calling `map.set(key, value)` on a LoroMap, if `map.get(key)` already returns `value`,
+    /// > the operation will be a no-op (no operation recorded) to avoid unnecessary updates.
     pub fn insert(&self, key: &str, value: impl Into<LoroValue>) -> LoroResult<()> {
         self.handler.insert(key, value)
     }