mongoid 7.2.1 → 9.0.0

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

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
     module Referenced
       class BelongsTo
-
-        # This class handles all behavior for associations that are either
-        # one-to-many or one-to-one, where the foreign key is stored on this side
-        # of the association and the reference is to document(s) in another
-        # collection.
+        # Transparent proxy for belong_to 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 document on the opposite-side collection which must
+        # be loaded.
         class Proxy < Association::One
           include Evolvable
 
@@ -19,11 +20,11 @@ module Mongoid
           #   Association::BelongsTo::Proxy.new(game, person, association)
           #
           # @param [ Document ] base The document this association hangs off of.
-          # @param [ Document, Array<Document> ] target The target (parent) of the
+          # @param [ Document | Array<Document> ] target The target (parent) of the
           #   association.
-          # @param [ Association ] association The association object.
+          # @param [ Mongoid::Association::Relatable ] association The association object.
           def initialize(base, target, association)
-            init(base, target, association) do
+            super do
               characterize_one(_target)
               bind_one
             end
@@ -35,7 +36,6 @@ module Mongoid
           #
           # @example Nullify the association.
           #   person.game.nullify
-          #
           def nullify
             unbind_one
             _target.save
@@ -47,18 +47,16 @@ module Mongoid
           # @example Substitute the association.
           #   name.substitute(new_name)
           #
-          # @param [ Document, Array<Document> ] replacement The replacement.
-          #
-          # @return [ self, nil ] The association or nil.
+          # @param [ Document | Array<Document> ] replacement The replacement.
           #
-          # @since 2.0.0.rc.1
+          # @return [ self | nil ] The association or nil.
           def substitute(replacement)
             unbind_one
-            if replacement
-              self._target = normalize(replacement)
-              bind_one
-              self
-            end
+            return unless replacement
+
+            self._target = normalize(replacement)
+            bind_one
+            self
           end
 
           private
@@ -69,8 +67,6 @@ module Mongoid
           #   binding([ address ])
           #
           # @return [ Binding ] The binding object.
-          #
-          # @since 2.0.0.rc.1
           def binding
             BelongsTo::Binding.new(_base, _target, _association)
           end
@@ -82,13 +78,12 @@ module Mongoid
           # @example Normalize the substitute.
           #   proxy.normalize(id)
           #
-          # @param [ Document, Object ] replacement The replacement object.
+          # @param [ Document | Object ] replacement The replacement object.
           #
           # @return [ Document ] The document.
-          #
-          # @since 3.1.5
           def normalize(replacement)
             return replacement if replacement.is_a?(Document)
+
             _association.build(klass, replacement)
           end
 
@@ -97,23 +92,21 @@ 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?
             _target.persisted? && !_binding? && !_building?
           end
 
           class << self
-
             # Get the Eager object for this type of association.
             #
             # @example Get the eager loader object
             #
-            # @param [ Association ] association The association object.
+            # @param [ Mongoid::Association::Relatable ] association The association object.
             # @param [ Array<Document> ] docs The array of documents.
             #
-            # @since 7.0
+            # @return [ Mongoid::Association::Referenced::BelongsTo::Eager ]
+            #   The eager loader.
             def eager_loader(association, docs)
               Eager.new(association, docs)
             end
@@ -125,8 +118,6 @@ module Mongoid
             #   Association::BelongsTo::Proxy.embedded?
             #
             # @return [ false ] Always false.
-            #
-            # @since 2.0.0.rc.1
             def embedded?
               false
             end

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/referenced/belongs_to/binding'
 require 'mongoid/association/referenced/belongs_to/buildable'
@@ -11,8 +11,6 @@ module Mongoid
     module Referenced
 
       # The BelongsTo type association.
-      #
-      # @since 7.0
       class BelongsTo
         include Relatable
         include Buildable
@@ -21,8 +19,6 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :autobuild,
             :autosave,
@@ -34,36 +30,29 @@ module Mongoid
             :primary_key,
             :touch,
             :optional,
-            :required
+            :required,
+            :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 [ Object ]
-        #
-        # @since 7.0
         FOREIGN_KEY_FIELD_TYPE = Object
 
         # The default foreign key suffix.
         #
         # @return [ String ] '_id'
