activerecord-temporal 0.1.0 → 0.3.0

data/lib/activerecord/temporal/application_versioning/application_versioned.rb

@@ -0,0 +1,122 @@
+module ActiveRecord::Temporal
+  module ApplicationVersioning
+    module ApplicationVersioned
+      extend ActiveSupport::Concern
+
+      included do
+        delegate :scope_time, to: :class
+
+        include Querying
+      end
+
+      class_methods do
+        def originate
+          originate_at(scope_time || Time.current)
+        end
+
+        def originate_at(time)
+          Original.new(self, time, save: true)
+        end
+
+        def original
+          original_at(scope_time || Time.current)
+        end
+
+        def original_at(time)
+          Original.new(self, time)
+        end
+
+        def scope_time
+          Querying::ScopeRegistry.global_constraint_for(time_dimensions.first)
+        end
+      end
+
+      class Revision
+        attr_reader :record, :time, :options
+
+        def initialize(record, time, **options)
+          @record = record
+          @time = time
+          @options = options
+        end
+
+        def with(attributes)
+          new_revision = record.dup
+          new_revision.assign_attributes(attributes)
+          new_revision.id = record.id
+          new_revision.set_time_dimension_start(time)
+          new_revision.time_tags = record.time_tags
+          record.set_time_dimension_end(time)
+
+          new_revision.after_initialize_revision(record)
+
+          if options[:save]
+            record.class.transaction do
+              new_revision.save if record.save
+            end
+          end
+
+          new_revision
+        end
+      end
+
+      class Original
+        attr_reader :klass, :time, :options
+
+        def initialize(klass, time, **options)
+          @klass = klass
+          @time = time
+          @options = options
+        end
+
+        def with(attributes)
+          new_record = klass.new(attributes)
+          new_record.set_time_dimension_start(time)
+
+          new_record.save if options[:save]
+
+          new_record
+        end
+      end
+
+      def after_initialize_revision(old_revision)
+        self.version = old_revision.version + 1
+      end
+
+      def head_revision?
+        time_dimension && !time_dimension_end
+      end
+
+      def revise
+        revise_at(scope_time || Time.current)
+      end
+
+      def revise_at(time)
+        raise ClosedRevisionError, "Cannot revise closed version" unless head_revision?
+
+        Revision.new(self, time, save: true)
+      end
+
+      def revision
+        revision_at(scope_time || Time.current)
+      end
+
+      def revision_at(time)
+        raise ClosedRevisionError, "Cannot revise closed version" unless head_revision?
+
+        Revision.new(self, time, save: false)
+      end
+
+      def inactivate
+        inactivate_at(scope_time || Time.current)
+      end
+
+      def inactivate_at(time)
+        raise ClosedRevisionError, "Cannot inactivate closed version" unless head_revision?
+
+        set_time_dimension_end(time)
+        save
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/application_versioning.rb

@@ -2,76 +2,12 @@ module ActiveRecord::Temporal
   module ApplicationVersioning
     extend ActiveSupport::Concern
 
-    included do
-      include AsOfQuery
-    end
-
-    class Revision
-      attr_reader :record, :time, :options
-
-      def initialize(record, time, **options)
-        @record = record
-        @time = time
-        @options = options
-      end
-
-      def with(attributes)
-        new_revision = record.dup
-        new_revision.assign_attributes(attributes)
-        new_revision.set_time_dimension_start(time)
-        new_revision.time_scopes = record.time_scopes
-        record.set_time_dimension_end(time)
-
-        new_revision.after_initialize_revision(record)
-
-        if options[:save]
-          record.class.transaction do
-            new_revision.save if record.save
-          end
-        end
+    class ClosedRevisionError < StandardError; end
 
-        [new_revision, record]
+    class_methods do
+      def application_versioned
+        include ApplicationVersioned
       end
     end
-
-    def after_initialize_revision(old_revision)
-      self.version = old_revision.version + 1
-      self.id_value = old_revision.id_value
-    end
-
-    def head_revision?
-      time_dimension && !time_dimension_end
-    end
-
-    def revise
-      revise_at(Time.current)
-    end
-
-    def revise_at(time)
-      raise "not head revision" unless head_revision?
-
-      Revision.new(self, time, save: true)
-    end
-
-    def revision
-      revision_at(Time.current)
-    end
-
-    def revision_at(time)
-      raise "not head revision" unless head_revision?
-
-      Revision.new(self, time, save: false)
-    end
-
-    def inactivate
-      inactivate_at(Time.current)
-    end
-
-    def inactivate_at(time)
-      raise "not head revision" unless head_revision?
-
-      set_time_dimension_end(time)
-      save
-    end
   end
 end

data/lib/activerecord/temporal/patches/association_reflection.rb

