MONGOID-5331 Document hash assignment to associations (#5494)

* MONGOID-5331 change buildable docs

* MONGOID-5331 add proxy tests and fix embedded_in proxy

* MONGOID-5331 update models

* Update spec/mongoid/association/embedded/embedded_in/proxy_spec.rb

* MONGOID-5331 update doc strings in batchable

* MONGOID-5331 add docs

* MONGOID-5331 add docs/release notes

* Apply suggestions from code review

* Update spec/mongoid/association/embedded/embedded_in/proxy_spec.rb

Author: neilshweky

docs/reference/associations.txt

@@ -875,6 +875,38 @@ documents that exist in the application:
   band.tours.destroy_all
 
 
+.. _hash-assignment:
+
+Hash Assignment
+---------------
+
+Embedded associations allow the user to assign a ``Hash`` instead of a document
+to an association. On assignment, this hash is coerced into a document of the
+class of the association that it's being assigned to. Take the following
+example:
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+    embeds_many :albums
+  end
+
+  class Album
+    include Mongoid::Document
+    field :name, type: String
+    embedded_in :band
+  end
+
+  band = Band.create!
+  band.albums = [ { name: "Narrow Stairs" }, { name: "Transatlanticism" } ]
+  p band.albums
+  # => [ #<Album _id: 633c71e93282a4357bb608e5, name: "Narrow Stairs">, #<Album _id: 633c71e93282a4357bb608e6, name: "Transatlanticism"> ]
+
+This works for ``embeds_one``, ``embeds_many``, and ``embedded_in`` associations.
+Note that you cannot assign hashes to referenced associations.
+
+
 Common Behavior
 ===============
 

docs/release-notes/mongoid-8.1.txt

@@ -341,3 +341,34 @@ This time, the value for the ``:age`` field is maintained.
   The default for the ``:replace`` option will be changed to ``false`` in
   Mongoid 9.0, therefore it is recommended to explicitly specify this option
   while using ``#upsert`` in 8.1 for easier upgradability.
+
+
+Allow Hash Assignment to ``embedded_in``
+----------------------------------------
+
+Mongoid 8.1 allows the assignment of a hash to an ``embedded_in`` association.
+On assignment, the hash will be coerced into a document of the class of the
+association that it is being assigned to. This functionality already exists
+for ``embeds_one`` and ``embeds_many`` associations. Consider the following
+example:
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+    embeds_many :albums
+  end
+
+  class Album
+    include Mongoid::Document
+    embedded_in :band
+  end
+
+  album = Album.new
+  album.band = { name: "Death Cab For Cutie" }
+  p album.band
+  # => <Band _id: 633c74113282a438a15d2b56, name: "Death Cab For Cutie">
+
+See the section on :ref:`Hash Assignment on Embedded Associations <hash-assignment>`
+for more details

lib/mongoid/association/embedded/batchable.rb

@@ -97,7 +97,7 @@ def batch_remove(docs, method = :delete)
         # @example Batch replace the documents.
         #   batchable.batch_replace([ doc_one, doc_two ])
         #
-        # @param [ Array<Document> ] docs The docs to replace with.
+        # @param [ Array<Document> | Array<Hash> ] docs The docs to replace with.
         #
         # @return [ Array<Hash> ] The inserts.
         def batch_replace(docs)
@@ -235,7 +235,7 @@ def inserts_valid=(value)
         # @example Normalize the docs.
         #   batchable.normalize_docs(docs)
         #
-        # @param [ Array<Hash | Document> ] docs The docs to normalize.
+        # @param [ Array<Document> | Array<Hash> ] docs The docs to normalize.
         #
         # @return [ Array<Document> ] The docs.
         def normalize_docs(docs)

lib/mongoid/association/embedded/embedded_in/buildable.rb

@@ -15,8 +15,8 @@ module Buildable
           # @example Build the document.
           #   Builder.new(meta, attrs).build
           #
-          # @param [ Object ] base The object.
-          # @param [ Object ] object The parent hash or document.
+          # @param [ Document ] base The object.
+          # @param [ Document | Hash ] object The parent hash or document.
           # @param [ String ] type Not used in this context.
           # @param [ Hash ] selected_fields Fields which were retrieved via
           #   #only. If selected_fields are specified, fields not listed in it

lib/mongoid/association/embedded/embedded_in/proxy.rb

@@ -30,7 +30,7 @@ def initialize(base, target, association)
           # @example Substitute the new document.
           #   person.name.substitute(new_name)
           #
-          # @param [ Document ] replacement A document to replace the target.
+          # @param [ Document | Hash ] replacement A document to replace the target.
           #
           # @return [ Document | nil ] The association or nil.
           def substitute(replacement)
@@ -40,6 +40,7 @@ def substitute(replacement)
               return nil
             end
             _base.new_record = true
+            replacement = Factory.build(klass, replacement) if replacement.is_a?(::Hash)
             self._target = replacement
             bind_one
             self

lib/mongoid/association/embedded/embeds_many/buildable.rb

@@ -17,8 +17,9 @@ module Buildable
           # @example Build the documents.
           #   Builder.new(meta, attrs).build
           #
-          # @param [ Object ] base The base object.
-          # @param [ Object ] object The object to use to build the association.
+          # @param [ Document ] base The base object.
+          # @param [ Array<Document> | Array<Hash> ] object The object to use
+          #   to build the association.
           # @param [ String ] type Not used in this context.
           # @param [ Hash ] selected_fields Fields which were retrieved via
           #   #only. If selected_fields are specified, fields not listed in it

lib/mongoid/association/embedded/embeds_many/proxy.rb

@@ -332,7 +332,7 @@ def shift(count = nil)
           # @example Substitute the association's target.
           #   person.addresses.substitute([ address ])
           #
-          # @param [ Array<Document> ] docs The replacement docs.
+          # @param [ Array<Document> | Array<Hash> ] docs The replacement docs.
           #
           # @return [ Many ] The proxied association.
           def substitute(docs)

lib/mongoid/association/embedded/embeds_one/buildable.rb

@@ -17,7 +17,7 @@ module Buildable
           #   Builder.new(meta, attrs).build
           #
           # @param [ Document ] base The document this association hangs off of.
-          # @param [ Document ] object The related document.
+          # @param [ Document | Hash ] object The related document.
           # @param [ String ] _type Not used in this context.
           # @param [ Hash ] selected_fields Fields which were retrieved via
           #   #only. If selected_fields are specified, fields not listed in it

lib/mongoid/association/embedded/embeds_one/proxy.rb

@@ -43,7 +43,7 @@ def initialize(base, target, association)
           # @example Substitute the new document.
           #   person.name.substitute(new_name)
           #
-          # @param [ Document ] replacement A document to replace the target.
+          # @param [ Document | Hash ] replacement A document to replace the target.
           #
           # @return [ Document | nil ] The association or nil.
           def substitute(replacement)

spec/mongoid/association/embedded/embedded_in/proxy_spec.rb

@@ -616,4 +616,31 @@
       end
     end
   end
+
+  context "when assigning a hash" do
+    let(:building_address) { BuildingAddress.new }
+
+    before do
+      building_address.building = { name: "Chrysler" }
+    end
+
+    it "creates the objects correctly" do
+      expect(building_address.building).to be_a(Building)
+      expect(building_address.building.name).to eq("Chrysler")
+    end
+  end
+
+  context "when replacing an association with a hash" do
+    let(:building_address) { BuildingAddress.new }
+
+    before do
+      building_address.building = { name: "Chrysler" }
+      building_address.building = { name: "Empire State" }
+    end
+
+    it "creates the objects correctly" do
+      expect(building_address.building).to be_a(Building)
+      expect(building_address.building.name).to eq("Empire State")
+    end
+  end
 end