hoardable 0.1.0 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24eee9ce1b76bd2d5a40a6b527ef4e048c25850ea454f75b2838f45b21339c25
-  data.tar.gz: e464f7418ec2527ed6fe598b4575481a01d50fea236631749d0722bdd328c66f
+  metadata.gz: 96952d8928266fc5ae03199a91e85428565ff11385a74851fe61fd3a8eafc881
+  data.tar.gz: 1b9117cbf4ea08325d29212c16580e368a857b12f8c2d20bc346d9e8f5268d59
 SHA512:
-  metadata.gz: a617926045371fa040ae329241fe37a5ea58ea4fdcd43c2c66f0c3fe2b89cc0b5c2723371c88c9946b4bda4cf20d477a936494a32f6e8e39b9a1b5e727c7e9b4
-  data.tar.gz: 283ee7c613a1d07b227e32dc823914ea2cdc9b144a9b9d03c0155adf21cdeeacecd92ba8d173d2c0c4bf17febbd1343571898db7c5e24ea828e0f261ae82cbb7
+  metadata.gz: e533edf9412339fcc90691fa5d10395265914f71f7f7493c9afc226902cf831db87f69661d565630602e2db815549e4209550420abc44f6a7d179ccb23ba7509
+  data.tar.gz: a8c690b0a3399f3853ed6c65ca7d514af9c82d10569483d7d4bed86c6e7a63d1881ecac61e13d6646facdce3370614dc6c86f88599bc6eb955feba38589c398c

data/Gemfile

@@ -2,11 +2,12 @@
 
 source 'https://rubygems.org'
 
-gemspec
-
 gem 'debug', '~> 1.6'
 gem 'minitest', '~> 5.0'
 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,23 +1,27 @@
-# 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**.
+versioning and soft-deletion of records through the use of _uni-temporal inherited tables_.
 
