mongoid 7.1.1 → 8.1.0

data/lib/mongoid/criteria/queryable/selectable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   class Criteria
@@ -12,18 +11,12 @@ module Mongoid
         extend Macroable
 
         # Constant for a LineString $geometry.
-        #
-        # @since 2.0.0
         LINE_STRING = "LineString"
 
         # Constant for a Point $geometry.
-        #
-        # @since 2.0.0
         POINT = "Point"
 
         # Constant for a Polygon $geometry.
-        #
-        # @since 2.0.0
         POLYGON = "Polygon"
 
         # @attribute [rw] negating If the next expression is negated.
@@ -38,11 +31,9 @@ module Mongoid
         # @example Execute an $all in a where query.
         #   selectable.where(:field.all => [ 1, 2 ])
         #
-        # @param [ Hash ] criterion The key value pairs for $all matching.
+        # @param [ Hash... ] *criteria The key value pair(s) for $all matching.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def all(*criteria)
           if criteria.empty?
             return clone.tap do |query|
@@ -78,22 +69,37 @@ module Mongoid
         # @example Add the criterion.
         #   selectable.and({ field: value }, { other: value })
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects that all must match to return results.
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
+        #   Multiple key/value pair matches or Criteria objects that all must
+        #   match to return results.
         #
         # @return [ Selectable ] The new selectable.
-        #
-        # @since 1.0.0
         def and(*criteria)
           _mongoid_flatten_arrays(criteria).inject(self.clone) do |c, new_s|
             if new_s.is_a?(Selectable)
               new_s = new_s.selector
             end
-            normalized = _mongoid_normalize_expr(new_s)
+            normalized = _mongoid_expand_keys(new_s)
             normalized.each do |k, v|
               k = k.to_s
               if c.selector[k]
-                c = c.send(:__multi__, [k => v], '$and')
+                # There is already a condition on k.
+                # If v is an operator, and all existing conditions are
+                # also operators, and v isn't present in existing conditions,
+                # we can add to existing conditions.
+                # Otherwise use $and.
+                if v.is_a?(Hash) &&
+                  v.length == 1 &&
+                  (new_k = v.keys.first).start_with?('$') &&
+                  (existing_kv = c.selector[k]).is_a?(Hash) &&
+                  !existing_kv.key?(new_k) &&
+                  existing_kv.keys.all? { |sub_k| sub_k.start_with?('$') }
+                then
+                  merged_v = c.selector[k].merge(v)
+                  c.selector.store(k, merged_v)
+                else
+                  c = c.send(:__multi__, [k => v], '$and')
+                end
               else
                 c.selector.store(k, v)
               end
@@ -114,8 +120,6 @@ module Mongoid
         # @param [ Hash ] criterion Multiple key/range pairs.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def between(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :between
