hoardable 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b85dfaf658e447049fcb09281d34dd25188be79f948eda294398f47b19b8244
-  data.tar.gz: 67219612736259e2dbc542230cc1490a156a15bc679340176aca35b76aaf516c
+  metadata.gz: 2d9f9ea3a4559d3a4515357eabc0c7ee05526ee1308a4e6eef111f2d6207aef6
+  data.tar.gz: be0011cb1ea9d3fcdcd5d1a4f4951d7185371cc1d05c91dfd27ea163b59620b7
 SHA512:
-  metadata.gz: cf3c5edfeac5526e7520dc2584caba8bb5399df43acf1ce6bd320b19f44981c154624b9b80c5b415aaeb840fc5d718f1999b4bbaf82eb3ff76149e09621ab0e5
-  data.tar.gz: 52112fb9bc55bec2009656cce9571887130333b6460d5478c1a0c113895ccb977ffcc80172954911c6e70d2012f136bf68c64b17bc69ffd7deeaa40a56c97646
+  metadata.gz: 20ebc8d7ec2924e43e6bbd806e7aaf08350653b695dc4aef16de28359ceb95d8de16da4c19790e8b1212bc8d8d202caeb3614e05b326977bd470defe48e4b731
+  data.tar.gz: fc3fa92ae0ab25bee4122456b889f86eec75b0eee4efba742dced8737d7bc9ab3a99e63e63839f49089183900df8ed54a315a4561aad634c0e2ea3fa56aa8732

data/CHANGELOG.md

@@ -2,57 +2,3 @@
 
 - Stability is coming.
 
-## [0.9.0] - 2022-10-02
-
-- **Breaking Change** - `Hoardable.return_everything` was removed in favor of the newly added
-  `Hoardable.at`.
-
-## [0.8.0] - 2022-10-01
-
-- **Breaking Change** - Due to the performance benefit of using `insert` for database injection of
-  versions, and a personal opinion that only an `after_versioned` hook might be needed, the
-  `before_versioned` and `around_versioned` ActiveRecord hooks are removed.
-
-- **Breaking Change** - Another side effect of the performance benefit gained by using `insert` is
-  that a source model will need to be reloaded before a call to `versions` on it can access the
-  latest version after an `update` on the source record.
-
-- **Breaking Change** - Previously the inherited `_versions` tables did not have a unique index on
-  the ID column, though it still pulled from the same sequence as the parent table. Prior to version
-  0.4.0 though, it was possible to have multiple trashed versions with the same ID. Adding unique
-  indexes to version tables prior to version 0.4.0 could result in issues.
-
-## [0.7.0] - 2022-09-29
-
-- **Breaking Change** - Continuing along with the change below, the `foreign_key` on the `_versions`
-  tables is now changed to `hoardable_source_id` instead of the i18n model name dervied foreign key.
-  The intent is to never leave room for conflict of foreign keys for existing relationships. This
-  can be resolved by renaming the foreign key columns from their i18n model name derived column
-  names to `hoardable_source_id`, i.e. `rename_column :post_versions, :post_id, :hoardable_source_id`.
-
-## [0.6.0] - 2022-09-28
-
-- **Breaking Change** - Previously, a source model would `has_many :versions` with an inverse
-  relationship based on the i18n interpreted name of the source model. Now it simply `has_many
-  :versions, inverse_of :hoardable_source` to not potentially conflict with previously existing
-  relationships.
-
-## [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/Gemfile

@@ -5,6 +5,7 @@ source 'https://rubygems.org'
 gem 'benchmark-ips', '~> 2.10'
 gem 'debug', '~> 1.6'
 gem 'minitest', '~> 5.0'
+gem 'rails', '>= 6.1'
 gem 'rake', '~> 13.0'
 gem 'rubocop', '~> 1.21'
 gem 'rubocop-minitest', '~> 0.20'

data/README.md

@@ -29,14 +29,19 @@ Add this line to your application's Gemfile:
 gem 'hoardable'
 ```
 
-And then execute `bundle install`.
-
-If you would like to generate an initializer with the global [configuration](#configuration) options:
+Run `bundle install`, and then run:
 
 ```
-rails g hoardable:initializer
+bin/rails g hoardable:install
+bin/rails db:migrate
 ```
 
+This will generate a PostgreSQL function and an initiailzer.
+
+_Note:_ It is recommended to set `config.active_record.schema_format = :sql` in `application.rb`, so
+that the function and triggers in the migrations that prevent updates to the versions table get
+captured in your schema.
+
 ### Model Installation
 
 You must include `Hoardable::Model` into an ActiveRecord model that you would like to hoard versions
@@ -66,10 +71,6 @@ 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.
-
 _Note:_ Creating an inherited table does not copy over the indexes from the parent table. If you
 need to query versions often, you should add appropriate indexes to the `_versions` tables.
 
@@ -164,12 +165,11 @@ specifically with:
 ```ruby
 PostVersion.trashed
 Post.version_class.trashed # <- same thing as above
