MONGOID-4547 Implement #take / #take! for AR feature parity (#5354)

* MONGOID-4547 add new error

* MONGOID-4547 implement take/take!

* MONGOID-4547 some cleanup

* MONGOID-4547 don't use Mongo#first

* MONGOID-4547 memory implementation

* MONGOID-4547 add none implementation

* MONGOID-4547 fix non implementation

* MONGOID-4547 add documentation for take method

* MONGOID-4547 add take! method docs

* MONGOID-4547 docs changes

* Apply suggestions from code review

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

* MONGOID-4547 change param to limit

* Apply suggestions from code review

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

* MONGOID-4547 address comments

* MONGOID-4547 fix document_not_found tests

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

Author: neilshweky

docs/reference/queries.txt

@@ -1390,6 +1390,32 @@ Mongoid also has some helpful methods on criteria.
           # expands out to "managers.name" in the query:
           Band.all.pluck('managers.n')
 
+   * - ``Criteria#take``
+
+       *Get a list of n documents from the database or just one if no parameter
+       is provided.*
+
+       *This method does not apply a sort to the documents, so it can return
+       different document(s) than #first and #last.*
+
+     -
+        .. code-block:: ruby
+
+          Band.take
+          Band.take(5)
+
+   * - ``Criteria#take!``
+
+       *Get a document from the database or raise an error if none exist.*
+
+       *This method does not apply a sort to the documents, so it can return
+       different document(s) than #first and #last.*
+
+     -
+        .. code-block:: ruby
+
+          Band.take!
+
    * - ``Criteria#tally``
 
        *Get a mapping of values to counts for the provided field.*

docs/release-notes/mongoid-7.5.txt

@@ -147,3 +147,44 @@ return a ``Hash`` when instantiating a new document:
   band = Band.first
   p band.attributes.class
   # => BSON::Document
+
+
+Implemented ``Criteria#take/take!`` Method
+------------------------------------------
+
+Mongoid 7.5 introduces the ``#take`` method which returns a document
+or a set of documents from the database without ordering by ``_id``:
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+  end
+
+  Band.create!
+  Band.create!
+
+  Band.take
+  # => #<Band _id: 62c835813282a4470c07d530, >
+  Band.take(2)
+  # => [ #<Band _id: 62c835813282a4470c07d530, >, #<Band _id: 62c835823282a4470c07d531, > ]
+
+If a parameter is given to ``#take``, an array of documents is returned. If no parameter is
+given, a singular document is returned.
+
+The ``#take!`` method functions the same as calling ``#take`` without arguments,
+but raises an DocumentNotFound error instead of returning nil if no documents
+are found.
+
+.. code:: ruby
+
+  Band.take!
+  # => #<Band _id: 62c835813282a4470c07d530, >
+
+Note that the ``#take/take!`` methods do not apply a sort to the view before
+retrieving the documents from the database, and therefore they may return different
+results than the ``#first`` and ``#last`` methods. ``#take`` is equivalent to
+calling ``#first`` or ``#last`` with the ``{ id_sort: :none }`` option. This
+option has been deprecated in Mongoid 7.5 and it is recommended to use ``#take``
+instead going forward. Support for the ``:id_sort`` option will be dropped in
+Mongoid 8.

lib/config/locales/en.yml

@@ -427,6 +427,13 @@ en:
             \_\_\_\_\_\_default:\n
             \_\_\_\_\_\_\_\_hosts:\n
             \_\_\_\_\_\_\_\_\_\_- localhost:27017\n\n"
+        no_documents_found:
+          message: "Could not find a document of class %{klass}."
+          summary: "Mongoid attempted to find a document of the class %{klass}
+            but none exist."
+          resolution: "Create a document of class %{klass} or use a finder
+            method that returns nil when no documents are found instead of
+            raising an exception."
         no_environment:
           message: "Could not load the configuration since no environment
             was defined."

lib/mongoid/contextual/memory.rb

@@ -164,6 +164,39 @@ def last
         eager_load([documents.last]).first
       end
 
+      # Take the given number of documents from the database.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @param [ Integer | nil ] limit The number of documents to take or nil.
+      #
+      # @return [ Document ] The document.
+      def take(limit = nil)
+        if limit
+          eager_load(documents.take(limit))
+        else
+          eager_load([documents.first]).first
+        end
+      end
+
+      # Take the given number of documents from the database.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @return [ Document ] The document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        if documents.empty?
+          raise Errors::DocumentNotFound.new(klass, nil, nil)
+        else
+          eager_load([documents.first]).first
+        end
+      end
+
       # Get the length of matching documents in the context.
       #
       # @example Get the length of matching documents.

lib/mongoid/contextual/mongo.rb

@@ -400,6 +400,44 @@ def limit(value)
         @view = view.limit(value) and self
       end
 
