MONGOID-5128 Support association :scope option

Author: johnnyshields

docs/reference/associations.txt

@@ -969,6 +969,44 @@ the model. However, since Mongoid doesn't know what type of data should be
 allowed in the field, the field is created with a type of Object. It is a
 good idea to explicitly define the field with the appropriate type.
 
+Custom Scopes
+-------------
+
+You may set a specific scope on an association using the ``:scope`` parameter.
+The scope may be either:
+- a ``Proc`` with arity zero
+- a ``Symbol`` which references a :ref:`named scope <named-scopes>` on the associated model
+
+.. code-block:: ruby
+  class Trainer
+    has_many :pets, scope: -> { where(species: 'dog' }
+    has_many :toys, scope: :rubber
+  end
+
+  class Pet
+    belongs_to :trainer
+  end
+
+  class Toy
+    scope :rubber, where(material: 'rubber')
+    belongs_to :trainer
+  end
+
+A scoped association will return only documents which satisfy the scope condition.
+
+As a caveat, it is still possible to make associations between documents which violate
+the scope condition. In this case, such documents will appear associated in-memory,
+but will not be present when the association is re-queried. Refer to the following example:
+
+.. code-block:: ruby
+  trainer = Trainer.create!
+  dog = Pet.create!(trainer: trainer, species: 'dog')
+  cat = Pet.create!(trainer: trainer, species: 'cat')
+
+  trainer.pets #=> [dog, cat]
+
+  trainer.reload.pets #=> [dog]
+
 Validations
 -----------
 

lib/mongoid/association/referenced/belongs_to.rb

@@ -29,7 +29,8 @@ class BelongsTo
             :primary_key,
             :touch,
             :optional,
-            :required
+            :required,
+            :scope
         ].freeze
 
         # The complete list of valid options for this association, including
@@ -130,6 +131,15 @@ def path(document)
           Mongoid::Atomic::Paths::Root.new(document)
         end
 
+        # Get the scope to be applied when querying the association.
+        #
+        # @return [ Proc, Symbol ] The association scope.
+        #
+        # @since 7.4
+        def scope
+          @options[:scope]
+        end
+
         private
 
         def setup_instance_methods!

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

@@ -32,8 +32,10 @@ def execute_query(object, type)
           end
 
           def query_criteria(object, type)
-            model = type ? type.constantize : relation_class
-            model.where(primary_key => object)
+            cls = type ? type.constantize : relation_class
+            crit = cls.criteria
+            crit = crit.apply_scope(scope)
+            crit.where(primary_key => object)
           end
 
           def query?(object)

lib/mongoid/association/referenced/eager.rb

@@ -70,7 +70,9 @@ def each_loaded_document(&block)
             # Upstream code is responsible for eliminating nils from keys.
             return cls.none if keys.empty?
 
-            criteria = cls.any_in(key => keys)
+            criteria = cls.criteria
+            criteria = criteria.apply_scope(@association.scope)
+            criteria = criteria.any_in(key => keys)
             criteria.inclusions = criteria.inclusions - [@association]
             criteria.each do |doc|
               yield doc

lib/mongoid/association/referenced/has_and_belongs_to_many.rb

@@ -32,6 +32,7 @@ class HasAndBelongsToMany
             :primary_key,
             :inverse_primary_key,
             :inverse_foreign_key,
+            :scope
         ].freeze
 
         # The complete list of valid options for this association, including
@@ -163,6 +164,15 @@ def path(document)
           Mongoid::Atomic::Paths::Root.new(document)
         end
 
+        # Get the scope to be applied when querying the association.
+        #
+        # @return [ Proc, Symbol ] The association scope.
+        #
+        # @since 7.4
+        def scope
+          @options[:scope]
+        end
+
         private
 
         def setup_instance_methods!
@@ -251,7 +261,9 @@ def with_ordering(criteria)
         end
 
         def query_criteria(id_list)
