activerecord 6.0.1

data/lib/active_record/attribute_methods/read.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module AttributeMethods
+    module Read
+      extend ActiveSupport::Concern
+
+      module ClassMethods # :nodoc:
+        private
+
+          def define_method_attribute(name)
+            ActiveModel::AttributeMethods::AttrNames.define_attribute_accessor_method(
+              generated_attribute_methods, name
+            ) do |temp_method_name, attr_name_expr|
+              generated_attribute_methods.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+                def #{temp_method_name}
+                  name = #{attr_name_expr}
+                  _read_attribute(name) { |n| missing_attribute(n, caller) }
+                end
+              RUBY
+            end
+          end
+      end
+
+      # Returns the value of the attribute identified by <tt>attr_name</tt> after
+      # it has been typecast (for example, "2004-12-12" in a date column is cast
+      # to a date object, like Date.new(2004, 12, 12)).
+      def read_attribute(attr_name, &block)
+        name = attr_name.to_s
+        name = self.class.attribute_aliases[name] || name
+
+        name = @primary_key if name == "id" && @primary_key
+        _read_attribute(name, &block)
+      end
+
+      # This method exists to avoid the expensive primary_key check internally, without
+      # breaking compatibility with the read_attribute API
+      def _read_attribute(attr_name, &block) # :nodoc
+        sync_with_transaction_state if @transaction_state&.finalized?
+        @attributes.fetch_value(attr_name.to_s, &block)
+      end
+
+      alias :attribute :_read_attribute
+      private :attribute
+    end
+  end
+end

data/lib/active_record/attribute_methods/serialization.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module AttributeMethods
+    module Serialization
+      extend ActiveSupport::Concern
+
+      class ColumnNotSerializableError < StandardError
+        def initialize(name, type)
+          super <<~EOS
+            Column `#{name}` of type #{type.class} does not support `serialize` feature.
+            Usually it means that you are trying to use `serialize`
+            on a column that already implements serialization natively.
+          EOS
+        end
+      end
+
+      module ClassMethods
+        # If you have an attribute that needs to be saved to the database as an
+        # object, and retrieved as the same object, then specify the name of that
+        # attribute using this method and it will be handled automatically. The
+        # serialization is done through YAML. If +class_name+ is specified, the
+        # serialized object must be of that class on assignment and retrieval.
+        # Otherwise SerializationTypeMismatch will be raised.
+        #
+        # Empty objects as <tt>{}</tt>, in the case of +Hash+, or <tt>[]</tt>, in the case of
+        # +Array+, will always be persisted as null.
+        #
+        # Keep in mind that database adapters handle certain serialization tasks
+        # for you. For instance: +json+ and +jsonb+ types in PostgreSQL will be
+        # converted between JSON object/array syntax and Ruby +Hash+ or +Array+
+        # objects transparently. There is no need to use #serialize in this
+        # case.
+        #
+        # For more complex cases, such as conversion to or from your application
+        # domain objects, consider using the ActiveRecord::Attributes API.
+        #
+        # ==== Parameters
+        #
+        # * +attr_name+ - The field name that should be serialized.
+        # * +class_name_or_coder+ - Optional, a coder object, which responds to +.load+ and +.dump+
+        #   or a class name that the object type should be equal to.
+        #
+        # ==== Example
+        #
+        #   # Serialize a preferences attribute.
+        #   class User < ActiveRecord::Base
+        #     serialize :preferences
+        #   end
+        #
+        #   # Serialize preferences using JSON as coder.
+        #   class User < ActiveRecord::Base
+        #     serialize :preferences, JSON
+        #   end
+        #
+        #   # Serialize preferences as Hash using YAML coder.
+        #   class User < ActiveRecord::Base
+        #     serialize :preferences, Hash
+        #   end
+        def serialize(attr_name, class_name_or_coder = Object)
+          # When ::JSON is used, force it to go through the Active Support JSON encoder
+          # to ensure special objects (e.g. Active Record models) are dumped correctly
+          # using the #as_json hook.
+          coder = if class_name_or_coder == ::JSON
+            Coders::JSON
+          elsif [:load, :dump].all? { |x| class_name_or_coder.respond_to?(x) }
+            class_name_or_coder
+          else
+            Coders::YAMLColumn.new(attr_name, class_name_or_coder)
+          end
+
+          decorate_attribute_type(attr_name, :serialize) do |type|
+            if type_incompatible_with_serialize?(type, class_name_or_coder)
+              raise ColumnNotSerializableError.new(attr_name, type)
+            end
+
+            Type::Serialized.new(type, coder)
+          end
+        end
+
+        private
+
+          def type_incompatible_with_serialize?(type, class_name)
+            type.is_a?(ActiveRecord::Type::Json) && class_name == ::JSON ||
+              type.respond_to?(:type_cast_array, true) && class_name == ::Array
+          end
+      end
+    end
+  end
+end