@@ -146,14 +150,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/match pairs.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def elem_match(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :elem_match
           end
 
-          __override__(criterion, "$elemMatch")
+          and_or_override(criterion, "$elemMatch")
         end
         key :elem_match, :override, "$elemMatch"
 
@@ -171,19 +173,17 @@ module Mongoid
         # @param [ Hash ] criterion The field/boolean existence checks.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def exists(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :exists
           end
 
           typed_override(criterion, "$exists") do |value|
-            ::Boolean.evolve(value)
+            Mongoid::Boolean.evolve(value)
           end
         end
         key :exists, :override, "$exists" do |value|
-          ::Boolean.evolve(value)
+          Mongoid::Boolean.evolve(value)
         end
 
         # Add a $geoIntersects or $geoWithin selection. Symbol operators must
@@ -200,35 +200,34 @@ module Mongoid
         #   the upper right (north east) as the second argument.
         #   Important: When latitude and longitude are passed, longitude is
         #   expected as the first element of the coordinate pair.
-        #   Source: https://docs.mongodb.com/manual/reference/operator/query/box/
+        #   Source: https://www.mongodb.com/docs/manual/reference/operator/query/box/
         #
         # @example Add a geo intersect criterion for a line.
-        #   query.geo_spacial(:location.intersects_line => [[ 1, 10 ], [ 2, 10 ]])
+        #   query.geo_spatial(:location.intersects_line => [[ 1, 10 ], [ 2, 10 ]])
         #
         # @example Add a geo intersect criterion for a point.
-        #   query.geo_spacial(:location.intersects_point => [[ 1, 10 ]])
+        #   query.geo_spatial(:location.intersects_point => [[ 1, 10 ]])
         #
         # @example Add a geo intersect criterion for a polygon.
-        #   query.geo_spacial(:location.intersects_polygon => [[ 1, 10 ], [ 2, 10 ], [ 1, 10 ]])
+        #   query.geo_spatial(:location.intersects_polygon => [[ 1, 10 ], [ 2, 10 ], [ 1, 10 ]])
         #
         # @example Add a geo within criterion for a polygon.
-        #   query.geo_spacial(:location.within_polygon => [[ 1, 10 ], [ 2, 10 ], [ 1, 10 ]])
+        #   query.geo_spatial(:location.within_polygon => [[ 1, 10 ], [ 2, 10 ], [ 1, 10 ]])
         #
         # @example Add a geo within criterion for a box.
-        #   query.geo_spacial(:location.within_box => [[ 1, 10 ], [ 2, 10 ])
+        #   query.geo_spatial(:location.within_box => [[ 1, 10 ], [ 2, 10 ])
         #
         # @param [ Hash ] criterion The criterion.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 2.0.0
-        def geo_spacial(criterion)
+        def geo_spatial(criterion)
           if criterion.nil?
-            raise Errors::CriteriaArgumentRequired, :geo_spacial
+            raise Errors::CriteriaArgumentRequired, :geo_spatial
           end
 
           __merge__(criterion)
         end
+
         key :intersects_line, :override, "$geoIntersects", "$geometry" do |value|
           { "type" => LINE_STRING, "coordinates" => value }
         end
@@ -243,6 +242,26 @@ module Mongoid
         end
         key :within_box, :override, "$geoWithin", "$box"
 
+        # Add the $eq criterion to the selector.
+        #
+        # @example Add the $eq criterion.
+        #   selectable.eq(age: 60)
+        #
+        # @example Execute an $eq in a where query.
+        #   selectable.where(:field.eq => 10)
+        #
+        # @param [ Hash ] criterion The field/value pairs to check.
+        #
+        # @return [ Selectable ] The cloned selectable.
+        def eq(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :eq
+          end
+
+          and_or_override(criterion, "$eq")
+        end
+        key :eq, :override, "$eq"
+
         # Add the $gt criterion to the selector.
         #
         # @example Add the $gt criterion.
@@ -254,14 +273,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/value pairs to check.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def gt(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :gt
           end
 
-          __override__(criterion, "$gt")
+          and_or_override(criterion, "$gt")
         end
         key :gt, :override, "$gt"
 
@@ -276,14 +293,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/value pairs to check.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def gte(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :gte
           end
 
-          __override__(criterion, "$gte")
+          and_or_override(criterion, "$gte")
         end
         key :gte, :override, "$gte"
 
@@ -301,8 +316,6 @@ module Mongoid
         # @param [ Hash ] condition The field/value criterion pairs.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def in(condition)
           if condition.nil?
             raise Errors::CriteriaArgumentRequired, :in
@@ -336,14 +349,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/value pairs to check.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def lt(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :lt
           end
 
-          __override__(criterion, "$lt")
+          and_or_override(criterion, "$lt")
         end
         key :lt, :override, "$lt"
 
@@ -358,14 +369,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/value pairs to check.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def lte(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :lte
           end
 
-          __override__(criterion, "$lte")
+          and_or_override(criterion, "$lte")
         end
         key :lte, :override, "$lte"
 
@@ -377,8 +386,6 @@ module Mongoid
         # @param [ Hash ] criterion The field/distance pairs.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def max_distance(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :max_distance
@@ -399,14 +406,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/mod selections.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def mod(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :mod
           end
 
-          __override__(criterion, "$mod")
+          and_or_override(criterion, "$mod")
         end
         key :mod, :override, "$mod"
 
@@ -421,14 +426,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/ne selections.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def ne(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :ne
           end
 
-          __override__(criterion, "$ne")
+          and_or_override(criterion, "$ne")
         end
         alias :excludes :ne
         key :ne, :override, "$ne"
@@ -444,14 +447,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/location pair.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def near(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :near
           end
 
-          __override__(criterion, "$near")
+          and_or_override(criterion, "$near")
         end
         key :near, :override, "$near"
 
@@ -466,14 +467,12 @@ module Mongoid
         # @param [ Hash ] criterion The field/location pair.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def near_sphere(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :near_sphere
           end
 
-          __override__(criterion, "$nearSphere")
+          and_or_override(criterion, "$nearSphere")
         end
         key :near_sphere, :override, "$nearSphere"
 
@@ -491,8 +490,6 @@ module Mongoid
         # @param [ Hash ] condition The field/value criterion pairs.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def nin(condition)
           if condition.nil?
             raise Errors::CriteriaArgumentRequired, :nin
@@ -520,12 +517,10 @@ module Mongoid
         # @example Add the $nor selection.
         #   selectable.nor(field: 1, field: 2)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects.
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
+        #   Multiple key/value pair matches or Criteria objects.
         #
         # @return [ Selectable ] The new selectable.
-        #
-        # @since 1.0.0
         def nor(*criteria)
           _mongoid_add_top_level_operation('$nor', criteria)
         end
@@ -535,9 +530,7 @@ module Mongoid
         # @example Is the selectable negating?
         #   selectable.negating?
         #
-        # @return [ true, false ] If the selectable is negating.
-        #
-        # @since 1.0.0
+        # @return [ true | false ] If the selectable is negating.
         def negating?
           !!negating
         end
@@ -553,12 +546,10 @@ module Mongoid
         # @example Execute a $not in a where query.
         #   selectable.where(:field.not => /Bob/)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        # @param [ [ Hash | Criteria ]... ] *criteria The key/value pair
         #   matches or Criteria objects to negate.
         #
         # @return [ Selectable ] The new selectable.
-        #
-        # @since 1.0.0
         def not(*criteria)
           if criteria.empty?
             dup.tap { |query| query.negating = true }
@@ -567,17 +558,21 @@ module Mongoid
               if new_s.is_a?(Selectable)
                 new_s = new_s.selector
               end
-              new_s.each do |k, v|
+              _mongoid_expand_keys(new_s).each do |k, v|
                 k = k.to_s
-                if c.selector[k] || k[0] == ?$
+                if c.selector[k] || k.start_with?('$')
                   c = c.send(:__multi__, [{'$nor' => [{k => v}]}], '$and')
                 else
-                  if v.is_a?(Regexp)
-                    negated_operator = '$not'
+                  if v.is_a?(Hash)
+                    c = c.send(:__multi__, [{'$nor' => [{k => v}]}], '$and')
                   else
-                    negated_operator = '$ne'
+                    if v.is_a?(Regexp)
+                      negated_operator = '$not'
+                    else
+                      negated_operator = '$ne'
+                    end
+                    c = c.send(:__override__, {k => v}, negated_operator)
                   end
-                  c = c.send(:__override__, {k => v}, negated_operator)
                 end
               end
               c
@@ -586,6 +581,35 @@ module Mongoid
         end
         key :not, :override, "$not"
 
+        # Negate the arguments, constraining the query to only those documents
+        # that do NOT match the arguments.
+        #
+        # @example Exclude a single criterion.
+        #   selectable.none_of(name: /Bob/)
+        #
+        # @example Exclude multiple criteria.
+        #   selectable.none_of(name: /Bob/, country: "USA")
+        #
+        # @example Exclude multiple criteria as an array.
+        #   selectable.none_of([{ name: /Bob/ }, { country: "USA" }])
+        #
+        # @param [ [ Hash | Criteria ]... ] *criteria The key/value pair
+        #   matches or Criteria objects to negate.
+        #
+        # @return [ Selectable ] The new selectable.
+        def none_of(*criteria)
+          criteria = _mongoid_flatten_arrays(criteria)
+          return dup if criteria.empty?
+
+          exprs = criteria.map do |criterion|
+            _mongoid_expand_keys(
+                criterion.is_a?(Selectable) ?
+                  criterion.selector : criterion)
+          end
+
+          self.and('$nor' => exprs)
+        end
+
         # Creates a disjunction using $or from the existing criteria in the
         # receiver and the provided arguments.
         #
@@ -611,13 +635,11 @@ module Mongoid
         # @example Same as previous example, also deprecated.
         #   selectable.or([{field: 1}], [{field: 2}])
         #
-        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
         #   Multiple key/value pair matches or Criteria objects, or arrays
         #   thereof. Passing arrays is deprecated.
         #
         # @return [ Selectable ] The new selectable.
-        #
-        # @since 1.0.0
         def or(*criteria)
           _mongoid_add_top_level_operation('$or', criteria)
         end
@@ -643,13 +665,11 @@ module Mongoid
         # @example Same as previous example, also deprecated.
         #   selectable.any_of([{field: 1}], [{field: 2}])
         #
-        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
         #   Multiple key/value pair matches or Criteria objects, or arrays
         #   thereof. Passing arrays is deprecated.
         #
         # @return [ Selectable ] The new selectable.
-        #
-        # @since 1.0.0
         def any_of(*criteria)
           criteria = _mongoid_flatten_arrays(criteria)
           case criteria.length
@@ -665,7 +685,7 @@ module Mongoid
             # and add the result to self.
             exprs = criteria.map do |criterion|
               if criterion.is_a?(Selectable)
-                _mongoid_normalize_expr(criterion.selector)
+                _mongoid_expand_keys(criterion.selector)
               else
                 Hash[criterion.map do |k, v|
                   if k.is_a?(Symbol)
@@ -676,16 +696,7 @@ module Mongoid
                 end]
               end
             end
-            # Should be able to do:
-            #where('$or' => exprs)
-            # But since that is broken do instead:
-            clone.tap do |query|
-              if query.selector['$or']
-                query.selector.store('$or', query.selector['$or'] + exprs)
-              else
-                query.selector.store('$or', exprs)
-              end
-            end
+            self.and('$or' => exprs)
           end
         end
 
@@ -703,8 +714,6 @@ module Mongoid
         # @param [ Hash ] criterion The field/size pairs criterion.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def with_size(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :with_size
@@ -731,8 +740,6 @@ module Mongoid
         # @param [ Hash ] criterion The field/type pairs.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def with_type(criterion)
           if criterion.nil?
             raise Errors::CriteriaArgumentRequired, :with_type
@@ -754,19 +761,17 @@ module Mongoid
         # @example Construct a text search selector with options.
         #   selectable.text_search("testing", :$language => "fr")
         #
-        # @note Per https://docs.mongodb.com/manual/reference/operator/query/text/
+        # @note Per https://www.mongodb.com/docs/manual/reference/operator/query/text/
         #   it is not currently possible to supply multiple text search
         #   conditions in a query. Mongoid will build such a query but the
         #   server will return an error when trying to execute it.
         #
-        # @param [ String, Symbol ] terms A string of terms that MongoDB parses
+        # @param [ String | Symbol ] terms A string of terms that MongoDB parses
         #   and uses to query the text index.
         # @param [ Hash ] opts Text search options. See MongoDB documentation
         #   for options.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 2.2.0
         def text_search(terms, opts = nil)
           if terms.nil?
             raise Errors::CriteriaArgumentRequired, :terms
@@ -776,7 +781,7 @@ module Mongoid
             criterion = {'$text' => { '$search' => terms }}
             criterion['$text'].merge!(opts) if opts
             if query.selector['$text']
-              # Per https://docs.mongodb.com/manual/reference/operator/query/text/
+              # Per https://www.mongodb.com/docs/manual/reference/operator/query/text/
               # multiple $text expressions are not currently supported by
               # MongoDB server, but build the query correctly instead of
               # overwriting previous text search condition with the currently
@@ -799,11 +804,10 @@ module Mongoid
         # @example Add a javascript selection.
         #   selectable.where("this.name == 'syd'")
         #
-        # @param [ String, Hash ] criterion The javascript or standard selection.
+        # @param [ [ Hash | String ]... ] *criterion The standard selection
+        #   or javascript string.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         def where(*criteria)
           criteria.inject(clone) do |query, criterion|
             if criterion.nil?
@@ -843,23 +847,24 @@ module Mongoid
         # @param [ Hash ] criterion The field/value pairs.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         # @api private
         def expr_query(criterion)
           if criterion.nil?
             raise ArgumentError, 'Criterion cannot be nil here'
           end
+          unless Hash === criterion
+            raise Errors::InvalidQuery, "Expression must be a Hash: #{Errors::InvalidQuery.truncate_expr(criterion)}"
+          end
 
+          normalized = _mongoid_expand_keys(criterion)
           clone.tap do |query|
-            criterion.each do |field, value|
+            normalized.each do |field, value|
               field_s = field.to_s
-              if field_s[0] == ?$
+              if field_s.start_with?('$')
                 # Query expression-level operator, like $and or $where
                 query.add_operator_expression(field_s, value)
               else
-                exp_field, exp_value = expand_one_condition(field, value)
-                query.add_field_expression(exp_field, exp_value)
+                query.add_field_expression(field, value)
               end
             end
             query.reset_strategies!
@@ -876,11 +881,9 @@ module Mongoid
         #   end
         #
         # @param [ Hash ] criterion The criterion.
-        #
-        # @since 1.0.0
         def typed_override(criterion, operator)
           if criterion
-            criterion.update_values do |value|
+            criterion.transform_values! do |value|
               yield(value)
             end
           end
@@ -897,8 +900,6 @@ module Mongoid
         # @param [ String ] criterion The javascript as a string.
         #
         # @return [ Selectable ] The cloned selectable
-        #
-        # @since 1.0.0
         def js_query(criterion)
           clone.tap do |query|
             if negating?
@@ -920,8 +921,6 @@ module Mongoid
         # @param [ Hash ] criterion The selection to store.
         #
         # @return [ Selectable ] The cloned selectable.
-        #
-        # @since 1.0.0
         # @api private
         def selection(criterion = nil)
           clone.tap do |query|
@@ -934,6 +933,22 @@ module Mongoid
           end
         end
 
+        # Combine operator expessions onto a Criteria using either
+        # an override or ands depending on the status of the
+        # Mongoid.overwrite_chained_operators feature flag.
+        #
+        # @param [ Hash ] The criterion to add to the criteria.
+        # @param [ String ] operator The MongoDB operator.
+        #
+        # @return [ Criteria ] The resulting criteria.
+        def and_or_override(criterion, operator)
+          if Mongoid.overwrite_chained_operators
+            __override__(criterion, operator)
+          else
+            and_with_operator(criterion, operator)
+          end
+        end
+
         class << self
 
           # Get the methods on the selectable that can be forwarded to from a model.
@@ -942,8 +957,6 @@ module Mongoid
           #   Selectable.forwardables
           #
           # @return [ Array<Symbol> ] The names of the forwardable methods.
-          #
-          # @since 1.0.0
           def forwardables
             public_instance_methods(false) -
               [ :negating, :negating=, :negating?, :selector, :selector= ]