-          crit = relation_class.all_of(primary_key => {"$in" => id_list || []})
+          crit = relation_class.criteria
+          crit = crit.apply_scope(scope)
+          crit = crit.all_of(primary_key => {"$in" => id_list || []})
           with_ordering(crit)
         end
       end

lib/mongoid/association/referenced/has_many.rb

@@ -29,7 +29,8 @@ class HasMany
             :dependent,
             :foreign_key,
             :order,
-            :primary_key
+            :primary_key,
+            :scope
         ].freeze
 
         # The complete list of valid options for this association, including
@@ -176,6 +177,15 @@ def path(document)
           Mongoid::Atomic::Paths::Root.new(document)
         end
 
+        # Get the scope to be applied when querying the association.
+        #
+        # @return [ Proc, Symbol ] The association scope.
+        #
+        # @since 7.4
+        def scope
+          @options[:scope]
+        end
+
         private
 
         def default_foreign_key_field
@@ -204,7 +214,9 @@ def default_primary_key
         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

lib/mongoid/association/referenced/has_one.rb

@@ -24,7 +24,8 @@ class HasOne
             :autosave,
             :dependent,
             :foreign_key,
-            :primary_key
+            :primary_key,
+            :scope
         ].freeze
 
         # The complete list of valid options for this association, including
@@ -129,6 +130,15 @@ def path(document)
           Mongoid::Atomic::Paths::Root.new(document)
         end
 
+        # Get the scope to be applied when querying the association.
+        #
+        # @return [ Proc, Symbol ] The association scope.
+        #
+        # @since 7.4
+        def scope
+          @options[:scope]
+        end
+
         private
 
         # Setup the instance methods on the class having this association type.

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

@@ -46,7 +46,9 @@ def clear_associated(object)
           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
 

lib/mongoid/criteria/scopable.rb

@@ -17,6 +17,22 @@ def apply_default_scope
         self.scoping_options = true, false
       end
 
+      # Applies a scope to the criteria
+      #
+      # @param [ Proc, Symbol ] scope The scope to apply.
+      #
+      # @return [ Criteria ] The criteria with scoping removed.
+      #
+      # @since 7.4.0
+      def apply_scope(scope)
+        case scope
+        when Proc then instance_exec(&scope)
+        when Symbol then send(scope)
+        when Criteria then merge(scope)
+        else self
+        end
+      end
+
       # Given another criteria, remove the other criteria's scoping from this
       # criteria.
       #

