feat: added a convenience method that will return an existing item du…

grovedb-version/src/version/grovedb_versions.rs

@@ -135,6 +135,7 @@ pub struct GroveDBOperationsInsertVersions {
     pub add_element_on_transaction: FeatureVersion,
     pub add_element_without_transaction: FeatureVersion,
     pub insert_if_not_exists: FeatureVersion,
+    pub insert_if_not_exists_return_existing_element: FeatureVersion,
     pub insert_if_changed_value: FeatureVersion,
 }
 

grovedb-version/src/version/v1.rs

@@ -94,6 +94,7 @@ pub const GROVE_V1: GroveVersion = GroveVersion {
                 add_element_on_transaction: 0,
                 add_element_without_transaction: 0,
                 insert_if_not_exists: 0,
+                insert_if_not_exists_return_existing_element: 0,
                 insert_if_changed_value: 0,
             },
             delete: GroveDBOperationsDeleteVersions {

grovedb/src/operations/insert/mod.rs

@@ -114,16 +114,16 @@
         })
     }
 
     fn insert_on_transaction<'db, 'b, B: AsRef<[u8]>>(
         &self,
         path: SubtreePath<'b, B>,
         key: &[u8],
         element: Element,
         options: InsertOptions,
         transaction: &'db Transaction,
         batch: &StorageBatch,
         grove_version: &GroveVersion,
     ) -> CostResult<(), Error> {
         check_grovedb_v0_with_cost!(
             "insert_on_transaction",
             grove_version
@@ -214,16 +214,16 @@
     /// first make sure other merk exist
     /// if it exists, then create merk to be inserted, and get root hash
     /// we only care about root hash of merk to be inserted
     fn add_element_on_transaction<'db, B: AsRef<[u8]>>(
         &'db self,
         path: SubtreePath<B>,
         key: &[u8],
         element: Element,
         options: InsertOptions,
         transaction: &'db Transaction,
         batch: &'db StorageBatch,
         grove_version: &GroveVersion,
     ) -> CostResult<Merk<PrefixedRocksDbTransactionContext<'db>>, Error> {
         check_grovedb_v0_with_cost!(
             "add_element_on_transaction",
             grove_version
@@ -486,6 +486,23 @@
     }
 
     /// Insert if not exists
+    /// Insert if not exists
+    ///
+    /// Inserts an element at the specified path and key if it does not already
+    /// exist.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The path where the element should be inserted.
+    /// * `key` - The key under which the element should be inserted.
+    /// * `element` - The element to insert.
+    /// * `transaction` - The transaction argument, if any.
+    /// * `grove_version` - The GroveDB version.
+    ///
+    /// # Returns
+    ///
+    /// Returns a `CostResult<bool, Error>` indicating whether the element was
+    /// inserted (`true`) or already existed (`false`).
     pub fn insert_if_not_exists<'b, B, P>(
         &self,
         path: P,
@@ -522,6 +539,62 @@
         }
     }
 
+    /// Insert if not exists
+    /// If the item does exist return it
+    ///
+    /// Inserts an element at the given `path` and `key` if it does not exist.
+    /// If the element already exists, returns the existing element.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The path where the element should be inserted.
+    /// * `key` - The key under which the element should be inserted.
+    /// * `element` - The element to insert.
+    /// * `transaction` - The transaction argument, if any.
+    /// * `grove_version` - The GroveDB version.
+    ///
+    /// # Returns
+    ///
+    /// Returns a `CostResult<Option<Element>, Error>`, where
+    /// `Ok(Some(element))` is the existing element if it was found, or
+    /// `Ok(None)` if the new element was inserted.
+    pub fn insert_if_not_exists_return_existing_element<'b, B, P>(
+        &self,
+        path: P,
+        key: &[u8],
+        element: Element,
+        transaction: TransactionArg,
+        grove_version: &GroveVersion,
+    ) -> CostResult<Option<Element>, Error>
+    where
+        B: AsRef<[u8]> + 'b,
+        P: Into<SubtreePath<'b, B>>,
+    {
+        check_grovedb_v0_with_cost!(
+            "insert_if_not_exists_return_existing_element",
+            grove_version
+                .grovedb_versions
+                .operations
+                .insert
+                .insert_if_not_exists_return_existing_element
+        );
+
+        let mut cost = OperationCost::default();
+        let subtree_path: SubtreePath<_> = path.into();
+
+        let previous_element = cost_return_on_error!(
+            &mut cost,
+            self.get_raw_optional(subtree_path.clone(), key, transaction, grove_version)
+        );
+        if previous_element.is_some() {
+            Ok(previous_element).wrap_with_cost(cost)
+        } else {
+            self.insert(subtree_path, key, element, None, transaction, grove_version)
+                .map_ok(|_| None)
+                .add_cost(cost)
+        }
+    }
+
     /// Insert if the value changed
     /// We return if the value was inserted
     /// If the value was changed then we return the previous element
