MONGOID-5418 AR Feature Parity first!/last!/second etc. (#5396)

* MONGOID-5418 add test for first-fifth(!)

* MONGOID-5418 add rest of the methods + findable tests

* MONGOID-5418 add memory methods

* MONGOID-5418 add none methods

* MONGOID-5418 add documentation

* MONGOID-5418 add release notes

* MONGOID-5418 fix query docs

* MONGOID-5418 fix query cache tests

Author: neilshweky

docs/reference/queries.txt

@@ -1249,6 +1249,29 @@ Mongoid also has some helpful methods on criteria.
           Band.exists?
           Band.where(name: "Photek").exists?
 
+   * - ``Criteria#fifth``
+
+       *Get the fifth document for the given criteria.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.fifth
+
+   * - ``Criteria#fifth!``
+
+       *Get the fifth document for the given criteria, or raise an error if
+       none exist.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.fifth!
+
    * - ``Criteria#find_by``
 
        *Find a document by the provided attributes. If not found,
@@ -1314,6 +1337,20 @@ Mongoid also has some helpful methods on criteria.
           Band.where(:members.with_size => 3).last
           Band.first(2)
 
+   * - ``Criteria#first!|last!``
+
+       *Finds a single document given the provided criteria, or raises an error
+       if none are found. This method automatically adds a sort on _id if no
+       sort is given. This can cause performance issues, so if the sort is
+       undesirable, Criteria#take! can be used instead.*
+
+     -
+        .. code-block:: ruby
+
+          Band.first!
+          Band.where(:members.with_size => 3).first!
+          Band.where(:members.with_size => 3).last!
+
    * - ``Criteria#first_or_create``
 
        *Find the first document by the provided attributes, and if not found
@@ -1361,6 +1398,29 @@ Mongoid also has some helpful methods on criteria.
           # MongoDB 4.2 and lower
           Band.for_js("this.name = param", param: "Tool")
 
+   * - ``Criteria#fourth``
+
+       *Get the fourth document for the given criteria.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.fourth
+
+   * - ``Criteria#fourth!``
+
+       *Get the fourth document for the given criteria, or raise an error if
+       none exist.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.fourth!
+
    * - ``Criteria#length|size``
 
        *Same as count but caches subsequent calls to the database*
@@ -1427,6 +1487,52 @@ Mongoid also has some helpful methods on criteria.
           Band.all.pluck(:name, :likes)
             #=> [ ["Daft Punk", 342], ["Aphex Twin", 98], ["Ween", 227] ]
 
+   * - ``Criteria#second``
+
+       *Get the second document for the given criteria.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.second
+
+   * - ``Criteria#second!``
+
+       *Get the second document for the given criteria, or raise an error if
+       none exist.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.second!
+
+   * - ``Criteria#second_to_last``
+
+       *Get the second to last document for the given criteria.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.second_to_last
+
+   * - ``Criteria#second_to_last!``
+
+       *Get the second to last document for the given criteria, or raise an
+       error if none exist.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.second_to_last!
+
    * - ``Criteria#take``
 
        *Get a list of n documents from the database or just one if no parameter
@@ -1474,6 +1580,52 @@ Mongoid also has some helpful methods on criteria.
           # expands out to "managers.name" in the query:
           Band.all.tally('managers.n')
 
+   * - ``Criteria#third``
+
+       *Get the third document for the given criteria.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.third
+
+   * - ``Criteria#third!``
+
+       *Get the third document for the given criteria, or raise an error if
+       none exist.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.third!
+
+   * - ``Criteria#third_to_last``
+
+       *Get the third to last document for the given criteria.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.third_to_last
+
+   * - ``Criteria#third_to_last!``
+
+       *Get the third to last document for the given criteria, or raise an
+       error if none exist.*
+
+       *This method automatically adds a sort on _id if no sort is given.*
+
+     -
+        .. code-block:: ruby
+
+          Band.third_to_last!
+
 
 Eager Loading
 =============

docs/release-notes/mongoid-8.1.txt

@@ -0,0 +1,44 @@
+***********
+Mongoid 8.1
+***********
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+This page describes significant changes and improvements in Mongoid 8.1.
+The complete list of releases is available `on GitHub
+<https://github.com/mongodb/mongoid/releases>`_ and `in JIRA
+<https://jira.mongodb.org/projects/MONGOID?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page>`_;
+please consult GitHub releases for detailed release notes and JIRA for
+the complete list of issues fixed in each release, including bug fixes.
+
+
+Added ``Mongoid::Criteria`` finder methods
+------------------------------------------
+
+Mongoid 8.1 implements several finder methods on ``Mongoid::Criteria``:
+
+- ``first!``
+- ``last!``
+- ``second/second!``
+- ``third/third!``
+- ``fourth/fourth!``
+- ``fifth/fifth!``
+- ``second_to_last/second_to_last!``
+- ``third_to_last/third_to_last!``
+
+When no documents are found, methods without a bang (!) return nil, and methods
+with a bang (!) raise an error:
+
+.. code:: ruby
+
+  Band.none.first
+  # => nil
+
+  Band.none.first!
+  # => raise Mongoid::Errors::DocumentNotFound