mongoid 7.2.1 → 9.0.0

data/lib/mongoid/association/referenced/has_and_belongs_to_many/proxy.rb

@@ -1,14 +1,42 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
     module Referenced
       class HasAndBelongsToMany
-
-        # This class defines the behavior for all associations that are a
-        # many-to-many between documents in different collections.
+        # Transparent proxy for has_and_belongs_to_many associations.
+        # An instance of this class is returned when calling
+        # the association getter method on the subject document.
+        # This class inherits from Mongoid::Association::Proxy and
+        # forwards most of its methods to the target of the association,
+        # i.e. the array of documents on the opposite-side collection
+        # which must be loaded.
         class Proxy < Referenced::HasMany::Proxy
+          # class-level methods for HasAndBelongsToMany::Proxy
+          module ClassMethods
+            # Get the Eager object for this type of association.
+            #
+            # @example Get the eager loader object
+            #
+            # @param [ Mongoid::Association::Relatable ] association The association metadata.
+            # @param [ Array<Document> ] docs The array of documents.
+            def eager_loader(association, docs)
+              Eager.new(association, docs)
+            end
+
+            # Returns true if the association is an embedded one. In this case
+            # always false.
+            #
+            # @example Is this association embedded?
+            #   Referenced::ManyToMany.embedded?
+            #
+            # @return [ false ] Always false.
+            def embedded?
+              false
+            end
+          end
+
+          extend ClassMethods
 
           # Appends a document or array of documents to the association. Will set
           # the parent and update the index in the process.
@@ -22,25 +50,48 @@ module Mongoid
           # @example Concat with other documents.
           #   person.posts.concat([ post_one, post_two ])
           #
-          # @param [ Document, Array<Document> ] args Any number of documents.
+          # @param [ Document... ] *args Any number of documents.
           #
           # @return [ Array<Document> ] The loaded docs.
           #
-          # @since 2.0.0.beta.1
+          # rubocop:disable Metrics/AbcSize
           def <<(*args)
             docs = args.flatten
             return concat(docs) if docs.size > 1
-            if doc = docs.first
-              append(doc)
-              _base.add_to_set(foreign_key => doc.send(_association.primary_key))
-              if child_persistable?(doc)
-                doc.save
+
+            if (doc = docs.first)
+              append(doc) do
+                # We ignore the changes to the value for the foreign key in the
+                # changed_attributes hash in this block of code for two reasons:
+                #
+                # 1) The add_to_set method deletes the value for the foreign
+                #    key in the changed_attributes hash, but if we enter this
+                #    method with a value for the foreign key in the
+                #    changed_attributes hash, then we want it to exist outside
+                #    this method as well. It's used later on in the Syncable
+                #    module to set the inverse foreign keys.
+                # 2) The reset_unloaded method accesses the value for the foreign
+                #    key on _base, which causes it to get added to the
+                #    changed_attributes hash. This happens because when reading
+                #    a "resizable" attribute, it is automatically added to the
+                #    changed_attributes hash. This is true only for the foreign
+                #    key value for HABTM associations as the other associations
+                #    use strings for their foreign key values. For consistency
+                #    with the other associations, we ignore this addition to
+                #    the changed_attributes hash.
+                #    See MONGOID-4843 for a longer discussion about this.
+                reset_foreign_key_changes do
+                  _base.add_to_set(foreign_key => doc.public_send(_association.primary_key))
+                  doc.save if child_persistable?(doc)
+                  reset_unloaded
+                end
               end
             end
             unsynced(_base, foreign_key) and self
           end
+          # rubocop:enable Metrics/AbcSize
 
-          alias :push :<<
+          alias push <<
 
           # Appends an array of documents to the association. Performs a batch
           # insert of the documents instead of persisting one at a time.
@@ -51,26 +102,10 @@ module Mongoid
           # @param [ Array<Document> ] documents The docs to add.
           #
           # @return [ Array<Document> ] The documents.
-          #
-          # @since 2.4.0
           def concat(documents)
             ids, docs, inserts = {}, [], []
-            documents.each do |doc|
-              next unless doc
-              append(doc)
-              if persistable? || _creating?
-                ids[doc._id] = true
-                save_or_delay(doc, docs, inserts)
-              else
-                existing = _base.send(foreign_key)
-                unless existing.include?(doc._id)
-                  existing.push(doc._id) and unsynced(_base, foreign_key)
-                end
-              end
-            end
-            if persistable? || _creating?
-              _base.push(foreign_key => ids.keys)
-            end
+            documents.each { |doc| append_document(doc, ids, docs, inserts) }
+            _base.push(foreign_key => ids.keys) if persistable? || _creating?
             persist_delayed(docs, inserts)
             self
           end
