mongoid 9.1.0 → 9.1.2

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

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'mongoid/association/referenced/has_many_through/proxy'
+require 'mongoid/association/referenced/has_many_through/eager'
+
+module Mongoid
+  module Association
+    module Referenced
+      # Metadata class for has_many :through associations.
+      class HasManyThrough
+        include Relatable
+
+        # The options available for this type of association, in addition to the
+        # common ones.
+        #
+        # @return [ Array<Symbol> ] The extra valid options.
+        ASSOCIATION_OPTIONS = %i[order source through].freeze
+
+        # The complete list of valid options for this association, including
+        # the shared ones.
+        #
+        # @return [ Array<Symbol> ] The valid options.
+        VALID_OPTIONS = (ASSOCIATION_OPTIONS + SHARED_OPTIONS).freeze
+
+        # The list of association complements.
+        #
+        # @return [ Array ]
+        def relation_complements
+          [].freeze
+        end
+
+        # Setup instance methods on the owner class.
+        #
+        # @return [ self ]
+        def setup!
+          setup_instance_methods!
+          self
+        end
+
+        # Is this association embedded?
+        #
+        # @return [ false ]
+        def embedded?
+          false
+        end
+
+        # The proxy class for this association type.
+        #
+        # @return [ Class ]
+        def relation
+          Proxy
+        end
+
+        # Through associations never store a foreign key on the owner document.
+        #
+        # @return [ false ]
+        def stores_foreign_key?
+          false
+        end
+
+        # The intermediate association metadata on the owner class.
+        # Resolved lazily to allow forward references.
+        #
+        # @return [ Mongoid::Association::Relatable ]
+        def through_association
+          @through_association ||= begin
+            assoc = @owner_class.relations[@options[:through].to_s] ||
+                    raise(
+                      Errors::InvalidRelationOption.new(
+                        @owner_class, name, :through, @options[:through]
+                      )
+                    )
+            if assoc.embedded?
+              raise(
+                Errors::InvalidRelationOption.new(
+                  @owner_class, name, :through,
+                  'through association must be a referenced association, not embedded'
+                )
+              )
+            end
+            assoc
+          end
+        end
+
+        # The source association metadata on the intermediate class.
+        # Resolved lazily to allow forward references.
+        #
+        # @return [ Mongoid::Association::Relatable ]
+        def source_association
+          @source_association ||= begin
+            source_name = (@options[:source] || name.to_s.singularize).to_s
+            assoc = through_association.klass.relations[source_name] ||
+                    raise(
+                      Errors::InvalidRelationOption.new(
+                        @owner_class, name, :source, source_name
+                      )
+                    )
+            if assoc.is_a?(Referenced::HasAndBelongsToMany)
+              raise(
+                Errors::InvalidRelationOption.new(
+                  @owner_class, name, :source,
+                  'has_and_belongs_to_many is not supported as a :through source'
+                )
+              )
+            end
+            assoc
+          end
+        end
+
+        # Return a Criteria scoped to the target documents reachable from base
+        # via the through association. Performs two queries: one against the
+        # intermediate collection, one against the source collection.
+        #
+        # @param [ Document ] base The owner document.
+        #
+        # @return [ Mongoid::Criteria ]
+        def criteria(base)
+          through_crit = through_association.criteria(base)
+
+          crit = if source_association.stores_foreign_key?
+                   # FK is on the intermediate (e.g. appointment.patient_id -> belongs_to :patient)
+                   target_pk = source_association.primary_key # '_id' on Patient
+                   source_fk = source_association.foreign_key # 'patient_id' on Appointment
+                   source_association.klass.where(
+                     target_pk => { '$in' => key_values(through_crit, source_fk) }
+                   )
+                 else
+                   # FK is on the source (e.g. reader.book_id -> has_many :readers on Book)
+                   source_pk = source_association.primary_key # '_id' on intermediate (Book)
+                   source_fk = source_association.foreign_key # 'book_id' on Reader
+                   source_association.klass.where(
+                     source_fk => { '$in' => key_values(through_crit, source_pk) }
+                   )
+                 end
+          order ? crit.order_by(order) : crit
+        end
+
+        # The default for validating the association object.
+        #
+        # @return [ false ]
+        def validation_default
+          false
+        end
+
+        private
+
+        # Pluck the given key from the criteria, dropping intermediates that
+        # have no value for it. A nil in an $in array matches every document
+        # whose queried field is null or absent, which would return documents
+        # outside the association. An empty result correctly matches nothing.
+        # Mirrors what the eager loader does.
+        #
+        # @param [ Mongoid::Criteria ] criteria The intermediate criteria.
+        # @param [ String ] key The key to pluck.
+        #
+        # @return [ Array<Object> ] The usable key values.
+        def key_values(criteria, key)
+          criteria.pluck(key).compact.uniq
+        end
+
+        def setup_instance_methods!
+          define_through_getter!
+          define_through_ids_getter!
+          define_readonly_setter!
+          define_existence_check!
+          self
+        end
+
+        def define_through_getter!
+          assoc = self
+          assoc_name = name
+          @owner_class.re_define_method(assoc_name) do |reload = false|
+            if reload || !instance_variable_defined?("@_#{assoc_name}")
+              set_relation(assoc_name, HasManyThrough::Proxy.new(self, assoc))
+            end
+            instance_variable_get("@_#{assoc_name}")
+          end
+        end
+
+        def define_through_ids_getter!
+          assoc_name = name
+          ids_method = :"#{assoc_name.to_s.singularize}_ids"
+          @owner_class.re_define_method(ids_method) do
+            send(assoc_name).pluck(:_id)
+          end
+        end
+
+        def define_readonly_setter!
+          assoc = self
+          @owner_class.re_define_method(:"#{name}=") do |_object|
+            raise Mongoid::Errors::ReadonlyAssociation.new(self.class, assoc)
+          end
+        end
+
+        def default_primary_key
+          PRIMARY_KEY_DEFAULT
+        end
+      end
+    end
+  end
+end

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

