mongoid 5.4.1 → 7.4.0

data/lib/mongoid/criteria/scopable.rb

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   class Criteria
     module Scopable
@@ -9,8 +10,6 @@ module Mongoid
       #   criteria.apply_default_scope
       #
       # @return [ Criteria ] The criteria.
-      #
-      # @since 3.0.0
       def apply_default_scope
         klass.without_default_scope do
           merge!(klass.default_scoping.call)
@@ -18,6 +17,31 @@ module Mongoid
         self.scoping_options = true, false
       end
 
+      # Applies a scope to the current criteria.
+      #
+      # This method does not modify the receiver but it may return a new
+      # object or the receiver depending on the argument: if the +scope+
+      # argument is nil, the receiver is returned without modification,
+      # otherwise a new criteria object is returned.
+      #
+      # @param [ Proc | Symbol | Criteria | nil ] scope The scope to apply.
+      #
+      # @return [ Criteria ] The criteria with the scope applied.
+      #
+      # @api private
+      def apply_scope(scope)
+        case scope
+        when Proc
+          instance_exec(&scope)
+        when Symbol
+          send(scope)
+        when Criteria
+          merge(scope)
+        else
+          self
+        end
+      end
+
       # Given another criteria, remove the other criteria's scoping from this
       # criteria.
       #
@@ -27,8 +51,6 @@ module Mongoid
       # @param [ Criteria ] other The other criteria.
       #
       # @return [ Criteria ] The criteria with scoping removed.
-      #
-      # @since 3.0.0
       def remove_scoping(other)
         if other
           reject_matching(other, :selector, :options)
@@ -47,8 +69,6 @@ module Mongoid
       # @param [ Hash ] options Additional query options.
       #
       # @return [ Criteria ] The scoped criteria.
-      #
-      # @since 3.0.0
       def scoped(options = nil)
         crit = clone
         crit.options.merge!(options || {})
@@ -64,8 +84,6 @@ module Mongoid
       #   criteria.scoped?
       #
       # @return [ true, false ] If the default scope is applied.
-      #
-      # @since 3.0.0
       def scoped?
         !!(defined?(@scoped) ? @scoped : nil)
       end
@@ -76,8 +94,6 @@ module Mongoid
       #   criteria.unscoped
       #
       # @return [ Criteria ] The unscoped criteria.
-      #
-      # @since 3.0.0
       def unscoped
         crit = clone
         unless unscoped?
@@ -93,8 +109,6 @@ module Mongoid
       #   criteria.unscoped?
       #
       # @return [ true, false ] If the criteria is force unscoped.
-      #
-      # @since 3.0.0
       def unscoped?
         !!(defined?(@unscoped) ? @unscoped : nil)
       end
@@ -105,8 +119,6 @@ module Mongoid
       #   criteria.scoping_options
       #
       # @return [ Array ] Scoped, unscoped.
-      #
-      # @since 3.0.0
       def scoping_options
         [ (defined?(@scoped) ? @scoped : nil), (defined?(@unscoped) ? @unscoped : nil) ]
       end
@@ -119,8 +131,6 @@ module Mongoid
       # @param [ Array ] options Scoped, unscoped.
       #
       # @return [ Array ] The new scoping options.
-      #
-      # @since 3.0.0
       def scoping_options=(options)
         @scoped, @unscoped = options
       end
@@ -134,8 +144,6 @@ module Mongoid
       #   criteria.with_default_scope
       #
       # @return [ Criteria ] The criteria.
-      #
-      # @since 3.0.0
       def with_default_scope
         crit = clone
         if klass.default_scopable? && !unscoped? && !scoped?

data/lib/mongoid/criteria.rb

@@ -1,10 +1,13 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 require "mongoid/criteria/findable"
 require "mongoid/criteria/includable"
 require "mongoid/criteria/inspectable"
 require "mongoid/criteria/marshalable"
 require "mongoid/criteria/modifiable"
+require "mongoid/criteria/queryable"
 require "mongoid/criteria/scopable"
+require "mongoid/criteria/options"
 
 module Mongoid
 
