paper_trail 3.0.6 → 4.2.0

data/lib/paper_trail/record_history.rb

@@ -0,0 +1,59 @@
+module PaperTrail
+
+  # Represents the history of a single record.
+  # @api private
+  class RecordHistory
+
+    # @param versions - ActiveRecord::Relation - All versions of the record.
+    # @param version_class - Class - Usually PaperTrail::Version,
+    #   but it could also be a custom version class.
+    # @api private
+    def initialize(versions, version_class)
+      @versions = versions
+      @version_class = version_class
+    end
+
+    # Returns ordinal position of `version` in `sequence`.
+    # @api private
+    def index(version)
+      sequence.index(version)
+    end
+
+    private
+
+    # Returns `@versions` in chronological order.
+    # @api private
+    def sequence
+      if @version_class.primary_key_is_int?
+        @versions.select(primary_key).order(primary_key.asc)
+      else
+        @versions.
+          select([timestamp, primary_key]).
+          order(@version_class.timestamp_sort_order)
+      end
+    end
+
+    # @return - Arel::Attribute - Attribute representing the primary key
+    #   of the version table. The column's data type is usually a serial
+    #   integer (the rails convention) but not always.
+    # @api private
+    def primary_key
+      table[@version_class.primary_key]
+    end
+
+    # @return - Arel::Table - The version table, usually named `versions`, but
+    #   not always.
+    # @api private
+    def table
+      @version_class.arel_table
+    end
+
+    # @return - Arel::Attribute - Attribute representing the timestamp column
+    #   of the version table, usually named `created_at` (the rails convention)
+    #   but not always.
+    # @api private
+    def timestamp
+      table[PaperTrail.timestamp_field]
+    end
+  end
+end

data/lib/paper_trail/reifier.rb

