activerecord 6.0.0 → 7.2.3

data/lib/active_record/enum.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/hash/slice"
 require "active_support/core_ext/object/deep_dup"
 
 module ActiveRecord
@@ -7,7 +8,7 @@ module ActiveRecord
   # but can be queried by name. Example:
   #
   #   class Conversation < ActiveRecord::Base
-  #     enum status: [ :active, :archived ]
+  #     enum :status, [ :active, :archived ]
   #   end
   #
   #   # conversation.update! status: 0
@@ -41,19 +42,33 @@ 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
   #
-  # Good practice is to let the first declared status be the default.
+  # You can set the default enum value by setting +:default+, like:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, [ :active, :archived ], default: :active
+  #   end
   #
-  # Finally, it's also possible to explicitly map the relation between attribute and
+  #   conversation = Conversation.new
+  #   conversation.status # => "active"
+  #
+  # It's possible to explicitly map the relation between attribute and
   # database integer with a hash:
   #
   #   class Conversation < ActiveRecord::Base
-  #     enum status: { active: 0, archived: 1 }
+  #     enum :status, active: 0, archived: 1
+  #   end
+  #
+  # Finally it's also possible to use a string column to persist the enumerated value.
+  # Note that this will likely lead to slower database queries:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, active: "active", archived: "archived"
   #   end
   #
   # Note that when an array is used, the implicit mapping from the values to database
@@ -68,7 +83,7 @@ module ActiveRecord
   #
   # In rare circumstances you might need to access the mapping directly.
   # The mappings are exposed through a class method with the pluralized attribute
-  # name, which return the mapping in a +HashWithIndifferentAccess+:
+  # name, which return the mapping in a ActiveSupport::HashWithIndifferentAccess :
   #
   #   Conversation.statuses[:active]    # => 0
   #   Conversation.statuses["archived"] # => 1
@@ -78,14 +93,14 @@ module ActiveRecord
   #
   #   Conversation.where("status <> ?", Conversation.statuses[:archived])
   #
-  # You can use the +:_prefix+ or +:_suffix+ options when you need to define
+  # You can use the +:prefix+ or +:suffix+ options when you need to define
   # multiple enums with same values. If the passed value is +true+, the methods
   # are prefixed/suffixed with the name of the enum. It is also possible to
   # supply a custom value:
   #
   #   class Conversation < ActiveRecord::Base
-  #     enum status: [:active, :archived], _suffix: true
-  #     enum comments_status: [:active, :inactive], _prefix: :comments
+  #     enum :status, [ :active, :archived ], suffix: true
+  #     enum :comments_status, [ :active, :inactive ], prefix: :comments
   #   end
   #
   # With the above example, the bang and predicate methods along with the
@@ -96,64 +111,137 @@ module ActiveRecord
   #
   #   conversation.comments_inactive!
   #   conversation.comments_active? # => false
-
+  #
+  # If you want to disable the auto-generated methods on the model, you can do
+  # so by setting the +:instance_methods+ option to false:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, [ :active, :archived ], instance_methods: false
+  #   end
+  #
+  # By default, an +ArgumentError+ will be raised when assigning an invalid value:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, [ :active, :archived ]
+  #   end
+  #
+  #   conversation = Conversation.new
+  #
+  #   conversation.status = :unknown # 'unknown' is not a valid status (ArgumentError)
+  #
+  # If, instead, you want the enum value to be validated before saving, use the
+  # +:validate+ option:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, [ :active, :archived ], validate: true
+  #   end
+  #
+  #   conversation = Conversation.new
+  #
+  #   conversation.status = :unknown
+  #   conversation.valid? # => false
+  #
+  #   conversation.status = nil
+  #   conversation.valid? # => false
+  #
+  #   conversation.status = :active
+  #   conversation.valid? # => true
+  #
+  # You may also pass additional validation options:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum :status, [ :active, :archived ], validate: { allow_nil: true }
+  #   end
+  #
+  #   conversation = Conversation.new
+  #
+  #   conversation.status = :unknown
+  #   conversation.valid? # => false
+  #
+  #   conversation.status = nil
+  #   conversation.valid? # => true
+  #
+  #   conversation.status = :active
+  #   conversation.valid? # => true
   module Enum
     def self.extended(base) # :nodoc:
       base.class_attribute(:defined_enums, instance_writer: false, default: {})
     end
 
