mongoid 7.2.1 → 9.0.0

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/referenced/has_many/binding'
 require 'mongoid/association/referenced/has_many/buildable'
@@ -12,8 +12,6 @@ module Mongoid
     module Referenced
 
       # The has_many association.
-      #
-      # @since 7.0
       class HasMany
         include Relatable
         include Buildable
@@ -22,8 +20,6 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :after_add,
             :after_remove,
@@ -34,29 +30,24 @@ module Mongoid
             :dependent,
             :foreign_key,
             :order,
-            :primary_key
+            :primary_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 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 ||= [ Referenced::BelongsTo ].freeze
         end
@@ -64,8 +55,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
@@ -74,8 +63,6 @@ module Mongoid
         # Setup the instance methods on the class having this association type.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup_instance_methods!
           define_getter!
           define_ids_getter!
@@ -94,8 +81,6 @@ module Mongoid
         #
         # @return [ String ] The foreign key field on the inverse 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
@@ -104,29 +89,21 @@ 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 [ true ] Always true.
-        #
-        # @since 7.0
         def validation_default; true; end
 
         # Does this association type store the foreign key?
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def stores_foreign_key?; false; end
 
         # Get the association proxy class for this association type.
         #
         # @return [ Association::HasMany::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
@@ -134,8 +111,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)
           query_criteria(base.send(primary_key), base)
         end
@@ -144,9 +119,7 @@ module Mongoid
         #
         # @note Only relevant for polymorphic associations.
         #
-        # @return [ String, nil ] The type field.
-        #
-        # @since 7.0
+        # @return [ String | nil ] The type field.
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -158,8 +131,6 @@ module Mongoid
         # @param [ Class ] object_class The object class.
         #
         # @return [ Mongoid::Criteria ] The criteria object.
-        #
-        # @since 7.0
         def add_polymorphic_criterion(criteria, object_class)
           if polymorphic?
             criteria.where(type => object_class.name)
@@ -170,9 +141,7 @@ module Mongoid
 
         # 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 ||= !!as
         end
@@ -182,7 +151,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
@@ -193,8 +162,6 @@ module Mongoid
         # @param [ Hash ] options The options for the association.
         #
         # @return [ Association::Nested::Many ] The Nested Builder object.
-        #
-        # @since 7.0
         def nested_builder(attributes, options)
           Nested::Many.new(self, attributes, options)
         end
@@ -207,12 +174,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 default_foreign_key_field
@@ -241,7 +213,9 @@ module Mongoid
         end
 
         def query_criteria(object, base)
-          crit = klass.where(foreign_key => object)
+          crit = klass.criteria
+          crit = crit.apply_scope(scope)
+          crit = crit.where(foreign_key => object)
           crit = with_polymorphic_criterion(crit, base)
           crit.association = self
           crit.parent_document = base

data/lib/mongoid/association/referenced/has_one/binding.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 HasOne
 
         # Binding class for has_one associations.
-        #
-        # @since 7.0
         class Binding
           include Bindable
 
@@ -21,8 +19,6 @@ module Mongoid
           # @example Bind the document.
           #   person.game.bind(:continue => true)
           #   person.game = Game.new
-          #
-          # @since 2.0.0.rc.1
           def bind_one
             binding do
               bind_from_relational_parent(_target)
@@ -35,8 +31,6 @@ module Mongoid
           # @example Unbind the document.
           #   person.game.unbind(:continue => true)
           #   person.game = nil
-          #
-          # @since 2.0.0.rc.1
           def unbind_one
             binding do
               unbind_from_relational_parent(_target)

data/lib/mongoid/association/referenced/has_one/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 HasOne
 
         # The Builder behavior for has_one associations.
-        #
-        # @since 7.0
         module Buildable
 
           # This method either takes an _id or an object and queries for the
@@ -49,12 +47,14 @@ module Mongoid
           end
 
           def query_criteria(object, base)
