historiographer 4.1.5 → 4.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5c265010aca1b01c9eda903723571b16456965c208879096542e9aadad079df
-  data.tar.gz: 59553cbf0764e820570dcb2bce9f6f6188d6920f16f0bf4fbb0cf5c4bb6ea52b
+  metadata.gz: 28891ab31232a7eae8efccd015269069d992eb775259c6a6b9e738da1df69aed
+  data.tar.gz: 7a794f1a26351b47d194a0b8d18eb0222d49e9dd7d2b6cdcf90467d94cea62b0
 SHA512:
-  metadata.gz: 0fc94e06266d5d21d28c4521e5ee9da3f90af4cbcea5594814b1916474929b42f4db37907acf0c104477b98db8e4f78082887a24f9495b7699b237f11bc1c9f9
-  data.tar.gz: 4b819a457d62ac154994b445b88ed7574341d4a366a24318ca64708d110d1081b6fb1032a9d505115b47eaffaf1efcc6e2bdabe39a56153c345ebcb8a8e57934
+  metadata.gz: 16ee4305c1aa8c6f09a13b042185afceea10fd18c0a19f7dba360bcab65a7f1a270dce78e24f15f2a30806fa4f4bcdf5ea6c10ecb81060b3dca02724918d7f5e
+  data.tar.gz: e66e7f2a31b5f65689f112ae6b43adeff5e286c42aeb6ed2ffc8931e1a75426dac3f4cb615b2fc06a537c74f070f4f2a245fe4668be8814b8382bd5084336651

data/README.md

@@ -137,7 +137,7 @@ Historiographer fully supports Single Table Inheritance, both with the default `
 ### Default STI with `type` column
 
 ```ruby
-class Post < ApplicationRecord
+class Post < ActiveRecord::Base
   include Historiographer
 end
 
@@ -145,7 +145,7 @@ class PrivatePost < Post
 end
 
 # The history classes follow the same inheritance pattern:
-class PostHistory < ApplicationRecord
+class PostHistory < ActiveRecord::Base
   include Historiographer::History
 end
 
@@ -170,9 +170,9 @@ history.type #=> "PrivatePostHistory"
 You can also use a custom column for STI instead of the default `type`:
 
 ```ruby
-class MLModel < ApplicationRecord
-  include Historiographer
+class MLModel < ActiveRecord::Base
   self.inheritance_column = :model_type
+  include Historiographer
 end
 
 class XGBoost < MLModel
@@ -291,12 +291,45 @@ trained_version = model.histories.find_by(metadata: { stage: "post_training" })
 ```
 
 This combination of STI and snapshots is particularly valuable for:
+
 - Model governance and compliance
 - A/B testing different model types
 - Debugging model behavior
 - Reproducing historical predictions
 - Maintaining audit trails for regulatory requirements
 
+## Namespaced Models
+
+When using namespaced models, Rails handles foreign key naming differently than with non-namespaced models. For example, if you have a model namespaced like this:
+
+```ruby
+module EasyML
+  class Dataset
+     self.table_name = "easy_ml_datasets"
+  end
+end
+```
+
+Rails will expect foreign keys to be formatted using just the model name (without the namespace) like this:
+
+```ruby
+:dataset_id
+```
+
+Therefore, when creating history migrations for namespaced models, you need to specify the foreign key name explicitly:
+
+```ruby
+class CreateEasyMLDatasetHistories < ActiveRecord::Migration
+  def change
+    create_table :easy_ml_dataset_histories do |t|
+      t.histories(foreign_key: :dataset_id) # instead of using the table name — easy_ml_dataset_id
+    end
+  end
+end
+```
+
+This ensures that the foreign key relationships are properly established between your namespaced models and their history tables.
+
 ## Getting Started
 
 Whenever you include the `Historiographer` gem in your ActiveRecord model, it allows you to insert, update, or delete data as you normally would.
@@ -305,6 +338,11 @@ Whenever you include the `Historiographer` gem in your ActiveRecord model, it al
 class Post < ActiveRecord::Base
   include Historiographer
 end