@@ -85,19 +120,18 @@ module Mongoid
           # @param [ Class ] type The optional subclass to build.
           #
           # @return [ Document ] The new document.
-          #
-          # @since 2.0.0.beta.1
           def build(attributes = {}, type = nil)
-            doc = Factory.build(type || klass, attributes)
-            _base.send(foreign_key).push(doc._id)
+            doc = Factory.execute_build(type || klass, attributes, execute_callbacks: false)
             append(doc)
             doc.apply_post_processed_defaults
+            _base.public_send(foreign_key).push(doc.public_send(_association.primary_key))
             unsynced(doc, inverse_foreign_key)
             yield(doc) if block_given?
+            doc.run_pending_callbacks
             doc
           end
 
-          alias :new :build
+          alias new build
 
           # Delete the document from the association. This will set the foreign key
           # on the document to nil. If the dependent options on the association are
@@ -109,18 +143,20 @@ module Mongoid
           # @param [ Document ] document The document to remove.
           #
           # @return [ Document ] The matching document.
-          #
-          # @since 2.1.0
           def delete(document)
             doc = super
             if doc && persistable?
-              _base.pull(foreign_key => doc.send(_association.primary_key))
+              _base.pull(foreign_key => doc.public_send(_association.primary_key))
               _target._unloaded = criteria
               unsynced(_base, foreign_key)
             end
             doc
           end
 
+          # Mongoid::Extensions::Array defines Array#delete_one, so we need
+          # to make sure that method behaves reasonably on proxies, too.
+          alias delete_one delete
+
           # Removes all associations between the base document and the target
           # documents by deleting the foreign keys and the references, orphaning
           # the target documents in the process.
@@ -129,49 +165,16 @@ module Mongoid
           #   person.preferences.nullify
           #
           # @param [ Array<Document> ] replacement The replacement documents.
-          #
-          # @since 2.0.0.rc.1
           def nullify(replacement = [])
-            _target.each do |doc|
-              execute_callback :before_remove, doc
-            end
-            unless _association.forced_nil_inverse?
-              if field = _association.options[:inverse_primary_key]
-                ipk = _base.send(field)
-              else
-                ipk = _base._id
-              end
-              if replacement
-                objects_to_clear = _base.send(foreign_key) - replacement.collect do |object|
-                  object.send(_association.primary_key)
-                end
-                criteria(objects_to_clear).pull(inverse_foreign_key => ipk)
-              else
-                criteria.pull(inverse_foreign_key => ipk)
-              end
-            end
-            if persistable?
-              _base.set(foreign_key => _base.send(foreign_key).clear)
-            end
-            after_remove_error = nil
-            many_to_many = _target.clear do |doc|
-              unbind_one(doc)
-              unless _association.forced_nil_inverse?
-                doc.changed_attributes.delete(inverse_foreign_key)
-              end
-              begin
-                execute_callback :after_remove, doc
-              rescue => e
-                after_remove_error = e
-              end
-            end
-            raise after_remove_error if after_remove_error
-            many_to_many
+            _target.each { |doc| execute_callback :before_remove, doc }
+            cleanup_inverse_for(replacement) unless _association.forced_nil_inverse?
+            _base.set(foreign_key => _base.public_send(foreign_key).clear) if persistable?
+            clear_target_for_nullify
           end
 
-          alias :nullify_all :nullify
-          alias :clear :nullify
-          alias :purge :nullify
+          alias nullify_all nullify
+          alias clear nullify
+          alias purge nullify
 
           # Substitutes the supplied target documents for the existing documents
           # in the association. If the new target is nil, perform the necessary
@@ -183,14 +186,13 @@ module Mongoid
           # @param [ Array<Document> ] replacement The replacement target.
           #
           # @return [ Many ] The association.
-          #
-          # @since 2.0.0.rc.1
           def substitute(replacement)
             purge(replacement)
-            unless replacement.blank?
-              push(replacement.compact.uniq)
-            else
+            if replacement.blank?
               reset_unloaded
+              clear_foreign_key_changes
+            else
+              push(replacement.compact.uniq)
             end
             self
           end
