paper_trail 12.0.0 → 12.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2ce7f019e3413c485beff4eefa957f759b084fe0d29b0d9f3451b6ba3e4befe
-  data.tar.gz: 3f73870b42c582f683936eee21fe288b17d915d1bfbff5327ac50dd8e9766732
+  metadata.gz: e0f6ef6591b15081a76d93a70d959527f8cdc53cc3a6343ab6f1b7c40ef6695e
+  data.tar.gz: 202ee3126567ab99b39f8c76039fb7e20a4eb5e10e0e0880e867f19f228ace63
 SHA512:
-  metadata.gz: 6134547d0c2c69f94962aea4f868aec8d456bbb0afc4588b9b07971074a8d50476f29a59acb41d3e058dea581678d0c7129d8e92a04c370fa2016dbd6bf544b7
-  data.tar.gz: a6ca4e41cf2f6bce774894a9927dc0b3e4abbcbbdbb39fbf4671d029398f26999ce8927143f1f14279a6ad8aa70194025f5b6e653780560a0cc4870dce9b754e
+  metadata.gz: c144126a2d8cec5537ef218b6637ee2ff6e6863de2e935facf6ad020dba6c2fb46bc5c13ed2ab674e9230c264d6e87905415ebc3c1e4bee5fbe50b1e73285663
+  data.tar.gz: 96530aebe8af35a95d47b6a5deadd3797b2d9255b28156f24a9f1be67fe629b254747d39ccad4d8f5d348d9fd74300b4b865ff9b32125c0951b14cf5d13ed60f

data/lib/generators/paper_trail/install/install_generator.rb

@@ -20,6 +20,12 @@ module PaperTrail
       default: false,
       desc: "Store changeset (diff) with each version"
     )
+    class_option(
+      :uuid,
+      type: :boolean,
+      default: false,
+      desc: "Use uuid instead of bigint for item_id type (use only if tables use UUIDs)"
+    )
 
     desc "Generates (but does not run) a migration to add a versions table." \
          "  See section 5.c. Generators in README.md for more information."
@@ -28,7 +34,8 @@ module PaperTrail
       add_paper_trail_migration(
         "create_versions",
         item_type_options: item_type_options,
-        versions_table_options: versions_table_options
+        versions_table_options: versions_table_options,
+        item_id_type_options: item_id_type_options
       )
       if options.with_changes?
         add_paper_trail_migration("add_object_changes_to_versions")
@@ -37,13 +44,18 @@ module PaperTrail
 
     private
 
+    # To use uuid instead of integer for primary key
+    def item_id_type_options
+      options.uuid? ? "string" : "bigint"
+    end
+
     # MySQL 5.6 utf8mb4 limit is 191 chars for keys used in indexes.
     # See https://github.com/paper-trail-gem/paper_trail/issues/651
     def item_type_options
       if mysql?
-        ", { null: false, limit: 191 }"
+        ", null: false, limit: 191"
       else
-        ", { null: false }"
+        ", null: false"
       end
     end
 

data/lib/generators/paper_trail/install/templates/create_versions.rb.erb

@@ -11,7 +11,7 @@ class CreateVersions < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :versions<%= versions_table_options %> do |t|
       t.string   :item_type<%= item_type_options %>
-      t.bigint   :item_id,   null: false
+      t.<%= item_id_type_options %>   :item_id,   null: false
       t.string   :event,     null: false
       t.string   :whodunnit
       t.text     :object, limit: TEXT_BYTES
@@ -28,7 +28,9 @@ class CreateVersions < ActiveRecord::Migration<%= migration_version %>
       # MySQL users should also upgrade to at least rails 4.2, which is the first
       # version of ActiveRecord with support for fractional seconds in MySQL.
       # (https://github.com/rails/rails/pull/14359)
-      #
+      # 
+      # MySQL users should use the following line for `created_at`
+      # t.datetime :created_at, limit: 6                                        
       t.datetime :created_at
     end
     add_index :versions, %i(item_type item_id)

data/lib/generators/paper_trail/update_item_subtype/update_item_subtype_generator.rb

@@ -7,8 +7,10 @@ module PaperTrail
   class UpdateItemSubtypeGenerator < MigrationGenerator
     source_root File.expand_path("templates", __dir__)
 
-    desc "Generates (but does not run) a migration to update item_subtype for STI entries in an "\
-      "existing versions table."
+    desc(
+      "Generates (but does not run) a migration to update item_subtype for "\
+      "STI entries in an existing versions table."
+    )
 
     def create_migration_file
       add_paper_trail_migration("update_versions_for_item_subtype", sti_type_options: options)

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -32,6 +32,12 @@ module PaperTrail
         if defined_enums[attr] && val.is_a?(::String)
           # Because PT 4 used to save the string version of enums to `object_changes`
           val