-PostVersion.trashed.first.trashed? # <- true
 ```
 
 _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.
+`created_at` timestamp column. If this is missing, an error will be raised.
 
 ### Tracking Contextual Data
 
@@ -318,25 +318,25 @@ with `Hoardable` considerations.
 
 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`:
+to have `belongs_to` resolve to the trashed parent model in this case, you can give it the option of
+`trashable: true`:
 
 ```ruby
 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
+  belongs_to :post, trashable: true
 end
 ```
 
 Sometimes you'll have a Hoardable record that `has_many` other Hoardable records and you will want
 to know the state of both the parent record and the children at a cetain point in time. You
-accomplish this by establishing a `has_many_hoardable` relationship and using the `Hoardable.at`
-method:
+accomplish this by adding `hoardable: true` to the `has_many` relationship and using the
+`Hoardable.at` method:
 
 ```ruby
 class Post
   include Hoardable::Model
-  has_many_hoardable :comments
+  has_many :comments, hoardable: true
 end
 
 def Comment
@@ -352,7 +352,7 @@ post.update!(title: 'New Title')
 post_id = post.id # 1
 
 Hoardable.at(datetime) do
-  post = Post.hoardable.find(post_id)
+  post = Post.find(post_id)
   post.title # => 'Title'
   post.comments.size # => 2
   post.id # => 2
@@ -370,11 +370,9 @@ version, even though it is masquerading as a `Post`.
 
 If you are ever unsure if a Hoardable record is a "source" or a "version", you can be sure by
 calling `version?` on it. If you want to get the true original source record ID, you can call
-`hoardable_source_id`. Finally, if you prepend `.hoardable` to a `.find` call on the source model
-class, you can always find the relevant source or temporal version record using just the original
-source record’s id.
+`hoardable_source_id`. 
 
-Sometimes you’ll trash something that `has_many_hoardable :children, dependent: :destroy` and want
+Sometimes you’ll trash something that `has_many :children, dependent: :destroy` and want
 to untrash everything in a similar dependent manner. 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 record, you can find and `untrash!`
@@ -383,7 +381,7 @@ records that were trashed with it:
 ```ruby
 class Post < ActiveRecord::Base
   include Hoardable::Model
-  has_many_hoardable :comments, dependent: :destroy # `Comment` also includes `Hoardable::Model`
+  has_many :comments, hoardable: true, dependent: :destroy # `Comment` also includes `Hoardable::Model`
 
   after_untrashed do
     Comment
@@ -395,9 +393,42 @@ class Post < ActiveRecord::Base
 end
 ```
 
+## ActionText
+
+Hoardable provides support for ActiveRecord models with `has_rich_text`. First, you must create a
+temporal table for `ActionText::RichText`:
+
+```
+bin/rails g hoardable:migration ActionText::RichText
+bin/rails db:migrate
+```
+
+Then in your model, include `Hoardable::Model` and provide the `hoardable: true` keyword to
+`has_rich_text`:
+
+``` ruby
+class Post < ActiveRecord::Base
+  include Hoardable::Model # or `Hoardable::Associations` if you don't need `PostVersion`
+  has_rich_text :content, hoardable: true
+end
+```
+
+Now the `rich_text_content` relationship will be managed as a Hoardable `has_one` relationship:
+
+``` ruby
+post = Post.create!(content: '<div>Hello World</div>')
+datetime = DateTime.current
+post.update!(content: '<div>Goodbye Cruel World</div>')
+post.content.versions.size # => 1
+assert_equal post.content.to_plain_text, 'Goodbye Cruel World'
+Hoardable.at(datetime) do
+  assert_equal post.content.to_plain_text, 'Hello World'
+end
+```
+
 ## 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
@@ -410,7 +441,7 @@ same database columns as their parents, which are more efficient for querying as
 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)
+#### [`audited`](https://github.com/collectiveidea/audited)
 
 `audited` works in a similar manner as `paper_trail`. It stores all versions for all model types in
 a single table, you must opt into using `jsonb` as the column type to store "changes", in case you
@@ -418,7 +449,7 @@ want to query them, and there is no concept of a `temporal` time-frame for a sin
 makes opinionated decisions about contextual data requirements and stores them as top level data
 types on the `audited` table.
 
-### [`discard`](https://github.com/jhawthorn/discard)
+#### [`discard`](https://github.com/jhawthorn/discard)
 
 `discard` only covers soft-deletion. The act of "soft deleting" a record is only captured through
 the time-stamping of a `discarded_at` column on the records table; there is no other capturing of
@@ -427,7 +458,7 @@ record is restored, the previous "discarded" awareness is lost. Since "discarded
 the same table as "undiscarded" records, you must explicitly omit the discarded records from queries
 across your app to keep them from leaking in.
 
-### [`paranoia`](https://github.com/rubysherpas/paranoia)
+#### [`paranoia`](https://github.com/rubysherpas/paranoia)
 
 `paranoia` also only covers soft-deletion. In their README, they recommend using `discard` instead
 of `paranoia` because of the fact they override ActiveRecord’s `delete` and `destroy` methods.
@@ -435,6 +466,13 @@ of `paranoia` because of the fact they override ActiveRecord’s `delete` and `d
 `paranoia` works similarly to `discard` in that it keeps deleted records in the same table and tags
 them with a `deleted_at` timestamp. No other information about the soft-deletion event is stored.
 
