houston-vestal_versions 2.0.0

data/lib/vestal_versions/versioned.rb

@@ -0,0 +1,27 @@
+module VestalVersions
+  # Simply adds a flag to determine whether a model class if versioned.
+  module Versioned
+    extend ActiveSupport::Concern
+
+    # Overrides the +versioned+ method to first define the +versioned?+ class method before
+    # deferring to the original +versioned+.
+    module ClassMethods
+      def versioned(*args)
+        super(*args)
+
+        class << self
+          def versioned?
+            true
+          end
+        end
+      end
+
+      # For all ActiveRecord::Base models that do not call the +versioned+ method, the +versioned?+
+      # method will return false.
+      def versioned?
+        false
+      end
+    end
+
+  end
+end

data/lib/vestal_versions/versions.rb

@@ -0,0 +1,89 @@
+# See: https://github.com/rails/rails/issues/11026
+if ActiveRecord::VERSION::MAJOR == 3 && ActiveRecord::VERSION::MINOR == 0 && RUBY_VERSION >= "2.0.0"
+  module ActiveRecord
+    module Associations
+      class AssociationProxy
+        def send(method, *args)
+          if proxy_respond_to?(method, true)
+            super
+          else
+            load_target
+            @target.send(method, *args)
+          end
+        end
+      end
+    end
+  end
+end
+
+module VestalVersions
+  # An extension module for the +has_many+ association with versions.
+  module Versions
+    # Returns all versions between (and including) the two given arguments. See documentation for
+    # the +at+ extension method for what arguments are valid. If either of the given arguments is
+    # invalid, an empty array is returned.
+    #
+    # The +between+ method preserves returns an array of version records, preserving the order
+    # given by the arguments. If the +from+ value represents a version before that of the +to+
+    # value, the array will be ordered from earliest to latest. The reverse is also true.
+    def between(from, to)
+      from_number, to_number = number_at(from), number_at(to)
+      return [] if from_number.nil? || to_number.nil?
+
+      condition = (from_number == to_number) ? to_number : Range.new(*[from_number, to_number].sort)
+      where(:number => condition).order("#{table_name}.#{connection.quote_column_name('number')} #{(from_number > to_number) ? 'DESC' : 'ASC'}").to_a
+    end
+
+    # Returns all version records created before the version associated with the given value.
+    def before(value)
+      return [] if (number = number_at(value)).nil?
+      where("#{table_name}.#{connection.quote_column_name('number')} < #{number}").to_a
+    end
+
+    # Returns all version records created after the version associated with the given value.
+    #
+    # This is useful for dissociating records during use of the +reset_to!+ method.
+    def after(value)
+      return [] if (number = number_at(value)).nil?
+      where("#{table_name}.#{connection.quote_column_name('number')} > #{number}").to_a
+    end
+
+    # Returns a single version associated with the given value. The following formats are valid:
+    # * A Date or Time object: When given, +to_time+ is called on the value and the last version
+    #   record in the history created before (or at) that time is returned.
+    # * A Numeric object: Typically a positive integer, these values correspond to version numbers
+    #   and the associated version record is found by a version number equal to the given value
+    #   rounded down to the nearest integer.
+    # * A String: A string value represents a version tag and the associated version is searched
+    #   for by a matching tag value. *Note:* Be careful with string representations of numbers.
+    # * A Symbol: Symbols represent association class methods on the +has_many+ versions
+    #   association. While all of the built-in association methods require arguments, additional
+    #   extension modules can be defined using the <tt>:extend</tt> option on the +versioned+
+    #   method. See the +versioned+ documentation for more information.
+    # * A Version object: If a version object is passed to the +at+ method, it is simply returned
+    #   untouched.
+    def at(value)
+      case value
+        when Date, Time then where("#{table_name}.created_at <= ?", value.to_time).last
+        when Numeric then find_by_number(value.floor)
+        when String then find_by_tag(value)
+        when Symbol then respond_to?(value) ? send(value) : nil
+        when Version then value
+      end
+    end
+
+    # Returns the version number associated with the given value. In many cases, this involves
+    # simply passing the value to the +at+ method and then returning the subsequent version number.
+    # Hoever, for Numeric values, the version number can be returned directly and for Date/Time
+    # values, a default value of 1 is given to ensure that times prior to the first version
+    # still return a valid version number (useful for reversion).
+    def number_at(value)
+      case value
+        when Date, Time then (v = at(value)) ? v.number : 1
+        when Numeric then value.floor
+        when String, Symbol then (v = at(value)) ? v.number : nil
+        when Version then value.number
+      end
+    end
+  end
+end