-            crit = klass.where(foreign_key => object)
+            crit = klass.criteria
+            crit = crit.apply_scope(scope)
+            crit = crit.where(foreign_key => object)
             with_polymorphic_criterion(crit, base)
           end
 
           def execute_query(object, base)
-            query_criteria(object, base).limit(1).first(id_sort: :none)
+            query_criteria(object, base).take
           end
 
           def with_polymorphic_criterion(criteria, base)

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

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Referenced
-
       class HasOne
-
-        class Eager < Association::Referenced::Eager::Base
+        # Eager class for has_one associations.
+        class Eager < Association::Eager
 
           private
 

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

@@ -1,14 +1,35 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
     module Referenced
       class HasOne
-
-        # This class defines the behavior for all associations that are a
-        # one-to-one between documents in different collections.
+        # Transparent proxy for has_one 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
+          # class-level methods for the HasOne::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::One.embedded?
+            #
+            # @return [ false ] Always false.
+            def embedded?
+              false
+            end
+          end
+
+          extend ClassMethods
 
           # Instantiate a new references_one association. Will set the foreign key
           # and the base on the inverse object.
@@ -18,9 +39,9 @@ module Mongoid
           #
           # @param [ Document ] base The document this association hangs off of.
           # @param [ Document ] target The target (child) of the association.
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           def initialize(base, target, association)
-            init(base, target, association) do
+            super do
               raise_mixed if klass.embedded? && !klass.cyclic?
               characterize_one(_target)
               bind_one
@@ -34,8 +55,6 @@ module Mongoid
           #
           # @example Nullify the association.
           #   person.game.nullify
-          #
-          # @since 2.0.0.rc.1
           def nullify
             unbind_one
             _target.save
@@ -51,22 +70,8 @@ module Mongoid
           # @param [ Array<Document> ] replacement The replacement target.
           #
           # @return [ One ] The association.
-          #
-          # @since 2.0.0.rc.1
           def substitute(replacement)
-            # If the same object currently associated is being assigned,
-            # rebind the association and save the target but do not destroy
-            # the target.
-
-            unbind_one
-            if persistable?
-              # TODO can this entire method be skipped if self == replacement?
-              if _association.destructive? && self != replacement
-                send(_association.dependent)
-              else
-                save if persisted?
-              end
-            end
+            prepare_for_replacement if self != replacement
             HasOne::Proxy.new(_base, replacement, _association) if replacement
           end
 
@@ -87,30 +92,22 @@ 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?
             _base.persisted? && !_binding? && !_building?
           end
 
-          class << self
+          # Takes the necessary steps to prepare for the current document
+          # to be replaced by a non-nil substitute.
+          def prepare_for_replacement
+            unbind_one
 
-            def eager_loader(association, docs)
-              Eager.new(association, docs)
-            end
+            return unless persistable?
 
-            # Returns true if the association is an embedded one. In this case
-            # always false.
-            #
-            # @example Is this association embedded?
-            #   Referenced::One.embedded?
-            #
-            # @return [ false ] Always false.
-            #
-            # @since 2.0.0.rc.1
-            def embedded?
-              false
+            if _association.destructive?
+              send(_association.dependent)
+            elsif persisted?
+              save
             end
           end
         end

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/referenced/has_one/binding'
 require 'mongoid/association/referenced/has_one/buildable'
@@ -11,8 +11,6 @@ module Mongoid
     module Referenced
 
       # The has_one association.
-      #
-      # @since 7.0
       class HasOne
         include Relatable
         include Buildable
@@ -21,37 +19,30 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :as,
             :autobuild,
             :autosave,
             :dependent,
             :foreign_key,
-            :primary_key
+            :primary_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 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 ||= [ Referenced::BelongsTo ].freeze
         end
@@ -59,8 +50,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
@@ -70,8 +59,6 @@ module Mongoid
         #
         # @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
@@ -80,22 +67,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 [ true ] Always true.
-        #
-        # @since 7.0
         def validation_default; true; end
 
         # Get the association proxy class for this association type.
         #
         # @return [ Association::HasOne::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