@@ -16,23 +19,31 @@ module Mongoid
   # against the database.
   class Criteria
     include Enumerable
+
+    # @api private
+    alias :_enumerable_find :find
+
     include Contextual
-    include Origin::Queryable
+    include Queryable
     include Findable
+
+    # @api private
+    alias :_findable_find :find
+
     include Inspectable
     include Includable
     include Marshalable
     include Modifiable
     include Scopable
     include Clients::Options
+    include Clients::Sessions
+    include Options
 
     # Static array used to check with method missing - we only need to ever
     # instantiate once.
-    #
-    # @since 4.0.0
     CHECK = []
 
-    attr_accessor :embedded, :klass, :parent_document, :metadata
+    attr_accessor :embedded, :klass, :parent_document, :association
 
     # Returns true if the supplied +Enumerable+ or +Criteria+ is equal to the results
     # of this +Criteria+ or the criteria itself.
@@ -42,13 +53,53 @@ module Mongoid
     # @param [ Object ] other The other +Enumerable+ or +Criteria+ to compare to.
     #
     # @return [ true, false ] If the objects are equal.
-    #
-    # @since 1.0.0
     def ==(other)
       return super if other.respond_to?(:selector)
       entries == other
     end
 
+    # Finds one or many documents given the provided _id values, or filters
+    # the documents in the current scope in the application process space
+    # after loading them if needed.
+    #
+    # If this method is not given a block, it delegates to +Findable#find+
+    # and finds one or many documents for the provided _id values.
+    #
+    # 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.
+    #
+    # Note that the "default proc" argument of Enumerable is not specially
+    # treated by Mongoid - the decision between delegating to +Findable+ vs
+    # +Enumerable+ is made solely based on whether +find+ is passed a block.
+    #
+    # @example Finds a document by its _id, invokes Findable#find.
+    #   critera.find("1234")
+    #
+    # @example Finds the first matching document using a block, invokes Enumerable#find.
+    #   criteria.find { |item| item.name == "Depeche Mode" }
+    #
+    # @example Finds the first matching document using a block using the default Proc, invokes Enumerable#find.
+    #   criteria.find(-> { "Default Band" }) { |item| item.name == "Milwaukee Mode" }
+    #
+    # @example Tries to find a document whose _id is the stringification of the provided Proc, typically failing.
+    #   enumerator = criteria.find(-> { "Default Band" })
+    #
+    # @return [ Document | Array<Document> | nil ] A document or matching documents.
+    #
+    # @raise Errors::DocumentNotFound If the parameters were _id values and
+    #   not all documents are found and the +raise_not_found_error+
+    #   Mongoid configuration option is truthy.
+    #
+    # @see https://ruby-doc.org/core/Enumerable.html#method-i-find
+    def find(*args, &block)
+      if block_given?
+        _enumerable_find(*args, &block)
+      else
+        _findable_find(*args)
+      end
+    end
+
     # Needed to properly get a criteria back as json
     #
     # @example Get the criteria as json.
@@ -92,8 +143,6 @@ module Mongoid
     #   criteria.documents
     #
     # @return [ Array<Document> ] The documents.
-    #
-    # @since 3.0.0
     def documents
       @documents ||= []
     end
@@ -105,8 +154,6 @@ module Mongoid
     # @param [ Array<Document> ] docs The embedded documents.
     #
     # @return [ Array<Document> ] The embedded documents.
-    #
-    # @since 3.0.0
     def documents=(docs)
       @documents = docs
     end
@@ -117,8 +164,6 @@ module Mongoid
     #   criteria.embedded?
     #
     # @return [ true, false ] If the criteria is embedded.
-    #
-    # @since 3.0.0
     def embedded?
       !!@embedded
     end
@@ -130,8 +175,6 @@ module Mongoid
     #   criteria.extract_id
     #
     # @return [ Object ] The id.
-    #
-    # @since 2.3.0
     def extract_id
       selector.extract_id
     end
@@ -145,8 +188,6 @@ module Mongoid
     # @param [ Hash ] extras The extra driver options.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 2.0.0
     def extras(extras)
       crit = clone
       crit.options.merge!(extras)