data/lib/vestal_versions.rb

@@ -0,0 +1,126 @@
+require 'active_support/concern'
+require 'active_support/dependencies/autoload'
+require 'active_support/core_ext/module/delegation'
+require 'active_record'
+
+# +vestal_versions+ keeps track of updates to ActiveRecord models, leveraging the introduction of
+# dirty attributes in Rails 2.1. By storing only the updated attributes in a serialized column of a
+# single version model, the history is kept DRY and no additional schema changes are necessary.
+#
+# Author:: Steve Richert
+# Copyright:: Copyright (c) 2009 Steve Richert
+# License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
+#
+# To enable versioning on a model, simply use the +versioned+ method:
+#
+#   class User < ActiveRecord::Base
+#     versioned
+#   end
+#
+#   user = User.create(:name => "Steve Richert")
+#   user.version # => 1
+#   user.update_attribute(:name, "Steve Jobs")
+#   user.version # => 2
+#   user.revert_to(1)
+#   user.name # => "Steve Richert"
+#
+# See the +versioned+ documentation for more details.
+
+# The base module that gets included in ActiveRecord::Base. See the documentation for
+# VestalVersions::ClassMethods for more useful information.
+module VestalVersions
+  extend ActiveSupport::Concern
+  extend ActiveSupport::Autoload
+
+  autoload :Changes
+  autoload :Conditions
+  autoload :Control
+  autoload :Creation
+  autoload :Deletion
+  autoload :Options
+  autoload :Reload
+  autoload :Reset
+  autoload :Reversion
+  autoload :Users
+  autoload :Version
+  autoload :VERSION, 'vestal_versions/version_num'
+  autoload :VersionTagging
+  autoload :Versioned
+  autoload :Versions
+
+  class << self
+    delegate :config, :configure, :to => Version
+  end
+
+  included do
+    include Versioned
+  end
+
+  module ClassMethods
+    # +versioned+ associates an ActiveRecord model with many versions. When the object is updated,
+    # a new version containing the changes is created. There are several options available to the
+    # +versioned+ method, most of which are passed to the +has_many+ association itself:
+    # * <tt>:class_name</tt>: The class name of the version model to use for the association. By
+    #   default, this is set to "VestalVersions::Version", representing the built-in version class.
+    #   By specifying this option, you can override the version class, to include custom version
+    #   behavior. It's recommended that a custom version inherit from VestalVersions::Version.
+    # * <tt>:dependent</tt>: Also common to +has_many+ associations, this describes the behavior of
+    #   version records when the parent object is destroyed. This defaults to :delete_all, which
+    #   will permanently remove all associated versions *without* triggering any destroy callbacks.
+    #   Other options are :destroy which removes the associated versions *with* callbacks, or
+    #   :nullify which leaves the version records in the database, but dissociates them from the
+    #   parent object by setting the foreign key columns to +nil+ values.  Setting this option to 
+    #   :tracking will perform a soft delete on destroy and create a new version record preserving
+    #   details of this record for later restoration.
+    # * <tt>:except</tt>: An update will trigger version creation as long as at least one column
+    #   outside those specified here was updated. Also, upon version creation, the columns
+    #   specified here will be excluded from the change history. This is useful when dealing with
+    #   unimportant, constantly changing, or sensitive information. This option accepts a symbol,
+    #   string or an array of either, representing column names to exclude. It is completely
+    #   optional and defaults to +nil+, allowing all columns to be versioned. This option is also
+    #   ignored if the +only+ option is used.
+    # * <tt>:extend</tt>: This option allows you to extend the +has_many+ association proxy with a
+    #   module or an array of modules. Any methods defined in those modules become available on the
+    #   +versions+ association. The VestalVersions::Versions module is essential to the
+    #   functionality of +vestal_versions+ and so is prepended to any additional modules that you
+    #   might specify here.
+    # * <tt>:if</tt>: Accepts a symbol, a proc or an array of either to be evaluated when the parent
+    #   object is updated to determine whether a new version should be created. +to_proc+ is called
+    #   on any symbols given and the resulting procs are called, passing in the object itself. If
+    #   an array is given, all must be evaluate to +true+ in order for a version to be created.
+    # * <tt>:initial_version</tt>: When set to true, an initial version is always created when the
+    #   parent object is created. This initial version will have nil changes however it can be
+    #   used to store who created the original version.
+    # * <tt>:only</tt>: An update will trigger version creation as long as at least one updated
+    #   column falls within those specified here. Also, upon version creation, only the columns
+    #   specified here will be included in the change history. This option accepts a symbol, string
+    #   or an array of either, representing column names to include. It is completely optional and
+    #   defaults to +nil+, allowing all columns to be versioned. This option takes precedence over
+    #   the +except+ option if both are specified.
+    # * <tt>:unless</tt>: Accepts a symbol, a proc or an array of either to be evaluated when the
+    #   parent object is updated to determine whether version creation should be skipped. +to_proc+
+    #   is called on any symbols given and the resulting procs are called, passing in the object
+    #   itself. If an array is given and any element evaluates as +true+, the version creation will
+    #   be skipped.
+    def versioned(options = {}, &block)
+      return if versioned?
+
+      include Options
+      include Changes
+      include Creation
+      include Users
+      include Reversion
+      include Reset
+      include Conditions
+      include Control
+      include VersionTagging
+      include Reload
+      include Deletion
+
+      prepare_versioned_options(options)
+      has_many :versions, options, &block
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval{ include VestalVersions }

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+if ENV['COVERAGE']
+  require 'coveralls'
+  Coveralls.wear!
+end
+
+require 'vestal_versions'
+
+require 'bundler'
+Bundler.require(:test)
+
+RSpec.configure do |c|
+  c.before(:suite) do
+    CreateSchema.suppress_messages{ CreateSchema.migrate(:up) }
+  end
+
+  c.after(:suite) do
+    FileUtils.rm_rf(File.expand_path('../test.db', __FILE__))
+  end
+
+  c.after(:each) do
+    VestalVersions::Version.config.clear
+    User.prepare_versioned_options({})
+  end
+
+  c.order = 'random'
+end
+
+Dir[File.expand_path('../support/*.rb', __FILE__)].each{|f| require f }

