historical 0.2.1 → 0.2.2

data/lib/historical/class_builder.rb

@@ -0,0 +1,60 @@
+module Historical
+  # Builds the customized classes for a record.
+  class ClassBuilder
+    # @return [Array<Proc>] A list of callbacks to be evaluated on save.
+    # @private
+    attr_accessor :callbacks
+    
+    # @return [Class] A customized subclass of {Models::ModelVersion::Meta}
+    # @private
+    attr_accessor :meta_class
+    
+    # @return [Class] A customized subclass of {Models::ModelVersion::Diff}
+    # @private
+    attr_accessor :diff_class
+    
+    # @return [Class] A customized subclass of {Models::ModelVersion}
+    # @private
+    attr_accessor :version_class
+    
+    # @param base The record on which the customized classes should be based on
+    def initialize(base)
+      self.callbacks = []
+      
+      self.version_class  = Historical::Models::ModelVersion.for_class(base)
+      self.diff_class     = Historical::Models::ModelVersion::Diff.for_class(base)
+      self.meta_class     = Historical::Models::ModelVersion::Meta.for_class(base)
+      
+      base.historical_customizations.each do |customization|
+        instance_eval(&customization)
+      end
+    end
+    
+    # @group Builder Methods
+    
+    # Evaluated within class scope of the custom {Models::ModelVersion::Meta} for this record.
+    # The Meta-class includes `MongoMapper::EmbeddedDocument` and {MongoMapperEnhancements}.
+    # @example Usage within is_historical
+    #   is_historical do
+    #     meta do
+    #       key :some_key, String
+    #     end
+    #   end
+    def meta(&block)
+      meta_class.instance_eval(&block)
+    end
+    
+    # A callback to be called when a new version is spawned (i.e. model was saved with changes)
+    # @yield [version] Your callback
+    # @yieldparam [Models::ModelVersion] version The new version to be saved
+    # @example Usage within is_historical
+    #   is_historical do
+    #     callback do |version|
+    #       version.meta.some_key = "foo"
+    #     end
+    #   end
+    def callback(&block)
+      self.callbacks << block
+    end
+  end
+end

data/lib/historical/model_history.rb

@@ -1,22 +1,41 @@
 module Historical
   class ModelHistory
-    attr_reader :record
+    attr_reader :record, :base_version
     
     def initialize(record)
       @record = record
-      @base_version = record.historical_version
-      @base_version ||= -1 if record.new_record?
-      @base_version ||= versions.count - 1
+      
+      if record.historical_version
+        @base_version = record.historical_version
+      elsif record.new_record?
+        @base_version = -1
+      else
+        version_count = versions.count
+        
+        if version_count.zero?
+          spawn_creation!
+          version_count = 1
+        end
+        
+        @base_version = version_count - 1
+      end
+    end
+    
+    def destroy
+      versions.remove
+      record.invalidate_history! if record.history == self
     end
   
     def versions
-      Models::ModelVersion.for_record(record).sort(:created_at.asc, :id.asc)
+      Models::ModelVersion.for_record(record).sort(:"meta.created_at".asc, :_id.asc)
     end
     
+    delegate :version_index, :to => :own_version
+    
     def own_version
-      own = versions.skip(@base_version).limit(1).first
-      raise "couldn't find myself (base_version: #{@base_version}, versions: #{versions.count})" unless own
-      own
+      versions.skip(@base_version).limit(1).first.tap do |own|
+        raise "couldn't find myself (base_version: #{@base_version}, versions: #{versions.count})" unless own
+      end
     end
     
     def previous_version
@@ -57,36 +76,23 @@ module Historical
       end
     end
     