@@ -202,14 +204,35 @@ module Mongoid
           #   person.preferences.unscoped
           #
           # @return [ Criteria ] The unscoped criteria.
-          #
-          # @since 2.4.0
           def unscoped
-            klass.unscoped.any_in(_id: _base.send(foreign_key))
+            klass.unscoped.any_in(_id: _base.public_send(foreign_key))
           end
 
           private
 
+          # Clears the foreign key from the changed_attributes hash.
+          #
+          # This is, in general, used to clear the foreign key from the
+          # changed_attributes hash for consistency with the other referenced
+          # associations.
+          #
+          # @api private
+          def clear_foreign_key_changes
+            _base.changed_attributes.delete(foreign_key)
+          end
+
+          # Reset the value in the changed_attributes hash for the foreign key
+          # to its value before executing the given block.
+          #
+          # @api private
+          def reset_foreign_key_changes
+            prior_fk_change = _base.changed_attributes.key?(foreign_key)
+            fk = _base.changed_attributes[foreign_key].dup
+            yield if block_given?
+            _base.changed_attributes[foreign_key] = fk
+            clear_foreign_key_changes unless prior_fk_change
+          end
+
           # Appends the document to the target array, updating the index on the
           # document at the same time.
           #
@@ -217,14 +240,13 @@ module Mongoid
           #   relation.append(document)
           #
           # @param [ Document ] document The document to append to the target.
-          #
-          # @since 2.0.0.rc.1
           def append(document)
-            execute_callback :before_add, document
-            _target.push(document)
-            characterize_one(document)
-            bind_one(document)
-            execute_callback :after_add, document
+            execute_callbacks_around(:add, document) do
+              _target.push(document)
+              characterize_one(document)
+              bind_one(document)
+              yield if block_given?
+            end
           end
 
           # Instantiate the binding associated with this association.
@@ -233,8 +255,6 @@ module Mongoid
           #   relation.binding([ address ])
           #
           # @return [ Binding ] The binding.
-          #
-          # @since 2.0.0.rc.1
           def binding
             HasAndBelongsToMany::Binding.new(_base, _target, _association)
           end
@@ -248,12 +268,10 @@ module Mongoid
           #
           # @param [ Document ] doc The document.
           #
-          # @return [ true, false ] If the document can be persisted.
-          #
-          # @since 3.0.20
+          # @return [ true | false ] If the document can be persisted.
           def child_persistable?(doc)
             (persistable? || _creating?) &&
-                !(doc.persisted? && _association.forced_nil_inverse?)
+              !(doc.persisted? && _association.forced_nil_inverse?)
           end
 
           # Returns the criteria object for the target class with its documents set
@@ -278,40 +296,90 @@ module Mongoid
           # @param [ Symbol ] key The key to flag on the document.
           #
           # @return [ true ] true.
-          #
-          # @since 3.0.0
           def unsynced(doc, key)
             doc._synced[key] = false
             true
           end
 
-          class << self
+          # Does the cleanup for the inverse of the association when
+          # replacing the relation with another list of documents.
+          #
+          # @param [ Array<Document> | nil ] replacement the list of documents
+          #   that will replace the current list.
+          def cleanup_inverse_for(replacement)
+            if replacement
+              new_ids = replacement.collect { |doc| doc.public_send(_association.primary_key) }
+              objects_to_clear = _base.public_send(foreign_key) - new_ids
+              criteria(objects_to_clear).pull(inverse_foreign_key => inverse_primary_key)
+            else
+              criteria.pull(inverse_foreign_key => inverse_primary_key)
+            end
+          end
 
-            # Get the Eager object for this type of association.
-            #
-            # @example Get the eager loader object
-            #
-            # @param [ Association ] association The association object.
-            # @param [ Array<Document> ] docs The array of documents.
-            #
-            # @since 7.0
-            def eager_loader(association, docs)
-              Eager.new(association, docs)
+          # The inverse primary key
+          #
+          # @return [ Object ] the inverse primary key
+          def inverse_primary_key
+            if (field = _association.options[:inverse_primary_key])
+              _base.public_send(field)
+            else
+              _base._id
             end
+          end
 