@@ -22,6 +22,7 @@ module Mongoid
           autobuild
           autosave
           dependent
+          fallback
           foreign_key
           primary_key
           scope

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+    module Referenced
+      class HasOneThrough
+        # Two-query eager preloader for has_one :through associations.
+        class Eager < Association::Eager
+          private
+
+          def preload
+            @docs.each { |d| set_relation(d, nil) }
+
+            through_assoc = @association.through_association
+            source_assoc  = @association.source_association
+
+            owner_pk   = through_assoc.primary_key
+            through_fk = through_assoc.foreign_key
+
+            owner_ids = @docs.filter_map { |d| d.public_send(owner_pk) }.uniq
+            return if owner_ids.empty?
+
+            intermediates = through_assoc.klass.where(through_fk => { '$in' => owner_ids }).to_a
+            intermediate_to_target = build_intermediate_to_target(intermediates, through_fk, source_assoc)
+
+            @docs.each do |doc|
+              owner_key_val = doc.public_send(owner_pk)
+              target = intermediate_to_target[owner_key_val]
+              proxy = target ? HasOneThrough::Proxy.new(doc, target, @association) : nil
+              doc.set_relation(@association.name, proxy) unless doc.blank?
+            end
+          end
+
+          def build_intermediate_to_target(intermediates, through_fk, source_assoc)
+            if source_assoc.stores_foreign_key?
+              # FK is on the intermediate (e.g. belongs_to :store => intermediate.store_id)
+              source_fk_values = intermediates.filter_map { |i| i.public_send(source_assoc.foreign_key) }.uniq
+              targets = source_assoc.klass.where(source_assoc.primary_key => { '$in' => source_fk_values }).to_a
+              targets_by_key = targets.index_by { |t| t.public_send(source_assoc.primary_key) }
+              intermediates.to_h do |i|
+                [ i.public_send(through_fk), targets_by_key[i.public_send(source_assoc.foreign_key)] ]
+              end
+            else
+              # FK is on the source (e.g. has_one :store => store.franchise_id)
+              source_pk = source_assoc.primary_key
+              intermediate_pks = intermediates.filter_map { |i| i.public_send(source_pk) }.uniq
+              targets = source_assoc.klass.where(source_assoc.foreign_key => { '$in' => intermediate_pks }).to_a
+              targets_by_fk = targets.index_by { |t| t.public_send(source_assoc.foreign_key) }
+              intermediates.index_by { |i| i.public_send(through_fk) }.transform_values do |i|
+                targets_by_fk[i.public_send(source_pk)]
+              end
+            end
+          end
+
+          # Required by the base class contract. Not called by this preloader
+          # because preload manages document traversal directly without using
+          # the grouped_docs / keys_from_docs machinery from the base class.
+          def group_by_key
+            @association.through_association.primary_key
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+    module Referenced
+      class HasOneThrough
+        # Read-only proxy for has_one :through associations.
+        # Instances are returned by the association getter. Write attempts raise
+        # ReadonlyAssociation.
+        class Proxy < Association::One
+          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.
+            #
+            # @return [ false ] Always false.
+            def embedded?
+              false
+            end
+          end
+
+          extend ClassMethods
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'mongoid/association/referenced/has_one_through/proxy'
+require 'mongoid/association/referenced/has_one_through/eager'
+
+module Mongoid
+  module Association
+    module Referenced
+      # Metadata class for has_one :through associations.
+      class HasOneThrough
+        include Relatable
+
+        # The options available for this type of association, in addition to the
+        # common ones.
+        #
+        # @return [ Array<Symbol> ] The extra valid options.
+        ASSOCIATION_OPTIONS = %i[source through].freeze
+
+        # The complete list of valid options for this association, including
+        # the shared ones.
+        #
+        # @return [ Array<Symbol> ] The valid options.
+        VALID_OPTIONS = (ASSOCIATION_OPTIONS + SHARED_OPTIONS).freeze
+
+        # The list of association complements.
+        #
+        # @return [ Array ]
+        def relation_complements
+          [].freeze
+        end
+
+        # Setup instance methods on the owner class.
+        #
+        # @return [ self ]
+        def setup!
+          setup_instance_methods!
+          self
+        end
+
+        # Is this association embedded?
+        #
+        # @return [ false ]
+        def embedded?
+          false
+        end
+
+        # The proxy class for this association type.
+        #
+        # @return [ Class ]
+        def relation
+          Proxy
+        end
+
+        # The intermediate association metadata on the owner class.
+        # Resolved lazily to allow forward references.
+        #
+        # @return [ Mongoid::Association::Relatable ]
+        def through_association
+          @through_association ||= begin
+            assoc = @owner_class.relations[@options[:through].to_s] ||
+                    raise(
+                      Errors::InvalidRelationOption.new(
+                        @owner_class, name, :through, @options[:through]
+                      )
+                    )
+            if assoc.embedded?
+              raise(
+                Errors::InvalidRelationOption.new(
+                  @owner_class, name, :through,
+                  'through association must be a referenced association, not embedded'
+                )
+              )
+            end
+            assoc
+          end
+        end
+
+        # The source association metadata on the intermediate class.
+        # Resolved lazily to allow forward references.
+        #
+        # @return [ Mongoid::Association::Relatable ]
+        def source_association
+          @source_association ||= begin
+            source_name = (@options[:source] || name).to_s
+            assoc = through_association.klass.relations[source_name] ||
+                    raise(
+                      Errors::InvalidRelationOption.new(
+                        @owner_class, name, :source, source_name
+                      )
+                    )
+            if assoc.is_a?(Referenced::HasAndBelongsToMany)
+              raise(
+                Errors::InvalidRelationOption.new(
+                  @owner_class, name, :source,
+                  'has_and_belongs_to_many is not supported as a :through source'
+                )
+              )
+            end
+            assoc
+          end
+        end
+
+        # Through associations never store a foreign key on the owner document.
+        #
+        # @return [ false ]
+        def stores_foreign_key?
+          false
+        end
+
+        # Resolve the target by delegating through the intermediate proxy.
+        # Unlike other association types, this returns a document (or nil)
+        # directly rather than a Mongoid::Criteria, because the two-hop
+        # traversal is performed eagerly via the existing association proxy.
+        #
+        # @param [ Document ] base The owner document.
+        #
+        # @return [ Document | nil ]
+        def criteria(base)
+          through_target = base.public_send(through_association.name)
+          return nil if through_target.nil?
+
+          through_target.public_send(source_association.name)
+        end
+
+        # The default for validating the association object.
+        #
+        # @return [ false ]
+        def validation_default
+          false
+        end
+
+        private
+
+        def setup_instance_methods!
+          define_through_getter!
+          define_readonly_setter!
+          define_existence_check!
+          self
+        end
+
+        def define_through_getter!
+          assoc = self
+          assoc_name = name
+          @owner_class.re_define_method(assoc_name) do |reload = false|
+            if reload || !instance_variable_defined?("@_#{assoc_name}")
+              doc = assoc.criteria(self)
+              proxy = doc ? HasOneThrough::Proxy.new(self, doc, assoc) : nil
+              set_relation(assoc_name, proxy)
+            end
+            instance_variable_get("@_#{assoc_name}")
+          end
+        end
+
+        def define_readonly_setter!
+          assoc = self
+          @owner_class.re_define_method("#{name}=") do |_object|
+            raise Mongoid::Errors::ReadonlyAssociation.new(self.class, assoc)
+          end
+        end
+
+        def default_primary_key
+          PRIMARY_KEY_DEFAULT
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/association/referenced.rb

