mongoid 7.2.1 → 9.0.0

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

@@ -1,19 +1,60 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
+# TODO: consider refactoring this Proxy class, to satisfy the following
+# cops...
+# rubocop:disable Metrics/ClassLength
 module Mongoid
   module Association
     module Referenced
       class HasMany
-
-        # This class defines the behavior for all associations that are a
-        # one-to-many between documents in different collections.
+        # Transparent proxy for has_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 < Association::Many
           extend Forwardable
 
+          # class-level methods for HasMany::Proxy
+          module ClassMethods
+            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::Many.embedded?
+            #
+            # @return [ false ] Always false.
+            def embedded?
+              false
+            end
+          end
+
+          extend ClassMethods
+
           def_delegator :criteria, :count
           def_delegators :_target, :first, :in_memory, :last, :reset, :uniq
 
+          # Instantiate a new references_many association. Will set the foreign key
+          # and the base on the inverse object.
+          #
+          # @example Create the new association.
+          #   Referenced::Many.new(base, target, association)
+          #
+          # @param [ Document ] base The document this association hangs off of.
+          # @param [ Array<Document> ] target The target of the association.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
+          def initialize(base, target, association)
+            enum = HasMany::Enumerable.new(target, base, association)
+            super(base, enum, association) do
+              raise_mixed if klass.embedded? && !klass.cyclic?
+            end
+          end
+
           # Appends a document or array of documents to the association. Will set
           # the parent and update the index in the process.
           #
@@ -26,22 +67,21 @@ 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
           def <<(*args)
             docs = args.flatten
             return concat(docs) if docs.size > 1
-            if doc = docs.first
+
+            if (doc = docs.first)
               append(doc)
               doc.save if persistable? && !_assigning? && !doc.validated?
             end
             self
           end
 
-          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.
@@ -52,15 +92,15 @@ module Mongoid
           # @param [ Array<Document> ] documents The docs to add.
           #
           # @return [ Array<Document> ] The documents.
-          #
-          # @since 2.4.0
           def concat(documents)
             docs, inserts = [], []
             documents.each do |doc|
               next unless doc
+
               append(doc)
               save_or_delay(doc, docs, inserts) if persistable?
             end
+
             persist_delayed(docs, inserts)
             self
           end
@@ -75,18 +115,17 @@ 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)
-            append(doc)
-            doc.apply_post_processed_defaults
-            yield(doc) if block_given?
-            doc.run_callbacks(:build) { doc }
-            doc
+            Factory.execute_build(type || klass, attributes, execute_callbacks: false).tap do |doc|
+              append(doc)
+              doc.apply_post_processed_defaults
+              yield doc if block_given?
+              doc.run_pending_callbacks
+              doc.run_callbacks(:build) { doc }
+            end
           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
@@ -98,19 +137,23 @@ module Mongoid
           # @param [ Document ] document The document to remove.
           #
           # @return [ Document ] The matching document.
-          #
-          # @since 2.1.0
           def delete(document)
-            execute_callback :before_remove, document
-            _target.delete(document) do |doc|
-              if doc
-                unbind_one(doc)
-                cascade!(doc) if !_assigning?
+            execute_callbacks_around(:remove, document) do
+              result = _target.delete(document) do |doc|
+                if doc
+                  unbind_one(doc)
+                  cascade!(doc) unless _assigning?
+                end
               end
-              execute_callback :after_remove, doc
+
+              result.tap { reset_unloaded }
             end
           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
+
           # Deletes all related documents from the database given the supplied
           # conditions.
           #
@@ -123,8 +166,6 @@ module Mongoid
           # @param [ Hash ] conditions Optional conditions to delete with.
           #
           # @return [ Integer ] The number of documents deleted.
-          #
-          # @since 2.0.0.beta.1
           def delete_all(conditions = nil)
             remove_all(conditions, :delete_all)
           end
@@ -135,14 +176,12 @@ module Mongoid
           # @example Destroy all documents in the association.
           #   person.posts.destroy_all
           #
-          # @example Conditonally destroy all documents in the association.
+          # @example Conditionally destroy all documents in the association.
           #   person.posts.destroy_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to destroy with.
           #
-          # @return [ Integer ] The number of documents destroyd.
-          #
-          # @since 2.0.0.beta.1
+          # @return [ Integer ] The number of documents destroyed.
           def destroy_all(conditions = nil)
             remove_all(conditions, :destroy_all)
           end
@@ -158,11 +197,9 @@ module Mongoid
           #   end
           #
           # @return [ Array<Document> ] The loaded docs.
