chrono_model 3.0.1 → 5.0.0

data/lib/chrono_model/patches/batches.rb

@@ -2,10 +2,44 @@
 
 module ChronoModel
   module Patches
+    # Overrides the default batch methods for historical models
+    #
+    # In the default implementation, `cursor` defaults to `primary_key`, which is 'id'.
+    # However, historical models need to use 'hid' instead of 'id'.
+    #
+    # This patch addresses an issue where `with_hid_pkey` is called after the cursor
+    # is already set, potentially leading to incorrect behavior.
+    #
+    # Notes:
+    # - `find_each` and `find_in_batches` internally utilize `in_batches`.
+    #   However, in the upcoming Rails 8.0, this implementation will be
+    #   insufficient due to a new conditional branch using `enum_for`.
+    # - This approach prevents specifying 'id' as a cursor for historical models.
+    #   If 'id' is needed, it must be handled separately.
+    #
+    # See: ifad/chronomodel#321 for more context
     module Batches
-      def in_batches(**)
+      def find_each(**options)
         return super unless try(:history?)
 
+        options[:cursor] = 'hid' if options[:cursor] == 'id'
+
+        with_hid_pkey { super }
+      end
+
+      def find_in_batches(**options)
+        return super unless try(:history?)
+
+        options[:cursor] = 'hid' if options[:cursor] == 'id'
+
+        with_hid_pkey { super }
+      end
+
+      def in_batches(**options)
+        return super unless try(:history?)
+
+        options[:cursor] = 'hid' if options[:cursor] == 'id'
+
         with_hid_pkey { super }
       end
     end

data/lib/chrono_model/patches/join_node.rb

@@ -2,28 +2,17 @@
 
 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.
-    #
+    # Replaces the left side of an Arel join (table or table alias) with a SQL
+    # literal pointing to the history virtual table at the given as_of_time,
+    # preserving any existing table alias.
     class JoinNode < Arel::Nodes::SqlLiteral
-      attr_reader :name, :table_name, :table_alias, :as_of_time
+      attr_reader :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_name: @table_alias || @table_name)
+        table_name = join_node.table_alias || join_node.name
+        virtual_table = history_model.virtual_table_at(@as_of_time, table_name: table_name)
 
         super(virtual_table)
       end

data/lib/chrono_model/patches/preloader.rb

@@ -9,43 +9,14 @@ module ChronoModel
     module Preloader
       attr_reader :chronomodel_options
 
-      # We overwrite the initializer in order to pass the +as_of_time+
-      # parameter above in the build_preloader
+      # Overwrite the initializer to set Chronomodel +as_of_time+ and +model+
+      # options.
       #
       def initialize(**options)
         @chronomodel_options = options.extract!(:as_of_time, :model)
         options[:scope] = chronomodel_scope(options[:scope]) if options.key?(:scope)
 
-        if options.empty?
-          super()
-        else
-          super(**options)
-        end
-      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)
-        super(records, associations, chronomodel_scope(given_preload_scope))
+        super
       end
 
       private
@@ -62,6 +33,8 @@ module ChronoModel
       end
 
       module Association
+        private
+
         # Builds the preloader scope taking into account a potential
         # +as_of_time+ passed down the call chain starting at the
         # end user invocation.
@@ -78,13 +51,14 @@ module ChronoModel
       end
 
       module ThroughAssociation
+        private
+
         # Builds the preloader scope taking into account a potential
         # +as_of_time+ passed down the call chain starting at the
         # end user invocation.
         #
         def through_scope
           scope = super
-          return unless scope # Rails 5.2 may not return a scope
 
           if preload_scope.try(:as_of_time)
             scope = scope.as_of(preload_scope.as_of_time)

data/lib/chrono_model/patches/relation.rb

@@ -23,10 +23,17 @@ module ChronoModel
         @values == klass.unscoped.as_of(as_of_time).values
       end
 