+#### [`logidze`](https://github.com/palkan/logidze)
+
+`logidze` is an interesting versioning alternative that leverages the power of PostgreSQL triggers.
+Instead of storing the previous versions or changes in a separate table, it stores them in a
+proprietary JSON format directly on the database row of the record itself. If does not support soft
+deletion.
+
 ## Contributing
 
 This gem still quite new and very open to feedback.

data/lib/generators/hoardable/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Hoardable
+  # Generates an initializer file for {Hoardable} configuration and a migration with a PostgreSQL
+  # function.
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+    include Rails::Generators::Migration
+
+    def create_initializer_file
+      create_file(
+        'config/initializers/hoardable.rb',
+        <<~TEXT
+          # Hoardable configuration defaults are below. Learn more at https://github.com/waymondo/hoardable#configuration
+          #
+          # Hoardable.enabled = true
+          # Hoardable.version_updates = true
+          # Hoardable.save_trash = true
+        TEXT
+      )
+    end
+
+    def create_migration_file
+      migration_template 'functions.rb.erb', 'db/migrate/install_hoardable.rb'
+    end
+
+    def self.next_migration_number(dir)
+      ::ActiveRecord::Generators::Base.next_migration_number(dir)
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class InstallHoardable < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    execute(
+      <<~SQL
+        CREATE OR REPLACE FUNCTION hoardable_version_prevent_update() RETURNS trigger
+          LANGUAGE plpgsql AS
+        $$BEGIN
+          RAISE EXCEPTION 'updating a version is not allowed';
+          RETURN NEW;
+        END;$$;
+      SQL
+    )
+  end
+end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+class Create<%= class_name.singularize.delete(':') %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_enum :hoardable_operation, %w[update delete insert]
     create_table :<%= singularized_table_name %>_versions, id: false, options: 'INHERITS (<%= table_name %>)' do |t|
@@ -10,20 +10,25 @@ class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%=
       t.enum :_operation, enum_type: 'hoardable_operation', null: false, index: true
       t.<%= foreign_key_type %> :hoardable_source_id, null: false, index: true
     end