data/spec/support/models.rb

@@ -0,0 +1,19 @@
+class User < ActiveRecord::Base
+  versioned
+
+  def name
+    [first_name, last_name].compact.join(' ')
+  end
+
+  def name= names
+    self[:first_name], self[:last_name] = names.split(' ', 2)
+  end
+end
+
+class DeletedUser < ActiveRecord::Base
+  self.table_name = 'users'
+  versioned :dependent => :tracking
+end
+
+class MyCustomVersion < VestalVersions::Version
+end

data/spec/support/schema.rb

@@ -0,0 +1,25 @@
+ActiveRecord::Base.establish_connection(
+  :adapter  => 'sqlite3',
+  :database => File.expand_path('../../test.db', __FILE__)
+)
+
+class CreateSchema < ActiveRecord::Migration
+  def self.up
+    create_table :users, :force => true do |t|
+      t.string :first_name
+      t.string :last_name
+      t.timestamps
+    end
+
+    create_table :versions, :force => true do |t|
+      t.belongs_to :versioned, :polymorphic => true
+      t.belongs_to :user, :polymorphic => true
+      t.string :user_name
+      t.text :modifications
+      t.integer :number
+      t.integer :reverted_from
+      t.string :tag
+      t.timestamps
+    end
+  end
+end

data/spec/vestal_versions/changes_spec.rb

