activerecord 5.2.8.1 → 6.1.7.3

data/lib/active_record/delegated_type.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inquiry"
+
+module ActiveRecord
+  # == Delegated types
+  #
+  # Class hierarchies can map to relational database tables in many ways. Active Record, for example, offers
+  # purely abstract classes, where the superclass doesn't persist any attributes, and single-table inheritance,
+  # where all attributes from all levels of the hierarchy are represented in a single table. Both have their
+  # places, but neither are without their drawbacks.
+  #
+  # The problem with purely abstract classes is that all concrete subclasses must persist all the shared
+  # attributes themselves in their own tables (also known as class-table inheritance). This makes it hard to
+  # do queries across the hierarchy. For example, imagine you have the following hierarchy:
+  #
+  #   Entry < ApplicationRecord
+  #   Message < Entry
+  #   Comment < Entry
+  #
+  # How do you show a feed that has both +Message+ and +Comment+ records, which can be easily paginated?
+  # Well, you can't! Messages are backed by a messages table and comments by a comments table. You can't
+  # pull from both tables at once and use a consistent OFFSET/LIMIT scheme.
+  #
+  # You can get around the pagination problem by using single-table inheritance, but now you're forced into
+  # a single mega table with all the attributes from all subclasses. No matter how divergent. If a Message
+  # has a subject, but the comment does not, well, now the comment does anyway! So STI works best when there's
+  # little divergence between the subclasses and their attributes.
+  #
+  # But there's a third way: Delegated types. With this approach, the "superclass" is a concrete class
+  # that is represented by its own table, where all the superclass attributes that are shared amongst all the
+  # "subclasses" are stored. And then each of the subclasses have their own individual tables for additional
+  # attributes that are particular to their implementation. This is similar to what's called multi-table
+  # inheritance in Django, but instead of actual inheritance, this approach uses delegation to form the
+  # hierarchy and share responsibilities.
+  #
+  # Let's look at that entry/message/comment example using delegated types:
+  #
+  #   # Schema: entries[ id, account_id, creator_id, created_at, updated_at, entryable_type, entryable_id ]
+  #   class Entry < ApplicationRecord
+  #     belongs_to :account
+  #     belongs_to :creator
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #   end
+  #
+  #   module Entryable
+  #     extend ActiveSupport::Concern
+  #
+  #     included do
+  #       has_one :entry, as: :entryable, touch: true
+  #     end
+  #   end
+  #
+  #   # Schema: messages[ id, subject ]
+  #   class Message < ApplicationRecord
+  #     include Entryable
+  #     has_rich_text :content
+  #   end
+  #
+  #   # Schema: comments[ id, content ]
+  #   class Comment < ApplicationRecord
+  #     include Entryable
+  #   end
+  #
+  # As you can see, neither +Message+ nor +Comment+ are meant to stand alone. Crucial metadata for both classes
+  # resides in the +Entry+ "superclass". But the +Entry+ absolutely can stand alone in terms of querying capacity
+  # in particular. You can now easily do things like:
+  #
+  #   Account.entries.order(created_at: :desc).limit(50)
+  #
+  # Which is exactly what you want when displaying both comments and messages together. The entry itself can
+  # be rendered as its delegated type easily, like so:
+  #
+  #   # entries/_entry.html.erb
+  #   <%= render "entries/entryables/#{entry.entryable_name}", entry: entry %>
+  #
+  #   # entries/entryables/_message.html.erb
+  #   <div class="message">
+  #     Posted on <%= entry.created_at %> by <%= entry.creator.name %>: <%= entry.message.content %>
+  #   </div>
+  #
+  #   # entries/entryables/_comment.html.erb
+  #   <div class="comment">
+  #     <%= entry.creator.name %> said: <%= entry.comment.content %>
+  #   </div>
+  #
+  # == Sharing behavior with concerns and controllers
+  #
+  # The entry "superclass" also serves as a perfect place to put all that shared logic that applies to both
+  # messages and comments, and which acts primarily on the shared attributes. Imagine:
+  #
+  #   class Entry < ApplicationRecord
+  #     include Eventable, Forwardable, Redeliverable
+  #   end
+  #
+  # Which allows you to have controllers for things like +ForwardsController+ and +RedeliverableController+
+  # that both act on entries, and thus provide the shared functionality to both messages and comments.
+  #
+  # == Creating new records
+  #
+  # You create a new record that uses delegated typing by creating the delegator and delegatee at the same time,
+  # like so:
+  #
+  #   Entry.create! entryable: Comment.new(content: "Hello!"), creator: Current.user
+  #
+  # If you need more complicated composition, or you need to perform dependent validation, you should build a factory
+  # method or class to take care of the complicated needs. This could be as simple as:
+  #
+  #   class Entry < ApplicationRecord
+  #     def self.create_with_comment(content, creator: Current.user)
+  #       create! entryable: Comment.new(content: content), creator: creator
+  #     end
+  #   end
+  #
+  # == Adding further delegation
+  #
+  # The delegated type shouldn't just answer the question of what the underlying class is called. In fact, that's
+  # an anti-pattern most of the time. The reason you're building this hierarchy is to take advantage of polymorphism.
+  # So here's a simple example of that:
+  #
+  #   class Entry < ApplicationRecord
+  #     delegated_type :entryable, types: %w[ Message Comment ]
+  #     delegate :title, to: :entryable
+  #   end
+  #
+  #   class Message < ApplicationRecord
+  #     def title
+  #       subject
+  #     end
+  #   end
+  #
+  #   class Comment < ApplicationRecord
+  #     def title
+  #       content.truncate(20)
+  #     end
+  #   end
+  #
+  # Now you can list a bunch of entries, call +Entry#title+, and polymorphism will provide you with the answer.
+  module DelegatedType
+    # Defines this as a class that'll delegate its type for the passed +role+ to the class references in +types+.
+    # That'll create a polymorphic +belongs_to+ relationship to that +role+, and it'll add all the delegated
+    # type convenience methods:
+    #
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment ], dependent: :destroy
+    #   end
+    #
+    #   Entry#entryable_class # => +Message+ or +Comment+
+    #   Entry#entryable_name  # => "message" or "comment"
+    #   Entry.messages        # => Entry.where(entryable_type: "Message")
+    #   Entry#message?        # => true when entryable_type == "Message"
+    #   Entry#message         # => returns the message record, when entryable_type == "Message", otherwise nil
+    #   Entry#message_id      # => returns entryable_id, when entryable_type == "Message", otherwise nil
+    #   Entry.comments        # => Entry.where(entryable_type: "Comment")
+    #   Entry#comment?        # => true when entryable_type == "Comment"
+    #   Entry#comment         # => returns the comment record, when entryable_type == "Comment", otherwise nil
+    #   Entry#comment_id      # => returns entryable_id, when entryable_type == "Comment", otherwise nil
+    #
+    # The +options+ are passed directly to the +belongs_to+ call, so this is where you declare +dependent+ etc.
+    #
+    # You can also declare namespaced types:
+    #
+    #   class Entry < ApplicationRecord
+    #     delegated_type :entryable, types: %w[ Message Comment Access::NoticeMessage ], dependent: :destroy
+    #   end
+    #
+    #   Entry.access_notice_messages
+    #   entry.access_notice_message
+    #   entry.access_notice_message?
+    def delegated_type(role, types:, **options)
+      belongs_to role, options.delete(:scope), **options.merge(polymorphic: true)
+      define_delegated_type_methods role, types: types
+    end
+
+    private
+      def define_delegated_type_methods(role, types:)
+        role_type = "#{role}_type"
+        role_id   = "#{role}_id"
+
+        define_method "#{role}_class" do
+          public_send("#{role}_type").constantize
+        end
+
+        define_method "#{role}_name" do
+          public_send("#{role}_class").model_name.singular.inquiry
+        end
+
+        types.each do |type|
+          scope_name = type.tableize.gsub("/", "_")
+          singular   = scope_name.singularize
+          query      = "#{singular}?"
+
+          scope scope_name, -> { where(role_type => type) }
+
+          define_method query do
+            public_send(role_type) == type
+          end
+
+          define_method singular do
+            public_send(role) if public_send(query)
+          end
+
+          define_method "#{singular}_id" do
+            public_send(role_id) if public_send(query)
+          end
+        end
+      end
+  end
+end