-    def inherited(base) # :nodoc:
-      base.defined_enums = defined_enums.deep_dup
-      super
-    end
-
     class EnumType < Type::Value # :nodoc:
       delegate :type, to: :subtype
 
-      def initialize(name, mapping, subtype)
+      def initialize(name, mapping, subtype, raise_on_invalid_values: true)
         @name = name
         @mapping = mapping
         @subtype = subtype
+        @_raise_on_invalid_values = raise_on_invalid_values
       end
 
       def cast(value)
-        return if value.blank?
-
         if mapping.has_key?(value)
           value.to_s
         elsif mapping.has_value?(value)
           mapping.key(value)
         else
-          assert_valid_value(value)
+          value.presence
         end
       end
 
       def deserialize(value)
-        return if value.nil?
         mapping.key(subtype.deserialize(value))
       end
 
       def serialize(value)
-        mapping.fetch(value, value)
+        subtype.serialize(mapping.fetch(value, value))
+      end
+
+      def serializable?(value, &block)
+        subtype.serializable?(mapping.fetch(value, value), &block)
       end
 
       def assert_valid_value(value)
+        return unless @_raise_on_invalid_values
+
         unless value.blank? || mapping.has_key?(value) || mapping.has_value?(value)
           raise ArgumentError, "'#{value}' is not a valid #{name}"
         end
       end
 
+      attr_reader :subtype
+
       private
-        attr_reader :name, :mapping, :subtype
+        attr_reader :name, :mapping
+    end
+
+    def enum(name = nil, values = nil, **options)
+      if name
+        values, options = options, {} unless values
+        return _enum(name, values, **options)
+      end
+
+      definitions = options.slice!(:_prefix, :_suffix, :_scopes, :_default, :_instance_methods)
+      options.transform_keys! { |key| :"#{key[1..-1]}" }
+
+      definitions.each { |name, values| _enum(name, values, **options) }
+
+      ActiveRecord.deprecator.warn(<<~MSG)
+        Defining enums with keyword arguments is deprecated and will be removed
+        in Rails 8.0. Positional arguments should be used instead:
+
+        #{definitions.map { |name, values| "enum :#{name}, #{values}" }.join("\n")}
+      MSG
     end
 
-    def enum(definitions)
-      klass = self
-      enum_prefix = definitions.delete(:_prefix)
-      enum_suffix = definitions.delete(:_suffix)
-      enum_scopes = definitions.delete(:_scopes)
-      definitions.each do |name, values|
+    private
+      def inherited(base)
+        base.defined_enums = defined_enums.deep_dup
+        super
+      end
+
+      def _enum(name, values, prefix: nil, suffix: nil, scopes: true, instance_methods: true, validate: false, **options)
         assert_valid_enum_definition_values(values)
+        assert_valid_enum_options(options)
         # statuses = { }
         enum_values = ActiveSupport::HashWithIndifferentAccess.new
         name = name.to_s
@@ -166,73 +254,128 @@ module ActiveRecord
         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|
-          EnumType.new(attr, enum_values, subtype)
+        attribute(name, **options)
+
+        decorate_attributes([name]) do |_name, subtype|
+          if subtype == ActiveModel::Type.default_value
+            raise "Undeclared attribute type for enum '#{name}' in #{self.name}. Enums must be" \
+              " backed by a database column or declared with an explicit type" \
+              " via `attribute`."
+          end
+
+          subtype = subtype.subtype if EnumType === subtype
+          EnumType.new(name, enum_values, subtype, raise_on_invalid_values: !validate)
         end
 
+        value_method_names = []
         _enum_methods_module.module_eval do
