hoardable 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5e5c29b0b6d4a24e7b41a9b4846fd1288caabd48158b517a4b9b61e53421d1c
-  data.tar.gz: 1e863147db8e3a39e4ed3d465855d465f14c4c8a444426abce72534e8bae4d9c
+  metadata.gz: c960d95a373942d9183464cc50b7c4213c25c7563fa9d920c81d2c325ea71705
+  data.tar.gz: e7e0f289e60acd720538edc15584209ed3d30e08b21758d06884a5486f198ee0
 SHA512:
-  metadata.gz: 4c997b34958fbe6253098778c03bf9226eac02b7fd218af1a1d1bd52527b7b1a0b0406a6ecf0cc8e3ea45d70e5b8823dc23a0e48fcc741c470831b98adb3fd65
-  data.tar.gz: 44b9c1cfe68aa6ab18370b90632d5563dda8ef50b0cde425be3b44eb7f2027fa6e61d609538653cc15adab20f9d79ba3423f614d95c9413f8db4c0ced3a2f4be
+  metadata.gz: a83966223151922d24bb009ac50465723388ba91825e27cf933bb5e00370c270a0518ec828358f1109a040e2a9202cee7b37d7ea98e0387b30dc07a74f7eb851
+  data.tar.gz: 6bc246f6664b61c5000ffa71b24c8ddd30c409eda87e790b0ea1bd9d47f46c4e85e0b5eb89736939a75018e272cdd5ac2ce1217c7c7e9272ddc4f96cc8cc33f4

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
 
@@ -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:
@@ -293,9 +295,49 @@ class Post < ActiveRecord::Base
 end
 ```
 
+## 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/version.rb

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

metadata

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