chrono_model 0.4.0 → 0.5.0.beta

data/lib/chrono_model/time_machine.rb

@@ -12,12 +12,25 @@ module ChronoModel
       end
 
       if table_exists? && !chrono?
-        raise Error, "#{table_name} is not a temporal table. " \
+        puts "WARNING: #{table_name} is not a temporal table. " \
           "Please use change_table :#{table_name}, :temporal => true"
       end
 
       history = TimeMachine.define_history_model_for(self)
       TimeMachine.chrono_models[table_name] = history
+
+      # STI support. TODO: more thorough testing
+      #
+      def self.inherited(subclass)
+        super
+
+        # Do not smash stack: as the below method is defining a
+        # new anonymous class, without this check this leads to
+        # infinite recursion.
+        unless subclass.name.nil?
+          TimeMachine.define_inherited_history_model_for(subclass)
+        end
+      end
     end
 
     # Returns an Hash keyed by table name of ChronoModels
@@ -55,63 +68,84 @@ module ChronoModel
           self.primary_key = old
         end
 
-        # SCD Type 2 validity from timestamp
+        # Returns the previous history entry, or nil if this
+        # is the first one.
         #
-        def valid_from
-          utc_timestamp_from('valid_from')
+        def pred
+          return nil if self.valid_from.year.zero?
+
+          if self.class.timeline_associations.empty?
+            self.class.where(:id => rid, :valid_to => valid_from_before_type_cast).first
+          else
+            super(:id => rid, :before => valid_from)
+          end
         end
 
-        # SCD Type 2 validity to timestamp
+        # Returns the next history entry, or nil if this is the
+        # last one.
         #
-        def valid_to
-          utc_timestamp_from('valid_to')
+        def succ
+          return nil if self.valid_to.year == 9999
+
+          if self.class.timeline_associations.empty?
+            self.class.where(:id => rid, :valid_from => valid_to_before_type_cast).first
+          else
+            super(:id => rid, :after => valid_to)
+          end
         end
+        alias :next :succ
 
-        # History recording timestamp
+        # Returns the first history entry
         #
-        def recorded_at
-          utc_timestamp_from('recorded_at')
+        def first
+          self.class.where(:id => rid).order(:valid_from).first
         end
 
-        # Virtual attribute used to pass around the
-        # current timestamp in association queries
+        # Returns the last history entry
         #
-        def as_of_time
-          Conversions.string_to_utc_time attributes['as_of_time']
+        def last
+          self.class.where(:id => rid).order(:valid_from).last
         end
 
-        # Inhibit destroy of historical records
+        # Returns this history entry's current record
         #
-        def destroy
-          raise ActiveRecord::ReadOnlyRecord, 'Cannot delete historical records'
+        def record
+          self.class.superclass.find(rid)
         end
-
-        private
-          # Hack around AR timezone support. These timestamps are recorded
-          # by the chrono rewrite rules in UTC, but AR reads them as they
-          # were stored in the local timezone - thus here we reset its
-          # assumption. TODO: OPTIMIZE.
-          #
-          if ActiveRecord::Base.default_timezone != :utc
-            def utc_timestamp_from(attr)
-              attributes[attr].utc + Time.now.utc_offset
-            end
-          else
-            def utc_timestamp_from(attr)
-              attributes[attr]
-            end
-          end
       end
 
       model.singleton_class.instance_eval do
         define_method(:history) { history }
       end
 
+      history.singleton_class.instance_eval do
+        define_method(:sti_name) { model.sti_name }
+      end
+
       model.const_set :History, history
 
       return history
     end
 
