hoardable 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c960d95a373942d9183464cc50b7c4213c25c7563fa9d920c81d2c325ea71705
-  data.tar.gz: e7e0f289e60acd720538edc15584209ed3d30e08b21758d06884a5486f198ee0
+  metadata.gz: 4c4bc9bc4cdd73263a6afe5551b59f085cbf7dc3877e472df8abdba62f5fcbd6
+  data.tar.gz: 7aa8ea828b2f6083a80c93e34a1fcc5756508db15f2a317dc95bfea2ae8b1e28
 SHA512:
-  metadata.gz: a83966223151922d24bb009ac50465723388ba91825e27cf933bb5e00370c270a0518ec828358f1109a040e2a9202cee7b37d7ea98e0387b30dc07a74f7eb851
-  data.tar.gz: 6bc246f6664b61c5000ffa71b24c8ddd30c409eda87e790b0ea1bd9d47f46c4e85e0b5eb89736939a75018e272cdd5ac2ce1217c7c7e9272ddc4f96cc8cc33f4
+  metadata.gz: 915cba36e937b34667b2ad31ae8dd780224a417669a6bb3c1abdfb2c8a19c10525e7d29a0a4f264aa475362f9b823104bd5a40d71bfc01848db2eb6a463f7c1d
+  data.tar.gz: ab0faaab94b03c5b6452b7aad505e16b4bb98538ae8649cfd65e17d397e3d917e6e61c752ed39b820dc30d72503e993ec5d6fbe353391c29025759a4bedeff74

data/.rubocop.yml

@@ -1,6 +1,7 @@
 AllCops:
   TargetRubyVersion: 2.6
   NewCops: enable
+  SuggestExtensions: false
 
 Layout/LineLength:
   Max: 120
@@ -8,3 +9,6 @@ Layout/LineLength:
 Metrics/ClassLength:
   Exclude:
     - 'test/**/*.rb'
+
+Style/DocumentDynamicEvalDefinition:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.5.0] - 2022-09-25
+
+- **Breaking Change** - Untrashing a version will now insert a version for the untrash event with
+  it's own temporal timespan. This simplifies the ability to query versions temporarily for when
+  they were trashed or not. This changes, but corrects, temporal query results using `.at`.
+
+- **Breaking Change** - Because of the above, a new operation enum value of "insert" was added. If
+  you already have the `hoardable_operation` enum in your PostgreSQL schema, you can add it by
+  executing the following SQL in a new migration: `ALTER TYPE hoardable_operation ADD VALUE
+  'insert';`.
+
+## [0.4.0] - 2022-09-24
+
+- **Breaking Change** - Trashed versions now pull from the same postgres sequenced used by the
+  source model’s table.
+
 ## [0.1.0] - 2022-07-23
 
 - Initial release

data/README.md

@@ -69,7 +69,7 @@ Rails 7.
 ### Overview
 
 Once you include `Hoardable::Model` into a model, it will dynamically generate a "Version" subclass
-of that model. As we continue our example above, :
+of that model. As we continue our example from above:
 
 ```
 $ irb
@@ -79,8 +79,8 @@ $ irb
 => PostVersion(id: integer, body: text, user_id: integer, created_at: datetime, _data: jsonb, _during: tsrange, post_id: integer)
 ```
 
-A `Post` now `has_many :versions`. Whenever an update and deletion of a `Post` occurs, a version is
-created (by default):
+A `Post` now `has_many :versions`. With the default configuration, whenever an update and deletion
+of a `Post` occurs, a version is created:
 
 ```ruby
 post = Post.create!(title: "Title")
@@ -97,9 +97,29 @@ Post.find(post.id) # raises ActiveRecord::RecordNotFound
 Each `PostVersion` has access to the same attributes, relationships, and other model behavior that
 `Post` has, but as a read-only record.
 
-If you ever need to revert to a specific version, you can call `version.revert!` on it. If you would
-like to untrash a specific version, you can call `version.untrash!` on it. This will re-insert the
-model in the parent class’ table with it’s original primary key.
+If you ever need to revert to a specific version, you can call `version.revert!` on it.
+
+``` ruby
+post = Post.create!(title: "Title")
+post.update!(title: "Whoops")
+post.versions.last.revert!
+post.title # => "Title"
+```
+
+If you would like to untrash a specific version, you can call `version.untrash!` on it. This will
+re-insert the model in the parent class’s table with it’s original primary key.
+
+```ruby
+post = Post.create!(title: "Title")
+post.id # => 1
+post.destroy!
+post.versions.size # => 1
+Post.find(post.id) # raises ActiveRecord::RecordNotFound
+trashed_post = post.versions.trashed.last
+trashed_post.id # => 2
+trashed_post.untrash!
+Post.find(post.id) # #<Post>
+```
 
 ### Querying and Temporal Lookup
 
@@ -112,20 +132,30 @@ post.versions.where(user_id: Current.user.id, body: "Cool!")
 If you want to look-up the version of a record at a specific time, you can use the `.at` method:
 
 ```ruby