-      def load
-        return super unless @_as_of_time && !loaded?
+      def load(&block)
+        return super unless @_as_of_time && (!loaded? || scheduled?)
 
-        super.each { |record| record.as_of_time!(@_as_of_time) }
+        records = super
+
+        records.each do |record|
+          record.as_of_time!(@_as_of_time)
+          propagate_as_of_time_to_includes(record)
+        end
+
+        self
       end
 
       def merge(*)
@@ -35,6 +42,20 @@ module ChronoModel
         super.as_of_time!(@_as_of_time)
       end
 
+      def find_nth(*)
+        return super unless try(:history?)
+
+        with_hid_pkey { super }
+      end
+
+      def last(*)
+        return super unless try(:history?)
+
+        with_hid_pkey { super }
+      end
+
+      private
+
       def build_arel(*)
         return super unless @_as_of_time
 
@@ -47,54 +68,71 @@ module ChronoModel
 
       # Replaces a join with the current data with another that
       # loads records As-Of time against the history data.
-      #
       def chrono_join_history(join)
+        join_left = join.left
+
         # 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 =
-          if join.left.respond_to?(:table_name)
-            ChronoModel.history_models[join.left.table_name]
-          else
-            ChronoModel.history_models[join.left]
-          end
+        return if join_left.is_a?(ChronoModel::Patches::JoinNode)
 
+        model = ChronoModel.history_models[join_left.name] if join_left.respond_to?(:name)
         return unless model
 
         join.left = ChronoModel::Patches::JoinNode.new(
-          join.left, model.history, @_as_of_time
+          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: model, as_of_time: as_of_time
-        )
-      end
-
-      def find_nth(*)
+      def ordered_relation
         return super unless try(:history?)
 
         with_hid_pkey { super }
       end
 
-      def last(*)
-        return super unless try(:history?)
+      # Propagate as_of_time to associations that were eager loaded via includes/eager_load
+      def propagate_as_of_time_to_includes(record)
+        return unless eager_loading?
 
-        with_hid_pkey { super }
+        assign_as_of_time_to_spec(record, includes_values)
       end
 
-      private
+      def assign_as_of_time_to_spec(record, spec)
+        case spec
+        when Symbol, String
+          assign_as_of_time_to_association(record, spec.to_sym, nil)
+        when Array
+          spec.each { |s| assign_as_of_time_to_spec(record, s) }
+        when Hash
+          # This branch is difficult to trigger in practice due to Rails query optimization.
+          # Modern Rails versions tend to optimize eager loading in ways that make this specific
+          # code path challenging to reproduce in tests without artificial scenarios.
+          spec.each do |name, nested|
+            assign_as_of_time_to_association(record, name.to_sym, nested)
+          end
+        end
+      end
 
-      def ordered_relation
-        return super unless try(:history?)
+      def assign_as_of_time_to_association(record, name, nested)
+        reflection = record.class.reflect_on_association(name)
+        return unless reflection
 
-        with_hid_pkey { super }
+        assoc = record.association(name)
+        return unless assoc.loaded?
+
+        target = assoc.target
+
+        if target.is_a?(Array)
+          target.each { |t| t.respond_to?(:as_of_time!) && t.as_of_time!(@_as_of_time) }
+          # This nested condition is difficult to trigger in practice as it requires specific
+          # association loading scenarios with Array targets and nested specs that Rails
+          # query optimization tends to handle differently in modern versions.
+          if nested.present?
+            target.each { |t| assign_as_of_time_to_spec(t, nested) }
+          end
+        else
+          target.respond_to?(:as_of_time!) && target.as_of_time!(@_as_of_time)
+          assign_as_of_time_to_spec(target, nested) if nested.present? && target
+        end
       end
     end
   end

data/lib/chrono_model/patches.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'chrono_model/patches/as_of_time_holder'
-require 'chrono_model/patches/as_of_time_relation'
+require_relative 'patches/as_of_time_holder'
+require_relative 'patches/as_of_time_relation'
 