@@ -1,14 +1,21 @@
 module ActiveRecord::Temporal
   module Patches
+    # This permits association scopes generated by this gem to be eager-load if
+    # they are "optionally instance-dependent." That is to say, they accept but
+    # don't require arguments.
+    #
+    # I think permitting eager-loading of such scopes would make sense as a
+    # standalone feature for Active Record. See this PR for my justification:
+    # https://github.com/rails/rails/pull/56004
     module AssociationReflection
       def check_eager_loadable!
-        super unless as_of_scope? && scope_requires_no_params?
+        super unless temporal_scope? && scope_requires_no_params?
       end
 
       private
 
-      def as_of_scope?
-        scope.respond_to?(:as_of_scope?) && scope.as_of_scope?
+      def temporal_scope?
+        scope.respond_to?(:temporal_scope?) && scope.temporal_scope?
       end
 
       def scope_requires_no_params?

data/lib/activerecord/temporal/patches/join_dependency.rb

@@ -1,5 +1,9 @@
 module ActiveRecord::Temporal
   module Patches
+    # This is a copy of a fix from https://github.com/rails/rails/pull/56088 that
+    # impacts this gem. I has been merged and backported to supported stable
+    # versions of Active Record, but until those patches are released it's included
+    # here.
     module JoinDependency
       def instantiate(result_set, strict_loading_value, &block)
         primary_key = Array(join_root.primary_key).map { |column| aliases.column_alias(join_root, column) }

data/lib/activerecord/temporal/patches/merger.rb

@@ -3,7 +3,7 @@ module ActiveRecord::Temporal
     module Merger
       def merge
         super.tap do |relation|
-          relation.time_scope!(values[:time_scope] || {})
+          relation.time_tags!(values[:time_tags] || {})
         end
       end
     end

data/lib/activerecord/temporal/patches/relation.rb

@@ -4,22 +4,26 @@ module ActiveRecord::Temporal
       private
 
       if ActiveRecord.version > Gem::Version.new("8.0.4")
-        def build_arel(connection)
-          AsOfQuery::ScopeRegistry.with_query_scope(time_scope_values) { super }
+        def build_arel(aliases)
+          Querying::Scoping.as_of(time_tag_values) do
+            super
+          end
         end
       else
-        def build_arel(connection, aliases = nil)
-          AsOfQuery::ScopeRegistry.with_query_scope(time_scope_values) { super }
+        def build_arel(aliases, connection = nil)
+          Querying::Scoping.as_of(time_tag_values) do
+            super
+          end
         end
       end
 
       def instantiate_records(rows, &block)
-        return super if time_scope_values.empty?
+        return super if time_tag_values.empty?
 
         records = super
 
         records.each do |record|
-          record.initialize_time_scope_from_relation(self) if record.is_a?(AsOfQuery)
+          record.initialize_time_tags_from_relation(self) if record.is_a?(Querying)
         end
 
         records

data/lib/activerecord/temporal/patches/through_association.rb

@@ -1,9 +1,12 @@
 module ActiveRecord::Temporal
   module Patches
+    # Patches the preloader's `through_scope` method to pass along the relation's
+    # time tag values when it handles has-many-through associations. The handler
+    # for has-many associations uses `Relation#merge`, but this one doesn't.
     module ThroughAssociation
       def through_scope
         super.tap do |scope|
-          scope.time_scope_values = reflection_scope.time_scope_values
+          scope.time_tag_values = reflection_scope.time_tag_values
         end
       end
     end

data/lib/activerecord/temporal/{as_of_query → querying}/association_macros.rb

@@ -1,5 +1,5 @@
 module ActiveRecord::Temporal
-  module AsOfQuery
+  module Querying
     module AssociationMacros
       extend ActiveSupport::Concern
 

data/lib/activerecord/temporal/querying/association_scope.rb

@@ -0,0 +1,55 @@
+module ActiveRecord::Temporal
+  module Querying
+    class AssociationScope
+      class << self
+        def build(block)
+          scope = merge_scopes(block)
+
+          def scope.temporal_scope? = true
+
+          scope
+        end
+
+        private
+
+        def merge_scopes(block)
+          temporal_scope = build_temporal_scope
+
+          if !block
+            return ->(owner = nil) do
+              instance_exec(owner, all, &temporal_scope)
+            end
+          end
+
+          if block.arity != 0
+            return ->(owner) do
+              base = instance_exec(owner, &block)
+              instance_exec(owner, base, &temporal_scope)
+            end
+          end
+
+          ->(owner = nil) do
+            base = instance_exec(&block)
+            instance_exec(owner, base, &temporal_scope)
+          end
+        end
+
+        def build_temporal_scope
+          ->(owner, base) do
+            registry_constraints = ScopeRegistry
+              .association_constraints_for(time_dimensions)
+
+            registry_time_tags = ScopeRegistry
+              .association_tags_for(time_dimensions)
+
+            owner_time_tags = owner&.time_tags_for(time_dimensions) || {}
+
+            base
+              .at_time(registry_constraints.merge(owner_time_tags))
+              .time_tags(owner_time_tags.merge(registry_time_tags))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/{as_of_query → querying}/association_walker.rb

