hoardable 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96952d8928266fc5ae03199a91e85428565ff11385a74851fe61fd3a8eafc881
-  data.tar.gz: 1b9117cbf4ea08325d29212c16580e368a857b12f8c2d20bc346d9e8f5268d59
+  metadata.gz: 50086ef99aac41454b28ab8bff2e8abf94d7870b371da0c706c477e0b296ffc3
+  data.tar.gz: 6e6d4ab40470bbfb93e23e96fdbb2d8b086878d24e55d499ac368523125e5397
 SHA512:
-  metadata.gz: e533edf9412339fcc90691fa5d10395265914f71f7f7493c9afc226902cf831db87f69661d565630602e2db815549e4209550420abc44f6a7d179ccb23ba7509
-  data.tar.gz: a8c690b0a3399f3853ed6c65ca7d514af9c82d10569483d7d4bed86c6e7a63d1881ecac61e13d6646facdce3370614dc6c86f88599bc6eb955feba38589c398c
+  metadata.gz: 747ac52845c950eb655cb7b0af22794dda49ed08e2b0f1aee472595fd2c63b1f886d4f516e686807607efe4946ca588792913ea92ec1c3152a44c23f8cd84487
+  data.tar.gz: 3460ccd66ebe6eed7cdb129bca6150696b82ad9f8613965e80b08fb458ac6e2b8b644e662036533f73f95f52b97a10bf50f2782f76d3fd6671f23f9c2b58df08

data/README.md

@@ -3,10 +3,6 @@
 Hoardable is an ActiveRecord extension for Ruby 2.6+, Rails 6.1+, and PostgreSQL that allows for
 versioning and soft-deletion of records through the use of _uni-temporal inherited tables_.
 