@@ -159,11 +200,9 @@ module Mongoid
     #   criteria.field_list
     #
     # @return [ Array<String> ] The fields.
-    #
-    # @since 2.0.0
     def field_list
       if options[:fields]
-        options[:fields].keys.reject{ |key| key == "_type" }
+        options[:fields].keys.reject{ |key| key == klass.discriminator_key }
       else
         []
       end
@@ -177,8 +216,6 @@ module Mongoid
     #   criteria.freeze
     #
     # @return [ Criteria ] The frozen criteria.
-    #
-    # @since 2.0.0
     def freeze
       context and inclusions and super
     end
@@ -189,8 +226,6 @@ module Mongoid
     #   Criteria.new(Band)
     #
     # @param [ Class ] klass The model class.
-    #
-    # @since 1.0.0
     def initialize(klass)
       @klass = klass
       @embedded = nil
@@ -208,7 +243,7 @@ module Mongoid
     #
     # @example Merge the criteria with a hash. The hash must contain a klass
     #   key and the key/value pairs correspond to method names/args.
-
+    #
     #   criteria.merge({
     #     klass: Band,
     #     where: { name: "Depeche Mode" },
@@ -232,8 +267,6 @@ module Mongoid
     # @param [ Criteria ] other The criteria to merge in.
     #
     # @return [ Criteria ] The merged criteria.
-    #
-    # @since 3.0.0
     def merge!(other)
       criteria = other.to_criteria
       selector.merge!(criteria.selector)
@@ -251,8 +284,6 @@ module Mongoid
     #   criteria.none
     #
     # @return [ Criteria ] The none criteria.
-    #
-    # @since 4.0.0
     def none
       @none = true and self
     end
@@ -263,8 +294,6 @@ module Mongoid
     #   criteria.empty_and_chainable?
     #
     # @return [ true, false ] If the criteria is a none.
-    #
-    # @since 4.0.0
     def empty_and_chainable?
       !!@none
     end
@@ -277,19 +306,16 @@ module Mongoid
     # @param [ Array<Symbol> ] args The names of the fields.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 1.0.0
     def only(*args)
-      return clone if args.flatten.empty?
       args = args.flatten
+      return clone if args.empty?
       if (args & Fields::IDS).empty?
         args.unshift(:_id)
       end
       if klass.hereditary?
-        super(*args.push(:_type))
-      else
-        super(*args)
+        args.push(klass.discriminator_key.to_sym)
       end
+      super(*args)
     end
 
     # Set the read preference for the criteria.
@@ -300,8 +326,6 @@ module Mongoid
     # @param [ Hash ] value The mode preference.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 5.0.0
     def read(value = nil)
       clone.tap do |criteria|
         criteria.options.merge!(read: value)
@@ -316,10 +340,8 @@ module Mongoid
     # @param [ Array<Symbol> ] args The names of the fields.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 4.0.3
     def without(*args)
-      args -= Fields::IDS
+      args -= id_fields
       super(*args)
     end
 
@@ -344,8 +366,6 @@ module Mongoid
     #   criteria.to_criteria
     #
     # @return [ Criteria ] self.
-    #
-    # @since 3.0.0
     def to_criteria
       self
     end
@@ -356,8 +376,6 @@ module Mongoid
     #   criteria.to_proc
     #
     # @return [ Proc ] The wrapped criteria.
-    #
-    # @since 3.0.0
     def to_proc
       ->{ self }
     end
@@ -373,7 +391,7 @@ module Mongoid
     #
     # @return [ Criteria ] The cloned criteria.
     def type(types)
-      any_in(_type: Array(types))
+      any_in(self.discriminator_key.to_sym => Array(types))
     end
 
     # This is the general entry point for most MongoDB queries. This either
@@ -392,11 +410,22 @@ module Mongoid
     #   is embedded.
     #
     # @return [ Criteria ] The cloned selectable.
