mongoid 7.2.1 → 9.0.0

data/lib/mongoid/selectable.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
 
   # Provides behavior for generating the selector for a specific document.
-  #
-  # @since 4.0.0
   module Selectable
     extend ActiveSupport::Concern
 
@@ -17,11 +15,8 @@ module Mongoid
     #   document.atomic_selector
     #
     # @return [ Hash ] The document's selector.
-    #
-    # @since 1.0.0
     def atomic_selector
-      @atomic_selector ||=
-        (embedded? ? embedded_atomic_selector : root_atomic_selector)
+      embedded? ? embedded_atomic_selector : root_atomic_selector_in_db
     end
 
     private
@@ -34,8 +29,6 @@ module Mongoid
     #   document.embedded_atomic_selector
     #
     # @return [ Hash ] The embedded document selector.
-    #
-    # @since 4.0.0
     def embedded_atomic_selector
       if persisted? && _id_changed?
         _parent.atomic_selector
@@ -44,18 +37,14 @@ module Mongoid
       end
     end
 
-    # Get the atomic selector for a root document.
+    # Get the atomic selector that would match the existing version of the
+    # root document.
     #
     # @api private
     #
-    # @example Get the root atomic selector.
-    #   document.root_atomic_selector
-    #
     # @return [ Hash ] The root document selector.
-    #
-    # @since 4.0.0
-    def root_atomic_selector
-      { "_id" => _id }.merge!(shard_key_selector)
+    def root_atomic_selector_in_db
+      { "_id" => _id }.merge!(shard_key_selector_in_db)
     end
   end
 end

data/lib/mongoid/serializable.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
 
   # This module provides the extra behavior for including associations in JSON
   # and XML serialization.
-  #
-  # @since 4.0.0
   module Serializable
     extend ActiveSupport::Concern
 
@@ -36,14 +34,16 @@ module Mongoid
     #
     # @param [ Hash ] options The options to pass.
     #
-    # @option options [ Symbol ] :include What associations to include.
-    # @option options [ Symbol ] :only Limit the fields to only these.
-    # @option options [ Symbol ] :except Dont include these fields.
-    # @option options [ Symbol ] :methods What methods to include.
+    # @option options [ Symbol | String | Array<Symbol | String> ] :except
+    #   Do not include these field(s).
+    # @option options [ Symbol | String | Array<Symbol | String> ] :include
+    #   Which association(s) to include.
+    # @option options [ Symbol | String | Array<Symbol | String> ] :only
+    #   Limit the field(s) to only these.
+    # @option options [ Symbol | String | Array<Symbol | String> ] :methods
+    #   What methods to include.
     #
     # @return [ Hash ] The document, ready to be serialized.
-    #
-    # @since 2.0.0.rc.6
     def serializable_hash(options = nil)
       options ||= {}
       attrs = {}
@@ -73,8 +73,6 @@ module Mongoid
     #   document.send(:field_names)
     #
     # @return [ Array<String> ] The names of the fields.
-    #
-    # @since 3.0.0
     def field_names(options)
       names = (as_attributes.keys + attribute_names).uniq.sort
 
@@ -104,8 +102,6 @@ module Mongoid
     # @param [ Hash ] options The options.
     #
     # @return [ Object ] The attribute.
-    #
-    # @since 3.0.0
     def serialize_attribute(attrs, name, names, options)
       if relations.key?(name)
         value = send(name)
@@ -129,8 +125,6 @@ module Mongoid
     # @option options [ Symbol ] :include What associations to include
     # @option options [ Symbol ] :only Limit the fields to only these.
     # @option options [ Symbol ] :except Dont include these fields.
-    #
-    # @since 2.0.0.rc.6
     def serialize_relations(attributes = {}, options = {})
       inclusions = options[:include]
       relation_names(inclusions).each do |name|
@@ -148,11 +142,9 @@ module Mongoid
     # @example Get the association names.
     #   document.relation_names(:include => [ :addresses ])
     #
-    # @param [ Hash, Symbol, Array<Symbol> ] inclusions The inclusions.
+    # @param [ Hash | Symbol | Array<Symbol> ] inclusions The inclusions.
     #
     # @return [ Array<Symbol> ] The names of the included associations.
-    #
-    # @since 2.0.0.rc.6
     def relation_names(inclusions)
       inclusions.is_a?(Hash) ? inclusions.keys : Array.wrap(inclusions)
     end