-[👉 Documentation](https://www.rubydoc.info/gems/hoardable)
-
-### huh?
-
 [Temporal tables](https://en.wikipedia.org/wiki/Temporal_database) are a database design pattern
 where each row of a table contains data along with one or more time ranges. In the case of this gem,
 each database row has a time range that represents the row’s valid time range - hence
@@ -20,8 +16,10 @@ change is reflected on its descendants.
 With these concepts combined, `hoardable` offers a simple and effective model versioning system for
 Rails. Versions of records are stored in separate, inherited tables along with their valid time
 ranges and contextual data. Compared to other Rails-oriented versioning systems, this gem strives to
-be more explicit and obvious on the lower RDBS level while still familiar and convenient within Ruby
-on Rails.
+be more explicit and obvious on the lower RDBS level while still familiar and convenient to use
+within Ruby on Rails.
+
+[👉 Documentation](https://www.rubydoc.info/gems/hoardable)
 
 ## Installation
 
@@ -71,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
@@ -119,6 +117,10 @@ post.at(1.day.ago) # => #<PostVersion:0x000000010d44fa30>
 PostVersion.at(1.day.ago).find_by(post_id: post.id) # => #<PostVersion:0x000000010d44fa30>
 ```
 
+_Note:_ A `Version` is not created upon initial parent model creation. If you would like to
+accurately capture the valid temporal frame of the first version, make sure your model’s table has a
+`created_at` timestamp field.
+
 By default, `hoardable` will keep copies of records you have destroyed. You can query for them as
 well:
 
@@ -129,7 +131,7 @@ PostVersion.trashed
 _Note:_ Creating an inherited table does not copy over the indexes from the parent table. If you
 need to query versions often, you should add appropriate indexes to the `_versions` tables.
 
-### Tracking contextual data
+### Tracking Contextual Data
 
 You’ll often want to track contextual data about the creation of a version. There are 3 optional
 symbol keys that are provided for tracking contextual information:
@@ -144,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
@@ -222,19 +227,27 @@ end
 
 ### Configuration
 
-There are two configurable options currently:
+There are three configurable options currently:
 
 ```ruby
 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 created at all.
+`Hoardable.enabled` controls whether versions will be ever be created.
+
+`Hoardable.version_updates` controls whether versions get created on record updates.
 
 `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.
 
-If you would like to temporarily set a config setting, you can use `Hoardable.with` as well:
+`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
 Hoardable.with(enabled: false) do
@@ -242,6 +255,27 @@ Hoardable.with(enabled: false) do
 end
 ```
 
+You can also configure these variables per `ActiveRecord` class as well using `hoardable_config`:
+
+```ruby
+class Comment < ActiveRecord::Base
+  include Hoardable::Model
+  hoardable_config version_updates: false
+end
+```
+
+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
 
 As in life, sometimes relationships can be hard. `hoardable` is still working out best practices and
@@ -250,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
@@ -278,9 +315,64 @@ 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` 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.
+
+### [`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
+want to query them, and there is no concept of a `temporal` time-frame for a single version. It
+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` 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
+the event that caused the soft deletion unless you implement it yourself. Once the "discarded"
+record is restored, the previous "discarded" awareness is lost. Since "discarded" records exist in
+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` 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.
+`hoardable` employs callbacks to create trashed versions instead of overriding methods. Otherwise,
+`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.
+
 ## Contributing
 
-This gem is currently considered alpha and very open to feedback.
+This gem still quite new and very open to feedback.
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/waymondo/hoardable.
 

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 save_trash].freeze
+  CONFIG_KEYS = %i[enabled version_updates save_trash return_everything].freeze
 
   # @!visibility private
   VERSION_CLASS_SUFFIX = 'Version'
@@ -15,15 +15,12 @@ module Hoardable
   # @!visibility private
   VERSION_TABLE_SUFFIX = "_#{VERSION_CLASS_SUFFIX.tableize}"
 
-  # @!visibility private
-  SAVE_TRASH_ENABLED = -> { Hoardable.save_trash }.freeze
-
   # @!visibility private
   DURING_QUERY = '_during @> ?::timestamp'
 
   @context = {}
   @config = CONFIG_KEYS.to_h do |key|
-    [key, true]
+    [key, key != :return_everything]
   end
 
   class << self
@@ -49,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

@@ -8,6 +8,42 @@ module Hoardable
   module Model
     extend ActiveSupport::Concern
 
+    class_methods do
+      # @!visibility private
+      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
+      # both model-level and global values.
+      #
+      # @param hash [Hash] The +Hoardable+ configuration for the model. Keys must be present in
+      #   {CONFIG_KEYS}
+      # @return [Hash]
+      def hoardable_config(hash = nil)
+        if hash
+          @_hoardable_config = hash.slice(*Hoardable::CONFIG_KEYS)
+        else
+          @_hoardable_config ||= {}
+          Hoardable::CONFIG_KEYS.to_h do |key|
+            [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
       define_model_callbacks :versioned
       define_model_callbacks :reverted, only: :after

data/lib/hoardable/source_model.rb

@@ -17,9 +17,9 @@ module Hoardable
     included do
       include Tableoid
 
-      around_update :insert_hoardable_version_on_update, if: :hoardable_callbacks_enabled
-      around_destroy :insert_hoardable_version_on_destroy, if: [:hoardable_callbacks_enabled, SAVE_TRASH_ENABLED]
-      before_destroy :delete_hoardable_versions, if: :hoardable_callbacks_enabled, unless: SAVE_TRASH_ENABLED
+      around_update :insert_hoardable_version_on_update, if: %i[hoardable_callbacks_enabled hoardable_version_updates]
+      around_destroy :insert_hoardable_version_on_destroy, if: %i[hoardable_callbacks_enabled hoardable_save_trash]
+      before_destroy :delete_hoardable_versions, if: :hoardable_callbacks_enabled, unless: :hoardable_save_trash
       after_commit :unset_hoardable_version_and_event_uuid
 
       # This will contain the +Version+ class instance for use within +versioned+, +reverted+, and
@@ -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,7 +71,15 @@ module Hoardable
     private
 
     def hoardable_callbacks_enabled
-      Hoardable.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_config[:save_trash]
+    end
+
+    def hoardable_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.1.3'
+  VERSION = '0.3.0'
 end

data/sig/hoardable.rbs

@@ -1,4 +1,86 @@
 module Hoardable
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  DATA_KEYS: [:meta, :whodunit, :note, :event_uuid]
+  CONFIG_KEYS: [:enabled, :version_updates, :save_trash, :return_everything]
+  VERSION_CLASS_SUFFIX: String
+  VERSION_TABLE_SUFFIX: String
+  DURING_QUERY: String
+  self.@context: Hash[untyped, untyped]
+  self.@config: untyped
+
+  def self.with: (untyped hash) -> untyped
+
+  module Tableoid
+    TABLEOID_AREL_CONDITIONS: Proc
+
+    private
+    def tableoid: -> untyped
+
+    public
+    attr_writer tableoid: untyped
+  end
+
+  class Error < StandardError
+  end
+
+  module SourceModel
+    include Tableoid
+
+    def trashed?: -> untyped
+    def at: (untyped datetime) -> SourceModel
+    def revert_to!: (untyped datetime) -> SourceModel?
+
+    private
+    def hoardable_callbacks_enabled: -> untyped
+    def hoardable_save_trash: -> untyped
+    def hoardable_version_updates: -> untyped
+    def insert_hoardable_version_on_update: -> untyped
+    def insert_hoardable_version_on_destroy: -> untyped
+    def insert_hoardable_version: (String operation, untyped attrs) -> untyped
+    def find_or_initialize_hoardable_event_uuid: -> untyped
+    def initialize_hoardable_version: (String operation, untyped attrs) -> untyped
+    def initialize_hoardable_data: -> untyped
+    def assign_hoardable_context: (:event_uuid | :meta | :note | :whodunit key) -> nil
+    def delete_hoardable_versions: -> untyped
+    def unset_hoardable_version_and_event_uuid: -> nil
+
+    public
+    def version_class: -> untyped
+    attr_reader hoardable_version: nil
+  end
+
+  module VersionModel
+    @hoardable_source_attributes: untyped
+    @hoardable_source_foreign_key: String
+    @hoardable_source_foreign_id: untyped
+
+    def revert!: -> untyped
+    def untrash!: -> untyped
+    def changes: -> untyped
+
+    private
+    def untrashable_hoardable_source_attributes: -> untyped
+    def hoardable_source_attributes: -> untyped
+    def hoardable_source_foreign_key: -> String
+    def hoardable_source_foreign_id: -> untyped
+    def previous_temporal_tsrange_end: -> untyped
+    def assign_temporal_tsrange: -> Range
+  end
+
+  module Model
+    include VersionModel
+    include SourceModel
+
+    def hoardable_config: (?nil hash) -> untyped
+    def with_hoardable_config: (untyped hash) -> untyped
+  end
+
+  class MigrationGenerator
+    @singularized_table_name: untyped
+
+    def create_versions_table: -> untyped
+    def foreign_key_type: -> String
+    def migration_template_name: -> String
+    def singularized_table_name: -> untyped
+  end
 end

metadata

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