-    execute(
-      <<~SQL
-        CREATE OR REPLACE FUNCTION hoardable_version_prevent_update() RETURNS trigger
-          LANGUAGE plpgsql AS
-        $$BEGIN
-          RAISE EXCEPTION 'updating a version is not allowed';
-          RETURN NEW;
-        END;$$;
-
-        CREATE TRIGGER <%= singularized_table_name %>_versions_prevent_update
-          BEFORE UPDATE ON <%= singularized_table_name %>_versions FOR EACH ROW
-          EXECUTE PROCEDURE hoardable_version_prevent_update();
-      SQL
-    )
+    reversible do |dir|
+      dir.up do
+        execute(
+          <<~SQL
+            CREATE TRIGGER <%= singularized_table_name %>_versions_prevent_update
+              BEFORE UPDATE ON <%= singularized_table_name %>_versions FOR EACH ROW
+              EXECUTE PROCEDURE hoardable_version_prevent_update();
+          SQL
+        )
+      end
+      dir.down do
+        execute(
+          <<~SQL
+            DROP TRIGGER <%= singularized_table_name %>_versions_prevent_update
+              ON <%= singularized_table_name %>_versions;
+          SQL
+        )
+      end
+    end
     add_index(:<%= singularized_table_name %>_versions, :id, unique: true)
     add_index(
       :<%= singularized_table_name %>_versions,

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+class Create<%= class_name.singularize.delete(':') %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     reversible do |dir|
       dir.up do
@@ -25,20 +25,25 @@ class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%=
       t.column :_operation, :hoardable_operation, null: false, index: true
       t.<%= foreign_key_type %> :hoardable_source_id, null: false, index: true
     end
-    execute(
-      <<~SQL
-        CREATE OR REPLACE FUNCTION hoardable_version_prevent_update() RETURNS trigger
-          LANGUAGE plpgsql AS
-        $$BEGIN
-          RAISE EXCEPTION 'updating a version is not allowed';
-          RETURN NEW;
-        END;$$;
-
-        CREATE TRIGGER <%= singularized_table_name %>_versions_prevent_update
-          BEFORE UPDATE ON <%= singularized_table_name %>_versions FOR EACH ROW
-          EXECUTE PROCEDURE hoardable_version_prevent_update();
-      SQL
-    )
+    reversible do |dir|
+      dir.up do
+        execute(
+          <<~SQL
+            CREATE TRIGGER <%= singularized_table_name %>_versions_prevent_update
+              BEFORE UPDATE ON <%= singularized_table_name %>_versions FOR EACH ROW
+              EXECUTE PROCEDURE hoardable_version_prevent_update();
+          SQL
+        )
+      end
+      dir.down do
+        execute(
+          <<~SQL
+            DROP TRIGGER <%= singularized_table_name %>_versions_prevent_update
+              ON <%= singularized_table_name %>_versions;
+          SQL
+        )
+      end
+    end
     add_index(:<%= singularized_table_name %>_versions, :id, unique: true)
     add_index(
       :<%= singularized_table_name %>_versions,

data/lib/hoardable/associations.rb

@@ -7,54 +7,12 @@ module Hoardable
   module Associations
     extend ActiveSupport::Concern
 
-    # An +ActiveRecord+ extension that allows looking up {VersionModel}s by +hoardable_source_id+ as
-    # if they were {SourceModel}s.
-    module HasManyScope
-      def scope
-        @scope ||= hoardable_scope
-      end
-
-      private
-
-      def hoardable_scope
-        if Hoardable.instance_variable_get('@at') &&
-           (hoardable_source_id = @association.owner.hoardable_source_id)
-          @association.scope.rewhere(@association.reflection.foreign_key => hoardable_source_id)
-        else
-          @association.scope
-        end
-      end
-    end
-    private_constant :HasManyScope
-
-    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.version_class
-          version_class.trashed.only_most_recent.find_by(
-            hoardable_source_id: source_reflection.foreign_key
-          )
-        end
-
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def #{name}
-            super || #{trashable_relationship_name}
-          end
-        RUBY
-      end
-
-      # A wrapper for +ActiveRecord+’s +has_many+ that allows for finding temporal versions of a
-      # record cast as instances of the {SourceModel}, when doing a {Hoardable#at} query.
-      def has_many_hoardable(name, scope = nil, **options)
-        has_many(name, scope, **options) { include HasManyScope }
-      end
+    included do
+      include HasMany
+      include HasOne
+      include BelongsTo
+      include HasRichText
+      include HasOneAttached
     end
   end
 end

data/lib/hoardable/attachment.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # A {Hoardable} subclass of {ActiveStorage::Attachment}
+  class Attachment < ActiveStorage::Attachment
+    include Model
+
+    class CreateOne < ActiveStorage::Attached::Changes::CreateOne
+      private
+
+      def build_attachment
+        Attachment.new(record: record, name: name, blob: blob)
+      end
+    end
+  end
+end

data/lib/hoardable/belongs_to.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # Provides awareness of trashed source records to +belongs_to+ relationships.
+  module BelongsTo
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def belongs_to(*args)
+        options = args.extract_options!
+        trashable = options.delete(:trashable)
+        super(*args, **options)
+        return unless trashable
+
+        hoardable_override_belongs_to(args.first)
+      end
+
+      private
+
+      def hoardable_override_belongs_to(name)
+        define_method("trashed_#{name}") do
+          source_reflection = reflections[name.to_s]
+          source_reflection.version_class.trashed.only_most_recent.find_by(
+            hoardable_source_id: source_reflection.foreign_key
+          )
+        end
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}
+            super || trashed_#{name}
+          end
+        RUBY
+      end
+    end
+  end
+  private_constant :BelongsTo
+end

data/lib/hoardable/database_client.rb

@@ -73,25 +73,9 @@ module Hoardable
     end
 
     def hoardable_source_epoch
-      if source_record.class.column_names.include?('created_at')
-        source_record.created_at
-      else
-        maybe_warn_about_missing_created_at_column
-        Time.at(0).utc
-      end
-    end
+      return source_record.created_at if source_record.class.column_names.include?('created_at')
 
-    def maybe_warn_about_missing_created_at_column
-      return unless source_record.class.hoardable_config[:warn_on_missing_created_at_column]
-
-      source_table_name = source_record.class.table_name
-      Hoardable.logger.info(
-        <<~LOG
-          '#{source_table_name}' does not have a 'created_at' column, so the first version’s temporal period
-          will begin at the unix epoch instead. Add a 'created_at' column to '#{source_table_name}'
-          or set 'Hoardable.warn_on_missing_created_at_column = false' to disable this message.
-        LOG
-      )
+      raise CreatedAtColumnMissingError, source_record.class.table_name
     end
   end
   private_constant :DatabaseClient

data/lib/hoardable/encrypted_rich_text.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # A {Hoardable} subclass of {ActionText::EncryptedRichText}.
+  class EncryptedRichText < ActionText::EncryptedRichText
+    include Model
+  end
+end

data/lib/hoardable/{hoardable.rb → engine.rb}

@@ -8,7 +8,7 @@ module Hoardable
 
   # Symbols for use with setting {Hoardable} configuration. See {file:README.md#configuration
   # README} for more.
-  CONFIG_KEYS = %i[enabled version_updates save_trash warn_on_missing_created_at_column].freeze
+  CONFIG_KEYS = %i[enabled version_updates save_trash].freeze
 
   VERSION_CLASS_SUFFIX = 'Version'
   private_constant :VERSION_CLASS_SUFFIX
@@ -34,6 +34,9 @@ module Hoardable
   end.freeze
   private_constant :HOARDABLE_VERSION_UPDATES
 
+  SUPPORTS_ENCRYPTED_ACTION_TEXT = ActiveRecord.version >= ::Gem::Version.new('7.0')
+  private_constant :SUPPORTS_ENCRYPTED_ACTION_TEXT
+
   @context = {}
   @config = CONFIG_KEYS.to_h do |key|
     [key, true]
@@ -91,4 +94,22 @@ module Hoardable
       @logger ||= ActiveSupport::TaggedLogging.new(Logger.new($stdout))
     end
   end
+
+  # A +Rails+ engine for providing support for +ActionText+
+  class Engine < ::Rails::Engine
+    isolate_namespace Hoardable
+
+    initializer 'hoardable.action_text' do
+      ActiveSupport.on_load(:action_text_rich_text) do
+        require_relative 'rich_text'
+        require_relative 'encrypted_rich_text' if SUPPORTS_ENCRYPTED_ACTION_TEXT
+      end
+    end
+
+    initializer 'hoardable.active_storage' do
+      ActiveSupport.on_load(:active_storage_attachment) do
+        require_relative 'attachment'
+      end
+    end
+  end
 end

data/lib/hoardable/error.rb

@@ -3,4 +3,16 @@
 module Hoardable
   # A subclass of +StandardError+ for general use within {Hoardable}.
   class Error < StandardError; end
+
+  # An error to be raised when 'created_at' columns are missing for {Hoardable::Model}s.
+  class CreatedAtColumnMissingError < Error
+    def initialize(source_table_name)
+      super(
+        <<~LOG
+          '#{source_table_name}' does not have a 'created_at' column, so the start of the first
+          version’s temporal period cannot be known. Add a 'created_at' column to '#{source_table_name}'.
+        LOG
+      )
+    end
+  end
 end

data/lib/hoardable/finder_methods.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # A module for overriding +ActiveRecord#find_one+ and +ActiveRecord#find_some+ in the case you are
+  # doing a temporal query and the current {SourceModel} record may in fact be a {VersionModel}
+  # record. This is extended into the current scope with {Hoardable#at} but can also be opt-ed into
+  # with the class method +hoardable+.
+  module FinderMethods
+    def find_one(id)
+      super(hoardable_source_ids([id])[0])
+    end
+
+    def find_some(ids)
+      super(hoardable_source_ids(ids))
+    end
+
+    private
+
+    def hoardable_source_ids(ids)
+      ids.map do |id|
+        version_class.where(hoardable_source_id: id).select(primary_key).ids[0] || id
+      end
+    end
+  end
+end

data/lib/hoardable/has_many.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # Provides temporal version awareness to +has_many+ relationships.
+  module HasMany
+    extend ActiveSupport::Concern
+
+    # An +ActiveRecord+ extension that allows looking up {VersionModel}s by +hoardable_source_id+ as
+    # if they were {SourceModel}s when using {Hoardable#at}.
+    module HasManyExtension
+      def scope
+        @scope ||= hoardable_scope
+      end
+
+      private
+
+      def hoardable_scope
+        if Hoardable.instance_variable_get('@at') &&
+           (hoardable_source_id = @association.owner.hoardable_source_id)
+          @association.scope.rewhere(@association.reflection.foreign_key => hoardable_source_id)
+        else
+          @association.scope
+        end
+      end
+    end
+    private_constant :HasManyExtension
+
+    class_methods do
+      def has_many(*args, &block)
+        options = args.extract_options!
+        options[:extend] = Array(options[:extend]).push(HasManyExtension) if options.delete(:hoardable)
+        super(*args, **options, &block)
+
+        # This hack is needed to force Rails to not use any existing method cache so that the
+        # {HasManyExtension} scope is always used.
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{args.first}
+            super.extending
+          end
+        RUBY
+      end
+    end
+  end
+  private_constant :HasMany
+end

data/lib/hoardable/has_one.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # Provides temporal version awareness to +has_one+ relationships.
+  module HasOne
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_one(*args)
+        options = args.extract_options!
+        hoardable = options.delete(:hoardable)
+        association = super(*args, **options)
+        name = args.first
+        return unless hoardable || association[name.to_s].options[:class_name].match?(/RichText$/)
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}
+            return super unless (at = Hoardable.instance_variable_get('@at'))
+
+            super&.version_at(at) ||
+              _reflections['profile'].klass.where(_reflections['profile'].foreign_key => id).first
+          end
+        RUBY
+      end
+    end
+  end
+  private_constant :HasOne
+end