@@ -163,13 +155,11 @@ module Mongoid
     # @example Get the association options.
     #   document.relation_names(:include => [ :addresses ])
     #
-    # @param [ Hash, Symbol, Array<Symbol> ] inclusions The inclusions.
+    # @param [ Hash | Symbol | Array<Symbol> ] inclusions The inclusions.
     # @param [ Hash ] options The options.
     # @param [ Symbol ] name The name of the association.
     #
     # @return [ Hash ] The options for the association.
-    #
-    # @since 2.0.0.rc.6
     def relation_options(inclusions, options, name)
       if inclusions.is_a?(Hash)
         inclusions[name]

data/lib/mongoid/shardable.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
 
   # This module contains behavior for adding shard key fields to updates.
-  #
-  # @since 4.0.0
   module Shardable
     extend ActiveSupport::Concern
 
@@ -46,26 +44,64 @@ module Mongoid
     #   model.shard_key_fields
     #
     # @return [ Array<String> ] The shard key field names.
-    #
-    # @since 1.0.0
     def shard_key_fields
       self.class.shard_key_fields
     end
 
-    # Get the document selector with the defined shard keys.
+    # Returns the selector that would match the defined shard keys. If
+    # `prefer_persisted` is false (the default), it uses the current values
+    # of the specified shard keys, otherwise, it will try to use whatever value
+    # was most recently persisted.
+    #
+    # @param [ true | false ] prefer_persisted Whether to use the current
+    #   value of the shard key fields, or to use their most recently persisted
+    #   values.
+    #
+    # @return [ Hash ] The shard key selector.
+    #
+    # @api private
+    def shard_key_selector(prefer_persisted: false)
+      shard_key_fields.each_with_object({}) do |field, selector|
+        selector[field.to_s] = shard_key_field_value(field.to_s, prefer_persisted: prefer_persisted)
+      end
+    end
+
+    # Returns the selector that would match the existing version of this
+    # document in the database.
     #
-    # @example Get the selector for the shard keys.
-    #   person.shard_key_selector
+    # If the document is not persisted, this method uses the current values
+    # of the shard key fields. If the document is persisted, this method
+    # uses the values retrieved from the database.
     #
     # @return [ Hash ] The shard key selector.
     #
-    # @since 2.0.0
-    def shard_key_selector
-      selector = {}
-      shard_key_fields.each do |field|
-        selector[field.to_s] = new_record? ? send(field) : attribute_was(field)
+    # @api private
+    def shard_key_selector_in_db
+      shard_key_selector(prefer_persisted: true)
+    end
+
+    # Returns the value for the named shard key. If the field identifies
+    # an embedded document, the key will be parsed and recursively evaluated.
+    # If `prefer_persisted` is true, the value last persisted to the database
+    # will be returned, regardless of what the current value of the attribute
+    # may be.
+    #
+    # @param [String] field The name of the field to evaluate
+    # @param [ true|false ] prefer_persisted Whether or not to prefer the
+    #   persisted value over the current value.
+    #
+    # @return [ Object ] The value of the named field.
+    #
+    # @api private
+    def shard_key_field_value(field, prefer_persisted:)
+      if field.include?(".")
+        relation, remaining = field.split(".", 2)
+        send(relation)&.shard_key_field_value(remaining, prefer_persisted: prefer_persisted)
+      elsif prefer_persisted && !new_record?
+        attribute_was(field)
+      else
+        send(field)
       end
-      selector
     end
 
     module ClassMethods
@@ -81,8 +117,6 @@ module Mongoid
       #
       #     shard_key first_name: 1, last_name: 1
       #   end
-      #
-      # @since 2.0.0
       def shard_key(*args)
         unless args.first.is_a?(Hash)
           # Shorthand syntax

data/lib/mongoid/stateful.rb

@@ -1,46 +1,75 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
 
-  # This module contains the behavior for getting the various states a
-  # document can transition through.
+  # Mixin module included into Mongoid::Document which adds behavior for
+  # getting the various lifecycle states a document can transition through.
   module Stateful
 
-    attr_writer :destroyed, :flagged_for_destroy, :new_record
+    attr_writer :destroyed, :flagged_for_destroy, :previously_new_record
 