-post.at(1.day.ago) # => #<PostVersion:0x000000010d44fa30>
-# or
-PostVersion.at(1.day.ago).find_by(post_id: post.id) # => #<PostVersion:0x000000010d44fa30>
+post.at(1.day.ago) # => #<PostVersion>
+# or you can use the scope on the version model class
+PostVersion.at(1.day.ago).find_by(post_id: post.id) # => #<PostVersion>
+```
+
+The source model class also has an `.at` method:
+
+``` ruby
+Post.at(1.day.ago) # => [#<Post>, #<Post>]
 ```
 
-_Note:_ A `Version` is not created upon initial parent model creation. If you would like to
-accurately capture the valid temporal frame of the first version, make sure your model’s table has a
-`created_at` timestamp field.
+This will return an ActiveRecord scoped query of all `Posts` and `PostVersions` that were valid at
+that time, all cast as instances of `Post`.
 
-By default, `hoardable` will keep copies of records you have destroyed. You can query for them as
-well:
+_Note:_ A `Version` is not created upon initial parent model creation. To accurately track the
+beginning of the first temporal period, you will need to ensure the source model table has a
+`created_at` timestamp column.
+
+By default, `hoardable` will keep copies of records you have destroyed. You can query them
+specifically with:
 
 ```ruby
 PostVersion.trashed
+Post.version_class.trashed # <- same thing as above
 ```
 
 _Note:_ Creating an inherited table does not copy over the indexes from the parent table. If you
@@ -146,7 +176,10 @@ choosing.
 One convenient way to assign contextual data to these is by defining a proc in an initializer, i.e.:
 
 ```ruby
+# config/initializers/hoardable.rb
 Hoardable.whodunit = -> { Current.user&.id }
+
+# somewhere in your app code
 Current.user = User.find(123)
 post.update!(status: 'live')
 post.versions.last.hoardable_whodunit # => 123
@@ -174,7 +207,7 @@ class ApplicationController < ActionController::Base
     Hoardable.with(whodunit: current_user.id, meta: { request_uuid: request.uuid }) do
       yield
     end
-    # `Hoardable.whodunit` is back to nil or the previously set value
+    # `Hoardable.whodunit` and `Hoardable.meta` are back to nil or their previously set values
   end
 end
 ```
@@ -224,12 +257,13 @@ end
 
 ### Configuration
 
-There are three configurable options currently:
+The configurable options are:
 
 ```ruby
 Hoardable.enabled # => default true
 Hoardable.version_updates # => default true
 Hoardable.save_trash # => default true
+Hoardable.return_everything # => default false
 ```
 
 `Hoardable.enabled` controls whether versions will be ever be created.
@@ -239,6 +273,10 @@ Hoardable.save_trash # => default true
 `Hoardable.save_trash` controls whether to create versions upon record deletion. When this is set to
 `false`, all versions of a record will be deleted when the record is destroyed.
 
+`Hoardable.return_everything` controls whether to include versions when doing queries for source
+models. This is typically only useful to set around a block, as explained below in
+[Relationships](#relationships).
+
 If you would like to temporarily set a config setting, you can use `Hoardable.with`:
 
 ```ruby
@@ -247,37 +285,49 @@ Hoardable.with(enabled: false) do
 end
 ```
 
-You can also configure these variables per `ActiveRecord` class as well using `hoardable_options`:
+You can also configure these variables per `ActiveRecord` class as well using `hoardable_config`:
 
 ```ruby
 class Comment < ActiveRecord::Base
   include Hoardable::Model