-            # Returns true if the association is an embedded one. In this case
-            # always false.
-            #
-            # @example Is this association embedded?
-            #   Referenced::ManyToMany.embedded?
-            #
-            # @return [ false ] Always false.
-            #
-            # @since 2.0.0.rc.1
-            def embedded?
-              false
+          # Clears the _target list and executes callbacks for each document.
+          # If an exception occurs in an after_remove hook, the exception is
+          # saved, the processing completes, and *then* the exception is
+          # re-raised.
+          #
+          # @return [ Array<Document> ] the replacement documents
+          def clear_target_for_nullify
+            after_remove_error = nil
+            many_to_many = _target.clear do |doc|
+              unbind_one(doc)
+              doc.changed_attributes.delete(inverse_foreign_key) unless _association.forced_nil_inverse?
+
+              begin
+                execute_callback :after_remove, doc
+              rescue StandardError => e
+                after_remove_error = e
+              end
+            end
+
+            raise after_remove_error if after_remove_error
+
+            many_to_many
+          end
+
+          # Processes a single document as part of a ``concat`` command.
+          #
+          # @param [ Mongoid::Document ] doc the document to append
+          # @param [ Hash ] ids the mapping of primary keys that have been
+          #   visited
+          # @param [ Array ] docs the list of new docs to be inserted later,
+          #   in bulk
+          # @param [ Array ] inserts the list of Hashes of attributes that will
+          #   be inserted (corresponding to the ``docs`` list)
+          #
+          # rubocop:disable Metrics/AbcSize
+          def append_document(doc, ids, docs, inserts)
+            return unless doc
+
+            append(doc)
+
+            pk = doc.public_send(_association.primary_key)
+            if persistable? || _creating?
+              ids[pk] = true
+              save_or_delay(doc, docs, inserts)
+            else
+              existing = _base.public_send(foreign_key)
+              return if existing.include?(pk)
+
+              existing.push(pk)
+              unsynced(_base, foreign_key)
             end
           end
+          # rubocop:enable Metrics/AbcSize
         end
       end
     end

data/lib/mongoid/association/referenced/has_and_belongs_to_many.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/referenced/has_and_belongs_to_many/binding'
 require 'mongoid/association/referenced/has_and_belongs_to_many/buildable'
@@ -11,8 +11,6 @@ module Mongoid
     module Referenced
 
       # The HasAndBelongsToMany type association.
-      #
-      # @since 7.0
       class HasAndBelongsToMany
         include Relatable
         include Buildable
@@ -21,8 +19,6 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :after_add,
             :after_remove,
@@ -37,35 +33,28 @@ module Mongoid
             :primary_key,
             :inverse_primary_key,
             :inverse_foreign_key,
+            :scope,
         ].freeze
 
         # The complete list of valid options for this association, including
         # the shared ones.
         #
         # @return [ Array<Symbol> ] The valid options.
-        #
-        # @since 7.0
         VALID_OPTIONS = (ASSOCIATION_OPTIONS + SHARED_OPTIONS).freeze
 
         # The type of the field holding the foreign key.
         #
         # @return [ Array ]
-        #
-        # @since 7.0
         FOREIGN_KEY_FIELD_TYPE = Array
 
         # The default foreign key suffix.
         #
         # @return [ String ] '_ids'
-        #
-        # @since 7.0
         FOREIGN_KEY_SUFFIX = '_ids'.freeze
 
         # The list of association complements.
         #
-        # @return [ Array<Association> ] The association complements.
-        #
-        # @since 7.0
+        # @return [ Array<Mongoid::Association::Relatable> ] The association complements.
         def relation_complements
           @relation_complements ||= [ self.class ].freeze
         end
@@ -73,8 +62,6 @@ module Mongoid
         # Setup the instance methods, fields, etc. on the association owning class.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup!
           setup_instance_methods!
           self
@@ -83,22 +70,16 @@ module Mongoid
         # Is this association type embedded?
         #
         # @return [ false ] Always false.
-        #
-        # @since 7.0
         def embedded?; false; end
 
         # The default for validation the association object.
         #
         # @return [ false ] Always false.
-        #
-        # @since 7.0
         def validation_default; true; end
 
         # Are ids only saved on this side of the association?
         #
-        # @return [ true, false ] Whether this association has a forced nil inverse.
-        #
-        # @since 7.0
+        # @return [ true | false ] Whether this association has a forced nil inverse.
         def forced_nil_inverse?
           @forced_nil_inverse ||= @options.key?(:inverse_of) && !@options[:inverse_of]
         end
@@ -106,15 +87,11 @@ module Mongoid
         # Does this association type store the foreign key?
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def stores_foreign_key?; true; end
 
         # Get the association proxy class for this association type.
         #
         # @return [ Association::HasAndBelongsToMany::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