-### 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 contains data as well as one or more time ranges. In the case of a temporal table
-representing versions, each row has one time range representing the row’s valid time range, hence
+where each row of a table contains data along with one or more time ranges. In the case of this gem,
+each database row has a time range that represents the row’s valid time range - hence
 "uni-temporal".
 
 [Table inheritance](https://www.postgresql.org/docs/14/ddl-inherit.html) is a feature of PostgreSQL
-that allows a table to inherit all columns of another table. The descendant table’s schema will stay
-in sync with all columns that it inherits from it’s parent. If a new column or removed from the
-parent, the schema change is reflected on its descendants.
+that allows a table to inherit all columns of a parent table. The descendant table’s schema will
+stay in sync with its parent. If a new column is added to or removed from the parent, the schema
+change is reflected on its descendants.
 
-With these principles combined, `hoardable` offers a simple and effective model versioning system,
-where versions of records are stored in a separate, inherited table with the validity time range and
-other versioning data.
+With these concepts combined, `hoardable` offers a simple and effective model versioning system for
+Rails. Versions of records are stored in separate, inherited tables along with their valid time
+ranges and contextual data. Compared to other Rails-oriented versioning systems, this gem strives to
+be more explicit and obvious on the lower RDBS level while still familiar and convenient within Ruby
+on Rails.
 
 ## Installation
 
@@ -31,68 +35,88 @@ And then execute `bundle install`.
 
 ### Model Installation
 
-First, include `Hoardable::Model` into a model you would like to hoard versions of:
+You must include `Hoardable::Model` into an ActiveRecord model that you would like to hoard versions
+of:
 
 ```ruby
 class Post < ActiveRecord::Base
   include Hoardable::Model
   belongs_to :user
+  has_many :comments, dependent: :destroy
+  ...
 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.
+
 ## Usage
 
-### Basics
+### Overview
 
 Once you include `Hoardable::Model` into a model, it will dynamically generate a "Version" subclass
-of that model. Continuing our example above:
+of that model. As we continue our example above, :
 
 ```
+$ irb
 >> Post
 => Post(id: integer, body: text, user_id: integer, created_at: datetime)
 >> PostVersion
 => PostVersion(id: integer, body: text, user_id: integer, created_at: datetime, _data: jsonb, _during: tsrange, post_id: integer)
 ```
 
-A `Post` now `has_many :versions` which are created on every update and deletion of a `Post` (by
-default):
+A `Post` now `has_many :versions`. Whenever an update and deletion of a `Post` occurs, a version is
+created (by default):
 
 ```ruby
-post_id = post.id
+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.reload # => ActiveRecord::RecordNotFound
-PostVersion.where(post_id: post_id).size # => 2
+post.trashed? # true
+post.versions.size # => 2
+Post.find(post.id) # raises ActiveRecord::RecordNotFound
 ```
 
 Each `PostVersion` has access to the same attributes, relationships, and other model behavior that
-`Post` has, but is a read-only record.
+`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 the
-source post had been deleted, this will untrash it with it’s original primary key.
+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.
 
 ### Querying and Temporal Lookup
 
-Since a `PostVersion` is just a normal `ActiveRecord`, you can query them like another model
-resource, i.e:
+Since a `PostVersion` is an `ActiveRecord` class, you can query them like another model resource:
 
 ```ruby
-post.versions.where(user_id: Current.user.id, body: nil)
+post.versions.where(user_id: Current.user.id, body: "Cool!")
 ```
 
-If you want to look-up the version of a `Post` at a specific time, you can use the `.at` method:
+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>
 ```
 
 By default, `hoardable` will keep copies of records you have destroyed. You can query for them as
@@ -103,26 +127,27 @@ PostVersion.trashed
 ```
 
 _Note:_ Creating an inherited table does not copy over the indexes from the parent table. If you
-need to query versions often, you will need to add those indexes to the `_versions` tables manually.
+need to query versions often, you should add appropriate indexes to the `_versions` tables.
 
 ### Tracking contextual data
 
-You’ll often want to track contextual data about a version. `hoardable` will automatically capture
-the ActiveRecord `changes` hash and `operation` that cause the version (`update` or `delete`).
-
-There are also 3 other optional keys that are provided for tracking contextual information:
+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:
 
-- `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.
 
-One convenient way to assign this contextual data is with a proc in an initializer, i.e.:
+One convenient way to assign contextual data to these is by defining a proc in an initializer, i.e.:
 
 ```ruby
 Hoardable.whodunit = -> { Current.user&.id }
+Current.user = User.find(123)
+post.update!(status: 'live')
+post.versions.last.hoardable_whodunit # => 123
 ```
 
 You can also set this context manually as well, just remember to clear them afterwards.
@@ -134,7 +159,7 @@ Hoardable.note = nil
 post.versions.last.hoardable_note # => "reverting due to accidental deletion"
 ```
 
-Another useful pattern is to use `Hoardable.with` to set the context around a block. A good example
+A more useful pattern is to use `Hoardable.with` to set the context around a block. A good example
 of this would be in `ApplicationController`:
 
 ```ruby
@@ -147,38 +172,59 @@ 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
   end
 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 it gets saved. You can access it in a
-`before_save` callback as `hoardable_version`. There is also an `after_reverted` callback available
-as well.
+Sometimes you might want to do something with a version before or after it gets inserted to the
+database. You can access it in `before/after/around_versioned` callbacks on the source record as
+`hoardable_version`. These happen around `.save`, which is enclosed in an ActiveRecord transaction.
 
-``` ruby
+There are also `after_reverted` and `after_untrashed` callbacks available as well, which are called
+on the source record after a version is reverted or untrashed.
+
+```ruby
 class User
-  before_save :sanitize_version
+  include Hoardable::Model
+  before_versioned :sanitize_version
   after_reverted :track_reverted_event
+  after_untrashed :track_untrashed_event
 
   private
 
   def sanitize_version
     hoardable_version.sanitize_password
-  end 
+  end
 
   def track_reverted_event
     track_event(:user_reverted, self)
   end
+
+  def track_untrashed_event
+    track_event(:user_untrashed, self)
+  end
 end
 ```
 
 ### Configuration
 
-There are two available options:
+There are two configurable options currently:
 
-``` ruby
+```ruby
 Hoardable.enabled # => default true
 Hoardable.save_trash # => default true
 ```
@@ -196,8 +242,46 @@ Hoardable.with(enabled: false) do
 end
 ```
 
+### 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,33 @@ 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.rb.erb', "db/migrate/create_#{singularized_table_name}_versions.rb"
+      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'
+        else
+          'migration.rb.erb'
+        end
+      end
+
       def singularized_table_name
         @singularized_table_name ||= table_name.singularize
       end

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

@@ -2,11 +2,18 @@
 
 class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
+    create_enum :hoardable_operation, %w[update delete]
     create_table :<%= singularized_table_name %>_versions, id: false, options: 'INHERITS (<%= table_name %>)' do |t|
       t.jsonb :_data
       t.tsrange :_during, 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]
+    add_index(
+      :<%= singularized_table_name %>_versions,
+      %i[_during <%= singularized_table_name %>_id],
+      name: 'idx_<%= singularized_table_name %>_versions_temporally'
+    )
   end
 end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    reversible do |dir|