data/lib/hoardable/has_one_attached.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # Provides temporal version awareness for +ActionText+.
+  module HasOneAttached
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_one_attached(name, **options, &block)
+        hoardable = options.delete(:hoardable)
+        super(name, **options, &block)
+        return unless hoardable
+
+        'ActiveStorage::Attachment'.constantize
+        reflection_options = reflections["#{name}_attachment"].options
+        reflection_options[:class_name] = reflection_options[:class_name].sub(/ActiveStorage/, 'Hoardable')
+
+        generated_association_methods.class_eval <<-CODE, __FILE__, __LINE__ + 1
+          # frozen_string_literal: true
+          def #{name}=(attachable)
+            attachment_changes["#{name}"] =
+              if attachable.nil?
+                ActiveStorage::Attached::Changes::DeleteOne.new("#{name}", self)
+              else
+                Hoardable::Attachment::CreateOne.new("#{name}", self, attachable)
+              end
+          end
+        CODE
+      end
+    end
+  end
+  private_constant :HasOneAttached
+end

data/lib/hoardable/has_rich_text.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # Provides temporal version awareness for +ActionText+.
+  module HasRichText
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_rich_text(name, encrypted: false, hoardable: false)
+        if SUPPORTS_ENCRYPTED_ACTION_TEXT
+          super(name, encrypted: encrypted)
+        else
+          super(name)
+        end
+        return unless hoardable
+
+        reflection_options = reflections["rich_text_#{name}"].options
+        reflection_options[:class_name] = reflection_options[:class_name].sub(/ActionText/, 'Hoardable')
+      end
+    end
+  end
+  private_constant :HasRichText
+end

