paper_trail 1.6.0 → 1.6.1

data/README.md

@@ -171,6 +171,13 @@ Finally, if you got an item by reifying one of its versions, you can navigate ba
     >> widget = latest_version.reify
     >> widget.version == latest_version    # true
 
+You can find out whether a model instance is the current, live one -- or whether it came instead from a previous version -- with `live?`:
+
+    >> widget = Widget.find 42
+    >> widget.live?                        # true
+    >> widget = widget.versions.last.reify
+    >> widget.live?                        # false
+
 
 ## Finding Out Who Was Responsible For A Change
 
@@ -215,7 +222,7 @@ To find out who made a `version`'s object look that way, use `version.originator
 
 ## Has-One Associations
 
-PaperTrail automatically restores `:has_one` associations as they were at the time.
+PaperTrail automatically restores `:has_one` associations as they were at (actually, 3 seconds before) the time.
 
     class Treasure < ActiveRecord::Base
       has_one :location
@@ -230,8 +237,19 @@ PaperTrail automatically restores `:has_one` associations as they were at the ti
     >> t = treasure.versions.last.reify
     >> t.amount                         # 100
     >> t.location.latitude              # 12.345
-    
-Unfortunately PaperTrail doesn't do this for `:has_many` associations (I can't get it to work) or `:belongs_to` (I ran out of time looking at `:has_many`).
+
+The implementation is complicated by the edge case where the parent and child are updated in one go, e.g. in one web request or database transaction.  PaperTrail doesn't know about different models being updated "together", so you can't ask it definitively to get the child as it was before the joint parent-and-child update.
+
+The correct solution is to make PaperTrail aware of requests or transactions (c.f. [Efficiency's transaction ID middleware](http://github.com/efficiency20/ops_middleware/blob/master/lib/e20/ops/middleware/transaction_id_middleware.rb)).  In the meantime we work around the problem by finding the child as it was a few seconds before the parent was updated.  By default we go 3 seconds before but you can change this by passing the `:has_one` option to `reify`:
+
+    >> t = treasure.versions.last.reify(:has_one => 1)       # look back 1 second instead of 3
+
+If you are shuddering, take solace from knowing you can opt out of these shenanigans:
+
+    >> t = treasure.versions.last.reify(:has_one => false)   # I say no to "workarounds"!
+
+Opting out means your `:has_one` associated objects will be the live ones, not the ones the user saw at the time.  Since PaperTrail doesn't auto-restore `:has_many` associations (I can't get it to work) or `:belongs_to` (I ran out of time looking at `:has_many`), this at least makes your associations wrong consistently ;)
+
 
 
 ## Has-Many-Through Associations

data/lib/paper_trail/has_paper_trail.rb

@@ -78,6 +78,12 @@ module PaperTrail
         end
       end
 
+      # Returns true if this instance is the current, live one;
+      # returns false if this instance came from a previous version.
+      def live?
+        version.nil?
+      end
+
       # Returns who put the object into its current state.
       def originator
         versions.last.try :whodunnit
@@ -105,17 +111,6 @@ module PaperTrail
         subsequent_version.reify if subsequent_version
       end
 
-      protected
-
-      # Returns the object (not a Version) as it was until the version record
-      # with the given id.
-      def version_until(id)
-        # Because a version stores how its object looked *before* the change,
-        # we need to look for the first version created *on or after* the id.
-        version = versions.first :conditions => ['id >= ?', id], :order => 'id ASC'
-        version ? version.reify : self
-      end
-
       private
 
       def merge_metadata(data)

data/lib/paper_trail/version.rb

@@ -2,7 +2,20 @@ class Version < ActiveRecord::Base
   belongs_to :item, :polymorphic => true
   validates_presence_of :event
 
-  def reify
+  # 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.
+  #
+  # 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).
+  def reify(options = {})
+    options.reverse_merge! :has_one => 3
+
     unless object.nil?
       attrs = YAML::load object
 
@@ -36,10 +49,11 @@ class Version < ActiveRecord::Base
       end
 
       model.version = self
-      # 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).
-      reify_has_ones model
+
+      unless options[:has_one] == false
+        reify_has_ones model, options[:has_one]
+      end
+
       model
     end
   end
@@ -72,12 +86,22 @@ class Version < ActiveRecord::Base
 
   private
 
-  def reify_has_ones(model)
+  # 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_until
-        if (version_until = child.version_until(id))
-          version_until.attributes.each do |k,v|
+      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(created_at - lookback.seconds))
+          child_as_it_was.attributes.each do |k,v|
             model.send(assoc.name).send "#{k}=", v rescue nil
           end
         else

data/lib/paper_trail/version_number.rb

@@ -1,3 +1,3 @@
 module PaperTrail
-  VERSION = '1.6.0'
+  VERSION = '1.6.1'
 end

data/test/paper_trail_model_test.rb

@@ -46,8 +46,7 @@ end
 
 class HasPaperTrailModelTest < Test::Unit::TestCase
   load_schema
-=begin
-=end
+
   context 'A record' do
     setup { @article = Article.create }
 
@@ -70,6 +69,10 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
       assert_equal [], @widget.versions
     end
 
+    should 'be live' do
+      assert @widget.live?
+    end
+
 
     context 'which is then created' do
       setup { @widget.update_attributes :name => 'Henry' }
