mongoid 7.2.1 → 9.0.0

data/lib/mongoid/findable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
 
   # This module defines the finder methods that hang off the document at the
   # class level.
-  #
-  # @since 4.0.0
   module Findable
     extend Forwardable
 
@@ -25,28 +23,45 @@ module Mongoid
       :each,
       :each_with_index,
       :extras,
+      :fifth,
+      :fifth!,
       :find_one_and_delete,
       :find_one_and_replace,
       :find_one_and_update,
       :find_or_create_by,
       :find_or_create_by!,
       :find_or_initialize_by,
+      :first!,
       :first_or_create,
       :first_or_create!,
       :first_or_initialize,
       :for_js,
-      :geo_near,
+      :fourth,
+      :fourth!,
       :includes,
+      :last!,
       :map_reduce,
       :max,
       :min,
       :none,
+      :pick,
       :pluck,
       :read,
+      :second,
+      :second!,
+      :second_to_last,
+      :second_to_last!,
       :sum,
+      :take,
+      :take!,
+      :tally,
       :text_search,
+      :third,
+      :third!,
+      :third_to_last,
+      :third_to_last!,
       :update,
-      :update_all
+      :update_all,
 
     # Returns a count of records in the database.
     # If you want to specify conditions use where.
@@ -75,7 +90,7 @@ module Mongoid
     # @example Are there no saved documents for this model?
     #   Person.empty?
     #
-    # @return [ true, false ] If the collection is empty.
+    # @return [ true | false ] If the collection is empty.
     def empty?
       count == 0
     end
@@ -86,9 +101,19 @@ module Mongoid
     # @example Do any documents exist for the conditions?
     #   Person.exists?
     #
-    # @return [ true, false ] If any documents exist for the conditions.
-    def exists?
-      with_default_scope.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.
+    #   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.
@@ -108,7 +133,7 @@ module Mongoid
     # even if its _id is given multiple times in the argument to +find+.
     # If the +raise_not_found_error+ Mongoid configuration option is truthy,
     # +Errors::DocumentNotFound+ exception is raised if any of the specified
-    # _ids were not found in the database. If the ++raise_not_found_error+
+    # _ids were not found in the database. If the +raise_not_found_error+
     # Mongoid configuration option is falsy, only those documents which are
     # found are returned; if no documents are found, the return value is an
     # empty array.
@@ -121,18 +146,32 @@ module Mongoid
     # strings will be transparently converted to +BSON::ObjectId+ instances
     # during query construction.
     #
+    # 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. If both a block and ids are
+    # given, the block is ignored and the documents for the given ids are
+    # returned. If a block and a Proc are given, the method delegates to
+    # +Enumerable#find+ and uses the proc as the default.
+    #
     # The +find+ method takes into account the default scope defined on the
     # model class, if any.
     #
-    # @param [ Object | Array<Object> ] args The _id values to find or an
-    #   array thereof.
+    # @note Each argument can be an individual id, an array of ids or
+    #   a nested array. Each array will be flattened.
+    #
+    # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #
     # @raise Errors::DocumentNotFound If not all documents are found and
     #   the +raise_not_found_error+ Mongoid configuration option is truthy.
-    def find(*args)
-      with_default_scope.find(*args)
+    def find(*args, &block)
+      empty_or_proc = args.empty? || (args.length == 1 && args.first.is_a?(Proc))
+      if block_given? && empty_or_proc
+        with_default_scope.find(*args, &block)
+      else
+        with_default_scope.find(*args)
+      end
     end
 
     # Find the first +Document+ given the conditions.
@@ -148,9 +187,7 @@ module Mongoid
     # @raise [ Errors::DocumentNotFound ] If no document found
     # and Mongoid.raise_not_found_error is true.
     #
-    # @return [ Document, nil ] A matching document.
-    #
-    # @since 3.0.0
+    # @return [ Document | nil ] A matching document.
     def find_by(attrs = {})
       result = where(attrs).find_first
       if result.nil? && Mongoid.raise_not_found_error
@@ -171,7 +208,6 @@ module Mongoid
     # @raise [ Errors::DocumentNotFound ] If no document found.
     #
     # @return [ Document ] A matching document.