@@ -788,6 +861,122 @@
         assert!(matches!(result, Err(Error::InvalidParentLayerPath(_))));
     }
 
+    #[test]
+    fn test_insert_if_not_exists_return_existing_element() {
+        let grove_version = GroveVersion::latest();
+        let db = make_test_grovedb(grove_version);
+
+        let element_key = b"key1";
+        let new_element = Element::new_item(b"new_value".to_vec());
+
+        // Insert a new element and check if it returns None
+        let result = db
+            .insert_if_not_exists_return_existing_element(
+                [TEST_LEAF].as_ref(),
+                element_key,
+                new_element.clone(),
+                None,
+                grove_version,
+            )
+            .unwrap()
+            .expect("Expected insertion of new element");
+
+        assert_eq!(result, None);
+
+        // Try inserting the same element again and expect it to return the existing
+        // element
+        let result = db
+            .insert_if_not_exists_return_existing_element(
+                [TEST_LEAF].as_ref(),
+                element_key,
+                Element::new_item(b"another_value".to_vec()),
+                None,
+                grove_version,
+            )
+            .unwrap()
+            .expect("Expected to return existing element");
+
+        assert_eq!(result, Some(new_element.clone()));
+
+        // Check if the existing element is still the original one and not replaced
+        let fetched_element = db
+            .get([TEST_LEAF].as_ref(), element_key, None, grove_version)
+            .unwrap()
+            .expect("Expected to retrieve the existing element");
+
+        assert_eq!(fetched_element, new_element);
+    }
+
+    #[test]
+    fn test_insert_if_not_exists_return_existing_element_with_transaction() {
+        let grove_version = GroveVersion::latest();
+        let db = make_test_grovedb(grove_version);
+
+        let element_key = b"key2";
+        let new_element = Element::new_item(b"transaction_value".to_vec());
+        let transaction = db.start_transaction();
+
+        // Insert a new element within a transaction and check if it returns None
+        let result = db
+            .insert_if_not_exists_return_existing_element(
+                [TEST_LEAF].as_ref(),
+                element_key,
+                new_element.clone(),
+                Some(&transaction),
+                grove_version,
+            )
+            .unwrap()
+            .expect("Expected insertion of new element in transaction");
+
+        assert_eq!(result, None);
+
+        // Try inserting the same element again within the transaction
+        // and expect it to return the existing element
+        let result = db
+            .insert_if_not_exists_return_existing_element(
+                [TEST_LEAF].as_ref(),
+                element_key,
+                Element::new_item(b"another_transaction_value".to_vec()),
+                Some(&transaction),
+                grove_version,
+            )
+            .unwrap()
+            .expect("Expected to return existing element in transaction");
+
+        assert_eq!(result, Some(new_element.clone()));
+
+        // Commit the transaction
+        db.commit_transaction(transaction).unwrap().unwrap();
+
+        // Check if the element is still the original one and not replaced
+        let fetched_element = db
+            .get([TEST_LEAF].as_ref(), element_key, None, grove_version)
+            .unwrap()
+            .expect("Expected to retrieve the existing element after transaction commit");
+
+        assert_eq!(fetched_element, new_element);
+    }
+
+    #[test]
+    fn test_insert_if_not_exists_return_existing_element_invalid_path() {
+        let grove_version = GroveVersion::latest();
+        let db = make_test_grovedb(grove_version);
+
+        // Try inserting to an invalid path and expect an error
+        let result = db.insert_if_not_exists_return_existing_element(
+            [b"invalid_path"].as_ref(),
+            b"key",
+            Element::new_item(b"value".to_vec()),
+            None,
+            grove_version,
+        );
+
+        assert!(matches!(
+            result.unwrap(),
+            Err(Error::InvalidParentLayerPath(_))
+        ));
+    }
+
     #[test]
     fn test_one_insert_item_cost() {
         let grove_version = GroveVersion::latest();