mongoid 7.0.2 → 8.1.1

data/lib/mongoid/association/macros.rb

@@ -1,9 +1,10 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
 
-    # This module contains the core macros for defining relations between
-    # documents. They can be either embedded or referenced (relational).
+    # This module contains the core macros for defining associations between
+    # documents. They can be either embedded or referenced.
     module Macros
       extend ActiveSupport::Concern
 
@@ -11,9 +12,33 @@ module Mongoid
         class_attribute :embedded, instance_reader: false
         class_attribute :embedded_relations
         class_attribute :relations
+
+        # A hash that maps aliases to their associations. This hash maps the
+        # associations "in database name" to its "in code" name. This is used when
+        # associations specify the `store_as` option, or on a referenced association.
+        # On a referenced association, this is used to map the foreign key to
+        # the association's name. For example, if we had the following
+        # relationship:
+        #
+        #   User has_many Accounts
+        #
+        # User will have an entry in the aliased associations hash:
+        #
+        #   account_ids => accounts
+        #
+        # Note that on the belongs_to associations, the mapping from
+        # foreign key => name is not in the aliased_associations hash, but a
+        # mapping from name => foreign key is in the aliased_fields hash.
+        #
+        # @return [ Hash<String, String> ] The aliased associations hash.
+        #
+        # @api private
+        class_attribute :aliased_associations
+
         self.embedded = false
         self.embedded_relations = BSON::Document.new
         self.relations = BSON::Document.new
+        self.aliased_associations = {}
       end
 
       # This is convenience for libraries still on the old API.
@@ -21,21 +46,19 @@ module Mongoid
       # @example Get the associations.
       #   person.associations
       #
-      # @return [ Hash ] The relations.
-      #
-      # @since 2.3.1
+      # @return [ Hash ] The associations.
       def associations
         self.relations
       end
 
       module ClassMethods
 
-        # Adds the relation back to the parent document. This macro is
+        # Adds the association back to the parent document. This macro is
         # necessary to set the references from the child back to the parent
-        # document. If a child does not define this relation calling
+        # document. If a child does not define this association calling
         # persistence methods on the child object will cause a save to fail.
         #
-        # @example Define the relation.
+        # @example Define the association.
         #
         #   class Person
         #     include Mongoid::Document
@@ -47,18 +70,18 @@ module Mongoid
         #     embedded_in :person
         #   end
         #