@@ -0,0 +1,270 @@
+module PaperTrail
+
+  # Given a version record and some options, builds a new model object.
+  # @api private
+  module Reifier
+    class << self
+
+      # See `VersionConcern#reify` for documentation.
+      # @api private
+      def reify(version, options)
+        options = options.dup
+
+        options.reverse_merge!(
+          :version_at => version.created_at,
+          :mark_for_destruction => false,
+          :has_one    => false,
+          :has_many   => false,
+          :unversioned_attributes => :nil
+        )
+
+        attrs = version.class.object_col_is_json? ?
+          version.object :
+          PaperTrail.serializer.load(version.object)
+
+        # Normally a polymorphic belongs_to relationship allows us to get the
+        # object we belong to by calling, in this case, `item`.  However this
+        # returns nil if `item` has been destroyed, and we need to be able to
+        # retrieve destroyed objects.
+        #
+        # In this situation we constantize the `item_type` to get hold of the
+        # class...except when the stored object's attributes include a `type`
+        # key.  If this is the case, the object we belong to is using single
+        # table inheritance and the `item_type` will be the base class, not the
+        # actual subclass. If `type` is present but empty, the class is the base
+        # class.
+
+        if options[:dup] != true && version.item
+          model = version.item
+          # Look for attributes that exist in the model and not in this
+          # version. These attributes should be set to nil.
+          if options[:unversioned_attributes] == :nil
+            (model.attribute_names - attrs.keys).each { |k| attrs[k] = nil }
+          end
+        else
+          inheritance_column_name = version.item_type.constantize.inheritance_column
+          class_name = attrs[inheritance_column_name].blank? ?
+            version.item_type :
+            attrs[inheritance_column_name]
+          klass = class_name.constantize
+          # The `dup` option always returns a new object, otherwise we should
+          # attempt to look for the item outside of default scope(s).
+          if options[:dup] || (_item = klass.unscoped.find_by_id(version.item_id)).nil?
+            model = klass.new
+          elsif options[:unversioned_attributes] == :nil
+            model = _item
+            # Look for attributes that exist in the model and not in this
+            # version. These attributes should be set to nil.
+            (model.attribute_names - attrs.keys).each { |k| attrs[k] = nil }
+          end
+        end
+
+        model.class.unserialize_attributes_for_paper_trail! attrs
+
+        # Set all the attributes in this version on the model.
+        attrs.each do |k, v|
+          if model.has_attribute?(k)
+            model[k.to_sym] = v
+          elsif model.respond_to?("#{k}=")
+            model.send("#{k}=", v)
+          else
+            version.logger.warn(
+              "Attribute #{k} does not exist on #{version.item_type} (Version id: #{version.id})."
+            )
+          end
+        end
+
+        model.send "#{model.class.version_association_name}=", version
+
+        unless options[:has_one] == false
+          reify_has_ones version.transaction_id, model, options
+        end
+
+        unless options[:has_many] == false
+          reify_has_manys version.transaction_id, model, options
+        end
+
+        model
+      end
+
+      private
+
+      # Replaces each record in `array` with its reified version, if present
+      # in `versions`.
+      #
+      # @api private
+      # @param array - The collection to be modified.
+      # @param options
+      # @param versions - A `Hash` mapping IDs to `Version`s
+      # @return nil - Always returns `nil`
+      #
+      # Once modified by this method, `array` will be assigned to the
+      # AR association currently being reified.
+      #
+      def prepare_array_for_has_many(array, options, versions)
+        # Iterate each child to replace it with the previous value if there is
+        # a version after the timestamp.
+        array.map! do |record|
+          if (version = versions.delete(record.id)).nil?
+            record
+          elsif version.event == 'create'
+            options[:mark_for_destruction] ? record.tap { |r| r.mark_for_destruction } : nil
+          else
+            version.reify(options.merge(:has_many => false, :has_one => false))
+          end
+        end
+
+        # Reify the rest of the versions and add them to the collection, these
+        # versions are for those that have been removed from the live
+        # associations.
+        array.concat(
+          versions.values.map { |v|
+            v.reify(options.merge(:has_many => false, :has_one => false))
+          }
+        )
+
+        array.compact!
+
+        nil
+      end
+
+      # Restore the `model`'s has_one associations as they were when this
+      # version was superseded by the next (because that's what the user was
+      # looking at when they made the change).
+      def reify_has_ones(transaction_id, model, options = {})
+        version_table_name = model.class.paper_trail_version_class.table_name
+        model.class.reflect_on_all_associations(:has_one).each do |assoc|
+          if assoc.klass.paper_trail_enabled_for_model?
+            version = model.class.paper_trail_version_class.joins(:version_associations).
+              where("version_associations.foreign_key_name = ?", assoc.foreign_key).
+              where("version_associations.foreign_key_id = ?", model.id).
+              where("#{version_table_name}.item_type = ?", assoc.class_name).
+              where("created_at >= ? OR transaction_id = ?", options[:version_at], transaction_id).
+              order("#{version_table_name}.id ASC").
+              first
+            if version
+              if version.event == 'create'
+                if options[:mark_for_destruction]
+                  model.send(assoc.name).mark_for_destruction if model.send(assoc.name, true)
+                else
+                  model.appear_as_new_record do
+                    model.send "#{assoc.name}=", nil
+                  end
+                end
+              else
+                child = version.reify(options.merge(:has_many => false, :has_one => false))
+                model.appear_as_new_record do
+                  model.send "#{assoc.name}=", child
+                end
+              end
+            end
+          end
+        end
+      end
+
+      # Restore the `model`'s has_many associations as they were at version_at
+      # timestamp We lookup the first child versions after version_at timestamp or
+      # in same transaction.
+      def reify_has_manys(transaction_id, model, options = {})
+        assoc_has_many_through, assoc_has_many_directly =
+          model.class.reflect_on_all_associations(:has_many).
+            partition { |assoc| assoc.options[:through] }
+        reify_has_many_directly(transaction_id, assoc_has_many_directly, model, options)
+        reify_has_many_through(transaction_id, assoc_has_many_through, model, options)
+      end
+
+      # Restore the `model`'s has_many associations not associated through
+      # another association.
+      def reify_has_many_directly(transaction_id, associations, model, options = {})
+        version_table_name = model.class.paper_trail_version_class.table_name
+        associations.each do |assoc|
+          next unless assoc.klass.paper_trail_enabled_for_model?
+          version_id_subquery = PaperTrail::VersionAssociation.
+            joins(model.class.version_association_name).
+            select("MIN(version_id)").
+            where("foreign_key_name = ?", assoc.foreign_key).
+            where("foreign_key_id = ?", model.id).
+            where("#{version_table_name}.item_type = ?", assoc.class_name).
+            where("created_at >= ? OR transaction_id = ?", options[:version_at], transaction_id).
+            group("item_id").
+            to_sql
+          versions = versions_by_id(model.class, version_id_subquery)
+          collection = Array.new model.send(assoc.name, true) # pass true to avoid cache
+          prepare_array_for_has_many(collection, options, versions)
+          model.send(assoc.name).proxy_association.target = collection
+        end
+      end
+
+      # Restore the `model`'s has_many associations through another association.
+      # This must be called after the direct has_manys have been reified
+      # (reify_has_many_directly).
+      def reify_has_many_through(transaction_id, associations, model, options = {})
+        associations.each do |assoc|
+          next unless assoc.klass.paper_trail_enabled_for_model?
+
+          # Load the collection of through-models. For example, if `model` is a
+          # Chapter, having many Paragraphs through Sections, then
+          # `through_collection` will contain Sections.
+          through_collection = model.send(assoc.options[:through])
+
+          # Examine the `source_reflection`, i.e. the "source" of `assoc` the
+          # `ThroughReflection`. The source can be a `BelongsToReflection`
+          # or a `HasManyReflection`.
+          #
+          # If the association is a has_many association again, then call
+          # reify_has_manys for each record in `through_collection`.
+          if !assoc.source_reflection.belongs_to? && through_collection.present?
+            through_collection.each do |through_model|
+              reify_has_manys(transaction_id, through_model, options)
+            end
+
+            # At this point, the "through" part of the association chain has
+            # been reified, but not the final, "target" part. To continue our
+            # example, `model.sections` (including `model.sections.paragraphs`)
+            # has been loaded. However, the final "target" part of the
+            # association, that is, `model.paragraphs`, has not been loaded. So,
+            # we do that now.
+            collection = through_collection.map { |through_model|
+              through_model.send(assoc.name.to_sym).to_a
+            }.flatten
+          else
+            collection_keys = through_collection.map { |through_model|
+              through_model.send(assoc.association_foreign_key)
+            }
+
+            version_id_subquery = assoc.klass.paper_trail_version_class.
+              select("MIN(id)").
+              where("item_type = ?", assoc.class_name).
+              where("item_id IN (?)", collection_keys).
+              where("created_at >= ? OR transaction_id = ?", options[:version_at], transaction_id).
+              group("item_id").
+              to_sql
+            versions = versions_by_id(assoc.klass, version_id_subquery)
+            collection = Array.new assoc.klass.where(assoc.klass.primary_key => collection_keys)
+            prepare_array_for_has_many(collection, options, versions)
+          end
+
+          # To continue our example above, assign to `model.paragraphs` the
+          # `collection` (an array of `Paragraph`s).
+          model.send(assoc.name).proxy_association.target = collection
+        end
+      end
+
+      # Given a SQL fragment that identifies the IDs of version records,
+      # returns a `Hash` mapping those IDs to `Version`s.
+      #
+      # @api private
+      # @param klass - An ActiveRecord class.
+      # @param version_id_subquery - String. A SQL subquery that selects
+      #   the IDs of version records.
+      # @return A `Hash` mapping IDs to `Version`s
+      #
+      def versions_by_id(klass, version_id_subquery)
+        klass.
+          paper_trail_version_class.
+          where("id IN (#{version_id_subquery})").
+          inject({}) { |acc, v| acc.merge!(v.item_id => v) }
+      end
+    end
+  end
+end

