Migrate ActiveRecord::Normalization to Active Model

Follow-up to [rails#53954][]
Re-submission of [rails#53887][]
Closes [rails#53793][]
Follow-up to [rails#43945][]

To support this behavior, the bulk of the implementation is moved to the
new `ActiveModel::Normalization` module. Any "persistence"-related
language, methods, and test coverage has been excised. The single
implementation change is related to reading and writing attributes:

```diff
  def normalize_attribute(name)
    # Treat the value as a new, unnormalized value.
-  self[name] = self[name]
+  send(:"#{name}=", send(name))
  end
```

This can be undone if a change like [rails#53886][] lands.

[rails#53954]: rails#53954
[rails#53887]: rails#53887
[rails#53793]: rails#53793
[rails#43945]: rails#43945
[rails#53886]: rails#53886

Author: seanpdoyle

activemodel/CHANGELOG.md

@@ -1,2 +1,20 @@
+*   Backport `ActiveRecord::Normalization` to `ActiveModel::Attributes::Normalization`
+
+    ```ruby
+    class User
+      include ActiveModel::Attributes
+      include ActiveModel::Attributes::Normalization
+
+      attribute :email, :string
+
+      normalizes :email, with: -> email { email.strip.downcase }
+    end
+
+    user = User.new
+    user.email =    " [email protected]\n"
+    user.email # => "[email protected]"
+    ```
+
+    *Sean Doyle*
 
 Please check [8-0-stable](https://github.com/rails/rails/blob/8-0-stable/activemodel/CHANGELOG.md) for previous changes.

activemodel/lib/active_model.rb

@@ -56,6 +56,12 @@ module ActiveModel
   autoload :Validations
   autoload :Validator
 
+  module Attributes
+    extend ActiveSupport::Autoload
+
+    autoload :Normalization
+  end
+
   eager_autoload do
     autoload :Errors
     autoload :Error

activemodel/lib/active_model/attributes/normalization.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  module Attributes
+    module Normalization
+      extend ActiveSupport::Concern
+
+      included do
+        include ActiveModel::Dirty
+        include ActiveModel::Validations::Callbacks
+
+        class_attribute :normalized_attributes, default: Set.new
+
+        before_validation :normalize_changed_in_place_attributes
+      end
+
+      # Normalizes a specified attribute using its declared normalizations.
+      #
+      # ==== Examples
+      #
+      #   class User
+      #     include ActiveModel::Attributes
+      #     include ActiveModel::Attributes::Normalization
+      #
+      #     attribute :email, :string
+      #
+      #     normalizes :email, with: -> email { email.strip.downcase }
+      #   end
+      #
+      #   legacy_user = User.load_from_legacy_data(...)
+      #   legacy_user.email # => " [email protected]\n"
+      #   legacy_user.normalize_attribute(:email)
+      #   legacy_user.email # => "[email protected]"
+      #
+      # ==== Behavior with Active Record
+      #
+      # To prevent confusion, normalization will not be applied
+      # when the attribute is fetched from the database. This means that if a
+      # record was persisted before the normalization was declared, the record's
+      # attribute will not be normalized until either it is assigned a new
+      # value, or it is explicitly migrated via Normalization#normalize_attribute.
+      #
+      # Be aware that if your app was created before Rails 7.1, and your app
+      # marshals instances of the targeted model (for example, when caching),
+      # then you should set ActiveRecord.marshalling_format_version to +7.1+ or
+      # higher via either <tt>config.load_defaults 7.1</tt> or
+      # <tt>config.active_record.marshalling_format_version = 7.1</tt>.
+      # Otherwise, +Marshal+ may attempt to serialize the normalization +Proc+
+      # and raise +TypeError+.
+      #
+      #   class User < ActiveRecord::Base
+      #     normalizes :email, with: -> email { email.strip.downcase }
+      #     normalizes :phone, with: -> phone { phone.delete("^0-9").delete_prefix("1") }
+      #   end
+      #
+      #   user = User.create(email: " [email protected]\n")
+      #   user.email                  # => "[email protected]"
+      #
+      #   user = User.find_by(email: "\[email protected] ")
+      #   user.email                  # => "[email protected]"
+      #   user.email_before_type_cast # => "[email protected]"
+      #
+      #   User.where(email: "\[email protected] ").count         # => 1
+      #   User.where(["email = ?", "\[email protected] "]).count # => 0
+      #
+      #   User.exists?(email: "\[email protected] ")         # => true
+      #   User.exists?(["email = ?", "\[email protected] "]) # => false
+      #
+      #   User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"
+      def normalize_attribute(name)
+        # Treat the value as a new, unnormalized value.
+        send(:"#{name}=", send(name))
+      end
+
+      module ClassMethods
+        # Declares a normalization for one or more attributes. The normalization
+        # is applied when the attribute is assigned or validated.
+        #
+        # Because the normalization may be applied multiple times, it should be
+        # _idempotent_. In other words, applying the normalization more than once
+        # should have the same result as applying it only once.
+        #
+        # By default, the normalization will not be applied to +nil+ values. This
+        # behavior can be changed with the +:apply_to_nil+ option.
+        #
+        # ==== Options
+        #
+        # * +:with+ - Any callable object that accepts the attribute's value as
+        #   its sole argument, and returns it normalized.
+        # * +:apply_to_nil+ - Whether to apply the normalization to +nil+ values.
+        #   Defaults to +false+.
+        #
+        # ==== Examples
+        #
+        #   class User
+        #     include ActiveModel::Attributes
+        #     include ActiveModel::Attributes::Normalization
+        #
+        #     attribute :email, :string
+        #     attribute :phone, :string
+        #
+        #     normalizes :email, with: -> email { email.strip.downcase }
+        #     normalizes :phone, with: -> phone { phone.delete("^0-9").delete_prefix("1") }
+        #   end
+        #
+        #   user = User.new
+        #   user.email =    " [email protected]\n"
+        #   user.email # => "[email protected]"
+        #
+        #   User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"
+        def normalizes(*names, with:, apply_to_nil: false)
+          decorate_attributes(names) do |name, cast_type|
+            NormalizedValueType.new(cast_type: cast_type, normalizer: with, normalize_nil: apply_to_nil)
+          end
+
+          self.normalized_attributes += names.map(&:to_sym)
+        end
+
+        # Normalizes a given +value+ using normalizations declared for +name+.
+        #
+        # ==== Examples
+        #
+        #   class User
+        #     include ActiveModel::Attributes
+        #     include ActiveModel::Attributes::Normalization
+        #
+        #     attribute :email, :string
+        #
+        #     normalizes :email, with: -> email { email.strip.downcase }
+        #   end
+        #
+        #   User.normalize_value_for(:email, " [email protected]\n")
+        #   # => "[email protected]"
+        def normalize_value_for(name, value)
+          type_for_attribute(name).cast(value)
+        end
+      end
+
+      private
+        def normalize_changed_in_place_attributes
+          self.class.normalized_attributes.each do |name|
+            normalize_attribute(name) if attribute_changed_in_place?(name)
+          end
+        end
+
+        class NormalizedValueType < DelegateClass(ActiveModel::Type::Value) # :nodoc:
+          include ActiveModel::Type::SerializeCastValue
+
+          attr_reader :cast_type, :normalizer, :normalize_nil
+          alias :normalize_nil? :normalize_nil
+
+          def initialize(cast_type:, normalizer:, normalize_nil:)
+            @cast_type = cast_type
+            @normalizer = normalizer
+            @normalize_nil = normalize_nil
+            super(cast_type)
+          end
+
+          def cast(value)
+            normalize(super(value))
+          end
+
+          def serialize(value)
+            serialize_cast_value(cast(value))
+          end
+
+          def serialize_cast_value(value)
+            ActiveModel::Type::SerializeCastValue.serialize(cast_type, value)
+          end
+
+          def ==(other)
+            self.class == other.class &&
+              normalize_nil? == other.normalize_nil? &&
+              normalizer == other.normalizer &&
+              cast_type == other.cast_type
+          end
+          alias eql? ==
+
+          def hash
+            [self.class, cast_type, normalizer, normalize_nil?].hash
+          end
+
+          define_method(:inspect, Kernel.instance_method(:inspect))
+
+          private
+            def normalize(value)
+              normalizer.call(value) unless value.nil? && !normalize_nil?
+            end
+        end
+    end
+  end
+end

activemodel/test/cases/attributes/normalization_test.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "cases/helper"
+
+class NormalizedAttributeTest < ActiveModel::TestCase
+  class Aircraft
+    include ActiveModel::API
+    include ActiveModel::Attributes
+    include ActiveModel::Attributes::Normalization
+
+    attribute :manufactured_at, :datetime, default: -> { Time.current }
+    attribute :name, :string
+    attribute :wheels_count, :integer, default: 0
+    attribute :wheels_owned_at, :datetime
+  end
+
+  class NormalizedAircraft < Aircraft
+    normalizes :name, with: -> name { name.presence&.titlecase }
+    normalizes :manufactured_at, with: -> time { time.noon }
+
+    attr_accessor :validated_name
+    validate { self.validated_name = name.dup }
+  end
+
+  setup do
+    @time = Time.utc(1999, 12, 31, 12, 34, 56)
+    @aircraft = NormalizedAircraft.new(name: "fly HIGH", manufactured_at: @time)
+  end
+
+  test "normalizes value from validation" do
+    @aircraft.validate!
+
+    assert_equal "Fly High", @aircraft.name
+  end
+
+  test "normalizes value from assignment" do
+    @aircraft.name = "fly HIGHER"
+    assert_equal "Fly Higher", @aircraft.name
+  end
+
+  test "normalizes changed-in-place value before validation" do
+    @aircraft.name.downcase!
+    assert_equal "fly high", @aircraft.name
+
+    @aircraft.valid?
+    assert_equal "Fly High", @aircraft.validated_name
+  end
+
+  test "normalizes value on demand" do
+    @aircraft.name.downcase!
+    assert_equal "fly high", @aircraft.name
+
+    @aircraft.normalize_attribute(:name)
+    assert_equal "Fly High", @aircraft.name
+  end
+
+  test "normalizes value without model" do
+    assert_equal "Titlecase Me", NormalizedAircraft.normalize_value_for(:name, "titlecase ME")
+  end
+
+  test "casts value when no normalization is declared" do
+    assert_equal 6, NormalizedAircraft.normalize_value_for(:wheels_count, "6")
+  end
+
+  test "casts value before applying normalization" do
+    @aircraft.manufactured_at = @time.to_s
+    assert_equal @time.noon, @aircraft.manufactured_at
+  end
+
+  test "ignores nil by default" do
+    assert_nil NormalizedAircraft.normalize_value_for(:name, nil)
+  end
+
+  test "normalizes nil if apply_to_nil" do
+    including_nil = Class.new(Aircraft) do
+      normalizes :name, with: -> name { name&.titlecase || "Untitled" }, apply_to_nil: true
+    end
+
+    assert_equal "Untitled", including_nil.normalize_value_for(:name, nil)
+  end
+
+  test "can stack normalizations" do
+    titlecase_then_reverse = Class.new(NormalizedAircraft) do
+      normalizes :name, with: -> name { name.reverse }
+    end
+
+    assert_equal "esreveR nehT esaceltiT", titlecase_then_reverse.normalize_value_for(:name, "titlecase THEN reverse")
+    assert_equal "Only Titlecase", NormalizedAircraft.normalize_value_for(:name, "ONLY titlecase")
+  end
+
+  test "minimizes number of times normalization is applied" do
+    count_applied = Class.new(Aircraft) do
+      normalizes :name, with: -> name { name.succ }
+    end
+
+    aircraft = count_applied.new(name: "0")
+    assert_equal "1", aircraft.name
+
+    aircraft.name = "0"
+    assert_equal "1", aircraft.name
+
+    aircraft.name.replace("0")
+    assert_equal "0", aircraft.name
+  end
+end

activerecord/lib/active_record.rb

@@ -62,7 +62,6 @@ module ActiveRecord
   autoload :ModelSchema
   autoload :NestedAttributes
   autoload :NoTouching
-  autoload :Normalization
   autoload :Persistence
   autoload :QueryCache
   autoload :QueryLogs

activerecord/lib/active_record/attributes.rb

@@ -7,6 +7,7 @@ module ActiveRecord
   module Attributes
     extend ActiveSupport::Concern
     include ActiveModel::AttributeRegistration
+    include ActiveModel::Attributes::Normalization
 
     # = Active Record \Attributes
     module ClassMethods

activerecord/lib/active_record/base.rb

@@ -328,7 +328,6 @@ class Base
     include TokenFor
     include SignedId
     include Suppressor
-    include Normalization
     include Marshalling::Methods
 
     self.param_delimiter = "_"