+        elsif PaperTrail::RAILS_GTE_7_0 && val.is_a?(ActiveRecord::Type::Time::Value)
+          # Because Rails 7 time attribute throws a delegation error when you deserialize
+          # it with the factory.
+          # See ActiveRecord::Type::Time::Value crashes when loaded from YAML on rails 7.0
+          # https://github.com/rails/rails/issues/43966
+          val.instance_variable_get(:@time)
         else
           AttributeSerializerFactory.for(@klass, attr).deserialize(val)
         end

data/lib/paper_trail/compatibility.rb

@@ -8,7 +8,7 @@ module PaperTrail
   #
   # It is not safe to assume that a new version of rails will be compatible with
   # PaperTrail. PT is only compatible with the versions of rails that it is
-  # tested against. See `.travis.yml`.
+  # tested against. See `.github/workflows/test.yml`.
   #
   # However, as of
   # [#1213](https://github.com/paper-trail-gem/paper_trail/pull/1213) our
@@ -18,7 +18,7 @@ module PaperTrail
   # versions.
   module Compatibility
     ACTIVERECORD_GTE = ">= 5.2" # enforced in gemspec
-    ACTIVERECORD_LT = "< 6.2" # not enforced in gemspec
+    ACTIVERECORD_LT = "< 7.1" # not enforced in gemspec
 
     E_INCOMPATIBLE_AR = <<-EOS
       PaperTrail %s is not compatible with ActiveRecord %s. We allow PT

data/lib/paper_trail/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Generic PaperTrail exception.
+  # @api public
+  class Error < StandardError
+  end
+
+  # An unexpected option, perhaps a typo, was passed to a public API method.
+  # @api public
+  class InvalidOption < Error
+  end
+
+  # The application's database schema is not supported.
+  # @api public
+  class UnsupportedSchema < Error
+  end
+
+  # The application's database column type is not supported.
+  # @api public
+  class UnsupportedColumnType < UnsupportedSchema
+    def initialize(method:, expected:, actual:)
+      super(
+        format(
+          "%s expected %s column, got %s",
+          method,
+          expected,
+          actual
+        )
+      )
+    end
+  end
+end

data/lib/paper_trail/events/base.rb

@@ -109,19 +109,25 @@ module PaperTrail
         @changed_in_latest_version ||= changes_in_latest_version.keys
       end
 
-      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
-      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      # Memoized to reduce memory usage
       #
       # @api private
       def changes_in_latest_version
-        # Memoized to reduce memory usage
-        @changes_in_latest_version ||= begin
-          if @in_after_callback
-            @record.saved_changes
-          else
-            @record.changes
-          end
+        @changes_in_latest_version ||= load_changes_in_latest_version
+      end
+
+      # @api private
+      def evaluate_only
+        only = @record.paper_trail_options[:only].dup
+        # Remove Hash arguments and then evaluate whether the attributes (the
+        # keys of the hash) should also get pushed into the collection.
+        only.delete_if do |obj|
+          obj.is_a?(Hash) &&
+            obj.each { |attr, condition|
+              only << attr if condition.respond_to?(:call) && condition.call(@record)
+            }
         end
+        only
       end
 
       # An attributed is "ignored" if it is listed in the `:ignore` option
@@ -134,6 +140,18 @@ module PaperTrail
         ignored.any? && (changed_in_latest_version & ignored).any?
       end
 
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      #
+      # @api private
+      def load_changes_in_latest_version
+        if @in_after_callback
+          @record.saved_changes
+        else
+          @record.changes
+        end
+      end
+
       # PT 10 has a new optional column, `item_subtype`
       #
       # @api private
@@ -178,20 +196,28 @@ module PaperTrail
         if value.respond_to?(:call)
           value.call(@record)
         elsif value.is_a?(Symbol) && @record.respond_to?(value, true)
-          # If it is an attribute that is changing in an existing object,
-          # be sure to grab the current version.
-          if event != "create" &&
-              @record.has_attribute?(value) &&
-              attribute_changed_in_latest_version?(value)
-            attribute_in_previous_version(value, false)
-          else
-            @record.send(value)
-          end
+          metadatum_from_model_method(event, value)
         else
           value
         end
       end
 