+      dir.up do
+        execute <<~SQL
+          DO $$
+          BEGIN
+              IF NOT EXISTS (
+                SELECT 1 FROM pg_type t
+                WHERE t.typname = 'hoardable_operation'
+              ) THEN
+                CREATE TYPE hoardable_operation AS ENUM ('update', 'delete');
+              END IF;
+          END
+          $$;
+        SQL
+      end
+    end
+    create_table :<%= singularized_table_name %>_versions, id: false, options: 'INHERITS (<%= table_name %>)' do |t|
+      t.jsonb :_data
+      t.tsrange :_during, null: false
+      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'
+    )
+  end
+end

data/lib/hoardable/error.rb

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

data/lib/hoardable/hoardable.rb

@@ -1,11 +1,26 @@
 # 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
-  VERSION = '0.1.0'
-  DATA_KEYS = %i[changes meta whodunit note operation].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 save_trash].freeze
 
+  # @!visibility private
+  VERSION_CLASS_SUFFIX = 'Version'
+
+  # @!visibility private
+  VERSION_TABLE_SUFFIX = "_#{VERSION_CLASS_SUFFIX.tableize}"
+
+  # @!visibility private
+  SAVE_TRASH_ENABLED = -> { Hoardable.save_trash }.freeze
+
+  # @!visibility private
+  DURING_QUERY = '_during @> ?::timestamp'
+
   @context = {}
   @config = CONFIG_KEYS.to_h do |key|
     [key, true]
@@ -32,6 +47,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,78 +1,30 @@
 # frozen_string_literal: true
 
 module Hoardable
-  # This concern includes the Hoardable API methods on ActiveRecord instances and dynamically
-  # generates the Version variant of the class
+  # 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
 
     included do
-      default_scope { where("#{table_name}.tableoid = '#{table_name}'::regclass") }
-
-      before_update :initialize_hoardable_version, if: -> { Hoardable.enabled }
-      before_destroy :initialize_hoardable_version, if: -> { Hoardable.enabled && Hoardable.save_trash }
-      after_update :save_hoardable_version, if: -> { Hoardable.enabled }
-      before_destroy :delete_hoardable_versions, if: -> { Hoardable.enabled && !Hoardable.save_trash }
-      after_destroy :save_hoardable_version, if: -> { Hoardable.enabled && Hoardable.save_trash }
-
-      attr_reader :hoardable_version
-
+      define_model_callbacks :versioned
       define_model_callbacks :reverted, only: :after
+      define_model_callbacks :untrashed, only: :after
 
       TracePoint.new(:end) do |trace|
         next unless self == trace.self
 
-        version_class_name = "#{name}Version"
-        next if Object.const_defined?(version_class_name)
+        version_class_name = "#{name}#{VERSION_CLASS_SUFFIX}"
+        unless Object.const_defined?(version_class_name)
+          Object.const_set(version_class_name, Class.new(self) { include VersionModel })
+        end
+
+        include SourceModel
 
-        Object.const_set(version_class_name, Class.new(self) { include VersionModel })
-        has_many(
-          :versions, -> { order(:_during) },
-          dependent: nil,
-          class_name: version_class_name,
-          inverse_of: model_name.i18n_key
-        )
         trace.disable
       end.enable
     end
-
-    def at(datetime)
-      versions.find_by('_during @> ?::timestamp', datetime) || self
-    end
-
-    private
-
-    def initialize_hoardable_version
-      Hoardable.with(changes: changes) do
-        @hoardable_version = versions.new(
-          attributes_before_type_cast
-            .without('id')
-            .merge(changes.transform_values { |h| h[0] })
-            .merge(_data: initialize_hoardable_data)
-        )
-      end
-    end
-
-    def initialize_hoardable_data
-      DATA_KEYS.to_h do |key|
-        [key, assign_hoardable_context(key)]
-      end
-    end
-
-    def assign_hoardable_context(key)
-      return nil if (value = Hoardable.public_send(key)).nil?
-
-      value.is_a?(Proc) ? value.call : value
-    end
-
-    def save_hoardable_version
-      hoardable_version._data['operation'] = persisted? ? 'update' : 'delete'
-      hoardable_version.save!(validate: false, touch: false)
-      @hoardable_version = nil
-    end
-
-    def delete_hoardable_versions
-      versions.delete_all(:delete_all)
-    end
   end
 end

