mongoid 7.2.1 → 9.0.0

data/lib/mongoid/association/macros.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
-
     # This module contains the core macros for defining associations between
     # documents. They can be either embedded or referenced.
     module Macros
@@ -13,9 +11,38 @@ 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
+
+        # @return [ Set<String> ] The set of associations that are configured
+        #   with :store_as parameter.
+        class_attribute :stored_as_associations
+
         self.embedded = false
         self.embedded_relations = BSON::Document.new
         self.relations = BSON::Document.new
+        self.aliased_associations = {}
+        self.stored_as_associations = Set.new
       end
 
       # This is convenience for libraries still on the old API.
@@ -24,14 +51,12 @@ module Mongoid
       #   person.associations
       #
       # @return [ Hash ] The associations.
-      #
-      # @since 2.3.1
       def associations
-        self.relations
+        relations
       end
 
+      # Class methods for associations.
       module ClassMethods
-
         # 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 association calling
@@ -51,7 +76,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embedded_in(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -74,7 +99,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -97,7 +122,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -119,11 +144,13 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def belongs_to(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
+        # rubocop:disable Naming/PredicateName
+
         # Adds a referenced association from a parent Document to many
         # Documents in another database or collection.
         #
@@ -141,7 +168,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -163,9 +190,7 @@ module Mongoid
         #
         # @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
+        # @param &block Optional block for defining extensions.
         def has_and_belongs_to_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -187,17 +212,23 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
+        # rubocop:enable Naming/PredicateName
+
         private
 
         def define_association!(macro_name, name, options = {}, &block)
           Association::MACRO_MAPPING[macro_name].new(self, name, options, &block).tap do |assoc|
             assoc.setup!
-            self.relations = self.relations.merge(name => assoc)
+            self.relations = relations.merge(name => assoc)
+            if assoc.embedded? && assoc.respond_to?(:store_as) && assoc.store_as != name
+              aliased_associations[assoc.store_as] = name
+              stored_as_associations << assoc.store_as
+            end
           end
         end
       end

data/lib/mongoid/association/many.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -18,9 +18,7 @@ module Mongoid
       # @example Is the association empty??
       #   person.addresses.blank?
       #
-      # @return [ true, false ] If the association is empty or not.
-      #
-      # @since 2.1.0
+      # @return [ true | false ] If the association is empty or not.
       def blank?
         !any?
       end
@@ -31,13 +29,10 @@ module Mongoid
       # @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) }
@@ -61,13 +56,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
@@ -123,8 +121,6 @@ module Mongoid
       #   relation.nil?
       #
       # @return [ false ] Always false.
-      #
-      # @since 2.0.0
       def nil?
         false
       end
@@ -135,11 +131,9 @@ 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
@@ -151,8 +145,6 @@ module Mongoid
       #   relation.scoped
       #
       # @return [ Criteria ] The scoped criteria.
-      #
-      # @since 2.1.0
       def scoped
         criteria
       end
@@ -166,13 +158,11 @@ module Mongoid
       #
       # @param [ Hash ] options The options to pass.
       #
-      # @option options [ Symbol ] :include What associations 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
@@ -184,8 +174,6 @@ module Mongoid
       #   person.addresses.unscoped
       #
       # @return [ Criteria ] The unscoped criteria.
-      #
-      # @since 2.4.0
       def unscoped
         criteria.unscoped
       end

data/lib/mongoid/association/marshalable.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
+
+    # Mixin module for Mongoid::Association::Proxy which adds
+    # custom Marshal.dump functionality.
     module Marshalable
 
       # Provides the data needed to Marshal.dump an association proxy.
@@ -11,8 +14,6 @@ module Mongoid
       #   Marshal.dump(proxy)
       #
       # @return [ Array<Object> ] The dumped data.
-      #
-      # @since 3.0.15
       def marshal_dump
         [ _base, _target, _association ]
       end
@@ -25,8 +26,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,9 +1,12 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Builder class used to perform #accepts_nested_attributes_for
+      # attribute assignment on many-to-n associations.
       class Many
         include Buildable
 
@@ -41,7 +44,7 @@ module Mongoid
         # @example Initialize the builder.
         #   Many.new(association, attributes, options)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         # @param [ Hash ] attributes The attributes hash to attempt to set.
         # @param [ Hash ] options The options defined.
         def initialize(association, attributes, options = {})
@@ -66,7 +69,7 @@ module Mongoid
         #
         # @param [ Hash ] attributes The attributes to pull the flag from.
         #
-        # @return [ true, false ] If the association 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?
@@ -80,7 +83,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
@@ -96,11 +99,10 @@ 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
+
+          if (id = extract_id(attrs))
             update_nested_relation(parent, id, attrs)
           else
             existing.push(Factory.build(@class_name, attrs)) unless destroyable?(attrs)
@@ -118,8 +120,6 @@ module Mongoid
         # @param [ Document ] parent The parent document.
         # @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?
@@ -138,11 +138,10 @@ module Mongoid
         #
         # @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.
@@ -154,10 +153,8 @@ 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
+          delete_id(attrs)
           if association.embedded?
             doc.assign_attributes(attrs)
           else
@@ -173,15 +170,13 @@ module Mongoid
         #   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?
+          if existing.where(_id: converted).exists?
             # document exists in association
             doc = existing.find(converted)
             if destroyable?(attrs)

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

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Mixin module containing common functionality used to
+      # perform #accepts_nested_attributes_for attribute assignment
+      # on associations.
       module Buildable
 
         attr_accessor :attributes, :existing, :association, :options
@@ -13,9 +17,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
@@ -28,9 +30,7 @@ module Mongoid
         # @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
@@ -48,9 +48,7 @@ module Mongoid
         # @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
@@ -63,12 +61,37 @@ 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
+
+        private
+
+        # Get the id attribute from the given hash, whether it's
+        # prefixed with an underscore or is a symbol.
+        #
+        # @example Get the id.
+        #   extract_id({ _id: 1 })
+        #
+        # @param [ Hash ] hash The hash from which to extract.
+        #
+        # @return [ Object ] The value of the id.
+        def extract_id(hash)
+          hash['_id'] || hash[:_id] || hash['id'] || hash[:id]
+        end
+
+        # Deletes the id key from the given hash.
+        #
+        # @example Delete an id value.
+        #   delete_id({ "_id" => 1 })
+        #
+        # @param [ Hash ] hash The hash from which to delete.
+        #
+        # @return [ Object ] The deleted value, or nil.
+        def delete_id(hash)
+          hash.delete('_id') || hash.delete(:_id) || hash.delete('id') || hash.delete(:id)
+        end
       end
     end
   end

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

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Builder class used to perform #accepts_nested_attributes_for
+      # attribute assignment on one-to-n associations.
       class One
         include Buildable
 
         attr_accessor :destroy
 
-
         # Builds the association depending on the attributes and the options
         # passed to the macro.
         #
@@ -23,18 +25,18 @@ module Mongoid
         # @param [ Document ] parent The parent document.
         #
         # @return [ Document ] The built document.
-        #
-        # @since 2.0.0
         def build(parent)
           return if reject?(parent, attributes)
           @existing = parent.send(association.name)
           if update?
-            attributes.delete_id
+            delete_id(attributes)
             existing.assign_attributes(attributes)
           elsif replace?
             parent.send(association.setter, Factory.build(@class_name, attributes))
           elsif delete?
             parent.send(association.setter, nil)
+          else
+            check_for_id_violation!
           end
         end
 
@@ -44,11 +46,9 @@ module Mongoid
         # @example Instantiate the builder.
         #   One.new(association, attributes)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         # @param [ Hash ] attributes The attributes hash to attempt to set.
         # @param [ Hash ] options The options defined.
-        #
-        # @since 2.0.0
         def initialize(association, attributes, options)
           @attributes = attributes.with_indifferent_access
           @association = association
@@ -59,7 +59,18 @@ module Mongoid
 
         private
 
-        # Is the id in the attribtues acceptable for allowing an update to
+        # Extracts and converts the id to the expected type.
+        #
+        # @return [ BSON::ObjectId | String | Object | nil ] The converted id,
+        #   or nil if no id is present in the attributes hash.
+        def extracted_id
+          @extracted_id ||= begin
+            id = association.klass.extract_id_field(attributes)
+            convert_id(existing.class, id)
+          end
+        end
+
+        # Is the id in the attributes acceptable for allowing an update to
         # the existing association?
         #
         # @api private
@@ -67,11 +78,9 @@ module Mongoid
         # @example Is the id acceptable?
         #   one.acceptable_id?
         #
-        # @return [ true, false ] If the id part of the logic will allow an update.
-        #
-        # @since 2.0.0
+        # @return [ true | false ] If the id part of the logic will allow an update.
         def acceptable_id?
-          id = convert_id(existing.class, attributes[:id])
+          id = extracted_id
           existing._id == id || id.nil? || (existing._id != id && update_only?)
         end
 
@@ -80,11 +89,10 @@ module Mongoid
         # @example Can the existing object be deleted?
         #   one.delete?
         #
-        # @return [ true, false ] If the association should be deleted.
-        #
-        # @since 2.0.0
+        # @return [ true | false ] If the association should be deleted.
         def delete?
-          destroyable? && !attributes[:id].nil?
+          id = association.klass.extract_id_field(attributes)
+          destroyable? && !id.nil?
         end
 
         # Can the existing association potentially be destroyed?
@@ -92,10 +100,8 @@ module Mongoid
         # @example Is the object destroyable?
         #   one.destroyable?({ :_destroy => "1" })
         #
-        # @return [ true, false ] If the association can potentially be
+        # @return [ true | false ] If the association can potentially be
         #   destroyed.
-        #
-        # @since 2.0.0
         def destroyable?
           Nested::DESTROY_FLAGS.include?(destroy) && allow_destroy?
         end
@@ -105,9 +111,7 @@ module Mongoid
         # @example Is the document to be replaced?
         #   one.replace?
         #
-        # @return [ true, false ] If the document should be replaced.
-        #
-        # @since 2.0.0
+        # @return [ true | false ] If the document should be replaced.
         def replace?
           !existing && !destroyable? && !attributes.blank?
         end
@@ -117,12 +121,36 @@ module Mongoid
         # @example Should the document be updated?
         #   one.update?
         #
-        # @return [ true, false ] If the object should have its attributes updated.
-        #
-        # @since 2.0.0
+        # @return [ true | false ] If the object should have its attributes updated.
         def update?
           existing && !destroyable? && acceptable_id?
         end
+
+        # Checks to see if the _id attribute (which is supposed to be
+        # immutable) is being asked to change. If so, raise an exception.
+        #
+        # If Mongoid::Config.immutable_ids is false, this will do nothing,
+        # and the update operation will fail silently.
+        #
+        # @raise [ Errors::ImmutableAttribute ] if _id has changed, and
+        #   the document has been persisted.
+        def check_for_id_violation!
+          # look for the basic criteria of an update (see #update?)
+          return unless existing&.persisted? && !destroyable?
+
+          # if the id is either absent, or if it equals the existing record's
+          # id, there is no immutability violation.
+          id = extracted_id
+          return if existing._id == id || id.nil?
+
+          # otherwise, an attempt has been made to set the _id of an existing,
+          # persisted document.
+          if Mongoid::Config.immutable_ids
+            raise Errors::ImmutableAttribute.new(:_id, id)
+          else
+            Mongoid::Warnings.warn_mutable_ids
+          end
+        end
       end
     end
   end

data/lib/mongoid/association/nested.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/nested/nested_buildable'
 require 'mongoid/association/nested/many'
@@ -10,8 +10,6 @@ module Mongoid
     module Nested
 
       # The flags indicating that an association can be destroyed.
-      #
-      # @since 7.0
       DESTROY_FLAGS = [1, "1", true, "true"].freeze
     end
   end