chrono_model 1.0.1 → 1.1.0

data/lib/chrono_model/patches/as_of_time_holder.rb

@@ -0,0 +1,23 @@
+module ChronoModel
+  module Patches
+
+    # Added to classes that need to carry the As-Of date around
+    #
+    module AsOfTimeHolder
+      # Sets the virtual 'as_of_time' attribute to the given time, converting to UTC.
+      #
+      def as_of_time!(time)
+        @_as_of_time = time.utc
+
+        self
+      end
+
+      # Reads the virtual 'as_of_time' attribute
+      #
+      def as_of_time
+        @_as_of_time
+      end
+    end
+
+  end
+end

data/lib/chrono_model/patches/as_of_time_relation.rb

@@ -0,0 +1,19 @@
+module ChronoModel
+  module Patches
+
+    # This class is a dummy relation whose scope is only to pass around the
+    # as_of_time parameters across ActiveRecord call chains.
+    #
+    # With AR 5.2 a simple relation can be used, as the only required argument
+    # is the model. 5.0 and 5.1 require more arguments, that are passed here.
+    #
+    class AsOfTimeRelation < ActiveRecord::Relation
+      if ActiveRecord::VERSION::STRING.to_f < 5.2
+        def initialize(klass, table: klass.arel_table, predicate_builder: klass.predicate_builder, values: {})
+          super(klass, table, predicate_builder, values)
+        end
+      end
+    end
+
+  end
+end

data/lib/chrono_model/patches/association.rb

@@ -0,0 +1,52 @@
+module ChronoModel
+  module Patches
+
+    # Patches ActiveRecord::Associations::Association to add support for
+    # temporal associations.
+    #
+    # Each record fetched from the +as_of+ scope on the owner class will have
+    # an additional "as_of_time" field yielding the UTC time of the request,
+    # then the as_of scope is called on either this association's class or
+    # on the join model's (:through association) one.
+    #
+    module Association
+      def skip_statement_cache?(*)
+        super || _chrono_target?
+      end
+
+      # If the association class or the through association are ChronoModels,
+      # then fetches the records from a virtual table using a subquery scope
+      # to a specific timestamp.
+      def scope
+        scope = super
+        return scope unless _chrono_record?
+
+        if _chrono_target?
+          # For standard associations, replace the table name with the virtual
+          # as-of table name at the owner's as-of-time
+          #
+          scope = scope.from(klass.history.virtual_table_at(owner.as_of_time))
+        end
+
+        scope.as_of_time!(owner.as_of_time)
+
+        return scope
+      end
+
+      private
+        def _chrono_record?
+          owner.respond_to?(:as_of_time) && owner.as_of_time.present?
+        end
+
+        def _chrono_target?
+          @_target_klass ||= reflection.options[:polymorphic] ?
+            owner.public_send(reflection.foreign_type).constantize :
+            reflection.klass
+
+          @_target_klass.chrono?
+        end
+
+    end
+
+  end
+end

data/lib/chrono_model/patches/db_console.rb

@@ -0,0 +1,11 @@
+module ChronoModel
+  module Patches
+
+    module DBConsole
+      def config
+        super.dup.tap {|config| config['adapter'] = 'postgresql/chronomodel' }
+      end
+    end
+
+  end
+end

data/lib/chrono_model/patches/join_node.rb

@@ -0,0 +1,32 @@
+module ChronoModel
+  module Patches
+
+    # This class supports the AR 5.0 code that expects to receive an
+    # Arel::Table as the left join node. We need to replace the node
+    # with a virtual table that fetches from the history at a given
+    # point in time, we replace the join node with a SqlLiteral node
+    # that does not respond to the methods that AR expects.
+    #
+    # This class provides AR with an object implementing the methods
+    # it expects, yet producing SQL that fetches from history tables
+    # as-of-time.
+    #
+    class JoinNode < Arel::Nodes::SqlLiteral
+      attr_reader :name, :table_name, :table_alias, :as_of_time
+
+      def initialize(join_node, history_model, as_of_time)
+        @name        = join_node.table_name
+        @table_name  = join_node.table_name
+        @table_alias = join_node.table_alias
+
+        @as_of_time  = as_of_time
+
+        virtual_table = history_model.
+          virtual_table_at(@as_of_time, @table_alias || @table_name)
+
+        super(virtual_table)
+      end
+    end
+
+  end
+end