-        # @param [ Symbol ] name The name of the relation.
-        # @param [ Hash ] options The relation options.
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
         # @param [ Proc ] block Optional block for defining extensions.
         def embedded_in(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
-        # Adds the relation from a parent document to its children. The name
-        # of the relation needs to be a pluralized form of the child class
+        # Adds the association from a parent document to its children. The name
+        # of the association needs to be a pluralized form of the child class
         # name.
         #
-        # @example Define the relation.
+        # @example Define the association.
         #
         #   class Person
         #     include Mongoid::Document
@@ -70,18 +93,18 @@ module Mongoid
         #     embedded_in :person
         #   end
         #
-        # @param [ Symbol ] name The name of the relation.
-        # @param [ Hash ] options The relation options.
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
         # @param [ Proc ] block Optional block for defining extensions.
         def embeds_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
-        # Adds the relation from a parent document to its child. The name
-        # of the relation needs to be a singular form of the child class
+        # Adds the association from a parent document to its child. The name
+        # of the association needs to be a singular form of the child class
         # name.
         #
-        # @example Define the relation.
+        # @example Define the association.
         #
         #   class Person
         #     include Mongoid::Document
@@ -93,17 +116,17 @@ module Mongoid
         #     embedded_in :person
         #   end
         #
-        # @param [ Symbol ] name The name of the relation.
-        # @param [ Hash ] options The relation options.
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
         # @param [ Proc ] block Optional block for defining extensions.
         def embeds_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
-        # Adds a relational association from the child Document to a Document in
-        # another database or collection.
+        # Adds a referenced association from the child Document to a Document
+        # in another database or collection.
         #
-        # @example Define the relation.
+        # @example Define the association.
         #
         #   class Game
         #     include Mongoid::Document
@@ -115,17 +138,17 @@ module Mongoid
         #     has_one :game
         #   end
         #
-        # @param [ Symbol ] name The name of the relation.
-        # @param [ Hash ] options The relation options.
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
         # @param [ Proc ] block Optional block for defining extensions.
         def belongs_to(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
-        # Adds a relational association from a parent Document to many
+        # Adds a referenced association from a parent Document to many
         # Documents in another database or collection.
         #
-        # @example Define the relation.
+        # @example Define the association.
         #
         #   class Person
         #     include Mongoid::Document
@@ -137,17 +160,17 @@ module Mongoid
         #     belongs_to :person
         #   end
         #
-        # @param [ Symbol ] name The name of the relation.
-        # @param [ Hash ] options The relation options.
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
         # @param [ Proc ] block Optional block for defining extensions.
         def has_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
-        # Adds a relational many-to-many association between many of this
+        # Adds a referenced many-to-many association between many of this
         # Document and many of another Document.
         #
-        # @example Define the relation.
+        # @example Define the association.
         #
         #   class Person
         #     include Mongoid::Document
@@ -159,19 +182,17 @@ module Mongoid
         #     has_and_belongs_to_many :people
         #   end
         #
-        # @param [ Symbol ] name The name of the relation.
-        # @param [ Hash ] options The relation options.
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
         # @param [ Proc ] block Optional block for defining extensions.
-        #
-        # @since 2.0.0.rc.1
         def has_and_belongs_to_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
-        # Adds a relational association from the child Document to a Document in
-        # another database or collection.
+        # Adds a referenced association from the child Document to a Document
+        # in another database or collection.
         #
-        # @example Define the relation.
+        # @example Define the association.
         #
         #   class Game
         #     include Mongoid::Document
@@ -183,8 +204,8 @@ module Mongoid
         #     has_one :game
         #   end
         #
-        # @param [ Symbol ] name The name of the relation.
-        # @param [ Hash ] options The relation options.
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
         # @param [ Proc ] block Optional block for defining extensions.
         def has_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
@@ -196,6 +217,9 @@ module Mongoid
           Association::MACRO_MAPPING[macro_name].new(self, name, options, &block).tap do |assoc|
             assoc.setup!
             self.relations = self.relations.merge(name => assoc)
+            if assoc.embedded? && assoc.respond_to?(:store_as) && assoc.store_as != name
+              self.aliased_associations[assoc.store_as] = name
+            end
           end
         end
       end

data/lib/mongoid/association/many.rb

@@ -1,40 +1,37 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
 
-    # This is the superclass for all many to one and many to many relation
+    # This is the superclass for all many to one and many to many association
     # proxies.
     class Many < Association::Proxy
+      extend Forwardable
       include ::Enumerable
 
-      delegate :avg, :max, :min, :sum, to: :criteria
-      delegate :length, :size, to: :_target
+      def_delegators :criteria, :avg, :max, :min, :sum
+      def_delegators :_target, :length, :size, :any?
 
-      # Is the relation empty?
+      # Is the association empty?
       #
-      # @example Is the relation empty??
+      # @example Is the association empty??
       #   person.addresses.blank?
       #
-      # @return [ true, false ] If the relation is empty or not.
-      #
-      # @since 2.1.0
+      # @return [ true | false ] If the association is empty or not.
       def blank?
-        size == 0
+        !any?
       end
 
-      # Creates a new document on the references many relation. This will
+      # Creates a new document on the references many association. This will
       # save the document if the parent has been persisted.
       #
       # @example Create and save the new document.
       #   person.posts.create(:text => "Testing")
       #
-      #
       # @param [ Hash ] attributes The attributes to create with.
       # @param [ Class ] type The optional type of document to create.
       #
       # @return [ Document ] The newly created document.
-      #
-      # @since 2.0.0.beta.1
       def create(attributes = nil, type = nil, &block)
         if attributes.is_a?(::Array)
           attributes.map { |attrs| create(attrs, type, &block) }
@@ -45,7 +42,7 @@ module Mongoid
         end
       end
 
-      # Creates a new document on the references many relation. This will
+      # Creates a new document on the references many association. This will
       # save the document if the parent has been persisted and will raise an
       # error if validation fails.
       #
@@ -58,13 +55,16 @@ module Mongoid
       # @raise [ Errors::Validations ] If validation failed.
       #
       # @return [ Document ] The newly created document.
-      #
-      # @since 2.0.0.beta.1
       def create!(attributes = nil, type = nil, &block)
         if attributes.is_a?(::Array)
           attributes.map { |attrs| create!(attrs, type, &block) }
         else
           doc = build(attributes, type, &block)
+
+          Array(doc).each do |doc|
+            doc.try(:run_pending_callbacks)
+          end
+
           _base.persisted? ? doc.save! : raise_unsaved(doc)
           doc
         end
@@ -120,8 +120,6 @@ module Mongoid
       #   relation.nil?
       #
       # @return [ false ] Always false.
-      #
-      # @since 2.0.0
       def nil?
         false
       end
@@ -132,24 +130,20 @@ module Mongoid
       #   relation.respond_to?(:name)
       #
       # @param [ Symbol ] name The method name.
-      # @param [ true, false ] include_private Whether to include private methods.
-      #
-      # @return [ true, false ] If the proxy responds to the method.
+      # @param [ true | false ] include_private Whether to include private methods.
       #
-      # @since 2.0.0
+      # @return [ true | false ] If the proxy responds to the method.
       def respond_to?(name, include_private = false)
         [].respond_to?(name, include_private) ||
           klass.respond_to?(name, include_private) || super
       end
 
-      # This is public access to the relation's criteria.
+      # This is public access to the association's criteria.
       #
-      # @example Get the scoped relation.
+      # @example Get the scoped association.
       #   relation.scoped
       #
       # @return [ Criteria ] The scoped criteria.
-      #
-      # @since 2.1.0
       def scoped
         criteria
       end
@@ -163,13 +157,11 @@ module Mongoid
       #
       # @param [ Hash ] options The options to pass.
       #
-      # @option options [ Symbol ] :include What relations to include
-      # @option options [ Symbol ] :only Limit the fields to only these.
-      # @option options [ Symbol ] :except Dont include these fields.
+      # @option options [ Symbol | String | Array<Symbol | String> ] :except Do not include these field(s).
+      # @option options [ Symbol | String | Array<Symbol | String> ] :include Which association(s) to include.
+      # @option options [ Symbol | String | Array<Symbol | String> ] :only Limit the field(s) to only these.
       #
       # @return [ Hash ] The documents, ready to be serialized.
-      #
-      # @since 2.0.0.rc.6
       def serializable_hash(options = {})
         _target.map { |document| document.serializable_hash(options) }
       end
@@ -181,8 +173,6 @@ module Mongoid
       #   person.addresses.unscoped
       #
       # @return [ Criteria ] The unscoped criteria.
-      #
-      # @since 2.4.0
       def unscoped
         criteria.unscoped
       end
@@ -204,7 +194,7 @@ module Mongoid
       #
       # @return [ Document ] A matching document or a new/created one.
       def find_or(method, attrs = {}, type = nil, &block)
-        attrs["_type"] = type.to_s if type
+        attrs[klass.discriminator_key] = type.discriminator_value if type
         where(attrs).first || send(method, attrs, type, &block)
       end
     end

data/lib/mongoid/association/marshalable.rb

@@ -1,16 +1,15 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Marshalable
 
-      # Provides the data needed to Marshal.dump a relation proxy.
+      # Provides the data needed to Marshal.dump an association proxy.
       #
       # @example Dump the proxy.
       #   Marshal.dump(proxy)
       #
       # @return [ Array<Object> ] The dumped data.
-      #
-      # @since 3.0.15
       def marshal_dump
         [ _base, _target, _association ]
       end
@@ -23,8 +22,6 @@ module Mongoid
       # @param [ Array<Object> ] data The data to set on the proxy.
       #
       # @return [ Array<Object> ] The loaded data.
-      #
-      # @since 3.0.15
       def marshal_load(data)
         @_base, @_target, @_association = data
         extend_proxy(_association.extension) if _association.extension

data/lib/mongoid/association/nested/many.rb

@@ -1,21 +1,22 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Nested
       class Many
         include Buildable
 
-        # Builds the relation depending on the attributes and the options
+        # Builds the association depending on the attributes and the options
         # passed to the macro.
         #
         # This attempts to perform 3 operations, either one of an update of
-        # the existing relation, a replacement of the relation with a new
-        # document, or a removal of the relation.
+        # the existing association, a replacement of the association with a new
+        # document, or a removal of the association.
         #
         # @example Build the nested attrs.
         #   many.build(person)
         #
-        # @param [ Document ] parent The parent document of the relation.
+        # @param [ Document ] parent The parent document of the association.
         # @param [ Hash ] options The options.
         #
         # @return [ Array ] The attributes.
@@ -34,7 +35,7 @@ module Mongoid
         end
 
         # Create the new builder for nested attributes on one-to-many
-        # relations.
+        # associations.
         #
         # @example Initialize the builder.
         #   Many.new(association, attributes, options)
@@ -57,14 +58,14 @@ module Mongoid
 
         private
 
-        # Can the existing relation potentially be deleted?
+        # Can the existing association potentially be deleted?
         #
         # @example Is the document destroyable?
         #   destroyable?({ :_destroy => "1" })
         #
         # @param [ Hash ] attributes The attributes to pull the flag from.
         #
-        # @return [ true, false ] If the relation can potentially be deleted.
+        # @return [ true | false ] If the association can potentially be deleted.
         def destroyable?(attributes)
           destroy = attributes.delete(:_destroy)
           Nested::DESTROY_FLAGS.include?(destroy) && allow_destroy?
@@ -78,7 +79,7 @@ module Mongoid
         #
         # @param [ Hash ] attributes The attributes being set.
         #
-        # @return [ true, false ] If the attributes exceed the limit.
+        # @return [ true | false ] If the attributes exceed the limit.
         def over_limit?(attributes)
           limit = options[:limit]
           limit ? attributes.size > limit : false
@@ -94,8 +95,6 @@ module Mongoid
         #
         # @param [ Document ] parent The parent document.
         # @param [ Hash ] attrs The single document attributes to process.
-        #
-        # @since 2.0.0
         def process_attributes(parent, attrs)
           return if reject?(parent, attrs)
           if id = attrs.extract_id
@@ -106,7 +105,7 @@ module Mongoid
         end
 
         # Destroy the child document, needs to do some checking for embedded
-        # relations and delay the destroy in case parent validation fails.
+        # associations and delay the destroy in case parent validation fails.
         #
         # @api private
         #
@@ -114,10 +113,8 @@ module Mongoid
         #   builder.destroy(parent, relation, doc)
         #
         # @param [ Document ] parent The parent document.
-        # @param [ Proxy ] relation The relation proxy.
+        # @param [ Proxy ] relation The association proxy.
         # @param [ Document ] doc The doc to destroy.
-        #
-        # @since 3.0.10
         def destroy(parent, relation, doc)
           doc.flagged_for_destroy = true
           if !doc.embedded? || parent.new_record?
@@ -134,13 +131,12 @@ module Mongoid
         # @example Destroy the document.
         #   builder.destroy_document(relation, doc)
         #
-        # @param [ Proxy ] relation The relation proxy.
+        # @param [ Proxy ] relation The association proxy.
         # @param [ Document ] doc The document to delete.
-        #
-        # @since 3.0.10
         def destroy_document(relation, doc)
+          res = doc.destroy unless doc.embedded? || doc.destroyed?
           relation.delete(doc)
-          doc.destroy unless doc.embedded? || doc.destroyed?
+          res
         end
 
         # Update the document.
@@ -152,8 +148,6 @@ module Mongoid
         #
         # @param [ Document ] doc The document to update.
         # @param [ Hash ] attrs The attributes.
-        #
-        # @since 3.0.10
         def update_document(doc, attrs)
           attrs.delete_id
           if association.embedded?
@@ -163,24 +157,22 @@ module Mongoid
           end
         end
 
-        # Update nested relation.
+        # Update nested association.
         #
         # @api private
         #
-        # @example Update nested relation.
+        # @example Update nested association.
         #   builder.update_nested_relation(parent, id, attrs)
         #
         # @param [ Document ] parent The parent document.
-        # @param [ String, BSON::ObjectId ] id of the related document.
+        # @param [ String | BSON::ObjectId ] id of the related document.
         # @param [ Hash ] attrs The single document attributes to process.
-        #
-        # @since 6.0.0
         def update_nested_relation(parent, id, attrs)
           first = existing.first
           converted = first ? convert_id(first.class, id) : id
 
-          if existing.where(id: converted).exists?
-            # document exists in relation
+          if existing.where(_id: converted).exists?
+            # document exists in association
             doc = existing.find(converted)
             if destroyable?(attrs)
               destroy(parent, existing, doc)
@@ -188,8 +180,8 @@ module Mongoid
               update_document(doc, attrs)
             end
           else
-            # push existing document to relation
-            doc = existing.unscoped.find(converted)
+            # push existing document to association
+            doc = association.klass.unscoped.find(converted)
             update_document(doc, attrs)
             existing.push(doc) unless destroyable?(attrs)
           end

data/lib/mongoid/association/nested/nested_buildable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Nested
@@ -10,9 +12,7 @@ module Mongoid
         # @example Do we allow a destroy?
         #   builder.allow_destroy?
         #
-        # @return [ true, false ] True if the allow destroy option was set.
-        #
-        # @since 2.0.0.rc.1
+        # @return [ true | false ] True if the allow destroy option was set.
         def allow_destroy?
           options[:allow_destroy] || false
         end
@@ -22,12 +22,10 @@ module Mongoid
         # @example Is there a reject proc?
         #   builder.reject?
         #
-        # @param [ Document ] document The parent document of the relation
+        # @param [ Document ] document The parent document of the association
         # @param [ Hash ] attrs The attributes to check for rejection.
         #
-        # @return [ true, false ] True and call proc or method if rejectable, false if not.
-        #
-        # @since 2.0.0.rc.1
+        # @return [ true | false ] True and call proc or method if rejectable, false if not.
         def reject?(document, attrs)
           case callback = options[:reject_if]
             when Symbol
@@ -40,14 +38,12 @@ module Mongoid
         end
 
         # Determines if only updates can occur. Only valid for one-to-one
-        # relations.
+        # associations.
         #
         # @example Is this update only?
         #   builder.update_only?
         #
-        # @return [ true, false ] True if the update_only option was set.
-        #
-        # @since 2.0.0.rc.1
+        # @return [ true | false ] True if the update_only option was set.
         def update_only?
           options[:update_only] || false
         end
@@ -60,13 +56,11 @@ module Mongoid
         # @param [ Class ] klass The class we're trying to convert for.
         # @param [ String ] id The id, usually coming from the form.
         #
-        # @return [ BSON::ObjectId, String, Object ] The converted id.
-        #
-        # @since 2.0.0.rc.6
+        # @return [ BSON::ObjectId | String | Object ] The converted id.
         def convert_id(klass, id)
           klass.using_object_ids? ? BSON::ObjectId.mongoize(id) : id
         end
       end
     end
   end
-end
+end