hoardable 0.16.0 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c41a6c69f62f7e2a99fefe00229a7244f5cd0dcb9ed3b0d243db9adf9cabd98
-  data.tar.gz: 30dc9d7a551c29331a7736f7b825c0b5f9db83bf5c5cd537d5d2910908f683ff
+  metadata.gz: 36d1113a71b72492244fadc8172ef4a08f28bdff546b7344bb385ce38e82ecbd
+  data.tar.gz: a4cee0c629c4c1d59f6c0b632c0499fc5e094e099c7e0dc4bf3e0d79271f6eb8
 SHA512:
-  metadata.gz: ad46ae05e3241052089aaf432016b906f648051fae6405e2ce4a90c7f247942a09a011d2fc35e6558695814949ef37a0398d36baaa71500f2c31d33436a7eac7
-  data.tar.gz: b3307392cdff1b14a37192cd1a004099c5d99d7dd0ce3d0f8fe230c1dac4b59697c4708f5859cb7b2b831f45f1a3a6489cdce2eaf464fef2d9e135bd902e4f26
+  metadata.gz: 3cb288b7dbd5938056d3fd5fae396ad6d7caca20a98902ebb228a75d4c05d5e689807ea90f4e6f96dc5e1ac20bbb028fa12717676da3f60163ca4a362bf33db1
+  data.tar.gz: 44bba102025a18563d29d76430d27f06299316d69b37e08fa3b216453dfe6c4890f82e6f065843c127cf26fb0da39f7ce76194d2e31dc2bd0021d9973e6c9748

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.17.0
+
+- Much improved performance of setting `hoardable_id` for versions.
+
 ## 0.16.0
 
 - Rails 8 support introduced

data/README.md

@@ -41,7 +41,6 @@ Include `Hoardable::Model` into an ActiveRecord model you would like to hoard ve
 ```ruby
 class Post < ActiveRecord::Base
   include Hoardable::Model
-  ...
 end
 ```
 