-    def restore(version_query)
-      version = version_by_query(version_query)
-      
-      raise ::ActiveRecord::RecordNotFound, "version does not exist" unless version
-      
-      record.clone.tap do |r|
-        r.id = record.id
-        
-        r.class.columns.each do |c|
-          attr = c.name.to_sym
-          next if Historical::IGNORED_ATTRIBUTES.include? attr
-          
-          r[attr] = version.send(attr)
-        end
-        
-        r.historical_version = version.version_index
-        r.clear_association_cache
-      end
+    def restore(query)
+      version = version_by_query(query)
+      raise ::ActiveRecord::RecordNotFound, "version (base_version: #{base_version}, query: #{query}) does not exist" unless version
+      version.restore(record)
     end
     
-    def restore_with_protection(*args)
-      restore_without_protection(*args).tap do |r|
-        r.readonly!
-      end
+    %w(original latest previous next).each do |k|
+      alias_method k, "#{k}_version"
     end
     
-    alias_method_chain :restore, :protection
+    protected
     
-    %w(original latest previous next).each do |k|
-      alias_method k, "#{k}_version"
+    def spawn_creation!
+      record.send(:spawn_version, :create).tap do |e|
+        e.created_at = record.created_at
+        e.save!
+      end
     end
   end
 end

data/lib/historical/models/attribute_diff.rb

@@ -1,16 +1,31 @@
 module Historical::Models
+  # The diff of an attribute (specialized by a type qualifier)
   class AttributeDiff
+    # MongoMappers supported native Ruby types
+    SUPPORTED_NATIVE_RUBY_TYPES = %w{Date String Time Boolean Integer Float Binary}
+    
     include MongoMapper::EmbeddedDocument
     extend Historical::MongoMapperEnhancements
   
+    # class identifier
+    # @private
     key :_type,           String
     
+    # @return [String] The attribute name
     key :attribute,       String, :required => true
+    
+    # @return [String] The attribute type (string, integer, float)
     key :attribute_type,  String, :required => true
     
+    # @return The old value
+    # @private
     key :_old_value,      Object
+    
+    # @return The new value
+    # @private
     key :_new_value,      Object
   
+    # @return [ModelVersion::Diff] The parent diff model.
     attr_accessor :parent
   
     alias_method :old_value, :_old_value
@@ -18,28 +33,22 @@ module Historical::Models
 
     protected :_old_value=, :_new_value=, :_old_value, :_new_value
     
+    # @return [Class] The specialized {AttributeDiff} class for a attribute type
+    # @private
     def self.specialized_for(parent, attribute)
       type = detect_attribute_type(parent, attribute)
       Historical::Models.const_get(specialized_class_name(type))
     end
-    
-    def self.specialized_class_name(type)
-      ruby_type = Historical::ActiveRecord.sql_to_type(type)
-      "#{ruby_type}#{simple_name}"
-    end
-    
-    def self.simple_name
-      name.to_s.demodulize
-    end
   
     def old_value=(value)
-      self._old_value = cast_value(value)
+      self._old_value = value
     end
   
     def new_value=(value)
-      self._new_value = cast_value(value)
+      self._new_value = value
     end
   
+    # Get attribute type for an attribute
     def self.detect_attribute_type(parent, attribute)
       model_class = parent.record.class
       
@@ -50,21 +59,42 @@ module Historical::Models
       column ? column.type.to_s : nil
     end
     
+    # Generates subclasses of {AttributeDiff} for each type in {SUPPORTED_NATIVE_RUBY_TYPES}
+    # @private
+    def self.generate_subclasses!
+      SUPPORTED_NATIVE_RUBY_TYPES.each do |type|
+        diff_class = Class.new(self)
+        type_class = type.constantize
+
+        diff_class.send :key, :_old_value, type_class
+        diff_class.send :key, :_new_value, type_class
+
+        const_name = specialized_class_name(type_class)
+        namespace = Historical::Models
+        
+        namespace.send(:remove_const, const_name) if namespace.const_defined?(const_name)
+        namespace.const_set(const_name, diff_class)
+      end
+    end
+    
     protected
     
