mongoid 7.1.1 → 8.1.0

data/lib/mongoid/findable.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 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 +22,46 @@ 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,
+      :fourth,
+      :fourth!,
       :geo_near,
       :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.
@@ -60,12 +75,22 @@ module Mongoid
       with_default_scope.count
     end
 
+    # Returns an estimated count of records in the database.
+    #
+    # @example Get the count of matching documents.
+    #   Person.estimated_count
+    #
+    # @return [ Integer ] The number of matching documents.
+    def estimated_count
+      with_default_scope.estimated_count
+    end
+
     # Returns true if count is zero
     #
     # @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
@@ -76,27 +101,77 @@ 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?
-    end
-
-    # Find a +Document+ in several different ways.
-    #
-    # If a +String+ is provided, it will be assumed that it is a
-    # representation of a Mongo::ObjectID and will attempt to find a single
-    # +Document+ based on that id. If a +Symbol+ and +Hash+ is provided then
-    # it will attempt to find either a single +Document+ or multiples based
-    # on the conditions provided and the first parameter.
+    # @example Do any documents exist for given _id.
+    #   Person.exists?(BSON::ObjectId(...))
     #
-    # @example Find a single document by an id.
-    #   Person.find(BSON::ObjectId)
+    # @example Do any documents exist for given conditions.
+    #   Person.exists?(name: "...")
     #
-    # @param [ Array ] args An assortment of finder options.
+    # @param [ Hash | Object | false ] id_or_conditions an _id to
+    #   search for, a hash of conditions, nil or false.
     #
-    # @return [ Document, nil, Criteria ] A document or matching documents.
-    def find(*args)
-      with_default_scope.find(*args)
+    # @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.
+    #
+    # If a single non-Array argument is given, this argument is interpreted
+    # as the _id value of a document to find. If there is a matching document
+    # in the database, this document is returned; otherwise, if the
+    # +raise_not_found_error+ Mongoid configuration option is truthy
+    # (which is the default), +Errors::DocumentNotFound+ is raised, and if
+    # +raise_not_found_error+ is falsy, +find+ returns +nil+.
+    #
+    # If multiple arguments are given, or an Array argument is given, the
+    # array is flattened and each array element is interpreted as the _id
+    # value of the document to find. Mongoid then attempts to retrieve all
+    # documents with the provided _id values. The return value is an array
+    # of found documents. Each document appears one time in the returned array,
+    # 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+
+    # 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.
+    #
+    # Note that MongoDB does not allow the _id field to be an array.
+    #
+    # The argument undergoes customary Mongoid type conversions based on
+    # the type declared for the _id field. By default the _id field is a
+    # +BSON::ObjectId+; this allows strings to be passed to +find+ and the
+    # 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.
+    #
+    # @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, &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.
@@ -112,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
@@ -135,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
@@ -148,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
 
@@ -159,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,13 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 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 +27,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,8 +40,6 @@ 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)
@@ -64,8 +55,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}"
@@ -84,8 +73,6 @@ module Mongoid
       # @param [ Hash ] key The index key(s).
       #
       # @return [ Hash ] The normalized specification.
-      #
-      # @since 4.0.0
       def normalize_key(key)
         normalized = {}
         key.each_pair do |name, direction|
@@ -99,13 +86,11 @@ module Mongoid
       # @api private
       #
       # @example Normalize the index options.
-      #   specification.normalize_options(drop_dups: true)
+      #   specification.normalize_options(unique: true)
       #
       # @param [ Hash ] opts The index options.
       #
       # @return [ Hash ] The normalized options.
-      #
-      # @since 4.0.0
       def normalize_options(opts)
         options = {}
         opts.each_pair do |option, value|

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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Indexable
@@ -14,7 +13,6 @@ module Mongoid
           :database,
           :default_language,
           :language_override,
-          :drop_dups,
           :name,
           :sparse,
           :unique,
@@ -30,7 +28,8 @@ module Mongoid
           :text_version,
           :version,
           :partial_filter_expression,
-          :collation
+          :collation,
+          :wildcard_projection,
         ]
 
         VALID_TYPES = [
@@ -53,8 +52,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 +71,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 +91,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 +98,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,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/indexable/specification"
 require "mongoid/indexable/validators/options"
@@ -8,8 +7,6 @@ require "ostruct"
 module Mongoid
 
   # Encapsulates behavior around defining indexes.
-  #
-  # @since 4.0.0
   module Indexable
     extend ActiveSupport::Concern
 
@@ -26,8 +23,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 +47,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,11 +72,9 @@ module Mongoid
       #   Person.add_indexes
       #
       # @return [ true ] If the operation succeeded.
-      #
-      # @since 1.0.0
       def add_indexes
-        if hereditary? && !index_keys.include?(_type: 1)
-          index({ _type: 1 }, unique: false, background: true)
+        if hereditary? && !index_keys.include?(self.discriminator_key.to_sym => 1)
+          index({ self.discriminator_key.to_sym => 1 }, unique: false, background: true)
         end
         true
       end
@@ -97,12 +88,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 +108,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 +126,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 +140,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,8 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 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 +12,10 @@ 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
 
     private
@@ -33,8 +28,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 +45,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