@@ -7,3 +7,5 @@ require 'mongoid/association/referenced/belongs_to'
 require 'mongoid/association/referenced/has_many'
 require 'mongoid/association/referenced/has_and_belongs_to_many'
 require 'mongoid/association/referenced/has_one'
+require 'mongoid/association/referenced/has_one_through'
+require 'mongoid/association/referenced/has_many_through'

data/lib/mongoid/association/relatable.rb

@@ -177,6 +177,23 @@ module Mongoid
       end
       alias klass relation_class
 
+      # The class of the association target, or nil when the named class is
+      # not defined.
+      #
+      # An association may name a class that never gets defined. The
+      # association is then unusable, but its owner still has to be. Callers
+      # that walk every association of every model, rather than following the
+      # one the application asked for, use this instead of relation_class.
+      #
+      # @return [ Class | nil ] The association objects' class.
+      #
+      # @api private
+      def try_relation_class
+        relation_class
+      rescue NameError
+        nil
+      end
+
       # The class name of the object owning this association.
       #
       # @return [ String ] The owning objects' class name.
@@ -200,6 +217,24 @@ module Mongoid
         stores_foreign_key? ? foreign_key : primary_key
       end
 
+      # The field a $lookup writes this association's preloaded documents into.
+      #
+      # @return [ String ] The field.
+      def preloaded_field
+        "#{PRELOADED_PREFIX}#{name}"
+      end
+
+      # A field where the aggregation collects this association's documents
+      # before moving them to where they belong. The qualifier tells it apart
+      # from the other temporary fields of the same association.
+      #
+      # @param [ String ] qualifier What tells this temporary field apart.
+      #
+      # @return [ String ] The field.
+      def temporary_field(qualifier)
+        "#{preloaded_field}_#{qualifier}"
+      end
+
       # The name of the setter on this object for assigning an associated object.
       #
       # @return [ String ] The setter name.
