hoardable 0.8.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cd77fbd3d35df59423ba95f7286703ae0d3b0f78bd9097b3574c713c38aa4c7
-  data.tar.gz: d5971e9daf59a9fa5343c13e389b20fc5b6ff193b398d05c958f34dfd056d0cb
+  metadata.gz: dad9a103d70ce10905528d1d7e56e67a4a8fb89e675b3097165ccede6262a015
+  data.tar.gz: a2dc95873a08175254cca315caa3de9b087674df1e4dadd17f42fb26a9080a9d
 SHA512:
-  metadata.gz: 5de03adf485f38e3ee3a24999bf770d92792404894529a5317f9788d15b784c0bcd9aa28b3d2966340a1244296cdc7b4ebe6fdccd6791172b44ca498c4bf5fca
-  data.tar.gz: a39bd22b66c727ec791e704ec3b24592c068dd2eb29ae0fa7d70a440073bd6d635fd7f24f12d3ba34bf05976b311bab9ec6a5a6fdf9f9069311347d89ae8f8c0
+  metadata.gz: 02b542ba1fe562750eb16bf6f310b08e2340610e01e7db68eaedb9185e4da4a1d7e7a5a42885fb09376759bf936b8b527de4bedec8399b71119541162e57604f
+  data.tar.gz: 77edd48d420fea18333996280d6e31e0daba198b96e67fdc49b4fc7fe1884cb86cc88416e1f486691e2292465818fb50e3c4fc4367d83cc6d751d0adcb39acf6

data/.rubocop.yml

@@ -16,3 +16,6 @@ Metrics/BlockLength:
 
 Style/DocumentDynamicEvalDefinition:
   Enabled: false
+
+Naming/PredicateName:
+  Enabled: false

data/CHANGELOG.md

@@ -2,52 +2,3 @@
 
 - Stability is coming.
 
-## [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/README.md

@@ -31,6 +31,12 @@ gem 'hoardable'
 
 And then execute `bundle install`.
 
