hoardable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 24eee9ce1b76bd2d5a40a6b527ef4e048c25850ea454f75b2838f45b21339c25
+  data.tar.gz: e464f7418ec2527ed6fe598b4575481a01d50fea236631749d0722bdd328c66f
+SHA512:
+  metadata.gz: a617926045371fa040ae329241fe37a5ea58ea4fdcd43c2c66f0c3fe2b89cc0b5c2723371c88c9946b4bda4cf20d477a936494a32f6e8e39b9a1b5e727c7e9b4
+  data.tar.gz: 283ee7c613a1d07b227e32dc823914ea2cdc9b144a9b9d03c0155adf21cdeeacecd92ba8d173d2c0c4bf17febbd1343571898db7c5e24ea828e0f261ae82cbb7

data/.rubocop.yml

@@ -0,0 +1,10 @@
+AllCops:
+  TargetRubyVersion: 2.6
+  NewCops: enable
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/ClassLength:
+  Exclude:
+    - 'test/**/*.rb'

data/.tool-versions

@@ -0,0 +1,2 @@
+ruby 3.1.2
+postgres 14.4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-07-23
+
+- Initial release

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'debug', '~> 1.6'
+gem 'minitest', '~> 5.0'
+gem 'rake', '~> 13.0'
+gem 'rubocop', '~> 1.21'
+gem 'rubocop-minitest', '~> 0.20'
+gem 'rubocop-rake', '~> 0.6'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 justin talbott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,205 @@
+# Hoardable
+
+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**.
+
+### Huh?
+
+[Temporal tables](https://en.wikipedia.org/wiki/Temporal_database) are a database design pattern
+where each row contains data as well as one or more time ranges. In the case of a temporal table
+representing versions, each row has one time range representing the row’s valid time range, hence
+"uni-temporal".
+
+[Table inheritance](https://www.postgresql.org/docs/14/ddl-inherit.html) is a feature of PostgreSQL
+that allows a table to inherit all columns of another table. The descendant table’s schema will stay
+in sync with all columns that it inherits from it’s parent. If a new column or removed from the
+parent, the schema change is reflected on its descendants.
+
+With these principles combined, `hoardable` offers a simple and effective model versioning system,
+where versions of records are stored in a separate, inherited table with the validity time range and
+other versioning data.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hoardable'
+```
+
+And then execute `bundle install`.
+
+### Model Installation
+
+First, include `Hoardable::Model` into a model you would like to hoard versions of:
+
+```ruby
+class Post < ActiveRecord::Base
+  include Hoardable::Model
+  belongs_to :user
+end
+```
+
+Then, run the generator command to create a database migration and migrate it:
+
+```
+bin/rails g hoardable:migration posts
+bin/rails db:migrate
+```
+
+## Usage
+
+### Basics
+
+Once you include `Hoardable::Model` into a model, it will dynamically generate a "Version" subclass
+of that model. Continuing our example above:
+
+```
+>> Post
+=> Post(id: integer, body: text, user_id: integer, created_at: datetime)
+>> PostVersion
+=> PostVersion(id: integer, body: text, user_id: integer, created_at: datetime, _data: jsonb, _during: tsrange, post_id: integer)
+```
+
+A `Post` now `has_many :versions` which are created on every update and deletion of a `Post` (by
+default):
+
+```ruby
+post_id = post.id
+post.versions.size # => 0
+post.update!(title: "Title")
+post.versions.size # => 1
+post.destroy!
+post.reload # => ActiveRecord::RecordNotFound
+PostVersion.where(post_id: post_id).size # => 2
+```
+
+Each `PostVersion` has access to the same attributes, relationships, and other model behavior that
+`Post` has, but is a read-only record.
+
+If you ever need to revert to a specific version, you can call `version.revert!` on it. If the
+source post had been deleted, this will untrash it with it’s original primary key.
+
+### Querying and Temporal Lookup
+
+Since a `PostVersion` is just a normal `ActiveRecord`, you can query them like another model
+resource, i.e:
+
+```ruby
+post.versions.where(user_id: Current.user.id, body: nil)
+```
+
+If you want to look-up the version of a `Post` at a specific time, you can use the `.at` method:
+
+```ruby
+post.at(1.day.ago) # => #<PostVersion:0x000000010d44fa30>
+```
+
+By default, `hoardable` will keep copies of records you have destroyed. You can query for them as
+well:
+
+```ruby
+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 will need to add those indexes to the `_versions` tables manually.
+
+### Tracking contextual data
+
+You’ll often want to track contextual data about a version. `hoardable` will automatically capture
+the ActiveRecord `changes` hash and `operation` that cause the version (`update` or `delete`).
+
+There are also 3 other optional keys that are provided for tracking contextual information:
+
+- `whodunit` - an identifier for who is responsible for creating the version
+- `note` - a string containing a description regarding the versioning
+- `meta` - any other contextual information you’d like to store along with the version
+
+This information is stored in a `jsonb` column. Each key’s value can be in the format of your
+choosing.
+
+One convenient way to assign this contextual data is with a proc in an initializer, i.e.:
+
+```ruby
+Hoardable.whodunit = -> { Current.user&.id }
+```
+
+You can also set this context manually as well, just remember to clear them afterwards.
+
+```ruby
+Hoardable.note = "reverting due to accidental deletion"
+post.update!(title: "We’re back!")
+Hoardable.note = nil
+post.versions.last.hoardable_note # => "reverting due to accidental deletion"
+```
+
+Another useful pattern is to use `Hoardable.with` to set the context around a block. A good example
+of this would be in `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  around_action :use_hoardable_context
+
+  private
+
+  def use_hoardable_context
+    Hoardable.with(whodunit: current_user.id, meta: { request_uuid: request.uuid }) do
+      yield
+    end
+  end
+end
+```
+
+### Model Callbacks
+
+Sometimes you might want to do something with a version before it gets saved. You can access it in a
+`before_save` callback as `hoardable_version`. There is also an `after_reverted` callback available
+as well.
+
+``` ruby
+class User
+  before_save :sanitize_version
+  after_reverted :track_reverted_event
+
+  private
+
+  def sanitize_version
+    hoardable_version.sanitize_password
+  end 
+
+  def track_reverted_event
+    track_event(:user_reverted, self)
+  end
+end
+```
+
+### Configuration
+
+There are two available options:
+
+``` ruby
+Hoardable.enabled # => default true
+Hoardable.save_trash # => default true
+```
+
+`Hoardable.enabled` controls whether versions will be created at all.
+
+`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:
+
+```ruby
+Hoardable.with(enabled: false) do
+  post.update!(title: 'unimportant change to create version for')
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/waymondo/hoardable.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/generators/hoardable/migration_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record/migration/migration_generator'
+
+module Hoardable
+  # Generates a migration for an inherited temporal table of a model including {Hoardable::Model}
+  class MigrationGenerator < ActiveRecord::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+    include Rails::Generators::Migration
+
+    def create_versions_table
+      migration_template 'migration.rb.erb', "db/migrate/create_#{singularized_table_name}_versions.rb"
+    end
+
+    no_tasks do
+      def singularized_table_name
+        @singularized_table_name ||= table_name.singularize
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class Create<%= class_name.singularize %>Versions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= singularized_table_name %>_versions, id: false, options: 'INHERITS (<%= table_name %>)' do |t|
+      t.jsonb :_data
+      t.tsrange :_during, null: false
+      t.bigint :<%= singularized_table_name %>_id, null: false, index: true
+    end
+    add_index :<%= singularized_table_name %>_versions, %i[_during <%= singularized_table_name %>_id]
+  end
+end

data/lib/hoardable/hoardable.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# An ActiveRecord extension for keeping versions of records in temporal inherited tables
+module Hoardable
+  VERSION = '0.1.0'
+  DATA_KEYS = %i[changes meta whodunit note operation].freeze
+  CONFIG_KEYS = %i[enabled save_trash].freeze
+
+  @context = {}
+  @config = CONFIG_KEYS.to_h do |key|
+    [key, true]
+  end
+
+  class << self
+    CONFIG_KEYS.each do |key|
+      define_method(key) do
+        @config[key]
+      end
+
+      define_method("#{key}=") do |value|
+        @config[key] = value
+      end
+    end
+
+    DATA_KEYS.each do |key|
+      define_method(key) do
+        @context[key]
+      end
+
+      define_method("#{key}=") do |value|
+        @context[key] = value
+      end
+    end
+
+    def with(hash)
+      current_config = @config
+      current_context = @context
+      @config = current_config.merge(hash.slice(*CONFIG_KEYS))
+      @context = current_context.merge(hash.slice(*DATA_KEYS))
+      yield
+    ensure
+      @config = current_config
+      @context = current_context
+    end
+  end
+end

data/lib/hoardable/model.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # This concern includes the Hoardable API methods on ActiveRecord instances and dynamically
+  # generates the Version variant of the class
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      default_scope { where("#{table_name}.tableoid = '#{table_name}'::regclass") }
+
+      before_update :initialize_hoardable_version, if: -> { Hoardable.enabled }
+      before_destroy :initialize_hoardable_version, if: -> { Hoardable.enabled && Hoardable.save_trash }
+      after_update :save_hoardable_version, if: -> { Hoardable.enabled }
+      before_destroy :delete_hoardable_versions, if: -> { Hoardable.enabled && !Hoardable.save_trash }
+      after_destroy :save_hoardable_version, if: -> { Hoardable.enabled && Hoardable.save_trash }
+
+      attr_reader :hoardable_version
+
+      define_model_callbacks :reverted, only: :after
+
+      TracePoint.new(:end) do |trace|
+        next unless self == trace.self
+
+        version_class_name = "#{name}Version"
+        next if Object.const_defined?(version_class_name)
+
+        Object.const_set(version_class_name, Class.new(self) { include VersionModel })
+        has_many(
+          :versions, -> { order(:_during) },
+          dependent: nil,
+          class_name: version_class_name,
+          inverse_of: model_name.i18n_key
+        )
+        trace.disable
+      end.enable
+    end
+
+    def at(datetime)
+      versions.find_by('_during @> ?::timestamp', datetime) || self
+    end
+
+    private
+
+    def initialize_hoardable_version
+      Hoardable.with(changes: changes) do
+        @hoardable_version = versions.new(
+          attributes_before_type_cast
+            .without('id')
+            .merge(changes.transform_values { |h| h[0] })
+            .merge(_data: initialize_hoardable_data)
+        )
+      end
+    end
+
+    def initialize_hoardable_data
+      DATA_KEYS.to_h do |key|
+        [key, assign_hoardable_context(key)]
+      end
+    end
+
+    def assign_hoardable_context(key)
+      return nil if (value = Hoardable.public_send(key)).nil?
+
+      value.is_a?(Proc) ? value.call : value
+    end
+
+    def save_hoardable_version
+      hoardable_version._data['operation'] = persisted? ? 'update' : 'delete'
+      hoardable_version.save!(validate: false, touch: false)
+      @hoardable_version = nil
+    end
+
+    def delete_hoardable_versions
+      versions.delete_all(:delete_all)
+    end
+  end
+end

data/lib/hoardable/version_model.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Hoardable
+  # This concern is included into the dynamically generated Version models.
+  module VersionModel
+    extend ActiveSupport::Concern
+
+    included do
+      hoardable_source_key = superclass.model_name.i18n_key
+      belongs_to hoardable_source_key, inverse_of: :versions
+      alias_method :hoardable_source, hoardable_source_key
+
+      self.table_name = "#{table_name.singularize}_versions"
+
+      alias_method :readonly?, :persisted?
+
+      before_create :assign_temporal_tsrange
+
+      scope :trashed, lambda {
+        left_outer_joins(hoardable_source_key)
+          .where(superclass.table_name => { id: nil })
+          .where("_data ->> 'operation' = 'delete'")
+      }
+    end
+
+    def revert!
+      transaction do
+        (
+          hoardable_source&.tap { |tapped| tapped.update!(hoardable_source_attributes.without('id')) } ||
+          untrash
+        ).tap do |tapped|
+          tapped.run_callbacks(:reverted)
+        end
+      end
+    end
+
+    DATA_KEYS.each do |key|
+      define_method("hoardable_#{key}") do
+        _data&.dig(key.to_s)
+      end
+    end
+
+    alias changes hoardable_changes
+
+    private
+
+    def untrash
+      foreign_id = public_send(hoardable_source_foreign_key)
+      self.class.superclass.insert(hoardable_source_attributes.merge('id' => foreign_id, 'updated_at' => Time.now))
+      self.class.superclass.find(foreign_id)
+    end
+
+    def hoardable_source_attributes
+      @hoardable_source_attributes ||=
+        attributes_before_type_cast
+        .without(hoardable_source_foreign_key)
+        .reject { |k, _v| k.start_with?('_') }
+    end
+
+    def hoardable_source_foreign_key
+      @hoardable_source_foreign_key ||= "#{self.class.superclass.model_name.i18n_key}_id"
+    end
+
+    def previous_temporal_tsrange_end
+      hoardable_source.versions.limit(1).order(_during: :desc).pluck('_during').first&.end
+    end
+
+    def assign_temporal_tsrange
+      self._during = ((previous_temporal_tsrange_end || hoardable_source.created_at)..Time.now)
+    end
+  end
+end

data/lib/hoardable.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'hoardable/hoardable'
+require_relative 'hoardable/version_model'
+require_relative 'hoardable/model'
+require_relative 'generators/hoardable/migration_generator'

data/sig/hoardable.rbs

@@ -0,0 +1,4 @@
+module Hoardable
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: hoardable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- justin talbott
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+description: Rails model versioning with the power of uni-temporal inherited tables
+email:
+- justin@waymondo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".tool-versions"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/hoardable/migration_generator.rb
+- lib/generators/hoardable/templates/migration.rb.erb
+- lib/hoardable.rb
+- lib/hoardable/hoardable.rb
+- lib/hoardable/model.rb
+- lib/hoardable/version_model.rb
+- sig/hoardable.rbs
+homepage: https://github.com/waymondo/hoardable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/waymondo/hoardable
+  source_code_uri: https://github.com/waymondo/hoardable
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: An ActiveRecord extension for versioning and soft-deletion of records in
+  Postgres
+test_files: []