@@ -0,0 +1,134 @@
+require 'spec_helper'
+
+describe VestalVersions::Changes do
+  context "a version's changes" do
+    let(:user){ User.create(:name => 'Steve Richert') }
+    subject{ user.versions.last.changes }
+
+    before do
+      user.update_attribute(:last_name, 'Jobs')
+    end
+
+    it { should be_a(Hash) }
+    it { should_not be_empty }
+
+    it 'has string keys' do
+      subject.keys.each{ |key| key.should be_a(String) }
+    end
+
+    it 'has two-element array values' do
+      subject.values.each do |key|
+        key.should be_a(Array)
+        key.size.should == 2
+      end
+    end
+
+    it 'has unique-element values' do
+      subject.values.each{ |v| v.uniq.should == v }
+    end
+
+    it "equals the model's changes" do
+      user.first_name = 'Stephen'
+      model_changes = user.changes
+      user.save
+      changes = user.versions.last.changes
+
+      model_changes.should == changes
+    end
+  end
+
+  context 'a hash of changes' do
+    let(:changes){ {'first_name' => ['Steve', 'Stephen']} }
+    let(:other){ {'first_name' => ['Catie', 'Catherine']} }
+
+    it 'properly appends other changes' do
+      expected = {'first_name' => ['Steve', 'Catherine']}
+
+      changes.append_changes(other).should == expected
+
+      changes.append_changes!(other)
+      changes.should == expected
+    end
+
+    it 'properly prepends other changes' do
+      expected = {'first_name' => ['Catie', 'Stephen']}
+
+      changes.prepend_changes(other).should == expected
+
+      changes.prepend_changes!(other)
+      changes.should == expected
+    end
+
+    it 'is reversible' do
+      expected = {'first_name' => ['Stephen', 'Steve']}
+
+      changes.reverse_changes.should == expected
+
+      changes.reverse_changes!
+      changes.should == expected
+    end
+  end
+
+  context 'the changes between two versions' do
+    let(:name){ 'Steve Richert' }
+    let(:user){ User.create(:name => name) }          # 1
+    let(:version){ user.version }
+
+    before do
+      user.update_attribute(:last_name, 'Jobs')       # 2
+      user.update_attribute(:first_name, 'Stephen')   # 3
+      user.update_attribute(:last_name, 'Richert')    # 4
+      user.update_attribute(:name, name)              # 5
+    end
+
+    it 'is a hash' do
+      1.upto(version) do |i|
+        1.upto(version) do |j|
+          user.changes_between(i, j).should be_a(Hash)
+        end
+      end
+    end
+
+    it 'has string keys' do
+      1.upto(version) do |i|
+        1.upto(version) do |j|
+          user.changes_between(i, j).keys.each{ |key| key.should be_a(String) }
+        end
+      end
+    end
+
+    it 'has two-element arrays with unique values' do
+      1.upto(version) do |i|
+        1.upto(version) do |j|
+          user.changes_between(i, j).values.each do |value|
+            value.should be_a(Array)
+            value.size.should == 2
+            value.uniq.should == value
+          end
+        end
+      end
+    end
+
+    it 'is empty between identical versions' do
+      user.changes_between(1, version).should be_empty
+      user.changes_between(version, 1).should be_empty
+    end
+
+    it 'is should reverse with direction' do
+      1.upto(version) do |i|
+        i.upto(version) do |j|
+          up    = user.changes_between(i, j)
+          down  = user.changes_between(j, i)
+          up.should == down.reverse_changes
+        end
+      end
+    end
+
+    it 'is empty with invalid arguments' do
+      1.upto(version) do |i|
+        user.changes_between(i, nil).should be_blank
+        user.changes_between(nil, i).should be_blank
+      end
+    end
+  end
+end

data/spec/vestal_versions/conditions_spec.rb

@@ -0,0 +1,103 @@
+require 'spec_helper'
+
+describe VestalVersions::Conditions do
+  shared_examples_for 'a conditional option' do |option|
+    before do
+      User.class_eval do
+        def true; true; end
+      end
+    end
+
+    it 'is an array' do
+      User.vestal_versions_options[option].should be_a(Array)
+      User.prepare_versioned_options(option => :true)
+      User.vestal_versions_options[option].should be_a(Array)
+    end
+
+    it 'has proc values' do
+      User.prepare_versioned_options(option => :true)
+      User.vestal_versions_options[option].each{|i| i.should be_a(Proc) }
+    end
+  end
+
+  it_should_behave_like 'a conditional option', :if
+  it_should_behave_like 'a conditional option', :unless
+
+  context 'a new version' do
+    subject{ User.create(:name => 'Steve Richert') }
+    let(:count){ subject.versions.count }
+
+    before do
+      User.class_eval do
+        def true; true; end
+        def false; false; end
+      end
+      count # memoize this value
+    end
+
+    after do
+      User.prepare_versioned_options(:if => [], :unless => [])
+    end
+
+    context 'with :if conditions' do
+      context 'that pass' do
+        before do
+          User.prepare_versioned_options(:if => [:true])
+          subject.update_attribute(:last_name, 'Jobs')
+        end
+
+        its('versions.count'){ should == count + 1 }
+      end
+
+      context 'that fail' do
+        before do
+          User.prepare_versioned_options(:if => [:false])
+          subject.update_attribute(:last_name, 'Jobs')
+        end
+
+        its('versions.count'){ should == count }
+      end
+    end
+
+    context 'with :unless conditions' do
+      context 'that pass' do
+        before do
+          User.prepare_versioned_options(:unless => [:true])
+          subject.update_attribute(:last_name, 'Jobs')
+        end
+
+        its('versions.count'){ should == count }
+      end
+
+      context 'that fail' do
+        before do
+          User.prepare_versioned_options(:unless => [:false])
+          subject.update_attribute(:last_name, 'Jobs')
+        end
+
+        its('versions.count'){ should == count + 1 }
+      end
+    end
+
+    context 'with :if and :unless conditions' do
+      context 'that pass' do
+        before do
+          User.prepare_versioned_options(:if => [:true], :unless => [:true])
+          subject.update_attribute(:last_name, 'Jobs')
+        end
+
+        its('versions.count'){ should == count }
+      end
+
+      context 'that fail' do
+        before do
+          User.prepare_versioned_options(:if => [:false], :unless => [:false])
+          subject.update_attribute(:last_name, 'Jobs')
+        end
+
+        its('versions.count'){ should == count }
+      end
+    end
+
+  end
+end