-        #
-        # @since 7.0
         FOREIGN_KEY_SUFFIX = '_id'.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 ||= [ HasMany, HasOne ].freeze
         end
@@ -71,8 +60,6 @@ module Mongoid
         # Setup the instance methods, fields, etc. on the association owning class.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup!
           setup_instance_methods!
           @owner_class.aliased_fields[name.to_s] = foreign_key
@@ -82,29 +69,21 @@ module Mongoid
         # Does this association type store the foreign key?
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def stores_foreign_key?; true; end
 
         # 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; false; end
 
         # 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
@@ -113,17 +92,13 @@ module Mongoid
         # Get the association proxy class for this association type.
         #
         # @return [ Association::BelongsTo::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
 
         # Is this association polymorphic?
         #
-        # @return [ true, false ] Whether this association is polymorphic.
-        #
-        # @since 7.0
+        # @return [ true | false ] Whether this association is polymorphic.
         def polymorphic?
           @polymorphic ||= !!@options[:polymorphic]
         end
@@ -131,8 +106,6 @@ module Mongoid
         # The name of the field used to store the type of polymorphic association.
         #
         # @return [ String ] The field used to store the type of polymorphic association.
-        #
-        # @since 7.0
         def inverse_type
           (@inverse_type ||= "#{name}_type") if polymorphic?
         end
@@ -143,8 +116,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::One.new(self, attributes, options)
         end
@@ -157,12 +128,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!
@@ -178,7 +154,7 @@ module Mongoid
           create_foreign_key_field!
           setup_index!
           define_touchable!
-          @owner_class.validates_associated(name) if validate?
+          @owner_class.validates_associated(name) if validate? || require_association?
           @owner_class.validates(name, presence: true) if require_association?
         end
 

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

@@ -1,22 +1,24 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Referenced
+
+      # Mixin module included into Mongoid::Document which adds
+      # the ability to cache the count of opposite-side documents
+      # in referenced n-to-many associations.
       module CounterCache
         extend ActiveSupport::Concern
 
         # Reset the given counter using the .count() query from the
-        # db. This method is usuful in case that a counter got
+        # db. This method is useful in case that a counter got
         # corrupted, or a new counter was added to the collection.
         #
         # @example Reset the given counter cache
         #   post.reset_counters(:comments)
         #
-        # @param [ Symbol, Array ] counters One or more counter caches to reset
-        #
-        # @since 4.0.0
+        # @param [ Symbol... ] *counters One or more counter caches to reset.
         def reset_counters(*counters)
           self.class.with(persistence_context) do |_class|
             _class.reset_counters(self, *counters)
@@ -26,16 +28,14 @@ module Mongoid
         module ClassMethods
 
           # Reset the given counter using the .count() query from the
-          # db. This method is usuful in case that a counter got
+          # db. This method is useful in case that a counter got
           # corrupted, or a new counter was added to the collection.
           #
           # @example Reset the given counter cache
           #   Post.reset_counters('50e0edd97c71c17ea9000001', :comments)
           #
           # @param [ String ] id The id of the object that will be reset.
-          # @param [ Symbol, Array ] counters One or more counter caches to reset
-          #
-          # @since 3.1.0
+          # @param [ Symbol... ] *counters One or more counter caches to reset.
           def reset_counters(id, *counters)
             document = id.is_a?(Document) ? id : find(id)
             counters.each do |name|
@@ -55,8 +55,6 @@ module Mongoid
           #
           # @param [ String ] id The id of the object to update.
           # @param [ Hash ] counters
-          #
-          # @since 3.1.0
           def update_counters(id, counters)
             where(:_id => id).inc(counters)
           end
@@ -70,8 +68,6 @@ module Mongoid
           #
           # @param [ Symbol ] counter_name Counter cache name
           # @param [ String ] id The id of the object that will have its counter incremented.
-          #
-          # @since 3.1.0
           def increment_counter(counter_name, id)
             update_counters(id, counter_name.to_sym => 1)
           end
@@ -85,8 +81,6 @@ module Mongoid
           #
           # @param [ Symbol ] counter_name Counter cache name
           # @param [ String ] id The id of the object that will have its counter decremented.
-          #
-          # @since 3.1.0
           def decrement_counter(counter_name, id)
             update_counters(id, counter_name.to_sym => -1)
           end