+      # The model method can either be an attribute or a non-attribute method.
+      #
+      # If it is an attribute that is changing in an existing object,
+      # be sure to grab the correct version.
+      #
+      # @api private
+      def metadatum_from_model_method(event, method)
+        if event != "create" &&
+            @record.has_attribute?(method) &&
+            attribute_changed_in_latest_version?(method)
+          attribute_in_previous_version(method, false)
+        else
+          @record.send(method)
+        end
+      end
+
       # @api private
       def notable_changes
         changes_in_latest_version.delete_if { |k, _v|
@@ -203,16 +229,9 @@ module PaperTrail
       def notably_changed
         # Memoized to reduce memory usage
         @notably_changed ||= begin
-          only = @record.paper_trail_options[:only].dup
-          # Remove Hash arguments and then evaluate whether the attributes (the
-          # keys of the hash) should also get pushed into the collection.
-          only.delete_if do |obj|
-            obj.is_a?(Hash) &&
-              obj.each { |attr, condition|
-                only << attr if condition.respond_to?(:call) && condition.call(@record)
-              }
-          end
-          only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & only)
+          only = evaluate_only
+          cani = changed_and_not_ignored
+          only.empty? ? cani : (cani & only)
         end
       end
 

data/lib/paper_trail/events/update.rb

@@ -35,16 +35,35 @@ module PaperTrail
         if record_object?
           data[:object] = recordable_object(@is_touch)
         end
-        if record_object_changes?
-          changes = @force_changes.nil? ? notable_changes : @force_changes
-          data[:object_changes] = prepare_object_changes(changes)
-        end
+        merge_object_changes_into(data)
         merge_item_subtype_into(data)
         merge_metadata_into(data)
       end
 
+      # If it is a touch event, and changed are empty, it is assumed to be
+      # implicit `touch` mutation, and will a version is created.
+      #
+      # See https://github.com/rails/rails/commit/dcb825902d79d0f6baba956f7c6ec5767611353e
+      #
+      # @api private
+      def changed_notably?
+        if @is_touch && changes_in_latest_version.empty?
+          true
+        else
+          super
+        end
+      end
+
       private
 
+      # @api private
+      def merge_object_changes_into(data)
+        if record_object_changes?
+          changes = @force_changes.nil? ? notable_changes : @force_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+      end
+
       # `touch` cannot record `object_changes` because rails' `touch` does not
       # perform dirty-tracking. Specifically, methods from `Dirty`, like
       # `saved_changes`, return the same values before and after `touch`.

data/lib/paper_trail/model_config.rb

@@ -18,11 +18,6 @@ module PaperTrail
       `abstract_class`. This is fine, but all application models must be
       configured to use concrete (not abstract) version models.
     STR
-    E_MODEL_LIMIT_REQUIRES_ITEM_SUBTYPE = <<~STR.squish.freeze
-      To use PaperTrail's per-model limit in your %s model, you must have an
-      item_subtype column in your versions table. See documentation sections
-      2.e.1 Per-model limit, and 4.b.1 The optional item_subtype column.
-    STR
     DPR_PASSING_ASSOC_NAME_DIRECTLY_TO_VERSIONS_OPTION = <<~STR.squish
       Passing versions association name as `has_paper_trail versions: %{versions_name}`
       is deprecated. Use `has_paper_trail versions: {name: %{versions_name}}` instead.
@@ -45,22 +40,14 @@ module PaperTrail
       @model_class.after_create { |r|
         r.paper_trail.record_create if r.paper_trail.save_version?
       }
-      return if @model_class.paper_trail_options[:on].include?(:create)
-      @model_class.paper_trail_options[:on] << :create
+      append_option_uniquely(:on, :create)
     end
 
     # Adds a callback that records a version before or after a "destroy" event.
     #
     # @api public
     def on_destroy(recording_order = "before")
-      unless %w[after before].include?(recording_order.to_s)
-        raise ArgumentError, 'recording order can only be "after" or "before"'
-      end
-
-      if recording_order.to_s == "after" && cannot_record_after_destroy?
-        raise E_CANNOT_RECORD_AFTER_DESTROY
-      end
-
+      assert_valid_recording_order_for_on_destroy(recording_order)
       @model_class.send(
         "#{recording_order}_destroy",
         lambda do |r|
@@ -68,9 +55,7 @@ module PaperTrail
           r.paper_trail.record_destroy(recording_order)
         end
       )
-
-      return if @model_class.paper_trail_options[:on].include?(:destroy)
-      @model_class.paper_trail_options[:on] << :destroy
+      append_option_uniquely(:on, :destroy)
     end
 
     # Adds a callback that records a version after an "update" event.
@@ -92,19 +77,27 @@ module PaperTrail
       @model_class.after_update { |r|
         r.paper_trail.clear_version_instance
       }
-      return if @model_class.paper_trail_options[:on].include?(:update)
-      @model_class.paper_trail_options[:on] << :update
+      append_option_uniquely(:on, :update)
     end
 
     # Adds a callback that records a version after a "touch" event.
