Add reify_original method.

Returning the original version is a common use-case and is not as easy as it should be, particularly because calling `reify` on the first version returns `nil`, which is the `object` *before* it was created.

This method simply tries to `reify` from the *second* version, if it exists. If it doesn’t exist (i.e. there has not been any changes to the object), it falls back to `self`, which is the original and *only* version of the object.

Added specs to document, legacy widget and widget.

Fixes #1204.

Author: joshuapinter

CHANGELOG.md

@@ -11,7 +11,7 @@ recommendations of [keepachangelog.com](http://keepachangelog.com/).
 
 ### Added
 
-- None
+- [#1204](https://github.com/paper-trail-gem/paper_trail/issues/1204) - Add `reify_original` method for reifying the original object.
 
 ### Fixed
 

lib/paper_trail/record_trail.rb

@@ -69,6 +69,13 @@ def record_create
       end
     end
 
+    # Returns the original version of this object or just this object if there has been no changes.
+    #
+    # @api public
+    def reify_original
+      versions.second&.reify || @record
+    end
+
     # `recording_order` is "after" or "before". See ModelConfig#on_destroy.
     #
     # @api private

spec/models/document_spec.rb

@@ -30,6 +30,17 @@
     end
   end
 
+  describe "#paper_trail.reify_original" do
+    it "returns the expected document" do
+      doc = described_class.create
+      original_name = doc.name
+      doc.update(name: "Doc 1")
+      doc.update(name: "Doc 2")
+      expect(doc.paper_trail_versions.length).to(eq(3))
+      expect(doc.paper_trail.reify_original.name).to(eq(original_name))
+    end
+  end
+
   describe "#paper_trail_versions" do
     it "returns the expected version records" do
       doc = described_class.create

spec/models/legacy_widget_spec.rb

@@ -23,6 +23,16 @@
     end
   end
 
+  describe "#reify_original" do
+    it "return its original self" do
+      widget = described_class.create(name: "foo", version: 2)
+      %w[bar baz].each { |name| widget.update(name: name) }
+      version = widget.versions.last
+      reified = version.reify
+      expect(reified.paper_trail.reify_original).to(eq(reified.versions[1].reify))
+    end
+  end
+
   describe "#update" do
     it "does not create a PT version record because the updated column is ignored" do
       described_class.create.update(version: 1)

spec/models/widget_spec.rb

@@ -654,6 +654,29 @@
     end
   end
 
+  describe "#reify_original" do
+    context "with a reified item" do
+      it "returns the object (not a Version) as it was originally" do
+        widget = described_class.create(name: "Bob")
+        %w[Tom Dick Jane].each do |name|
+          widget.update(name: name)
+        end
+        last_widget = widget.versions.last.reify
+        expect(last_widget.paper_trail.reify_original.name).to(eq(widget.versions[1].reify.name))
+      end
+    end
+
+    context "with a non-reified item" do
+      it "returns the object (not a Version) as it was originally" do
+        widget = described_class.create
+        %w[Tom Dick Jane].each do |name|
+          widget.update(name: name)
+        end
+        expect(widget.paper_trail.reify_original.name).to(eq(widget.versions[1].reify.name))
+      end
+    end
+  end
+
   context "with an unsaved record" do
     it "not have a version created on destroy" do
       widget = described_class.new