spec/integration/associations/scope_option_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+require 'spec_helper'
+require_relative '../../mongoid/association/referenced/has_and_belongs_to_many_models'
+require_relative '../../mongoid/association/referenced/has_many_models'
+require_relative '../../mongoid/association/referenced/has_one_models'
+
+describe 'association :scope option' do
+
+  context 'has_many and belongs_to' do
+    let!(:trainer1) { HmmTrainer.create!(name: 'Dave') }
+    let!(:trainer2) { HmmTrainer.create!(name: 'Ash') }
+    let!(:animal1) { HmmAnimal.create!(taxonomy: 'reptile', trainer: trainer1) }
+    let!(:animal2) { HmmAnimal.create!(taxonomy: 'bird', trainer: trainer1) }
+    let!(:animal3) { HmmAnimal.create!(taxonomy: 'mammal', trainer: trainer2) }
+
+    it 'initially associates the documents in-memory' do
+      expect(trainer1.animals).to eq [animal1, animal2]
+      expect(trainer2.animals).to eq [animal3]
+      expect(animal1.trainer).to eq trainer1
+      expect(animal2.trainer).to eq trainer1
+      expect(animal3.trainer).to eq trainer2
+    end
+
+    it 'loads correct documents when queried' do
+      expect(trainer1.reload.animals).to eq [animal1]
+      expect(trainer2.reload.animals).to eq []
+      expect(animal1.reload.trainer).to eq trainer1
+      expect(animal2.reload.trainer).to eq trainer1
+      expect(animal3.reload.trainer).to be_nil
+    end
+
+    it 'eager loads correct documents' do
+      expect(HmmTrainer.includes(:animals).find(trainer1._id).animals).to eq [animal1]
+      expect(HmmTrainer.includes(:animals).find(trainer2._id).animals).to eq []
+      expect(HmmAnimal.includes(:trainer).find(animal1._id).trainer).to eq trainer1
+      expect(HmmAnimal.includes(:trainer).find(animal2._id).trainer).to eq trainer1
+      expect(HmmAnimal.includes(:trainer).find(animal3._id).trainer).to be_nil
+    end
+  end
+
+  context 'has_one and belongs_to' do
+    let!(:trainer1) { HomTrainer.create!(name: 'Dave') }
+    let!(:trainer2) { HomTrainer.create!(name: 'Ash') }
+    let!(:animal1) { HomAnimal.create!(taxonomy: 'reptile', trainer: trainer1) }
+    let!(:animal2) { HomAnimal.create!(taxonomy: 'bird', trainer: trainer1) }
+    let!(:animal3) { HomAnimal.create!(taxonomy: 'mammal', trainer: trainer2) }
+
+    it 'initially associates the documents in-memory' do
+      expect(trainer1.animal).to eq animal2
+      expect(trainer2.animal).to eq animal3
+      expect(animal1.trainer).to eq trainer1
+      expect(animal2.trainer).to eq trainer1
+      expect(animal3.trainer).to eq trainer2
+    end
+
+    it 'loads correct documents when queried' do
+      expect(trainer1.reload.animal).to eq animal1
+      expect(trainer2.reload.animal).to be_nil
+      expect(animal1.reload.trainer).to eq trainer1
+      expect(animal2.reload.trainer).to eq trainer1
+      expect(animal3.reload.trainer).to be_nil
+    end
+
+    it 'eager loads correct documents' do
+      expect(HomTrainer.includes(:animal).find(trainer1._id).animal).to eq animal1
+      expect(HomTrainer.includes(:animal).find(trainer2._id).animal).to be_nil
+      expect(HomAnimal.includes(:trainer).find(animal1._id).trainer).to eq trainer1
+      expect(HomAnimal.includes(:trainer).find(animal2._id).trainer).to eq trainer1
+      expect(HomAnimal.includes(:trainer).find(animal3._id).trainer).to be_nil
+    end
+  end
+
+  context 'has_and_belongs_to_many' do
+    let!(:trainer1) { HabtmmTrainer.create!(name: 'Dave') }
+    let!(:trainer2) { HabtmmTrainer.create!(name: 'Ash') }
+    let!(:animal1) { HabtmmAnimal.create!(taxonomy: 'reptile', trainers: [trainer1, trainer2]) }
+    let!(:animal2) { HabtmmAnimal.create!(taxonomy: 'bird', trainers: [trainer1, trainer2]) }
+
+    it 'initially associates the documents in-memory' do
+      expect(trainer1.animals).to eq [animal1]
+      expect(trainer2.animals).to eq [animal1]
+      expect(animal1.trainers).to eq [trainer1, trainer2]
+      expect(animal2.trainers).to eq [trainer1, trainer2]
+    end
+
+    it 'loads correct documents when queried' do
+      expect(trainer1.reload.animals).to eq [animal1]
+      expect(trainer2.reload.animals).to eq [animal1]
+      expect(animal1.reload.trainers).to eq [trainer1]
+      expect(animal2.reload.trainers).to eq [trainer1]
+    end
+
+    it 'eager loads correct documents' do
+      expect(HabtmmTrainer.includes(:animals).find(trainer1._id).animals).to eq [animal1]
+      expect(HabtmmTrainer.includes(:animals).find(trainer2._id).animals).to eq [animal1]
+      expect(HabtmmAnimal.includes(:trainers).find(animal1._id).trainers).to eq [trainer1]
+      expect(HabtmmAnimal.includes(:trainers).find(animal2._id).trainers).to eq [trainer1]
+    end
+  end
+end