-    # Returns true if the +Document+ has not been persisted to the database,
+    # Sets whether the document has been persisted to the database.
+    #
+    # @param [ true | false ] new_value The value to set.
+    #
+    # @return [ true | false ] The set value.
+    def new_record=(new_value)
+      @new_record ||= false
+      if @new_record && !new_value
+        @previously_new_record = true
+      end
+      @new_record = new_value
+    end
+
+    # Returns true if the document has not been persisted to the database,
     # false if it has. This is determined by the variable @new_record
     # and NOT if the object has an id.
     #
     # @example Is the document new?
     #   person.new_record?
     #
-    # @return [ true, false ] True if new, false if not.
+    # @return [ true | false ] True if new, false if not.
     def new_record?
       @new_record ||= false
     end
 
+    # Returns true if this document was just created -- that is, prior to the last
+    # save, the object didn't exist in the database and new_record? would have
+    # returned true.
+    #
+    # @return [ true | false ] True if was just created, false if not.
+    def previously_new_record?
+      @previously_new_record ||= false
+    end
+
     # Checks if the document has been saved to the database. Returns false
     # if the document has been destroyed.
     #
     # @example Is the document persisted?
     #   person.persisted?
     #
-    # @return [ true, false ] True if persisted, false if not.
+    # @return [ true | false ] True if persisted, false if not.
     def persisted?
       !new_record? && !destroyed?
     end
 
+    # Checks if the document was previously saved to the database
+    # but now it has been deleted.
+    #
+    # @return [ true | false ] True if was persisted but now destroyed,
+    #   otherwise false.
+    def previously_persisted?
+      !new_record? && destroyed?
+    end
+
     # Returns whether or not the document has been flagged for deletion, but
     # not destroyed yet. Used for atomic pulls of child documents.
     #
     # @example Is the document flagged?
     #   document.flagged_for_destroy?
     #
-    # @return [ true, false ] If the document is flagged.
-    #
-    # @since 2.3.2
+    # @return [ true | false ] If the document is flagged.
     def flagged_for_destroy?
       @flagged_for_destroy ||= false
     end
@@ -54,7 +83,7 @@ module Mongoid
     # @example Is the document destroyed?
     #   person.destroyed?
     #
-    # @return [ true, false ] True if destroyed, false if not.
+    # @return [ true | false ] True if destroyed, false if not.
     def destroyed?
       @destroyed ||= false
     end
@@ -64,7 +93,7 @@ module Mongoid
     # @example Is this pushable?
     #   person.pushable?
     #
-    # @return [ true, false ] Is the document new and embedded?
+    # @return [ true | false ] Is the document new and embedded?
     def pushable?
       new_record? &&
         embedded_many? &&
@@ -72,16 +101,35 @@ module Mongoid
         !_parent.delayed_atomic_sets[atomic_path]
     end
 
+    # Flags the document as readonly. Will cause a ReadonlyDocument error to be
+    # raised if the document is attempted to be saved, updated or destroyed.
+    #
+    # @example Flag the document as readonly.
+    #   document.readonly!
+    #
+    # @return [ true | false ] true if the document was successfully marked
+    #   readonly, false otherwise.
+    def readonly!
+      if Mongoid.legacy_readonly
+        Mongoid::Warnings.warn_legacy_readonly
+        false
+      else
+        @readonly = true
+      end
+    end
+
     # Is the document readonly?
     #
     # @example Is the document readonly?
     #   document.readonly?
     #
-    # @return [ true, false ] If the document is readonly.
-    #
-    # @since 4.0.0
+    # @return [ true | false ] If the document is readonly.
     def readonly?
-      __selected_fields != nil
+      if Mongoid.legacy_readonly
+        __selected_fields != nil
+      else
+        @readonly ||= false
+      end
     end
 
     # Determine if the document can be set.
@@ -89,9 +137,7 @@ module Mongoid
     # @example Is this settable?
     #   person.settable?
     #
-    # @return [ true, false ] Is this document a new embeds one?
-    #
-    # @since 2.1.0
+    # @return [ true | false ] Is this document a new embeds one?
     def settable?
       new_record? && embedded_one? && _parent.persisted?
     end
@@ -101,9 +147,7 @@ module Mongoid
     # @example Is the document updateable?
     #   person.updateable?
     #
-    # @return [ true, false ] If the document is changed and persisted.
-    #
-    # @since 2.1.0
+    # @return [ true | false ] If the document is changed and persisted.
     def updateable?
       persisted? && changed?
     end

data/lib/mongoid/stringified_symbol.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
-# A class which sends values to the database as Strings but returns them to the user as Symbols.
 module Mongoid
