activerecord-temporal 0.1.0 → 0.3.0

data/lib/activerecord/temporal/querying.rb

@@ -0,0 +1,95 @@
+module ActiveRecord::Temporal
+  module Querying
+    class RangeError < StandardError; end
+
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def resolve_time_coords(time_or_time_coords)
+        return time_or_time_coords if time_or_time_coords.is_a?(Hash)
+
+        {default_time_dimension.to_sym => time_or_time_coords}
+      end
+    end
+
+    included do
+      include AssociationMacros
+      include TimeDimensions
+      include PredicateBuilder::Handlers
+
+      delegate :resolve_time_coords, to: :class
+
+      default_scope do
+        at_time(Querying::ScopeRegistry.global_constraints_for(time_dimensions))
+      end
+
+      scope :as_of, ->(time) do
+        time_coords = resolve_time_coords(time)
+
+        at_time(time_coords).time_tags(time_coords)
+      end
+
+      scope :at_time, ->(time) do
+        time_coords = resolve_time_coords(time)
+
+        constraints = time_coords.slice(*time_dimension_columns)
+
+        return if constraints.empty?
+
+        rewhere_contains(constraints.transform_values { |v| contains(v) })
+      end
+    end
+
+    def time_tags
+      @time_tags || {}
+    end
+
+    def time_tags=(value)
+      @time_tags = value&.slice(*time_dimensions)
+    end
+
+    def time_tag
+      time_tags[default_time_dimension]
+    end
+
+    def time_tags_for(time_dimensions)
+      time_tags.slice(*time_dimensions)
+    end
+
+    def as_of!(time)
+      time_coords = resolve_time_coords(time)
+
+      ensure_time_tags_in_bounds!(time_coords)
+
+      reload
+
+      self.time_tags = time_coords
+    end
+
+    def as_of(time)
+      time_coords = resolve_time_coords(time)
+
+      self.class.as_of(time_coords).find_by(self.class.primary_key => [id])
+    end
+
+    def initialize_time_tags_from_relation(relation)
+      associations = relation.includes_values | relation.eager_load_values
+
+      self.time_tags = relation.time_tag_values
+
+      AssociationWalker.each_target(self, associations) do |target|
+        target.time_tags = relation.time_tag_values
+      end
+    end
+
+    private
+
+    def ensure_time_tags_in_bounds!(time_tags)
+      time_tags.each do |dimension, time|
+        if time_dimension_column?(dimension) && !time_dimension(dimension).cover?(time)
+          raise RangeError, "#{time} is outside of '#{dimension}' range"
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/scoping.rb

@@ -0,0 +1,7 @@
+module ActiveRecord::Temporal
+  module Scoping
+    def temporal_scoping
+      Querying::Scoping
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/history_model.rb

@@ -0,0 +1,47 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module HistoryModel
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def polymorphic_class_for(name)
+          super.version_model
+        end
+
+        def sti_name
+          superclass.sti_name
+        end
+
+        def find_sti_class(type_name)
+          superclass.send(:find_sti_class, type_name).history_model
+        end
+
+        def finder_needs_type_condition?
+          superclass.finder_needs_type_condition?
+        end
+      end
+
+      included do
+        include Querying
+
+        if include?(SystemVersioned)
+          self.table_name = history_table_name
+          self.primary_key = Array(primary_key) + [:system_period]
+        end
+
+        self.time_dimensions = time_dimensions + [:system_period]
+
+        reflect_on_all_associations.each do |reflection|
+          next if reflection.scope&.temporal_scope?
+
+          send(
+            reflection.macro,
+            reflection.name,
+            reflection.scope,
+            **reflection.options.merge(temporal: true)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/history_model_namespace.rb

@@ -0,0 +1,45 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module HistoryModelNamespace
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def const_missing(model_name)
+          model = join(@root, model_name).constantize
+        rescue NameError
+          super
+        else
+          unless model.is_a?(Class) && model < ActiveRecord::Base
+            raise NameError, "#{model} is not a descendent of ActiveRecord::Base"
+          end
+
+          history_model = Class.new(model) do
+            include HistoryModel
+          end
+
+          const_set(model_name, history_model)
+        end
+
+        def namespace(name, &block)
+          new_namespace = Module.new do
+            include HistoryModelNamespace
+          end
+
+          const_set(name, new_namespace)
+
+          new_namespace.root(join(@root, name))
+
+          new_namespace.instance_eval(&block) if block
+        end
+
+        def root(name)
+          @root = name
+        end
+
+        def join(base, name)
+          [base, name].compact.join("::")
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/history_models.rb

@@ -0,0 +1,29 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module HistoryModels
+      class Error < StandardError; end
+
+      extend ActiveSupport::Concern
+
+      class_methods do
+        delegate :at_time, :as_of, to: :history
+
+        def history_model
+          raise Error, "abstract classes cannot have a history model" if abstract_class?
+
+          [history_model_namespace, name].join("::").constantize
+        end
+
+        def history
+          ActiveRecord::Relation.create(history_model)
+        end
+
+        private
+
+        def history_model_namespace
+          History
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning/schema_creation.rb

@@ -30,7 +30,8 @@ module ActiveRecord::Temporal
           verb: :insert,
           source_table: o.source_table,
           history_table: o.history_table,
-          columns: o.columns
+          columns: o.columns,
+          gem_version: o.gem_version
         }
 
         <<~SQL