data/lib/hoardable/model.rb

@@ -53,11 +53,17 @@ module Hoardable
       TracePoint.new(:end) do |trace|
         next unless self == trace.self
 
-        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 })
+        full_version_class_name = "#{name}#{VERSION_CLASS_SUFFIX}"
+        if (namespace_match = full_version_class_name.match(/(.*)::(.*)/))
+          object_namespace = namespace_match[1].constantize
+          version_class_name = namespace_match[2]
+        else
+          object_namespace = Object
+          version_class_name = full_version_class_name
+        end
+        unless Object.const_defined?(full_version_class_name)
+          object_namespace.const_set(version_class_name, Class.new(self) { include VersionModel })
         end
-
         include SourceModel
 
         trace.disable

data/lib/hoardable/rich_text.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # A {Hoardable} subclass of {ActionText::RichText}
+  class RichText < ActionText::RichText
+    include Model
+  end
+end

data/lib/hoardable/scopes.rb

@@ -60,9 +60,13 @@ module Hoardable
       # 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|
+        raise(CreatedAtColumnMissingError, @klass.table_name) unless @klass.column_names.include?('created_at')
+
         include_versions.where(id: version_class.at(datetime).select('id')).or(
-          where.not(id: version_class.select(:hoardable_source_id).where(DURING_QUERY, datetime))
-        )
+          exclude_versions
+            .where("#{table_name}.created_at < ?", datetime)
+            .where.not(id: version_class.select(:hoardable_source_id).where(DURING_QUERY, datetime))
+        ).hoardable
       }
     end
 

