mongoid 7.2.1 → 9.0.0

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   class Criteria
@@ -17,8 +17,6 @@ module Mongoid
         #   mergeable.intersect.in(field: [ 1, 2, 3 ])
         #
         # @return [ Mergeable ] The intersect flagged mergeable.
-        #
-        # @since 1.0.0
         def intersect
           use(:__intersect__)
         end
@@ -29,8 +27,6 @@ module Mongoid
         #   mergeable.override.in(field: [ 1, 2, 3 ])
         #
         # @return [ Mergeable ] The override flagged mergeable.
-        #
-        # @since 1.0.0
         def override
           use(:__override__)
         end
@@ -41,8 +37,6 @@ module Mongoid
         #   mergeable.union.in(field: [ 1, 2, 3 ])
         #
         # @return [ Mergeable ] The union flagged mergeable.
-        #
-        # @since 1.0.0
         def union
           use(:__union__)
         end
@@ -53,14 +47,33 @@ module Mongoid
         #   mergeable.reset_strategies!
         #
         # @return [ Criteria ] self.
-        #
-        # @since 1.0.0
         def reset_strategies!
           self.strategy = nil
           self.negating = nil
           self
         end
 
+        # Merge criteria with operators using the and operator.
+        #
+        # @param [ Hash ] criterion The criterion to add to the criteria.
+        # @param [ String ] operator The MongoDB operator.
+        #
+        # @return [ Criteria ] The resulting criteria.
+        def and_with_operator(criterion, operator)
+          crit = self
+          if criterion
+            criterion.each_pair do |field, value|
+              val = prepare(field, operator, value)
+              # The prepare method already takes the negation into account. We
+              # set negating to false here so that ``and`` doesn't also apply
+              # negation and we have a double negative.
+              crit.negating = false
+              crit = crit.and(field => val)
+            end
+          end
+          crit
+        end
+
         private
 
         # Adds the criterion to the existing selection.
@@ -74,8 +87,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __add__(criterion, operator)
           with_strategy(:__add__, criterion, operator)
         end
@@ -92,8 +103,6 @@ module Mongoid
         # @param [ String ] inner The inner MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __expanded__(criterion, outer, inner)
           selection(criterion) do |selector, field, value|
             selector.store(field, { outer => { inner => value }})
@@ -111,8 +120,6 @@ module Mongoid
         # @param [ Hash ] criterion The criteria.
         #
         # @return [ Mergeable ] The cloned object.
-        #
-        # @since 2.0.0
         def __merge__(criterion)
           selection(criterion) do |selector, field, value|
             selector.merge!(field.__expr_part__(value))
@@ -130,8 +137,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __intersect__(criterion, operator)
           with_strategy(:__intersect__, criterion, operator)
         end
@@ -152,8 +157,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __multi__(criteria, operator)
           clone.tap do |query|
             sel = query.selector
@@ -171,7 +174,7 @@ module Mongoid
 
         # Combines criteria into a MongoDB selector.
         #
-        # Criteria is an array of criterions which will be flattened.
+        # Criteria is an array of criterion objects which will be flattened.
         #
         # Each criterion can be:
         # - A hash
@@ -227,7 +230,16 @@ module Mongoid
         end
 
         # Takes a criteria hash and expands Key objects into hashes containing
-        # MQL corresponding to said key objects.
+        # MQL corresponding to said key objects. Also converts the input to
+        # BSON::Document to permit indifferent access.
+        #
+        # The argument must be a hash containing key-value pairs of the
+        # following forms:
+        # - {field_name: value}
+        # - {'field_name' => value}
+        # - {key_instance: value}
+        # - {:$operator => operator_value_expression}
+        # - {'$operator' => operator_value_expression}
         #
         # Ruby does not permit multiple symbol operators. For example,
         # {:foo.gt => 1, :foo.gt => 2} is collapsed to {:foo.gt => 2} by the
@@ -237,19 +249,23 @@ module Mongoid
         # Similarly, this method should never need to expand a literal value
         # and an operator at the same time.
         #
+        # This method effectively converts symbol keys to string keys in
+        # the input +expr+, such that the downstream code can assume that
+        # conditions always contain string keys.
+        #
         # @param [ Hash ] expr Criteria including Key instances.
         #
-        # @return [ Hash ] The expanded criteria.
+        # @return [ BSON::Document ] The expanded criteria.
         private def _mongoid_expand_keys(expr)
           unless expr.is_a?(Hash)
             raise ArgumentError, 'Argument must be a Hash'
           end
 
-          result = {}
+          result = BSON::Document.new
           expr.each do |field, value|
-            field.__expr_part__(value.__expand_complex__).each do |k, v|
-              if result[k]
-                if result[k].is_a?(Hash)
+            field.__expr_part__(value.__expand_complex__, negating?).each do |k, v|
+              if existing = result[k]
+                if existing.is_a?(Hash)
                   # Existing value is an operator.
                   # If new value is also an operator, ensure there are no
                   # conflicts and add
@@ -257,8 +273,8 @@ module Mongoid
                     # The new value is also an operator.
                     # If there are no conflicts, combine the hashes, otherwise
                     # add new conditions to top level with $and.
-                    if (v.keys & result[k].keys).empty?
-                      result[k].update(v)
+                    if (v.keys & existing.keys).empty?
+                      existing.update(v)
                     else
                       raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
                       result['$and'] ||= []
@@ -266,26 +282,39 @@ module Mongoid
                     end
                   else
                     # The new value is a simple value.
-                    # If there isn't an $eq operator already in the query,
-                    # transform the new value into an $eq operator and add it
-                    # to the existing hash. Otherwise add the new condition
-                    # with $and to the top level.
-                    if result[k].key?('$eq')
+                    # Transform the implicit equality to either $eq or $regexp
+                    # depending on the type of the argument. See
+                    # https://www.mongodb.com/docs/manual/reference/operator/query/eq/#std-label-eq-usage-examples
+                    # for the description of relevant server behavior.
+                    op = case v
+                    when Regexp, BSON::Regexp::Raw
+                      '$regex'
+                    else
+                      '$eq'
+                    end
+                    # If there isn't an $eq/$regex operator already in the
+                    # query, transform the new value into an operator
+                    # expression and add it to the existing hash. Otherwise
+                    # add the new condition with $and to the top level.
+                    if existing.key?(op)
                       raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
                       result['$and'] ||= []
                       result['$and'] << {k => v}
                     else
-                      result[k].update('$eq' => v)
+                      existing.update(op => v)
                     end
                   end
                 else
                   # Existing value is a simple value.
-                  # If we are adding an operator, and the operator is not $eq,
-                  # convert existing value into $eq and add the new operator
-                  # to the same hash. Otherwise add the new condition with $and
-                  # to the top level.
-                  if v.is_a?(Hash) && !v.key?('$eq')
-                    result[k] = {'$eq' => result[k]}.update(v)
+                  # See the notes above about transformations to $eq/$regex.
+                  op = case existing
+                  when Regexp, BSON::Regexp::Raw
+                    '$regex'
+                  else
+                    '$eq'
+                  end
+                  if v.is_a?(Hash) && !v.key?(op)
+                    result[k] = {op => existing}.update(v)
                   else
                     raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
                     result['$and'] ||= []
@@ -311,8 +340,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __override__(criterion, operator)
           if criterion.is_a?(Selectable)
             criterion = criterion.selector
@@ -339,8 +366,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
-        #
-        # @since 1.0.0
         def __union__(criterion, operator)
           with_strategy(:__union__, criterion, operator)
         end
@@ -355,8 +380,6 @@ module Mongoid
         # @param [ Symbol ] strategy The strategy to use.
         #
         # @return [ Mergeable ] The existing mergeable.
-        #
-        # @since 1.0.0
         def use(strategy)
           tap do |mergeable|
             mergeable.strategy = strategy
@@ -375,8 +398,6 @@ module Mongoid
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The cloned query.
-        #
-        # @since 1.0.0
         def with_strategy(strategy, criterion, operator)
           selection(criterion) do |selector, field, value|
             selector.store(
@@ -397,8 +418,6 @@ module Mongoid
         # @param [ Object ] value The value.
         #
         # @return [ Object ] The serialized value.
-        #
-        # @since 1.0.0
         def prepare(field, operator, value)
           unless operator =~ /exists|type|size/
             value = value.__expand_complex__

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   class Criteria
@@ -18,11 +18,9 @@ module Mongoid
         # @example Add ascending sorting.
         #   optional.ascending(:first_name, :last_name)
         #
-        # @param [ Array<Symbol> ] fields The fields to sort.
+        # @param [ Symbol... ] *fields The field(s) to sort.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def ascending(*fields)
           sort_with_list(*fields, 1)
         end
@@ -39,8 +37,6 @@ module Mongoid
         # @param [ Integer ] value The batch size.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def batch_size(value = nil)
           option(value) { |options| options.store(:batch_size, value) }
         end
@@ -50,11 +46,9 @@ module Mongoid
         # @example Add descending sorting.
         #   optional.descending(:first_name, :last_name)
         #
-        # @param [ Array<Symbol> ] fields The fields to sort.
+        # @param [ Symbol... ] *fields The field(s) to sort.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def descending(*fields)
           sort_with_list(*fields, -1)
         end
@@ -70,8 +64,6 @@ module Mongoid
         # @param [ Hash ] value The index hint.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def hint(value = nil)
           option(value) { |options| options.store(:hint, value) }
         end
@@ -84,8 +76,6 @@ module Mongoid
         # @param [ Integer ] value The number of documents to return.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def limit(value = nil)
           option(value) do |options, query|
             val = value.to_i
@@ -103,8 +93,6 @@ module Mongoid
         # @param [ Integer ] value The max number of documents to scan.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def max_scan(value = nil)
           option(value) { |options| options.store(:max_scan, value) }
         end
@@ -117,8 +105,6 @@ module Mongoid
         # @param [ Integer ] value The max time in milliseconds for processing operations on a cursor.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 6.0.0
         def max_time_ms(value = nil)
           option(value) { |options| options.store(:max_time_ms, value) }
         end
@@ -129,8 +115,6 @@ module Mongoid
         #   optional.no_timeout
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def no_timeout
           clone.tap { |query| query.options.store(:timeout, false) }
         end
@@ -140,11 +124,9 @@ module Mongoid
         # @example Limit the results to the provided fields.
         #   optional.only(:name, :dob)
         #
-        # @param [ Array<Symbol> ] args The fields to return.
+        # @param [ Symbol... ] *args The field(s) to return.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def only(*args)
           args = args.flatten
           option(*args) do |options|
@@ -182,11 +164,9 @@ module Mongoid
         # @example Add sorting options via a string.
         #   optional.order_by("name ASC, dob DESC")
         #
-        # @param [ Array, Hash, String ] spec The sorting specification.
+        # @param [ [ Array | Hash | String ]... ] *spec The sorting specification.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def order_by(*spec)
           option(spec) do |options, query|
             spec.compact.each do |criterion|
@@ -205,11 +185,9 @@ module Mongoid
         # @example Replace the ordering.
         #   optional.reorder(name: :asc)
         #
-        # @param [ Array, Hash, String ] spec The sorting specification.
+        # @param [ [ Array | Hash | String ]... ] *spec The sorting specification.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 2.1.0
         def reorder(*spec)
           clone.tap do |query|
             query.options.delete(:sort)
@@ -224,8 +202,6 @@ module Mongoid
         # @param [ Integer ] value The number to skip.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def skip(value = nil)
           option(value) do |options, query|
             val = value.to_i
@@ -243,8 +219,6 @@ module Mongoid
         # @param [ Hash ] criterion The slice options.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def slice(criterion = nil)
           option(criterion) do |options|
             options.__union__(
@@ -261,8 +235,6 @@ module Mongoid
         #   optional.snapshot
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def snapshot
           clone.tap do |query|
             query.options.store(:snapshot, true)
@@ -274,11 +246,9 @@ module Mongoid
         # @example Limit the results to the fields not provided.
         #   optional.without(:name, :dob)
         #
-        # @param [ Array<Symbol> ] args The fields to ignore.
+        # @param [ Symbol... ] *args The field(s) to ignore.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def without(*args)
           args = args.flatten
           option(*args) do |options|
@@ -301,8 +271,6 @@ module Mongoid
         # @param [ String ] comment The comment to be associated with the query.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 2.2.0
         def comment(comment = nil)
           clone.tap do |query|
             query.options.store(:comment, comment)
@@ -320,8 +288,6 @@ module Mongoid
         # @param [ Symbol ] type The type of cursor to create.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 2.2.0
         def cursor_type(type)
           clone.tap { |query| query.options.store(:cursor_type, type) }
         end
@@ -334,8 +300,6 @@ module Mongoid
         # @param [ Hash ] collation_doc The document describing the collation to use.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 6.1.0
         def collation(collation_doc)
           clone.tap { |query| query.options.store(:collation, collation_doc) }
         end
@@ -354,18 +318,10 @@ module Mongoid
         # @param [ Integer ] direction The sort direction.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def add_sort_option(options, field, direction)
-          if driver == :mongo1x
-            sorting = (options[:sort] || []).dup
-            sorting.push([ field, direction ])
-            options.store(:sort, sorting)
-          else
-            sorting = (options[:sort] || {}).dup
-            sorting[field] = direction
-            options.store(:sort, sorting)
-          end
+          sorting = (options[:sort] || {}).dup
+          sorting[field] = direction
+          options.store(:sort, sorting)
         end
 
         # Take the provided criterion and store it as an option in the query
@@ -376,11 +332,9 @@ module Mongoid
         # @example Store the option.
         #   optional.option({ skip: 10 })
         #
-        # @param [ Array ] args The options.
+        # @param [ Object... ] *args The options.
         #
         # @return [ Queryable ] The cloned queryable.
-        #
-        # @since 1.0.0
         def option(*args)
           clone.tap do |query|
             unless args.compact.empty?
@@ -396,12 +350,10 @@ module Mongoid
         # @example Add multiple sort options.
         #   optional.sort_with_list(:name, :dob, 1)
         #
-        # @param [ Array<String> ] fields The field names.
+        # @param [ [ Symbol | String ]... ] *fields The field name(s).
         # @param [ Integer ] direction The sort direction.
         #
         # @return [ Optional ] The cloned optional.
-        #
-        # @since 1.0.0
         def sort_with_list(*fields, direction)
           option(fields) do |options, query|
             fields.flatten.compact.each do |field|
@@ -419,8 +371,6 @@ module Mongoid
           #   Optional.forwardables
           #
           # @return [ Array<Symbol> ] The names of the forwardable methods.
-          #
-          # @since 1.0.0
           def forwardables
             public_instance_methods(false) - [ :options, :options= ]
           end

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   class Criteria
@@ -15,8 +15,6 @@ module Mongoid
         #   options.fields
         #
         # @return [ Hash ] The fields options.
-        #
-        # @since 1.0.0
         def fields
           self[:fields]
         end
@@ -27,8 +25,6 @@ module Mongoid
         #   options.limit
         #
         # @return [ Integer ] The limit option.
-        #
-        # @since 1.0.0
         def limit
           self[:limit]
         end
@@ -39,8 +35,6 @@ module Mongoid
         #   options.skip
         #
         # @return [ Integer ] The skip option.
-        #
-        # @since 1.0.0
         def skip
           self[:skip]
         end
@@ -51,8 +45,6 @@ module Mongoid
         #   options.sort
         #
         # @return [ Hash ] The sort options.
-        #
-        # @since 1.0.0
         def sort
           self[:sort]
         end
@@ -63,12 +55,10 @@ module Mongoid
         # @example Store a value in the options.
         #   options.store(:key, "testing")
         #
-        # @param [ String, Symbol ] key The name of the attribute.
+        # @param [ String | Symbol ] key The name of the attribute.
         # @param [ Object ] value The value to add.
         #
         # @return [ Object ] The stored object.
-        #
-        # @since 1.0.0
         def store(key, value, localize = true)
           super(key, evolve(value, localize))
         end
@@ -80,8 +70,6 @@ module Mongoid
         #   options.to_pipeline
         #
         # @return [ Array<Hash> ] The options in pipeline form.
-        #
-        # @since 2.0.0
         def to_pipeline
           pipeline = []
           pipeline.push({ "$skip" => skip }) if skip
@@ -96,10 +84,8 @@ module Mongoid
         #   options.__deep_copy__
         #
         # @return [ Options ] The copied options.
-        #
-        # @since 6.1.1
         def __deep_copy__
-          self.class.new(aliases, serializers) do |copy|
+          self.class.new(aliases, serializers, associations, aliased_associations) do |copy|
             each_pair do |key, value|
               copy.merge!(key => value.__deep_copy__)
             end
@@ -118,8 +104,6 @@ module Mongoid
         # @param [ Object ] value The value to serialize.
         #
         # @return [ Object ] The serialized object.
-        #
-        # @since 1.0.0
         def evolve(value, localize = true)
           case value
           when Hash
@@ -139,8 +123,6 @@ module Mongoid
         # @param [ Hash ] value The hash to serialize.
         #
         # @return [ Object ] The serialized hash.
-        #
-        # @since 1.0.0
         def evolve_hash(value, localize = true)
           value.inject({}) do |hash, (field, _value)|
             name, serializer = storage_pair(field)

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

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   class Criteria
     module Queryable
 
       # Represents an aggregation pipeline.
-      #
-      # @since 2.0.0
       class Pipeline < Array
 
         # @attribute [r] aliases The field aliases.
@@ -20,8 +18,6 @@ module Mongoid
         #   pipeline.__deep_copy__
         #
         # @return [ Pipeline ] The cloned pipeline.
-        #
-        # @since 2.0.0
         def __deep_copy__
           self.class.new(aliases) do |copy|
             each do |entry|
@@ -38,8 +34,6 @@ module Mongoid
         # @param [ Hash ] entry The group entry.
         #
         # @return [ Pipeline ] The pipeline.
-        #
-        # @since 2.0.0
         def group(entry)
           push("$group" => evolve(entry.__expand_complex__))
         end
@@ -51,8 +45,6 @@ module Mongoid
         #
         # @param [ Hash ] aliases A hash of mappings from aliases to the actual
         #   field names in the database.
-        #
-        # @since 2.0.0
         def initialize(aliases = {})
           @aliases = aliases
           yield(self) if block_given?
@@ -76,12 +68,10 @@ module Mongoid
         #   pipeline.unwind(:field)
         #   pipeline.unwind(document)
         #
-        # @param [ String, Symbol, Hash ] field_or_doc A field name or a
+        # @param [ String | Symbol | Hash ] field_or_doc A field name or a
         #   document.
         #
         # @return [ Pipeline ] The pipeline.
-        #
-        # @since 2.0.0
         def unwind(field_or_doc)
           unless field_or_doc.respond_to? :keys
             normalized = field_or_doc.to_s
@@ -104,8 +94,6 @@ module Mongoid
         # @param [ Hash ] entry The entry to evolve.
         #
         # @return [ Hash ] The evolved entry.
-        #
-        # @since 2.0.0
         def evolve(entry)
           aggregate = Selector.new(aliases)
           entry.each_pair do |field, value|