-    def cast_value(value)
-      value
+    # A unique subclass name for the type diffs.
+    # @private
+    def self.specialized_class_name(type)
+      ruby_type = case type
+        when Class
+          type.name
+        else
+          Historical::ActiveRecord.sql_to_type(type)
+      end
+      "#{ruby_type}#{simple_name}"
     end
-  end
-  
-  %w{Date String Time Boolean Integer Float Binary}.each do |type|
-    superclass = AttributeDiff
-    diff_class = Class.new(superclass)
-    type_class = type.constantize
-    
-    diff_class.send :key, :_old_value, type_class
-    diff_class.send :key, :_new_value, type_class
     
-    self.const_set "#{type}#{superclass.simple_name}", diff_class
+    # @return [String] Pure classname without modules
+    # @private
+    def self.simple_name
+      name.to_s.demodulize
+    end
   end
 end

data/lib/historical/models/model_version.rb

@@ -1,44 +1,95 @@
-module Historical::Models  
+module Historical::Models
+  # A complete snapshot of a model.
   class ModelVersion
+    autoload :Diff, 'historical/models/model_version/diff'
+    autoload :Meta, 'historical/models/model_version/meta'
+    
     include MongoMapper::Document
     extend Historical::MongoMapperEnhancements
     
     validate :validate_diff
+    validate :validate_meta
+    
+    validates_presence_of :meta
 
     key :_type,           String
     
     belongs_to_active_record :_record, :polymorphic => true, :required => true
+
+    # The diff between the current and the previous version (if exists)
+    # @return [Diff]
+    one :diff, :class_name => "Historical::Models::ModelVersion::Diff"
     
-    timestamps!
-  
-    one :diff, :class_name => "Historical::Models::ModelDiff"
+    # The meta-data associated with the diff (i.e. this version)
+    # @return [Meta]
+    one :meta, :class_name => "Historical::Models::ModelVersion::Meta"
+    
+    before_save :update_timestamps
     
     alias_method :record, :_record
   
+    # All other versions of the associated record
     def siblings
       self.class.for_record(_record_id, _record_type)
     end
   
+    # All the previous versions (immediate predecessor first)
     def previous_versions
-      (new? ? siblings : siblings.where(:created_at.lte => created_at, :_id.lt => _id)).sort(:created_at.desc)
+      (new? ? siblings : siblings.where(:"meta.created_at".lte => created_at, :_id.lt => _id)).sort(:"meta.created_at".desc, :_id.desc)
     end
   
+    # The immediate predecessor version
     def previous
       previous_versions.first
     end
   
+    # All the next versions (immediate successor first)
     def next_versions
-      siblings.where(:created_at.gte => created_at, :_id.gt => _id).sort(:created_at.asc)
+      siblings.where(:"meta.created_at".gte => created_at, :_id.gt => _id).sort(:"meta.created_at".asc, :_id.asc)
     end
   
+    # The immediate successor version
     def next
       next_versions.first
     end
     
+    # The current version index (zero-based)
     def version_index
       previous_versions.count
     end
     
+    # Restores the current version.
+    # @param base A reference to the record (to reduce DB queries)
+    def restore(base = nil)
+      base ||= record
+      
+      base.clone.tap do |r|
+        r.class.columns.each do |c|
+          attr = c.name.to_sym
+          next if Historical::IGNORED_ATTRIBUTES.include? attr
+          
+          r[attr] = send(attr)
+        end
+        
+        r.id = base.id
+        r.historical_version = version_index
+        r.clear_association_cache
+        r.invalidate_history!
+      end
+    end
+    
+    # Prevents the restored version from being saved or modifed.
+    def restore_with_protection(*args)
+      restore_without_protection(*args).tap do |r|
+        r.readonly!
+      end
+    end
+    
+    alias_method_chain :restore, :protection
+    
+    # Return all versions for the provided record
+    # @param record_or_id [Record,Integer] The id of the record (or a record - then type can be left nil)
+    # @param type [String] The type of the record
     def self.for_record(record_or_id, type = nil)
       if type
         ModelVersion.where(:_record_id => record_or_id, :_record_type => type)
