Introduce monger.collection/save-and-return that mimics /insert-and-return but for /save

ChangeLog.md

@@ -1,3 +1,13 @@
+## Changes between 1.0.0-beta2 and 1.1.0-rc1
+
+### monger.collection/save-and-return
+
+`monger.collection/save-and-return` is a new function that to `monger.collection/save` is what `monger.collection/insert-and-return`
+is to `monger.collection/insert`. See Monger 1.1.0-beta1 changes or function documentation strings for more information.
+
+
+
+
 ## Changes between 1.0.0-beta1 and 1.1.0-beta2
 
 ### Support for passing keywords as collection names

src/clojure/monger/collection.clj

@@ -417,6 +417,9 @@
    If the object is not present in the database, insert operation will be performed.
    If the object is already in the database, it will be updated.
 
+   This function returns write result. If you want to get the exact persisted document back,
+   use `save-and-return`.
+
    EXAMPLES
 
        (monger.collection/save \"people\" {:first_name \"Ian\" :last_name \"Gillan\"})
@@ -427,13 +430,39 @@
             monger.core/*mongodb-write-concern*))
   ([^String collection ^Map document ^WriteConcern write-concern]
      (.save (.getCollection monger.core/*mongodb-database* (name collection))
-            document
+            (to-db-object document)
             write-concern))
   ([^DB db ^String collection ^Map document ^WriteConcern write-concern]
      (.save (.getCollection db (name collection))
-            document
+            (to-db-object document)
             write-concern)))
 
+(defn ^clojure.lang.IPersistentMap save-and-return
+  "Saves an object to the given collection (does insert or update based on the object _id).
+
+   If the object is not present in the database, insert operation will be performed.
+   If the object is already in the database, it will be updated.
+
+   This function returns the exact persisted document back, including the `:_id` key in
+   case of an insert.
+
+   If you want to get write result back, use `save`.
+
+   EXAMPLES
+
+       (monger.collection/save-and-return \"people\" {:first_name \"Ian\" :last_name \"Gillan\"})
+   "
+  ([^String collection ^Map document]
+     (save-and-return ^DB monger.core/*mongodb-database* collection document ^WriteConcern monger.core/*mongodb-write-concern*))
+  ([^String collection ^Map document ^WriteConcern write-concern]
+     (save-and-return ^DB monger.core/*mongodb-database* collection document write-concern))
+  ([^DB db ^String collection ^Map document ^WriteConcern write-concern]
+     ;; see the comment in insert-and-return. Here we additionally need to make sure to not scrap the :_id key if
+     ;; it is already present. MK.
+     (let [doc (merge {:_id (ObjectId.)} document)]
+       (save db collection doc write-concern)
+       doc)))
+
 
 ;; monger.collection/remove
 

test/monger/test/updating_test.clj

@@ -22,7 +22,7 @@
 ;; update, save
 ;;
 
-(deftest update-document-by-id-without-upsert
+(deftest ^{:updating true} update-document-by-id-without-upsert
   (let [collection "libraries"
         doc-id       (monger.util/random-uuid)
         date         (Date.)
@@ -33,7 +33,7 @@
     (mc/update collection { :_id doc-id } { :language "Erlang" })
     (is (= (modified-doc (mc/find-by-id collection doc-id))))))
 
-(deftest update-document-by-id-without-upsert-using-update-by-id
+(deftest ^{:updating true} update-document-by-id-without-upsert-using-update-by-id
   (let [collection "libraries"
         doc-id       (monger.util/random-uuid)
         date         (Date.)
@@ -44,7 +44,7 @@
     (mc/update-by-id collection doc-id { :language "Erlang" })
     (is (= (modified-doc (mc/find-by-id collection doc-id))))))
 
-(deftest update-nested-document-fields-without-upsert-using-update-by-id
+(deftest ^{:updating true} update-nested-document-fields-without-upsert-using-update-by-id
   (let [collection "libraries"
         doc-id       (ObjectId.)
         date         (Date.)
@@ -56,7 +56,7 @@
     (is (= (modified-doc (mc/find-by-id collection doc-id))))))
 
 
-(deftest update-multiple-documents
+(deftest ^{:updating true} update-multiple-documents
   (let [collection "libraries"]
     (mc/insert collection { :language "Clojure", :name "monger" })
     (mc/insert collection { :language "Clojure", :name "langohr" })
@@ -71,23 +71,31 @@
     (is (= 3 (mc/count collection { :language "Python"  })))))
 
 
-(deftest save-a-new-document
+(deftest ^{:updating true} save-a-new-document
   (let [collection "people"
-        document       { :name "Joe", :age 30 }]
+        document       {:name "Joe" :age 30}]
     (is (monger.result/ok? (mc/save "people" document)))
     (is (= 1 (mc/count collection)))))
 
-
-(deftest save-a-new-basic-db-object
+(deftest ^{:updating true} save-and-return-a-new-document
   (let [collection "people"
-        doc        (to-db-object { :name "Joe", :age 30 })]
+        document       {:name "Joe" :age 30}
+        returned   (mc/save-and-return "people" document)]
+    (is (:_id returned))
+    (is (= document (dissoc returned :_id)))
+    (is (= 1 (mc/count collection)))))
+
+
+(deftest ^{:updating true} save-a-new-basic-db-object
+  (let [collection "people"
+        doc        (to-db-object {:name "Joe" :age 30})]
     (is (nil? (monger.util/get-id doc)))
     (mc/save monger.core/*mongodb-database* "people" doc WriteConcern/SAFE)
     (is (not (nil? (monger.util/get-id doc))))))
 
 
 
-(deftest update-an-existing-document-using-save
+(deftest ^{:updating true} update-an-existing-document-using-save
   (let [collection "people"
         doc-id            "people-1"
         document          { :_id doc-id, :name "Joe",   :age 30 }]
@@ -96,8 +104,17 @@
     (mc/save collection { :_id doc-id, :name "Alan", :age 40 })
     (is (= 1 (mc/count collection { :name "Alan", :age 40 })))))
 
+(deftest ^{:updating true} update-an-existing-document-using-save-and-return
+  (let [collection "people"
+        document   (mc/insert-and-return "people" {:name "Joe" :age 30})
+        doc-id     (:_id document)
+        updated    (mc/save-and-return collection {:_id doc-id :name "Alan" :age 40})]
+    (is (= {:_id doc-id :name "Alan" :age 40} updated))
+    (is (= 1 (mc/count collection)))
+    (is (= 1 (mc/count collection {:name "Alan" :age 40})))))
 
-(deftest set-an-attribute-on-existing-document-using-update
+
+(deftest ^{:updating true} set-an-attribute-on-existing-document-using-update
   (let [collection "people"
         doc-id            (monger.util/object-id)
         document          { :_id doc-id, :name "Joe",   :age 30 }]
@@ -108,7 +125,7 @@
     (is (= 1 (mc/count collection { :has_kids true })))))
 
 
-(deftest  increment-multiple-fields-using-exists-operator-and-update
+(deftest ^{:updating true}  increment-multiple-fields-using-exists-operator-and-update
   (let [collection "matches"
         doc-id     (monger.util/object-id)
         document   { :_id doc-id :abc 0 :def 10 }]
@@ -120,7 +137,7 @@
 
 
 
-(deftest upsert-a-document
+(deftest ^{:updating true} upsert-a-document
   (let [collection "libraries"
         doc-id       (monger.util/random-uuid)
         date         (Date.)