-    #
     def find_by!(attrs = {})
       result = where(attrs).find_first
       raise(Errors::DocumentNotFound.new(self, attrs)) unless result
@@ -184,9 +220,11 @@ module Mongoid
     # @example Find the first document.
     #   Person.first
     #
+    # @param [ Integer ] limit The number of documents to return.
+    #
     # @return [ Document ] The first matching document.
-    def first
-      with_default_scope.first
+    def first(limit = nil)
+      with_default_scope.first(limit)
     end
     alias :one :first
 
@@ -195,9 +233,11 @@ module Mongoid
     # @example Find the last document.
     #   Person.last
     #
+    # @param [ Integer ] limit The number of documents to return.
+    #
     # @return [ Document ] The last matching document.
-    def last
-      with_default_scope.last
+    def last(limit = nil)
+      with_default_scope.last(limit)
     end
   end
 end

data/lib/mongoid/indexable/specification.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Indexable
 
     # Encapsulates behavior around an index specification.
-    #
-    # @since 4.0.0
     class Specification
 
       # The mappings of nice Ruby-style names to the corresponding driver
       # option name.
-      #
-      # @since 4.0.0
       MAPPINGS = {
         expire_after_seconds: :expire_after
       }
@@ -32,9 +28,7 @@ module Mongoid
       #
       # @param [ Specification ] other The spec to compare against.
       #
-      # @return [ true, false ] If the specs are equal.
-      #
-      # @since 4.0.0
+      # @return [ true | false ] If the specs are equal.
       def ==(other)
         fields == other.fields && key == other.key
       end
@@ -47,15 +41,13 @@ module Mongoid
       # @param [ Class ] klass The class the index is defined on.
       # @param [ Hash ] key The hash of name/direction pairs.
       # @param [ Hash ] opts the index options.
-      #
-      # @since 4.0.0
       def initialize(klass, key, opts = nil)
         options = opts || {}
         Validators::Options.validate(klass, key, options)
         @klass = klass
-        @key = normalize_key(key)
+        @key = normalize_aliases!(key.dup)
         @fields = @key.keys
-        @options = normalize_options(options.dup)
+        @options = normalize_options!(options.deep_dup)
       end
 
       # Get the index name, generated using the index key.
@@ -64,8 +56,6 @@ module Mongoid
       #   specification.name
       #
       # @return [ String ] name The index name.
-      #
-      # @since 5.0.2
       def name
         @name ||= key.reduce([]) do |n, (k,v)|
           n << "#{k}_#{v}"
@@ -74,43 +64,74 @@ module Mongoid
 
       private
 
-      # Normalize the spec, in case aliased fields are provided.
+      # Normalize the spec in-place, in case aliased fields are provided.
       #
       # @api private
       #
-      # @example Normalize the spec.
-      #   specification.normalize_key(name: 1)
+      # @example Normalize the spec in-place.
+      #   specification.normalize_aliases!(name: 1)
       #
-      # @param [ Hash ] key The index key(s).
+      # @param [ Hash ] spec The index specification.
       #
       # @return [ Hash ] The normalized specification.
-      #
-      # @since 4.0.0
-      def normalize_key(key)
-        normalized = {}
-        key.each_pair do |name, direction|
-          normalized[klass.database_field_name(name).to_sym] = direction
+      def normalize_aliases!(spec)
+        return unless spec.is_a?(Hash)
+
+        spec.transform_keys! do |name|
+          klass.database_field_name(name).to_sym
         end
-        normalized
       end
 
-      # Normalize the index options, if any are provided.
+      # Normalize the index options in-place. Performs deep normalization
+      # on options which have a fields hash value.
       #
       # @api private
       #
-      # @example Normalize the index options.
-      #   specification.normalize_options(drop_dups: true)
+      # @example Normalize the index options in-place.
+      #   specification.normalize_options!(unique: true)
       #
-      # @param [ Hash ] opts The index options.
+      # @param [ Hash ] options The index options.
       #
       # @return [ Hash ] The normalized options.
