paper_trail 9.2.0 → 12.1.0

data/lib/paper_trail/reifier.rb

@@ -52,26 +52,29 @@ module PaperTrail
       # not the actual subclass. If `type` is present but empty, the class is
       # the base class.
       def init_model(attrs, options, version)
-        if options[:dup] != true && version.item
-          model = version.item
-          if options[:unversioned_attributes] == :nil
-            init_unversioned_attrs(attrs, model)
-          end
-        else
-          klass = version_reification_class(version, attrs)
-          # The `dup` option always returns a new object, otherwise we should
-          # attempt to look for the item outside of default scope(s).
-          find_cond = { klass.primary_key => version.item_id }
-          if options[:dup] || (item_found = klass.unscoped.where(find_cond).first).nil?
-            model = klass.new
-          elsif options[:unversioned_attributes] == :nil
-            model = item_found
-            init_unversioned_attrs(attrs, model)
-          end
+        klass = version_reification_class(version, attrs)
+
+        # The `dup` option and destroyed version always returns a new object,
+        # otherwise we should attempt to load item or to look for the item
+        # outside of default scope(s).
+        model = if options[:dup] == true || version.event == "destroy"
+                  klass.new
+                else
+                  version.item || init_model_by_finding_item_id(klass, version) || klass.new
+                end
+
+        if options[:unversioned_attributes] == :nil && !model.new_record?
+          init_unversioned_attrs(attrs, model)
         end
+
         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
@@ -88,9 +91,7 @@ module PaperTrail
       #
       # @api private
       def reify_attribute(k, v, model, version)
-        enums = model.class.respond_to?(:defined_enums) ? model.class.defined_enums : {}
-        is_enum_without_type_caster = ::ActiveRecord::VERSION::MAJOR < 5 && enums.key?(k)
-        if model.has_attribute?(k) && !is_enum_without_type_caster
+        if model.has_attribute?(k)
           model[k.to_sym] = v
         elsif model.respond_to?("#{k}=")
           model.send("#{k}=", v)
