hoardable 0.9.1 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b85dfaf658e447049fcb09281d34dd25188be79f948eda294398f47b19b8244
-  data.tar.gz: 67219612736259e2dbc542230cc1490a156a15bc679340176aca35b76aaf516c
+  metadata.gz: dad9a103d70ce10905528d1d7e56e67a4a8fb89e675b3097165ccede6262a015
+  data.tar.gz: a2dc95873a08175254cca315caa3de9b087674df1e4dadd17f42fb26a9080a9d
 SHA512:
-  metadata.gz: cf3c5edfeac5526e7520dc2584caba8bb5399df43acf1ce6bd320b19f44981c154624b9b80c5b415aaeb840fc5d718f1999b4bbaf82eb3ff76149e09621ab0e5
-  data.tar.gz: 52112fb9bc55bec2009656cce9571887130333b6460d5478c1a0c113895ccb977ffcc80172954911c6e70d2012f136bf68c64b17bc69ffd7deeaa40a56c97646
+  metadata.gz: 02b542ba1fe562750eb16bf6f310b08e2340610e01e7db68eaedb9185e4da4a1d7e7a5a42885fb09376759bf936b8b527de4bedec8399b71119541162e57604f
+  data.tar.gz: 77edd48d420fea18333996280d6e31e0daba198b96e67fdc49b4fc7fe1884cb86cc88416e1f486691e2292465818fb50e3c4fc4367d83cc6d751d0adcb39acf6

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/README.md

@@ -164,12 +164,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 +317,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 +351,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,9 +369,7 @@ 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
 to untrash everything in a similar dependent manner. Whenever a hoardable version is created in a

data/lib/hoardable/associations.rb

@@ -8,8 +8,8 @@ module Hoardable
     extend ActiveSupport::Concern
 
     # An +ActiveRecord+ extension that allows looking up {VersionModel}s by +hoardable_source_id+ as
-    # if they were {SourceModel}s.
-    module HasManyScope
+    # if they were {SourceModel}s when using {Hoardable#at}.
+    module HasManyExtension
       def scope
         @scope ||= hoardable_scope
       end
@@ -25,35 +25,85 @@ module Hoardable
         end
       end
     end
-    private_constant :HasManyScope
+    private_constant :HasManyExtension
 
-    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)
+    # A private service class for installing +ActiveRecord+ association overrides.
+    class Overrider
+      attr_reader :klass
 
-        trashable_relationship_name = "trashable_#{name}"
+      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
 
-      # 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 }
+      def hoardable_association_overrider
+        @hoardable_association_overrider ||= Overrider.new(self)
       end
     end
   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/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 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

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
@@ -50,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 }
@@ -81,14 +71,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.10.1'
 end

data/lib/hoardable.rb

@@ -2,6 +2,7 @@
 
 require_relative 'hoardable/version'
 require_relative 'hoardable/hoardable'
+require_relative 'hoardable/finder_methods'
 require_relative 'hoardable/scopes'
 require_relative 'hoardable/error'
 require_relative 'hoardable/database_client'

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
@@ -46,7 +46,6 @@ 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hoardable
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.1
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-03 00:00:00.000000000 Z
+date: 2022-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -112,6 +112,7 @@ 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