+    #
+    # Rails < 6.0 has a bug where dirty-tracking does not occur during
+    # a `touch`. (https://github.com/rails/rails/issues/33429) See also:
+    # https://github.com/paper-trail-gem/paper_trail/issues/1121
+    # https://github.com/paper-trail-gem/paper_trail/issues/1161
+    # https://github.com/paper-trail-gem/paper_trail/pull/1285
+    #
     # @api public
     def on_touch
       @model_class.after_touch { |r|
-        r.paper_trail.record_update(
-          force: true,
-          in_after_callback: true,
-          is_touch: true
-        )
+        if r.paper_trail.save_version?
+          r.paper_trail.record_update(
+            force: RAILS_LT_6_0,
+            in_after_callback: true,
+            is_touch: true
+          )
+        end
       }
     end
 
@@ -117,7 +110,6 @@ module PaperTrail
       @model_class.send :include, ::PaperTrail::Model::InstanceMethods
       setup_options(options)
       setup_associations(options)
-      check_presence_of_item_subtype_column(options)
       @model_class.after_rollback { paper_trail.clear_rolled_back_versions }
       setup_callbacks_from_options options[:on]
     end
@@ -129,26 +121,37 @@ module PaperTrail
 
     private
 
+    RAILS_LT_6_0 = ::ActiveRecord.gem_version < ::Gem::Version.new("6.0.0")
+    private_constant :RAILS_LT_6_0
+
+    # @api private
+    def append_option_uniquely(option, value)
+      collection = @model_class.paper_trail_options.fetch(option)
+      return if collection.include?(value)
+      collection << value
+    end
+
     # Raises an error if the provided class is an `abstract_class`.
     # @api private
     def assert_concrete_activerecord_class(class_name)
       if class_name.constantize.abstract_class?
-        raise format(E_HPT_ABSTRACT_CLASS, @model_class, class_name)
+        raise Error, format(E_HPT_ABSTRACT_CLASS, @model_class, class_name)
       end
     end
 
-    def cannot_record_after_destroy?
-      ::ActiveRecord::Base.belongs_to_required_by_default
+    # @api private
+    def assert_valid_recording_order_for_on_destroy(recording_order)
+      unless %w[after before].include?(recording_order.to_s)
+        raise ArgumentError, 'recording order can only be "after" or "before"'
+      end
+
+      if recording_order.to_s == "after" && cannot_record_after_destroy?
+        raise Error, E_CANNOT_RECORD_AFTER_DESTROY
+      end
     end
 
-    # Some options require the presence of the `item_subtype` column. Currently
-    # only `limit`, but in the future there may be others.
-    #
-    # @api private
-    def check_presence_of_item_subtype_column(options)
-      return unless options.key?(:limit)
-      return if version_class.item_subtype_column_present?
-      raise format(E_MODEL_LIMIT_REQUIRES_ITEM_SUBTYPE, @model_class.name)
+    def cannot_record_after_destroy?
+      ::ActiveRecord::Base.belongs_to_required_by_default
     end
 
     def check_version_class_name(options)
@@ -206,6 +209,14 @@ module PaperTrail
       options
     end
 
+    # Process an `ignore`, `skip`, or `only` option.
+    def event_attribute_option(option_name)
+      [@model_class.paper_trail_options[option_name]].
+        flatten.
+        compact.
+        map { |attr| attr.is_a?(Hash) ? attr.stringify_keys : attr.to_s }
+    end
+
     def get_versions_scope(options)
       options[:versions][:scope] || -> { order(model.timestamp_sort_order) }
     end
@@ -240,12 +251,8 @@ module PaperTrail
       @model_class.paper_trail_options = options.dup
 
       %i[ignore skip only].each do |k|
-        @model_class.paper_trail_options[k] = [@model_class.paper_trail_options[k]].
-          flatten.
-          compact.
-          map { |attr| attr.is_a?(Hash) ? attr.stringify_keys : attr.to_s }
+        @model_class.paper_trail_options[k] = event_attribute_option(k)
       end
-
       @model_class.paper_trail_options[:meta] ||= {}
     end
   end

data/lib/paper_trail/queries/versions/where_attribute_changes.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Queries
+    module Versions
+      # For public API documentation, see `where_attribute_changes` in
+      # `paper_trail/version_concern.rb`.
+      # @api private
+      class WhereAttributeChanges
+        # - version_model_class - The class that VersionConcern was mixed into.
+        # - attribute - An attribute that changed. See the public API
+        #   documentation for details.
+        # @api private
+        def initialize(version_model_class, attribute)
+          @version_model_class = version_model_class
+          @attribute = attribute
+        end
+
+        # @api private
+        def execute
+          if PaperTrail.config.object_changes_adapter.respond_to?(:where_attribute_changes)
+            return PaperTrail.config.object_changes_adapter.where_attribute_changes(
+              @version_model_class, @attribute
+            )
+          end
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
+          when :jsonb, :json
+            json
+          else
+            raise UnsupportedColumnType.new(
+              method: "where_attribute_changes",
+              expected: "json or jsonb",
+              actual: column_type
+            )
+          end
+        end
+
+        private
+
+        # @api private
+        def json
+          sql = "object_changes -> ? IS NOT NULL"
+
+          @version_model_class.where(sql, @attribute)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/queries/versions/where_object.rb