data/lib/active_record/destroy_association_async_job.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  class DestroyAssociationAsyncError < StandardError
+  end
+
+  # Job to destroy the records associated with a destroyed record in background.
+  class DestroyAssociationAsyncJob < ActiveJob::Base
+    queue_as { ActiveRecord::Base.queues[:destroy] }
+
+    discard_on ActiveJob::DeserializationError
+
+    def perform(
+      owner_model_name: nil, owner_id: nil,
+      association_class: nil, association_ids: nil, association_primary_key_column: nil,
+      ensuring_owner_was_method: nil
+    )
+      association_model = association_class.constantize
+      owner_class = owner_model_name.constantize
+      owner = owner_class.find_by(owner_class.primary_key.to_sym => owner_id)
+
+      if !owner_destroyed?(owner, ensuring_owner_was_method)
+        raise DestroyAssociationAsyncError, "owner record not destroyed"
+      end
+
+      association_model.where(association_primary_key_column => association_ids).find_each do |r|
+        r.destroy
+      end
+    end
+
+    private
+      def owner_destroyed?(owner, ensuring_owner_was_method)
+        !owner || (ensuring_owner_was_method && owner.public_send(ensuring_owner_was_method))
+      end
+  end
+end

data/lib/active_record/dynamic_matchers.rb