-  hoardable_options version_updates: false
+  hoardable_config version_updates: false
+end
+```
+
+If you want to temporarily set the `hoardable_config` for a specific model, you can use
+`with_hoardable_config`:
+
+```ruby
+Comment.with_hoardable_config(version_updates: true) do
+  comment.update!(text: "Edited")
 end
 ```
 
-If either the model-level option or global option for a configuration variable is set to `false`,
-that behavior will be disabled.
+If a model-level option exists, it will use that. Otherwise, it will fall back to the global
+`Hoardable` config.
 
 ### Relationships
 
-As in life, sometimes relationships can be hard. `hoardable` is still working out best practices and
-features in this area, but here are a couple pointers.
+As in life, sometimes relationships can be hard, but here are some pointers on handling associations
+with `Hoardable` considerations.
 
-Sometimes you’ll have a record that belongs to a record that you’ll trash. Now the child record’s
-foreign key will point to the non-existent trashed version of the parent. If you would like this
-`belongs_to` relationship to always resolve to the parent as if it was not trashed, you can include
-the scope on the relationship definition:
+Sometimes you’ll have a record that belongs to a parent record that you’ll trash. Now the child
+record’s foreign key will point to the non-existent trashed version of the parent. If you would like
+to have `belongs_to` resolve to the trashed parent model in this case, you can use
+`belongs_to_trashable` in place of `belongs_to`:
 
 ```ruby
-belongs_to :parent, -> { include_versions }
+class Comment
+  include Hoardable::Associations # <- This includes is not required if this model already includes `Hoardable::Model`
+  belongs_to_trashable :post, -> { where(status: 'published') }, class_name: 'Article' # <- Accepts normal `belongs_to` arguments
+end
 ```
 
 Sometimes you’ll trash something that `has_many :children, dependent: :destroy` and both the parent
 and child model classes include `Hoardable::Model`. Whenever a hoardable version is created in a
 database transaction, it will create or re-use a unique event UUID for that transaction and tag all
-versions created with it. That way, when you `untrash!` a parent object, you can find and `untrash!`
-the children like so:
+versions created with it. That way, when you `untrash!` a record, you can find and `untrash!`
+records that were trashed with it:
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -295,20 +345,36 @@ class Post < ActiveRecord::Base
 end
 ```
 
+If there are models that might be related to versions that are trashed or otherwise, and/or might
+trashed themselves, you can bypass the inherited tables query handling altogether by using the
+`return_everything` configuration variable in `Hoardable.with`. This will ensure that you always see
+all records, including update and trashed versions.
+
+```ruby
+post.destroy!
+
+Hoardable.with(return_everything: true) do
+  post = Post.find(post.id) # returns the trashed post as if it was not
+  post.comments # returns the trashed comments as well
+end
+
+post.reload # raises ActiveRecord::RecordNotFound
+```
+
 ## Gem Comparison
 
-###  [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) 
+### [`paper_trail`](https://github.com/paper-trail-gem/paper_trail)
 
 `paper_trail` is maybe the most popular and fully featured gem in this space. It works for other
-  database types than PostgeSQL and (by default) stores all versions of all versioned models in a
-  single `versions` table. It stores changes in a `text`, `json`, or `jsonb` column. In order to
-  efficiently query the `versions` table, a `jsonb` column should be used, which takes up a lot of
-  space to index. Unless you customize your configuration, all `versions` for all models types are
-  in the same table which is inefficient if you are only interested in querying versions of a single
-  model. By contrast, `hoardable` stores versions in smaller, isolated and inherited tables with the
-  same database columns as their parents, which are more efficient for querying as well as auditing
-  for truncating and dropping. The concept of a `temporal` time-frame does not exist for a single
-  version since there is only a `created_at` timestamp.
+database types than PostgeSQL and (by default) stores all versions of all versioned models in a
+single `versions` table. It stores changes in a `text`, `json`, or `jsonb` column. In order to
+efficiently query the `versions` table, a `jsonb` column should be used, which takes up a lot of
+space to index. Unless you customize your configuration, all `versions` for all models types are
+in the same table which is inefficient if you are only interested in querying versions of a single
+model. By contrast, `hoardable` stores versions in smaller, isolated and inherited tables with the
+same database columns as their parents, which are more efficient for querying as well as auditing
+for truncating and dropping. The concept of a `temporal` time-frame does not exist for a single
+version since there is only a `created_at` timestamp.
 
 ### [`audited`](https://github.com/collectiveidea/audited)
 

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

@@ -2,7 +2,7 @@
 
 class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