@@ -19,7 +19,7 @@ module PaperTrail
         # @api private
         def execute
           column = @version_model_class.columns_hash["object"]
-          raise "where_object can't be called without an object column" unless column
+          raise Error, "where_object requires an object column" unless column
 
           case column.type
           when :jsonb

data/lib/paper_trail/queries/versions/where_object_changes.rb

@@ -28,13 +28,18 @@ module PaperTrail
               @version_model_class, @attributes
             )
           end
-          case @version_model_class.columns_hash["object_changes"].type
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
           when :jsonb
             jsonb
           when :json
             json
           else
-            text
+            raise UnsupportedColumnType.new(
+              method: "where_object_changes",
+              expected: "json or jsonb",
+              actual: column_type
+            )
           end
         end
 
@@ -59,16 +64,6 @@ module PaperTrail
           @attributes.each { |field, value| @attributes[field] = [value] }
           @version_model_class.where("object_changes @> ?", @attributes.to_json)
         end
-
-        # @api private
-        def text
-          arel_field = @version_model_class.arel_table[:object_changes]
-          where_conditions = @attributes.map { |field, value|
-            ::PaperTrail.serializer.where_object_changes_condition(arel_field, field, value)
-          }
-          where_conditions = where_conditions.reduce { |a, e| a.and(e) }
-          @version_model_class.where(where_conditions)
-        end
       end
     end
   end

data/lib/paper_trail/queries/versions/where_object_changes_from.rb

@@ -23,12 +23,16 @@ module PaperTrail
               @version_model_class, @attributes
             )
           end
-
-          case @version_model_class.columns_hash["object_changes"].type
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
           when :jsonb, :json
             json
           else
-            text
+            raise UnsupportedColumnType.new(
+              method: "where_object_changes_from",
+              expected: "json or jsonb",
+              actual: column_type
+            )
           end
         end
 
@@ -47,18 +51,6 @@ module PaperTrail
           sql = predicates.join(" and ")
           @version_model_class.where(sql, *values)
         end
-
-        # @api private
-        def text
-          arel_field = @version_model_class.arel_table[:object_changes]
-
-          where_conditions = @attributes.map do |field, value|
-            ::PaperTrail.serializer.where_object_changes_from_condition(arel_field, field, value)
-          end
-
-          where_conditions = where_conditions.reduce { |a, e| a.and(e) }
-          @version_model_class.where(where_conditions)
-        end
       end
     end
   end

data/lib/paper_trail/queries/versions/where_object_changes_to.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Queries
+    module Versions
+      # For public API documentation, see `where_object_changes_to` in
+      # `paper_trail/version_concern.rb`.
+      # @api private
+      class WhereObjectChangesTo
+        # - version_model_class - The class that VersionConcern was mixed into.
+        # - attributes - A `Hash` of attributes and values. See the public API
+        #   documentation for details.
+        # @api private
+        def initialize(version_model_class, attributes)
+          @version_model_class = version_model_class
+          @attributes = attributes
+        end
+
+        # @api private
+        def execute
+          if PaperTrail.config.object_changes_adapter.respond_to?(:where_object_changes_to)
+            return PaperTrail.config.object_changes_adapter.where_object_changes_to(
+              @version_model_class, @attributes
+            )
+          end
+          column_type = @version_model_class.columns_hash["object_changes"].type
+          case column_type
+          when :jsonb, :json
+            json
+          else
+            raise UnsupportedColumnType.new(
+              method: "where_object_changes_to",
+              expected: "json or jsonb",
+              actual: column_type
+            )
+          end
+        end
+
+        private
+
+        # @api private
+        def json
+          predicates = []
+          values = []
+          @attributes.each do |field, value|
+            predicates.push(
+              "(object_changes->>? ILIKE ?)"
+            )
+            values.concat([field, "[%#{value.to_json}]"])
+          end
+          sql = predicates.join(" and ")
+          @version_model_class.where(sql, *values)
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/record_trail.rb

@@ -194,15 +194,17 @@ module PaperTrail
     # Save, and create a version record regardless of options such as `:on`,
     # `:if`, or `:unless`.
     #
-    # Arguments are passed to `save`.
+    # `in_after_callback`: Indicates if this method is being called within an
+    #                      `after` callback. Defaults to `false`.
+    # `options`: Optional arguments passed to `save`.
     #
     # This is an "update" event. That is, we record the same data we would in
     # the case of a normal AR `update`.