data/lib/paper_trail/serializers/json.rb

@@ -13,8 +13,8 @@ module PaperTrail
         ActiveSupport::JSON.encode object
       end
 
-      # Returns a SQL condition to be used to match the given field and value in
-      # the serialized object.
+      # Returns a SQL condition to be used to match the given field and value
+      # in the serialized object
       def where_object_condition(arel_field, field, value)
         # Convert to JSON to handle strings and nulls correctly.
         json_value = value.to_json
@@ -31,6 +31,17 @@ module PaperTrail
           arel_field.matches("%\"#{field}\":#{json_value}%")
         end
       end
+
+      # Returns a SQL condition to be used to match the given field and value
+      # in the serialized object_changes
+      def where_object_changes_condition(arel_field, field, value)
+        # Convert to JSON to handle strings and nulls correctly.
+        json_value = value.to_json
+
+        # Need to check first (before) and secondary (after) fields
+        arel_field.matches("%\"#{field}\":[#{json_value},%").
+          or(arel_field.matches("%\"#{field}\":[%,#{json_value}]%"))
+      end
     end
   end
 end

data/lib/paper_trail/serializers/yaml.rb

@@ -13,11 +13,25 @@ module PaperTrail
         ::YAML.dump object
       end
 
-      # Returns a SQL condition to be used to match the given field and value in
-      # the serialized object.
+      # Returns a SQL condition to be used to match the given field and value
+      # in the serialized object
       def where_object_condition(arel_field, field, value)
         arel_field.matches("%\n#{field}: #{value}\n%")
       end