-    create_enum :hoardable_operation, %w[update delete]
+    create_enum :hoardable_operation, %w[update delete insert]
     create_table :<%= singularized_table_name %>_versions, id: false, options: 'INHERITS (<%= table_name %>)' do |t|
       t.jsonb :_data
       t.tsrange :_during, null: false

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

@@ -11,7 +11,7 @@ class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%=
                 SELECT 1 FROM pg_type t
                 WHERE t.typname = 'hoardable_operation'
               ) THEN
-                CREATE TYPE hoardable_operation AS ENUM ('update', 'delete');
+                CREATE TYPE hoardable_operation AS ENUM ('update', 'delete', 'insert');
               END IF;
           END
           $$;

data/lib/hoardable/associations.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # This concern contains +ActiveRecord+ association considerations for {SourceModel}. It is
+  # included by {Model} but can be included on it’s own for models that +belongs_to+ a Hoardable
+  # {Model}.
+  module Associations
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # A wrapper for +ActiveRecord+’s +belongs_to+ that allows for falling back to the most recent
+      # trashed +version+, in the case that the related source has been trashed.
+      def belongs_to_trashable(name, scope = nil, **options)
+        belongs_to(name, scope, **options)
+
+        trashable_relationship_name = "trashable_#{name}"
+
+        define_method(trashable_relationship_name) do
+          source_reflection = self.class.reflections[name.to_s]
+          version_class = source_reflection.klass.version_class
+          version_class.trashed.only_most_recent.find_by(
+            version_class.hoardable_source_foreign_key => source_reflection.foreign_key
+          )
+        end
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}
+            super || #{trashable_relationship_name}
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/hoardable/hoardable.rb

@@ -5,22 +5,23 @@ module Hoardable
   # Symbols for use with setting contextual data, when creating versions. See
   # {file:README.md#tracking-contextual-data README} for more.
   DATA_KEYS = %i[meta whodunit note event_uuid].freeze
+
   # Symbols for use with setting {Hoardable} configuration. See {file:README.md#configuration
   # README} for more.
-  CONFIG_KEYS = %i[enabled version_updates save_trash].freeze
+  CONFIG_KEYS = %i[enabled version_updates save_trash return_everything].freeze
 
-  # @!visibility private
   VERSION_CLASS_SUFFIX = 'Version'
+  private_constant :VERSION_CLASS_SUFFIX
 
-  # @!visibility private
   VERSION_TABLE_SUFFIX = "_#{VERSION_CLASS_SUFFIX.tableize}"
+  private_constant :VERSION_TABLE_SUFFIX
 
-  # @!visibility private
   DURING_QUERY = '_during @> ?::timestamp'
+  private_constant :DURING_QUERY
 
   @context = {}
   @config = CONFIG_KEYS.to_h do |key|
-    [key, true]
+    [key, key != :return_everything]
   end
 
   class << self
@@ -44,9 +45,10 @@ module Hoardable
       end
     end
 
-    # This is a general use method for setting {DATA_KEYS} or {CONFIG_KEYS} around a scoped block.
+    # This is a general use method for setting {file:README.md#tracking-contextual-data Contextual
+    # Data} or {file:README.md#configuration Configuration} around a block.
     #
-    # @param hash [Hash] Options and contextual data to set within a block
+    # @param hash [Hash] config and contextual data to set within a block
     def with(hash)
       current_config = @config
       current_context = @context

data/lib/hoardable/model.rb

@@ -10,7 +10,7 @@ module Hoardable
 
     class_methods do
       # @!visibility private
-      attr_reader :_hoardable_options
+      attr_reader :_hoardable_config
 
       # If called with a hash, this will set the model-level +Hoardable+ configuration variables. If
       # called without an argument it will return the computed +Hoardable+ configuration considering
@@ -19,19 +19,33 @@ module Hoardable
       # @param hash [Hash] The +Hoardable+ configuration for the model. Keys must be present in
       #   {CONFIG_KEYS}
       # @return [Hash]
-      def hoardable_options(hash = nil)
+      def hoardable_config(hash = nil)
         if hash
-          @_hoardable_options = hash.slice(*Hoardable::CONFIG_KEYS)
+          @_hoardable_config = hash.slice(*CONFIG_KEYS)
         else
-          @_hoardable_options ||= {}
-          Hoardable::CONFIG_KEYS.to_h do |key|
-            [key, Hoardable.send(key) != false && @_hoardable_options[key] != false]
+          @_hoardable_config ||= {}
+          CONFIG_KEYS.to_h do |key|
+            [key, @_hoardable_config.key?(key) ? @_hoardable_config[key] : Hoardable.send(key)]
           end
         end
       end