+
+  # A class which sends values to the database as Strings but returns
+  # them to the user as Symbols.
   class StringifiedSymbol
 
     class << self
@@ -10,7 +12,7 @@ module Mongoid
       # Convert the object from its mongo friendly ruby type to this type.
       #
       # @example Demongoize the object.
-      #   Symbol.demongoize(object)
+      #   Mongoid::StringifiedSymbol.demongoize('hedgehog')
       #
       # @param [ Object ] object The object to demongoize.
       #
@@ -25,15 +27,15 @@ module Mongoid
         end
       end
 
-      # Turn the object from the ruby type we deal with to a Mongo friendly
-      # type.
+      # Turn the object from the Ruby type into the type
+      # type used for MongoDB persistence.
       #
       # @example Mongoize the object.
-      #   Symbol.mongoize("123.11")
+      #   Mongoid::StringifiedSymbol.mongoize(:hedgehog)
       #
       # @param [ Object ] object The object to mongoize.
       #
-      # @return [ Symbol ] The object mongoized.
+      # @return [ String ] The object mongoized.
       #
       # @api private
       def mongoize(object)
@@ -44,6 +46,16 @@ module Mongoid
          end
       end
 
+      # Turn the object from the Ruby type into the type
+      # type used in MQL queries.
+      #
+      # @example Evolve the object.
+      #   Mongoid::StringifiedSymbol.evolve(:hedgehog)
+      #
+      # @param [ Object ] object The object to evolve.
+      #
+      # @return [ String ] The object evolved.
+      #
       # @api private
       def evolve(object)
         mongoize(object)

data/lib/mongoid/tasks/database.rake

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 namespace :db do
   namespace :mongoid do
     task :load_models do
+      ::Mongoid.load_models
+    end
+
+    desc "Create collections for Mongoid models"
+    task :create_collections => [:environment, :load_models] do
+      ::Mongoid::Tasks::Database.create_collections
     end
 
     desc "Create indexes specified in Mongoid models"
@@ -10,6 +17,12 @@ namespace :db do
       ::Mongoid::Tasks::Database.create_indexes
     end
 
+    desc "Create search indexes specified in Mongoid models"
+    task :create_search_indexes => [:environment, :load_models] do
+      wait = Mongoid::Utils.truthy_string?(ENV['WAIT_FOR_SEARCH_INDEXES'] || '1')
+      ::Mongoid::Tasks::Database.create_search_indexes(wait: wait)
+    end
+
     desc "Remove indexes that exist in the database but are not specified in Mongoid models"
     task :remove_undefined_indexes => [:environment, :load_models] do
       ::Mongoid::Tasks::Database.remove_undefined_indexes
@@ -20,6 +33,11 @@ namespace :db do
       ::Mongoid::Tasks::Database.remove_indexes
     end
 
+    desc "Remove search indexes specified in Mongoid models"
+    task :remove_search_indexes => [:environment, :load_models] do
+      ::Mongoid::Tasks::Database.remove_search_indexes
+    end
+
     desc "Shard collections with shard keys specified in Mongoid models"
     task :shard_collections => [:environment, :load_models] do
       ::Mongoid::Tasks::Database.shard_collections
@@ -34,5 +52,12 @@ namespace :db do
     task :purge => :environment do
       ::Mongoid.purge!
     end
+
+    namespace :create_collections do
+      desc "Drop and create collections for Mongoid models"
+      task :force => [:environment, :load_models] do
+        ::Mongoid::Tasks::Database.create_collections(force: true)
+      end
+    end
   end
 end

data/lib/mongoid/tasks/database.rb

@@ -1,11 +1,37 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Tasks
+
+    # Utility module to manage database collections, indexes, sharding, etc.
+    # Invoked from Rake tasks.
     module Database
       extend self
 
+      # Create collections for each model given the provided globs and the class is
+      # not embedded.
+      #
+      # @param [ Array<Mongoid::Document> ] models. Array of document classes for
+      #   which collections should be created. Defaulted to all document classes
+      #   in the application.
+      # @param [ true | false ] force If true, the method will drop existing
+      #   collections before creating new ones. If false, the method will create
+      #   only new collection (that do not exist in the database).
+      def create_collections(models = ::Mongoid.models, force: false)
+        models.each do |model|
+          if !model.embedded? || model.cyclic?
+            model.create_collection(force: force)
+            logger.info("MONGOID: Created collection for #{model}:")
+          else
+            logger.info("MONGOID: collection options ignored on: #{model}, please define in the root model.")
+          end
+        rescue Exception
+          logger.error "error while creating collection for #{model}"
+          raise
+        end
+      end
+
       # Create indexes for each model given the provided globs and the class is
       # not embedded.
       #