data/lib/active_record/attribute_methods/time_zone_conversion.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module AttributeMethods
+    module TimeZoneConversion
+      class TimeZoneConverter < DelegateClass(Type::Value) # :nodoc:
+        def deserialize(value)
+          convert_time_to_time_zone(super)
+        end
+
+        def cast(value)
+          return if value.nil?
+
+          if value.is_a?(Hash)
+            set_time_zone_without_conversion(super)
+          elsif value.respond_to?(:in_time_zone)
+            begin
+              super(user_input_in_time_zone(value)) || super
+            rescue ArgumentError
+              nil
+            end
+          else
+            map_avoiding_infinite_recursion(super) { |v| cast(v) }
+          end
+        end
+
+        private
+
+          def convert_time_to_time_zone(value)
+            return if value.nil?
+
+            if value.acts_like?(:time)
+              value.in_time_zone
+            elsif value.is_a?(::Float)
+              value
+            else
+              map_avoiding_infinite_recursion(value) { |v| convert_time_to_time_zone(v) }
+            end
+          end
+
+          def set_time_zone_without_conversion(value)
+            ::Time.zone.local_to_utc(value).try(:in_time_zone) if value
+          end
+
+          def map_avoiding_infinite_recursion(value)
+            map(value) do |v|
+              if value.equal?(v)
+                nil
+              else
+                yield(v)
+              end
+            end
+          end
+      end
+
+      extend ActiveSupport::Concern
+
+      included do
+        mattr_accessor :time_zone_aware_attributes, instance_writer: false, default: false
+
+        class_attribute :skip_time_zone_conversion_for_attributes, instance_writer: false, default: []
+        class_attribute :time_zone_aware_types, instance_writer: false, default: [ :datetime, :time ]
+      end
+
+      module ClassMethods # :nodoc:
+        private
+
+          def inherited(subclass)
+            super
+            # We need to apply this decorator here, rather than on module inclusion. The closure
+            # created by the matcher would otherwise evaluate for `ActiveRecord::Base`, not the
+            # sub class being decorated. As such, changes to `time_zone_aware_attributes`, or
+            # `skip_time_zone_conversion_for_attributes` would not be picked up.
+            subclass.class_eval do
+              matcher = ->(name, type) { create_time_zone_conversion_attribute?(name, type) }
+              decorate_matching_attribute_types(matcher, "_time_zone_conversion") do |type|
+                TimeZoneConverter.new(type)
+              end
+            end
+          end
+
+          def create_time_zone_conversion_attribute?(name, cast_type)
+            enabled_for_column = time_zone_aware_attributes &&
+              !skip_time_zone_conversion_for_attributes.include?(name.to_sym)
+
+            enabled_for_column && time_zone_aware_types.include?(cast_type.type)
+          end
+      end
+    end
+  end
+end