+
+      # Set the model-level +Hoardable+ configuration variables around a block. The configuration
+      # will be reset to it’s previous value afterwards.
+      #
+      # @param hash [Hash] The +Hoardable+ configuration for the model. Keys must be present in
+      #   {CONFIG_KEYS}
+      def with_hoardable_config(hash)
+        current_config = @_hoardable_config
+        @_hoardable_config = hash.slice(*CONFIG_KEYS)
+        yield
+      ensure
+        @_hoardable_config = current_config
+      end
     end
 
     included do
+      include Associations
       define_model_callbacks :versioned
       define_model_callbacks :reverted, only: :after
       define_model_callbacks :untrashed, only: :after

data/lib/hoardable/source_model.rb

@@ -34,18 +34,33 @@ module Hoardable
 
       # Returns all +versions+ in ascending order of their temporal timeframes.
       has_many(
-        :versions, -> { order(:_during) },
+        :versions, -> { order('UPPER(_during) ASC') },
         dependent: nil,
         class_name: version_class.to_s,
         inverse_of: model_name.i18n_key
       )
+
+      # @!scope class
+      # @!method at
+      # @return [ActiveRecord<Object>]
+      #
+      # Returns instances of the source model and versions that were valid at the supplied
+      # +datetime+ or +time+, all cast as instances of the source model.
+      scope :at, lambda { |datetime|
+        versioned = version_class.at(datetime)
+        trashed = version_class.trashed_at(datetime)
+        foreign_key = version_class.hoardable_source_foreign_key
+        include_versions.where(id: versioned.select('id')).or(
+          where.not(id: versioned.select(foreign_key)).where.not(id: trashed.select(foreign_key))
+        )
+      }
     end
 
     # Returns a boolean of whether the record is actually a trashed +version+.
     #
     # @return [Boolean]
     def trashed?
-      versions.trashed.limit(1).order(_during: :desc).first&.send(:hoardable_source_attributes) == attributes
+      versions.trashed.only_most_recent.first&.hoardable_source_foreign_id == id
     end
 
     # Returns the +version+ at the supplied +datetime+ or +time+. It will return +self+ if there is
@@ -71,27 +86,31 @@ module Hoardable
     private
 
     def hoardable_callbacks_enabled
-      self.class.hoardable_options[:enabled] && !self.class.name.end_with?(VERSION_CLASS_SUFFIX)
+      self.class.hoardable_config[:enabled] && !self.class.name.end_with?(VERSION_CLASS_SUFFIX)
     end
 
     def hoardable_save_trash
-      self.class.hoardable_options[:save_trash]
+      self.class.hoardable_config[:save_trash]
     end
 
     def hoardable_version_updates
-      self.class.hoardable_options[:version_updates]
+      self.class.hoardable_config[:version_updates]
     end
 
     def insert_hoardable_version_on_update(&block)
-      insert_hoardable_version('update', attributes_before_type_cast.without('id'), &block)
+      insert_hoardable_version('update', &block)
     end
 
     def insert_hoardable_version_on_destroy(&block)
-      insert_hoardable_version('delete', attributes_before_type_cast, &block)
+      insert_hoardable_version('delete', &block)
+    end
+
+    def insert_hoardable_version_on_untrashed
+      initialize_hoardable_version('insert').save(validate: false, touch: false)
     end
 
-    def insert_hoardable_version(operation, attrs)
-      @hoardable_version = initialize_hoardable_version(operation, attrs)
+    def insert_hoardable_version(operation)
+      @hoardable_version = initialize_hoardable_version(operation)
       run_callbacks(:versioned) do
         yield
         hoardable_version.save(validate: false, touch: false)
@@ -102,9 +121,9 @@ module Hoardable
       Thread.current[:hoardable_event_uuid] ||= ActiveRecord::Base.connection.query('SELECT gen_random_uuid();')[0][0]
     end
 