data/lib/hoardable/source_model.rb

@@ -16,16 +16,6 @@ module Hoardable
     #   @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
 
-    # A module for overriding +ActiveRecord#find_one+’ in the case you are doing a temporal query
-    # and the current {SourceModel} record may in fact be a {VersionModel} record.
-    module FinderMethods
-      def find_one(id)
-        conditions = { primary_key => [id, *version_class.where(hoardable_source_id: id).select(primary_key).ids] }
-        find_by(conditions) || where(conditions).raise_record_not_found_exception!
-      end
-    end
-    private_constant :FinderMethods
-
     class_methods do
       # The dynamically generated +Version+ class for this model.
       def version_class
@@ -42,6 +32,8 @@ module Hoardable
       include Scopes
 
       around_update(if: [HOARDABLE_CALLBACKS_ENABLED, HOARDABLE_VERSION_UPDATES]) do |_, block|
+        next if self.is_a?(Hoardable::Attachment)
+
         hoardable_client.insert_hoardable_version('update', &block)
       end
 
@@ -50,7 +42,7 @@ module Hoardable
       end
 
       before_destroy(if: HOARDABLE_CALLBACKS_ENABLED, unless: HOARDABLE_SAVE_TRASH) do
-        versions.delete_all(:delete_all)
+        versions.delete_all
       end
 
       after_commit { hoardable_client.unset_hoardable_version_and_event_uuid }
@@ -81,14 +73,21 @@ module Hoardable
       !!hoardable_client.hoardable_version_source_id
     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.
+    # Returns the +version+ at the supplied +datetime+ or +time+, or +self+ if there is none.
     #
     # @param datetime [DateTime, Time]
     def at(datetime)
+      version_at(datetime) || (self if created_at < datetime)
+    end
+
+    # Returns the +version+ at the supplied +datetime+ or +time+. This will raise an error if you
+    # try to find a version in the future.
+    #
+    # @param datetime [DateTime, Time]
+    def version_at(datetime)
       raise(Error, 'Future state cannot be known') if datetime.future?
 
-      versions.at(datetime).first || self
+      versions.at(datetime).limit(1).first
     end
 
     # If a version is found at the supplied datetime, it will +revert!+ to it and return it. This

data/lib/hoardable/version.rb

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

data/lib/hoardable.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require 'active_record'
 require_relative 'hoardable/version'
-require_relative 'hoardable/hoardable'
+require_relative 'hoardable/engine'
+require_relative 'hoardable/finder_methods'
 require_relative 'hoardable/scopes'
 require_relative 'hoardable/error'
 require_relative 'hoardable/database_client'
@@ -9,5 +11,10 @@ require_relative 'hoardable/source_model'
 require_relative 'hoardable/version_model'
 require_relative 'hoardable/model'
 require_relative 'hoardable/associations'
+require_relative 'hoardable/has_many'
+require_relative 'hoardable/belongs_to'
+require_relative 'hoardable/has_one'
+require_relative 'hoardable/has_rich_text'
+require_relative 'hoardable/has_one_attached'
 require_relative 'generators/hoardable/migration_generator'
-require_relative 'generators/hoardable/initializer_generator'
+require_relative 'generators/hoardable/install_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, :warn_on_missing_created_at_column]
+  CONFIG_KEYS: [:enabled, :version_updates, :save_trash]
   VERSION_CLASS_SUFFIX: String
   VERSION_TABLE_SUFFIX: String
   DURING_QUERY: String
@@ -17,8 +17,17 @@ module Hoardable
   def self.at: (untyped datetime) -> untyped
   def self.logger: -> untyped
 
+  module FinderMethods
+    def find_one: (untyped id) -> untyped
+    def find_some: (untyped ids) -> untyped
+
+    private
+    def hoardable_source_ids: ([untyped] ids) -> Array[untyped]
+  end
+
   module Scopes
     TABLEOID_AREL_CONDITIONS: Proc
+    self.@klass: bot
 
     private
     def tableoid: -> untyped
@@ -30,6 +39,10 @@ module Hoardable
   class Error < StandardError
   end
 