+      def normalize_options!(options)
+
+        options.transform_keys! do |option|
+          option = option.to_sym
+          MAPPINGS[option] || option
+        end
+
+        %i[partial_filter_expression weights wildcard_projection].each do |key|
+          recursive_normalize_conditionals!(options[key])
+        end
+
+        options
+      end
+
+      # Recursively normalizes the nested elements of an options hash in-place,
+      # to account for $and operator (and other potential $-prefixed operators
+      # which may be supported by MongoDB in the future.)
+      #
+      # @api private
       #
-      # @since 4.0.0
-      def normalize_options(opts)
-        options = {}
-        opts.each_pair do |option, value|
-          options[MAPPINGS[option] || option] = value
+      # @example Recursively normalize the index options in-place.
+      #   opts = { '$and' => [{ name: { '$eq' => 'Bob' } },
+      #                       { age: { '$gte' => 20 } }] }
+      #   specification.recursive_normalize_conditionals!(opts)
+      #
+      # @param [ Hash | Array | Object ] options The index options.
+      #
+      # @return [ Hash | Array | Object ] The normalized options.
+      def recursive_normalize_conditionals!(options)
+        case options
+        when Hash
+          normalize_aliases!(options)
+          options.keys.select { |key| key.to_s.start_with?('$') }.each do |key|
+            recursive_normalize_conditionals!(options[key])
+          end
+        when Array
+          options.each { |opt| recursive_normalize_conditionals!(opt) }
         end
+
         options
       end
     end

data/lib/mongoid/indexable/validators/options.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Indexable
@@ -14,7 +14,6 @@ module Mongoid
           :database,
           :default_language,
           :language_override,
-          :drop_dups,
           :name,
           :sparse,
           :unique,
@@ -30,7 +29,8 @@ module Mongoid
           :text_version,
           :version,
           :partial_filter_expression,