data/spec/vestal_versions/control_spec.rb

@@ -0,0 +1,120 @@
+require 'spec_helper'
+
+describe VestalVersions::Control do
+  let(:user){ User.create(:name => 'Steve Richert') }
+  let(:other_user){ User.create(:name => 'Michael Rossin') }
+  before do
+    @count = user.versions.count
+  end
+
+  shared_examples_for 'a version preserver' do |method|
+    it 'creates one version with a model update' do
+      user.send(method){ user.update_attribute(:last_name, 'Jobs') }
+
+      user.versions.count.should == @count
+    end
+
+    it 'creates one version with multiple model updates' do
+      user.send(method) do
+        user.update_attribute(:first_name, 'Stephen')
+        user.update_attribute(:last_name, 'Jobs')
+        user.update_attribute(:first_name, 'Steve')
+      end
+
+      user.versions.count.should == @count
+    end
+
+  end
+
+  shared_examples_for 'a version incrementer' do |method|
+    it 'creates one version with a model update' do
+      user.send(method){ user.update_attribute(:last_name, 'Jobs') }
+
+      user.versions.count.should == @count + 1
+    end
+
+    it 'creates one version with multiple model updates' do
+      user.send(method) do
+        user.update_attribute(:first_name, 'Stephen')
+        user.update_attribute(:last_name, 'Jobs')
+        user.update_attribute(:first_name, 'Steve')
+      end
+
+      user.versions.count.should == @count + 1
+    end
+
+  end
+
+  it_should_behave_like 'a version preserver', :skip_version
+  it_should_behave_like 'a version incrementer', :merge_version
+
+  context "when operating on the class level" do
+    before do
+      @count = user.versions.count
+      @other_user_count = other_user.versions.count
+    end
+    it 'skip_version doesn\' create versions on multiple models' do
+      other_user_count = other_user.versions.count
+
+      User.skip_version do
+        user.update_attribute(:first_name, 'Stephen')
+        user.update_attribute(:last_name, 'Jobs')
+        user.update_attribute(:first_name, 'Steve')
+
+        other_user.update_attribute(:first_name, 'Stephen')
+        other_user.update_attribute(:last_name, 'Jobs')
+        other_user.update_attribute(:first_name, 'Steve')
+      end
+      user.versions.count.should == @count
+      other_user.versions.count.should == @other_user_count
+    end
+
+  end
+
+  context 'within a append_version block' do
+
+    context 'when no versions exist' do
+      it_should_behave_like 'a version incrementer', :append_version
+    end
+
+    context 'when versions exist' do
+      let(:last_version){ user.versions.last }
+
+      before do
+        user.update_attribute(:last_name, 'Jobs')
+        user.update_attribute(:last_name, 'Richert')
+
+        @count = user.versions.count
+      end
+
+      it_should_behave_like 'a version preserver', :append_version
+
+      it "updates the last version with one update" do
+        original_id = last_version.id
+        original_attrs = last_version.attributes
+
+        user.append_version{ user.update_attribute(:last_name, 'Jobs') }
+
+        other_last_version = user.versions(true).last
+        other_last_version.id.should == original_id
+        other_last_version.attributes.should_not == original_attrs
+      end
+
+      it "updates the last version with multiple updates" do
+        original_id = last_version.id
+        original_attrs = last_version.attributes
+
+        user.append_version do
+          user.update_attribute(:first_name, 'Stephen')
+          user.update_attribute(:last_name, 'Jobs')
+          user.update_attribute(:first_name, 'Steve')
+        end
+
+        other_last_version = user.versions(true).last
+        other_last_version.id.should == original_id
+        other_last_version.attributes.should_not == original_attrs
+      end
+
+    end
+  end
+end