paper_trail 4.0.0 → 4.0.1

data/lib/paper_trail/version_concern.rb

@@ -7,10 +7,10 @@ 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/`)
+      # 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
@@ -47,8 +47,8 @@ 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`
+      # Expects `obj` to be an instance of `PaperTrail::Version` by default,
+      # but can accept a timestamp if `timestamp_arg` receives `true`
       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)
@@ -75,7 +75,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?
@@ -137,12 +138,14 @@ 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?
         [: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?
         [:json, :jsonb].include?(columns_hash['object_changes'].try(:type))
       end
@@ -150,18 +153,31 @@ 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.
+    # 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 `true` to also reify has_one associations. Default is `false`.
-    # :has_many             set to `true` to also reify has_many and has_many :through associations.
-    #                       Default is `false`.
-    # :mark_for_destruction set to `true` to mark the has_one/has_many associations that did not exist in the
-    #                       reified version for destruction, instead of remove them. Default is `false`.
-    #                       This option is handy for people who want to persist the reified version.
-    # :dup                  `false` default behavior
-    #                       `true` it always create a new object instance. It is useful for comparing two versions of the same object
+    #
+    # - :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?
 
@@ -170,39 +186,43 @@ module PaperTrail
           :version_at => created_at,
           :mark_for_destruction => false,
           :has_one    => false,
-          :has_many   => false
+          :has_many   => false,
+          :unversioned_attributes => :nil
         )
 
         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.
+        # 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.
+        # 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 && 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 }
+          # 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 = item_type.constantize.inheritance_column
           class_name = attrs[inheritance_column_name].blank? ? 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)
+          # 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(item_id)).nil?
             model = klass.new
-          else
+          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.
+            # 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
@@ -211,7 +231,7 @@ module PaperTrail
           model.class.unserialize_attributes_for_paper_trail! attrs
         end
 
-        # Set all the attributes in this version on the model
+        # 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
@@ -236,8 +256,9 @@ module PaperTrail
       end
     end
 
-    # 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.
+    # 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'
 
@@ -261,8 +282,8 @@ module PaperTrail
       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
@@ -304,9 +325,9 @@ 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).
+    # 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(model, options = {})
       version_table_name = model.class.paper_trail_version_class.table_name
       model.class.reflect_on_all_associations(:has_one).each do |assoc|
@@ -337,8 +358,9 @@ module PaperTrail
       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.
+    # 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(model, options = {})
       assoc_has_many_through, assoc_has_many_directly =
         model.class.reflect_on_all_associations(:has_many).
@@ -347,7 +369,8 @@ module PaperTrail
       reify_has_many_through(assoc_has_many_through, model, options)
     end
 
-    # Restore the `model`'s has_many associations not associated through another association
+    # Restore the `model`'s has_many associations not associated through
+    # another association.
     def reify_has_many_directly(associations, model, options = {})
       version_table_name = model.class.paper_trail_version_class.table_name
       associations.each do |assoc|
@@ -363,10 +386,11 @@ module PaperTrail
           acc.merge!(v.item_id => v)
         end
 
-        # Pass true to force the model to load
+        # Pass true to force the model to load.
         collection = Array.new model.send(assoc.name, true)
 
-        # Iterate each child to replace it with the previous value if there is a version after the timestamp
+        # Iterate each child to replace it with the previous value if there is
+        # a version after the timestamp.
         collection.map! do |c|
           if (version = versions.delete(c.id)).nil?
             c
@@ -377,16 +401,18 @@ module PaperTrail
           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
+        # 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.
         collection += versions.values.map { |version| version.reify(options.merge(:has_many => false, :has_one => false)) }
 
         model.send(assoc.name).proxy_association.target = collection.compact
       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)
+    # 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(associations, model, options = {})
       associations.each do |assoc|
         next unless assoc.klass.paper_trail_enabled_for_model?
@@ -405,7 +431,8 @@ module PaperTrail
 
         collection = Array.new assoc.klass.where(assoc.klass.primary_key => collection_keys)
 
-        # Iterate each child to replace it with the previous value if there is a version after the timestamp
+        # Iterate each child to replace it with the previous value if there is
+        # a version after the timestamp.
         collection.map! do |c|
           if (version = versions.delete(c.id)).nil?
             c
@@ -416,15 +443,17 @@ module PaperTrail
           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
+        # 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.
         collection += versions.values.map { |version| version.reify(options.merge(:has_many => false, :has_one => false)) }
 
         model.send(assoc.name).proxy_association.target = collection.compact
       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.
     def enforce_version_limit!
       return unless PaperTrail.config.version_limit.is_a? Numeric
       previous_versions = sibling_versions.not_creates

data/lib/paper_trail/version_number.rb