+    def self.define_inherited_history_model_for(subclass)
+      # Define history model for the subclass
+      history = Class.new(subclass.superclass.history)
+      history.table_name = subclass.superclass.history.table_name
+
+      # Override the STI name on the history subclass
+      history.singleton_class.instance_eval do
+        define_method(:sti_name) { subclass.sti_name }
+      end
+
+      # Return the subclass history via the .history method
+      subclass.singleton_class.instance_eval do
+        define_method(:history) { history }
+      end
+
+      # Define the History constant inside the subclass
+      subclass.const_set :History, history
+    end
+
     # Returns a read-only representation of this record as it was +time+ ago.
     #
     def as_of(time)
@@ -127,18 +161,108 @@ module ChronoModel
     # Returns an Array of timestamps for which this instance has an history
     # record. Takes temporal associations into account.
     #
-    def history_timestamps
-      self.class.history.timestamps do |query|
-        query.where(:id => self)
-      end
+    def timeline(options = {})
+      self.class.history.timeline(self, options)
     end
 
+    # Returns a boolean indicating whether this record is an history entry.
+    #
     def historical?
-      self.kind_of? self.class.history
+      self.attributes.key?('as_of_time') || self.kind_of?(self.class.history)
+    end
+
+    # Hack around AR timezone support. These timestamps are recorded
+    # by the chrono rewrite rules in UTC, but AR reads them as they
+    # were stored in the local timezone - thus here we bypass type
+    # casting to force creation of UTC timestamps.
+    #
+    %w( valid_from valid_to recorded_at as_of_time ).each do |attr|
+      define_method(attr) do
+        Conversions.string_to_utc_time attributes_before_type_cast[attr]
+      end
+    end
+
+    # Inhibit destroy of historical records
+    #
+    def destroy
+      raise ActiveRecord::ReadOnlyRecord, 'Cannot delete historical records' if historical?
+      super
     end
 
-    def attributes(*)
-      super.tap {|x| x.delete('__xid')}
+    # Returns the previous record in the history, or nil if this is the only
+    # recorded entry.
+    #
+    def pred(options = {})
+      if self.class.timeline_associations.empty?
+        history.order('valid_to DESC').offset(1).first
+      else
+        return nil unless (ts = pred_timestamp(options))
+        self.class.as_of(ts).order('hid desc').find(options[:id] || id)
+      end
+    end
+
+    # Returns the previous timestamp in this record's timeline. Includes
+    # temporal associations.
+    #
+    def pred_timestamp(options = {})
+      if historical?
+        options[:before] ||= as_of_time
+        timeline(options.merge(:limit => 1, :reverse => true)).first
+      else
+        timeline(options.merge(:limit => 2, :reverse => true)).second
+      end
+    end
+
+    # Returns the next record in the history timeline.
+    #
+    def succ(options = {})
+      unless self.class.timeline_associations.empty?
+        return nil unless (ts = succ_timestamp(options))
+        self.class.as_of(ts).order('hid desc').find(options[:id] || id)
+      end
+    end
+
+    # Returns the next timestamp in this record's timeline. Includes temporal
+    # associations.
+    #
+    def succ_timestamp(options = {})
+      return nil unless historical?
+
+      options[:after] ||= as_of_time
+      timeline(options.merge(:limit => 1, :reverse => false)).first
+    end
+
+    # Returns the differences between this entry and the previous history one.
+    # See: +changes_against+.
+    #
+    def last_changes
+      pred = self.pred
+      changes_against(pred) if pred
+    end
+
+    # Returns the differences between this record and an arbitrary reference
+    # record. The changes representation is an hash keyed by attribute whose
+    # values are arrays containing previous and current attributes values -
+    # the same format used by ActiveModel::Dirty.
+    #
+    def changes_against(ref)
+      self.class.attribute_names_for_history_changes.inject({}) do |changes, attr|
+        old, new = ref.public_send(attr), self.public_send(attr)
+
+        changes.tap do |c|
+          changed = old.respond_to?(:history_eql?) ?
+            !old.history_eql?(new) : old != new
+
+          c[attr] = [old, new] if changed
+        end
+      end
+    end
+
+    # Wraps AR::Base#attributes by removing the __xid internal attribute
+    # used to squash together changes made in the same transaction.
+    #
+    %w( attributes attribute_names ).each do |name|
+      define_method(name) { super().tap {|x| x.delete('__xid')} }
     end
 
     module ClassMethods