-          :collation
+          :collation,
+          :wildcard_projection,
         ]
 
         VALID_TYPES = [
@@ -53,8 +53,6 @@ module Mongoid
         # @param [ Hash ] options The index options.
         #
         # @raise [ Errors::InvalidIndex ] If validation failed.
-        #
-        # @since 3.0.0
         def validate(klass, spec, options)
           validate_spec(klass, spec, options)
           validate_options(klass, spec, options)
@@ -74,8 +72,6 @@ module Mongoid
         # @param [ Hash ] options The index options.
         #
         # @raise [ Errors::InvalidIndex ] If validation failed.
-        #
-        # @since 3.0.0
         def validate_options(klass, spec, options)
           options.each_pair do |name, value|
             unless VALID_OPTIONS.include?(name)
@@ -96,8 +92,6 @@ module Mongoid
         # @param [ Hash ] options The index options.
         #
         # @raise [ Errors::InvalidIndex ] If validation failed.
-        #
-        # @since 3.0.0
         def validate_spec(klass, spec, options)
           raise Errors::InvalidIndex.new(klass, spec, options) if !spec.is_a?(::Hash)
           spec.each_pair do |name, value|
@@ -105,6 +99,10 @@ module Mongoid
             unless VALID_TYPES.include?(value)
               raise Errors::InvalidIndex.new(klass, spec, options)
             end
+
+            if value == "geoHaystack"
+              Mongoid::Warnings.warn_geo_haystack_deprecated
+            end
           end
         end
       end

data/lib/mongoid/indexable.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require "mongoid/indexable/specification"
 require "mongoid/indexable/validators/options"
@@ -8,8 +8,6 @@ require "ostruct"
 module Mongoid
 
   # Encapsulates behavior around defining indexes.
-  #
-  # @since 4.0.0
   module Indexable
     extend ActiveSupport::Concern
 
@@ -26,8 +24,6 @@ module Mongoid
       #   Person.create_indexes
       #
       # @return [ true ] If the operation succeeded.
-      #
-      # @since 1.0.0
       def create_indexes
         return unless index_specifications
 
@@ -52,8 +48,6 @@ module Mongoid
       #   Person.remove_indexes
       #
       # @return [ true ] If the operation succeeded.
-      #
-      # @since 3.0.0
       def remove_indexes
         indexed_database_names.each do |database|
           with(database: database) do |klass|
@@ -79,8 +73,6 @@ module Mongoid
       #   Person.add_indexes
       #
       # @return [ true ] If the operation succeeded.
-      #
-      # @since 1.0.0
       def add_indexes
         if hereditary? && !index_keys.include?(self.discriminator_key.to_sym => 1)
           index({ self.discriminator_key.to_sym => 1 }, unique: false, background: true)
@@ -97,12 +89,10 @@ module Mongoid
       #     index({ name: 1 }, { background: true })
       #   end
       #
-      # @param [ Symbol ] spec The index spec.
+      # @param [ Hash ] spec The index spec.
       # @param [ Hash ] options The index options.
       #
       # @return [ Hash ] The index options.
-      #
-      # @since 1.0.0
       def index(spec, options = nil)
         specification = Specification.new(self, spec, options)
         if !index_specifications.include?(specification)
@@ -119,8 +109,6 @@ module Mongoid
       # @param [ String ] index_name The index name.
       #
       # @return [ Specification ] The found specification.
-      #
-      # @since 4.0.0
       def index_specification(index_hash, index_name = nil)
         index = OpenStruct.new(fields: index_hash.keys, key: index_hash)
         index_specifications.detect do |spec|
@@ -139,8 +127,6 @@ module Mongoid
       #   Model.indexed_database_names
       #
       # @return [ Array<String> ] The names.
-      #
-      # @since 3.1.0
       def indexed_database_names
         index_specifications.map do |spec|
           spec.options[:database] || database_name
@@ -155,8 +141,6 @@ module Mongoid
       #   Model.index_keys
       #
       # @return [ Array<Hash> ] The specification keys.
-      #
-      # @since 4.0.0
       def index_keys
         index_specifications.map(&:key)
       end

data/lib/mongoid/inspectable.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
 
-  # Contains the bahvior around inspecting documents via inspect.
-  #
-  # @since 4.0.0
+  # Contains the behavior around inspecting documents via inspect.
   module Inspectable
 
     # Returns the class name plus its attributes. If using dynamic fields will
@@ -15,12 +13,41 @@ module Mongoid
     #   person.inspect
     #
     # @return [ String ] A nice pretty string to look at.
-    #
-    # @since 1.0.0
     def inspect
       inspection = []
       inspection.concat(inspect_fields).concat(inspect_dynamic_fields)
-      "#<#{self.class.name} _id: #{id}, #{inspection * ', '}>"
+      "#<#{self.class.name} _id: #{_id}, #{inspection * ', '}>"
+    end
+
+    # This pretty prints the same information as the inspect method. This is
+    # meant to be called by the standard 'pp' library.
+    #
+    # @param [ PP ] pretty_printer The pretty printer.
+    #
+    # @example Pretty print the document.
+    #   person.pretty_inspect
+    #
+    # @api private
+    def pretty_print(pretty_printer)
+      keys = fields.keys | attributes.keys
+      pretty_printer.group(1, "#<#{self.class.name}", '>') do
+        sep = lambda { pretty_printer.text(',') }
+        pretty_printer.seplist(keys, sep) do |key|
+          pretty_printer.breakable
+          field = fields[key]
+          as = "(#{field.options[:as]})" if field && field.options[:as]
+          pretty_printer.text("#{key}#{as}")
+          pretty_printer.text(':')
+          pretty_printer.group(1) do
+            pretty_printer.breakable
+            if key == "_id"
+              pretty_printer.text(_id.to_s)
+            else
+              pretty_printer.pp(@attributes[key])
+            end
+          end
+        end
+      end
     end
 
     private
@@ -33,8 +60,6 @@ module Mongoid
     #   document.inspect_fields
     #
     # @return [ String ] An array of pretty printed field values.
-    #
-    # @since 1.0.0
     def inspect_fields
       fields.map do |name, field|
         unless name == "_id"
@@ -52,8 +77,6 @@ module Mongoid
     #   document.inspect_dynamic_fields
     #
     # @return [ String ] An array of pretty printed dynamic field values.
-    #
-    # @since 1.0.0
     def inspect_dynamic_fields
       []
     end