MONGOID-5003 Delegate Model#find with block argument to Enumerable#find (#5352)

* MONGOID-5003 Delegate Model#find with block argument to Enumerable#find

* Update lib/mongoid/findable.rb

Author: neilshweky

docs/release-notes/mongoid-8.0.txt

@@ -305,7 +305,7 @@ Mongoid 7 behavior:
 
 
 ``#pluck`` on Embedded Criteria Returns ``nil`` Values
-------------------------------------------------
+------------------------------------------------------
 
 Mongoid 8 fixes a bug where calling ``#pluck`` on a Mongoid::Criteria
 for embedded documents discarded nil values. This behavior was
@@ -573,3 +573,30 @@ Calling ``tally`` on the age field yields the following:
 
 The ``tally`` method accepts the dot notation and field aliases. It also
 allows for tallying localized fields.
+
+
+``find`` delegates to ``Enumerable#find`` when given a block
+------------------------------------------------------------
+
+When given a block, without ``_id`` arguments, ``find`` delegates to
+``Enumerable#find``. Consider the following model:
+
+.. code::
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+  end
+
+  Band.create!(name: "Depeche Mode")
+  Band.create!(name: "The Rolling Stones")
+
+Calling ``find`` with a block returns the first document for which the block
+returns ``true``:
+
+.. code::
+
+  Band.find do |b|
+    b.name == "Depeche Mode"
+  end
+  # => #<Band _id: 62c58e383282a4cbe82bd74b, name: "Depeche Mode">

lib/mongoid/findable.rb

@@ -119,6 +119,13 @@ def exists?
     # strings will be transparently converted to +BSON::ObjectId+ instances
     # during query construction.
     #
+    # If this method is given a block, it delegates to +Enumerable#find+ and
+    # returns the first document of those found by the current Crieria object
+    # for which the block returns a truthy value. If both a block and ids are
+    # given, the block is ignored and the documents for the given ids are
+    # returned. If a block and a Proc are given, the method delegates to
+    # +Enumerable#find+ and uses the proc as the default.
+    #
     # The +find+ method takes into account the default scope defined on the
     # model class, if any.
     #
@@ -129,8 +136,13 @@ def exists?
     #
     # @raise Errors::DocumentNotFound If not all documents are found and
     #   the +raise_not_found_error+ Mongoid configuration option is truthy.
-    def find(*args)
-      with_default_scope.find(*args)
+    def find(*args, &block)
+      empty_or_proc = args.empty? || (args.length == 1 && args.first.is_a?(Proc))
+      if block_given? && empty_or_proc
+        with_default_scope.find(*args, &block)
+      else
+        with_default_scope.find(*args)
+      end
     end
 
     # Find the first +Document+ given the conditions.

spec/mongoid/criteria/findable_spec.rb

@@ -1006,6 +1006,42 @@
         end
       end
     end
+
+    context "when passing in a block" do
+
+      let!(:band1) { Band.create!(name: '1') }
+      let!(:band2) { Band.create!(name: '2') }
+      let!(:band3) { Band.create!(name: '2') }
+
+      it "yields the documents to the block" do
+        doc = Band.find { |b| b.name == '2' }
+        expect(doc).to eq(band2)
+      end
+    end
+
+    context "when passing in ids and a block" do
+
+      let!(:band1) { Band.create!(name: '1') }
+      let!(:band2) { Band.create!(name: '2') }
+      let!(:band3) { Band.create!(name: '2') }
+
+      it "acts like findable find" do
+        docs = Band.find(band1.id, band2.id) { |b| b.name == '2' }
+        expect(docs).to eq([ band1, band2 ])
+      end
+    end
+
+    context "when passing in a Proc and a block" do
+
+      let!(:band1) { Band.create!(name: '1') }
+      let!(:band2) { Band.create!(name: '2') }
+      let!(:band3) { Band.create!(name: '2') }
+
+      it "acts like findable find" do
+        docs = Band.find(-> { 'default' }) { |b| b.name == '3' }
+        expect(docs).to eq('default')
+      end
+    end
   end
 
   describe "#for_ids" do

spec/mongoid/criteria_spec.rb

@@ -837,8 +837,8 @@
       end
     end
 
-    context "when given a Proc" do
-      it "behaves as Enumerable" do
+    context "when given a Proc without a block" do
+      it "raises an error" do
         lambda do
           criteria.find(-> {"default"})
         # Proc is not serializable to a BSON type