@@ -52,7 +53,7 @@ module ActiveRecord::Temporal
 
       def visit_UpdateHookDefinition(o)
         column_names = o.columns.map { |c| quote_column_name(c) }
-        primary_key_quoted = o.primary_key.map { |c| quote_column_name(c) }
+        primary_key_quoted = Array(o.primary_key).map { |c| quote_column_name(c) }
         fields = column_names.join(", ")
         values = column_names.map { |c| "NEW.#{c}" }.join(", ")
         update_pk_predicates = primary_key_quoted.map { |c| "#{c} = OLD.#{c}" }.join(" AND ")
@@ -64,7 +65,8 @@ module ActiveRecord::Temporal
           source_table: o.source_table,
           history_table: o.history_table,
           columns: o.columns,
-          primary_key: o.primary_key
+          primary_key: o.primary_key,
+          gem_version: o.gem_version
         }
 
         <<~SQL
@@ -94,14 +96,15 @@ module ActiveRecord::Temporal
       end
 
       def visit_DeleteHookDefinition(o)
-        primary_key_quoted = o.primary_key.map { |c| quote_column_name(c) }
+        primary_key_quoted = Array(o.primary_key).map { |c| quote_column_name(c) }
         function_name = versioning_function_name(o.source_table, :delete)
         pk_predicates = primary_key_quoted.map { |c| "#{c} = OLD.#{c}" }.join(" AND ")
         metadata = {
           verb: :delete,
           source_table: o.source_table,
           history_table: o.history_table,
-          primary_key: o.primary_key
+          primary_key: o.primary_key,
+          gem_version: o.gem_version
         }
 
         <<~SQL

data/lib/activerecord/temporal/system_versioning/schema_definitions.rb

@@ -1,37 +1,39 @@
 module ActiveRecord::Temporal
   module SystemVersioning
     class VersioningHookDefinition
-      attr_accessor :source_table, :history_table, :columns, :primary_key
+      attr_accessor :source_table, :history_table, :columns, :primary_key, :gem_version
 
       def initialize(
         source_table,
         history_table,
         columns:,
-        primary_key:
+        primary_key:,
+        gem_version:
       )
         @source_table = source_table
         @history_table = history_table
         @columns = columns
         @primary_key = primary_key
+        @gem_version = gem_version
       end
 
       def insert_hook
-        InsertHookDefinition.new(@source_table, @history_table, @columns)
+        InsertHookDefinition.new(@source_table, @history_table, @columns, @gem_version)
       end
 
       def update_hook
-        UpdateHookDefinition.new(@source_table, @history_table, @columns, @primary_key)
+        UpdateHookDefinition.new(@source_table, @history_table, @columns, @primary_key, @gem_version)
       end
 
       def delete_hook
-        DeleteHookDefinition.new(@source_table, @history_table, @primary_key)
+        DeleteHookDefinition.new(@source_table, @history_table, @primary_key, @gem_version)
       end
     end
 
-    InsertHookDefinition = Struct.new(:source_table, :history_table, :columns)
+    InsertHookDefinition = Struct.new(:source_table, :history_table, :columns, :gem_version)
 
-    UpdateHookDefinition = Struct.new(:source_table, :history_table, :columns, :primary_key)
+    UpdateHookDefinition = Struct.new(:source_table, :history_table, :columns, :primary_key, :gem_version)
 
-    DeleteHookDefinition = Struct.new(:source_table, :history_table, :primary_key)
+    DeleteHookDefinition = Struct.new(:source_table, :history_table, :primary_key, :gem_version)
   end
 end

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