@@ -1,5 +1,5 @@
 module ActiveRecord::Temporal
-  module AsOfQuery
+  module Querying
     class AssociationWalker
       class << self
         def each_target(parent_record, associations, &block)

data/lib/activerecord/temporal/querying/predicate_builder/contains_handler.rb

@@ -0,0 +1,24 @@
+module ActiveRecord::Temporal::Querying
+  class PredicateBuilder
+    class ContainsHandler
+      def initialize(predicate_builder)
+        @predicate_builder = predicate_builder
+      end
+
+      def call(attribute, value)
+        time_as_tstz = Arel::Nodes::As.new(
+          Arel::Nodes::Quoted.new(value.time),
+          Arel::Nodes::SqlLiteral.new("timestamptz")
+        )
+
+        cast_value = Arel::Nodes::NamedFunction.new("CAST", [time_as_tstz])
+
+        attribute.contains(cast_value)
+      end
+
+      private
+
+      attr_reader :predicate_builder
+    end
+  end
+end

data/lib/activerecord/temporal/querying/predicate_builder/handlers.rb

@@ -0,0 +1,31 @@
+module ActiveRecord::Temporal::Querying
+  class PredicateBuilder
+    require_relative "contains_handler"
+
+    module Handlers
+      Contains = Struct.new(:time)
+
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def contains(time)
+          Contains.new(time)
+        end
+
+        def predicate_builder
+          super.tap do |base_predicate_builder|
+            register_predicate_builder_handlers(base_predicate_builder)
+          end
+        end
+
+        private
+
+        def register_predicate_builder_handlers(base_predicate_builder)
+          @register_predicate_builder_handlers ||= base_predicate_builder
+            .register_handler Contains,
+              PredicateBuilder::ContainsHandler.new(base_predicate_builder)
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/querying/query_methods.rb

@@ -0,0 +1,37 @@
+module ActiveRecord::Temporal
+  module Querying
+    module QueryMethods
+      require "activerecord/temporal/querying/where_clause_refinement"
+
+      using Querying::WhereClauseRefinement
+
+      def time_tags(scope)
+        spawn.time_tags!(scope)
+      end
+
+      def time_tags!(scope)
+        self.time_tag_values = time_tag_values.merge(scope)
+        self
+      end
+
+      def time_tag_values
+        @values.fetch(:time_tags, ActiveRecord::QueryMethods::FROZEN_EMPTY_HASH)
+      end
+
+      def time_tag_values=(scope)
+        assert_modifiable! # TODO: write test
+
+        @values[:time_tags] = scope
+      end
+
+      def rewhere_contains(conditions)
+        scope = spawn
+
+        scope.where_clause = where_clause.except_contains(conditions.keys)
+        scope.where_clause += build_where_clause(conditions)
+
+        scope
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/querying/scope_registry.rb

@@ -0,0 +1,95 @@
+module ActiveRecord::Temporal
+  module Querying
+    class ScopeRegistry
+      class << self
+        delegate :global_constraints,
+          :association_constraints,
+          :association_tags,
+          :universal_global_constraint_time,
+          :global_constraints=,
+          :association_constraints=,
+          :association_tags=,
+          :universal_global_constraint_time=,
+          :global_constraint_for,
+          :association_constraint_for,
+          :association_tag_for,
+          :global_constraints_for,
+          :association_constraints_for,
+          :association_tags_for,
+          :set_global_constraints,
+          :set_association_constraints,
+          :set_association_tags,
+          to: :instance
+
+        def instance
+          ActiveSupport::IsolatedExecutionState[:temporal_querying_registry] ||= new
+        end
+      end
+
+      attr_accessor :global_constraints,
+        :association_constraints,
+        :association_tags,
+        :universal_global_constraint_time
+
+      def initialize(
+        global_constraints: nil,
+        association_constraints: nil,
+        association_tags: nil,
+        default_association_constraint_time: nil,
+        universal_global_constraint_time: nil
+      )
+        @global_constraints = global_constraints || {}
+        @association_constraints = association_constraints || {}
+        @association_tags = association_tags || {}
+        @default_association_constraint_time = default_association_constraint_time ||
+          -> { Time.current }
+        @universal_global_constraint_time = universal_global_constraint_time
+      end
+
+      def global_constraint_for(dimension)
+        global_constraints[dimension] || universal_global_constraint_time
+      end
+
+      def association_constraint_for(dimension)
+        association_constraints[dimension] ||
+          global_constraint_for(dimension) ||
+          @default_association_constraint_time.call
+      end
+
+      def association_tag_for(dimension)
+        association_tags[dimension]
+      end
+
+      def global_constraints_for(*dimensions)
+        dimensions.flatten.index_with do |dimension|
+          global_constraint_for(dimension)
+        end.compact
+      end
+
+      def association_constraints_for(*dimensions)
+        dimensions.flatten.index_with do |dimension|
+          association_constraint_for(dimension)
+        end
+      end
+
+      def association_tags_for(*dimensions)
+        association_tags.slice(*dimensions.flatten)
+      end
+
+      def set_global_constraints(time_coords)
+        self.global_constraints = global_constraints
+          .merge(time_coords)
+      end
+
+      def set_association_constraints(time_coords)
+        self.association_constraints = association_constraints
+          .merge(time_coords)
+      end
+
+      def set_association_tags(time_coords)
+        self.association_tags = association_tags
+          .merge(time_coords)
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/querying/scoping.rb

@@ -0,0 +1,70 @@
+module ActiveRecord::Temporal
+  module Querying
+    class Scoping
+      class << self
+        def at(time_or_time_coords, &block)
+          if time_or_time_coords.is_a?(Hash)
+            with_global_constraint(time_or_time_coords, &block)
+          else
+            without_global_constraints do
+              with_universal_global_constraint_time(time_or_time_coords, &block)
+            end
+          end
+        end
+
+        def as_of(time_coords, &block)
+          with_association_constraints(time_coords) do
+            with_association_tags(time_coords, &block)
+          end
+        end
+
+        private
+
+        def with_association_constraints(time_coords, &block)
+          original = ScopeRegistry.association_constraints
+          ScopeRegistry.set_association_constraints(time_coords)
+
+          block.call
+        ensure
+          ScopeRegistry.association_constraints = original
+        end
+
+        def with_association_tags(time_coords, &block)
+          original = ScopeRegistry.association_tags
+          ScopeRegistry.set_association_tags(time_coords)
+
+          block.call
+        ensure
+          ScopeRegistry.association_tags = original
+        end
+
+        def with_global_constraint(value, &block)
+          original = ScopeRegistry.global_constraints
+          ScopeRegistry.set_global_constraints(value)
+
+          block.call
+        ensure
+          ScopeRegistry.global_constraints = original
+        end
+
+        def without_global_constraints(&block)
+          original = ScopeRegistry.global_constraints
+          ScopeRegistry.global_constraints = {}
+
+          block.call
+        ensure
+          ScopeRegistry.global_constraints = original
+        end
+
+        def with_universal_global_constraint_time(time, &block)
+          original = ScopeRegistry.universal_global_constraint_time
+          ScopeRegistry.universal_global_constraint_time = time
+
+          block.call
+        ensure
+          ScopeRegistry.universal_global_constraint_time = original
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/{as_of_query → querying}/time_dimensions.rb

@@ -1,5 +1,5 @@
 module ActiveRecord::Temporal
-  module AsOfQuery
+  module Querying
     module TimeDimensions
       extend ActiveSupport::Concern
 
@@ -8,7 +8,9 @@ module ActiveRecord::Temporal
       end
 
       class_methods do
-        def set_time_dimensions(*dimensions)
+        def time_dimensions=(*dimensions)
+          dimensions = dimensions.flatten
+
           define_singleton_method(:time_dimensions) { dimensions }
           define_singleton_method(:default_time_dimension) { dimensions.first }
         end
@@ -17,7 +19,15 @@ module ActiveRecord::Temporal
         def default_time_dimension = nil
 
         def time_dimension_column?(time_dimension)
-          connection.column_exists?(table_name, time_dimension)
+          @time_dimension_column_cache ||= {}
+
+          @time_dimension_column_cache[time_dimension] ||= connection.column_exists?(table_name, time_dimension)
+        end
+
+        def time_dimension_columns
+          time_dimensions.select do |dimension|
+            time_dimension_column?(dimension)
+          end
         end
       end
 

data/lib/activerecord/temporal/querying/where_clause_refinement.rb

@@ -0,0 +1,17 @@
+module ActiveRecord::Temporal
+  module Querying
+    module WhereClauseRefinement
+      refine ActiveRecord::Relation::WhereClause do
+        def except_contains(columns)
+          columns = columns.map(&:to_s)
+
+          remaining_predications = predicates.reject do |node|
+            node.is_a?(Arel::Nodes::Contains) && columns.include?(node.left.name)
+          end
+
+          self.class.new(remaining_predications)
+        end
+      end
+    end
+  end
+end