data/lib/chrono_model/patches/preloader.rb

@@ -0,0 +1,68 @@
+module ChronoModel
+  module Patches
+
+    # Patches ActiveRecord::Associations::Preloader to add support for
+    # temporal associations. This is tying itself to Rails internals
+    # and it is ugly :-(.
+    #
+    module Preloader
+      attr_reader :options
+
+      # We overwrite the initializer in order to pass the +as_of_time+
+      # parameter above in the build_preloader
+      #
+      def initialize(options = {})
+        @options = options.freeze
+      end
+
+      # Patches the AR Preloader (lib/active_record/associations/preloader.rb)
+      # in order to carry around the +as_of_time+ of the original invocation.
+      #
+      # * The +records+ are the parent records where the association is defined
+      # * The +associations+ are the association names involved in preloading
+      # * The +given_preload_scope+ is the preloading scope, that is used only
+      #   in the :through association and it holds the intermediate records
+      #   _through_ which the final associated records are eventually fetched.
+      #
+      # As the +preload_scope+ is passed around to all the different
+      # incarnations of the preloader strategies, we are using it to pass
+      # around the +as_of_time+ of the original query invocation, so that
+      # preloaded records are preloaded honoring the +as_of_time+.
+      #
+      # The +preload_scope+ is present only in through associations, but the
+      # preloader interfaces expect it to be always defined, for consistency.
+      #
+      # For `:through` associations, the +given_preload_scope+ is already a
+      # +Relation+, that already has the +as_of_time+ getters and setters,
+      # so we use it directly.
+      #
+      def preload(records, associations, given_preload_scope = nil)
+        if options[:as_of_time]
+          preload_scope = given_preload_scope ||
+            ChronoModel::Patches::AsOfTimeRelation.new(options[:model])
+
+          preload_scope.as_of_time!(options[:as_of_time])
+        end
+
+        super records, associations, preload_scope
+      end
+
+      module Association
+        # Builds the preloader scope taking into account a potential
+        # +as_of_time+ passed down the call chain starting at the
+        # end user invocation.
+        #
+        def build_scope
+          scope = super
+
+          if preload_scope.try(:as_of_time)
+            scope = scope.as_of(preload_scope.as_of_time)
+          end
+
+          return scope
+        end
+      end
+    end
+
+  end
+end

data/lib/chrono_model/patches/relation.rb

@@ -0,0 +1,58 @@
+module ChronoModel
+  module Patches
+
+    module Relation
+      include ChronoModel::Patches::AsOfTimeHolder
+
+      def load
+        return super unless @_as_of_time && !loaded?
+
+        super.each {|record| record.as_of_time!(@_as_of_time) }
+      end
+
+      def merge(*)
+        return super unless @_as_of_time
+
+        super.as_of_time!(@_as_of_time)
+      end
+
+      def build_arel(*)
+        return super unless @_as_of_time
+
+        super.tap do |arel|
+
+          arel.join_sources.each do |join|
+            chrono_join_history(join)
+          end
+
+        end
+      end
+
+      # Replaces a join with the current data with another that
+      # loads records As-Of time against the history data.
+      #
+      def chrono_join_history(join)
+        # This case happens with nested includes, where the below
+        # code has already replaced the join.left with a JoinNode.
+        #
+        return if join.left.respond_to?(:as_of_time)
+
+        model = ChronoModel.history_models[join.left.table_name]
+        return unless model
+
+        join.left = ChronoModel::Patches::JoinNode.new(
+          join.left, model.history, @_as_of_time)
+      end
+
+      # Build a preloader at the +as_of_time+ of this relation.
+      # Pass the current model to define Relation
+      #
+      def build_preloader
+        ActiveRecord::Associations::Preloader.new(
+          model: self.model, as_of_time: as_of_time
+        )
+      end
+    end
+
+  end
+end

data/lib/chrono_model/time_gate.rb

@@ -6,18 +6,18 @@ module ChronoModel
   module TimeGate
     extend ActiveSupport::Concern
 
+    include ChronoModel::Patches::AsOfTimeHolder
+
     module ClassMethods
+      include ChronoModel::TimeMachine::Timeline
+
       def as_of(time)
         all.as_of_time!(time)
       end
-
-      include TimeMachine::HistoryMethods::Timeline
     end
 
-    include Patches::AsOfTimeHolder
-
     def as_of(time)