data/lib/hoardable/source_model.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # 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
+    end
+
+    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_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,
+        class_name: version_class.to_s,
+        inverse_of: model_name.i18n_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
+    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)
+    end
+
+    def insert_hoardable_version_on_update(&block)
+      insert_hoardable_version('update', attributes_before_type_cast.without('id'), &block)
+    end
+
+    def insert_hoardable_version_on_destroy(&block)
+      insert_hoardable_version('delete', attributes_before_type_cast, &block)
+    end
+
+    def insert_hoardable_version(operation, attrs)
+      @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_uuid
+      Thread.current[:hoardable_event_uuid] ||= ActiveRecord::Base.connection.query('SELECT gen_random_uuid();')[0][0]
+    end
+
+    def initialize_hoardable_version(operation, attrs)
+      versions.new(
+        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)
+          }
+        )
+      )
+    end
+
+    def initialize_hoardable_data
+      DATA_KEYS.to_h do |key|
+        [key, assign_hoardable_context(key)]
+      end
+    end
+
+    def assign_hoardable_context(key)
+      return nil if (value = Hoardable.public_send(key)).nil?
+
+      value.is_a?(Proc) ? value.call : value
+    end
+
+    def delete_hoardable_versions
+      versions.delete_all(:delete_all)
+    end
+
+    def unset_hoardable_version_and_event_uuid
+      @hoardable_version = nil
+      return if ActiveRecord::Base.connection.transaction_open?
+
+      Thread.current[:hoardable_event_uuid] = nil
+    end
+  end
+end

data/lib/hoardable/tableoid.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # 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,
+        Arel::Nodes::NamedFunction.new('CAST', [Arel::Nodes::Quoted.new(arel_table.name).as('regclass')])
+      )
+    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
+  end
+end

data/lib/hoardable/version.rb

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

data/lib/hoardable/version_model.rb

@@ -1,35 +1,79 @@
 # 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}_versions"
+      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("_data ->> 'operation' = 'delete'")
+          .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 hoardable_operation == 'update'
+
       transaction do
-        (
-          hoardable_source&.tap { |tapped| tapped.update!(hoardable_source_attributes.without('id')) } ||
-          untrash
-        ).tap do |tapped|
-          tapped.run_callbacks(:reverted)
+        hoardable_source.tap do |reverted|
+          reverted.update!(hoardable_source_attributes.without('id'))
+          reverted.instance_variable_set(:@hoardable_version, self)
+          reverted.run_callbacks(:reverted)
+        end
+      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 hoardable_operation == 'delete'
+
+      transaction do
+        superscope = self.class.superclass.unscoped
+        superscope.insert(untrashable_hoardable_source_attributes)
+        superscope.find(hoardable_source_foreign_id).tap do |untrashed|
+          untrashed.instance_variable_set(:@hoardable_version, self)
+          untrashed.run_callbacks(:untrashed)
         end
       end
     end
@@ -40,14 +84,19 @@ module Hoardable
       end
     end
 
-    alias changes hoardable_changes
+    # 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
 
     private
 
-    def untrash
-      foreign_id = public_send(hoardable_source_foreign_key)
-      self.class.superclass.insert(hoardable_source_attributes.merge('id' => foreign_id, 'updated_at' => Time.now))
-      self.class.superclass.find(foreign_id)
+    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
 
     def hoardable_source_attributes
@@ -61,12 +110,24 @@ module Hoardable
       @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
     end
 
     def assign_temporal_tsrange
-      self._during = ((previous_temporal_tsrange_end || hoardable_source.created_at)..Time.now)
+      range_start = (
+        previous_temporal_tsrange_end ||
+        if hoardable_source.class.column_names.include?('created_at')
+          hoardable_source.created_at
+        else
+          Time.at(0)
+        end
+      )
+      self._during = (range_start..Time.now)
     end
   end
 end

data/lib/hoardable.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
+require_relative 'hoardable/version'
 require_relative 'hoardable/hoardable'
+require_relative 'hoardable/tableoid'
+require_relative 'hoardable/error'
+require_relative 'hoardable/source_model'
 require_relative 'hoardable/version_model'
 require_relative 'hoardable/model'
 require_relative 'generators/hoardable/migration_generator'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hoardable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-26 00:00:00.000000000 Z
+date: 2022-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -51,45 +51,45 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '8'
 - !ruby/object:Gem::Dependency
-  name: pg
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '8'
 - !ruby/object:Gem::Dependency
-  name: railties
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '2'
 description: Rails model versioning with the power of uni-temporal inherited tables
 email:
 - justin@waymondo.com
@@ -106,9 +106,14 @@ files:
 - Rakefile
 - lib/generators/hoardable/migration_generator.rb
 - lib/generators/hoardable/templates/migration.rb.erb
+- lib/generators/hoardable/templates/migration_6.rb.erb
 - lib/hoardable.rb
+- lib/hoardable/error.rb
 - lib/hoardable/hoardable.rb
 - lib/hoardable/model.rb
+- lib/hoardable/source_model.rb
+- lib/hoardable/tableoid.rb
+- lib/hoardable/version.rb
 - lib/hoardable/version_model.rb
 - sig/hoardable.rbs
 homepage: https://github.com/waymondo/hoardable