@@ -2,45 +2,67 @@ module ActiveRecord::Temporal
   module SystemVersioning
     module SchemaStatements
       def create_versioning_hook(source_table, history_table, **options)
-        columns = options.fetch(:columns)&.map(&:to_s)
-        primary_key = Array(options.fetch(:primary_key, :id))
+        options.assert_valid_keys(:columns, :primary_key)
 
-        ensure_table_exists!(source_table)
-        ensure_table_exists!(history_table)
-        ensure_columns_match!(source_table, history_table, columns)
-        ensure_columns_exists!(source_table, primary_key)
+        columns = options.fetch(:columns, :all)
+        primary_key = options.fetch(:primary_key, :id)
+
+        column_names = if columns == :all
+          columns(source_table).map(&:name)
+        else
+          Array(columns).map(&:to_s)
+        end
+
+        primary_key = if primary_key.is_a?(Array) && primary_key.length == 1
+          primary_key.first
+        else
+          primary_key
+        end
+
+        assert_table_exists!(source_table)
+        assert_table_exists!(history_table)
+        assert_columns_match!(source_table, history_table, column_names)
+        assert_columns_exists!(source_table, Array(primary_key))
+        assert_primary_key_matches!(source_table, Array(primary_key))
 
         schema_creation = SchemaCreation.new(self)
 
         hook_definition = VersioningHookDefinition.new(
           source_table,
           history_table,
-          columns: columns,
-          primary_key: primary_key
+          columns: column_names,
+          primary_key: primary_key,
+          gem_version: VERSION
         )
 
         execute schema_creation.accept(hook_definition)
       end
 
-      def drop_versioning_hook(source_table, history_table, columns: nil)
+      def drop_versioning_hook(source_table, history_table, **options)
+        options.assert_valid_keys(:columns, :primary_key, :if_exists)
+
         %i[insert update delete].each do |verb|
           function_name = versioning_function_name(source_table, verb)
 
-          execute "DROP FUNCTION #{function_name}() CASCADE"
+          sql = "DROP FUNCTION"
+          sql << " IF EXISTS" if options[:if_exists]
+          sql << " #{function_name}() CASCADE"
+
+          execute sql
         end
       end
 
       def versioning_hook(source_table)
         update_function_name = versioning_function_name(source_table, :update)
 
-        row = execute(<<~SQL.squish).first
+        row = exec_query(<<~SQL.squish, "SQL", [update_function_name]).first
           SELECT
             pg_proc.proname as function_name,
             obj_description(pg_proc.oid, 'pg_proc') as comment
           FROM pg_proc
           JOIN pg_namespace ON pg_proc.pronamespace = pg_namespace.oid
           WHERE pg_namespace.nspname NOT IN ('pg_catalog', 'information_schema')
-            AND pg_proc.proname = '#{update_function_name}'
+            AND pg_proc.proname = $1
         SQL
 
         return unless row
@@ -51,27 +73,33 @@ module ActiveRecord::Temporal
           metadata["source_table"],
           metadata["history_table"],
           columns: metadata["columns"],
-          primary_key: metadata["primary_key"]
+          primary_key: metadata["primary_key"],
+          gem_version: metadata["gem_version"]
         )
       end
 
       def change_versioning_hook(source_table, history_table, options)
+        options.assert_valid_keys(:add_columns, :remove_columns)
+
         add_columns = (options[:add_columns] || []).map(&:to_s)
         remove_columns = (options[:remove_columns] || []).map(&:to_s)
 
-        ensure_table_exists!(source_table)
-        ensure_table_exists!(history_table)
-        ensure_columns_match!(source_table, history_table, add_columns)
+        assert_table_exists!(source_table)
+        assert_table_exists!(history_table)
+        assert_columns_match!(source_table, history_table, add_columns)
 
         hook_definition = versioning_hook(source_table)
 
-        ensure_hook_has_columns!(hook_definition, remove_columns)
+        assert_hook_has_columns!(hook_definition, remove_columns)
 
         drop_versioning_hook(source_table, history_table)
 
         new_columns = hook_definition.columns + add_columns - remove_columns
 
-        create_versioning_hook(source_table, history_table, columns: new_columns)
+        create_versioning_hook source_table,
+          history_table,
+          columns: new_columns,
+          primary_key: hook_definition.primary_key
       end
 
       def history_table(source_table)