-    def save_with_version(**options)
+    def save_with_version(in_after_callback: false, **options)
       ::PaperTrail.request(enabled: false) do
         @record.save(**options)
       end
-      record_update(force: true, in_after_callback: false, is_touch: false)
+      record_update(force: true, in_after_callback: in_after_callback, is_touch: false)
     end
 
     # Like the `update_column` method from `ActiveRecord::Persistence`, but also
@@ -283,7 +285,7 @@ module PaperTrail
     def log_version_errors(version, action)
       version.logger&.warn(
         "Unable to create version for #{action} of #{@record.class.name}" \
-          "##{@record.id}: " + version.errors.full_messages.join(", ")
+        "##{@record.id}: " + version.errors.full_messages.join(", ")
       )
     end
 

data/lib/paper_trail/reifier.rb

@@ -60,9 +60,7 @@ module PaperTrail
         model = if options[:dup] == true || version.event == "destroy"
                   klass.new
                 else
-                  find_cond = { klass.primary_key => version.item_id }
-
-                  version.item || klass.unscoped.where(find_cond).first || klass.new
+                  version.item || init_model_by_finding_item_id(klass, version) || klass.new
                 end
 
         if options[:unversioned_attributes] == :nil && !model.new_record?
@@ -72,6 +70,11 @@ module PaperTrail
         model
       end
 
+      # @api private
+      def init_model_by_finding_item_id(klass, version)
+        klass.unscoped.where(klass.primary_key => version.item_id).first
+      end
+
       # Look for attributes that exist in `model` and not in this version.
       # These attributes should be set to nil. Modifies `attrs`.
       # @api private
@@ -109,21 +112,35 @@ module PaperTrail
       end
 
       # Given a `version`, return the class to reify. This method supports
-      # Single Table Inheritance (STI) with custom inheritance columns.
+      # Single Table Inheritance (STI) with custom inheritance columns and
+      # custom inheritance column values.
       #
       # For example, imagine a `version` whose `item_type` is "Animal". The
       # `animals` table is an STI table (it has cats and dogs) and it has a
       # custom inheritance column, `species`. If `attrs["species"]` is "Dog",
       # this method returns the constant `Dog`. If `attrs["species"]` is blank,
-      # this method returns the constant `Animal`. You can see this particular
-      # example in action in `spec/models/animal_spec.rb`.
+      # this method returns the constant `Animal`.
       #
-      # TODO: Duplication: similar `constantize` in VersionConcern#version_limit
+      # The values contained in the inheritance columns may be non-camelized
+      # strings (e.g. 'dog' instead of 'Dog'). To reify classes in this case
+      # we need to call the parents class `sti_class_for` method to retrieve
+      # the correct record class.
+      #
+      # You can see these particular examples in action in
+      # `spec/models/animal_spec.rb` and `spec/models/plant_spec.rb`
       def version_reification_class(version, attrs)
-        inheritance_column_name = version.item_type.constantize.inheritance_column
+        clazz = version.item_type.constantize
+        inheritance_column_name = clazz.inheritance_column
         inher_col_value = attrs[inheritance_column_name]
-        class_name = inher_col_value.blank? ? version.item_type : inher_col_value
-        class_name.constantize
+        return clazz if inher_col_value.blank?
+
+        # Rails 6.1 adds a public method for clients to use to customize STI classes. If that
+        # method is not available, fall back to using the private one
+        if clazz.public_methods.include?(:sti_class_for)
+          return clazz.sti_class_for(inher_col_value)
+        end
+
+        clazz.send(:find_sti_class, inher_col_value)
       end
     end
   end

data/lib/paper_trail/request.rb

@@ -12,9 +12,6 @@ module PaperTrail
   #
   # @api private
   module Request
-    class InvalidOption < RuntimeError
-    end
-
     class << self
       # Sets any data from the controller that you want PaperTrail to store.
       # See also `PaperTrail::Rails::Controller#info_for_paper_trail`.

data/lib/paper_trail/serializers/json.rb

@@ -31,24 +31,6 @@ module PaperTrail
           arel_field.matches("%\"#{field}\":#{json_value}%")
         end
       end
-
-      def where_object_changes_condition(*)
-        raise <<-STR.squish.freeze
-          where_object_changes no longer supports reading JSON from a text
-          column. The old implementation was inaccurate, returning more records
-          than you wanted. This feature was deprecated in 7.1.0 and removed in
-          8.0.0. The json and jsonb datatypes are still supported. See the
-          discussion at https://github.com/paper-trail-gem/paper_trail/issues/803
-        STR
-      end
-
-      # Raises an exception as this operation is not allowed from text columns.
-      def where_object_changes_from_condition(*)
-        raise <<-STR.squish.freeze
-          where_object_changes_from does not support reading JSON from a text
-          column. The json and jsonb datatypes are supported.
-        STR
-      end
     end
   end
 end