@@ -2,7 +2,7 @@ module PaperTrail
   module VERSION
     MAJOR = 4
     MINOR = 0
-    TINY  = 0
+    TINY  = 1
     PRE   = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')

data/spec/models/skipper_spec.rb

@@ -1,16 +1,45 @@
 require 'rails_helper'
 
 describe Skipper, :type => :model do
-  describe "#update_attributes!", :versioning => true do
-    context "updating a skipped attribute" do
-      let(:t1) { Time.zone.local(2015, 7, 15, 20, 34, 0) }
-      let(:t2) { Time.zone.local(2015, 7, 15, 20, 34, 30) }
+  with_versioning do
+    it { is_expected.to be_versioned }
 
-      it "should not create a version" do
-        skipper = Skipper.create!(:another_timestamp => t1)
-        expect {
-          skipper.update_attributes!(:another_timestamp => t2)
-        }.to_not change { skipper.versions.length }
+    describe "#update_attributes!", :versioning => true do
+      context "updating a skipped attribute" do
+        let(:t1) { Time.zone.local(2015, 7, 15, 20, 34, 0) }
+        let(:t2) { Time.zone.local(2015, 7, 15, 20, 34, 30) }
+
+        it "should not create a version" do
+          skipper = Skipper.create!(:another_timestamp => t1)
+          expect {
+            skipper.update_attributes!(:another_timestamp => t2)
+          }.to_not change { skipper.versions.length }
+        end
+      end
+    end
+
+    describe "reify" do
+      context "reifying a with a skipped attribute" do
+        let(:t1) { Time.zone.local(2015, 7, 15, 20, 34, 0) }
+        let(:t2) { Time.zone.local(2015, 7, 15, 20, 34, 30) }
+
+        context "without preserve (default)" do
+          it "should have no timestamp" do
+            skipper = Skipper.create!(:another_timestamp => t1)
+            skipper.update_attributes!(:another_timestamp => t2, :name => "Foobar")
+            skipper = skipper.versions.last.reify
+            expect(skipper.another_timestamp).to be(nil)
+          end
+        end
+
+        context "with preserve" do
+          it "should preserve its timestamp" do
+            skipper = Skipper.create!(:another_timestamp => t1)
+            skipper.update_attributes!(:another_timestamp => t2, :name => "Foobar")
+            skipper = skipper.versions.last.reify(:unversioned_attributes => :preserve)
+            expect(skipper.another_timestamp).to eq(t2)
+          end
+        end
       end
     end
   end

data/spec/models/widget_spec.rb

@@ -51,8 +51,8 @@ describe Widget, :type => :model do
     describe :after_create do
       let(:widget) { Widget.create!(:name => 'Foobar', :created_at => Time.now - 1.week) }
 
-      it "corresponding version should use the widget's `created_at`" do
-        expect(widget.versions.last.created_at.to_i).to eq(widget.created_at.to_i)
+      it "corresponding version should use the widget's `updated_at`" do
+        expect(widget.versions.last.created_at.to_i).to eq(widget.updated_at.to_i)
       end
     end
 

data/test/dummy/db/migrate/20110208155312_set_up_test_tables.rb

@@ -1,7 +1,8 @@
 class SetUpTestTables < ActiveRecord::Migration
   def self.up
     create_table :skippers, :force => true do |t|
-      t.datetime :another_timestamp
+      t.string     :name
+      t.datetime   :another_timestamp
       t.timestamps :null => true
     end
 

data/test/dummy/db/schema.rb

@@ -13,77 +13,108 @@
 
 ActiveRecord::Schema.define(version: 20110208155312) do
 
-  create_table "animals", force: true do |t|
+  create_table "animals", force: :cascade do |t|
     t.string "name"
     t.string "species"
   end
 
-  create_table "articles", force: true do |t|
+  create_table "articles", force: :cascade do |t|
     t.string "title"
     t.string "content"
     t.string "abstract"
     t.string "file_upload"
   end
 
-  create_table "authorships", force: true do |t|
+  create_table "authorships", force: :cascade do |t|
     t.integer "book_id"
     t.integer "person_id"
   end
 
-  create_table "books", force: true do |t|
+  create_table "banana_versions", force: :cascade do |t|
+    t.string   "item_type",  null: false
+    t.integer  "item_id",    null: false
+    t.string   "event",      null: false
+    t.string   "whodunnit"
+    t.text     "object"
+    t.datetime "created_at"
+  end
+
+  add_index "banana_versions", ["item_type", "item_id"], name: "index_banana_versions_on_item_type_and_item_id"
+
+  create_table "bananas", force: :cascade do |t|
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  create_table "books", force: :cascade do |t|
     t.string "title"
   end
 