@@ -235,6 +234,21 @@ version.changes # => { "title"=> ["Title", "New Title"] }
 version.hoardable_operation # => "update"
 ```
 
+### Overriding the temporal range
+
+When calculating the temporal range for a given version, the default upper bound is `Time.now.utc`.
+
+You can, however, use the `Hoardable.travel_to` class method to specify a custom upper bound for the time range. This allows
+you to specify the datetime that a particular change should be recorded at by passing a block:
+
+```ruby
+Hoardable.travel_to(2.weeks.ago) do
+  post.destroy!
+end
+```
+
+Note: If the provided datetime pre-dates the calculated lower bound then an `InvalidTemporalUpperBoundError` will be raised.
+
 ### Model Callbacks
 
 Sometimes you might want to do something with a version after it gets inserted to the database. You
@@ -313,6 +327,14 @@ end
 
 Model-level configuration overrides global configuration.
 
+### Single Table Inheritance
+
+Hoardable works for [Single Table
+Inheritance](https://guides.rubyonrails.org/association_basics.html#single-table-inheritance-sti). You
+will need to include `Hoardable::Model` in each child model you'd like to version, as that is what
+generates the model's version class. The migration generator only needs to be run for the parent
+model, as the versions will similarly be stored in a single table.
+
 ## Relationships
 
 ### `belongs_to`

data/lib/generators/hoardable/functions/set_hoardable_id.sql

@@ -0,0 +1,7 @@
+CREATE OR REPLACE FUNCTION <%= function_name %>() RETURNS trigger
+  LANGUAGE plpgsql AS
+$$
+BEGIN
+  NEW.hoardable_id = NEW.<%= primary_key %>;
+  RETURN NEW;
+END;$$;

data/lib/generators/hoardable/install_generator.rb

@@ -25,7 +25,7 @@ module Hoardable
 
     def create_functions
       Dir
-        .glob(File.join(__dir__, "functions", "*.sql"))
+        .glob(File.join(__dir__, "install_functions", "*.sql"))
         .each do |file_path|
           file_name = file_path.match(%r{([^/]+)\.sql})[1]
           template file_path, "db/functions/#{file_name}_v01.sql"

data/lib/generators/hoardable/migration_generator.rb

@@ -36,22 +36,33 @@ module Hoardable
       end
     end
 
+    def create_function
+      template("../functions/set_hoardable_id.sql", "db/functions/#{function_name}_v01.sql")
+    end
+
     no_tasks do
+      def function_name
+        "hoardable_set_hoardable_id_from_#{primary_key}"
+      end
+
+      def klass
+        @klass ||= class_name.singularize.constantize
+      end
+
       def table_name
-        class_name.singularize.constantize.table_name
+        klass.table_name
       rescue StandardError
         super
       end
 
       def foreign_key_type
-        options[:foreign_key_type] ||
-          class_name.singularize.constantize.columns.find { |col| col.name == primary_key }.sql_type
+        options[:foreign_key_type] || klass.columns.find { |col| col.name == primary_key }.sql_type
       rescue StandardError
         "bigint"
       end
 
       def primary_key
-        options[:primary_key] || class_name.singularize.constantize.primary_key
+        options[:primary_key] || klass.primary_key
       rescue StandardError
         "id"
       end

data/lib/generators/hoardable/templates/install.rb.erb

@@ -4,7 +4,6 @@ class InstallHoardable < ActiveRecord::Migration[<%= ActiveRecord::Migration.cur
   def change
     <% if postgres_version < 13 %>enable_extension :pgcrypto
     <% end %>create_function :hoardable_prevent_update_id
-    create_function :hoardable_source_set_id
     create_function :hoardable_version_prevent_update
     create_enum :hoardable_operation, %w[update delete insert]
   end

data/lib/generators/hoardable/templates/migration.rb.erb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-class Create<%= class_name.singularize.delete(':') %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+class Create<%= singularized_table_name.classify %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     add_column :<%= table_name %>, :hoardable_id, :<%= foreign_key_type %>
     add_index :<%= table_name %>, :hoardable_id
     create_table(
       :<%= singularized_table_name %>_versions,
-      id: false, 
+      id: false,
       options: 'INHERITS (<%= table_name %>)',
     ) do |t|
       t.jsonb :_data
@@ -25,6 +25,7 @@ class Create<%= class_name.singularize.delete(':') %>Versions < ActiveRecord::Mi
       :<%= singularized_table_name %>_versions_prevent_update,
       on: :<%= singularized_table_name %>_versions
     )
+    create_function :<%= function_name %>
     create_trigger :<%= table_name %>_set_hoardable_id, on: :<%= table_name %>
     create_trigger :<%= table_name %>_prevent_update_hoardable_id, on: :<%= table_name %>
     change_column_null :<%= table_name %>, :hoardable_id, false

data/lib/generators/hoardable/triggers/set_hoardable_id.sql

@@ -1,3 +1,3 @@
 CREATE TRIGGER <%= table_name %>_set_hoardable_id
   BEFORE INSERT ON <%= table_name %> FOR EACH ROW
-  EXECUTE PROCEDURE hoardable_source_set_id();
+  EXECUTE PROCEDURE <%= function_name %>();

data/lib/hoardable/database_client.rb

@@ -93,7 +93,14 @@ module Hoardable
     end
 
     def initialize_temporal_range
-      ((previous_temporal_tsrange_end || hoardable_source_epoch)..Time.now.utc)
+      upper_bound = Hoardable.instance_variable_get("@travel_to") || Time.now.utc
+      lower_bound = (previous_temporal_tsrange_end || hoardable_source_epoch)
+
+      if upper_bound < lower_bound
+        raise InvalidTemporalUpperBoundError.new(upper_bound, lower_bound)
+      end
+
+      (lower_bound..upper_bound)
     end
 
     def initialize_hoardable_data

data/lib/hoardable/engine.rb

@@ -81,6 +81,16 @@ module Hoardable
       @at = nil
     end
 
+    # Allows calling code to set the upper bound for the temporal range for recorded audits.
+    #
+    # @param datetime [DateTime] the datetime to temporally record versions at
+    def travel_to(datetime)
+      @travel_to = datetime
+      yield
+    ensure
+      @travel_to = nil
+    end
+
     # @!visibility private
     def logger
       @logger ||= ActiveSupport::TaggedLogging.new(Logger.new($stdout))
@@ -101,7 +111,7 @@ module Hoardable
     initializer "hoardable.schema_statements" do
       ActiveSupport.on_load(:active_record_postgresqladapter) do
         # We need to control the table dumping order of tables, so revert these to just +super+
-        Fx::SchemaDumper::Trigger.module_eval("def tables(streams); super; end")
+        Fx::SchemaDumper.module_eval("def tables(streams); super; end")
 
         ActiveRecord::ConnectionAdapters::PostgreSQL::SchemaDumper.prepend(SchemaDumper)
         ActiveRecord::ConnectionAdapters::PostgreSQL::SchemaStatements.prepend(SchemaStatements)

data/lib/hoardable/error.rb

@@ -24,4 +24,14 @@ module Hoardable
         LOG
     end
   end
+
+  # An error to be raised when the provided temporal upper bound is before the calcualated lower bound.
+  class InvalidTemporalUpperBoundError < Error
+    def initialize(upper, lower)
+      super(<<~LOG)
+          'The supplied value to `Hoardable.travel_to` (#{upper}) is before the calculated lower bound (#{lower}).
+          You must provide a datetime > the lower bound.
+        LOG
+    end
+  end
 end

data/lib/hoardable/has_many.rb

@@ -26,16 +26,21 @@ module Hoardable
     class_methods do
       def has_many(*args, &block)
         options = args.extract_options!
-        options[:extend] = Array(options[:extend]).push(HasManyExtension) if options.delete(
-          :hoardable
-        )
+        hoardable_option = options.delete(:hoardable)
+        options[:extend] = Array(options[:extend]).push(HasManyExtension) if hoardable_option
+
         super(*args, **options, &block)
+        return unless hoardable_option
 
         # This hack is needed to force Rails to not use any existing method cache so that the
-        # {HasManyExtension} scope is always used.
+        # {HasManyExtension} scope is always used when using {Hoardable.at}.
         class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def #{args.first}
-            super.extending
+            if Hoardable.instance_variable_get("@at")
+              super.extending
+            else
+              super
+            end
           end
         RUBY
       end

data/lib/hoardable/model.rb

@@ -50,12 +50,14 @@ module Hoardable
       define_model_callbacks :versioned, only: :after
       define_model_callbacks :reverted, only: :after
       define_model_callbacks :untrashed, only: :after
+    end
 
+    def self.included(base)
       TracePoint
         .new(:end) do |trace|
-          next unless self == trace.self
+          next unless base == trace.self
 
-          full_version_class_name = "#{name}#{VERSION_CLASS_SUFFIX}"
+          full_version_class_name = "#{base.name}#{VERSION_CLASS_SUFFIX}"
           if (namespace_match = full_version_class_name.match(/(.*)::(.*)/))
             object_namespace = namespace_match[1].constantize
             version_class_name = namespace_match[2]
@@ -64,10 +66,10 @@ module Hoardable
             version_class_name = full_version_class_name
           end
           unless Object.const_defined?(full_version_class_name)
-            object_namespace.const_set(version_class_name, Class.new(self) { include VersionModel })
+            object_namespace.const_set(version_class_name, Class.new(base) { include VersionModel })
           end
-          include SourceModel
-          REGISTRY.add(self)
+          base.class_eval { include SourceModel }
+          REGISTRY.add(base)
 
           trace.disable
         end

data/lib/hoardable/scopes.rb

@@ -9,13 +9,20 @@ module Hoardable
     included do
       # By default {Hoardable} only returns instances of the parent table, and not the +versions+ in
       # the inherited table. This can be bypassed by using the {.include_versions} scope or wrapping
-      # the code in a `Hoardable.at(datetime)` block.
+      # the code in a `Hoardable.at(datetime)` block. When this is a version class that is an STI
+      # model, also scope to them.
       default_scope do
-        if (hoardable_at = Hoardable.instance_variable_get("@at"))
-          at(hoardable_at)
-        else
-          exclude_versions
-        end
+        scope =
+          (
+            if (hoardable_at = Hoardable.instance_variable_get("@at"))
+              at(hoardable_at)
+            else
+              exclude_versions
+            end
+          )
+        next scope unless klass == version_class && "type".in?(column_names)
+
+        scope.where(type: superclass.sti_name)
       end
 
       # @!scope class

data/lib/hoardable/source_model.rb

@@ -40,20 +40,24 @@ module Hoardable
       end
 
       before_destroy(if: HOARDABLE_CALLBACKS_ENABLED, unless: HOARDABLE_SAVE_TRASH) do
-        versions.delete_all
+        versions.extending.delete_all
       end
 
       after_commit { hoardable_client.unset_hoardable_version_and_event_uuid }
+    end
 
-      # Returns all +versions+ in ascending order of their temporal timeframes.
-      has_many(
-        :versions,
-        -> { order("UPPER(_during) ASC") },
-        dependent: nil,
-        class_name: version_class.to_s,
-        inverse_of: :hoardable_source,
-        foreign_key: :hoardable_id
-      )
+    def self.included(base)
+      base.class_eval do
+        # Returns all +versions+ in ascending order of their temporal timeframes.
+        has_many(
+          :versions,
+          -> { order("UPPER(_during) ASC") },
+          dependent: nil,
+          class_name: version_class.to_s,
+          inverse_of: :hoardable_source,
+          foreign_key: :hoardable_id
+        )
+      end
     end
 
     # Returns a boolean of whether the record is actually a trashed +version+ cast as an instance of the

data/lib/hoardable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hoardable
-  VERSION = "0.16.0"
+  VERSION = "0.18.1"
 end

data/lib/hoardable/version_model.rb

@@ -24,6 +24,9 @@ module Hoardable
         class_name: superclass.model_name
       )
 
+      # disable STI on versions tables
+      self.inheritance_column = :_
+
       self.table_name = "#{table_name.singularize}#{VERSION_TABLE_SUFFIX}"
 
       alias_method :readonly?, :persisted?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hoardable
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.1
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-11 00:00:00.000000000 Z
+date: 2025-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -58,7 +58,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
     - - "<"
       - !ruby/object:Gem::Version
         version: '1'
@@ -68,7 +68,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
     - - "<"
       - !ruby/object:Gem::Version
         version: '1'
@@ -100,15 +100,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".streerc"
-- ".tool-versions"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
-- lib/generators/hoardable/functions/hoardable_prevent_update_id.sql
-- lib/generators/hoardable/functions/hoardable_source_set_id.sql
-- lib/generators/hoardable/functions/hoardable_version_prevent_update.sql
+- lib/generators/hoardable/functions/set_hoardable_id.sql
+- lib/generators/hoardable/install_functions/hoardable_prevent_update_id.sql
+- lib/generators/hoardable/install_functions/hoardable_version_prevent_update.sql
 - lib/generators/hoardable/install_generator.rb
 - lib/generators/hoardable/migration_generator.rb
 - lib/generators/hoardable/templates/install.rb.erb
@@ -159,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: An ActiveRecord extension for versioning and soft-deletion of records in

data/.tool-versions

@@ -1,2 +0,0 @@
-ruby 3.3.0
-postgres 16.1

data/lib/generators/hoardable/functions/hoardable_source_set_id.sql

@@ -1,18 +0,0 @@
-CREATE OR REPLACE FUNCTION hoardable_source_set_id() RETURNS trigger
-  LANGUAGE plpgsql AS
-$$
-DECLARE
-  _pk information_schema.constraint_column_usage.column_name%TYPE;
-  _id _pk%TYPE;
-BEGIN
-  SELECT c.column_name
-    FROM information_schema.table_constraints t
-    JOIN information_schema.constraint_column_usage c
-    ON c.constraint_name = t.constraint_name
-    WHERE c.table_name = TG_TABLE_NAME AND t.constraint_type = 'PRIMARY KEY'
-    LIMIT 1
-    INTO _pk;
-  EXECUTE format('SELECT $1.%I', _pk) INTO _id USING NEW;
-  NEW.hoardable_id = _id;
-  RETURN NEW;
-END;$$;