-      self.class.as_of(time).where(:id => self.id).first!
+      self.class.as_of(time).where(id: self.id).first!
     end
 
     def timeline

data/lib/chrono_model/time_machine.rb

@@ -1,11 +1,13 @@
-require 'active_record'
+require 'chrono_model/time_machine/time_query'
+require 'chrono_model/time_machine/timeline'
+require 'chrono_model/time_machine/history_model'
 
 module ChronoModel
 
   module TimeMachine
-    extend ActiveSupport::Concern
+    include ChronoModel::Patches::AsOfTimeHolder
 
-    include Patches::AsOfTimeHolder
+    extend ActiveSupport::Concern
 
     included do
       if table_exists? && !chrono?
@@ -13,8 +15,8 @@ module ChronoModel
           "Please use `change_table :#{table_name}, temporal: true` in a migration."
       end
 
-      history = TimeMachine.define_history_model_for(self)
-      TimeMachine.chrono_models[table_name] = history
+      history = ChronoModel::TimeMachine.define_history_model_for(self)
+      ChronoModel.history_models[table_name] = history
 
       class << self
         alias_method :direct_descendants_with_history, :direct_descendants
@@ -36,130 +38,14 @@ module ChronoModel
           # new anonymous class, without this check this leads to
           # infinite recursion.
           unless subclass.name.nil?
-            TimeMachine.define_inherited_history_model_for(subclass)
+            ChronoModel::TimeMachine.define_inherited_history_model_for(subclass)
           end
         end
       end
     end
 
-    # Returns an Hash keyed by table name of ChronoModels
-    #
-    def self.chrono_models
-      (@chrono_models ||= {})
-    end
-
     def self.define_history_model_for(model)
-      history = Class.new(model) do
-        self.table_name = [Adapter::HISTORY_SCHEMA, model.table_name].join('.')
-
-        extend TimeMachine::HistoryMethods
-
-        scope :chronological, -> { order(Arel.sql('lower(validity) ASC')) }
-
-        # The history id is `hid`, but this cannot set as primary key
-        # or temporal assocations will break. Solutions are welcome.
-        def id
-          hid
-        end
-
-        # Referenced record ID.
-        #
-        def rid
-          attributes[self.class.primary_key]
-        end
-
-        # HACK. find() and save() require the real history ID. So we are
-        # setting it now and ensuring to reset it to the original one after
-        # execution completes.
-        #
-        def self.with_hid_pkey(&block)
-          old = self.primary_key
-          self.primary_key = :hid
-
-          block.call
-        ensure
-          self.primary_key = old
-        end
-
-        def self.find(*)
-          with_hid_pkey { super }
-        end
-
-        def save(*)
-          self.class.with_hid_pkey { super }
-        end
-
-        def save!(*)
-          self.class.with_hid_pkey { super }
-        end
-
-        def update_columns(*)
-          self.class.with_hid_pkey { super }
-        end
-
-        # Returns the previous history entry, or nil if this
-        # is the first one.
-        #
-        def pred
-          return if self.valid_from.nil?
-
-          if self.class.timeline_associations.empty?
-            self.class.where('id = ? AND upper(validity) = ?', rid, valid_from).first
-          else
-            super(:id => rid, :before => valid_from, :table => self.class.superclass.quoted_table_name)
-          end
-        end
-
-        # Returns the next history entry, or nil if this is the
-        # last one.
-        #
-        def succ
-          return if self.valid_to.nil?
-
-          if self.class.timeline_associations.empty?
-            self.class.where('id = ? AND lower(validity) = ?', rid, valid_to).first
-          else
-            super(:id => rid, :after => valid_to, :table => self.class.superclass.quoted_table_name)
-          end
-        end
-        alias :next :succ
-
-        # Returns the first history entry
-        #
-        def first
-          self.class.where(:id => rid).chronological.first
-        end
-
-        # Returns the last history entry
-        #
-        def last
-          self.class.where(:id => rid).chronological.last
-        end
-
-        # Returns this history entry's current record
-        #
-        def current_version
-          self.class.non_history_superclass.find(rid)
-        end
-
-        def record #:nodoc:
-          ActiveSupport::Deprecation.warn '.record is deprecated in favour of .current_version'
-          self.current_version
-        end
-
-        def valid_from
-          validity.first
-        end
-
-        def valid_to
-          validity.last
-        end
-        alias as_of_time valid_to
-
-        def recorded_at
-          Conversions.string_to_utc_time attributes_before_type_cast['recorded_at']
-        end
-      end
+      history = Class.new(model) { include ChronoModel::TimeMachine::HistoryModel }
 
       model.singleton_class.instance_eval do
         define_method(:history) { history }