-require 'chrono_model/patches/join_node'
-require 'chrono_model/patches/relation'
-require 'chrono_model/patches/preloader'
-require 'chrono_model/patches/association'
-require 'chrono_model/patches/batches'
+require_relative 'patches/join_node'
+require_relative 'patches/relation'
+require_relative 'patches/preloader'
+require_relative 'patches/association'
+require_relative 'patches/batches'

data/lib/chrono_model/railtie.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'active_record/tasks/chronomodel_database_tasks'
+require_relative '../active_record/tasks/chronomodel_database_tasks'
 
 module ChronoModel
   class Railtie < ::Rails::Railtie

data/lib/chrono_model/time_machine/history_model.rb

@@ -11,7 +11,6 @@ module ChronoModel
         scope :chronological, -> { order(Arel.sql('lower(validity) ASC')) }
       end
 
-      # ACTIVE RECORD 7 does not call `class.find` but a new internal method called `_find_record`
       def _find_record(options)
         if options && options[:lock]
           self.class.preload(strict_loaded_associations).lock(options[:lock]).find_by!(hid: hid)
@@ -33,7 +32,7 @@ module ChronoModel
         #
         def with_hid_pkey
           old = primary_key
-          self.primary_key = :hid
+          self.primary_key = 'hid'
 
           yield
         ensure
@@ -83,14 +82,18 @@ module ChronoModel
 
         # Fetches history record at the given time
         #
+        # Build on an unscoped relation to avoid leaking outer predicates
+        # (e.g., through association scopes) into the inner subquery.
+        #
+        # @see https://github.com/ifad/chronomodel/issues/295
         def at(time)
-          time_query(:at, time).from(quoted_table_name).as_of_time!(time)
+          unscoped.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 )))
+          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
@@ -107,7 +110,7 @@ module ChronoModel
         # name has the "::History" suffix but that is never going to be
         # present in the data.
         #
-        # As such it is overriden here to return the same contents that
+        # As such it is overridden here to return the same contents that
         # the parent would have returned.
         delegate :sti_name, to: :superclass
 
@@ -132,7 +135,7 @@ module ChronoModel
       end
 
       # The history id is `hid`, but this cannot set as primary key
-      # or temporal assocations will break. Solutions are welcome.
+      # or temporal associations will break. Solutions are welcome.
       def id
         hid
       end
@@ -204,26 +207,49 @@ module ChronoModel
         self.class.superclass.find(rid)
       end
 
-      def record # :nodoc:
-        ActiveSupport::Deprecation.warn '.record is deprecated in favour of .current_version'
-        current_version
-      end
-
+      # Return `nil` instead of -Infinity/Infinity to preserve current
+      # Chronomodel behaviour and avoid failures with Rails 7.0 and
+      # unbounded time ranges
+      #
+      # Check if `begin` and `end` are `Time` because validity is a `tsrange`
+      # column, so it is either `Time`, `nil`, and in some cases Infinity.
+      #
+      # Ref: rails/rails#45099
+      # TODO: consider removing when Rails 7.0 support will be dropped
       def valid_from
-        validity.first
+        validity.begin if validity.begin.is_a?(Time)
       end
 
       def valid_to
-        validity.last
+        validity.end if validity.end.is_a?(Time)
       end
-      alias as_of_time valid_to
 
-      def recorded_at
-        ChronoModel::Conversions.string_to_utc_time attributes_before_type_cast['recorded_at']
+      # Computes an `as_of_time` strictly inside this record's validity period
+      # for historical queries.
+      #
+      # Ensures association queries return versions that existed during this
+      # record's validity, not ones that became valid exactly at the boundary
+      # time. When objects are updated in the same transaction, they can share
+      # the same `valid_to`, which would otherwise cause boundary
+      # mis-selection.
+      #
+      # PostgreSQL ranges are half-open `[start, end)` by default.
+      #
+      # @return [Time, nil] `valid_to - ChronoModel::VALIDITY_TSRANGE_PRECISION`
+      #   when `valid_to` is a Time; otherwise returns `valid_to` unchanged
+      #   (which may be `nil` for open-ended validity).
+      #
+      # @see https://github.com/ifad/chronomodel/issues/283
+      def as_of_time
+        if valid_to.is_a?(Time)
+          valid_to - ChronoModel::VALIDITY_TSRANGE_PRECISION
+        else
+          valid_to
+        end
       end
 