-  create_table "customers", force: true do |t|
+  create_table "boolits", force: :cascade do |t|
+    t.string  "name"
+    t.boolean "scoped", default: true
+  end
+
+  create_table "customers", force: :cascade do |t|
     t.string "name"
   end
 
-  create_table "documents", force: true do |t|
+  create_table "documents", force: :cascade do |t|
     t.string "name"
   end
 
-  create_table "editors", force: true do |t|
+  create_table "editors", force: :cascade do |t|
     t.string "name"
   end
 
-  create_table "editorships", force: true do |t|
+  create_table "editorships", force: :cascade do |t|
     t.integer "book_id"
     t.integer "editor_id"
   end
 
-  create_table "fluxors", force: true do |t|
+  create_table "fluxors", force: :cascade do |t|
     t.integer "widget_id"
     t.string  "name"
   end
 
-  create_table "gadgets", force: true do |t|
+  create_table "fruits", force: :cascade do |t|
+    t.string "name"
+    t.string "color"
+  end
+
+  create_table "gadgets", force: :cascade do |t|
     t.string   "name"
     t.string   "brand"
     t.datetime "created_at"
     t.datetime "updated_at"
   end
 
-  create_table "legacy_widgets", force: true do |t|
+  create_table "legacy_widgets", force: :cascade do |t|
     t.string  "name"
     t.integer "version"
   end
 
-  create_table "line_items", force: true do |t|
+  create_table "line_items", force: :cascade do |t|
     t.integer "order_id"
     t.string  "product"
   end
 
-  create_table "orders", force: true do |t|
+  create_table "not_on_updates", force: :cascade do |t|
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  create_table "orders", force: :cascade do |t|
     t.integer "customer_id"
     t.string  "order_date"
   end
 
-  create_table "people", force: true do |t|
+  create_table "people", force: :cascade do |t|
     t.string "name"
     t.string "time_zone"
   end
 
-  create_table "post_versions", force: true do |t|
+  create_table "post_versions", force: :cascade do |t|
     t.string   "item_type",  null: false
     t.integer  "item_id",    null: false
     t.string   "event",      null: false
@@ -96,31 +127,38 @@ ActiveRecord::Schema.define(version: 20110208155312) do
 
   add_index "post_versions", ["item_type", "item_id"], name: "index_post_versions_on_item_type_and_item_id"
 
-  create_table "post_with_statuses", force: true do |t|
+  create_table "post_with_statuses", force: :cascade do |t|
     t.integer "status"
   end
 
-  create_table "posts", force: true do |t|
+  create_table "posts", force: :cascade do |t|
     t.string "title"
     t.string "content"
   end
 
-  create_table "songs", force: true do |t|
+  create_table "skippers", force: :cascade do |t|
+    t.string   "name"
+    t.datetime "another_timestamp"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  create_table "songs", force: :cascade do |t|
     t.integer "length"
   end
 
-  create_table "things", force: true do |t|
+  create_table "things", force: :cascade do |t|
     t.string "name"
   end
 
-  create_table "translations", force: true do |t|
+  create_table "translations", force: :cascade do |t|
     t.string "headline"
     t.string "content"
     t.string "language_code"
     t.string "type"
   end
 
-  create_table "version_associations", force: true do |t|
+  create_table "version_associations", force: :cascade do |t|
     t.integer "version_id"
     t.string  "foreign_key_name", null: false
     t.integer "foreign_key_id"
@@ -129,7 +167,7 @@ ActiveRecord::Schema.define(version: 20110208155312) do
   add_index "version_associations", ["foreign_key_name", "foreign_key_id"], name: "index_version_associations_on_foreign_key"
   add_index "version_associations", ["version_id"], name: "index_version_associations_on_version_id"
 
-  create_table "versions", force: true do |t|
+  create_table "versions", force: :cascade do |t|
     t.string   "item_type",      null: false
     t.integer  "item_id",        null: false
     t.string   "event",          null: false
@@ -149,13 +187,13 @@ ActiveRecord::Schema.define(version: 20110208155312) do
 
   add_index "versions", ["item_type", "item_id"], name: "index_versions_on_item_type_and_item_id"
 
-  create_table "whatchamajiggers", force: true do |t|
+  create_table "whatchamajiggers", force: :cascade do |t|
     t.string  "owner_type"
     t.integer "owner_id"
     t.string  "name"
   end
 
-  create_table "widgets", force: true do |t|
+  create_table "widgets", force: :cascade do |t|
     t.string   "name"
     t.text     "a_text"
     t.integer  "an_integer"
@@ -171,7 +209,7 @@ ActiveRecord::Schema.define(version: 20110208155312) do
     t.datetime "updated_at"
   end
 
-  create_table "wotsits", force: true do |t|
+  create_table "wotsits", force: :cascade do |t|
     t.integer  "widget_id"
     t.string   "name"
     t.datetime "created_at"