@@ -342,6 +377,15 @@ module Mongoid
         [ Referenced::BelongsTo, Embedded::EmbeddedIn ].any? { |a| is_a?(a) }
       end
 
+      # Is this association a many-to-many association? Such an association stores
+      # its foreign keys as an array on the document itself.
+      #
+      # @return [ true | false ] true if it is a has_and_belongs_to_many
+      #   association, false if not.
+      def many_to_many?
+        is_a?(Referenced::HasAndBelongsToMany)
+      end
+
       private
 
       # Gets the model classes with inverse associations of this model. This is used to determine
@@ -413,6 +457,20 @@ module Mongoid
           end
         end
 
+        if @options.key?(:fallback)
+          unless @options[:fallback].respond_to?(:call)
+            raise ArgumentError,
+                  "The :fallback option for association '#{name}' on " \
+                  "#{@owner_class} must be a Proc or lambda."
+          end
+
+          if @options.key?(:autobuild)
+            raise ArgumentError,
+                  "The :fallback option for association '#{name}' on " \
+                  "#{@owner_class} cannot be combined with :autobuild."
+          end
+        end
+
         [ name, :"#{name}?", :"#{name}=" ].each do |n|
           raise Errors::InvalidRelation.new(@owner_class, n) if Mongoid.destructive_fields.include?(n)
         end

data/lib/mongoid/association.rb

@@ -33,6 +33,14 @@ module Mongoid
     include Macros
     include Reflections
 
+    # Prefixes the field a $lookup writes an association's preloaded documents
+    # into. They travel apart from the document's own fields, so the hydration
+    # can keep them out of the attributes instead of leaving them on the
+    # document, where a later save would persist them.
+    #
+    # @api private
+    PRELOADED_PREFIX = '__mongoid_eager_loaded_'
+
     # Map the macros to their corresponding Association classes.
     #
     # @return [ Hash ] The mapping from macros to their Association class.
@@ -46,6 +54,13 @@ module Mongoid
       belongs_to: Association::Referenced::BelongsTo
     }.freeze
 
+    # Internal mapping used when :through option is present. Not exposed as
+    # callable macros.
+    THROUGH_MACRO_MAPPING = {
+      has_one: Association::Referenced::HasOneThrough,
+      has_many: Association::Referenced::HasManyThrough
+    }.freeze
+
     attr_accessor :_association
 
     included do