data/lib/paper_trail/serializers/yaml.rb

@@ -9,7 +9,7 @@ module PaperTrail
       extend self # makes all instance methods become module methods as well
 
       def load(string)
-        ::YAML.load string
+        ::YAML.respond_to?(:unsafe_load) ? ::YAML.unsafe_load(string) : ::YAML.load(string)
       end
 
       # @param object (Hash | HashWithIndifferentAccess) - Coming from
@@ -26,26 +26,6 @@ module PaperTrail
       def where_object_condition(arel_field, field, value)
         arel_field.matches("%\n#{field}: #{value}\n%")
       end
-
-      # Returns a SQL LIKE condition to be used to match the given field and
-      # value in the serialized `object_changes`.
-      def where_object_changes_condition(*)
-        raise <<-STR.squish.freeze
-          where_object_changes no longer supports reading YAML from a text
-          column. The old implementation was inaccurate, returning more records
-          than you wanted. This feature was deprecated in 8.1.0 and removed in
-          9.0.0. The json and jsonb datatypes are still supported. See
-          discussion at https://github.com/paper-trail-gem/paper_trail/pull/997
-        STR
-      end
-
-      # Raises an exception as this operation is not allowed with YAML.
-      def where_object_changes_from_condition(*)
-        raise <<-STR.squish.freeze
-          where_object_changes_from does not support reading YAML from a text
-          column. The json and jsonb datatypes are supported.
-        STR
-      end
     end
   end
 end

data/lib/paper_trail/version_concern.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 require "paper_trail/attribute_serializers/object_changes_attribute"
+require "paper_trail/queries/versions/where_attribute_changes"
 require "paper_trail/queries/versions/where_object"
 require "paper_trail/queries/versions/where_object_changes"
 require "paper_trail/queries/versions/where_object_changes_from"
+require "paper_trail/queries/versions/where_object_changes_to"
 
 module PaperTrail
   # Originally, PaperTrail did not provide this module, and all of this
@@ -14,17 +16,13 @@ module PaperTrail
     extend ::ActiveSupport::Concern
 
     included do
-      belongs_to :item, polymorphic: true, optional: true
+      belongs_to :item, polymorphic: true, optional: true, inverse_of: false
       validates_presence_of :event
       after_create :enforce_version_limit!
     end
 
     # :nodoc:
     module ClassMethods
-      def item_subtype_column_present?
-        column_names.include?("item_subtype")
-      end
-
       def with_item_keys(item_type, item_id)
         where item_type: item_type, item_id: item_id
       end
@@ -42,7 +40,7 @@ module PaperTrail
       end
 
       def not_creates
-        where "event <> ?", "create"
+        where.not(event: "create")
       end
 
       def between(start_time, end_time)
@@ -60,6 +58,18 @@ module PaperTrail
         end
       end
 
+      # Given an attribute like `"name"`, query the `versions.object_changes`
+      # column for any changes that modified the provided attribute.
+      #
+      # @api public
+      def where_attribute_changes(attribute)
+        unless attribute.is_a?(String) || attribute.is_a?(Symbol)
+          raise ArgumentError, "expected to receive a String or Symbol"
+        end
+
+        Queries::Versions::WhereAttributeChanges.new(self, attribute).execute
+      end
+
       # Given a hash of attributes like `name: 'Joan'`, query the
       # `versions.objects` column.
       #
@@ -131,6 +141,21 @@ module PaperTrail
         Queries::Versions::WhereObjectChangesFrom.new(self, args).execute
       end
 
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column for changes where the version changed
+      # to the hash of attributes from other values.
+      #
+      # This is useful for finding versions where the attribute started with an
+      # unknown value and changed to a known value. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_to(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChangesTo.new(self, args).execute
+      end
+
       def primary_key_is_int?
         @primary_key_is_int ||= columns_hash[primary_key].type == :integer
       rescue StandardError # TODO: Rescue something more specific
@@ -237,7 +262,7 @@ module PaperTrail
     #
     def reify(options = {})
       unless self.class.column_names.include? "object"
-        raise "reify can't be called without an object column"
+        raise Error, "reify requires an object column"
       end
       return nil if object.nil?
       ::PaperTrail::Reifier.reify(self, options)
@@ -350,16 +375,23 @@ module PaperTrail
     # The version limit can be global or per-model.
     #
     # @api private
-    #
-    # TODO: Duplication: similar `constantize` in Reifier#version_reification_class
     def version_limit