-          #
-          # @since 2.1.0
-          def each
-            if block_given?
-              _target.each { |doc| yield(doc) }
+          def each(&block)
+            if block
+              _target.each(&block)
             else
               to_enum
             end
@@ -180,60 +217,63 @@ module Mongoid
           # @example Are there persisted documents?
           #   person.posts.exists?
           #
-          # @return [ true, false ] True is persisted documents exist, false if not.
-          def exists?
-            criteria.exists?
+          # @param [ :none | nil | false | Hash | Object ] id_or_conditions
+          #   When :none (the default), returns true if any persisted
+          #   documents exist in the association. When nil or false, this
+          #   will always return false. When a Hash is given, this queries
+          #   the documents in the association for those that match the given
+          #   conditions, and returns true if any match. Any other argument is
+          #   interpreted as an id, and queries for the existence of documents
+          #   in the association with a matching _id.
+          #
+          # @return [ true | false ] True is persisted documents exist, false if not.
+          def exists?(id_or_conditions = :none)
+            criteria.exists?(id_or_conditions)
           end
 
-          # Find the matchind document on the association, either based on id or
+          # Find the matching document on the association, either based on id or
           # conditions.
           #
+          # This method delegates to +Mongoid::Criteria#find+. If this method is
+          # not given a block, it returns one or many documents for the provided
+          # _id values.
+          #
+          # If this method is given a block, it returns the first document
+          # of those found by the current Criteria object for which the block
+          # returns a truthy value.
+          #
+          # @note Each argument can be an individual id, an array of ids or
+          #   a nested array. Each array will be flattened.
+          #
           # @example Find by an id.
           #   person.posts.find(BSON::ObjectId.new)
           #
           # @example Find by multiple ids.
           #   person.posts.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
           #
+          # @example Finds the first matching document using a block.
+          #   person.addresses.find { |addr| addr.state == 'CA' }
+          #
           # @note This will keep matching documents in memory for iteration
           #   later.
           #
-          # @param [ BSON::ObjectId, Array<BSON::ObjectId> ] args The ids.
-          #
-          # @return [ Document, Criteria ] The matching document(s).
+          # @param [ [ Object | Array<Object> ]... ] *args The ids.
+          # @param &block Optional block to pass.
+          # @yield [ Object ] Yields each enumerable element to the block.
           #
-          # @since 2.0.0.beta.1
-          def find(*args)
-            matching = criteria.find(*args)
+          # @return [ Document | Array<Document> | nil ] A document or matching documents.
+          def find(*args, &block)
+            matching = criteria.find(*args, &block)
             Array(matching).each { |doc| _target.push(doc) }
             matching
           end
 
-          # Instantiate a new references_many association. Will set the foreign key
-          # and the base on the inverse object.
-          #
-          # @example Create the new association.
-          #   Referenced::Many.new(base, target, association)
-          #
-          # @param [ Document ] base The document this association hangs off of.
-          # @param [ Array<Document> ] target The target of the association.
-          # @param [ Association ] association The association metadata.
-          #
-          # @since 2.0.0.beta.1
-          def initialize(base, target, association)
-            enum = HasMany::Targets::Enumerable.new(target, base, association)
-            init(base, enum, association) do
-              raise_mixed if klass.embedded? && !klass.cyclic?
-            end
-          end
-
           # 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.
           #
           # @example Nullify the association.
           #   person.posts.nullify
-          #
-          # @since 2.0.0.rc.1
           def nullify
             criteria.update_all(foreign_key => nil)
             _target.clear do |doc|
@@ -242,7 +282,7 @@ module Mongoid
             end
           end
 
-          alias :nullify_all :nullify
+          alias nullify_all nullify
 
           # Clear the association. Will delete the documents from the db if they are
           # already persisted.
@@ -251,30 +291,28 @@ module Mongoid
           #   person.posts.clear
           #
           # @return [ Many ] The association emptied.
-          #
-          # @since 2.0.0.beta.1
           def purge
-            unless _association.destructive?
-              nullify
-            else
-              after_remove_error = nil
-              criteria.delete_all
-              many = _target.clear do |doc|
-                execute_callback :before_remove, doc
-                unbind_one(doc)
-                doc.destroyed = true
-                begin
-                  execute_callback :after_remove, doc
-                rescue => e
-                  after_remove_error = e
-                end
+            return nullify unless _association.destructive?
+
+            after_remove_error = nil
+            criteria.delete_all
+            many = _target.clear do |doc|
+              execute_callback :before_remove, doc
+              unbind_one(doc)
+              doc.destroyed = true
+              begin
+                execute_callback :after_remove, doc
+              rescue StandardError => e
+                after_remove_error = e
               end
