mongoid 7.2.1 → 9.0.0

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   class Criteria
@@ -12,18 +12,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 +32,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,12 +70,11 @@ 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)
@@ -130,8 +121,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
@@ -162,14 +151,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_with_operator(criterion, "$elemMatch")
         end
         key :elem_match, :override, "$elemMatch"
 
@@ -187,19 +174,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
@@ -216,7 +201,7 @@ 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_spatial(:location.intersects_line => [[ 1, 10 ], [ 2, 10 ]])
@@ -244,19 +229,6 @@ module Mongoid
           __merge__(criterion)
         end
 
-        # Alias for +geo_spatial+.
-        #
-        # @deprecated
-        def geo_spacial(criterion)
-          # Duplicate method body so that we can raise this exception with
-          # geo_spacial as the indicated operator rather than geo_spatial.
-          if criterion.nil?
-            raise Errors::CriteriaArgumentRequired, :geo_spacial
-          end
-
-          __merge__(criterion)
-        end
-
         key :intersects_line, :override, "$geoIntersects", "$geometry" do |value|
           { "type" => LINE_STRING, "coordinates" => value }
         end
@@ -271,6 +243,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_with_operator(criterion, "$eq")
+        end
+        key :eq, :override, "$eq"
+
         # Add the $gt criterion to the selector.
         #
         # @example Add the $gt criterion.
@@ -282,14 +274,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_with_operator(criterion, "$gt")
         end
         key :gt, :override, "$gt"
 
@@ -304,14 +294,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_with_operator(criterion, "$gte")
         end
         key :gte, :override, "$gte"
 
@@ -329,8 +317,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
@@ -364,14 +350,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_with_operator(criterion, "$lt")
         end
         key :lt, :override, "$lt"
 
@@ -386,14 +370,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_with_operator(criterion, "$lte")
         end
         key :lte, :override, "$lte"
 
@@ -405,8 +387,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
@@ -427,14 +407,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_with_operator(criterion, "$mod")
         end
         key :mod, :override, "$mod"
 
@@ -449,14 +427,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_with_operator(criterion, "$ne")
         end
         alias :excludes :ne
         key :ne, :override, "$ne"
@@ -472,14 +448,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_with_operator(criterion, "$near")
         end
         key :near, :override, "$near"
 
@@ -494,14 +468,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_with_operator(criterion, "$nearSphere")
         end
         key :near_sphere, :override, "$nearSphere"
 
@@ -519,8 +491,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
@@ -548,12 +518,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
@@ -563,9 +531,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
@@ -581,12 +547,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 }
@@ -597,7 +561,7 @@ module Mongoid
               end
               _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?(Hash)
@@ -618,6 +582,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.
         #
@@ -643,13 +636,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
@@ -675,13 +666,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
@@ -708,16 +697,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
 
@@ -735,8 +715,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
@@ -763,8 +741,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
@@ -786,19 +762,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
@@ -808,7 +782,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
@@ -831,11 +805,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?
@@ -875,26 +848,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|
-            unless Hash === criterion
-              raise Errors::InvalidQuery, "Expression must be a Hash: #{Errors::InvalidQuery.truncate_expr(criterion)}"
-            end
-            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!
@@ -911,11 +882,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
@@ -932,8 +901,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?
@@ -955,8 +922,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|
@@ -977,8 +942,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= ]