-      if self.class.item_subtype_column_present?
-        klass = (item_subtype || item_type).constantize
-        if klass&.paper_trail_options&.key?(:limit)
-          return klass.paper_trail_options[:limit]
-        end
+      klass = item.class
+      if limit_option?(klass)
+        klass.paper_trail_options[:limit]
+      elsif base_class_limit_option?(klass)
+        klass.base_class.paper_trail_options[:limit]
+      else
+        PaperTrail.config.version_limit
       end
-      PaperTrail.config.version_limit
+    end
+
+    def limit_option?(klass)
+      klass.respond_to?(:paper_trail_options) && klass.paper_trail_options.key?(:limit)
+    end
+
+    def base_class_limit_option?(klass)
+      klass.respond_to?(:base_class) && limit_option?(klass.base_class)
     end
   end
 end

data/lib/paper_trail/version_number.rb

@@ -8,7 +8,7 @@ module PaperTrail
   # People are encouraged to use `PaperTrail.gem_version` instead.
   module VERSION
     MAJOR = 12
-    MINOR = 0
+    MINOR = 3
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

data/lib/paper_trail.rb

@@ -8,6 +8,7 @@
 # can revisit this decision.
 require "active_support/all"
 
+require "paper_trail/errors"
 require "paper_trail/cleaner"
 require "paper_trail/compatibility"
 require "paper_trail/config"
@@ -25,6 +26,8 @@ module PaperTrail
     named created_at.
   EOS
 
+  RAILS_GTE_7_0 = ::ActiveRecord.gem_version >= ::Gem::Version.new("7.0.0")
+
   extend PaperTrail::Cleaner
 
   class << self
@@ -68,7 +71,7 @@ module PaperTrail
     #
     # @api public
     def request(options = nil, &block)
-      if options.nil? && !block_given?
+      if options.nil? && !block
         Request
       else
         Request.with(options, &block)
@@ -78,7 +81,7 @@ module PaperTrail
     # Set the field which records when a version was created.
     # @api public
     def timestamp_field=(_field_name)
-      raise(E_TIMESTAMP_FIELD_CONFIG)
+      raise Error, E_TIMESTAMP_FIELD_CONFIG
     end
 
     # Set the PaperTrail serializer. This setting affects all threads.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail
 version: !ruby/object:Gem::Version
-  version: 12.0.0
+  version: 12.3.0
 platform: ruby
 authors:
 - Andy Stewart
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-29 00:00:00.000000000 Z
+date: 2022-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -46,42 +46,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.4.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.4.1
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '11.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '11.1'
 - !ruby/object:Gem::Dependency
   name: ffaker
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.11'
+        version: '2.20'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.11'
+        version: '2.20'
 - !ruby/object:Gem::Dependency
   name: generator_spec
   requirement: !ruby/object:Gem::Requirement
@@ -102,14 +102,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.14
+        version: 1.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.14
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -144,118 +144,140 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.0.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.0.2
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.11.0
+        version: 1.22.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.11.0
+        version: 1.22.2
 - !ruby/object:Gem::Dependency
-  name: rubocop-rails
+  name: rubocop-packaging
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.9.1
+        version: 0.5.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.9.1
+        version: 0.5.1
 - !ruby/object:Gem::Dependency
-  name: rubocop-packaging
+  name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: 1.11.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: 1.11.5
 - !ruby/object:Gem::Dependency
-  name: rubocop-performance
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.12.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.12.4
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.10.1
+        version: 0.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.10.1
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: 2.5.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
 - !ruby/object:Gem::Dependency
   name: mysql2
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.5.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.5.3
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.18'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.18'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -297,6 +319,7 @@ files:
 - lib/paper_trail/cleaner.rb
 - lib/paper_trail/compatibility.rb
 - lib/paper_trail/config.rb
+- lib/paper_trail/errors.rb
 - lib/paper_trail/events/base.rb
 - lib/paper_trail/events/create.rb
 - lib/paper_trail/events/destroy.rb
@@ -311,9 +334,11 @@ files:
 - lib/paper_trail/frameworks/rspec/helpers.rb
 - lib/paper_trail/has_paper_trail.rb
 - lib/paper_trail/model_config.rb
+- lib/paper_trail/queries/versions/where_attribute_changes.rb
 - lib/paper_trail/queries/versions/where_object.rb
 - lib/paper_trail/queries/versions/where_object_changes.rb
 - lib/paper_trail/queries/versions/where_object_changes_from.rb
+- lib/paper_trail/queries/versions/where_object_changes_to.rb
 - lib/paper_trail/record_history.rb
 - lib/paper_trail/record_trail.rb
 - lib/paper_trail/reifier.rb
@@ -335,15 +360,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
+rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
 summary: Track changes to your models.