-              raise after_remove_error if after_remove_error
-              many
             end
+
+            raise after_remove_error if after_remove_error
+
+            many
           end
 
-          alias :clear :purge
+          alias clear purge
 
           # Substitutes the supplied target documents for the existing documents
           # in the association. If the new target is nil, perform the necessary
@@ -286,12 +324,10 @@ module Mongoid
           # @param [ Array<Document> ] replacement The replacement target.
           #
           # @return [ Many ] The association.
-          #
-          # @since 2.0.0.rc.1
           def substitute(replacement)
             if replacement
               new_docs, docs = replacement.compact, []
-              new_ids = new_docs.map { |doc| doc._id }
+              new_ids = new_docs.map(&:_id)
               remove_not_in(new_ids)
               new_docs.each do |doc|
                 docs.push(doc) if doc.send(foreign_key) != _base.send(_association.primary_key)
@@ -310,8 +346,6 @@ module Mongoid
           #   person.posts.unscoped
           #
           # @return [ Criteria ] The unscoped criteria.
-          #
-          # @since 2.4.0
           def unscoped
             klass.unscoped.where(foreign_key => _base.send(_association.primary_key))
           end
@@ -325,8 +359,6 @@ module Mongoid
           #   relation.append(document)
           #
           # @param [ Document ] document The document to append to the target.
-          #
-          # @since 2.0.0.rc.1
           def append(document)
             with_add_callbacks(document, already_related?(document)) do
               _target.push(document)
@@ -342,10 +374,8 @@ module Mongoid
           #   relation.with_add_callbacks(document, false)
           #
           # @param [ Document ] document The document to append to the target.
-          # @param [ true, false ] already_related Whether the document is already related
+          # @param [ true | false ] already_related Whether the document is already related
           #   to the target.
-          #
-          # @since 5.1.0
           def with_add_callbacks(document, already_related)
             execute_callback :before_add, document unless already_related
             yield
@@ -359,15 +389,13 @@ module Mongoid
           #
           # @param [ Document ] document The document to possibly append to the target.
           #
-          # @return [ true, false ] Whether the document is already related to the base and the
+          # @return [ true | false ] Whether the document is already related to the base and the
           #   association is persisted.
-          #
-          # @since 5.1.0
           def already_related?(document)
             document.persisted? &&
-                document._association &&
-                document.respond_to?(document._association.foreign_key) &&
-                document.__send__(document._association.foreign_key) == _base.id
+              document._association &&
+              document.respond_to?(document._association.foreign_key) &&
+              document.__send__(document._association.foreign_key) == _base._id
           end
 
           # Instantiate the binding associated with this association.
@@ -376,8 +404,6 @@ module Mongoid
           #   relation.binding([ address ])
           #
           # @return [ Binding ] The binding.
-          #
-          # @since 2.0.0.rc.1
           def binding
             HasMany::Binding.new(_base, _target, _association)
           end
@@ -388,8 +414,6 @@ module Mongoid
           #   relation.collection
           #
           # @return [ Collection ] The collection of the association.
-          #
-          # @since 2.0.2
           def collection
             klass.collection
           end
@@ -401,8 +425,6 @@ module Mongoid
           #   relation.criteria
           #
           # @return [ Criteria ] A new criteria.
-          #
-          # @since 2.0.0.beta.1
           def criteria
             @criteria ||= _association.criteria(_base)
           end
@@ -415,19 +437,17 @@ module Mongoid
           #
           # @param [ Document ] document The document to cascade on.
           #
-          # @return [ true, false ] If the association is destructive.
-          #
-          # @since 2.1.0
+          # @return [ true | false ] If the association is destructive.
           def cascade!(document)
-            if persistable?
-              case _association.dependent
-              when :delete_all
-                document.delete
-              when :destroy
-                document.destroy
-              else
-                document.save
-              end
+            return unless persistable?
+
+            case _association.dependent
+            when :delete_all
+              document.delete
+            when :destroy
+              document.destroy
+            else
+              document.save
             end
           end
 
@@ -436,14 +456,16 @@ module Mongoid
           #
           # If the method exists on the array, use the default proxy behavior.
           #
-          # @param [ Symbol, String ] name The name of the method.
-          # @param [ Array ] args The method args
-          # @param [ Proc ] block Optional block to pass.
+          # @param [ Symbol | String ] name The name of the method.
+          # @param [ Object... ] *args The method args
+          # @param &block Optional block to pass.
           #