@@ -89,15 +117,18 @@ module ActiveRecord::Temporal
 
       private
 
-      def ensure_table_exists!(table_name)
+      def validate_create_versioning_hook_options!(options)
+      end
+
+      def assert_table_exists!(table_name)
         return if table_exists?(table_name)
 
         raise ArgumentError, "table '#{table_name}' does not exist"
       end
 
-      def ensure_columns_match!(source_table, history_table, column_names)
-        ensure_columns_exists!(source_table, column_names)
-        ensure_columns_exists!(history_table, column_names)
+      def assert_columns_match!(source_table, history_table, column_names)
+        assert_columns_exists!(source_table, column_names)
+        assert_columns_exists!(history_table, column_names)
 
         column_names.each do |column|
           source_column = columns(source_table).find { _1.name == column }
@@ -109,7 +140,7 @@ module ActiveRecord::Temporal
         end
       end
 
-      def ensure_columns_exists!(table_name, column_names)
+      def assert_columns_exists!(table_name, column_names)
         column_names.each do |column|
           next if column_exists?(table_name, column)
 
@@ -117,7 +148,14 @@ module ActiveRecord::Temporal
         end
       end
 
-      def ensure_hook_has_columns!(hook, column_names)
+      def assert_primary_key_matches!(source_table, primary_key)
+        primary_key = primary_key&.map(&:to_s)
+        unless Array(primary_key(source_table)) == primary_key
+          raise ArgumentError, "table '#{source_table}' does not have primary key #{primary_key}"
+        end
+      end
+
+      def assert_hook_has_columns!(hook, column_names)
         column_names.each do |column_name|
           next if hook.columns.include?(column_name)
 

data/lib/activerecord/temporal/system_versioning/system_versioned.rb

@@ -0,0 +1,13 @@
+module ActiveRecord::Temporal
+  module SystemVersioning
+    module SystemVersioned
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def history_table_name
+          table_name + "_history" if table_name
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/temporal/system_versioning.rb

@@ -2,25 +2,13 @@ module ActiveRecord::Temporal
   module SystemVersioning
     extend ActiveSupport::Concern
 
-    class_methods do
-      def history_table
-        connection.history_table(table_name)
-      end
-
-      def primary_key_from_db
-        Array(connection.primary_key(table_name)).map(&:to_sym)
-      end
-
-      def version_model
-        "Version::#{name}".constantize
-      end
+    included do
+      include HistoryModels
+    end
 
-      def system_versioning(namespace: "Version")
-        unless Object.const_defined?(namespace)
-          mod = Module.new
-          mod.include(Namespace)
-          Object.const_set(namespace, mod)
-        end
+    class_methods do
+      def system_versioned
+        include SystemVersioned
       end
     end
   end

data/lib/activerecord/temporal/version.rb

@@ -1,3 +1,3 @@
 module ActiveRecord::Temporal
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/activerecord/temporal.rb

@@ -1,63 +1,94 @@
 require "active_support"
 
-require_relative "temporal/application_versioning"
-require_relative "temporal/as_of_query"
-require_relative "temporal/as_of_query/association_macros"
-require_relative "temporal/as_of_query/association_scope"
-require_relative "temporal/as_of_query/association_walker"
-require_relative "temporal/as_of_query/query_methods"
-require_relative "temporal/as_of_query/scope_registry"
-require_relative "temporal/as_of_query/time_dimensions"
+require_relative "temporal/application_versioning/application_versioned"
+require_relative "temporal/querying/association_macros"
+require_relative "temporal/querying/association_scope"
+require_relative "temporal/querying/association_walker"
+require_relative "temporal/querying/predicate_builder/handlers"
+require_relative "temporal/querying/query_methods"
+require_relative "temporal/querying/scope_registry"
+require_relative "temporal/querying/scoping"
+require_relative "temporal/querying/time_dimensions"
 require_relative "temporal/patches/association_reflection"
 require_relative "temporal/patches/join_dependency"
 require_relative "temporal/patches/merger"
 require_relative "temporal/patches/relation"
 require_relative "temporal/patches/through_association"
-require_relative "temporal/system_versioning"
 require_relative "temporal/system_versioning/command_recorder"
-require_relative "temporal/system_versioning/namespace"
-require_relative "temporal/system_versioning/model"
+require_relative "temporal/system_versioning/history_model_namespace"
+require_relative "temporal/system_versioning/history_model"
+require_relative "temporal/system_versioning/history_models"
 require_relative "temporal/system_versioning/schema_creation"
 require_relative "temporal/system_versioning/schema_definitions"
 require_relative "temporal/system_versioning/schema_statements"