+
+      # Returns a SQL condition to be used to match the given field and value
+      # in the serialized object_changes
+      def where_object_changes_condition(arel_field, field, value)
+        # Need to check first (before) and secondary (after) fields
+        if (defined?(::YAML::ENGINE) && ::YAML::ENGINE.yamler == 'psych') ||
+          (defined?(::Psych) && ::YAML == ::Psych)
+          arel_field.matches("%\n#{field}:\n- #{value}\n%").
+            or(arel_field.matches("%\n#{field}:\n-%\n- #{value}\n%"))
+        else # Syck adds extra spaces into array dumps
+          arel_field.matches("%\n#{field}: \n%- #{value}\n%").
+            or(arel_field.matches("%\n#{field}: \n-%\n- #{value}\n%"))
+        end
+      end
     end
   end
 end

data/lib/paper_trail/version_association_concern.rb

@@ -0,0 +1,15 @@
+require 'active_support/concern'
+
+module PaperTrail
+  module VersionAssociationConcern
+    extend ::ActiveSupport::Concern
+
+    included do
+      belongs_to :version
+
+      if PaperTrail.active_record_protected_attributes?
+        attr_accessible :version_id, :foreign_key_name, :foreign_key_id
+      end
+    end
+  end
+end

data/lib/paper_trail/version_concern.rb

@@ -6,10 +6,33 @@ module PaperTrail
 
     included do
       belongs_to :item, :polymorphic => true
+
+      # Since the test suite has test coverage for this, we want to declare
+      # the association when the test suite is running. This makes it pass when
+      # DB is not initialized prior to test runs such as when we run on Travis
+      # CI (there won't be a db in `test/dummy/db/`).
+      if PaperTrail.config.track_associations?
+        has_many :version_associations, :dependent => :destroy
+      end
+
       validates_presence_of :event
-      attr_accessible :item_type, :item_id, :event, :whodunnit, :object, :object_changes if PaperTrail.active_record_protected_attributes?
+
+      if PaperTrail.active_record_protected_attributes?
+        attr_accessible(
+          :item_type,
+          :item_id,
+          :event,
+          :whodunnit,
+          :object,
+          :object_changes,
+          :transaction_id,
+          :created_at
+        )
+      end
 
       after_create :enforce_version_limit!
+
+      scope :within_transaction, lambda { |id| where :transaction_id => id }
     end
 
     module ClassMethods
@@ -33,8 +56,13 @@ module PaperTrail
         where 'event <> ?', 'create'
       end
 
-      # Expects `obj` to be an instance of `PaperTrail::Version` by default, but can accept a timestamp if
-      # `timestamp_arg` receives `true`
+      # 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 && self.primary_key_is_int?
           return where(arel_table[primary_key].gt(obj.id)).order(arel_table[primary_key].asc)