@@ -203,6 +89,37 @@ module ChronoModel
       end
     end
 
+    module ClassMethods
+      # Identify this class as the parent, non-history, class.
+      #
+      def history?
+        false
+      end
+
+      # Returns an ActiveRecord::Relation on the history of this model as
+      # it was +time+ ago.
+      def as_of(time)
+        history.as_of(time)
+      end
+
+      def attribute_names_for_history_changes
+        @attribute_names_for_history_changes ||= attribute_names -
+          %w( id hid validity recorded_at )
+      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
+
     # Returns a read-only representation of this record as it was +time+ ago.
     # Returns nil if no record is found.
     #
@@ -217,12 +134,12 @@ module ChronoModel
       _as_of(time).first!
     end
 
-    # Delegates to +HistoryMethods.as_of+ to fetch this instance as it was on
-    # +time+. Used both by +as_of+ and +as_of!+ for performance reasons, to
-    # avoid a `rescue` (@lleirborras).
+    # Delegates to +HistoryModel::ClassMethods.as_of+ to fetch this instance
+    # as it was on +time+. Used both by +as_of+ and +as_of!+ for performance
+    # reasons, to avoid a `rescue` (@lleirborras).
     #
     def _as_of(time)
-      self.class.as_of(time).where(:id => self.id)
+      self.class.as_of(time).where(id: self.id)
     end
     protected :_as_of
 
@@ -279,26 +196,10 @@ module ChronoModel
       end
     end
 
-    # Returns the next record in the history timeline.
+    # This is a current record, so its next instance is always nil.
     #