+If you would like to generate an initializer with the global [configuration](#configuration) options:
+
+```
+rails g hoardable:initializer
+```
+
 ### Model Installation
 
 You must include `Hoardable::Model` into an ActiveRecord model that you would like to hoard versions
@@ -64,6 +70,9 @@ _Note:_ If you are on Rails 6.1, you might want to set `config.active_record.sch
 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.
+
 ## Usage
 
 ### Overview
@@ -99,7 +108,7 @@ Each `PostVersion` has access to the same attributes, relationships, and other m
 
 If you ever need to revert to a specific version, you can call `version.revert!` on it.
 
-``` ruby
+```ruby
 post = Post.create!(title: "Title")
 post.update!(title: "Whoops")
 post.reload.versions.last.revert!
@@ -107,7 +116,7 @@ post.title # => "Title"
 ```
 
 If you would like to untrash a specific version, you can call `version.untrash!` on it. This will
-re-insert the model in the parent class’s table with it’s original primary key.
+re-insert the model in the parent class’s table with the original primary key.
 
 ```ruby
 post = Post.create!(title: "Title")
@@ -139,16 +148,15 @@ PostVersion.at(1.day.ago).find_by(hoardable_source_id: post.id) # => #<PostVersi
 
 The source model class also has an `.at` method:
 
-``` ruby
+```ruby
 Post.at(1.day.ago) # => [#<Post>, #<Post>]
 ```
 
-This will return an ActiveRecord scoped query of all `Posts` and `PostVersions` that were valid at
-that time, all cast as instances of `Post`.
+This will return an ActiveRecord scoped query of all `Post` and `PostVersion` records that were
+valid at that time, all cast as instances of `Post`.
 
-_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.
+There is also an `at` method on `Hoardable` itself for more complex temporal resource querying. See
+[Relationships](#relationships) for more.
 
 By default, `hoardable` will keep copies of records you have destroyed. You can query them
 specifically with:
@@ -158,8 +166,9 @@ PostVersion.trashed
 Post.version_class.trashed # <- same thing as above
 ```
 
-_Note:_ Creating an inherited table does not copy over the indexes from the parent table. If you
-need to query versions often, you should add appropriate indexes to the `_versions` tables.
+_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. If this is missing, an error will be raised.
 
 ### Tracking Contextual Data
 
@@ -263,7 +272,6 @@ The configurable options are:
 Hoardable.enabled # => default true
 Hoardable.version_updates # => default true
 Hoardable.save_trash # => default true
-Hoardable.return_everything # => default false
 ```
 
 `Hoardable.enabled` controls whether versions will be ever be created.
@@ -273,10 +281,6 @@ Hoardable.return_everything # => default false
 `Hoardable.save_trash` controls whether to create versions upon record deletion. When this is set to
 `false`, all versions of a record will be deleted when the record is destroyed.
 
-`Hoardable.return_everything` controls whether to include versions when doing queries for source
-models. This is typically only useful to set around a block, as explained below in
-[Relationships](#relationships).
-
 If you would like to temporarily set a config setting, you can use `Hoardable.with`:
 
 ```ruby
@@ -313,18 +317,62 @@ 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 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
+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 adding `hoardable: true` to the `has_many` relationship and using the
+`Hoardable.at` method:
+
+```ruby
+class Post
+  include Hoardable::Model
+  has_many :comments, hoardable: true
+end
+
+def Comment
+  include Hoardable::Model
+end
+
+post = Post.create!(title: 'Title')
+comment1 = post.comments.create!(body: 'Comment')
+comment2 = post.comments.create!(body: 'Comment')
+datetime = DateTime.current
+comment2.destroy!
+post.update!(title: 'New Title')
+post_id = post.id # 1
+
+Hoardable.at(datetime) do
+  post = Post.find(post_id)
+  post.title # => 'Title'
+  post.comments.size # => 2
+  post.id # => 2
+  post.version? # => true
+  post.hoardable_source_id # => 1
+end
+```
+
+There are some additional details to point out above. Firstly, it is important to note that the
+final `post.id` yields a different value than the originally created `Post`. This is because the
+`post` within the `#at` block is actually a temporal version, since it has been subsequently
+updated, but it has been reified as a `Post` for the purposes of your business logic (serialization,
+rendering views, exporting, etc). Don’t fret - you will not be able to commit any updates to the
+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`. 
+
+Sometimes you’ll trash something that `has_many_hoardable :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!`
 records that were trashed with it:
@@ -332,7 +380,7 @@ records that were trashed with it:
 ```ruby
 class Post < ActiveRecord::Base
   include Hoardable::Model
-  has_many :comments, dependent: :destroy # `Comment` also includes `Hoardable::Model`
+  has_many_hoardable :comments, dependent: :destroy # `Comment` also includes `Hoardable::Model`
 
   after_untrashed do
     Comment
@@ -344,22 +392,6 @@ class Post < ActiveRecord::Base
 end
 ```
 
-If there are models that might be related to versions that are trashed or otherwise, and/or might be
-trashed themselves, you can bypass the inherited tables query handling altogether by using the
-`return_everything` configuration variable in `Hoardable.with`. This will ensure that you always see
-all records, including update and trashed versions.
-
-```ruby
-post.destroy!
-
-Hoardable.with(return_everything: true) do
-  post = Post.find(post.id) # returns the trashed post as if it was not
-  post.comments # returns the trashed comments as well
-end
-
-post.reload # raises ActiveRecord::RecordNotFound
-```
-
 ## Gem Comparison
 
 ### [`paper_trail`](https://github.com/paper-trail-gem/paper_trail)

data/lib/generators/hoardable/initializer_generator.rb

@@ -0,0 +1,21 @@
+# 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

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

@@ -10,6 +10,20 @@ 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
+    )
     add_index(:<%= singularized_table_name %>_versions, :id, unique: true)
     add_index(
       :<%= singularized_table_name %>_versions,

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

@@ -25,6 +25,20 @@ 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
+    )
     add_index(:<%= singularized_table_name %>_versions, :id, unique: true)
     add_index(
       :<%= singularized_table_name %>_versions,

data/lib/hoardable/associations.rb

@@ -7,28 +7,104 @@ module Hoardable
   module Associations
     extend ActiveSupport::Concern
 
-    class_methods do
-      # A wrapper for +ActiveRecord+’s +belongs_to+ that allows for falling back to the most recent
-      # trashed +version+, in the case that the related source has been trashed.
-      def belongs_to_trashable(name, scope = nil, **options)
-        belongs_to(name, scope, **options)
+    # 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
 
-        trashable_relationship_name = "trashable_#{name}"
+      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
+
+    # A private service class for installing +ActiveRecord+ association overrides.
+    class Overrider
+      attr_reader :klass
+
+      def initialize(klass)
+        @klass = klass
+      end
 
-        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(
+      def override_belongs_to(name)
+        klass.define_method("trashable_#{name}") do
+          source_reflection = klass.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
+        klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}
+            super || trashable_#{name}
+          end
+        RUBY
+      end
+
+      def override_has_one(name)
+        klass.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
+
+      def override_has_many(name)
+        # This hack is needed to force Rails to not use any existing method cache so that the
+        # {HasManyExtension} scope is always used.
+        klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def #{name}
-            super || #{trashable_relationship_name}
+            super.extending
           end
         RUBY
       end
     end
+    private_constant :Overrider
+
+    class_methods do
+      def belongs_to(*args)
+        options = args.extract_options!
+        trashable = options.delete(:trashable)
+        super(*args, **options)
+        return unless trashable
+
+        hoardable_association_overrider.override_belongs_to(args.first)
+      end
+
+      def has_one(*args)
+        options = args.extract_options!
+        hoardable = options.delete(:hoardable)
+        super(*args, **options)
+        return unless hoardable
+
+        hoardable_association_overrider.override_has_one(args.first)
+      end
+
+      def has_many(*args, &block)
+        options = args.extract_options!
+        options[:extend] = Array(options[:extend]).push(HasManyExtension) if options.delete(:hoardable)
+        super(*args, **options, &block)
+
+        hoardable_association_overrider.override_has_many(args.first)
+      end
+
+      private
+
+      def hoardable_association_overrider
+        @hoardable_association_overrider ||= Overrider.new(self)
+      end
+    end
   end
 end

data/lib/hoardable/database_client.rb

@@ -23,6 +23,15 @@ module Hoardable
       Thread.current[:hoardable_event_uuid] ||= ActiveRecord::Base.connection.query('SELECT gen_random_uuid();')[0][0]
     end
 
+    def hoardable_version_source_id
+      @hoardable_version_source_id ||= query_hoardable_version_source_id
+    end
+
+    def query_hoardable_version_source_id
+      primary_key = source_record.class.primary_key
+      version_class.where(primary_key => source_record.read_attribute(primary_key)).pluck('hoardable_source_id')[0]
+    end
+
     def initialize_version_attributes(operation)
       source_record.attributes_before_type_cast.without('id').merge(
         source_record.changes.transform_values { |h| h[0] },
@@ -64,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/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/hoardable.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 return_everything 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
@@ -36,7 +36,7 @@ module Hoardable
 
   @context = {}
   @config = CONFIG_KEYS.to_h do |key|
-    [key, key != :return_everything]
+    [key, true]
   end
 
   class << self
@@ -75,6 +75,17 @@ module Hoardable
       @context = current_context
     end
 
+    # Allows performing a query for record states at a certain time. Returned {SourceModel}
+    # instances within the block may be {SourceModel} or {VersionModel} records.
+    #
+    # @param datetime [DateTime, Time] the datetime or time to temporally query records at
+    def at(datetime)
+      @at = datetime
+      yield
+    ensure
+      @at = nil
+    end
+
     # @!visibility private
     def logger
       @logger ||= ActiveSupport::TaggedLogging.new(Logger.new($stdout))

data/lib/hoardable/{tableoid.rb → scopes.rb}

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Hoardable
-  # This concern provides support for PostgreSQL’s tableoid system column to {SourceModel}.
-  module Tableoid
+  # This concern provides support for PostgreSQL’s tableoid system column to {SourceModel} and
+  # temporal +ActiveRecord+ scopes.
+  module Scopes
     extend ActiveSupport::Concern
 
     TABLEOID_AREL_CONDITIONS = lambda do |arel_table, condition|
@@ -19,10 +20,10 @@ module Hoardable
 
       # By default {Hoardable} only returns instances of the parent table, and not the +versions+ in
       # the inherited table. This can be bypassed by using the {.include_versions} scope or wrapping
-      # the code in a `Hoardable.with(return_everything: true)` block.
+      # the code in a `Hoardable.at(datetime)` block.
       default_scope do
-        if hoardable_config[:return_everything]
-          where(nil)
+        if (hoardable_at = Hoardable.instance_variable_get('@at'))
+          at(hoardable_at)
         else
           exclude_versions
         end
@@ -51,6 +52,22 @@ module Hoardable
       # Excludes +versions+ of the parent +ActiveRecord+ class. This is included by default in the
       # source model’s +default_scope+.
       scope :exclude_versions, -> { where(TABLEOID_AREL_CONDITIONS.call(arel_table, :eq)) }
+
+      # @!scope class
+      # @!method at
+      # @return [ActiveRecord<Object>]
+      #
+      # Returns instances of the source model and versions that were valid at the supplied
+      # +datetime+ or +time+, all cast as instances of the source model.
+      scope :at, lambda { |datetime|
+        raise(CreatedAtColumnMissingError, @klass.table_name) unless @klass.column_names.include?('created_at')
+
+        include_versions.where(id: version_class.at(datetime).select('id')).or(
+          exclude_versions
+            .where("#{table_name}.created_at < ?", datetime)
+            .where.not(id: version_class.select(:hoardable_source_id).where(DURING_QUERY, datetime))
+        ).hoardable
+      }
     end
 
     private

data/lib/hoardable/source_model.rb

@@ -21,10 +21,15 @@ module Hoardable
       def version_class
         "#{name}#{VERSION_CLASS_SUFFIX}".constantize
       end
+
+      # Extends the current {SourceModel} scoping to include Hoardable’s {FinderMethods} overrides.
+      def hoardable
+        extending(FinderMethods)
+      end
     end
 
     included do
-      include Tableoid
+      include Scopes
 
       around_update(if: [HOARDABLE_CALLBACKS_ENABLED, HOARDABLE_VERSION_UPDATES]) do |_, block|
         hoardable_client.insert_hoardable_version('update', &block)
@@ -35,7 +40,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 }
@@ -48,35 +53,39 @@ module Hoardable
         inverse_of: :hoardable_source,
         foreign_key: :hoardable_source_id
       )
-
-      # @!scope class
-      # @!method at
-      # @return [ActiveRecord<Object>]
-      #
-      # Returns instances of the source model and versions that were valid at the supplied
-      # +datetime+ or +time+, all cast as instances of the source model.
-      scope :at, lambda { |datetime|
-        include_versions.where(id: version_class.at(datetime).select('id')).or(
-          where.not(id: version_class.select(:hoardable_source_id).where(DURING_QUERY, datetime))
-        )
-      }
     end
 
-    # Returns a boolean of whether the record is actually a trashed +version+.
+    # Returns a boolean of whether the record is actually a trashed +version+ cast as an instance of the
+    # source model.
     #
     # @return [Boolean]
     def trashed?
-      versions.trashed.only_most_recent.first&.hoardable_source_foreign_id == id
+      versions.trashed.only_most_recent.first&.hoardable_source_id == id
+    end
+
+    # Returns a boolean of whether the record is actually a +version+ cast as an instance of the
+    # source model.
+    #
+    # @return [Boolean]
+    def version?
+      !!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
@@ -89,6 +98,15 @@ module Hoardable
       version.is_a?(version_class) ? version.revert! : self
     end
 
+    # Returns the +hoardable_source_id+ that represents the original {SourceModel} record’s ID. Will
+    # return nil if the current {SourceModel} record is not an instance of a {VersionModel} cast as
+    # {SourceModel}.
+    #
+    # @return [Integer, nil]
+    def hoardable_source_id
+      hoardable_client.hoardable_version_source_id || id
+    end
+
     delegate :version_class, to: :class
 
     private

data/lib/hoardable/version.rb

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

data/lib/hoardable/version_model.rb

@@ -113,17 +113,17 @@ module Hoardable
       _data&.dig('changes')
     end
 
-    # Returns the foreign reference that represents the source model of the version.
-    def hoardable_source_foreign_id
-      @hoardable_source_foreign_id ||= public_send(:hoardable_source_id)
+    # Returns the ID of the {SourceModel} that created this {VersionModel}
+    def hoardable_source_id
+      read_attribute('hoardable_source_id')
     end
 
     private
 
     def insert_untrashed_source
       superscope = self.class.superclass.unscoped
-      superscope.insert(hoardable_source_attributes.merge('id' => hoardable_source_foreign_id))
-      superscope.find(hoardable_source_foreign_id)
+      superscope.insert(hoardable_source_attributes.merge('id' => hoardable_source_id))
+      superscope.find(hoardable_source_id)
     end
 
     def hoardable_source_attributes

data/lib/hoardable.rb

@@ -2,7 +2,8 @@
 
 require_relative 'hoardable/version'
 require_relative 'hoardable/hoardable'
-require_relative 'hoardable/tableoid'
+require_relative 'hoardable/finder_methods'
+require_relative 'hoardable/scopes'
 require_relative 'hoardable/error'
 require_relative 'hoardable/database_client'
 require_relative 'hoardable/source_model'
@@ -10,3 +11,4 @@ require_relative 'hoardable/version_model'
 require_relative 'hoardable/model'
 require_relative 'hoardable/associations'
 require_relative 'generators/hoardable/migration_generator'
+require_relative 'generators/hoardable/initializer_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, :return_everything, :warn_on_missing_created_at_column]
+  CONFIG_KEYS: [:enabled, :version_updates, :save_trash]
   VERSION_CLASS_SUFFIX: String
   VERSION_TABLE_SUFFIX: String
   DURING_QUERY: String
@@ -10,12 +10,14 @@ module Hoardable
   HOARDABLE_VERSION_UPDATES: ^(untyped) -> untyped
   self.@context: Hash[untyped, untyped]
   self.@config: untyped
+  self.@at: nil
   self.@logger: untyped
 
   def self.with: (untyped hash) -> untyped
+  def self.at: (untyped datetime) -> untyped
   def self.logger: -> untyped
 
-  module Tableoid
+  module Scopes
     TABLEOID_AREL_CONDITIONS: Proc
 
     private
@@ -29,10 +31,14 @@ module Hoardable
   end
 
   class DatabaseClient
-    attr_reader source_model: SourceModel
-    def initialize: (SourceModel source_model) -> void
+    @hoardable_version_source_id: untyped
+
+    attr_reader source_record: SourceModel
+    def initialize: (SourceModel source_record) -> void
     def insert_hoardable_version: (untyped operation) -> untyped
     def find_or_initialize_hoardable_event_uuid: -> untyped
+    def hoardable_version_source_id: -> untyped
+    def query_hoardable_version_source_id: -> untyped
     def initialize_version_attributes: (untyped operation) -> untyped
     def initialize_temporal_range: -> Range
     def initialize_hoardable_data: -> untyped
@@ -40,33 +46,38 @@ module Hoardable
     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
   end
 
   module SourceModel
-    include Tableoid
+    include Scopes
     @hoardable_client: DatabaseClient
 
     attr_reader hoardable_version: untyped
     def trashed?: -> untyped
+    def version?: -> untyped
     def at: (untyped datetime) -> SourceModel
     def revert_to!: (untyped datetime) -> SourceModel?
+    def hoardable_source_id: -> untyped
 
     private
     def hoardable_client: -> DatabaseClient
 
     public
     def version_class: -> untyped
+    def hoardable: -> untyped
+
+    module FinderMethods
+      def find_one: (untyped id) -> untyped
+    end
   end
 
   module VersionModel
-    @hoardable_source_foreign_id: untyped
     @hoardable_source_attributes: untyped
 
     def revert!: -> untyped
     def untrash!: -> untyped
     def changes: -> untyped
-    def hoardable_source_foreign_id: -> untyped
+    def hoardable_source_id: -> untyped
 
     private
     def insert_untrashed_source: -> untyped
@@ -88,6 +99,17 @@ module Hoardable
 
   module Associations
     def belongs_to_trashable: (untyped name, ?nil scope, **untyped) -> untyped
+    def has_many_hoardable: (untyped name, ?nil scope, **untyped) -> untyped
+
+    module HasManyScope
+      @scope: untyped
+      @association: bot
+
+      def scope: -> untyped
+
+      private
+      def hoardable_scope: -> untyped
+    end
   end
 
   class MigrationGenerator
@@ -98,4 +120,8 @@ module Hoardable
     def migration_template_name: -> String
     def singularized_table_name: -> untyped
   end
+
+  class InitializerGenerator
+    def create_initializer_file: -> untyped
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hoardable
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.1
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-01 00:00:00.000000000 Z
+date: 2022-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -104,6 +104,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/generators/hoardable/initializer_generator.rb
 - lib/generators/hoardable/migration_generator.rb
 - lib/generators/hoardable/templates/migration.rb.erb
 - lib/generators/hoardable/templates/migration_6.rb.erb
@@ -111,10 +112,11 @@ files:
 - lib/hoardable/associations.rb
 - lib/hoardable/database_client.rb
 - lib/hoardable/error.rb
+- lib/hoardable/finder_methods.rb
 - lib/hoardable/hoardable.rb
 - lib/hoardable/model.rb
+- lib/hoardable/scopes.rb
 - lib/hoardable/source_model.rb
-- lib/hoardable/tableoid.rb
 - lib/hoardable/version.rb
 - lib/hoardable/version_model.rb
 - sig/hoardable.rbs