@@ -49,11 +49,11 @@ module ActiveRecord
 
         attr_reader :model, :name, :attribute_names
 
-        def initialize(model, name)
+        def initialize(model, method_name)
           @model           = model
-          @name            = name.to_s
+          @name            = method_name.to_s
           @attribute_names = @name.match(self.class.pattern)[1].split("_and_")
-          @attribute_names.map! { |n| @model.attribute_aliases[n] || n }
+          @attribute_names.map! { |name| @model.attribute_aliases[name] || name }
         end
 
         def valid?
@@ -69,7 +69,6 @@ module ActiveRecord
         end
 
         private
-
           def body
             "#{finder}(#{attributes_hash})"
           end

data/lib/active_record/enum.rb

@@ -31,7 +31,9 @@ module ActiveRecord
   # as well. With the above example:
   #
   #   Conversation.active
+  #   Conversation.not_active
   #   Conversation.archived
+  #   Conversation.not_archived
   #
   # Of course, you can also query them directly if the scopes don't fit your
   # needs:
@@ -39,13 +41,20 @@ module ActiveRecord
   #   Conversation.where(status: [:active, :archived])
   #   Conversation.where.not(status: :active)
   #
-  # You can set the default value from the database declaration, like:
+  # Defining scopes can be disabled by setting +:_scopes+ to +false+.
   #
-  #   create_table :conversations do |t|
-  #     t.column :status, :integer, default: 0
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: [ :active, :archived ], _scopes: false
+  #   end
+  #
+  # You can set the default enum value by setting +:_default+, like:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: [ :active, :archived ], _default: "active"
   #   end
   #
-  # Good practice is to let the first declared status be the default.
+  #   conversation = Conversation.new
+  #   conversation.status # => "active"
   #
   # Finally, it's also possible to explicitly map the relation between attribute and
   # database integer with a hash:
@@ -115,19 +124,18 @@ module ActiveRecord
       end
 
       def cast(value)
-        return if value.blank?
-
         if mapping.has_key?(value)
           value.to_s
         elsif mapping.has_value?(value)
           mapping.key(value)
+        elsif value.blank?
+          nil
         else
           assert_valid_value(value)
         end
       end
 
       def deserialize(value)
-        return if value.nil?
         mapping.key(subtype.deserialize(value))
       end
 
@@ -141,83 +149,134 @@ module ActiveRecord
         end
       end
 
-      # TODO Change this to private once we've dropped Ruby 2.2 support.
-      # Workaround for Ruby 2.2 "private attribute?" warning.
-      protected
+      attr_reader :subtype
 
-        attr_reader :name, :mapping, :subtype
+      private
+        attr_reader :name, :mapping
     end
 
     def enum(definitions)
-      klass = self
       enum_prefix = definitions.delete(:_prefix)
       enum_suffix = definitions.delete(:_suffix)
+      enum_scopes = definitions.delete(:_scopes)
+
+      default = {}
+      default[:default] = definitions.delete(:_default) if definitions.key?(:_default)
+
       definitions.each do |name, values|
+        assert_valid_enum_definition_values(values)
         # statuses = { }
         enum_values = ActiveSupport::HashWithIndifferentAccess.new
         name = name.to_s
 
         # def self.statuses() statuses end
         detect_enum_conflict!(name, name.pluralize, true)
-        singleton_class.send(:define_method, name.pluralize) { enum_values }
+        singleton_class.define_method(name.pluralize) { enum_values }
         defined_enums[name] = enum_values
 
         detect_enum_conflict!(name, name)
         detect_enum_conflict!(name, "#{name}=")
 
         attr = attribute_alias?(name) ? attribute_alias(name) : name
-        decorate_attribute_type(attr, :enum) do |subtype|
+
+        decorate_attribute_type(attr, **default) do |subtype|
           EnumType.new(attr, enum_values, subtype)
         end
 
+        value_method_names = []
         _enum_methods_module.module_eval do
+          prefix = if enum_prefix == true
+            "#{name}_"
+          elsif enum_prefix
+            "#{enum_prefix}_"
+          end
+
+          suffix = if enum_suffix == true
+            "_#{name}"
+          elsif enum_suffix
+            "_#{enum_suffix}"
+          end
+
           pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
           pairs.each do |label, value|
