MONGOID-5100 allow selector arguments for .exists? (#5466)

* MONGOID-5100 allow selector arguments for .exists?

* MONGOID-5100 add examples to the docstrings

* MONGOID-5100 add docs and release notes

* Empty-Commit

* MONGOID-5100 allow false to be passed

* MONGOID-5100 update docs and docstrings

* MONGOID-5100 remove false as a param

* MONGOID-5100 put back nil/false

* MONGOID-5100 fix memory tests and fix limit == 0

Author: neilshweky

docs/reference/queries.txt

@@ -1243,11 +1243,22 @@ Mongoid also has some helpful methods on criteria.
        *Determine if any matching documents exist. Will return true if there
        are 1 or more.*
 
+       ``#exists?`` *now takes a number of argument types:*
+
+       - ``Hash``: *A hash of conditions.*
+       - ``Object``: *An _id to search for.*
+       - ``false``/``nil``: *Always returns false.*
+
      -
         .. code-block:: ruby
 
           Band.exists?
           Band.where(name: "Photek").exists?
+          Band.exists?(name: "Photek")
+          Band.exists?(BSON::ObjectId('6320d96a3282a48cfce9e72c'))
+          Band.exists?('6320d96a3282a48cfce9e72c')
+          Band.exists?(false)
+          Band.exists?(nil)
 
    * - ``Criteria#fifth``
 

docs/release-notes/mongoid-8.1.txt

@@ -287,3 +287,16 @@ raised when destroying or deleting, and not on saving or updating. See the
 section on :ref:`Read-only Documents <readonly-documents>` for more details.
 
 
+Added method parameters to ``#exists?``
+---------------------------------------
+
+Mongoid 8.1 introduces method paramters to the ``Contextual#exists?`` method.
+An _id, a hash of conditions, or ``false``/``nil`` can now be included:
+
+.. code:: ruby
+
+  Band.exists?
+  Band.exists?(name: "The Rolling Stones")
+  Band.exists?(BSON::ObjectId('6320d96a3282a48cfce9e72c'))
+  Band.exists?(false) # always false
+  Band.exists?(nil) # always false

lib/mongoid/contextual/memory.rb

@@ -110,9 +110,24 @@ def each
       # @example Do any documents exist for the context.
       #   context.exists?
       #
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
+      #
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
       # @return [ true | false ] If the count is more than zero.
-      def exists?
-        any?
+      #   Always false if passed nil or false.
+      def exists?(id_or_conditions = :none)
+        case id_or_conditions
+        when :none then any?
+        when nil, false then false
+        when Hash then Memory.new(criteria.where(id_or_conditions)).exists?
+        else Memory.new(criteria.where(_id: id_or_conditions)).exists?
+        end
       end
 
       # Get the first document in the database for the criteria's selector.

lib/mongoid/contextual/mongo.rb

@@ -161,12 +161,28 @@ def each(&block)
       # @example Do any documents exist for the context.
       #   context.exists?
       #
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
+      #
       # @note We don't use count here since Mongo does not use counted
       #   b-tree indexes.
       #
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
       # @return [ true | false ] If the count is more than zero.
-      def exists?
-        !!(view.projection(_id: 1).limit(1).first)
+      #   Always false if passed nil or false.
+      def exists?(id_or_conditions = :none)
+        return false if self.view.limit == 0
+        case id_or_conditions
+        when :none then !!(view.projection(_id: 1).limit(1).first)
+        when nil, false then false
+        when Hash then Mongo.new(criteria.where(id_or_conditions)).exists?
+        else Mongo.new(criteria.where(_id: id_or_conditions)).exists?
+        end
       end
 
       # Run an explain on the criteria.

lib/mongoid/contextual/none.rb

@@ -80,8 +80,17 @@ def each
       # @example Do any documents exist in the null context.
       #   context.exists?
       #
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
+      #
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
       # @return [ false ] Always false.
-      def exists?; false; end
+      def exists?(id_or_conditions = :none); false; end
 
       # Pluck the field values in null context.
       #

lib/mongoid/findable.rb

@@ -101,9 +101,19 @@ def empty?
     # @example Do any documents exist for the conditions?
     #   Person.exists?
     #
+    # @example Do any documents exist for given _id.
+    #   Person.exists?(BSON::ObjectId(...))
+    #
+    # @example Do any documents exist for given conditions.
+    #   Person.exists?(name: "...")
+    #
+    # @param [ Hash | Object | false ] id_or_conditions an _id to
+    #   search for, a hash of conditions, nil or false.
+    #
     # @return [ true | false ] If any documents exist for the conditions.
-    def exists?
-      with_default_scope.exists?
+    #   Always false if passed nil or false.
+    def exists?(id_or_conditions = :none)
+      with_default_scope.exists?(id_or_conditions)
     end
 
     # Finds a +Document+ or multiple documents by their _id values.

spec/mongoid/contextual/memory_spec.rb

@@ -766,52 +766,158 @@
       Address.new(street: "friedel")
     end
 
-    context "when there are matching documents" do
+    let(:criteria) do
+      Address.where(street: "hobrecht").tap do |crit|
+        crit.documents = [ hobrecht, friedel ]
+      end
+    end
 
-      let(:criteria) do
-        Address.where(street: "hobrecht").tap do |crit|
-          crit.documents = [ hobrecht, friedel ]
+    context "when not passing options" do
+
+      context "when there are matching documents" do
+
+        let(:context) do
+          described_class.new(criteria)
+        end
+
+        it "returns true" do
+          expect(context).to be_exists
         end
       end
 
-      let(:context) do
-        described_class.new(criteria)
+      context "when there are no matching documents" do
+
+        let(:criteria) do
+          Address.where(street: "pfluger").tap do |crit|
+            crit.documents = [ hobrecht, friedel ]
+          end
+        end
+
+        let(:context) do
+          described_class.new(criteria)
+        end
+
+        it "returns false" do
+          expect(context).to_not be_exists
+        end
       end
 
-      it "returns true" do
-        expect(context).to be_exists
+      context 'when there is a collation on the criteria' do
+
+        let(:criteria) do
+          Address.where(street: "pfluger").tap do |crit|
+            crit.documents = [ hobrecht, friedel ]
+          end.collation(locale: 'en_US', strength: 2)
+        end
+
+        it "raises an exception" do
+          expect {
+            context
+          }.to raise_exception(Mongoid::Errors::InMemoryCollationNotSupported)
+        end
       end
     end
 
-    context "when there are no matching documents" do
+    context "when passing an _id" do
 
-      let(:criteria) do
-        Address.where(street: "pfluger").tap do |crit|
-          crit.documents = [ hobrecht, friedel ]
+      context "when its of type BSON::ObjectId" do
+
+        context "when calling it on an empty criteria" do
+
+          it "returns true" do
+            expect(criteria.exists?(hobrecht._id)).to be true
+          end
+        end
+
+        context "when calling it on a criteria that includes the object" do
+
+          it "returns true" do
+            expect(criteria.where(street: hobrecht.street).exists?(hobrecht._id)).to be true
+          end
+        end
+
+        context "when calling it on a criteria that does not include the object" do
+
+          it "returns false" do
+            expect(criteria.where(street: "bogus").exists?(hobrecht._id)).to be false
+          end
+        end
+
+        context "when the id does not exist" do
+
+          it "returns false" do
+            expect(criteria.exists?(BSON::ObjectId.new)).to be false
+          end
         end
       end
 
-      let(:context) do
-        described_class.new(criteria)
+      context "when its of type String" do
+
+        context "when the id exists" do
+
+          it "returns true" do
+            expect(criteria.exists?(hobrecht._id.to_s)).to be true
+          end
+        end
+
+        context "when the id does not exist" do
+
+          it "returns false" do
+            expect(criteria.exists?(BSON::ObjectId.new.to_s)).to be false
+          end
+        end
+      end
+    end
+
+    context "when passing a hash" do
+
+      context "when calling it on an empty criteria" do
+
+        it "returns true" do
+          expect(criteria.exists?(street: hobrecht.street)).to be true
+        end
+      end
+
+      context "when calling it on a criteria that includes the object" do
+
+        it "returns true" do
+          expect(criteria.where(_id: hobrecht._id).exists?(street: hobrecht.street)).to be true
+        end
+      end
+
+      context "when calling it on a criteria that does not include the object" do
+
+        it "returns false" do
+          expect(criteria.where(_id: BSON::ObjectId.new).exists?(street: hobrecht.street)).to be false
+        end
       end
 
+      context "when the conditions don't match" do
+
+        it "returns false" do
+          expect(criteria.exists?(street: "bogus")).to be false
+        end
+      end
+    end
+
+    context "when passing false" do
+
       it "returns false" do
-        expect(context).to_not be_exists
+        expect(criteria.exists?(false)).to be false
       end
     end
 
-    context 'when there is a collation on the criteria' do
+    context "when passing nil" do
 
-      let(:criteria) do
-        Address.where(street: "pfluger").tap do |crit|
-          crit.documents = [ hobrecht, friedel ]
-        end.collation(locale: 'en_US', strength: 2)
+      it "returns false" do
+        expect(criteria.exists?(nil)).to be false
       end
+    end
 
-      it "raises an exception" do
-        expect {
-          context
-        }.to raise_exception(Mongoid::Errors::InMemoryCollationNotSupported)
+    context "when the limit is 0" do
+
+      it "returns false" do
+        expect(criteria.limit(0).exists?).to be false
       end
     end
   end