@@ -147,30 +271,92 @@ module ChronoModel
       def as_of(time)
         history.as_of(time, current_scope)
       end
+
+      def attribute_names_for_history_changes
+        @attribute_names_for_history_changes ||= attribute_names -
+          %w( id hid valid_from valid_to recorded_at as_of_time )
+      end
+
+      def has_timeline(options)
+        changes = options.delete(:changes)
+        assocs  = history.has_timeline(options)
+
+        attributes = changes.present? ?
+          Array.wrap(changes) : assocs.map(&:name)
+
+        attribute_names_for_history_changes.concat(attributes.map(&:to_s))
+      end
+
+      delegate :timeline_associations, :to => :history
+    end
+
+    module TimeQuery
+      OPERATORS = {
+        :at      => '&&',
+        :before  => '<<',
+        :after   => '>>',
+      }.freeze
+
+      def time_query(match, time_or_times, options)
+        from_f, to_f = options[:on]
+
+        from_t, to_t = if time_or_times.kind_of?(Array)
+          time_or_times.map! {|t| time_for_time_query(t)}
+        else
+          [time_for_time_query(time_or_times)]*2
+        end
+
+        if match == :not
+          where(%[
+            #{build_time_query(:before, from_t, from_f, to_t, to_f)} OR
+            #{build_time_query(:after,  from_t, from_f, to_t, to_f)}
+          ])
+        else
+          where(build_time_query(match, from_t, from_f, to_t, to_f))
+        end
+      end
+
+      private
+        def time_for_time_query(t)
+          t = Conversions.time_to_utc_string(t.utc) if t.kind_of?(Time)
+          t == :now ? 'now()' : "#{connection.quote(t)}::timestamp"
+        end
+
+        def build_time_query(match, from_t, from_f, to_t, to_f)
+          %[
+            box(
+              point( date_part( 'epoch', #{from_f} ), 0 ),
+              point( date_part( 'epoch', #{to_f  } ), 0 )
+            ) #{OPERATORS.fetch(match)}
+            box(
+              point( date_part( 'epoch', #{from_t} ), 0 ),
+              point( date_part( 'epoch', #{to_t  } ), 0 )
+            )
+          ]
+        end
     end
 
     # Methods that make up the history interface of the companion History
-    # model build on each Model that includes TimeMachine
+    # model, automatically built for each Model that includes TimeMachine
     module HistoryMethods
+      include TimeQuery
+
       # Fetches as of +time+ records.
       #
       def as_of(time, scope = nil)
-        time = Conversions.time_to_utc_string(time.utc) if time.kind_of? Time
-
-        as_of = superclass.unscoped.readonly.
-          with(superclass.table_name, at(time))
+        as_of = superclass.unscoped.readonly.from(virtual_table_at(time))
 
         # Add default scopes back if we're passed nil or a
         # specific scope, because we're .unscopeing above.
         #
-        scopes = scope.present? ? [scope] : (
+        scopes = !scope.nil? ? [scope] : (
           superclass.default_scopes.map do |s|
             s.respond_to?(:call) ? s.call : s
           end)
 
-        scopes.each do |scope|
-          scope.order_values.each {|clause| as_of = as_of.order(clause.to_sql)}
-          scope.where_values.each {|clause| as_of = as_of.where(clause.to_sql)}
+        scopes.each do |s|
+          s.order_values.each {|clause| as_of = as_of.order(clause)}
+          s.where_values.each {|clause| as_of = as_of.where(clause)}
         end
 
         as_of.instance_variable_set(:@temporal, time)
@@ -178,60 +364,133 @@ module ChronoModel
         return as_of
       end
 
+      def virtual_table_at(time, name = nil)
+        name = name ? connection.quote_table_name(name) :
+          superclass.quoted_table_name
+
+        "(#{at(time).to_sql}) #{name}"
+      end
+
       # Fetches history record at the given time
       #
       def at(time)
-        from, to = quoted_history_fields
+        time = Conversions.time_to_utc_string(time.utc) if time.kind_of?(Time)
+
         unscoped.
-          select("#{quoted_table_name}.*, '#{time}' AS as_of_time").
-          where("'#{time}' >= #{from} AND '#{time}' < #{to}")
+          select("#{quoted_table_name}.*, #{connection.quote(time)} AS as_of_time").
+          time_query(:at, time, :on => quoted_history_fields)
       end
 
       # Returns the whole history as read only.
       #
       def all
         readonly.
-          order("#{table_name}.recorded_at, hid").all
+          order("#{quoted_table_name}.recorded_at, hid").all
       end
 
-      # Fetches the given +object+ history, sorted by history record time.
+      # Fetches the given +object+ history, sorted by history record time
+      # by default. Always includes an "as_of_time" column that is either
+      # the valid_to timestamp or now() if history validity is maximum.
       #
       def of(object)
-        now = 'LEAST(valid_to, now()::timestamp)'
-        readonly.
-          select("#{table_name}.*, #{now} AS as_of_time").
-          order("#{table_name}.recorded_at, hid").
-          where(:id => object)
+        readonly.where(:id => object).extend(HistorySelect)
       end
 
+      module HistorySelect #:nodoc:
+        Aggregates = %r{(?:(?:bit|bool)_(?:and|or)|(?:array_|string_|xml)agg|count|every|m(?:in|ax)|sum|stddev|var(?:_pop|_samp|iance)|corr|covar_|regr_)\w*\s*\(}i
 
-      # Returns an Array of unique UTC timestamps for which at least an
-      # history record exists. Takes temporal associations into account.
-      #
-      def timestamps
-        assocs = reflect_on_all_associations.select {|a|
-          [:belongs_to, :has_one, :has_many].include?(a.macro) && a.klass.chrono?
-        }
+        def build_arel
+          has_aggregate = select_values.any? do |v|
+            v.kind_of?(Arel::Nodes::Function) || # FIXME this is a bit ugly.
+            v.to_s =~ Aggregates
+          end
+
+          return super if has_aggregate
+
+          if order_values.blank?
+            self.order_values += ["#{quoted_table_name}.recorded_at, #{quoted_table_name}.hid"]
+          end
+
+          super.tap do |rel|
+            rel.project("LEAST(valid_to, now()::timestamp) AS as_of_time")
+          end
+        end
+      end
+
+      include(Timeline = Module.new do
+        # Returns an Array of unique UTC timestamps for which at least an
+        # history record exists. Takes temporal associations into account.
+        #
+        def timeline(record = nil, options = {})
+          rid = record.respond_to?(:rid) ? record.rid : record.id if record
+
+          assocs = options.key?(:with) ?
+            timeline_associations_from(options[:with]) : timeline_associations
+
+          models = []
+          models.push self if self.chrono?
+          models.concat(assocs.map {|a| a.klass.history})
+
+          return [] if models.empty?
+
+          fields = models.inject([]) {|a,m| a.concat m.quoted_history_fields}
+          fields.map! {|f| "#{f} + INTERVAL '2 usec'"}
 
-        models = [self].concat(assocs.map {|a| a.klass.history})
-        fields = models.inject([]) {|a,m| a.concat m.quoted_history_fields}
+          relation = self.
+            joins(*assocs.map(&:name)).
+            select("DISTINCT UNNEST(ARRAY[#{fields.join(',')}]) AS ts").
+            order('ts ' << (options[:reverse] ? 'DESC' : 'ASC'))
 
-        relation = self.
-          joins(*assocs.map(&:name)).
-          select("DISTINCT UNNEST(ARRAY[#{fields.join(',')}]) AS ts").
-          order('ts')
+          relation = relation.from(%["public".#{quoted_table_name}]) unless self.chrono?
+          relation = relation.where(:id => rid) if rid
 
-        relation = yield relation if block_given?
+          sql = "SELECT ts FROM ( #{relation.to_sql} ) foo WHERE ts IS NOT NULL"
 
-        sql = "SELECT ts FROM ( #{relation.to_sql} ) foo WHERE ts IS NOT NULL AND ts < NOW()"
-        sql.gsub! 'INNER JOIN', 'LEFT OUTER JOIN'
+          if options.key?(:before)
+            sql << " AND ts < '#{Conversions.time_to_utc_string(options[:before])}'"
+          end
+
+          if options.key?(:after)
+            sql << " AND ts > '#{Conversions.time_to_utc_string(options[:after ])}'"
+          end
 
-        connection.on_schema(Adapter::HISTORY_SCHEMA) do
-          connection.select_values(sql, "#{self.name} periods").map! do |ts|
-            Conversions.string_to_utc_time ts
+          if rid
+            sql << (self.chrono? ? %[
+              AND ts >= ( SELECT MIN(valid_from) FROM #{quoted_table_name} WHERE id = #{rid} )
+              AND ts <  ( SELECT MAX(valid_to  ) FROM #{quoted_table_name} WHERE id = #{rid} )
+            ] : %[ AND ts < NOW() ])
+          end
+
+          sql << " LIMIT #{options[:limit].to_i}" if options.key?(:limit)
+
+          sql.gsub! 'INNER JOIN', 'LEFT OUTER JOIN'
+
+          connection.on_schema(Adapter::HISTORY_SCHEMA) do
+            connection.select_values(sql, "#{self.name} periods").map! do |ts|
+              Conversions.string_to_utc_time ts
+            end
           end
         end
-      end
+
+        def has_timeline(options)
+          options.assert_valid_keys(:with)
+
+          timeline_associations_from(options[:with]).tap do |assocs|
+            timeline_associations.concat assocs
+          end
+        end
+
+        def timeline_associations
+          @timeline_associations ||= []
+        end
+
+        def timeline_associations_from(names)
+          Array.wrap(names).map do |name|
+            reflect_on_association(name) or raise ArgumentError,
+              "No association found for name `#{name}'"
+          end
+        end
+      end)
 
       def quoted_history_fields
         @quoted_history_fields ||= [:valid_from, :valid_to].map do |field|
@@ -246,10 +505,13 @@ module ChronoModel
       def build_arel
         super.tap do |arel|
 
-          # Extract joined tables and add temporal WITH if appropriate
-          arel.join_sources.map {|j| j.to_sql =~ /JOIN "(\w+)" ON/ && $1}.compact.each do |table|
-            next unless (model = TimeMachine.chrono_models[table])
-            with(table, model.history.at(@temporal))
+          arel.join_sources.each do |join|
+            model = TimeMachine.chrono_models[join.left.table_name]
+            next unless model
+
+            join.left = Arel::Nodes::SqlLiteral.new(
+              model.history.virtual_table_at(@temporal, join.left.table_alias || join.left.table_name)
+            )
           end if @temporal
 
         end
@@ -257,45 +519,6 @@ module ChronoModel
     end
     ActiveRecord::Relation.instance_eval { include QueryMethods }
 
-    module Conversions
-      extend self
-
-      ISO_DATETIME = /\A(\d{4})-(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)(\.\d+)?\z/
-
-      def string_to_utc_time(string)
-        if string =~ ISO_DATETIME
-          microsec = ($7.to_f * 1_000_000).to_i
-          Time.utc $1.to_i, $2.to_i, $3.to_i, $4.to_i, $5.to_i, $6.to_i, microsec
-        end
-      end
-
-      def time_to_utc_string(time)
-        [time.to_s(:db), sprintf('%06d', time.usec)].join '.'
-      end
-    end
-
-    module Utilities
-      # Amends the given history item setting a different period.
-      # Useful when migrating from legacy systems, but it is here
-      # as this is not a proper API.
-      #
-      # Extend your model with the Utilities model if you want to
-      # use it.
-      #
-      def amend_history_period!(hid, from, to)
-        unless [from, to].all? {|ts| ts.respond_to?(:zone) && ts.zone == 'UTC'}
-          raise 'Can amend history only with UTC timestamps'
-        end
-
-        connection.execute %[
-          UPDATE #{history_table_name}
-             SET valid_from = #{connection.quote(from)},
-                 valid_to   = #{connection.quote(to  )}
-           WHERE hid = #{hid.to_i}
-        ]
-      end
-    end
-
   end
 
 end

data/lib/chrono_model/utils.rb

@@ -0,0 +1,89 @@
+module ChronoModel
+
+  module Conversions
+    extend self
+
+    ISO_DATETIME = /\A(\d{4})-(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)(\.\d+)?\z/
+
+    def string_to_utc_time(string)
+      if string =~ ISO_DATETIME
+        microsec = ($7.to_f * 1_000_000).to_i
+        Time.utc $1.to_i, $2.to_i, $3.to_i, $4.to_i, $5.to_i, $6.to_i, microsec
+      end
+    end
+
+    def time_to_utc_string(time)
+      [time.to_s(:db), sprintf('%06d', time.usec)].join '.'
+    end
+  end
+
+  module Utilities
+    # Amends the given history item setting a different period.
+    # Useful when migrating from legacy systems, but it is here
+    # as this is not a proper API.
+    #
+    # Extend your model with the Utilities model if you want to
+    # use it.
+    #
+    def amend_period!(hid, from, to)
+      unless [from, to].all? {|ts| ts.respond_to?(:zone) && ts.zone == 'UTC'}
+        raise 'Can amend history only with UTC timestamps'
+      end
+
+      connection.execute %[
+        UPDATE #{quoted_table_name}
+           SET "valid_from" = #{connection.quote(from)},
+               "valid_to"   = #{connection.quote(to  )}
+         WHERE "hid" = #{hid.to_i}
+      ]
+    end
+  end
+
+  module Migrate
+    extend self
+
+    def upgrade_indexes!(base = ActiveRecord::Base)
+      use base
+
+      db.on_schema(Adapter::HISTORY_SCHEMA) do
+        db.tables.each do |table|
+          if db.is_chrono?(table)
+            upgrade_indexes_for(table)
+          end
+        end
+      end
+    end
+
+    private
+      attr_reader :db
+
+      def use(ar)
+        @db = ar.connection
+      end
+
+      def upgrade_indexes_for(table_name)
+        upgradeable =
+          %r{_snapshot$|_valid_(?:from|to)$|_recorded_at$|_instance_(?:update|history)$}
+
+        indexes_sql = %[
+          SELECT DISTINCT i.relname
+          FROM pg_class t
+          INNER JOIN pg_index d ON t.oid = d.indrelid
+          INNER JOIN pg_class i ON d.indexrelid = i.oid
+          WHERE i.relkind = 'i'
+          AND d.indisprimary = 'f'
+          AND t.relname = '#{table_name}'
+          AND i.relnamespace IN (SELECT oid FROM pg_namespace WHERE nspname = ANY(current_schemas(false)) )
+        ]
+
+        db.select_values(indexes_sql).each do |idx|
+          if idx =~ upgradeable
+            db.execute "DROP INDEX #{idx}"
+          end
+        end
+
+        db.send(:chrono_create_history_indexes_for, table_name)
+      end
+  end
+
+end

data/lib/chrono_model/version.rb

@@ -1,3 +1,3 @@
 module ChronoModel
-  VERSION = "0.4.0"
+  VERSION = "0.5.0.beta"
 end