+          prefix = if prefix
+            prefix == true ? "#{name}_" : "#{prefix}_"
+          end
+
+          suffix = if suffix
+            suffix == true ? "_#{name}" : "_#{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, scopes, instance_methods)
+
+            method_friendly_label = label.gsub(/[\W&&[:ascii:]]+/, "_")
+            value_method_alias = "#{prefix}#{method_friendly_label}#{suffix}"
 
-            # def active!() update!(status: 0) end
-            klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
-            define_method("#{value_method_name}!") { update!(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, scopes, instance_methods)
+            end
+          end
+        end
+        detect_negative_enum_conditions!(value_method_names) if scopes
 
-            # scope :active, -> { where(status: 0) }
-            # scope :not_active, -> { where.not(status: 0) }
-            if enum_scopes != false
-              klass.send(:detect_negative_condition!, value_method_name)
+        if validate
+          validate = {} unless Hash === validate
+          validates_inclusion_of name, in: enum_values.keys, **validate
+        end
 
+        enum_values.freeze
+      end
+
+      class EnumMethods < Module # :nodoc:
+        def initialize(klass)
+          @klass = klass
+        end
+
+        private
+          attr_reader :klass
+
+          def define_enum_methods(name, value_method_name, value, scopes, instance_methods)
+            if instance_methods
+              # 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) }
+            end
+
+            if scopes
+              # scope :active, -> { where(status: 0) }
               klass.send(:detect_enum_conflict!, name, value_method_name, true)
-              klass.scope value_method_name, -> { where(attr => value) }
+              klass.scope value_method_name, -> { where(name => value) }
 
+              # scope :not_active, -> { where.not(status: 0) }
               klass.send(:detect_enum_conflict!, name, "not_#{value_method_name}", true)
-              klass.scope "not_#{value_method_name}", -> { where.not(attr => value) }
+              klass.scope "not_#{value_method_name}", -> { where.not(name => value) }
             end
           end
-        end
-        enum_values.freeze
       end
-    end
+      private_constant :EnumMethods
 
-    private
       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
+        case values
+        when Hash
+          if values.empty?
+            raise ArgumentError, "Enum values #{values} must not be empty."
+          end
+
+          if values.keys.any?(&:blank?)
+            raise ArgumentError, "Enum values #{values} must not contain a blank name."
+          end
+        when Array
+          if values.empty?
+            raise ArgumentError, "Enum values #{values} must not be empty."
+          end
+
+          unless values.all?(Symbol) || values.all?(String)
+            raise ArgumentError, "Enum values #{values} must only contain symbols or strings."
+          end
+
+          if values.any?(&:blank?)
+            raise ArgumentError, "Enum values #{values} must not contain a blank name."
+          end
+        else
+          raise ArgumentError, "Enum values #{values} must be either a non-empty hash or an array."
         end
+      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."
+      def assert_valid_enum_options(options)
+        invalid_keys = options.keys & %i[_prefix _suffix _scopes _default _instance_methods]
+        unless invalid_keys.empty?
+          raise ArgumentError, "invalid option(s): #{invalid_keys.map(&:inspect).join(", ")}. Valid options are: :prefix, :suffix, :scopes, :default, :instance_methods, and :validate."
         end
       end
 
@@ -247,6 +390,8 @@ module ActiveRecord
           raise_conflict_error(enum_name, method_name, type: "class")
         elsif klass_method && method_defined_within?(method_name, Relation)
           raise_conflict_error(enum_name, method_name, type: "class", source: Relation.name)
+        elsif klass_method && method_name.to_sym == :id
+          raise_conflict_error(enum_name, method_name)
         elsif !klass_method && dangerous_attribute_method?(method_name)
           raise_conflict_error(enum_name, method_name)
         elsif !klass_method && method_defined_within?(method_name, _enum_methods_module, Module)
@@ -264,10 +409,16 @@ module ActiveRecord
         }
       end
 
-      def detect_negative_condition!(method_name)
-        if method_name.start_with?("not_") && logger
-          logger.warn "An enum element in #{self.name} uses the prefix 'not_'." \
-            " This will cause a conflict with auto generated negative scopes."
+      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