+      # Take the given number of documents from the database.
+      #
+      # @example Take 10 documents
+      #   context.take(10)
+      #
+      # @param [ Integer | nil ] limit The number of documents to return or nil.
+      #
+      # @return [ Document | Array<Document> ] The list of documents, or one
+      #   document if no value was given.
+      def take(limit = nil)
+        if limit
+          limit(limit).to_a
+        else
+          # Do to_a first so that the Mongo#first method is not used and the
+          # result is not sorted.
+          limit(1).to_a.first
+        end
+      end
+
+      # Take one document from the database and raise an error if there are none.
+      #
+      # @example Take a document
+      #   context.take!
+      #
+      # @return [ Document ] The document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        # Do to_a first so that the Mongo#first method is not used and the
+        # result is not sorted.
+        if fst = limit(1).to_a.first
+          fst
+        else
+          raise Errors::DocumentNotFound.new(klass, nil, nil)
+        end
+      end
+
       # Initiate a map/reduce operation from the context.
       #
       # @example Initiate a map/reduce.

lib/mongoid/contextual/none.rb

@@ -125,6 +125,28 @@ def initialize(criteria)
       # @return [ nil ] Always nil.
       def last; nil; end
 
+      # Returns nil or empty array.
+      #
+      # @example Take a document in null context.
+      #   context.take
+      #
+      # @param [ Integer | nil ] limit The number of documents to take or nil.
+      #
+      # @return [ [] | nil ] Empty array or nil.
+      def take(limit = nil)
+        limit ? [] : nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Take a document in null context.
+      #   context.take!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def take!
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
+
       # Always returns zero.
       #
       # @example Get the length of null context.

lib/mongoid/errors/document_not_found.rb

@@ -24,7 +24,7 @@ class DocumentNotFound < MongoidError
       #   there is a shard key this will be a hash.
       def initialize(klass, params, unmatched = nil)
         if !unmatched && !params.is_a?(Hash)
-          unmatched = Array(params)
+          unmatched = Array(params) if params
         end
 
         @klass, @params = klass, params
@@ -98,7 +98,9 @@ def total(params)
       #
       # @return [ String ] The problem.
       def message_key(params, unmatched)
-        if Hash === params
+        if !params && !unmatched
+          "no_documents_found"
+        elsif Hash === params
           "document_with_attributes_not_found"
         elsif Hash === unmatched && unmatched.size >= 2
           "document_with_shard_key_not_found"

lib/mongoid/findable.rb

@@ -41,10 +41,12 @@ module Findable
       :pluck,
       :read,
       :sum,
+      :take,
+      :take!,
+      :tally,
       :text_search,
       :update,
       :update_all,
-      :tally,
 
     # Returns a count of records in the database.
     # If you want to specify conditions use where.

spec/mongoid/contextual/memory_spec.rb

@@ -641,6 +641,108 @@
     end
   end
 
+  describe "#take" do
+
+    let(:hobrecht) do
+      Address.new(street: "hobrecht")
+    end
+
+    let(:friedel) do
+      Address.new(street: "friedel")
+    end
+
+    let(:criteria) do
+      Address.where(:street.in => [ "hobrecht", "friedel" ]).tap do |crit|
+        crit.documents = [ hobrecht, friedel ]
+      end
+    end
+
+    let(:context) do
+      described_class.new(criteria)
+    end
+
+    it "returns the first matching document" do
+      expect(context.take).to eq(hobrecht)
+    end
+
+    it "returns an array when passing a limit" do
+      expect(context.take(2)).to eq([ hobrecht, friedel ])
+    end
+
+    it "returns an array when passing a limit as 1" do
+      expect(context.take(1)).to eq([ hobrecht ])
+    end
+
+    context 'when there is a collation on the criteria' do
+
+      let(:criteria) do
+        Address.where(:street.in => [ "hobrecht", "friedel" ]).tap do |crit|
+          crit.documents = [ hobrecht, friedel ]
+        end.collation(locale: 'en_US', strength: 2)
+      end
+
+      it "raises an exception" do
+        expect {
+          context.take
+        }.to raise_exception(Mongoid::Errors::InMemoryCollationNotSupported)
+      end
+    end
+  end
+
+  describe "#take!" do
+
+    let(:hobrecht) do
+      Address.new(street: "hobrecht")
+    end
+
+    let(:friedel) do
+      Address.new(street: "friedel")
+    end
+
+    let(:criteria) do
+      Address.where(:street.in => [ "hobrecht", "friedel" ]).tap do |crit|
+        crit.documents = [ hobrecht, friedel ]
+      end
+    end
+
+    let(:context) do
+      described_class.new(criteria)
+    end
+
+    it "returns the first matching document" do
+      expect(context.take!).to eq(hobrecht)
+    end
+
+    context "when the criteria is empty" do
+      let(:criteria) do
+        Address.where(street: "bogus").tap do |crit|
+          crit.documents = []
+        end
+      end
+
+      it "raise an error" do
+        expect do
+          context.take!
+        end.to raise_error(Mongoid::Errors::DocumentNotFound, /Could not find a document of class Address./)
+      end
+    end
+
+    context 'when there is a collation on the criteria' do
+
+      let(:criteria) do
+        Address.where(:street.in => [ "hobrecht", "friedel" ]).tap do |crit|
+          crit.documents = [ hobrecht, friedel ]
+        end.collation(locale: 'en_US', strength: 2)
+      end
+
+      it "raises an exception" do
+        expect {
+          context.take
+        }.to raise_exception(Mongoid::Errors::InMemoryCollationNotSupported)
+      end
+    end
+  end
+
   describe "#initialize" do
 
     context "when the criteria has no options" do