@@ -122,8 +99,6 @@ module Mongoid
         # Get the foreign key field for saving the association reference.
         #
         # @return [ String ] The foreign key field for saving the association reference.
-        #
-        # @since 7.0
         def foreign_key
           @foreign_key ||= @options[:foreign_key] ? @options[:foreign_key].to_s :
                              default_foreign_key_field
@@ -132,8 +107,6 @@ module Mongoid
         # The criteria used for querying this association.
         #
         # @return [ Mongoid::Criteria ] The criteria used for querying this association.
-        #
-        # @since 7.0
         def criteria(base, id_list = nil)
           query_criteria(id_list || base.send(foreign_key))
         end
@@ -142,13 +115,13 @@ module Mongoid
         #
         # @return [ String ] The foreign key field for saving the association reference
         #  on the inverse side.
-        #
-        # @since 7.0
         def inverse_foreign_key
           if @options.key?(:inverse_foreign_key)
             @options[:inverse_foreign_key]
           elsif @options.key?(:inverse_of)
             inverse_of ? "#{inverse_of.to_s.singularize}#{FOREIGN_KEY_SUFFIX}" : nil
+          elsif inv = inverse_association&.foreign_key
+            inv
           else
             "#{inverse_class_name.demodulize.underscore}#{FOREIGN_KEY_SUFFIX}"
           end
@@ -159,7 +132,7 @@ module Mongoid
         #
         # @param [ Document ] doc The document to be bound.
         #
-        # @return [ true, false ] Whether the document can be bound.
+        # @return [ true | false ] Whether the document can be bound.
         def bindable?(doc)
           forced_nil_inverse? || (!!inverse && doc.fields.keys.include?(foreign_key))
         end
@@ -168,8 +141,6 @@ module Mongoid
         #
         # @return [ String ] The foreign key setter for saving the association reference
         #  on the inverse side.
-        #
-        # @since 7.0
         def inverse_foreign_key_setter
           @inverse_foreign_key_setter ||= "#{inverse_foreign_key}=" if inverse_foreign_key
         end
@@ -180,8 +151,6 @@ module Mongoid
         # @param [ Hash ] options The options for the association.
         #
         # @return [ Association::Nested::One ] The Nested Builder object.
-        #
-        # @since 7.0
         def nested_builder(attributes, options)
           Nested::Many.new(self, attributes, options)
         end
@@ -194,12 +163,17 @@ module Mongoid
         # @param [ Document ] document The document to calculate on.
         #
         # @return [ Root ] The root atomic path calculator.
-        #
-        # @since 2.1.0
         def path(document)
           Mongoid::Atomic::Paths::Root.new(document)
         end
 
+        # Get the scope to be applied when querying the association.
+        #
+        # @return [ Proc | Symbol | nil ] The association scope, if any.
+        def scope
+          @options[:scope]
+        end
+
         private
 
         def setup_instance_methods!
@@ -248,7 +222,7 @@ module Mongoid
         def synced_save
           assoc = self
           inverse_class.set_callback(
-              :save,
+              :persist_parent,
               :after,
               if: ->(doc){ doc._syncable?(assoc) }
           ) do |doc|
@@ -257,6 +231,7 @@ module Mongoid
         end
 
         def create_foreign_key_field!
+          inverse_class.aliased_associations[foreign_key] = name.to_s
           @owner_class.field(
               foreign_key,
               type: FOREIGN_KEY_FIELD_TYPE,
@@ -288,7 +263,13 @@ module Mongoid
         end
 
         def query_criteria(id_list)
-          crit = relation_class.all_of(primary_key => {"$in" => id_list || []})
+          crit = relation_class.criteria
+          crit = if id_list
+            crit = crit.apply_scope(scope)
+            crit.all_of(primary_key => { "$in" => id_list })
+          else
+            crit.none
+          end
           with_ordering(crit)
         end
       end

data/lib/mongoid/association/referenced/has_many/binding.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -15,8 +15,6 @@ module Mongoid
           #
           # @example Bind one document.
           #   person.posts.bind_one(post)
-          #
-          # @since 2.0.0.rc.1
           def bind_one(doc)
             binding do
               bind_from_relational_parent(doc)
@@ -27,8 +25,6 @@ module Mongoid
           #
           # @example Unbind the document.
           #   person.posts.unbind_one(document)
-          #
-          # @since 2.0.0.rc.1
           def unbind_one(doc)
             binding do
               unbind_from_relational_parent(doc)