@@ -87,6 +90,10 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
         assert_match /create/i, @widget.versions.first.event
       end
 
+      should 'be live' do
+        assert @widget.live?
+      end
+
 
       context 'and then updated without any changes' do
         setup { @widget.save }
@@ -120,6 +127,10 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
           assert_match /update/i, @widget.versions.last.event
         end
 
+        should 'have versions that are not live' do
+          assert @widget.versions.map(&:reify).compact.all? { |w| !w.live? }
+        end
+
 
         context 'and has one associated object' do
           setup do
@@ -650,13 +661,16 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
 
   context 'A model with a has_one association' do
     setup { @widget = Widget.create :name => 'widget_0' }
+
     context 'before the associated was created' do
       setup do
         @widget.update_attributes :name => 'widget_1'
         @wotsit = @widget.create_wotsit :name => 'wotsit_0'
       end
+
       context 'when reified' do
-        setup { @widget_0 = @widget.versions.last.reify }
+        setup { @widget_0 = @widget.versions.last.reify(:has_one => 1) }
+
         should 'see the associated as it was at the time' do
           assert_nil @widget_0.wotsit
         end
@@ -666,10 +680,14 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
     context 'where the associated is created between model versions' do
       setup do
         @wotsit = @widget.create_wotsit :name => 'wotsit_0'
+        make_last_version_earlier @wotsit
+
         @widget.update_attributes :name => 'widget_1'
       end
+
       context 'when reified' do
-        setup { @widget_0 = @widget.versions.last.reify }
+        setup { @widget_0 = @widget.versions.last.reify(:has_one => 1) }
+
         should 'see the associated as it was at the time' do
           assert_equal 'wotsit_0', @widget_0.wotsit.name
         end
@@ -678,24 +696,42 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
       context 'and then the associated is updated between model versions' do
         setup do
           @wotsit.update_attributes :name => 'wotsit_1'
+          make_last_version_earlier @wotsit
           @wotsit.update_attributes :name => 'wotsit_2'
+          make_last_version_earlier @wotsit
+
           @widget.update_attributes :name => 'widget_2'
+          @wotsit.update_attributes :name => 'wotsit_3'
         end
+
         context 'when reified' do
-          setup { @widget_1 = @widget.versions.last.reify }
+          setup { @widget_1 = @widget.versions.last.reify(:has_one => 1) }
+
           should 'see the associated as it was at the time' do
             assert_equal 'wotsit_2', @widget_1.wotsit.name
           end
         end
+
+        context 'when reified opting out of has_one reification' do
+          setup { @widget_1 = @widget.versions.last.reify(:has_one => false) }
+
+          should 'see the associated as it is live' do
+            assert_equal 'wotsit_3', @widget_1.wotsit.name
+          end
+        end
       end
 
       context 'and then the associated is destroyed between model versions' do
         setup do
           @wotsit.destroy
+          make_last_version_earlier @wotsit
+
           @widget.update_attributes :name => 'widget_3'
         end
+
         context 'when reified' do
-          setup { @widget_2 = @widget.versions.last.reify }
+          setup { @widget_2 = @widget.versions.last.reify(:has_one => 1) }
+
           should 'see the associated as it was at the time' do
             assert_nil @widget_2.wotsit
           end
@@ -704,4 +740,14 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
     end
   end
 
+  private
+
+  # Updates `model`'s last version so it looks like the version was
+  # created 2 seconds ago.
+  def make_last_version_earlier(model)
+    Version.record_timestamps = false
+    model.versions.last.update_attributes :created_at => 2.seconds.ago
+    Version.record_timestamps = true
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 13
   prerelease: false
   segments: 
   - 1
   - 6
-  - 0
-  version: 1.6.0
+  - 1
+  version: 1.6.1
 platform: ruby
 authors: 
 - Andy Stewart
@@ -15,14 +15,13 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-20 00:00:00 +01:00
+date: 2010-10-21 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: bundler
-  type: :development
   prerelease: false
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -32,12 +31,12 @@ dependencies:
         - 1
         - 0
         version: "1.0"
-  requirement: *id001
+  type: :development
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: rake
-  type: :development
   prerelease: false
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - "="
@@ -48,12 +47,12 @@ dependencies:
         - 8
         - 7
         version: 0.8.7
-  requirement: *id002
+  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: shoulda
-  type: :development
   prerelease: false
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - "="
@@ -64,12 +63,12 @@ dependencies:
         - 10
         - 3
         version: 2.10.3
-  requirement: *id003
+  type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: activesupport
-  type: :development
   prerelease: false
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -79,12 +78,12 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  requirement: *id004
+  type: :development
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: sqlite3-ruby
-  type: :development
   prerelease: false
-  version_requirements: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -94,12 +93,12 @@ dependencies:
         - 1
         - 2
         version: "1.2"
-  requirement: *id005
+  type: :development
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: activerecord
-  type: :runtime
   prerelease: false
-  version_requirements: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -109,12 +108,12 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  requirement: *id006
+  type: :runtime
+  version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: actionpack
-  type: :runtime
   prerelease: false
-  version_requirements: &id007 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -124,7 +123,8 @@ dependencies:
         - 2
         - 3
         version: "2.3"
-  requirement: *id007
+  type: :runtime
+  version_requirements: *id007
 description: Track changes to your models' data.  Good for auditing or versioning.
 email: boss@airbladesoftware.com
 executables: []