data/lib/active_record/attribute_methods/write.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module AttributeMethods
+    module Write
+      extend ActiveSupport::Concern
+
+      included do
+        attribute_method_suffix "="
+      end
+
+      module ClassMethods # :nodoc:
+        private
+
+          def define_method_attribute=(name)
+            ActiveModel::AttributeMethods::AttrNames.define_attribute_accessor_method(
+              generated_attribute_methods, name, writer: true,
+            ) do |temp_method_name, attr_name_expr|
+              generated_attribute_methods.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+                def #{temp_method_name}(value)
+                  name = #{attr_name_expr}
+                  _write_attribute(name, value)
+                end
+              RUBY
+            end
+          end
+      end
+
+      # Updates the attribute identified by <tt>attr_name</tt> with the
+      # specified +value+. Empty strings for Integer and Float columns are
+      # turned into +nil+.
+      def write_attribute(attr_name, value)
+        name = attr_name.to_s
+        name = self.class.attribute_aliases[name] || name
+
+        name = @primary_key if name == "id" && @primary_key
+        _write_attribute(name, value)
+      end
+
+      # This method exists to avoid the expensive primary_key check internally, without
+      # breaking compatibility with the write_attribute API
+      def _write_attribute(attr_name, value) # :nodoc:
+        sync_with_transaction_state if @transaction_state&.finalized?
+        @attributes.write_from_user(attr_name.to_s, value)
+        value
+      end
+
+      private
+        def write_attribute_without_type_cast(attr_name, value)
+          sync_with_transaction_state if @transaction_state&.finalized?
+          @attributes.write_cast_value(attr_name.to_s, value)
+          value
+        end
+
+        # Dispatch target for <tt>*=</tt> attribute methods.
+        def attribute=(attribute_name, value)
+          _write_attribute(attribute_name, value)
+        end
+    end
+  end
+end