@@ -99,29 +93,27 @@ module Mongoid
         # @example Add the touchable.
         #   Mongoid::Association::Referenced::CounterCache.define_callbacks!(association)
         #
-        # @param [ Association ] association The association.
+        # @param [ Mongoid::Association::Relatable ] association The association.
         #
         # @return [ Class ] The association's owning class.
-        #
-        # @since 7.0
         def self.define_callbacks!(association)
           name = association.name
           cache_column = association.counter_cache_column_name.to_sym
 
           association.inverse_class.tap do |klass|
             klass.after_update do
-              if record = __send__(name)
-                foreign_key = association.foreign_key
+              foreign_key = association.foreign_key
 
-                if attribute_changed?(foreign_key)
-                  original, current = attribute_change(foreign_key)
+              if send("#{foreign_key}_previously_changed?")
+                original, current = send("#{foreign_key}_previous_change")
 
-                  unless original.nil?
-                    record.class.with(persistence_context) do |_class|
-                      _class.decrement_counter(cache_column, original)
-                    end
+                unless original.nil?
+                  association.klass.with(persistence_context.for_child(association.klass)) do |_class|
+                    _class.decrement_counter(cache_column, original)
                   end
+                end
 
+                if record = __send__(name)
                   unless current.nil?
                     record[cache_column] = (record[cache_column] || 0) + 1
                     record.class.with(record.persistence_context) do |_class|

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -17,15 +17,13 @@ module Mongoid
           #   person.preferences.bind_one(preference)
           #
           # @param [ Document ] doc The single document to bind.
-          #
-          # @since 2.0.0.rc.1
           def bind_one(doc)
             binding do
-              inverse_keys = doc.you_must(_association.inverse_foreign_key)
+              inverse_keys = try_method(doc, _association.inverse_foreign_key) unless doc.frozen?
               if inverse_keys
                 record_id = inverse_record_id(doc)
                 unless inverse_keys.include?(record_id)
-                  doc.you_must(_association.inverse_foreign_key_setter, inverse_keys.push(record_id))
+                  try_method(doc, _association.inverse_foreign_key_setter, inverse_keys.push(record_id))
                 end
                 doc.reset_relation_criteria(_association.inverse)
               end
@@ -38,12 +36,10 @@ module Mongoid
           #
           # @example Unbind the document.
           #   person.preferences.unbind_one(document)
-          #
-          # @since 2.0.0.rc.1
           def unbind_one(doc)
             binding do
               _base.send(_association.foreign_key).delete_one(record_id(doc))
-              inverse_keys = doc.you_must(_association.inverse_foreign_key)
+              inverse_keys = try_method(doc, _association.inverse_foreign_key) unless doc.frozen?
               if inverse_keys
                 inverse_keys.delete_one(inverse_record_id(doc))
                 doc.reset_relation_criteria(_association.inverse)
@@ -54,6 +50,11 @@ module Mongoid
           end
 
           # Find the inverse id referenced by inverse_keys
+          #
+          # @param [ Mongoid::Document ] doc The document for which
+          #   to determine the inverse id.
+          #
+          # @return [ BSON::ObjectId ] The inverse id.
           def inverse_record_id(doc)
             if pk = _association.options[:inverse_primary_key]
               _base.send(pk)
@@ -67,6 +68,12 @@ module Mongoid
             end
           end
 
+          # Find the inverse association given a document.
+          #
+          # @param [ Mongoid::Document ] doc The document for which
+          #   to determine the inverse association.
+          #
+          # @return [ Mongoid::Association::Relatable ] The inverse association.
           def determine_inverse_association(doc)
             doc.relations[_base.class.name.demodulize.underscore.pluralize]
           end

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -7,8 +7,6 @@ module Mongoid
       class HasAndBelongsToMany
 
         # The Builder behavior for has_and_belongs_to_many associations.
-        #
-        # @since 7.0
         module Buildable
 
           # This builder either takes a hash and queries for the

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -7,7 +7,7 @@ module Mongoid
       class HasAndBelongsToMany
 
         # Eager class for has_and_belongs_to_many associations.
-        class Eager < Association::Referenced::Eager::Base
+        class Eager < Association::Eager
 
           private