+
+class PostHistory < ActiveRecord::Base
+  self.table_name = "post_histories"
+  include Historiographer::History
+end
 ```
 
 ### History Modes
@@ -337,6 +375,29 @@ class Comment < ActiveRecord::Base
 end
 ```
 
+The class-level mode setting takes precedence over the global configuration. This allows you to:
+
+- Have different history tracking strategies for different models
+- Set most models to use snapshots while keeping detailed history for critical models
+- Optimize storage by only tracking detailed history where needed
+
+For example:
+
+```ruby
+# Global setting for most models
+Historiographer::Configuration.mode = :snapshot_only
+
+class Order < ActiveRecord::Base
+  include Historiographer
+  # Uses global :snapshot_only mode
+end
+
+class Payment < ActiveRecord::Base
+  include Historiographer
+  historiographer_mode :histories  # Override to record histories of every change
+end
+```
+
 ## Create A Migration
 
 You need a separate table to store histories for each model.
@@ -391,12 +452,18 @@ The primary model should include `Historiographer`:
 class Post < ActiveRecord::Base
   include Historiographer
 end
+
+class PostHistory < ActiveRecord::Base
+  self.table_name = "post_histories"
+  include Historiographer::History
+end
 ```
 
 You should also make a `PostHistory` class if you're going to query `PostHistory` from Rails:
 
 ```ruby
 class PostHistory < ActiveRecord::Base