data/lib/active_record/attributes.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require "active_model/attribute/user_provided_default"
+
+module ActiveRecord
+  # See ActiveRecord::Attributes::ClassMethods for documentation
+  module Attributes
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :attributes_to_define_after_schema_loads, instance_accessor: false, default: {} # :internal:
+    end
+
+    module ClassMethods
+      # Defines an attribute with a type on this model. It will override the
+      # type of existing attributes if needed. This allows control over how
+      # values are converted to and from SQL when assigned to a model. It also
+      # changes the behavior of values passed to
+      # {ActiveRecord::Base.where}[rdoc-ref:QueryMethods#where]. This will let you use
+      # your domain objects across much of Active Record, without having to
+      # rely on implementation details or monkey patching.
+      #
+      # +name+ The name of the methods to define attribute methods for, and the
+      # column which this will persist to.
+      #
+      # +cast_type+ A symbol such as +:string+ or +:integer+, or a type object
+      # to be used for this attribute. See the examples below for more
+      # information about providing custom type objects.
+      #
+      # ==== Options
+      #
+      # The following options are accepted:
+      #
+      # +default+ The default value to use when no value is provided. If this option
+      # is not passed, the previous default value (if any) will be used.
+      # Otherwise, the default will be +nil+.
+      #
+      # +array+ (PostgreSQL only) specifies that the type should be an array (see the
+      # examples below).
+      #
+      # +range+ (PostgreSQL only) specifies that the type should be a range (see the
+      # examples below).
+      #
+      # When using a symbol for +cast_type+, extra options are forwarded to the
+      # constructor of the type object.
+      #
+      # ==== Examples
+      #
+      # The type detected by Active Record can be overridden.
+      #
+      #   # db/schema.rb
+      #   create_table :store_listings, force: true do |t|
+      #     t.decimal :price_in_cents
+      #   end
+      #
+      #   # app/models/store_listing.rb
+      #   class StoreListing < ActiveRecord::Base
+      #   end
+      #
+      #   store_listing = StoreListing.new(price_in_cents: '10.1')
+      #
+      #   # before
+      #   store_listing.price_in_cents # => BigDecimal(10.1)
+      #
+      #   class StoreListing < ActiveRecord::Base
+      #     attribute :price_in_cents, :integer
+      #   end
+      #
+      #   # after
+      #   store_listing.price_in_cents # => 10
+      #
+      # A default can also be provided.
+      #
+      #   # db/schema.rb
+      #   create_table :store_listings, force: true do |t|
+      #     t.string :my_string, default: "original default"
+      #   end
+      #
+      #   StoreListing.new.my_string # => "original default"
+      #
+      #   # app/models/store_listing.rb
+      #   class StoreListing < ActiveRecord::Base
+      #     attribute :my_string, :string, default: "new default"
+      #   end
+      #
+      #   StoreListing.new.my_string # => "new default"
+      #
+      #   class Product < ActiveRecord::Base
+      #     attribute :my_default_proc, :datetime, default: -> { Time.now }
+      #   end
+      #
+      #   Product.new.my_default_proc # => 2015-05-30 11:04:48 -0600
+      #   sleep 1
+      #   Product.new.my_default_proc # => 2015-05-30 11:04:49 -0600
+      #
+      # \Attributes do not need to be backed by a database column.
+      #
+      #   # app/models/my_model.rb
+      #   class MyModel < ActiveRecord::Base
+      #     attribute :my_string, :string
+      #     attribute :my_int_array, :integer, array: true
+      #     attribute :my_float_range, :float, range: true
+      #   end
+      #
+      #   model = MyModel.new(
+      #     my_string: "string",
+      #     my_int_array: ["1", "2", "3"],
+      #     my_float_range: "[1,3.5]",
+      #   )
+      #   model.attributes
+      #   # =>
+      #     {
+      #       my_string: "string",
+      #       my_int_array: [1, 2, 3],
+      #       my_float_range: 1.0..3.5
+      #     }
+      #
+      # Passing options to the type constructor
+      #
+      #   # app/models/my_model.rb
+      #   class MyModel < ActiveRecord::Base
+      #     attribute :small_int, :integer, limit: 2
+      #   end
+      #
+      #   MyModel.create(small_int: 65537)
+      #   # => Error: 65537 is out of range for the limit of two bytes
+      #
+      # ==== Creating Custom Types
+      #
+      # Users may also define their own custom types, as long as they respond
+      # to the methods defined on the value type. The method +deserialize+ or
+      # +cast+ will be called on your type object, with raw input from the
+      # database or from your controllers. See ActiveModel::Type::Value for the
+      # expected API. It is recommended that your type objects inherit from an
+      # existing type, or from ActiveRecord::Type::Value
+      #
+      #   class MoneyType < ActiveRecord::Type::Integer
+      #     def cast(value)
+      #       if !value.kind_of?(Numeric) && value.include?('$')
+      #         price_in_dollars = value.gsub(/\$/, '').to_f
+      #         super(price_in_dollars * 100)
+      #       else
+      #         super
+      #       end
+      #     end
+      #   end
+      #
+      #   # config/initializers/types.rb
+      #   ActiveRecord::Type.register(:money, MoneyType)
+      #
+      #   # app/models/store_listing.rb
+      #   class StoreListing < ActiveRecord::Base
+      #     attribute :price_in_cents, :money
+      #   end
+      #
+      #   store_listing = StoreListing.new(price_in_cents: '$10.00')
+      #   store_listing.price_in_cents # => 1000
+      #
+      # For more details on creating custom types, see the documentation for
+      # ActiveModel::Type::Value. For more details on registering your types
+      # to be referenced by a symbol, see ActiveRecord::Type.register. You can
+      # also pass a type object directly, in place of a symbol.
+      #
+      # ==== \Querying
+      #
+      # When {ActiveRecord::Base.where}[rdoc-ref:QueryMethods#where] is called, it will
+      # use the type defined by the model class to convert the value to SQL,
+      # calling +serialize+ on your type object. For example:
+      #
+      #   class Money < Struct.new(:amount, :currency)
+      #   end
+      #
+      #   class MoneyType < Type::Value
+      #     def initialize(currency_converter:)
+      #       @currency_converter = currency_converter
+      #     end
+      #
+      #     # value will be the result of +deserialize+ or
+      #     # +cast+. Assumed to be an instance of +Money+ in
+      #     # this case.
+      #     def serialize(value)
+      #       value_in_bitcoins = @currency_converter.convert_to_bitcoins(value)
+      #       value_in_bitcoins.amount
+      #     end
+      #   end
+      #
+      #   # config/initializers/types.rb
+      #   ActiveRecord::Type.register(:money, MoneyType)
+      #
+      #   # app/models/product.rb
+      #   class Product < ActiveRecord::Base
+      #     currency_converter = ConversionRatesFromTheInternet.new
+      #     attribute :price_in_bitcoins, :money, currency_converter: currency_converter
+      #   end
+      #
+      #   Product.where(price_in_bitcoins: Money.new(5, "USD"))
+      #   # => SELECT * FROM products WHERE price_in_bitcoins = 0.02230
+      #
+      #   Product.where(price_in_bitcoins: Money.new(5, "GBP"))
+      #   # => SELECT * FROM products WHERE price_in_bitcoins = 0.03412
+      #
+      # ==== Dirty Tracking
+      #
+      # The type of an attribute is given the opportunity to change how dirty
+      # tracking is performed. The methods +changed?+ and +changed_in_place?+
+      # will be called from ActiveModel::Dirty. See the documentation for those
+      # methods in ActiveModel::Type::Value for more details.
+      def attribute(name, cast_type = Type::Value.new, **options)
+        name = name.to_s
+        reload_schema_from_cache
+
+        self.attributes_to_define_after_schema_loads =
+          attributes_to_define_after_schema_loads.merge(
+            name => [cast_type, options]
+          )
+      end
+
+      # This is the low level API which sits beneath +attribute+. It only
+      # accepts type objects, and will do its work immediately instead of
+      # waiting for the schema to load. Automatic schema detection and
+      # ClassMethods#attribute both call this under the hood. While this method
+      # is provided so it can be used by plugin authors, application code
+      # should probably use ClassMethods#attribute.
+      #
+      # +name+ The name of the attribute being defined. Expected to be a +String+.
+      #
+      # +cast_type+ The type object to use for this attribute.
+      #
+      # +default+ The default value to use when no value is provided. If this option
+      # is not passed, the previous default value (if any) will be used.
+      # Otherwise, the default will be +nil+. A proc can also be passed, and
+      # will be called once each time a new value is needed.
+      #
+      # +user_provided_default+ Whether the default value should be cast using
+      # +cast+ or +deserialize+.
+      def define_attribute(
+        name,
+        cast_type,
+        default: NO_DEFAULT_PROVIDED,
+        user_provided_default: true
+      )
+        attribute_types[name] = cast_type
+        define_default_attribute(name, default, cast_type, from_user: user_provided_default)
+      end
+
+      def load_schema! # :nodoc:
+        super
+        attributes_to_define_after_schema_loads.each do |name, (type, options)|
+          if type.is_a?(Symbol)
+            type = ActiveRecord::Type.lookup(type, **options.except(:default))
+          end
+
+          define_attribute(name, type, **options.slice(:default))
+        end
+      end
+
+      private
+
+        NO_DEFAULT_PROVIDED = Object.new # :nodoc:
+        private_constant :NO_DEFAULT_PROVIDED
+
+        def define_default_attribute(name, value, type, from_user:)
+          if value == NO_DEFAULT_PROVIDED
+            default_attribute = _default_attributes[name].with_type(type)
+          elsif from_user
+            default_attribute = ActiveModel::Attribute::UserProvidedDefault.new(
+              name,
+              value,
+              type,
+              _default_attributes.fetch(name.to_s) { nil },
+            )
+          else
+            default_attribute = ActiveModel::Attribute.from_database(name, value, type)
+          end
+          _default_attributes[name] = default_attribute
+        end
+    end
+  end
+end