@@ -106,17 +87,13 @@ module Mongoid
         # @param [ Hash ] options The options for the association.
         #
         # @return [ Association::Nested::Many ] The Nested Builder object.
-        #
-        # @since 7.0
         def nested_builder(attributes, options)
           Nested::One.new(self, attributes, options)
         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 ||= !!as
         end
@@ -125,9 +102,7 @@ module Mongoid
         #
         # @note Only relevant for polymorphic associations.
         #
-        # @return [ String, nil ] The type field.
-        #
-        # @since 7.0
+        # @return [ String | nil ] The type field.
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -137,11 +112,14 @@ 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
 
+        # Does this association type store the foreign key?
+        #
+        # @return [ false ] Always false.
         def stores_foreign_key?; false; end
 
         # Get the path calculator for the supplied document.
@@ -152,19 +130,22 @@ 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
 
         # Setup the instance methods on the class having this association type.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup_instance_methods!
           define_getter!
           define_setter!

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -15,11 +15,9 @@ module Mongoid
         # @example Are the foreign keys syncable?
         #   document._syncable?(association)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
-        # @return [ true, false ] If we can sync.
-        #
-        # @since 2.1.0
+        # @return [ true | false ] If we can sync.
         def _syncable?(association)
           !_synced?(association.foreign_key) && send(association.foreign_key_check)
         end
@@ -30,8 +28,6 @@ module Mongoid
         #   document._synced
         #
         # @return [ Hash ] The synced foreign keys.
-        #
-        # @since 2.1.0
         def _synced
           @_synced ||= {}
         end
@@ -43,9 +39,7 @@ module Mongoid
         #
         # @param [ String ] foreign_key The foreign key.
         #
-        # @return [ true, false ] If we can sync.
-        #
-        # @since 2.1.0
+        # @return [ true | false ] If we can sync.
         def _synced?(foreign_key)
           !!_synced[foreign_key]
         end
@@ -55,11 +49,9 @@ module Mongoid
         # @example Update the inverse keys.
         #   document.remove_inverse_keys(association)
         #
-        # @param [ Association ] association The association.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
         # @return [ Object ] The updated values.
-        #
-        # @since 2.2.1
         def remove_inverse_keys(association)
           foreign_keys = send(association.foreign_key)
           unless foreign_keys.nil? || foreign_keys.empty?
@@ -72,14 +64,12 @@ module Mongoid
         # @example Update the inverse keys
         #   document.update_inverse_keys(association)
         #
-        # @param [ Association ] association The document association.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
         # @return [ Object ] The updated values.
-        #
-        # @since 2.1.0
         def update_inverse_keys(association)
-          if changes.has_key?(association.foreign_key)
-            old, new = changes[association.foreign_key]
+          if previous_changes.has_key?(association.foreign_key)
+            old, new = previous_changes[association.foreign_key]
             adds, subs = new - (old || []), (old || []) - new
 
             # If we are autosaving we don't want a duplicate to get added - the
@@ -109,9 +99,7 @@ module Mongoid
           # @example Set up the syncing.
           #   Person._synced(association)
           #
-          # @param [ Association ] association The association metadata.
-          #
-          # @since 2.1.0
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           def _synced(association)
             unless association.forced_nil_inverse?
               synced_save(association)
@@ -130,11 +118,9 @@ module Mongoid
           # @example Set up the save syncing.
           #   Person.synced_save(association)
           #
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           #
           # @return [ Class ] The class getting set up.
-          #
-          # @since 2.1.0
           def synced_save(association)
             set_callback(
                 :save,
@@ -151,11 +137,9 @@ module Mongoid
           # @example Set up the destroy syncing.
           #   Person.synced_destroy(association)
           #
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           #
           # @return [ Class ] The class getting set up.
-          #
-          # @since 2.2.1
           def synced_destroy(association)
             set_callback(
                 :destroy,

data/lib/mongoid/association/referenced.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require 'mongoid/association/referenced/auto_save'
 require 'mongoid/association/referenced/counter_cache'