hoardable 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c960d95a373942d9183464cc50b7c4213c25c7563fa9d920c81d2c325ea71705
-  data.tar.gz: e7e0f289e60acd720538edc15584209ed3d30e08b21758d06884a5486f198ee0
+  metadata.gz: 50086ef99aac41454b28ab8bff2e8abf94d7870b371da0c706c477e0b296ffc3
+  data.tar.gz: 6e6d4ab40470bbfb93e23e96fdbb2d8b086878d24e55d499ac368523125e5397
 SHA512:
-  metadata.gz: a83966223151922d24bb009ac50465723388ba91825e27cf933bb5e00370c270a0518ec828358f1109a040e2a9202cee7b37d7ea98e0387b30dc07a74f7eb851
-  data.tar.gz: 6bc246f6664b61c5000ffa71b24c8ddd30c409eda87e790b0ea1bd9d47f46c4e85e0b5eb89736939a75018e272cdd5ac2ce1217c7c7e9272ddc4f96cc8cc33f4
+  metadata.gz: 747ac52845c950eb655cb7b0af22794dda49ed08e2b0f1aee472595fd2c63b1f886d4f516e686807607efe4946ca588792913ea92ec1c3152a44c23f8cd84487
+  data.tar.gz: 3460ccd66ebe6eed7cdb129bca6150696b82ad9f8613965e80b08fb458ac6e2b8b644e662036533f73f95f52b97a10bf50f2782f76d3fd6671f23f9c2b58df08

data/README.md

@@ -69,7 +69,7 @@ Rails 7.
 ### Overview
 
 Once you include `Hoardable::Model` into a model, it will dynamically generate a "Version" subclass
-of that model. As we continue our example above, :
+of that model. As we continue our example above:
 
 ```
 $ irb
@@ -146,7 +146,10 @@ choosing.
 One convenient way to assign contextual data to these is by defining a proc in an initializer, i.e.:
 
 ```ruby
+# config/initiailzers/hoardable.rb
 Hoardable.whodunit = -> { Current.user&.id }
+
+# somewhere in your app code
 Current.user = User.find(123)
 post.update!(status: 'live')
 post.versions.last.hoardable_whodunit # => 123
@@ -230,6 +233,7 @@ There are three configurable options currently:
 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.
@@ -239,6 +243,10 @@ Hoardable.save_trash # => default true
 `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
@@ -247,17 +255,26 @@ Hoardable.with(enabled: false) do
 end
 ```
 
-You can also configure these variables per `ActiveRecord` class as well using `hoardable_options`:
+You can also configure these variables per `ActiveRecord` class as well using `hoardable_config`:
 
 ```ruby
 class Comment < ActiveRecord::Base
   include Hoardable::Model
-  hoardable_options version_updates: false
+  hoardable_config version_updates: false
 end
 ```
 
-If either the model-level option or global option for a configuration variable is set to `false`,
-that behavior will be disabled.
+If you want to temporarily set the `hoardable_config` for a specific model, you can use
+`with_hoardable_config`:
+
+```ruby
+Comment.with_hoardable_config(version_updates: true) do
+  comment.update!(text: "Edited")
+end
+```
+
+If a model-level option exists, it will use that. Otherwise, it will fall back to the global
+`Hoardable` config.
 
 ### Relationships
 
@@ -267,17 +284,20 @@ features in this area, but here are a couple pointers.
 Sometimes you’ll have a record that belongs to a record that you’ll trash. Now the child record’s
 foreign key will point to the non-existent trashed version of the parent. If you would like this
 `belongs_to` relationship to always resolve to the parent as if it was not trashed, you can include
-the scope on the relationship definition:
+the `include_versions` scope on the relationship definition:
 
 ```ruby
-belongs_to :parent, -> { include_versions }
+class Comment
+  include Hoardable::Model
+  belongs_to :post, -> { include_versions } # `Post` also includes `Hoardable::Model`
+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
 database transaction, it will create or re-use a unique event UUID for that transaction and tag all
-versions created with it. That way, when you `untrash!` a parent object, you can find and `untrash!`
-the children like so:
+versions created with it. That way, when you `untrash!` a record, you can find and `untrash!`
+records that were trashed with it:
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -295,20 +315,35 @@ class Post < ActiveRecord::Base
 end
 ```
 
+If there are models that might be related to versions that are trashed or otherwise, and/or might
+trashed themselves, you can bypass the inherited tables query handling altogether by using the
+`return_everything` configuration variable in `Hoardable.with`:
+
+```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) 
+### [`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
-  single `versions` table. It stores changes in a `text`, `json`, or `jsonb` column. In order to
-  efficiently query the `versions` table, a `jsonb` column should be used, which takes up a lot of
-  space to index. Unless you customize your configuration, all `versions` for all models types are
-  in the same table which is inefficient if you are only interested in querying versions of a single
-  model. By contrast, `hoardable` stores versions in smaller, isolated and inherited tables with the
-  same database columns as their parents, which are more efficient for querying as well as auditing
-  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.
+database types than PostgeSQL and (by default) stores all versions of all versioned models in a
+single `versions` table. It stores changes in a `text`, `json`, or `jsonb` column. In order to
+efficiently query the `versions` table, a `jsonb` column should be used, which takes up a lot of
+space to index. Unless you customize your configuration, all `versions` for all models types are
+in the same table which is inefficient if you are only interested in querying versions of a single
+model. By contrast, `hoardable` stores versions in smaller, isolated and inherited tables with the
+same database columns as their parents, which are more efficient for querying as well as auditing
+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)
 