-      # Starting from Rails 6.0, `.read_attribute` will use the memoized
-      # `primary_key` if it detects that the attribute name is `id`.
+      # `.read_attribute` uses the memoized `primary_key` if it detects
+      # that the attribute name is `id`.
       #
       # Since the `primary key` may have been changed to `hid` because of
       # `.find` overload, the new behavior may break relations where `id` is
@@ -240,7 +266,7 @@ module ChronoModel
 
       def with_hid_pkey(&block)
         old_primary_key = @primary_key
-        @primary_key = :hid
+        @primary_key = 'hid'
 
         self.class.with_hid_pkey(&block)
       ensure

data/lib/chrono_model/time_machine/time_query.rb

@@ -46,7 +46,8 @@ module ChronoModel
       end
 
       def time_for_time_query(t, column)
-        if t == :now || t == :today
+        case t
+        when :now, :today
           now_for_column(column)
         else
           quoted_t = connection.quote(connection.quoted_date(t))
@@ -92,9 +93,9 @@ module ChronoModel
 
       def build_time_query(time, range, op = '&&')
         if time.is_a?(Array)
-          Arel.sql %[ #{range.type}(#{time.first}, #{time.last}) #{op} #{table_name}.#{range.name} ]
+          Arel.sql %[#{range.type}(#{time.first}, #{time.last}) #{op} #{table_name}.#{range.name} ]
         else
-          Arel.sql %( #{time} <@ #{table_name}.#{range.name} )
+          Arel.sql %(#{time} <@ #{table_name}.#{range.name})
         end
       end
     end

data/lib/chrono_model/time_machine/timeline.rb

@@ -59,7 +59,7 @@ module ChronoModel
         relation = relation.from("public.#{quoted_table_name}") unless chrono?
         relation = relation.where(id: rid) if rid
 
-        sql = +"SELECT ts FROM ( #{relation.to_sql} ) AS foo WHERE ts IS NOT NULL"
+        sql = "SELECT ts FROM (#{relation.to_sql}) AS foo WHERE ts IS NOT NULL"
 
         if options.key?(:before)
           sql << " AND ts < '#{Conversions.time_to_utc_string(options[:before])}'"
@@ -72,18 +72,16 @@ module ChronoModel
         if rid && !options[:with]
           sql <<
             if chrono?
-              %{ AND ts <@ ( SELECT tsrange(min(lower(validity)), max(upper(validity)), '[]') FROM #{quoted_table_name} WHERE id = #{rid} ) }
+              %{ AND ts <@ (SELECT tsrange(min(lower(validity)), max(upper(validity)), '[]') FROM #{quoted_table_name} WHERE id = #{rid})}
             else
-              %[ AND ts < NOW() ]
+              ' AND ts < NOW()'
             end
         end
 
         sql << " LIMIT #{options[:limit].to_i}" if options.key?(:limit)
 
         connection.on_schema(Adapter::HISTORY_SCHEMA) do
-          connection.select_values(sql, "#{name} periods").map! do |ts|
-            Conversions.string_to_utc_time ts
-          end
+          connection.select_values(sql, "#{name} periods")
         end
       end
 

data/lib/chrono_model/time_machine.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'chrono_model/time_machine/time_query'
-require 'chrono_model/time_machine/timeline'
-require 'chrono_model/time_machine/history_model'
+require_relative 'time_machine/time_query'
+require_relative 'time_machine/timeline'
+require_relative 'time_machine/history_model'
 
 module ChronoModel
   module TimeMachine
@@ -12,7 +12,7 @@ module ChronoModel
 
     included do
       if table_exists? && !chrono?
-        logger.warn <<-MSG.squish
+        logger.warn <<~MSG.squish
           ChronoModel: #{table_name} is not a temporal table.
           Please use `change_table :#{table_name}, temporal: true` in a migration.
         MSG
@@ -176,7 +176,7 @@ module ChronoModel
       else
         return nil unless (ts = pred_timestamp(options))
 
-        order_clause = Arel.sql %[ LOWER(#{options[:table] || self.class.quoted_table_name}."validity") DESC ]
+        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

data/lib/chrono_model/utilities.rb

@@ -16,12 +16,12 @@ module ChronoModel
         raise 'Can amend history only with UTC timestamps'
       end
 
-      connection.execute %[
+      connection.execute <<~SQL.squish
         UPDATE #{quoted_table_name}
-           SET "validity" = tsrange(#{connection.quote(from)}, #{connection.quote(to)}),
+           SET "validity"    = tsrange(#{connection.quote(from)}, #{connection.quote(to)}),
                "recorded_at" = #{connection.quote(from)}
          WHERE "hid" = #{hid.to_i}
-      ]
+      SQL
     end
   end
 end

data/lib/chrono_model/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChronoModel
-  VERSION = '3.0.1'
+  VERSION = '5.0.0'
 end

data/lib/chrono_model.rb

@@ -2,21 +2,26 @@
 
 require 'active_record'
 
-require 'chrono_model/chrono'
-require 'chrono_model/conversions'
-require 'chrono_model/patches'
-require 'chrono_model/adapter'
-require 'chrono_model/time_machine'
-require 'chrono_model/time_gate'
-require 'chrono_model/version'
+require_relative 'chrono_model/chrono'
+require_relative 'chrono_model/conversions'
+require_relative 'chrono_model/patches'
+require_relative 'chrono_model/adapter'
+require_relative 'chrono_model/time_machine'
+require_relative 'chrono_model/time_gate'
+require_relative 'chrono_model/version'
 
-require 'chrono_model/railtie' if defined?(Rails::Railtie)
-require 'chrono_model/db_console' if defined?(Rails::DBConsole) && Rails.version < '7.1'
+require_relative 'chrono_model/railtie' if defined?(Rails::Railtie)
+require_relative 'chrono_model/db_console' if defined?(Rails::DBConsole) && Rails.version < '7.1'
 
 module ChronoModel
   class Error < ActiveRecord::ActiveRecordError # :nodoc:
   end
 
+  # ChronoModel uses default timestamp precision (p=6) for tsrange columns.
+  # PostgreSQL timestamp precision can range from 0 to 6 fractional digits,
+  # where 6 provides microsecond resolution (1 microsecond = 10^-6 seconds).
+  VALIDITY_TSRANGE_PRECISION = Rational(1, 10**6)
+
   # Performs structure upgrade.
   #
   def self.upgrade!

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chrono_model
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 5.0.0
 platform: ruby
 authors:
 - Marcello Barnaba
 - Peter Joseph Brindisi
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -72,7 +71,6 @@ files:
 - lib/chrono_model/adapter/indexes.rb
 - lib/chrono_model/adapter/migrations.rb
 - lib/chrono_model/adapter/migrations_modules/stable.rb
-- lib/chrono_model/adapter/tsrange.rb
 - lib/chrono_model/adapter/upgrade.rb
 - lib/chrono_model/chrono.rb
 - lib/chrono_model/conversions.rb
@@ -102,7 +100,6 @@ metadata:
   homepage_uri: https://github.com/ifad/chronomodel
   source_code_uri: https://github.com/ifad/chronomodel
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -117,8 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.5
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Temporal extensions (SCD Type II) for Active Record
 test_files: []