@@ -111,20 +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`.
+      #
+      # 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,16 +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
     end
   end
 end

data/lib/paper_trail/serializers/yaml.rb

@@ -12,7 +12,12 @@ module PaperTrail
         ::YAML.load string
       end
 
+      # @param object (Hash | HashWithIndifferentAccess) - Coming from
+      # `recordable_object` `object` will be a plain `Hash`. However, due to
+      # recent [memory optimizations](https://git.io/fjeYv), when coming from
+      # `recordable_object_changes`, it will be a `HashWithIndifferentAccess`.
       def dump(object)
+        object = object.to_hash if object.is_a?(HashWithIndifferentAccess)
         ::YAML.dump object
       end
 
@@ -21,18 +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
     end
   end
 end

data/lib/paper_trail/type_serializers/postgres_array_serializer.rb

@@ -11,15 +11,12 @@ module PaperTrail
       end
 
       def serialize(array)
-        return serialize_with_ar(array) if active_record_pre_502?
         array
       end
 
       def deserialize(array)
-        return deserialize_with_ar(array) if active_record_pre_502?
-
         case array
-        # Needed for legacy reasons. If serialized array is a string
+        # Needed for legacy data. If serialized array is a string
         # then it was serialized with Rails < 5.0.2.
         when ::String then deserialize_with_ar(array)
         else array
@@ -28,17 +25,6 @@ module PaperTrail
 
       private
 
-      def active_record_pre_502?
-        ::ActiveRecord::VERSION::MAJOR < 5 ||
-          (::ActiveRecord::VERSION::MINOR.zero? && ::ActiveRecord::VERSION::TINY < 2)
-      end
-
-      def serialize_with_ar(array)
-        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
-          new(@subtype, @delimiter).
-          serialize(array)
-      end
-
       def deserialize_with_ar(array)
         ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
           new(@subtype, @delimiter).

data/lib/paper_trail/version_concern.rb

@@ -1,8 +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
@@ -13,12 +16,7 @@ module PaperTrail
     extend ::ActiveSupport::Concern
 
     included do
-      if ::ActiveRecord.gem_version >= Gem::Version.new("5.0")
-        belongs_to :item, polymorphic: true, optional: true
-      else
-        belongs_to :item, polymorphic: true
-      end
-
+      belongs_to :item, polymorphic: true, optional: true
       validates_presence_of :event
       after_create :enforce_version_limit!
     end
@@ -42,40 +40,7 @@ module PaperTrail
       end
 
       def not_creates
-        where "event <> ?", "create"
-      end
-
-      # Returns versions after `obj`.
-      #
-      # @param obj - a `Version` or a timestamp
-      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
-      #   Default: false.
-      # @return `ActiveRecord::Relation`
-      # @api public
-      def subsequent(obj, timestamp_arg = false)
-        if timestamp_arg != true && primary_key_is_int?
-          return where(arel_table[primary_key].gt(obj.id)).order(arel_table[primary_key].asc)
-        end
-
-        obj = obj.send(:created_at) if obj.is_a?(self)
-        where(arel_table[:created_at].gt(obj)).order(timestamp_sort_order)
-      end
-
-      # Returns versions before `obj`.
-      #
-      # @param obj - a `Version` or a timestamp
-      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
-      #   Default: false.
-      # @return `ActiveRecord::Relation`
-      # @api public
-      def preceding(obj, timestamp_arg = false)
-        if timestamp_arg != true && primary_key_is_int?
-          return where(arel_table[primary_key].lt(obj.id)).order(arel_table[primary_key].desc)
-        end
-
-        obj = obj.send(:created_at) if obj.is_a?(self)
-        where(arel_table[:created_at].lt(obj)).
-          order(timestamp_sort_order("desc"))
+        where.not(event: "create")
       end
 
       def between(start_time, end_time)
@@ -93,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.
       #
@@ -149,6 +126,36 @@ module PaperTrail
         Queries::Versions::WhereObjectChanges.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
+      # from the hash of attributes to other values.
+      #
+      # This is useful for finding versions where the attribute started with a
+      # known value and changed to something else. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_from(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        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
@@ -166,6 +173,65 @@ module PaperTrail
       def object_changes_col_is_json?
         %i[json jsonb].include?(columns_hash["object_changes"].try(:type))
       end
+
+      # Returns versions before `obj`.
+      #
+      # @param obj - a `Version` or a timestamp
+      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
+      #   Default: false.
+      # @return `ActiveRecord::Relation`
+      # @api public
+      # rubocop:disable Style/OptionalBooleanParameter
+      def preceding(obj, timestamp_arg = false)
+        if timestamp_arg != true && primary_key_is_int?
+          preceding_by_id(obj)
+        else
+          preceding_by_timestamp(obj)
+        end
+      end
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      # Returns versions after `obj`.
+      #
+      # @param obj - a `Version` or a timestamp
+      # @param timestamp_arg - boolean - When true, `obj` is a timestamp.
+      #   Default: false.
+      # @return `ActiveRecord::Relation`
+      # @api public
+      # rubocop:disable Style/OptionalBooleanParameter
+      def subsequent(obj, timestamp_arg = false)
+        if timestamp_arg != true && primary_key_is_int?
+          subsequent_by_id(obj)
+        else
+          subsequent_by_timestamp(obj)
+        end
+      end
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      private
+
+      # @api private
+      def preceding_by_id(obj)
+        where(arel_table[primary_key].lt(obj.id)).order(arel_table[primary_key].desc)
+      end
+
+      # @api private
+      def preceding_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(arel_table[:created_at].lt(obj)).
+          order(timestamp_sort_order("desc"))
+      end
+
+      # @api private
+      def subsequent_by_id(version)
+        where(arel_table[primary_key].gt(version.id)).order(arel_table[primary_key].asc)
+      end
+
+      # @api private
+      def subsequent_by_timestamp(obj)
+        obj = obj.send(:created_at) if obj.is_a?(self)
+        where(arel_table[:created_at].gt(obj)).order(timestamp_sort_order)
+      end
     end
 
     # @api private
@@ -179,18 +245,8 @@ module PaperTrail
 
     # Restore the item from this version.
     #
-    # Optionally this can also restore all :has_one and :has_many (including
-    # has_many :through) associations as they were "at the time", if they are
-    # also being versioned by PaperTrail.
-    #
     # Options:
     #
-    # - :has_one
-    #   - `true` - Also reify has_one associations.
-    #   - `false - Default.
-    # - :has_many
-    #   - `true` - Also reify has_many and has_many :through associations.
-    #   - `false` - Default.
     # - :mark_for_destruction
     #   - `true` - Mark the has_one/has_many associations that did not exist in
     #     the reified version for destruction, instead of removing them.