@@ -13,8 +39,6 @@ module Mongoid
       #   Mongoid::Tasks::Database.create_indexes
       #
       # @return [ Array<Class> ] The indexed models.
-      #
-      # @since 2.1.0
       def create_indexes(models = ::Mongoid.models)
         models.each do |model|
           next if model.index_specifications.empty?
@@ -32,6 +56,26 @@ module Mongoid
         end.compact
       end
 
+      # Submit requests for the search indexes to be created. This will happen
+      # asynchronously. If "wait" is true, the method will block while it
+      # waits for the indexes to be created.
+      #
+      # @param [ Array<Mongoid::Document> ] models the models to build search
+      #   indexes for.
+      # @param [ true | false ] wait whether to wait for the indexes to be
+      #   built.
+      def create_search_indexes(models = ::Mongoid.models, wait: true)
+        searchable = models.select { |m| m.search_index_specs.any? }
+
+        # queue up the search index creation requests
+        index_names_by_model = searchable.each_with_object({}) do |model, obj|
+          logger.info("MONGOID: Creating search indexes on #{model}...")
+          obj[model] = model.create_search_indexes
+        end
+
+        wait_for_search_indexes(index_names_by_model) if wait
+      end
+
       # Return the list of indexes by model that exist in the database but aren't
       # specified on the models.
       #
@@ -39,7 +83,6 @@ module Mongoid
       #   Mongoid::Tasks::Database.undefined_indexes
       #
       # @return [ Array<Hash> ] The list of undefined indexes by model.
-      #
       def undefined_indexes(models = ::Mongoid.models)
         undefined_by_model = {}
 
@@ -72,8 +115,6 @@ module Mongoid
       #   Mongoid::Tasks::Database.remove_undefined_indexes
       #
       # @return [ Hash{Class => Array(Hash)}] The list of indexes that were removed by model.
-      #
-      # @since 4.0.0
       def remove_undefined_indexes(models = ::Mongoid.models)
         undefined_indexes(models).each do |model, indexes|
           indexes.each do |index|
@@ -95,7 +136,6 @@ module Mongoid
       #   Mongoid::Tasks::Database.remove_indexes
       #
       # @return [ Array<Class> ] The un-indexed models.
-      #
       def remove_indexes(models = ::Mongoid.models)
         models.each do |model|
           next if model.embedded?
@@ -108,6 +148,17 @@ module Mongoid
         end.compact
       end
 
+      # Remove all search indexes from the given models.
+      #
+      # @params [ Array<Mongoid::Document> ] models the models to remove
+      #   search indexes from.
+      def remove_search_indexes(models = ::Mongoid.models)
+        models.each do |model|
+          next if model.embedded?
+          model.remove_search_indexes
+        end
+      end
+
       # Shard collections for models that declare shard keys.
       #
       # Returns the model classes that have had their collections sharded,
@@ -123,7 +174,7 @@ module Mongoid
           next if model.shard_config.nil?
 
           if model.embedded? && !model.cyclic?
-            logger.warn("MONGOID: #{model} has shard config but is emdedded")
+            logger.warn("MONGOID: #{model} has shard config but is embedded")
             next
           end
 
@@ -196,6 +247,31 @@ module Mongoid
       def logger
         Mongoid.logger
       end
+
+      # Waits for the search indexes to be built on the given models.
+      #
+      # @param [ Hash<Mongoid::Document, Array<String>> ] models a mapping of
+      #   index names for each model
+      def wait_for_search_indexes(models)
+        logger.info('MONGOID: Waiting for search indexes to be created')
+        logger.info('MONGOID: Press ctrl-c to skip the wait and let the indexes be created in the background')
+
+        models.each do |model, names|
+          model.wait_for_search_indexes(names) do |status|
+            if status.ready?
+              puts
+              logger.info("MONGOID: Search indexes on #{model} are READY")
+            else
+              print '.'
+              $stdout.flush
+            end
+          end
+        end
+      rescue Interrupt
+        # ignore ctrl-C here; we assume it is meant only to skip
+        # the wait, and that subsequent tasks ought to continue.
+        logger.info('MONGOID: Skipping the wait for search indexes; they will be created in the background')
+      end
     end
   end
 end