-    def initialize_hoardable_version(operation, attrs)
+    def initialize_hoardable_version(operation)
       versions.new(
-        attrs.merge(
+        attributes_before_type_cast.without('id').merge(
           changes.transform_values { |h| h[0] },
           {
             _event_uuid: find_or_initialize_hoardable_event_uuid,

data/lib/hoardable/tableoid.rb

@@ -5,21 +5,28 @@ module Hoardable
   module Tableoid
     extend ActiveSupport::Concern
 
-    # @!visibility private
     TABLEOID_AREL_CONDITIONS = lambda do |arel_table, condition|
       arel_table[:tableoid].send(
         condition,
         Arel::Nodes::NamedFunction.new('CAST', [Arel::Nodes::Quoted.new(arel_table.name).as('regclass')])
       )
     end.freeze
+    private_constant :TABLEOID_AREL_CONDITIONS
 
     included do
       # @!visibility private
       attr_writer :tableoid
 
-      # By default, {Hoardable} only returns instances of the parent table, and not the +versions+
-      # in the inherited table.
-      default_scope { where(TABLEOID_AREL_CONDITIONS.call(arel_table, :eq)) }
+      # 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.with(return_everything: true)` block.
+      default_scope do
+        if hoardable_config[:return_everything]
+          where(nil)
+        else
+          exclude_versions
+        end
+      end
 
       # @!scope class
       # @!method include_versions
@@ -36,6 +43,14 @@ module Hoardable
       # Returns only +versions+ of the parent +ActiveRecord+ class, cast as instances of the source
       # model’s class.
       scope :versions, -> { include_versions.where(TABLEOID_AREL_CONDITIONS.call(arel_table, :not_eq)) }
+
+      # @!scope class
+      # @!method exclude_versions
+      # @return [ActiveRecord<Object>]
+      #
+      # Excludes +versions+ of the parent +ActiveRecord+ class. This is included by default in the
+      # source model’s +default_scope+.
+      scope :exclude_versions, -> { where(TABLEOID_AREL_CONDITIONS.call(arel_table, :eq)) }
     end
 
     private

data/lib/hoardable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hoardable
-  VERSION = '0.2.0'
+  VERSION = '0.5.0'
 end

data/lib/hoardable/version_model.rb

@@ -6,6 +6,13 @@ module Hoardable
   module VersionModel
     extend ActiveSupport::Concern
 
+    class_methods do
+      # Returns the foreign column that holds the reference to the source model of the version.
+      def hoardable_source_foreign_key
+        @hoardable_source_foreign_key ||= "#{superclass.model_name.i18n_key}_id"
+      end
+    end
+
     included do
       hoardable_source_key = superclass.model_name.i18n_key
 
@@ -13,7 +20,7 @@ module Hoardable
       belongs_to hoardable_source_key, inverse_of: :versions
       alias_method :hoardable_source, hoardable_source_key
 
-      self.table_name = "#{table_name.singularize}#{Hoardable::VERSION_TABLE_SUFFIX}"
+      self.table_name = "#{table_name.singularize}#{VERSION_TABLE_SUFFIX}"
 
       alias_method :readonly?, :persisted?
       alias_attribute :hoardable_operation, :_operation
@@ -26,7 +33,7 @@ module Hoardable
       # @!method trashed
       # @return [ActiveRecord<Object>]
       #
-      # Returns only trashed +versions+ that are orphans.
+      # Returns only trashed +versions+ that are currently orphans.
       scope :trashed, lambda {
         left_outer_joins(hoardable_source_key)
           .where(superclass.table_name => { id: nil })
@@ -38,7 +45,14 @@ module Hoardable
       # @return [ActiveRecord<Object>]
       #
       # Returns +versions+ that were valid at the supplied +datetime+ or +time+.
-      scope :at, ->(datetime) { where(DURING_QUERY, datetime) }
+      scope :at, ->(datetime) { where(_operation: %w[delete update]).where(DURING_QUERY, datetime) }
+
+      # @!scope class
+      # @!method trashed_at
+      # @return [ActiveRecord<Object>]
+      #
+      # Returns +versions+ that were trashed at the supplied +datetime+ or +time+.
+      scope :trashed_at, ->(datetime) { where(_operation: 'insert').where(DURING_QUERY, datetime) }
 
       # @!scope class
       # @!method with_hoardable_event_uuid
@@ -47,6 +61,13 @@ module Hoardable
       # Returns all +versions+ that were created as part of the same +ActiveRecord+ database
       # transaction of the supplied +event_uuid+. Useful in +reverted+ and +untrashed+ callbacks.
       scope :with_hoardable_event_uuid, ->(event_uuid) { where(_event_uuid: event_uuid) }
+
+      # @!scope class
+      # @!method only_most_recent
+      # @return [ActiveRecord<Object>]
+      #
+      # Returns a limited +ActiveRecord+ scope of only the most recent version.
+      scope :only_most_recent, -> { limit(1).reorder('UPPER(_during) DESC') }
     end
 
     # Reverts the parent +ActiveRecord+ instance to the saved attributes of this +version+. Raises
@@ -70,8 +91,9 @@ module Hoardable
 
       transaction do
         superscope = self.class.superclass.unscoped
-        superscope.insert(untrashable_hoardable_source_attributes)
+        superscope.insert(hoardable_source_attributes.merge('id' => hoardable_source_foreign_id))
         superscope.find(hoardable_source_foreign_id).tap do |untrashed|
+          untrashed.send('insert_hoardable_version_on_untrashed')
           untrashed.instance_variable_set(:@hoardable_version, self)
           untrashed.run_callbacks(:untrashed)
         end
@@ -91,13 +113,14 @@ module Hoardable
       _data&.dig('changes')
     end
 
+    # Returns the foreign reference that represents the source model of the version.
+    def hoardable_source_foreign_id
+      @hoardable_source_foreign_id ||= public_send(hoardable_source_foreign_key)
+    end
+
     private
 
-    def untrashable_hoardable_source_attributes
-      hoardable_source_attributes.merge('id' => hoardable_source_foreign_id).tap do |hash|
-        hash['updated_at'] = Time.now if self.class.column_names.include?('updated_at')
-      end
-    end
+    delegate :hoardable_source_foreign_key, to: :class
 
     def hoardable_source_attributes
       @hoardable_source_attributes ||=
@@ -106,16 +129,8 @@ module Hoardable
         .reject { |k, _v| k.start_with?('_') }
     end
 
-    def hoardable_source_foreign_key
-      @hoardable_source_foreign_key ||= "#{self.class.superclass.model_name.i18n_key}_id"
-    end
-
-    def hoardable_source_foreign_id
-      @hoardable_source_foreign_id ||= public_send(hoardable_source_foreign_key)
-    end
-
     def previous_temporal_tsrange_end
-      hoardable_source.versions.limit(1).order(_during: :desc).pluck('_during').first&.end
+      hoardable_source.versions.only_most_recent.pluck('_during').first&.end
     end
 
     def assign_temporal_tsrange
@@ -124,10 +139,10 @@ module Hoardable
         if hoardable_source.class.column_names.include?('created_at')
           hoardable_source.created_at
         else
-          Time.at(0)
+          Time.at(0).utc
         end
       )
-      self._during = (range_start..Time.now)
+      self._during = (range_start..Time.now.utc)
     end
   end
 end

data/lib/hoardable.rb

@@ -7,4 +7,5 @@ require_relative 'hoardable/error'
 require_relative 'hoardable/source_model'
 require_relative 'hoardable/version_model'
 require_relative 'hoardable/model'
+require_relative 'hoardable/associations'
 require_relative 'generators/hoardable/migration_generator'

data/sig/hoardable.rbs

@@ -1,7 +1,7 @@
 module Hoardable
   VERSION: String
   DATA_KEYS: [:meta, :whodunit, :note, :event_uuid]
-  CONFIG_KEYS: [:enabled, :version_updates, :save_trash]
+  CONFIG_KEYS: [:enabled, :version_updates, :save_trash, :return_everything]
   VERSION_CLASS_SUFFIX: String
   VERSION_TABLE_SUFFIX: String
   DURING_QUERY: String
@@ -71,8 +71,9 @@ module Hoardable
     include VersionModel
     include SourceModel
 
-    attr_reader _hoardable_options: Hash[untyped, untyped]
-    def hoardable_options: (?nil hash) -> untyped
+    attr_reader _hoardable_config: Hash[untyped, untyped]
+    def hoardable_config: (?nil hash) -> untyped
+    def with_hoardable_config: (untyped hash) -> untyped
   end
 
   class MigrationGenerator

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hoardable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-08 00:00:00.000000000 Z
+date: 2022-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -108,6 +108,7 @@ files:
 - lib/generators/hoardable/templates/migration.rb.erb
 - lib/generators/hoardable/templates/migration_6.rb.erb
 - lib/hoardable.rb
+- lib/hoardable/associations.rb
 - lib/hoardable/error.rb
 - lib/hoardable/hoardable.rb
 - lib/hoardable/model.rb