data/lib/hoardable/hoardable.rb

@@ -7,7 +7,7 @@ module Hoardable
   DATA_KEYS = %i[meta whodunit note event_uuid].freeze
   # Symbols for use with setting {Hoardable} configuration. See {file:README.md#configuration
   # README} for more.
-  CONFIG_KEYS = %i[enabled version_updates save_trash].freeze
+  CONFIG_KEYS = %i[enabled version_updates save_trash return_everything].freeze
 
   # @!visibility private
   VERSION_CLASS_SUFFIX = 'Version'
@@ -20,7 +20,7 @@ module Hoardable
 
   @context = {}
   @config = CONFIG_KEYS.to_h do |key|
-    [key, true]
+    [key, key != :return_everything]
   end
 
   class << self
@@ -46,7 +46,7 @@ module Hoardable
 
     # This is a general use method for setting {DATA_KEYS} or {CONFIG_KEYS} around a scoped block.
     #
-    # @param hash [Hash] Options and contextual data to set within a block
+    # @param hash [Hash] config and contextual data to set within a block
     def with(hash)
       current_config = @config
       current_context = @context

data/lib/hoardable/model.rb

@@ -10,7 +10,7 @@ module Hoardable
 
     class_methods do
       # @!visibility private
-      attr_reader :_hoardable_options
+      attr_reader :_hoardable_config
 
       # If called with a hash, this will set the model-level +Hoardable+ configuration variables. If
       # called without an argument it will return the computed +Hoardable+ configuration considering
@@ -19,16 +19,29 @@ module Hoardable
       # @param hash [Hash] The +Hoardable+ configuration for the model. Keys must be present in
       #   {CONFIG_KEYS}
       # @return [Hash]
-      def hoardable_options(hash = nil)
+      def hoardable_config(hash = nil)
         if hash
-          @_hoardable_options = hash.slice(*Hoardable::CONFIG_KEYS)
+          @_hoardable_config = hash.slice(*Hoardable::CONFIG_KEYS)
         else
-          @_hoardable_options ||= {}
+          @_hoardable_config ||= {}
           Hoardable::CONFIG_KEYS.to_h do |key|
-            [key, Hoardable.send(key) != false && @_hoardable_options[key] != false]
+            [key, @_hoardable_config.key?(key) ? @_hoardable_config[key] : Hoardable.send(key)]
           end
         end
       end
+
+      # Set the model-level +Hoardable+ configuration variables around a block. The configuration
+      # will be reset to it’s previous value afterwards.
+      #
+      # @param hash [Hash] The +Hoardable+ configuration for the model. Keys must be present in
+      #   {CONFIG_KEYS}
+      def with_hoardable_config(hash)
+        current_config = @_hoardable_config
+        @_hoardable_config = hash.slice(*Hoardable::CONFIG_KEYS)
+        yield
+      ensure
+        @_hoardable_config = current_config
+      end
     end
 
     included do

data/lib/hoardable/source_model.rb

@@ -45,7 +45,7 @@ module Hoardable
     #
     # @return [Boolean]
     def trashed?
-      versions.trashed.limit(1).order(_during: :desc).first&.send(:hoardable_source_attributes) == attributes
+      versions.trashed.limit(1).order(_during: :desc).first&.id == id
     end
 
     # Returns the +version+ at the supplied +datetime+ or +time+. It will return +self+ if there is
@@ -71,15 +71,15 @@ module Hoardable
     private
 
     def hoardable_callbacks_enabled
-      self.class.hoardable_options[:enabled] && !self.class.name.end_with?(VERSION_CLASS_SUFFIX)
+      self.class.hoardable_config[:enabled] && !self.class.name.end_with?(VERSION_CLASS_SUFFIX)
     end
 
     def hoardable_save_trash
-      self.class.hoardable_options[:save_trash]
+      self.class.hoardable_config[:save_trash]
     end
 
     def hoardable_version_updates
-      self.class.hoardable_options[:version_updates]
+      self.class.hoardable_config[:version_updates]
     end
 
     def insert_hoardable_version_on_update(&block)

data/lib/hoardable/tableoid.rb

@@ -17,9 +17,16 @@ module Hoardable
       # @!visibility private
       attr_writer :tableoid
 
-      # By default, {Hoardable} only returns instances of the parent table, and not the +versions+
-      # in the inherited table.
-      default_scope { where(TABLEOID_AREL_CONDITIONS.call(arel_table, :eq)) }
+      # 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.
+      default_scope do
+        if hoardable_config[:return_everything]
+          where(nil)
+        else
+          where(TABLEOID_AREL_CONDITIONS.call(arel_table, :eq))
+        end
+      end
 
       # @!scope class
       # @!method include_versions

data/lib/hoardable/version.rb

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

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]
+  CONFIG_KEYS: [:enabled, :version_updates, :save_trash, :return_everything]
   VERSION_CLASS_SUFFIX: String
   VERSION_TABLE_SUFFIX: String
   DURING_QUERY: String
@@ -71,8 +71,8 @@ module Hoardable
     include VersionModel
     include SourceModel
 
-    attr_reader _hoardable_options: Hash[untyped, untyped]
-    def hoardable_options: (?nil hash) -> untyped
+    def hoardable_config: (?nil hash) -> untyped
+    def with_hoardable_config: (untyped hash) -> untyped
   end
 
   class MigrationGenerator

metadata

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