-    def succ(options = {})
-      unless self.class.timeline_associations.empty?
-        return nil unless (ts = succ_timestamp(options))
-
-        order_clause = Arel.sql %[ LOWER(#{options[:table] || self.class.quoted_table_name}."validity"_ DESC ]
-
-        self.class.as_of(ts).order(order_clause).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
+    def succ
+      nil
     end
 
     # Returns the current history version
@@ -333,287 +234,6 @@ module ChronoModel
       end
     end
 
-    module ClassMethods
-      # Identify this class as the parent, non-history, class.
-      #
-      def history?
-        false
-      end
-
-      # Returns an ActiveRecord::Relation on the history of this model as
-      # it was +time+ ago.
-      def as_of(time)
-        history.as_of(time)
-      end
-
-      def attribute_names_for_history_changes
-        @attribute_names_for_history_changes ||= attribute_names -
-          %w( id hid validity recorded_at )
-      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
-      # TODO Documentation
-      #
-      def time_query(match, time, options)
-        range = columns_hash.fetch(options[:on].to_s)
-
-        query = case match
-        when :at
-          build_time_query_at(time, range)
-
-        when :not
-          "NOT (#{build_time_query_at(time, range)})"
-
-        when :before
-          op = options.fetch(:inclusive, true) ? '&&' : '@>'
-          build_time_query(['NULL', time_for_time_query(time, range)], range, op)
-
-        when :after
-          op = options.fetch(:inclusive, true) ? '&&' : '@>'
-          build_time_query([time_for_time_query(time, range), 'NULL'], range, op)
-
-        else
-          raise ArgumentError, "Invalid time_query: #{match}"
-        end
-
-        where(query)
-      end
-
-      private
-
-        def time_for_time_query(t, column)
-          if t == :now || t == :today
-            now_for_column(column)
-          else
-            quoted_t = connection.quote(connection.quoted_date(t))
-            [quoted_t, primitive_type_for_column(column)].join('::')
-          end
-        end
-
-        def now_for_column(column)
-          case column.type
-          when :tsrange, :tstzrange then "timezone('UTC', current_timestamp)"
-          when :daterange           then "current_date"
-          else raise "Cannot generate 'now()' for #{column.type} column #{column.name}"
-          end
-        end
-
-        def primitive_type_for_column(column)
-          case column.type
-          when :tsrange   then :timestamp
-          when :tstzrange then :timestamptz
-          when :daterange then :date
-          else raise "Don't know how to map #{column.type} column #{column.name} to a primitive type"
-          end
-        end
-
-        def build_time_query_at(time, range)
-          time = if time.kind_of?(Array)
-            time.map! {|t| time_for_time_query(t, range)}
-
-            # If both edges of the range are the same the query fails using the '&&' operator.
-            # The correct solution is to use the <@ operator.
-            time.first == time.last ? time.first : time
-          else
-            time_for_time_query(time, range)
-          end
-
-          build_time_query(time, range)
-        end
-
-        def build_time_query(time, range, op = '&&')
-          if time.kind_of?(Array)
-            Arel.sql %[ #{range.type}(#{time.first}, #{time.last}) #{op} #{table_name}.#{range.name} ]
-          else
-            Arel.sql %[ #{time} <@ #{table_name}.#{range.name} ]
-          end
-        end
-    end
-
-    # Methods that make up the history interface of the companion History
-    # model, automatically built for each Model that includes TimeMachine
-    module HistoryMethods
-      include TimeQuery
-
-      # In the History context, pre-fill the :on options with the validity interval.
-      #
-      def time_query(match, time, options = {})
-        options[:on] ||= :validity
-        super
-      end
-
-      def past
-        time_query(:before, :now).where("NOT upper_inf(#{quoted_table_name}.validity)")
-      end
-
-      # To identify this class as the History subclass
-      def history?
-        true
-      end
-
-      # Getting the correct quoted_table_name can be tricky when
-      # STI is involved. If Orange < Fruit, then Orange::History < Fruit::History
-      # (see define_inherited_history_model_for).
-      # This means that the superclass method returns Fruit::History, which
-      # will give us the wrong table name. What we actually want is the
-      # superclass of Fruit::History, which is Fruit. So, we use
-      # non_history_superclass instead. -npj
-      def non_history_superclass(klass = self)
-        if klass.superclass.history?
-          non_history_superclass(klass.superclass)
-        else
-          klass.superclass
-        end
-      end
-
-      def relation
-        super.as_of_time!(Time.now)
-      end
-
-      # Fetches as of +time+ records.
-      #
-      def as_of(time)
-        non_history_superclass.from(virtual_table_at(time)).as_of_time!(time)
-      end
-
-      def virtual_table_at(time, name = nil)
-        name = name ? connection.quote_table_name(name) :
-          non_history_superclass.quoted_table_name
-
-        "(#{at(time).to_sql}) #{name}"
-      end
-
-      # Fetches history record at the given time
-      #
-      def at(time)
-        time_query(:at, time).from(quoted_table_name).as_of_time!(time)
-      end
-
-      # Returns the history sorted by recorded_at
-      #
-      def sorted
-        all.order(Arel.sql(%[ #{quoted_table_name}."recorded_at" ASC, #{quoted_table_name}."hid" ASC ]))
-      end
-
-      # Fetches the given +object+ history, sorted by history record time
-      # by default. Always includes an "as_of_time" column that is either
-      # the upper bound of the validity range or now() if history validity
-      # is maximum.
-      #
-      def of(object)
-        where(:id => object)
-      end
-
-      # FIXME Remove, this was a workaround to a former design flaw.
-      #
-      #   - vjt  Wed Oct 28 17:13:57 CET 2015
-      #
-      def force_history_fields
-        self
-      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}
-
-          relation = self.except(:order).
-            select("DISTINCT UNNEST(ARRAY[#{fields.join(',')}]) AS ts")
-
-          if assocs.present?
-            relation = relation.joins(*assocs.map(&:name))
-          end
-
-          relation = relation.
-            order('ts ' << (options[:reverse] ? 'DESC' : 'ASC'))
-
-          relation = relation.from(%["public".#{quoted_table_name}]) unless self.chrono?
-          relation = relation.where(:id => rid) if rid
-
-          sql = "SELECT ts FROM ( #{relation.to_sql} ) foo WHERE ts IS NOT NULL"
-
-          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
-
-          if rid && !options[:with]
-            sql << (self.chrono? ? %{
-              AND ts <@ ( SELECT tsrange(min(lower(validity)), max(upper(validity)), '[]') 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
-
-        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 ||= begin
-          validity =
-            [connection.quote_table_name(table_name),
-             connection.quote_column_name('validity')
-            ].join('.')
-
-          [:lower, :upper].map! {|func| "#{func}(#{validity})"}
-        end
-      end
-    end
   end
 
 end