hoardable 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7380fb64f7dd3132bec65fd1cfc0c8317a52e6cb6f26895d0b83d7b78391c193
-  data.tar.gz: 71241a1edc81c57d1bb0549685da47642036fc65ff8d659284c31a9784b0f571
+  metadata.gz: a5e5c29b0b6d4a24e7b41a9b4846fd1288caabd48158b517a4b9b61e53421d1c
+  data.tar.gz: 1e863147db8e3a39e4ed3d465855d465f14c4c8a444426abce72534e8bae4d9c
 SHA512:
-  metadata.gz: 4f473b92097e223dd535512ec5850a6c00d9c22faba482787ffbf2ae7b0f6130d37b0a3ed34a46701f53ec4958e7293a69626bdc9693f1f7a51c0e35ff62bb2e
-  data.tar.gz: 530e609fd4535b4d37f82fc4a39ce3322209451bdd0fa67079e74ed2ef658bd252d9a87ca7189a9332e0303b20c8cb073765bc1c99fcdb647c346f893a133ecd
+  metadata.gz: 4c997b34958fbe6253098778c03bf9226eac02b7fd218af1a1d1bd52527b7b1a0b0406a6ecf0cc8e3ea45d70e5b8823dc23a0e48fcc741c470831b98adb3fd65
+  data.tar.gz: 44b9c1cfe68aa6ab18370b90632d5563dda8ef50b0cde425be3b44eb7f2027fa6e61d609538653cc15adab20f9d79ba3423f614d95c9413f8db4c0ced3a2f4be

data/Gemfile

@@ -8,5 +8,6 @@ gem 'rake', '~> 13.0'
 gem 'rubocop', '~> 1.21'
 gem 'rubocop-minitest', '~> 0.20'
 gem 'rubocop-rake', '~> 0.6'
+gem 'yard', '~> 0.9'
 
 gemspec

data/README.md

@@ -1,9 +1,11 @@
-# Hoardable
+# Hoardable ![gem version](https://img.shields.io/gem/v/hoardable?style=flat-square)
 
 Hoardable is an ActiveRecord extension for Ruby 2.6+, Rails 6.1+, and PostgreSQL that allows for
 versioning and soft-deletion of records through the use of _uni-temporal inherited tables_.
 
