activerecord-temporal 0.1.0 → 0.2.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 "not head revision" unless head_revision?
+
+        Revision.new(self, time, save: true)
+      end
+
+      def revision
+        revision_at(scope_time || 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(scope_time || Time.current)
+      end
+
+      def inactivate_at(time)
+        raise "not head revision" unless head_revision?
+
+        set_time_dimension_end(time)
+        save
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module ActiveRecord::Temporal
+  module ApplicationVersioning
+    module CommandRecorder
+      def create_application_versioned_table(*args)
+        record(:create_application_versioned_table, args)
+      end
+      ruby2_keywords(:create_application_versioned_table)
+
+      def invert_create_application_versioned_table(args)
+        [:drop_table, args]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module ActiveRecord::Temporal
+  module ApplicationVersioning
+    module Migration
+      extend ActiveSupport::Concern
+
+      included do
+        prepend Patches
+      end
+
+      module Patches
+        def create_table(table_name, id: :primary_key, primary_key: nil, force: nil, **options, &block)
+          application_versioning = options.delete(:application_versioning)
+
+          if application_versioning
+            create_application_versioned_table(
+              table_name, id:, primary_key:, force:, **options, &block
+            )
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module ActiveRecord::Temporal
+  module ApplicationVersioning
+    module SchemaStatements
+      def create_application_versioned_table(table_name, **options, &block)
+        pk_option = options[:primary_key]
+
+        primary_key = if options[:primary_key]
+          Array(options[:primary_key]) | [:version]
+        else
+          [:id, :version]
+        end
+
+        exclusion_constraint_expression = (primary_key - [:version]).map do |col|
+          "#{col} WITH ="
+        end.join(", ") + ", validity WITH &&"
+
+        options = options.merge(primary_key: primary_key)
+
+        create_table(table_name, **options) do |t|
+          unless pk_option.is_a?(Array)
+            t.bigserial pk_option || :id, null: false
+          end
+
+          t.bigint :version, null: false, default: 1
+          t.tstzrange :validity, null: false
+          t.exclusion_constraint exclusion_constraint_expression, using: :gist
+
+          instance_exec(t, &block)
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/application_versioning.rb

@@ -2,76 +2,10 @@ 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
-
-        [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/command_recorder.rb

@@ -0,0 +1,23 @@
+module ActiveRecord::Temporal
+  module Patches
+    module CommandRecorder
+      def invert_drop_table(args, &block)
+        if extract_options(args).delete(:system_versioning)
+          raise ActiveRecord::IrreversibleMigration, "drop_table with system versioning is not supported"
+        end
+
+        super
+      end
+
+      private
+
+      def extract_options(array)
+        if array.last.is_a?(Hash) && array.last.extractable_options?
+          array.last
+        else
+          {}
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,8 @@
 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 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