-            if enum_prefix == true
-              prefix = "#{name}_"
-            elsif enum_prefix
-              prefix = "#{enum_prefix}_"
-            end
-            if enum_suffix == true
-              suffix = "_#{name}"
-            elsif enum_suffix
-              suffix = "_#{enum_suffix}"
-            end
-
-            value_method_name = "#{prefix}#{label}#{suffix}"
             enum_values[label] = value
             label = label.to_s
 
-            # def active?() status == "active" end
-            klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
-            define_method("#{value_method_name}?") { self[attr] == label }
+            value_method_name = "#{prefix}#{label}#{suffix}"
+            value_method_names << value_method_name
+            define_enum_methods(name, value_method_name, value, enum_scopes)
 
-            # def active!() update!(status: 0) end
-            klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
-            define_method("#{value_method_name}!") { update!(attr => value) }
+            method_friendly_label = label.gsub(/[\W&&[:ascii:]]+/, "_")
+            value_method_alias = "#{prefix}#{method_friendly_label}#{suffix}"
 
-            # scope :active, -> { where(status: 0) }
-            klass.send(:detect_enum_conflict!, name, value_method_name, true)
-            klass.scope value_method_name, -> { where(attr => value) }
+            if value_method_alias != value_method_name && !value_method_names.include?(value_method_alias)
+              value_method_names << value_method_alias
+              define_enum_methods(name, value_method_alias, value, enum_scopes)
+            end
           end
         end
+        detect_negative_enum_conditions!(value_method_names) if enum_scopes != false
         enum_values.freeze
       end
     end
 
     private
+      class EnumMethods < Module # :nodoc:
+        def initialize(klass)
+          @klass = klass
+        end
+
+        private
+          attr_reader :klass
+
+          def define_enum_methods(name, value_method_name, value, enum_scopes)
+            # def active?() status_for_database == 0 end
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
+            define_method("#{value_method_name}?") { public_send(:"#{name}_for_database") == value }
+
+            # def active!() update!(status: 0) end
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
+            define_method("#{value_method_name}!") { update!(name => value) }
+
+            # scope :active, -> { where(status: 0) }
+            # scope :not_active, -> { where.not(status: 0) }
+            if enum_scopes != false
+              klass.send(:detect_enum_conflict!, name, value_method_name, true)
+              klass.scope value_method_name, -> { where(name => value) }
+
+              klass.send(:detect_enum_conflict!, name, "not_#{value_method_name}", true)
+              klass.scope "not_#{value_method_name}", -> { where.not(name => value) }
+            end
+          end
+      end
+      private_constant :EnumMethods
+
       def _enum_methods_module
         @_enum_methods_module ||= begin
-          mod = Module.new
+          mod = EnumMethods.new(self)
           include mod
           mod
         end
       end
 
+      def assert_valid_enum_definition_values(values)
+        unless values.is_a?(Hash) || values.all? { |v| v.is_a?(Symbol) } || values.all? { |v| v.is_a?(String) }
+          error_message = <<~MSG
+            Enum values #{values} must be either a hash, an array of symbols, or an array of strings.
+          MSG
+          raise ArgumentError, error_message
+        end
+
+        if values.is_a?(Hash) && values.keys.any?(&:blank?) || values.is_a?(Array) && values.any?(&:blank?)
+          raise ArgumentError, "Enum label name must not be blank."
+        end
+      end
+
       ENUM_CONFLICT_MESSAGE = \
         "You tried to define an enum named \"%{enum}\" on the model \"%{klass}\", but " \
         "this will generate a %{type} method \"%{method}\", which is already defined " \
         "by %{source}."
+      private_constant :ENUM_CONFLICT_MESSAGE
 
       def detect_enum_conflict!(enum_name, method_name, klass_method = false)
         if klass_method && dangerous_class_method?(method_name)
@@ -240,5 +299,18 @@ module ActiveRecord
           source: source
         }
       end
+
+      def detect_negative_enum_conditions!(method_names)
+        return unless logger
+
+        method_names.select { |m| m.start_with?("not_") }.each do |potential_not|
+          inverted_form = potential_not.sub("not_", "")
+          if method_names.include?(inverted_form)
+            logger.warn "Enum element '#{potential_not}' in #{self.name} uses the prefix 'not_'." \
+              " This has caused a conflict with auto generated negative scopes." \
+              " Avoid using enum elements starting with 'not' where the positive form is also an element."
+          end
+        end
+      end
   end
 end