@@ -44,6 +72,13 @@ module PaperTrail
         where(arel_table[PaperTrail.timestamp_field].gt(obj)).order(self.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 && self.primary_key_is_int?
           return where(arel_table[primary_key].lt(obj.id)).order(arel_table[primary_key].desc)
@@ -53,7 +88,6 @@ module PaperTrail
         where(arel_table[PaperTrail.timestamp_field].lt(obj)).order(self.timestamp_sort_order('desc'))
       end
 
-
       def between(start_time, end_time)
         where(
           arel_table[PaperTrail.timestamp_field].gt(start_time).
@@ -61,7 +95,8 @@ module PaperTrail
         ).order(self.timestamp_sort_order)
       end
 
-      # defaults to using the primary key as the secondary sort order if possible
+      # Defaults to using the primary key as the secondary sort order if
+      # possible.
       def timestamp_sort_order(direction = 'asc')
         [arel_table[PaperTrail.timestamp_field].send(direction.downcase)].tap do |array|
           array << arel_table[primary_key].send(direction.downcase) if self.primary_key_is_int?
@@ -72,15 +107,51 @@ module PaperTrail
       # identically-named method in the serializer being used.
       def where_object(args = {})
         raise ArgumentError, 'expected to receive a Hash' unless args.is_a?(Hash)
-        arel_field = arel_table[:object]
 
-        where_conditions = args.map do |field, value|
-          PaperTrail.serializer.where_object_condition(arel_field, field, value)
-        end.reduce do |condition1, condition2|
-          condition1.and(condition2)
+        if columns_hash['object'].type == :jsonb
+          where("object @> ?", args.to_json)
+        elsif columns_hash['object'].type == :json
+          predicates = []
+          values = []
+          args.each do |field, value|
+            predicates.push "object->>? = ?"
+            values.concat([field, value.to_s])
+          end
+          sql = predicates.join(" and ")
+          where(sql, *values)
+        else
+          arel_field = arel_table[:object]
+          where_conditions = args.map { |field, value|
+            PaperTrail.serializer.where_object_condition(arel_field, field, value)
+          }.reduce { |a, e| a.and(e) }
+          where(where_conditions)
         end
+      end
 
-        where(where_conditions)
+      def where_object_changes(args = {})
+        raise ArgumentError, 'expected to receive a Hash' unless args.is_a?(Hash)
+
+        if columns_hash['object_changes'].type == :jsonb
+          args.each { |field, value| args[field] = [value] }
+          where("object_changes @> ?", args.to_json)
+        elsif columns_hash['object'].type == :json
+          predicates = []
+          values = []
+          args.each do |field, value|
+            predicates.push(
+              "((object_changes->>? ILIKE ?) OR (object_changes->>? ILIKE ?))"
+            )
+            values.concat([field, "[#{value.to_json},%", field, "[%,#{value.to_json}]%"])
+          end
+          sql = predicates.join(" and ")
+          where(sql, *values)
+        else
+          arel_field = arel_table[:object_changes]
+          where_conditions = args.map { |field, value|
+            PaperTrail.serializer.where_object_changes_condition(arel_field, field, value)
+          }.reduce { |a, e| a.and(e) }
+          where(where_conditions)
+        end
       end
 
       def primary_key_is_int?
@@ -89,110 +160,83 @@ module PaperTrail
         true
       end
 
-      # Returns whether the `object` column is using the `json` type supported by PostgreSQL
+      # Returns whether the `object` column is using the `json` type supported
+      # by PostgreSQL.
       def object_col_is_json?
-        @object_col_is_json ||= columns_hash['object'].type == :json
+        [:json, :jsonb].include?(columns_hash['object'].type)
       end
 
-      # Returns whether the `object_changes` column is using the `json` type supported by PostgreSQL
+      # Returns whether the `object_changes` column is using the `json` type
+      # supported by PostgreSQL.
       def object_changes_col_is_json?
-        @object_changes_col_is_json ||= columns_hash['object_changes'].type == :json
+        [:json, :jsonb].include?(columns_hash['object_changes'].try(:type))
       end
     end
 
     # Restore the item from this version.
     #
-    # This will automatically restore all :has_one associations as they were "at the time",
-    # if they are also being versioned by PaperTrail.  NOTE: this isn't always guaranteed
-    # to work so you can either change the lookback period (from the default 3 seconds) or
-    # opt out.
+    # 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     set to `false` to opt out of has_one reification.
-    #              set to a float to change the lookback time (check whether your db supports
-    #              sub-second datetimes if you want them).
+    #
+    # - :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.
+    #   - `false` - Default. Useful for persisting the reified version.
+    # - :dup
+    #   - `false` - Default.
+    #   - `true` - Always create a new object instance. Useful for
+    #     comparing two versions of the same object.
+    # - :unversioned_attributes
+    #   - `:nil` - Default. Attributes undefined in version record are set to
+    #     nil in reified record.
+    #   - `:preserve` - Attributes undefined in version record are not modified.
+    #
     def reify(options = {})
       return nil if object.nil?
-
       without_identity_map do
-        options[:has_one] = 3 if options[:has_one] == true
-        options.reverse_merge! :has_one => false
-
-        attrs = self.class.object_col_is_json? ? object : PaperTrail.serializer.load(object)
-
-        # Normally a polymorphic belongs_to relationship allows us
-        # to get the object we belong to by calling, in this case,
-        # `item`.  However this returns nil if `item` has been
-        # destroyed, and we need to be able to retrieve destroyed
-        # objects.
-        #
-        # In this situation we constantize the `item_type` to get hold of
-        # the class...except when the stored object's attributes
-        # include a `type` key.  If this is the case, the object
-        # we belong to is using single table inheritance and the
-        # `item_type` will be the base class, not the actual subclass.
-        # If `type` is present but empty, the class is the base class.
-
-        if item
-          model = item
-          # Look for attributes that exist in the model and not in this version. These attributes should be set to nil.
-          (model.attribute_names - attrs.keys).each { |k| attrs[k] = nil }
-        else
-          inheritance_column_name = item_type.constantize.inheritance_column
-          class_name = attrs[inheritance_column_name].blank? ? item_type : attrs[inheritance_column_name]
-          klass = class_name.constantize
-          model = klass.new
-        end
-
-        model.class.unserialize_attributes_for_paper_trail attrs
-
-        # Set all the attributes in this version on the model
-        attrs.each do |k, v|
-          if model.respond_to?("#{k}=")
-            model[k.to_sym] = v
-          else
-            logger.warn "Attribute #{k} does not exist on #{item_type} (Version id: #{id})."
-          end
-        end
-
-        model.send "#{model.class.version_association_name}=", self
-
-        unless options[:has_one] == false
-          reify_has_ones model, options[:has_one]
-        end
-
-        model
+        ::PaperTrail::Reifier.reify(self, options)
       end
     end
 
-    # Returns what changed in this version of the item.  Cf. `ActiveModel::Dirty#changes`.
-    # Returns `nil` if your `versions` table does not have an `object_changes` text column.
+    # Returns what changed in this version of the item.
+    # `ActiveModel::Dirty#changes`. returns `nil` if your `versions` table does
+    # not have an `object_changes` text column.
     def changeset
       return nil unless self.class.column_names.include? 'object_changes'
-
-      _changes = self.class.object_changes_col_is_json? ? object_changes : PaperTrail.serializer.load(object_changes)
-      @changeset ||= HashWithIndifferentAccess.new(_changes).tap do |changes|
-        item_type.constantize.unserialize_attribute_changes(changes)
-      end
-    rescue
-      {}
+      @changeset ||= load_changeset
     end
 
     # Returns who put the item into the state stored in this version.
+    def paper_trail_originator
+      @paper_trail_originator ||= previous.whodunnit rescue nil
+    end
+
     def originator
-      @originator ||= previous.whodunnit rescue nil
+      ::ActiveSupport::Deprecation.warn "Use paper_trail_originator instead of originator."
+      self.paper_trail_originator
     end
 
-    # Returns who changed the item from the state it had in this version.
-    # This is an alias for `whodunnit`.
+    # Returns who changed the item from the state it had in this version. This
+    # is an alias for `whodunnit`.
     def terminator
       @terminator ||= whodunnit
     end
     alias_method :version_author, :terminator
 
     def sibling_versions(reload = false)
-      @sibling_versions = nil if reload == true
-      @sibling_versions ||= self.class.with_item_keys(item_type, item_id)
+      if reload || @sibling_versions.nil?
+        @sibling_versions = self.class.with_item_keys(item_type, item_id)
+      end
+      @sibling_versions
     end
 
     def next
@@ -203,21 +247,37 @@ module PaperTrail
       @previous ||= sibling_versions.preceding(self).first
     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.
+    # @api public
     def index
-      table = self.class.arel_table unless @index
-      @index ||=
-        if self.class.primary_key_is_int?
-          sibling_versions.select(table[self.class.primary_key]).order(table[self.class.primary_key].asc).index(self)
-        else
-          sibling_versions.select([table[PaperTrail.timestamp_field], table[self.class.primary_key]]).
-            order(self.class.timestamp_sort_order).index(self)
-        end
+      @index ||= RecordHistory.new(sibling_versions, self.class).index(self)
     end
 
     private
 
+    # @api private
+    def load_changeset
+      changes = HashWithIndifferentAccess.new(object_changes_deserialized)
+      item_type.constantize.unserialize_attribute_changes_for_paper_trail!(changes)
+      changes
+    rescue # TODO: Rescue something specific
+      {}
+    end
+
+    # @api private
+    def object_changes_deserialized
+      if self.class.object_changes_col_is_json?
+        object_changes
+      else
+        PaperTrail.serializer.load(object_changes)
+      end
+    end
+
     # In Rails 3.1+, calling reify on a previous version confuses the
     # IdentityMap, if enabled. This prevents insertion into the map.
+    # @api private
     def without_identity_map(&block)
       if defined?(::ActiveRecord::IdentityMap) && ::ActiveRecord::IdentityMap.respond_to?(:without)
         ::ActiveRecord::IdentityMap.without(&block)
@@ -226,38 +286,16 @@ module PaperTrail
       end
     end
 
-    # Restore the `model`'s has_one associations as they were when this version was
-    # superseded by the next (because that's what the user was looking at when they
-    # made the change).
-    #
-    # The `lookback` sets how many seconds before the model's change we go.
-    def reify_has_ones(model, lookback)
-      model.class.reflect_on_all_associations(:has_one).each do |assoc|
-        child = model.send assoc.name
-        if child.respond_to? :version_at
-          # N.B. we use version of the child as it was `lookback` seconds before the parent was updated.
-          # Ideally we want the version of the child as it was just before the parent was updated...
-          # but until PaperTrail knows which updates are "together" (e.g. parent and child being
-          # updated on the same form), it's impossible to tell when the overall update started;
-          # and therefore impossible to know when "just before" was.
-          if (child_as_it_was = child.version_at(send(PaperTrail.timestamp_field) - lookback.seconds))
-            child_as_it_was.attributes.each do |k,v|
-              model.send(assoc.name).send :write_attribute, k.to_sym, v rescue nil
-            end
-          else
-            model.send "#{assoc.name}=", nil
-          end
-        end
-      end
-    end
-
-    # checks to see if a value has been set for the `version_limit` config option, and if so enforces it
+    # Checks that a value has been set for the `version_limit` config
+    # option, and if so enforces it.
+    # @api private
     def enforce_version_limit!
-      return unless PaperTrail.config.version_limit.is_a? Numeric
+      limit = PaperTrail.config.version_limit
+      return unless limit.is_a? Numeric
       previous_versions = sibling_versions.not_creates
-      return unless previous_versions.size > PaperTrail.config.version_limit
-      excess_previous_versions = previous_versions - previous_versions.last(PaperTrail.config.version_limit)
-      excess_previous_versions.map(&:destroy)
+      return unless previous_versions.size > limit
+      excess_versions = previous_versions - previous_versions.last(limit)
+      excess_versions.map(&:destroy)
     end
   end
 end