-#### nice... huh?
+[👉 Documentation](https://www.rubydoc.info/gems/hoardable)
+
+### huh?
 
 [Temporal tables](https://en.wikipedia.org/wiki/Temporal_database) are a database design pattern
 where each row of a table contains data along with one or more time ranges. In the case of this gem,
@@ -48,10 +50,18 @@ end
 Then, run the generator command to create a database migration and migrate it:
 
 ```
-bin/rails g hoardable:migration posts
+bin/rails g hoardable:migration Post
 bin/rails db:migrate
 ```
 
+By default, it will try to guess the foreign key type for the `_versions` table based on the primary
+key of the model specified in the migration generator above. If you want/need to specify this
+explicitly, you can do so:
+
+```
+bin/rails g hoardable:migration Post --foreign-key-type uuid
+```
+
 _Note:_ If you are on Rails 6.1, you might want to set `config.active_record.schema_format = :sql`
 in `application.rb`, so that the enum type is captured in your schema dump. This is not required in
 Rails 7.
@@ -75,10 +85,11 @@ A `Post` now `has_many :versions`. Whenever an update and deletion of a `Post` o
 created (by default):
 
 ```ruby
-post = Post.create!(attributes)
+post = Post.create!(title: "Title")
 post.versions.size # => 0
-post.update!(title: "Title")
+post.update!(title: "Revised Title")
 post.versions.size # => 1
+post.versions.first.title # => "Title"
 post.destroy!
 post.trashed? # true
 post.versions.size # => 2
@@ -120,17 +131,12 @@ need to query versions often, you should add appropriate indexes to the `_versio
 
 ### Tracking contextual data
 
-You’ll often want to track contextual data about the creation of a version. `hoardable` will
-automatically capture the ActiveRecord
-[changes](https://api.rubyonrails.org/classes/ActiveModel/Dirty.html#method-i-changes) hash and the
-`operation` that cause the version (`update` or `delete`). It will also tag all versions created in
-the same database transaction with a shared and unique `event_id`.
+You’ll often want to track contextual data about the creation of a version. There are 3 optional
+symbol keys that are provided for tracking contextual information:
 
-There 3 other optional keys that are provided for tracking contextual information:
-
-- `whodunit` - an identifier for who is responsible for creating the version
-- `note` - a string containing a description regarding the versioning
-- `meta` - any other contextual information you’d like to store along with the version
+- `:whodunit` - an identifier for who is responsible for creating the version
+- `:note` - a description regarding the versioning
+- `:meta` - any other contextual information you’d like to store along with the version
 
 This information is stored in a `jsonb` column. Each key’s value can be in the format of your
 choosing.
@@ -171,6 +177,17 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+`hoardable` will also automatically capture the ActiveRecord
+[changes](https://api.rubyonrails.org/classes/ActiveModel/Dirty.html#method-i-changes) hash, the
+`operation` that cause the version (`update` or `delete`), and it will also tag all versions created
+in the same database transaction with a shared and unique `event_uuid`. These are available as:
+
+```ruby
+version.changes
+version.hoardable_operation
+version.hoardable_event_uuid
+```
+
 ### Model Callbacks
 
 Sometimes you might want to do something with a version before or after it gets inserted to the
@@ -205,19 +222,22 @@ end
 
 ### Configuration
 
-There are two configurable options currently:
+There are three configurable options currently:
 
 ```ruby
 Hoardable.enabled # => default true
+Hoardable.version_updates # => default true
 Hoardable.save_trash # => default true
 ```
 
-`Hoardable.enabled` controls whether versions will be created at all.
+`Hoardable.enabled` controls whether versions will be ever be created.
+
+`Hoardable.version_updates` controls whether versions get created on record updates.
 
 `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.
 
-If you would like to temporarily set a config setting, you can use `Hoardable.with` as well:
+If you would like to temporarily set a config setting, you can use `Hoardable.with`:
 
 ```ruby
 Hoardable.with(enabled: false) do
@@ -225,8 +245,58 @@ Hoardable.with(enabled: false) do
 end
 ```
 
+You can also configure these variables per `ActiveRecord` class as well using `hoardable_options`:
+
+```ruby
+class Comment < ActiveRecord::Base
+  include Hoardable::Model
+  hoardable_options version_updates: false
+end
+```
+
+If either the model-level option or global option for a configuration variable is set to `false`,
+that behavior will be disabled.
+
+### 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.
+
+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:
+
+```ruby
+belongs_to :parent, -> { include_versions }
+```
+
+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:
+
+```ruby
+class Post < ActiveRecord::Base
+  include Hoardable::Model
+  has_many :comments, dependent: :destroy # `Comment` also includes `Hoardable::Model`
+
+  after_untrashed do
+    Comment
+      .version_class
+      .trashed
+      .where(post_id: id)
+      .with_hoardable_event_uuid(hoardable_event_uuid)
+      .find_each(&:untrash!)
+  end
+end
+```
+
 ## Contributing
 
+This gem is currently considered alpha and very open to feedback.
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/waymondo/hoardable.
 
 ## License

data/lib/generators/hoardable/migration_generator.rb

@@ -4,16 +4,25 @@ require 'rails/generators'
 require 'rails/generators/active_record/migration/migration_generator'
 
 module Hoardable
-  # Generates a migration for an inherited temporal table of a model including {Hoardable::Model}
+  # Generates a migration to create an inherited uni-temporal table of a model including
+  # {Hoardable::Model}, for the storage of +versions+.
   class MigrationGenerator < ActiveRecord::Generators::Base
     source_root File.expand_path('templates', __dir__)
     include Rails::Generators::Migration
+    class_option :foreign_key_type, type: :string
 
     def create_versions_table
       migration_template migration_template_name, "db/migrate/create_#{singularized_table_name}_versions.rb"
     end
 
     no_tasks do
+      def foreign_key_type
+        options[:foreign_key_type] ||
+          class_name.singularize.constantize.columns.find { |col| col.name == 'id' }.sql_type
+      rescue StandardError
+        'bigint'
+      end
+
       def migration_template_name
         if Gem::Version.new(ActiveRecord::Migration.current_version.to_s) < Gem::Version.new('7')
           'migration_6.rb.erb'

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

@@ -6,14 +6,14 @@ class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%=
     create_table :<%= singularized_table_name %>_versions, id: false, options: 'INHERITS (<%= table_name %>)' do |t|
       t.jsonb :_data
       t.tsrange :_during, null: false
-      t.enum :_operation, enum_type: 'hoardable_operation', null: false
-      t.bigint :<%= singularized_table_name %>_id, null: false, index: true
+      t.uuid :_event_uuid, null: false, index: true
+      t.enum :_operation, enum_type: 'hoardable_operation', null: false, index: true
+      t.<%= foreign_key_type %> :<%= singularized_table_name %>_id, null: false, index: true
     end
     add_index(
       :<%= singularized_table_name %>_versions,
       %i[_during <%= singularized_table_name %>_id],
       name: 'idx_<%= singularized_table_name %>_versions_temporally'
     )
-    add_index :<%= singularized_table_name %>_versions, :_operation
   end
 end

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

@@ -21,14 +21,14 @@ class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%=
     create_table :<%= singularized_table_name %>_versions, id: false, options: 'INHERITS (<%= table_name %>)' do |t|
       t.jsonb :_data
       t.tsrange :_during, null: false
-      t.column :_operation, :hoardable_operation, null: false
-      t.bigint :<%= singularized_table_name %>_id, null: false, index: true
+      t.uuid :_event_uuid, null: false, index: true
+      t.column :_operation, :hoardable_operation, null: false, index: true
+      t.<%= foreign_key_type %> :<%= singularized_table_name %>_id, null: false, index: true
     end
     add_index(
       :<%= singularized_table_name %>_versions,
       %i[_during <%= singularized_table_name %>_id],
       name: 'idx_<%= singularized_table_name %>_versions_temporally'
     )
-    add_index :<%= singularized_table_name %>_versions, :_operation
   end
 end

data/lib/hoardable/error.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Hoardable
-  # A subclass of StandardError for general use within Hoardable
+  # A subclass of +StandardError+ for general use within {Hoardable}.
   class Error < StandardError; end
 end

data/lib/hoardable/hoardable.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
-# An ActiveRecord extension for keeping versions of records in temporal inherited tables
+# An +ActiveRecord+ extension for keeping versions of records in uni-temporal inherited tables.
 module Hoardable
-  DATA_KEYS = %i[meta whodunit note event_id].freeze
-  CONFIG_KEYS = %i[enabled save_trash].freeze
-
+  # 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
+
+  # @!visibility private
   VERSION_CLASS_SUFFIX = 'Version'
+
+  # @!visibility private
   VERSION_TABLE_SUFFIX = "_#{VERSION_CLASS_SUFFIX.tableize}"
-  SAVE_TRASH_ENABLED = -> { Hoardable.save_trash }.freeze
+
+  # @!visibility private
   DURING_QUERY = '_during @> ?::timestamp'
 
   @context = {}
@@ -36,6 +44,9 @@ module Hoardable
       end
     end
 
+    # This is a general use method for setting {DATA_KEYS} or {CONFIG_KEYS} around a scoped block.
+    #
+    # @param hash [Hash] Options and contextual data to set within a block
     def with(hash)
       current_config = @config
       current_context = @context

data/lib/hoardable/model.rb

@@ -1,11 +1,36 @@
 # frozen_string_literal: true
 
 module Hoardable
-  # This concern dynamically generates the Version variant of the class module Model and includes
-  # the API methods and relationships on the source model
+  # This concern is the main entrypoint for using {Hoardable}. When included into an +ActiveRecord+
+  # class, it dynamically generates the +Version+ variant of that class (with {VersionModel}) and
+  # includes the {Hoardable} API methods and relationships on the source model class (through
+  # {SourceModel}).
   module Model
     extend ActiveSupport::Concern
 
+    class_methods do
+      # @!visibility private
+      attr_reader :_hoardable_options
+
+      # 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
+      # both model-level and global values.
+      #
+      # @param hash [Hash] The +Hoardable+ configuration for the model. Keys must be present in
+      #   {CONFIG_KEYS}
+      # @return [Hash]
+      def hoardable_options(hash = nil)
+        if hash
+          @_hoardable_options = hash.slice(*Hoardable::CONFIG_KEYS)
+        else
+          @_hoardable_options ||= {}
+          Hoardable::CONFIG_KEYS.to_h do |key|
+            [key, Hoardable.send(key) != false && @_hoardable_options[key] != false]
+          end
+        end
+      end
+    end
+
     included do
       define_model_callbacks :versioned
       define_model_callbacks :reverted, only: :after
@@ -15,9 +40,9 @@ module Hoardable
         next unless self == trace.self
 
         version_class_name = "#{name}#{VERSION_CLASS_SUFFIX}"
-        next if Object.const_defined?(version_class_name)
-
-        Object.const_set(version_class_name, Class.new(self) { include VersionModel })
+        unless Object.const_defined?(version_class_name)
+          Object.const_set(version_class_name, Class.new(self) { include VersionModel })
+        end
 
         include SourceModel
 

data/lib/hoardable/source_model.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 module Hoardable
-  # This concern contains the relationships, callbacks, and API methods for a Source model
+  # This concern contains the {Hoardable} relationships, callbacks, and API methods for an
+  # +ActiveRecord+. It is included by {Hoardable::Model} after the dynamic generation of the
+  # +Version+ class variant.
   module SourceModel
     extend ActiveSupport::Concern
 
     class_methods do
+      # The dynamically generated +Version+ class for this model.
       def version_class
         "#{name}#{VERSION_CLASS_SUFFIX}".constantize
       end
@@ -14,13 +17,22 @@ module Hoardable
     included do
       include Tableoid
 
-      around_update :insert_hoardable_version_on_update, if: :hoardable_callbacks_enabled
-      around_destroy :insert_hoardable_version_on_destroy, if: [:hoardable_callbacks_enabled, SAVE_TRASH_ENABLED]
-      before_destroy :delete_hoardable_versions, if: :hoardable_callbacks_enabled, unless: SAVE_TRASH_ENABLED
-      after_commit :unset_hoardable_version_and_event_id
+      around_update :insert_hoardable_version_on_update, if: %i[hoardable_callbacks_enabled hoardable_version_updates]
+      around_destroy :insert_hoardable_version_on_destroy, if: %i[hoardable_callbacks_enabled hoardable_save_trash]
+      before_destroy :delete_hoardable_versions, if: :hoardable_callbacks_enabled, unless: :hoardable_save_trash
+      after_commit :unset_hoardable_version_and_event_uuid
 
+      # This will contain the +Version+ class instance for use within +versioned+, +reverted+, and
+      # +untrashed+ callbacks.
       attr_reader :hoardable_version
 
+      # @!attribute [r] hoardable_event_uuid
+      #   @return [String] A postgres UUID that represents the +version+’s +ActiveRecord+ database transaction
+      # @!attribute [r] hoardable_operation
+      #   @return [String] The database operation that created the +version+ - either +update+ or +delete+.
+      delegate :hoardable_event_uuid, :hoardable_operation, to: :hoardable_version, allow_nil: true
+
+      # Returns all +versions+ in ascending order of their temporal timeframes.
       has_many(
         :versions, -> { order(:_during) },
         dependent: nil,
@@ -29,18 +41,45 @@ module Hoardable
       )
     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
     end
 
+    # Returns the +version+ at the supplied +datetime+ or +time+. It will return +self+ if there is
+    # none. This will raise an error if you try to find a version in the future.
+    #
+    # @param datetime [DateTime, Time]
     def at(datetime)
+      raise(Error, 'Future state cannot be known') if datetime.future?
+
       versions.find_by(DURING_QUERY, datetime) || self
     end
 
+    # If a version is found at the supplied datetime, it will +revert!+ to it and return it. This
+    # will raise an error if you try to revert to a version in the future.
+    #
+    # @param datetime [DateTime, Time]
+    def revert_to!(datetime)
+      return unless (version = at(datetime))
+
+      version.is_a?(self.class.version_class) ? version.revert! : self
+    end
+
     private
 
     def hoardable_callbacks_enabled
-      Hoardable.enabled && !self.class.name.end_with?(VERSION_CLASS_SUFFIX)
+      self.class.hoardable_options[:enabled] && !self.class.name.end_with?(VERSION_CLASS_SUFFIX)
+    end
+
+    def hoardable_save_trash
+      self.class.hoardable_options[:save_trash]
+    end
+
+    def hoardable_version_updates
+      self.class.hoardable_options[:version_updates]
     end
 
     def insert_hoardable_version_on_update(&block)
@@ -52,18 +91,15 @@ module Hoardable
     end
 
     def insert_hoardable_version(operation, attrs)
-      event_id = find_or_initialize_hoardable_event_id
-      Hoardable.with(event_id: event_id) do
-        @hoardable_version = initialize_hoardable_version(operation, attrs)
-        run_callbacks(:versioned) do
-          yield
-          hoardable_version.save(validate: false, touch: false)
-        end
+      @hoardable_version = initialize_hoardable_version(operation, attrs)
+      run_callbacks(:versioned) do
+        yield
+        hoardable_version.save(validate: false, touch: false)
       end
     end
 
-    def find_or_initialize_hoardable_event_id
-      Thread.current[:hoardable_event_id] ||= SecureRandom.hex
+    def find_or_initialize_hoardable_event_uuid
+      Thread.current[:hoardable_event_uuid] ||= ActiveRecord::Base.connection.query('SELECT gen_random_uuid();')[0][0]
     end
 
     def initialize_hoardable_version(operation, attrs)
@@ -71,6 +107,7 @@ module Hoardable
         attrs.merge(
           changes.transform_values { |h| h[0] },
           {
+            _event_uuid: find_or_initialize_hoardable_event_uuid,
             _operation: operation,
             _data: initialize_hoardable_data.merge(changes: changes)
           }
@@ -94,11 +131,11 @@ module Hoardable
       versions.delete_all(:delete_all)
     end
 
-    def unset_hoardable_version_and_event_id
+    def unset_hoardable_version_and_event_uuid
       @hoardable_version = nil
       return if ActiveRecord::Base.connection.transaction_open?
 
-      Thread.current[:hoardable_event_id] = nil
+      Thread.current[:hoardable_event_uuid] = nil
     end
   end
 end

data/lib/hoardable/tableoid.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 module Hoardable
-  # This concern provides support for PostgreSQL's tableoid system column
+  # This concern provides support for PostgreSQL’s tableoid system column to {SourceModel}.
   module Tableoid
     extend ActiveSupport::Concern
 
+    # @!visibility private
     TABLEOID_AREL_CONDITIONS = lambda do |arel_table, condition|
       arel_table[:tableoid].send(
         condition,
@@ -13,13 +14,32 @@ module Hoardable
     end.freeze
 
     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)) }
+
+      # @!scope class
+      # @!method include_versions
+      # @return [ActiveRecord<Object>]
+      #
+      # Returns +versions+ along with instances of the source models, all cast as instances of the
+      # source model’s class.
       scope :include_versions, -> { unscope(where: [:tableoid]) }
+
+      # @!scope class
+      # @!method versions
+      # @return [ActiveRecord<Object>]
+      #
+      # 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)) }
     end
 
+    private
+
     def tableoid
       connection.execute("SELECT oid FROM pg_class WHERE relname = '#{table_name}'")[0]['oid']
     end

data/lib/hoardable/version.rb

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

data/lib/hoardable/version_model.rb

@@ -1,31 +1,58 @@
 # frozen_string_literal: true
 
 module Hoardable
-  # This concern is included into the dynamically generated Version models.
+  # This concern is included into the dynamically generated +Version+ kind of the parent
+  # +ActiveRecord+ class.
   module VersionModel
     extend ActiveSupport::Concern
 
     included do
       hoardable_source_key = superclass.model_name.i18n_key
+
+      # A +version+ belongs to it’s parent +ActiveRecord+ source.
       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}"
 
       alias_method :readonly?, :persisted?
+      alias_attribute :hoardable_operation, :_operation
+      alias_attribute :hoardable_event_uuid, :_event_uuid
+      alias_attribute :hoardable_during, :_during
 
       before_create :assign_temporal_tsrange
 
+      # @!scope class
+      # @!method trashed
+      # @return [ActiveRecord<Object>]
+      #
+      # Returns only trashed +versions+ that are orphans.
       scope :trashed, lambda {
         left_outer_joins(hoardable_source_key)
           .where(superclass.table_name => { id: nil })
           .where(_operation: 'delete')
       }
+
+      # @!scope class
+      # @!method at
+      # @return [ActiveRecord<Object>]
+      #
+      # Returns +versions+ that were valid at the supplied +datetime+ or +time+.
       scope :at, ->(datetime) { where(DURING_QUERY, datetime) }
+
+      # @!scope class
+      # @!method with_hoardable_event_uuid
+      # @return [ActiveRecord<Object>]
+      #
+      # 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) }
     end
 
+    # Reverts the parent +ActiveRecord+ instance to the saved attributes of this +version+. Raises
+    # an error if the version is trashed.
     def revert!
-      raise(Error, 'Version is trashed, cannot revert') unless _operation == 'update'
+      raise(Error, 'Version is trashed, cannot revert') unless hoardable_operation == 'update'
 
       transaction do
         hoardable_source.tap do |reverted|
@@ -36,8 +63,10 @@ module Hoardable
       end
     end
 
+    # Inserts a trashed +version+ back into its parent +ActiveRecord+ table with its original
+    # primary key. Raises an error if the version is not trashed.
     def untrash!
-      raise(Error, 'Version is not trashed, cannot untrash') unless _operation == 'delete'
+      raise(Error, 'Version is not trashed, cannot untrash') unless hoardable_operation == 'delete'
 
       transaction do
         superscope = self.class.superclass.unscoped
@@ -55,6 +84,9 @@ module Hoardable
       end
     end
 
+    # Returns the +ActiveRecord+
+    # {https://api.rubyonrails.org/classes/ActiveModel/Dirty.html#method-i-changes changes} that
+    # were present during version creation.
     def changes
       _data&.dig('changes')
     end

data/sig/hoardable.rbs

@@ -1,4 +1,86 @@
 module Hoardable
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  DATA_KEYS: [:meta, :whodunit, :note, :event_uuid]
+  CONFIG_KEYS: [:enabled, :version_updates, :save_trash]
+  VERSION_CLASS_SUFFIX: String
+  VERSION_TABLE_SUFFIX: String
+  DURING_QUERY: String
+  self.@context: Hash[untyped, untyped]
+  self.@config: untyped
+
+  def self.with: (untyped hash) -> untyped
+
+  module Tableoid
+    TABLEOID_AREL_CONDITIONS: Proc
+
+    private
+    def tableoid: -> untyped
+
+    public
+    attr_writer tableoid: untyped
+  end
+
+  class Error < StandardError
+  end
+
+  module SourceModel
+    include Tableoid
+
+    def trashed?: -> untyped
+    def at: (untyped datetime) -> SourceModel
+    def revert_to!: (untyped datetime) -> SourceModel?
+
+    private
+    def hoardable_callbacks_enabled: -> untyped
+    def hoardable_save_trash: -> untyped
+    def hoardable_version_updates: -> untyped
+    def insert_hoardable_version_on_update: -> untyped
+    def insert_hoardable_version_on_destroy: -> untyped
+    def insert_hoardable_version: (String operation, untyped attrs) -> untyped
+    def find_or_initialize_hoardable_event_uuid: -> untyped
+    def initialize_hoardable_version: (String operation, untyped attrs) -> untyped
+    def initialize_hoardable_data: -> untyped
+    def assign_hoardable_context: (:event_uuid | :meta | :note | :whodunit key) -> nil
+    def delete_hoardable_versions: -> untyped
+    def unset_hoardable_version_and_event_uuid: -> nil
+
+    public
+    def version_class: -> untyped
+    attr_reader hoardable_version: nil
+  end
+
+  module VersionModel
+    @hoardable_source_attributes: untyped
+    @hoardable_source_foreign_key: String
+    @hoardable_source_foreign_id: untyped
+
+    def revert!: -> untyped
+    def untrash!: -> untyped
+    def changes: -> untyped
+
+    private
+    def untrashable_hoardable_source_attributes: -> untyped
+    def hoardable_source_attributes: -> untyped
+    def hoardable_source_foreign_key: -> String
+    def hoardable_source_foreign_id: -> untyped
+    def previous_temporal_tsrange_end: -> untyped
+    def assign_temporal_tsrange: -> Range
+  end
+
+  module Model
+    include VersionModel
+    include SourceModel
+
+    attr_reader _hoardable_options: Hash[untyped, untyped]
+    def hoardable_options: (?nil hash) -> untyped
+  end
+
+  class MigrationGenerator
+    @singularized_table_name: untyped
+
+    def create_versions_table: -> untyped
+    def foreign_key_type: -> String
+    def migration_template_name: -> String
+    def singularized_table_name: -> untyped
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hoardable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.4
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-28 00:00:00.000000000 Z
+date: 2022-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord