activerecord-exclusive-arc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5dbceaa69bcb956d89d1c636209771640242741ae2e06f57a038f474f64825d8
+  data.tar.gz: a8319a8c41ea99543fc8d52387adb35aa6a56b264adfdfa39a25b8b6d603f774
+SHA512:
+  metadata.gz: c0c2ab91655256c9226c3775d2e6ee1c05d733089110728ade4aa39416e23f15a7a048f6e2189fc23aa9aac93783180ac8eabca57f404808957a044375c9ee8d
+  data.tar.gz: ca725edf128c121af9e4a5e8880b8a8895ce8eefabf0ae9175d7c0054a1c7f38475f8b8e47ede79cd31db64fc63a697e97c28525c63062a21b148e042eaefadf

data/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+gem "debug"
+gem "minitest"
+gem "rails", "~> #{ENV.fetch("RAILS_VERSION", "7.0")}"
+gem "rake"
+gem "pg"
+gem "sqlite3"
+gem "standard", "~> 1.26"
+
+gemspec

data/README.md

@@ -0,0 +1,138 @@
+### What does it do?
+
+It allows an ActiveRecord model to exclusively belong to one of any number of different types of ActiveRecord
+models.
+
+### Doesn’t Rails already provide this?
+
+It does, but there are decent arguments against the default Rails way of doing polymorphism. Consider the
+fact that the Ruby class name is stored in the database as a string. If you want to change the name of the
+Ruby class used for such reasons, you must also update the database strings that represent it. The bleeding
+of application-layer definitions into the database may become a liability.
+
+Another common argument concerns referential integrity. *Foreign Key Constraints* are a common mechanism to
+ensure primary keys of tables can be reliably used as foreign keys on others. This becomes harder to enforce
+when a column that represents a Ruby class is one of the components required for unique identification.
+
+There are also quality of life considerations, such as not being able to eager-load the `belongs_to ...
+polymorphic: true` relationship and the fact that polymorphic indexes require multiple columns.
+
+### So how does this work?
+
+It reduces the boilerplate of managing a *Polymorphic Assication* modeled as a pattern called an *Exclusive
+Arc*. This maps nicely to a database constraint, a set of optional `belongs_to` relationships, some
+polymorphic methods, and an `ActiveRecord` validation for good measure.
+
+## How to use
+
+Firstly, in your `Gemfile`:
+
+```ruby
+gem "activerecord-exclusive-arc"
+```
+
+The feature set of this gem is offered via a Rails generator command:
+
+```
+bin/rails g exclusive_arc <Model> <arc> <belongs_to1> <belongs_to2> ...
+```
+
+This assumes you already have a `<Model>`. The `<arc>` is the name of the polymorphic association you want to
+establish that may either be a `<belongs_to1>`, `<belongs_to2>`, etc. Say we ran:
+
+```
+bin/rails g exclusive_arc Comment commentable post comment
+```
+
+This will inject code into your `Comment` Model:
+
+```ruby
+class Comment < ApplicationRecord
+  include ExclusiveArc::Model
+  exclusive_arc :commentable, [:post, :comment]
+end
+```
+
+At a high-level, this essentially transpiles to the following:
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post, optional: true
+  belongs_to :comment, optional: true
+  validate :post_or_comment_present?
+
+  def commentable
+    @commentable ||= (post || comment)
+  end
+
+  def commentable=(post_or_comment)
+    @commentable = post_or_comment
+  end
+end
+```
+
+It's a bit more involved than that, but it demonstrates the essense of the API as an `ActiveRecord` user.
+
+Continuing with our example, the generator command would also produce a migration that looks like this:
+
+```ruby
+class CommentCommentableExclusiveArc < ActiveRecord::Migration[7.0]
+  def change
+    add_reference :comments, :post, foreign_key: true, index: {where: "post_id IS NOT NULL"}
+    add_reference :comments, :comment, foreign_key: true, index: {where: "comment_id IS NOT NULL"}
+    add_check_constraint(
+      :comments,
+      "(CASE WHEN post_id IS NULL THEN 0 ELSE 1 END + CASE WHEN comment_id IS NULL THEN 0 ELSE 1 END) = 1",
+      name: :commentable
+    )
+  end
+end
+```
+
+The check constraint ensures `ActiveRecord` validations can’t be bypassed to break the fabeled rule - "There
+Can Only Be One™️". Traditional foreign key constraints can be used and the partial indexes provide improved
+lookup performance for each individual polymorphic assoication.
+
+### Exclusive Arc Options
+
+Some options are available to the generator command. You can see them with:
+
+```
+$ bin/rails g exclusive_arc --help
+Usage:
+  rails generate exclusive_arc NAME [arc belongs_to1 belongs_to2 ...] [options]
+
+Options:
+  [--skip-namespace], [--no-skip-namespace]                              # Skip namespace (affects only isolated engines)
+  [--skip-collision-check], [--no-skip-collision-check]                  # Skip collision check
+  [--optional], [--no-optional]                                          # Exclusive arc is optional
+  [--skip-foreign-key-constraints], [--no-skip-foreign-key-constraints]  # Skip foreign key constraints
+  [--skip-foreign-key-indexes], [--no-skip-foreign-key-indexes]          # Skip foreign key partial indexes
+  [--skip-check-constraint], [--no-skip-check-constraint]                # Skip check constraint
+
+Runtime options:
+  -f, [--force]                    # Overwrite files that already exist
+  -p, [--pretend], [--no-pretend]  # Run but do not make any changes
+  -q, [--quiet], [--no-quiet]      # Suppress status output
+  -s, [--skip], [--no-skip]        # Skip files that already exist
+
+Adds an Exclusive Arc to an ActiveRecord model and generates the migration for it
+```
+
+Notably, if you want to make an Exclusive Arc optional, you can use the `--optional` flag. This will adjust
+the definition in your `ActiveRecord` model and loosen both the validation and database check constraint so
+that there can be 0 or 1 foreign keys set for the polymorphic association.
+
+### Compatibility
+
+Currently `activerecord-exclusive-arc` is tested against a matrix of Ruby 2.7 and 3.2, Rails 6.1 and 7.0, and
+`postgresql` and `sqlite3` database adapters.
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/waymondo/activerecord-exclusive-arc.
+
+### 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,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: %i[standard test]

data/lib/activerecord-exclusive-arc.rb

@@ -0,0 +1 @@
+require "exclusive_arc"

data/lib/exclusive_arc/definition.rb

@@ -0,0 +1,10 @@
+module ExclusiveArc
+  class Definition
+    attr_reader :reflections, :options
+
+    def initialize(reflections:, options:)
+      @reflections = reflections
+      @options = options
+    end
+  end
+end

data/lib/exclusive_arc/model.rb

@@ -0,0 +1,52 @@
+module ExclusiveArc
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :exclusive_arcs, default: {}
+      delegate :exclusive_arcs, to: :class
+    end
+
+    class_methods do
+      def exclusive_arc(*args)
+        arcs = args[0].is_a?(Hash) ? args[0] : {args[0] => args[1]}
+        options = args[2] || {}
+        arcs.each do |(name, belong_tos)|
+          belong_tos.map { |option| belongs_to(option, optional: true) }
+          exclusive_arcs[name] = Definition.new(
+            reflections: reflections.slice(*belong_tos.map(&:to_s)),
+            options: options
+          )
+
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}
+              #{belong_tos.join(" || ")}
+            end
+
+            def #{name}=(polymorphic)
+              assign_exclusive_arc(:#{name}, polymorphic)
+            end
+          RUBY
+        end
+
+        validate :validate_exclusive_arcs
+      end
+    end
+
+    private
+
+    def assign_exclusive_arc(arc, polymorphic)
+      exclusive_arcs.fetch(arc).reflections.each do |name, reflection|
+        public_send("#{name}=", polymorphic.is_a?(reflection.klass) ? polymorphic : nil)
+      end
+    end
+
+    def validate_exclusive_arcs
+      exclusive_arcs.each do |(arc, definition)|
+        foreign_key_count = definition.reflections.keys.count { |name| !!public_send(name) }
+        valid = definition.options[:optional] ? foreign_key_count.in?([0, 1]) : foreign_key_count == 1
+        errors.add(arc, :arc_not_exclusive) unless valid
+      end
+    end
+  end
+end

data/lib/exclusive_arc/version.rb

@@ -0,0 +1,3 @@
+module ExclusiveArc
+  VERSION = "0.1.0"
+end

data/lib/exclusive_arc.rb

@@ -0,0 +1,4 @@
+require "exclusive_arc/version"
+require "exclusive_arc/definition"
+require "exclusive_arc/model"
+require "generators/exclusive_arc_generator"

data/lib/generators/exclusive_arc_generator.rb

@@ -0,0 +1,91 @@
+require "rails/generators"
+require "rails/generators/active_record/migration/migration_generator"
+
+class ExclusiveArcGenerator < ActiveRecord::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+  desc "Adds an Exclusive Arc to an ActiveRecord model and generates the migration for it"
+
+  argument :arguments, type: :array, default: [], banner: "arc belongs_to1 belongs_to2 ..."
+  class_option :optional, type: :boolean, default: false, desc: "Exclusive arc is optional"
+  class_option :skip_foreign_key_constraints, type: :boolean, default: false, desc: "Skip foreign key constraints"
+  class_option :skip_foreign_key_indexes, type: :boolean, default: false, desc: "Skip foreign key partial indexes"
+  class_option :skip_check_constraint, type: :boolean, default: false, desc: "Skip check constraint"
+
+  Error = Class.new(StandardError)
+
+  def initialize(*args)
+    raise Error, "must supply a Model, arc, and at least two belong_tos" if args[0].size <= 3
+    super
+  end
+
+  def create_exclusive_arc_migration
+    migration_template(
+      "migration.rb.erb",
+      "db/migrate/#{migration_file_name}"
+    )
+  end
+
+  def inject_exclusive_arc_into_model
+    indents = "  " * (class_name.scan("::").count + 1)
+    inject_into_class(
+      model_file_path,
+      class_name.demodulize,
+      <<~RB
+        #{indents}include ExclusiveArc::Model
+        #{indents}exclusive_arc #{model_exclusive_arcs}
+      RB
+    )
+  end
+
+  no_tasks do
+    def model_exclusive_arcs
+      string = ":#{arc}, [#{belong_tos.map { |reference| ":#{reference}" }.join(", ")}]"
+      string += ", optional: true" if options[:optional]
+      string
+    end
+
+    def add_reference(reference)
+      string = "add_reference :#{table_name}, :#{reference}"
+      type = reference_type(reference)
+      string += ", type: :#{type}" unless /int/.match?(type.downcase)
+      string += ", foreign_key: true" unless options[:skip_foreign_key_constraints]
+      string += ", index: {where: \"#{reference}_id IS NOT NULL\"}" unless options[:skip_foreign_key_indexes]
+      string
+    end
+
+    def migration_file_name
+      "#{class_name.delete(":").underscore}_#{arc}_exclusive_arc.rb"
+    end
+
+    def migration_class_name
+      [class_name.delete(":").singularize, arc.classify, "ExclusiveArc"].join
+    end
+
+    def reference_type(reference)
+      klass = reference.singularize.classify.constantize
+      klass.columns.find { |col| col.name == klass.primary_key }.sql_type
+    rescue
+      "bigint"
+    end
+
+    def check_constraint
+      reference_checks = belong_tos.map do |reference|
+        "CASE WHEN #{reference}_id IS NULL THEN 0 ELSE 1 END"
+      end
+      condition = options[:optional] ? "<= 1" : "= 1"
+      "(#{reference_checks.join(" + ")}) #{condition}"
+    end
+
+    def arc
+      arguments[0]
+    end
+
+    def belong_tos
+      @belong_tos ||= arguments.slice(1, arguments.length - 1)
+    end
+
+    def model_file_path
+      File.join("app", "models", "#{file_path}.rb")
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    <% belong_tos.each do |reference| %><%= add_reference(reference) %>
+    <% end %><% unless options[:skip_check_constraint] %>add_check_constraint(
+      :<%= table_name %>,
+      "<%= check_constraint %>",
+      name: :<%= arc %>
+    )<% end %>
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-exclusive-arc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- justin talbott
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-04-08 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: 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:
+email:
+- gmail@justintalbott.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- lib/activerecord-exclusive-arc.rb
+- lib/exclusive_arc.rb
+- lib/exclusive_arc/definition.rb
+- lib/exclusive_arc/model.rb
+- lib/exclusive_arc/version.rb
+- lib/generators/exclusive_arc_generator.rb
+- lib/generators/templates/migration.rb.erb
+homepage: https://github.com/waymondo/exclusive-arc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/waymondo/exclusive-arc
+  source_code_uri: https://github.com/waymondo/exclusive-arc
+  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.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: An ActiveRecord extension for polymorphic exclusive arc relationships
+test_files: []