-    #
-    # @since 1.0.0
-    def where(expression)
-      if expression.is_a?(::String) && embedded?
-        raise Errors::UnsupportedJavascript.new(klass, expression)
+    def where(*args)
+      # Historically this method required exactly one argument.
+      # As of https://jira.mongodb.org/browse/MONGOID-4804 it also accepts
+      # zero arguments.
+      # The underlying where implemetation that super invokes supports
+      # any number of arguments, but we don't presently allow mutiple
+      # arguments through this method. This API can be reconsidered in the
+      # future.
+      if args.length > 1
+        raise ArgumentError, "Criteria#where requires zero or one arguments (given #{args.length})"
+      end
+      if args.length == 1
+        expression = args.first
+        if expression.is_a?(::String) && embedded?
+          raise Errors::UnsupportedJavascript.new(klass, expression)
+        end
       end
       super
     end
@@ -408,8 +437,6 @@ module Mongoid
     #   criteria.without_options
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 3.0.4
     def without_options
       crit = clone
       crit.options.clear
@@ -428,10 +455,14 @@ module Mongoid
     # @param [ Hash ] scope The scope for the code.
     #
     # @return [ Criteria ] The criteria.
-    #
-    # @since 3.1.0
     def for_js(javascript, scope = {})
-      js_query(BSON::CodeWithScope.new(javascript, scope))
+      code = if scope.empty?
+        # CodeWithScope is not supported for $where as of MongoDB 4.4
+        BSON::Code.new(javascript)
+      else
+        BSON::CodeWithScope.new(javascript, scope)
+      end
+      js_query(code)
     end
 
     private
@@ -449,8 +480,6 @@ module Mongoid
     #
     # @raise [ Errors::DocumentNotFound ] If none are found and raising an
     #   error.
-    #
-    # @since 3.0.0
     def check_for_missing_documents!(result, ids)
       if (result.size < ids.size) && Mongoid.raise_not_found_error
         raise Errors::DocumentNotFound.new(klass, ids, ids - result.map(&:_id))
@@ -471,8 +500,6 @@ module Mongoid
     # @param [ Criteria ] other The criteria getting cloned.
     #
     # @return [ nil ] nil.
-    #
-    # @since 1.0.0
     def initialize_copy(other)
       @inclusions = other.inclusions.dup
       @scoping_options = other.scoping_options
@@ -491,9 +518,7 @@ module Mongoid
     # @param [ Array ] args The arguments.
     #
     # @return [ Object ] The result of the method call.
-    #
-    # @since 1.0.0
-    def method_missing(name, *args, &block)
+    ruby2_keywords def method_missing(name, *args, &block)
       if klass.respond_to?(name)
         klass.send(:with_scope, self) do
           klass.send(name, *args, &block)
@@ -512,8 +537,6 @@ module Mongoid
     #   criteria.merge_type_selection
     #
     # @return [ true, false ] If type selection was added.
-    #
-    # @since 3.0.3
     def merge_type_selection
       selector.merge!(type_selection) if type_selectable?
     end
@@ -526,12 +549,10 @@ module Mongoid
     #   criteria.type_selectable?
     #
     # @return [ true, false ] If type selection should be added.
-    #
-    # @since 3.0.3
     def type_selectable?
       klass.hereditary? &&
-        !selector.keys.include?("_type") &&
-        !selector.keys.include?(:_type)
+        !selector.keys.include?(self.discriminator_key) &&
+        !selector.keys.include?(self.discriminator_key.to_sym)
     end
 
     # Get the selector for type selection.
@@ -542,14 +563,12 @@ module Mongoid
     #   criteria.type_selection
     #
     # @return [ Hash ] The type selection.
-    #
-    # @since 3.0.3
     def type_selection
       klasses = klass._types
       if klasses.size > 1
-        { _type: { "$in" => klass._types }}
+        { klass.discriminator_key.to_sym => { "$in" => klass._types }}
       else
-        { _type: klass._types[0] }
+        { klass.discriminator_key.to_sym => klass._types[0] }
       end
     end
 
@@ -561,8 +580,6 @@ module Mongoid
     #   criteria.selector_with_type_selection
     #
     # @return [ Hash ] The selector.
-    #
-    # @since 3.0.3
     def selector_with_type_selection
       type_selectable? ? selector.merge(type_selection) : selector
     end