+  class CreatedAtColumnMissingError < Error
+    def initialize: (untyped source_table_name) -> void
+  end
+
   class DatabaseClient
     @hoardable_version_source_id: untyped
 
@@ -45,8 +58,7 @@ module Hoardable
     def assign_hoardable_context: (:event_uuid | :meta | :note | :whodunit key) -> nil
     def unset_hoardable_version_and_event_uuid: -> nil
     def previous_temporal_tsrange_end: -> untyped
-    def hoardable_source_epoch: -> Time
-    def maybe_warn_about_missing_created_at_column: -> nil
+    def hoardable_source_epoch: -> untyped
   end
 
   module SourceModel
@@ -56,7 +68,8 @@ module Hoardable
     attr_reader hoardable_version: untyped
     def trashed?: -> untyped
     def version?: -> untyped
-    def at: (untyped datetime) -> SourceModel
+    def at: (untyped datetime) -> SourceModel?
+    def version_at: (untyped datetime) -> untyped
     def revert_to!: (untyped datetime) -> SourceModel?
     def hoardable_source_id: -> untyped
 
@@ -66,10 +79,6 @@ module Hoardable
     public
     def version_class: -> untyped
     def hoardable: -> untyped
-
-    module FinderMethods
-      def find_one: (untyped id) -> untyped
-    end
   end
 
   module VersionModel
@@ -99,10 +108,16 @@ module Hoardable
   end
 
   module Associations
-    def belongs_to_trashable: (untyped name, ?nil scope, **untyped) -> untyped
-    def has_many_hoardable: (untyped name, ?nil scope, **untyped) -> untyped
+    @hoardable_association_overrider: Overrider
+
+    def belongs_to: (*untyped args) -> nil
+    def has_one: (*untyped args) -> nil
+    def has_many: (*untyped args) -> untyped
+
+    private
+    def hoardable_association_overrider: -> Overrider
 
-    module HasManyScope
+    module HasManyExtension
       @scope: untyped
       @association: bot
 
@@ -111,6 +126,14 @@ module Hoardable
       private
       def hoardable_scope: -> untyped
     end
+
+    class Overrider
+      attr_reader klass: Associations
+      def initialize: (Associations klass) -> void
+      def override_belongs_to: (untyped name) -> untyped
+      def override_has_one: (untyped name) -> untyped
+      def override_has_many: (untyped name) -> untyped
+    end
   end
 
   class MigrationGenerator
@@ -122,7 +145,9 @@ module Hoardable
     def singularized_table_name: -> untyped
   end
 
-  class InitializerGenerator
+  class InstallGenerator
     def create_initializer_file: -> untyped
+    def create_migration_file: -> untyped
+    def self.next_migration_number: (untyped dir) -> untyped
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hoardable
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.0
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-03 00:00:00.000000000 Z
+date: 2022-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -104,16 +104,26 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- lib/generators/hoardable/initializer_generator.rb
+- lib/generators/hoardable/install_generator.rb
 - lib/generators/hoardable/migration_generator.rb
+- lib/generators/hoardable/templates/functions.rb.erb
 - lib/generators/hoardable/templates/migration.rb.erb
 - lib/generators/hoardable/templates/migration_6.rb.erb
 - lib/hoardable.rb
 - lib/hoardable/associations.rb
+- lib/hoardable/attachment.rb
+- lib/hoardable/belongs_to.rb
 - lib/hoardable/database_client.rb
+- lib/hoardable/encrypted_rich_text.rb
+- lib/hoardable/engine.rb
 - lib/hoardable/error.rb
-- lib/hoardable/hoardable.rb
+- lib/hoardable/finder_methods.rb
+- lib/hoardable/has_many.rb
+- lib/hoardable/has_one.rb
+- lib/hoardable/has_one_attached.rb
+- lib/hoardable/has_rich_text.rb
 - lib/hoardable/model.rb
+- lib/hoardable/rich_text.rb
 - lib/hoardable/scopes.rb
 - lib/hoardable/source_model.rb
 - lib/hoardable/version.rb

data/lib/generators/hoardable/initializer_generator.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-require 'rails/generators'
-
-module Hoardable
-  # Generates an initializer file for {Hoardable} configuration.
-  class InitializerGenerator < Rails::Generators::Base
-    def create_initializer_file
-      create_file(
-        'config/initializers/hoardable.rb',
-        <<~TEXT
-          # Hoardable configuration defaults are below. Learn more at https://github.com/waymondo/hoardable#configuration
-          #
-          # Hoardable.enabled = true
-          # Hoardable.version_updates = true
-          # Hoardable.save_trash = true
-        TEXT
-      )
-    end
-  end
-end