+require_relative "temporal/system_versioning/system_versioned"
+require_relative "temporal/application_versioning"
+require_relative "temporal/querying"
+require_relative "temporal/scoping"
+require_relative "temporal/system_versioning"
+require_relative "temporal/version"
+
+module ActiveRecord::Temporal
+  def system_versioning
+    include SystemVersioning
+  end
+
+  def application_versioning(**options)
+    include Querying
+    include ApplicationVersioning
+
+    self.time_dimensions = options[:dimensions] if options[:dimensions]
+  end
+end
 
 ActiveSupport.on_load(:active_record) do
-  require "active_record/connection_adapters/postgresql_adapter" # TODO: add test
+  require "active_record/connection_adapters/postgresql_adapter"
+
+  ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+    .include ActiveRecord::Temporal::SystemVersioning::SchemaStatements
+
+  ActiveRecord::Migration::CommandRecorder
+    .include ActiveRecord::Temporal::SystemVersioning::CommandRecorder
 
-  ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.include(ActiveRecord::Temporal::SystemVersioning::SchemaStatements)
-  ActiveRecord::Migration::CommandRecorder.include(ActiveRecord::Temporal::SystemVersioning::CommandRecorder)
-  ActiveRecord::Relation.include(ActiveRecord::Temporal::AsOfQuery::QueryMethods)
+  ActiveRecord::Relation
+    .include ActiveRecord::Temporal::Querying::QueryMethods
 
   # Patches
 
-  # Patches the `build_arel` method wrap itself in the as-of query scope registry.
+  # Patches `#build_arel` to  wrap itself in the as-of query scope registry.
   # This is what allows temporal association scopes to be aware of the time-scope
   # value of the relation that included them.
   #
-  # Patches the `instantiate_records` method to call `initialize_time_scope_from_relation`
+  # Patches `#instantiate_records` method to call `initialize_time_tags_from_relation`
   # on each loaded record.
-  ActiveRecord::Relation.prepend(ActiveRecord::Temporal::Patches::Relation)
+  ActiveRecord::Relation
+    .prepend ActiveRecord::Temporal::Patches::Relation
 
-  # Patches the `merge` method (called by `Relation#merge`) to handle the new
-  # query method `time_scope` that this gem adds.
-  ActiveRecord::Relation::Merger.prepend(ActiveRecord::Temporal::Patches::Merger)
+  # Patches `#merge` (called by `Relation#merge`) to handle the new query method
+  # `time_tags` that this gem adds.
+  ActiveRecord::Relation::Merger
+    .prepend ActiveRecord::Temporal::Patches::Merger
 
-  # Patches the preloader's `through_scope` method to pass along the relation's
-  # time-scope values when it handles has-many-through associations. The handler
-  # for has-many assoication uses `Relation#merge`, but this one doesn't.
-  ActiveRecord::Associations::Preloader::ThroughAssociation.prepend(ActiveRecord::Temporal::Patches::ThroughAssociation)
+  # Patches `#through_scope` to pass along the relation's time tag values when it
+  # handles has-many-through associations. The handler for has-many association
+  # uses `Relation#merge`, but this one doesn't.
+  ActiveRecord::Associations::Preloader::ThroughAssociation
+    .prepend ActiveRecord::Temporal::Patches::ThroughAssociation
 
   # This permits association scopes generated by this gem to be eager-load if they
-  # are "optionally instance-dependent." That is to say, they accept arguments,
-  # but don't require any arguments.
+  # are "optionally instance-dependent." That is to say, they accept but don't
+  # require arguments.
   #
-  # I think permitting eager-loading optionally instance-dependent association
-  # scopes would make sense as a general feature. See this PR for my justification:
+  # 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
-  ActiveRecord::Reflection::AssociationReflection.prepend(ActiveRecord::Temporal::Patches::AssociationReflection)
+  ActiveRecord::Reflection::AssociationReflection
+    .prepend ActiveRecord::Temporal::Patches::AssociationReflection
 
   # 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.
-  ActiveRecord::Associations::JoinDependency.prepend(ActiveRecord::Temporal::Patches::JoinDependency)
+  # 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.
+  ActiveRecord::Associations::JoinDependency
+    .prepend ActiveRecord::Temporal::Patches::JoinDependency
 end