-          # @return [ Criteria, Object ] A Criteria or return value from the target.
+          # @return [ Criteria | Object ] A Criteria or return value from the target.
           #
-          # @since 2.0.0.beta.1
-          def method_missing(name, *args, &block)
+          # TODO: make sure we are consistingly using respond_to_missing
+          #   anywhere we define method_missing.
+          # rubocop:disable Style/MissingRespondToMissing
+          ruby2_keywords def method_missing(name, *args, &block)
             if _target.respond_to?(name)
               _target.send(name, *args, &block)
             else
@@ -452,6 +474,7 @@ module Mongoid
               end
             end
           end
+          # rubocop:enable Style/MissingRespondToMissing
 
           # Persist all the delayed batch inserts.
           #
@@ -462,16 +485,14 @@ module Mongoid
           #
           # @param [ Array<Document> ] docs The delayed inserts.
           # @param [ Array<Hash> ] inserts The raw insert document.
-          #
-          # @since 3.0.0
           def persist_delayed(docs, inserts)
-            unless docs.empty?
-              collection.insert_many(inserts, session: _session)
-              docs.each do |doc|
-                doc.new_record = false
-                doc.run_after_callbacks(:create, :save) unless _association.autosave?
-                doc.post_persist
-              end
+            return if docs.empty?
+
+            collection.insert_many(inserts, session: _session)
+            docs.each do |doc|
+              doc.new_record = false
+              doc.run_after_callbacks(:create, :save) unless _association.autosave?
+              doc.post_persist
             end
           end
 
@@ -480,11 +501,9 @@ module Mongoid
           # @example Can we persist the association?
           #   relation.persistable?
           #
-          # @return [ true, false ] If the association is persistable.
-          #
-          # @since 2.1.0
+          # @return [ true | false ] If the association is persistable.
           def persistable?
-            !_binding? && (_creating? || _base.persisted? && !_building?)
+            !_binding? && (_creating? || (_base.persisted? && !_building?))
           end
 
           # Deletes all related documents from the database given the supplied
@@ -500,14 +519,12 @@ module Mongoid
           # @param [ Symbol ] method The deletion method to call.
           #
           # @return [ Integer ] The number of documents deleted.
-          #
-          # @since 2.1.0
           def remove_all(conditions = nil, method = :delete_all)
             selector = conditions || {}
             removed = klass.send(method, selector.merge!(criteria.selector))
             _target.delete_if do |doc|
-              if doc._matches?(selector)
-                unbind_one(doc) and true
+              doc._matches?(selector).tap do |b|
+                unbind_one(doc) if b
               end
             end
             removed
@@ -520,24 +537,31 @@ module Mongoid
           #   proxy.remove_not_in([ id ])
           #
           # @param [ Array<Object> ] ids The ids.
-          #
-          # @since 2.4.0
           def remove_not_in(ids)
             removed = criteria.not_in(_id: ids)
+
+            update_or_delete_all(removed)
+
+            in_memory.each do |doc|
+              next if ids.include?(doc._id)
+
+              unbind_one(doc)
+              _target.delete(doc)
+              doc.destroyed = true if _association.destructive?
+            end
+          end
+
+          # If the association is destructive, the matching documents will
+          # be removed. Otherwise, their foreign keys will be set to nil.
+          #
+          # @param [ Criteria ] removed The criteria for the documents to
+          #   remove.
+          def update_or_delete_all(removed)
             if _association.destructive?
               removed.delete_all
             else
               removed.update_all(foreign_key => nil)
             end
-            in_memory.each do |doc|
-              if !ids.include?(doc._id)
-                unbind_one(doc)
-                _target.delete(doc)
-                if _association.destructive?
-                  doc.destroyed = true
-                end
-              end
-            end
           end
 
           # Save a persisted document immediately or delay a new document for
@@ -550,8 +574,6 @@ module Mongoid
           #
           # @param [ Document ] doc The document.
           # @param [ Array<Document> ] inserts The inserts.
-          #
-          # @since 3.0.0
           def save_or_delay(doc, docs, inserts)
             if doc.new_record? && doc.valid?(:create)
               doc.run_before_callbacks(:save, :create)
@@ -561,28 +583,9 @@ module Mongoid
               doc.save
             end
           end
-
-          class << self
-
-            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::Many.embedded?
-            #
-            # @return [ false ] Always false.
-            #
-            # @since 2.0.0.rc.1
-            def embedded?
-              false
-            end
-          end
         end
       end
     end
   end
 end
+# rubocop:enable Metrics/ClassLength