@@ -47,6 +98,7 @@ module Historical::Models
       end
     end
     
+    # Retrieve customized class definition for a record class (e.g. TopicVersion, MessageVersion)
     def self.for_class(source_class)
       Historical::Models::Pool.pooled(Historical::Models::Pool.pooled_name(source_class, self)) do
         Class.new(self).tap do |cls|
@@ -61,10 +113,26 @@ module Historical::Models
     
     protected
     
+    # Sets the created_at timestamp in the meta model
+    def update_timestamps
+      if new? and !meta.created_at?
+        now = Time.now.utc
+        meta[:created_at] = now
+      end
+    end
+    
+    # Cascading validation for `diff`
     def validate_diff
       if diff.present? and !diff.valid?
         errors.add(:diff, "not valid")
       end
     end
+    
+    # Cascading validation for `meta`
+    def validate_meta
+      if meta.present? and !meta.valid?
+        errors.add(:meta, "not valid")
+      end
+    end
   end
 end

data/lib/historical/models/model_version/diff.rb

@@ -0,0 +1,90 @@
+module Historical::Models
+  class ModelVersion
+    # Contains the differences between the current and the previous version.
+    class Diff
+      include MongoMapper::EmbeddedDocument
+      extend Historical::MongoMapperEnhancements
+
+      validates_associated :changes
+
+      key   :_type,       String
+      key   :diff_type,   String,   :required => true
+      
+      # @return [Array<Historical::Models::AttributeDiff>]
+      many  :changes,     :class_name => "Historical::Models::AttributeDiff"
+    
+      delegate :creation?, :update?, :to => :diff_type_inquirer
+  
+      # The record the diff was applied on
+      def record
+        new_version.record
+      end
+      
+      # The version after the diff was applied
+      def new_version
+        @parent || _parent_document
+      end
+  
+      # The version before the diff was applied
+      def old_version
+        new_version.previous
+      end
+
+      # Generates a diff from two versions.
+      # @private
+      def self.from_versions(from, to)
+        return from_creation(to) if !from
+      
+        generate_from_version(from, 'update').tap do |d|
+          from.record.attribute_names.each do |attr_name|
+            attr = attr_name.to_sym
+            next if Historical::IGNORED_ATTRIBUTES.include? attr
+    
+            old_value, new_value = from[attr], to[attr]
+         
+            Historical::Models::AttributeDiff.specialized_for(d, attr).new.tap do |ad|
+              ad.attribute_type = Historical::Models::AttributeDiff.detect_attribute_type(d, attr)
+              ad.parent = d
+              ad.old_value = old_value
+              ad.new_value = new_value
+              ad.attribute = attr.to_s
+              d.changes << ad
+            end if old_value != new_value
+          end
+        end
+      end
+
+      # Generates a creation diff
+      # @private
+      def self.from_creation(to)
+        generate_from_version(to)
+      end
+  
+      protected
+    
+      # Helper to allow diff_type.create? and diff_type.update?
+      # @private
+      def diff_type_inquirer
+        ActiveSupport::StringInquirer.new(diff_type)
+      end
+  
+      # Generates a basic Diff instance
+      # @private
+      def self.generate_from_version(version, type = 'creation')
+        for_class(version.record.class).new.tap do |d|
+          d.diff_type   = type
+          d.instance_variable_set :@parent, version
+        end
+      end
+    
+      # Retrieve customized class definition for a record class (e.g. TopicDiff, MessageDiff)
+      # @return [Class]
+      # @private
+      def self.for_class(source_class)
+        Historical::Models::Pool.pooled(Historical::Models::Pool.pooled_name(source_class, self)) do
+          Class.new(self)
+        end
+      end
+    end
+  end
+end