@@ -205,6 +261,9 @@ module PaperTrail
     #   - `:preserve` - Attributes undefined in version record are not modified.
     #
     def reify(options = {})
+      unless self.class.column_names.include? "object"
+        raise Error, "reify requires an object column"
+      end
       return nil if object.nil?
       ::PaperTrail::Reifier.reify(self, options)
     end
@@ -229,13 +288,6 @@ module PaperTrail
     end
     alias version_author terminator
 
-    def sibling_versions(reload = false)
-      if reload || !defined?(@sibling_versions) || @sibling_versions.nil?
-        @sibling_versions = self.class.with_item_keys(item_type, item_id)
-      end
-      @sibling_versions
-    end
-
     def next
       @next ||= sibling_versions.subsequent(self).first
     end
@@ -245,8 +297,9 @@ module PaperTrail
     end
 
     # Returns an integer representing the chronological position of the
-    # version among its siblings (see `sibling_versions`). The "create" event,
-    # for example, has an index of 0.
+    # version among its siblings. The "create" event, for example, has an index
+    # of 0.
+    #
     # @api public
     def index
       @index ||= RecordHistory.new(sibling_versions, self.class).index(self)
@@ -256,7 +309,7 @@ module PaperTrail
 
     # @api private
     def load_changeset
-      if PaperTrail.config.object_changes_adapter
+      if PaperTrail.config.object_changes_adapter.respond_to?(:load_changeset)
         return PaperTrail.config.object_changes_adapter.load_changeset(self)
       end
 
@@ -304,7 +357,7 @@ module PaperTrail
     # Enforces the `version_limit`, if set. Default: no limit.
     # @api private
     def enforce_version_limit!
-      limit = PaperTrail.config.version_limit
+      limit = version_limit
       return unless limit.is_a? Numeric
       previous_versions = sibling_versions.not_creates.
         order(self.class.timestamp_sort_order("asc"))
@@ -312,5 +365,32 @@ module PaperTrail
       excess_versions = previous_versions - previous_versions.last(limit)
       excess_versions.map(&:destroy)
     end
+
+    # @api private
+    def sibling_versions
+      @sibling_versions ||= self.class.with_item_keys(item_type, item_id)
+    end
+
+    # See docs section 2.e. Limiting the Number of Versions Created.
+    # The version limit can be global or per-model.
+    #
+    # @api private
+    def version_limit
+      if limit_option?(item.class)
+        item.class.paper_trail_options[:limit]
+      elsif base_class_limit_option?(item.class)
+        item.class.base_class.paper_trail_options[:limit]
+      else
+        PaperTrail.config.version_limit
+      end
+    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

@@ -7,8 +7,8 @@ module PaperTrail
   # because of this confusion, but it's not worth the breaking change.
   # People are encouraged to use `PaperTrail.gem_version` instead.
   module VERSION
-    MAJOR = 9
-    MINOR = 2
+    MAJOR = 12
+    MINOR = 1
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

data/lib/paper_trail.rb

@@ -8,33 +8,18 @@
 # can revisit this decision.
 require "active_support/all"
 
-# AR is required for, eg. has_paper_trail.rb, so we could put this `require` in
-# all of those files, but it seems easier to troubleshoot if we just make sure
-# AR is loaded here before loading *any* of PT. See discussion of
-# performance/simplicity tradeoff for activesupport above.
-require "active_record"
-
-require "request_store"
+require "paper_trail/errors"
 require "paper_trail/cleaner"
+require "paper_trail/compatibility"
 require "paper_trail/config"
-require "paper_trail/has_paper_trail"
 require "paper_trail/record_history"
-require "paper_trail/reifier"
 require "paper_trail/request"
-require "paper_trail/version_concern"
 require "paper_trail/version_number"
 require "paper_trail/serializers/json"
-require "paper_trail/serializers/yaml"
 
 # An ActiveRecord extension that tracks changes to your models, for auditing or
 # versioning.
 module PaperTrail
-  E_RAILS_NOT_LOADED = <<-EOS.squish.freeze
-    PaperTrail has been loaded too early, before rails is loaded. This can
-    happen when another gem defines the ::Rails namespace, then PT is loaded,
-    all before rails is loaded. You may want to reorder your Gemfile, or defer
-    the loading of PT by using `require: false` and a manual require elsewhere.
-  EOS
   E_TIMESTAMP_FIELD_CONFIG = <<-EOS.squish.freeze
     PaperTrail.timestamp_field= has been removed, without replacement. It is no
     longer configurable. The timestamp column in the versions table must now be
