MONGOID-5128 Scoped associations (#5017)

* MONGOID-5128 Support association :scope option

* typo fix

* expand documentation

* Fix specs

* Fix broken specs

* expand docs

* release note

* remove broken link

* Revert "remove broken link"

This reverts commit 8e4fea74f1bdf881f8b3fd0cda742ba01bd600e4.

* add missing labels

Co-authored-by: shields <[email protected]>
Co-authored-by: Oleg Pudeyev <[email protected]>
Co-authored-by: Dmitry Rybakov <[email protected]>

Author: 3 people

source/reference/associations.txt

@@ -969,6 +969,61 @@ 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.
 
+
+.. _association-scope:
+
+Custom Scopes
+-------------
+
+You may set a specific scope on an association using the ``:scope`` parameter.
+The scope is an additional filter that restricts which objects are considered
+to be a part of the association - a scoped association will return only
+documents which satisfy the scope condition.. The scope may be either:
+
+- a ``Proc`` with arity zero, or
+- 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
+
+.. note::
+
+  It is possible to add documents that do not satisfy an association's scope
+  to that association. In this case, such documents will appear associated
+  in memory, and will be saved to the database, but will not be present when
+  the association is queried in the future. For 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]
+
+.. note::
+
+  Mongoid's syntax for scoped association differs from that of Active Record.
+  Mongoid uses the ``:scope`` keyword argument for consistency with other
+  association options, whereas in Active Record the scope is a positional
+  argument.
+
+
 Validations
 -----------
 

source/reference/queries.txt

@@ -880,6 +880,8 @@ as its ``id`` alias) cannot be omitted via ``without``:
   #   embedded: false>
 
 
+.. _ordering:
+
 Ordering
 ========
 
@@ -1032,7 +1034,7 @@ to be combined with :ref:`ordering <ordering>` to ensure consistent results.
 .. _batch-size:
 
 ``batch_size``
---------
+--------------
 
 When executing large queries, or when iterating over query results with an enumerator method such as
 ``Criteria#each``, Mongoid automatically uses the `MongoDB getMore command
@@ -1829,6 +1831,9 @@ Scoping
 Scopes provide a convenient way to reuse common criteria with more
 business domain style syntax.
 
+
+.. _named-scopes:
+
 Named Scopes
 ------------
 

source/release-notes/mongoid-7.4.txt

@@ -113,6 +113,13 @@ Mongoid 7.4 and later will inherit the new implementation provided by
 implementation returning a hash of ``{"$oid" => "..."}``.
 
 
+Scoped Associations
+-------------------
+
+Associations now support the ``:scope`` argument, yielding
+:ref:`scoped associations <association-scope>`.
+
+
 ``distinct`` and ``pluck`` Respect Field Aliases In Embedded Documents
 ----------------------------------------------------------------------