+  self.table_name = "post_histories"
 end
 ```
 

data/lib/historiographer/history/instance_methods.rb

@@ -0,0 +1,98 @@
+module Historiographer
+  module History
+    module InstanceMethods
+      def destroy
+        false
+      end
+
+      def destroy!
+        false
+      end
+
+      def save(*args, **kwargs)
+        if persisted? && (changes.keys - %w(history_ended_at snapshot_id)).any?
+          false
+        else
+          super(*args, **kwargs)
+        end
+      end
+
+      def save!(*args, **kwargs)
+        if persisted? && (changes.keys - %w(history_ended_at snapshot_id)).any?
+          false
+        else
+          super(*args, **kwargs)
+        end
+      end
+
+      def snapshot
+        raise "Cannot snapshot a history model!"
+      end
+
+      def original_class
+        self.class.original_class
+      end
+
+      private
+
+      def dummy_instance
+        return @dummy_instance if @dummy_instance
+
+        cannot_keep_cols = %w(history_started_at history_ended_at history_user_id snapshot_id)
+        cannot_keep_cols += [self.class.inheritance_column.to_sym] if self.original_class.sti_enabled?
+        cannot_keep_cols += [self.class.history_foreign_key] 
+        cannot_keep_cols.map!(&:to_s)
+
+        attrs = attributes.clone
+        attrs[original_class.primary_key] = attrs[self.class.history_foreign_key]
+
+        instance = original_class.find_or_initialize_by(original_class.primary_key => attrs[original_class.primary_key])
+        instance.assign_attributes(attrs.except(*cannot_keep_cols))
+
+        # Create a module to hold methods from the history class
+        history_methods_module = Module.new
+
+        # Get methods defined directly in the history class, excluding baseline methods
+        history_methods = self.class.instance_methods(false) - baseline_methods
+
+        history_methods.each do |method_name|
+          next if instance.singleton_class.method_defined?(method_name)
+
+          method = self.class.instance_method(method_name)
+          history_methods_module.define_method(method_name) do |*args, &block|
+            method.bind(self.instance_variable_get(:@_history_instance)).call(*args, &block)
+          end
+        end
+
+        instance.singleton_class.prepend(history_methods_module)
+
+        self.class.reflect_on_all_associations.each do |reflection|
+          instance.singleton_class.class_eval do
+            define_method(reflection.name) do |*args, &block|
+              history_instance = instance.instance_variable_get(:@_history_instance)
+              history_instance.send(reflection.name, *args, &block)
+            end
+          end
+        end
+
+        instance.singleton_class.class_eval do
+          define_method(:class) do
+            history_instance = instance.instance_variable_get(:@_history_instance)
+            history_instance.class
+          end
+        end
+
+        instance.instance_variable_set(:@_history_instance, self)
+        @dummy_instance = instance
+      end
+
+      def forward_method(method_name, *args, &block)
+        if method_name == :class || method_name == 'class'
+          self.class
+        else
+          dummy_instance.send(method_name, *args, &block)
+        end
+      end
+    end
+  end
+end 

data/lib/historiographer/history.rb

@@ -61,6 +61,7 @@ module Historiographer
     extend ActiveSupport::Concern
 
     included do |base|
+      clear_validators! if respond_to?(:clear_validators!)
       #
       # A History class (e.g. RetailerProductHistory) will gain
       # access to a current scope, returning
@@ -91,6 +92,68 @@ module Historiographer
       foreign_class = foreign_class_name.constantize
       association_name   = foreign_class_name.split("::").last.underscore.to_sym # e.g. "RetailerProduct" => :retailer_product
 
+      # Store the original class for method delegation
+      class_variable_set(:@@original_class, foreign_class)
+      class_variable_set(:@@method_map, {})
+
+      # Add method_added hook to the original class
+      foreign_class.singleton_class.class_eval do
+        # Keep track of original method_added if it exists
+        if method_defined?(:method_added)
+          alias_method :original_method_added, :method_added
+        end
+
+        define_method(:method_added) do |method_name|
+          # Skip if we're already in the process of defining a method
+          return if Thread.current[:defining_historiographer_method]
+
+          begin
+            Thread.current[:defining_historiographer_method] = true
+            
+            # Call original method_added if it exists
+            original_method_added(method_name) if respond_to?(:original_method_added)
+
+            # Get the method object to check if it's from our class (not inherited)
+            method_obj = instance_method(method_name)
+            return unless method_obj.owner == self
+
+            # Skip if we've already defined this method in the history class
+            return if foreign_class.history_class.method_defined?(method_name)
+
+            # Define the method in the history class
+            foreign_class.history_class.set_method_map(method_name, false)
+            foreign_class.history_class.class_eval do
+              define_method(method_name) do |*args, &block|
+                forward_method(method_name, *args, &block)
+              end
+            end
+          ensure
+            Thread.current[:defining_historiographer_method] = false
+          end
+        end
+      end
+
+      foreign_class.columns.map(&:name).each do |method_name|
+        define_method(method_name) do |*args, &block|
+          forward_method(method_name, *args, &block)
+        end
+      end
+
+      # Add method_missing for any methods we might have missed
+      def method_missing(method_name, *args, &block)
+        original_class = self.class.class_variable_get(:@@original_class)
+        if original_class.method_defined?(method_name)
+          forward_method(method_name, *args, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        original_class = self.class.class_variable_get(:@@original_class)
+        original_class.method_defined?(method_name) || super
+      end
+
       #
       # Historiographer will automatically setup the association
       # to the primary class (e.g. RetailerProduct)
@@ -147,19 +210,19 @@ module Historiographer
       #
       # If the record was not already persisted, proceed as normal.
       #
-      def save(*args)
+      def save(*args, **kwargs)
         if persisted? && (changes.keys - %w(history_ended_at snapshot_id)).any?
           false
         else
-          super
+          super(*args, **kwargs)
         end
       end
 
-      def save!(*args)
+      def save!(*args, **kwargs)
         if persisted? && (changes.keys - %w(history_ended_at snapshot_id)).any?
           false
         else
-          super
+          super(*args, **kwargs)
         end
       end
 
@@ -167,11 +230,87 @@ module Historiographer
       # Orders by history_started_at and id to handle cases where multiple records
       # have the same history_started_at timestamp
       scope :latest_snapshot, -> {
-        where.not(snapshot_id: nil).order('id DESC').limit(1)&.first || none
+        where.not(snapshot_id: nil)
+          .select('DISTINCT ON (snapshot_id) *')
+          .order('snapshot_id, history_started_at DESC, id DESC')
       }
+
+      # Dynamically define associations on the history class
+      foreign_class.reflect_on_all_associations.each do |association|
+        define_history_association(association)
+      end
+
+      def snapshot
+        raise "Cannot snapshot a history model!"
+      end
+
     end
 
     class_methods do
+      def method_added(method_name)
+        set_method_map(method_name, true)
+      end
+
+      def set_method_map(method_name, is_overridden)
+        mm = method_map
+        mm[method_name.to_sym] = is_overridden
+        class_variable_set(:@@method_map, mm)
+      end
+
+      def method_map
+        unless class_variable_defined?(:@@method_map)
+          class_variable_set(:@@method_map, {})
+        end
+        class_variable_get(:@@method_map) || {}
+      end
+
+      def original_class
+        unless class_variable_defined?(:@@original_class)
+          class_variable_set(:@@original_class, self.name.gsub(/History$/, '').constantize)
+        end
+
+        class_variable_get(:@@original_class)
+      end
+
+      def define_history_association(association)
+        if association.is_a?(Symbol) || association.is_a?(String)
+          association = original_class.reflect_on_association(association)
+        end
+        assoc_name = association.name
+        assoc_module = association.active_record.module_parent
+        assoc_history_class_name = "#{association.class_name}History"
+
+        begin
+          assoc_module.const_get(assoc_history_class_name)
+          assoc_history_class_name = "#{assoc_module}::#{assoc_history_class_name}" unless assoc_history_class_name.match?(Regexp.new("#{assoc_module}::"))
+        rescue
+        end
+
+        assoc_foreign_key = association.foreign_key
+
+        # Skip through associations to history classes to avoid infinite loops
+        return if association.class_name.end_with?('History')
+
+        # Always use the history class if it exists
+        assoc_class = assoc_history_class_name.safe_constantize || OpenStruct.new(name: association.class_name)
+        assoc_class_name = assoc_class.name
+
+        # Define the scope to filter by snapshot_id for history associations
+        scope = if assoc_class_name.match?(/History/)
+                  ->(history_instance) { where(snapshot_id: history_instance.snapshot_id) }
+                else
+                  ->(history_instance) { all }
+                end
+
+        case association.macro
+        when :belongs_to
+          belongs_to assoc_name, scope, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: assoc_foreign_key
+        when :has_one
+          has_one assoc_name, scope, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: history_foreign_key
+        when :has_many
+          has_many assoc_name, scope, class_name: assoc_class_name, foreign_key: assoc_foreign_key, primary_key: history_foreign_key
+        end
+      end
       #
       # The foreign key to the primary class.
       #
@@ -180,7 +319,8 @@ module Historiographer
       def history_foreign_key
         return @history_foreign_key if @history_foreign_key
 
-        @history_foreign_key = sti_base_class.table_name.singularize.foreign_key
+        # CAN THIS BE TABLE OR MODEL?
+        @history_foreign_key = sti_base_class.name.singularize.foreign_key
       end
 
       def sti_base_class
@@ -194,5 +334,71 @@ module Historiographer
         @sti_base_class = base_class
       end
     end
+
+    def original_class
+      self.class.original_class
+    end
+
+  private
+    def dummy_instance
+      return @dummy_instance if @dummy_instance
+
+      cannot_keep_cols = %w(history_started_at history_ended_at history_user_id snapshot_id)
+      cannot_keep_cols += [self.class.inheritance_column.to_sym] if self.original_class.sti_enabled?
+      cannot_keep_cols += [self.class.history_foreign_key] 
+      cannot_keep_cols.map!(&:to_s)
+
+      attrs = attributes.clone
+      attrs[original_class.primary_key] = attrs[self.class.history_foreign_key]
+
+      instance = original_class.find_or_initialize_by(original_class.primary_key => attrs[original_class.primary_key])
+      instance.assign_attributes(attrs.except(*cannot_keep_cols))
+
+      # Filter out any methods that are not overridden on the history class
+      history_methods = self.class.instance_methods(false)
+      history_class_location = Module.const_source_location(self.class.name).first
+      history_methods.select! do |method| 
+        self.class.instance_method(method).source_location.first == history_class_location
+      end
+
+      history_methods.each do |method_name|
+        instance.singleton_class.class_eval do 
+          define_method(method_name) do |*args, &block|
+            history_instance = instance.instance_variable_get(:@_history_instance)
+            history_instance.send(method_name, *args, &block)
+          end
+        end
+      end
+
+      # For each association in the history class
+      self.class.reflect_on_all_associations.each do |reflection|
+        # Define a method that forwards to the history association
+        instance.singleton_class.class_eval do
+          define_method(reflection.name) do |*args, &block|
+            history_instance = instance.instance_variable_get(:@_history_instance)
+            history_instance.send(reflection.name, *args, &block)
+          end
+        end
+      end
+
+      # Override class method to return history class
+      instance.singleton_class.class_eval do
+        define_method(:class) do
+          history_instance = instance.instance_variable_get(:@_history_instance)
+          history_instance.class
+        end
+      end
+
+      instance.instance_variable_set(:@_history_instance, self)
+      @dummy_instance = instance
+    end
+
+    def forward_method(method_name, *args, &block)
+      if method_name == :class || method_name == 'class'
+        self.class
+      else
+        dummy_instance.send(method_name, *args, &block)
+      end
+    end
   end
 end

data/lib/historiographer/history_migration.rb

@@ -16,10 +16,11 @@ module Historiographer
     # Will automatically add user_id, history_started_at,
     # and history_ended_at columns
     #
-    def histories(except: [], only: [], no_business_columns: false, index_names: {})
+    def histories(except: [], only: [], no_business_columns: false, index_names: {}, foreign_key: nil)
       index_names.symbolize_keys!
-      original_table_name = self.name.gsub(/_histories$/) {}.pluralize
-      foreign_key         = original_table_name.singularize.foreign_key
+      history_table_name = self.name
+      original_table_name = history_table_name.gsub(/_histories$/) {}.pluralize
+      foreign_key ||= original_table_name.singularize.foreign_key
 
       class_definer = Class.new(ActiveRecord::Base) do
       end

data/lib/historiographer/version.rb

@@ -1,3 +1,3 @@
 module Historiographer
-  VERSION = "4.1.5"
+  VERSION = "4.1.8"
 end

data/lib/historiographer.rb

@@ -85,7 +85,6 @@ module Historiographer
     after_save :record_history, if: :should_record_history?
     validate :validate_history_user_id_present, if: :should_validate_history_user_id_present?
 
-
     def should_alert_history_user_id_present?
       !snapshot_mode? && !is_history_class? && Thread.current[:skip_history_user_id_validation] != true
     end
@@ -184,15 +183,15 @@ module Historiographer
 
     begin
       class_name.constantize
-    rescue StandardError
+    rescue NameError
       # Get the base table name without _histories suffix
-      base_table = base.table_name.sub(/_histories$/, '')
+      base_table = base.table_name.singularize.sub(/_histories$/, '')
       
-      history_class_initializer = Class.new(base) do
+      history_class_initializer = Class.new(ActiveRecord::Base) do
         self.table_name = "#{base_table}_histories"
         
         # Handle STI properly
-        self.inheritance_column = base.inheritance_column if base.respond_to?(:inheritance_column)
+        self.inheritance_column = base.inheritance_column if base.sti_enabled?
       end
 
       # Split the class name into module parts and the actual class name
@@ -217,63 +216,26 @@ module Historiographer
     base.singleton_class.prepend(Module.new do
       def belongs_to(name, scope = nil, **options, &extension)
         super
-        define_history_association(name, :belongs_to, options)
+        return if is_history_class?
+        history_class.define_history_association(name)
       end
 
       def has_one(name, scope = nil, **options, &extension)
         super
-        define_history_association(name, :has_one, options)
+        return if is_history_class?
+        history_class.define_history_association(name)
       end
 
       def has_many(name, scope = nil, **options, &extension)
         super
-        define_history_association(name, :has_many, options)
+        return if is_history_class?
+        history_class.define_history_association(name)
       end
 
       def has_and_belongs_to_many(name, scope = nil, **options, &extension)
         super
-        define_history_association(name, :has_and_belongs_to_many, options)
-      end
-
-      private
-
-      def define_history_association(name, type, options)
         return if is_history_class?
-        return if @defining_association
-        return if %i[histories current_history].include?(name)
-        @defining_association = true
-
-        history_class = "#{self.name}History".constantize
-        history_class_name = "#{name.to_s.singularize.camelize}History"
-
-        # Get the original association's foreign key
-        original_reflection = self.reflect_on_association(name)
-        foreign_key = original_reflection.foreign_key
-
-        if type == :has_many || type == :has_and_belongs_to_many
-          history_class.send(
-            type, 
-            name, 
-            -> (owner) { where("#{name.to_s.singularize}_histories.snapshot_id = ?", owner.snapshot_id) }, 
-            **options.merge(
-              class_name: history_class_name, 
-              foreign_key: foreign_key,
-              primary_key: foreign_key
-            )
-          )
-        else
-          history_class.send(
-            type, 
-            name, 
-            -> (owner) { where("#{name}_histories.snapshot_id = ?", owner.snapshot_id) }, 
-            **options.merge(
-              class_name: history_class_name, 
-              foreign_key: foreign_key,
-              primary_key: foreign_key
-            )
-          )
-        end
-        @defining_association = false
+        history_class.define_history_association(name)
       end
     end)
 
@@ -318,7 +280,6 @@ module Historiographer
       save!(*args, &block)
       @no_history = false
     end
-
     
     def snapshot(tree = {}, snapshot_id = nil)
       return if is_history_class?
@@ -334,10 +295,11 @@ module Historiographer
         return if existing_snapshot.present?
 
         null_snapshot = history_class.where(foreign_key => attrs[primary_key], snapshot_id: nil)
+        snapshot = nil
         if null_snapshot.present?
-          null_snapshot.update(snapshot_id: snapshot_id)
+          snapshot = null_snapshot.update(snapshot_id: snapshot_id)
         else
-          record_history(snapshot_id: snapshot_id)
+          snapshot = record_history(snapshot_id: snapshot_id)
         end
 
         # Recursively snapshot associations, avoiding infinite loops
@@ -356,6 +318,8 @@ module Historiographer
             record.snapshot(new_tree, snapshot_id) if record.respond_to?(:snapshot)
           end
         end
+
+        snapshot
       end
     end
 
@@ -383,8 +347,12 @@ module Historiographer
       attrs
     end
 
+    def snapshots
+      histories.where.not(snapshot_id: nil)
+    end
+
     def latest_snapshot
-      histories.where.not(snapshot_id: nil).order('id DESC').limit(1)&.first || none
+      snapshots.order('id DESC').limit(1)&.first || history_class.none
     end
 
     private
@@ -407,7 +375,7 @@ module Historiographer
       current_history = histories.where(history_ended_at: nil).order('id desc').limit(1).last
 
       if history_class.history_foreign_key.present? && history_class.present?
-        history_class.create!(attrs).tap do |history|
+        history_class.create!(attrs).tap do |new_history|
           current_history.update!(history_ended_at: now) if current_history.present?
         end
       else

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: historiographer
 version: !ruby/object:Gem::Version
-  version: 4.1.5
+  version: 4.1.8
 platform: ruby
 authors:
 - brettshollenberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-19 00:00:00.000000000 Z
+date: 2024-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -220,6 +220,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Append-only histories + chained snapshots of your ActiveRecord tables
 email: brett.shollenberger@gmail.com
 executables: []
@@ -233,6 +247,7 @@ files:
 - lib/historiographer.rb
 - lib/historiographer/configuration.rb
 - lib/historiographer/history.rb
+- lib/historiographer/history/instance_methods.rb
 - lib/historiographer/history_migration.rb
 - lib/historiographer/history_migration_mysql.rb
 - lib/historiographer/mysql_migration.rb