@@ -57,46 +42,6 @@ module PaperTrail
       !!PaperTrail.config.enabled
     end
 
-    # @deprecated
-    def enabled_for_controller=(value)
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.enabled_for_controller= is deprecated, " \
-        "use PaperTrail.request.enabled=",
-        caller(1)
-      )
-      request.enabled = value
-    end
-
-    # @deprecated
-    def enabled_for_controller?
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.enabled_for_controller? is deprecated, " \
-        "use PaperTrail.request.enabled?",
-        caller(1)
-      )
-      request.enabled?
-    end
-
-    # @deprecated
-    def enabled_for_model(model, value)
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.enabled_for_model is deprecated, " \
-        "use PaperTrail.request.enabled_for_model",
-        caller(1)
-      )
-      request.enabled_for_model(model, value)
-    end
-
-    # @deprecated
-    def enabled_for_model?(model)
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.enabled_for_model? is deprecated, " \
-        "use PaperTrail.request.enabled_for_model?",
-        caller(1)
-      )
-      request.enabled_for_model?(model)
-    end
-
     # Returns PaperTrail's `::Gem::Version`, convenient for comparisons. This is
     # recommended over `::PaperTrail::VERSION::STRING`.
     #
@@ -124,7 +69,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)
@@ -134,54 +79,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)
-    end
-
-    # @deprecated
-    def whodunnit=(value)
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.whodunnit= is deprecated, use PaperTrail.request.whodunnit=",
-        caller(1)
-      )
-      request.whodunnit = value
-    end
-
-    # @deprecated
-    def whodunnit(value = nil, &block)
-      if value.nil?
-        ::ActiveSupport::Deprecation.warn(
-          "PaperTrail.whodunnit is deprecated, use PaperTrail.request.whodunnit",
-          caller(1)
-        )
-        request.whodunnit
-      elsif block_given?
-        ::ActiveSupport::Deprecation.warn(
-          "Passing a block to PaperTrail.whodunnit is deprecated, " \
-          'use PaperTrail.request(whodunnit: "John") do .. end',
-          caller(1)
-        )
-        request(whodunnit: value, &block)
-      else
-        raise ArgumentError, "Invalid arguments"
-      end
-    end
-
-    # @deprecated
-    def controller_info=(value)
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.controller_info= is deprecated, use PaperTrail.request.controller_info=",
-        caller(1)
-      )
-      request.controller_info = value
-    end
-
-    # @deprecated
-    def controller_info
-      ::ActiveSupport::Deprecation.warn(
-        "PaperTrail.controller_info is deprecated, use PaperTrail.request.controller_info",
-        caller(1)
-      )
-      request.controller_info
+      raise Error, E_TIMESTAMP_FIELD_CONFIG
     end
 
     # Set the PaperTrail serializer. This setting affects all threads.
@@ -212,23 +110,18 @@ module PaperTrail
   end
 end
 
-ActiveSupport.on_load(:active_record) do
-  include PaperTrail::Model
-end
-
-# Require frameworks
-if defined?(::Rails)
-  # Rails module is sometimes defined by gems like rails-html-sanitizer
-  # so we check for presence of Rails.application.
-  if defined?(::Rails.application)
-    require "paper_trail/frameworks/rails"
-  else
-    ::Kernel.warn(::PaperTrail::E_RAILS_NOT_LOADED)
-  end
+# PT is built on ActiveRecord, but does not require Rails. If Rails is defined,
+# our Railtie makes sure not to load the AR-dependent parts of PT until AR is
+# ready. A typical Rails `application.rb` has:
+#
+# ```
+# require 'rails/all' # Defines `Rails`
+# Bundler.require(*Rails.groups) # require 'paper_trail' (this file)
+# ```
+#
+# Non-rails applications should take similar care to load AR before PT.
+if defined?(Rails)
+  require "paper_trail/frameworks/rails"
 else
   require "paper_trail/frameworks/active_record"
 end
-
-# https://github.com/paper-trail-gem/paper_trail/issues/1070
-# https://github.com/westonganger/paper_trail-association_tracking/issues/2
-require "paper_trail-association_tracking"