activerecord-exclusive-arc 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3824d9259213c59c55ee5287cc9bd3b8e76924be405a269c6752434811c2599
-  data.tar.gz: 2e8b6ad42b5b4cad774e7ef56e21c54fa9a0e8223fce05762ecb60cf791b4b87
+  metadata.gz: 2fa6d4449542465ef3cc8420e9428a6faee1b4a91c547f5df660aeb615c15638
+  data.tar.gz: f945d9a76c78658e9c3a7a357f9c46202377ccd11488ec1cd286dfb467dd8eb2
 SHA512:
-  metadata.gz: 28d0736dfd28b87e367ab62d9ac1c39cc556bc76d999b390a4b6220b88ac566bcac66c6fda36b0237a5442180b44602c72e6ef837ed99a4f281b0e42da4aac81
-  data.tar.gz: e62da6627153c7853dde9bba360ec654ea28baf088bb4db6261fc77dd88fc78d1bf4b5f5d2c2d777682d0233e7f6ab72567ed1790e8813670b4964ec69a063a8
+  metadata.gz: 8c829330cc1049ffddf223122cab10681e454f13184ea0ae7218bb55ed8f3b90e3ede9e140907917b2402f7a5740b0857ffe5c71dd0ed798a9a82cc364c30438
+  data.tar.gz: 140aea768b0e93d5e7cf22b7c0c6517a7ce19ecc64e48bce405501ed06adcc47072a8f789bccabb20fb9b0fb366b2928d5b14573bff9bed91245a4262fb360af

data/Gemfile

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

data/README.md

@@ -1,31 +1,22 @@
-### What does it do?
+## 💫 `activerecord-exclusive-arc` 💫
 
-It allows an ActiveRecord model to exclusively belong to one of any number of different types of ActiveRecord
-models.
+A RubyGem that allows an ActiveRecord model to exclusively belong to one of any number of different
+types of ActiveRecord models.
 
-### Doesn’t Rails already provide this?
+### Doesn’t Rails already provide a way to do 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.
+Yes but [here’s a post about why this exists](https://waymondo.com/posts/are-exclusive-arcs-evil/).
 
 ### 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.
+It reduces the boilerplate of managing a _Polymorphic Assication_ modeled as a pattern called an
+_Exclusive Arc_, where each potential polymorphic reference has its own foreign key. This maps
+nicely to a set of optional `belongs_to` relationships, some polymorphic convenience methods, and a
+database check constraint with a matching `ActiveRecord` validation.
 
 ## How to use
 
-Firstly, in your `Gemfile`:
+Firstly, add the gem to your `Gemfile` and `bundle install`:
 
 ```ruby
 gem "activerecord-exclusive-arc"
@@ -37,8 +28,8 @@ 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:
+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
@@ -84,25 +75,26 @@ class Comment < ApplicationRecord
 end
 ```
 
-Continuing with our example, the generator command would also produce a migration that looks like this:
+Continuing with our example, the generator command would also produce a migration that looks like
+this:
 
 ```ruby
-class CommentCommentableExclusiveArc < ActiveRecord::Migration[7.0]
+class CommentCommentableExclusiveArcPostComment < 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
+      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.
+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
 
@@ -114,30 +106,61 @@ 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.
+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 reference.
+
+### Updating an existing exclusive arc
+
+If you need to add an additional polymorphic option to an existing exclusive arc, you can simply run
+the generator command again with the additional target. Existing references will be skipped and the
+check constraint will be removed and re-added in a reversible manner.
+
+```
+bin/rails g exclusive_arc Comment commentable post comment page
+```
+
+``` ruby
+class CommentCommentableExclusiveArcPostCommentPage < ActiveRecord::Migration[7.0]
+  def change
+    add_reference :comments, :page, foreign_key: true, index: {where: "page_id IS NOT NULL"}
+    remove_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"
+    )
+    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 + CASE WHEN page_id IS NULL THEN 0 ELSE 1 END) = 1",
+      name: "commentable"
+    )
+  end
+end
+```
+
+The registration in the model will be updated as well.
+
+``` ruby
+class Comment < ApplicationRecord
+  include ExclusiveArc::Model
+  has_exclusive_arc :commentable, [:post, :comment, :page]
+end
+```
 
 ### 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.
+Currently `activerecord-exclusive-arc` is tested against a matrix of:
+* Ruby 2.7 and 3.3
+* Rails 6.1, 7.0, 7.1
+* `postgresql`, `sqlite3`, and `mysql2` database adapters
 
 ### Contributing
 

data/lib/exclusive_arc/model.rb

@@ -15,7 +15,9 @@ module ExclusiveArc
           next if reflections[option.to_s]
 
           belongs_to(option, optional: true)
+          validate :"validate_#{arc}"
         end
+
         exclusive_arcs[arc] = Definition.new(
           reflections: reflections.slice(*belong_tos.map(&:to_s)),
           options: args[2] || {}
@@ -39,9 +41,11 @@ module ExclusiveArc
             assign_exclusive_arc(:#{arc}, polymorphic)
             @#{arc} = polymorphic
           end
-        RUBY
 
-        validate :validate_exclusive_arcs
+          def validate_#{arc}
+            validate_exclusive_arc(:#{arc})
+          end
+        RUBY
       end
     end
 
@@ -54,12 +58,11 @@ module ExclusiveArc
       assign_attributes attributes
     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
+    def validate_exclusive_arc(arc)
+      definition = exclusive_arcs.fetch(arc)
+      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

data/lib/exclusive_arc/version.rb

@@ -1,3 +1,3 @@
 module ExclusiveArc
-  VERSION = "0.2.2"
+  VERSION = "0.3.1"
 end

data/lib/generators/exclusive_arc_generator.rb

@@ -31,15 +31,20 @@ class ExclusiveArcGenerator < ActiveRecord::Generators::Base
       model_file_path,
       class_name.demodulize,
       <<~RB
-        #{indents}has_exclusive_arc #{model_exclusive_arcs}
+        #{indents}include ExclusiveArc::Model
       RB
     )
-    inject_into_class(
+    gsub_file(
       model_file_path,
-      class_name.demodulize,
-      <<~RB
-        #{indents}include ExclusiveArc::Model
+      /has_exclusive_arc :#{arc}(.*)$/,
+      ""
+    )
+    inject_into_file(
+      model_file_path,
+      <<~RB,
+        #{indents}has_exclusive_arc #{model_exclusive_arcs}
       RB
+      after: "include ExclusiveArc::Model\n"
     )
   end
 
@@ -52,8 +57,8 @@ class ExclusiveArcGenerator < ActiveRecord::Generators::Base
 
     def add_references
       belong_tos.map do |reference|
-        add_reference(reference)
-      end.join("\n")
+        add_reference(reference) unless column_exists?(reference)
+      end.compact.join("\n")
     end
 
     def add_reference(reference)
@@ -78,11 +83,22 @@ class ExclusiveArcGenerator < ActiveRecord::Generators::Base
     end
 
     def migration_file_name
-      "#{class_name.delete(":").underscore}_#{arc}_exclusive_arc.rb"
+      "#{class_name.delete(":").underscore}_#{arc}_exclusive_arc_#{belong_tos.map(&:underscore).join("_")}.rb"
     end
 
     def migration_class_name
-      [class_name.delete(":").singularize, arc.classify, "ExclusiveArc"].join
+      (
+        [class_name.delete(":").singularize, arc.classify, "ExclusiveArc"] |
+        belong_tos.map(&:classify)
+      ).join
+    end
+
+    def existing_check_constraint
+      @existing_check_constraint ||=
+        class_name.constantize.connection.check_constraints(class_name.constantize.table_name)
+          .find { |constraint| constraint.name == arc }
+    rescue
+      nil
     end
 
     def reference_type(reference)
@@ -98,19 +114,41 @@ class ExclusiveArcGenerator < ActiveRecord::Generators::Base
       reference.tableize
     end
 
+    def column_exists?(reference)
+      foreign_key = foreign_key_name(reference)
+      class_name.constantize.column_names.include?(foreign_key)
+    rescue
+      false
+    end
+
     def foreign_key_name(reference)
       class_name.constantize.reflections[reference].foreign_key
     rescue
       "#{reference}_id"
     end
 
+    def remove_check_constraint
+      return unless class_name.constantize.connection.supports_check_constraints?
+      return if options[:skip_check_constraint]
+      return unless existing_check_constraint&.expression
+
+      <<-RUBY.chomp
+    remove_check_constraint(
+      :#{table_name},
+      "#{existing_check_constraint.expression.squish}",
+      name: "#{arc}"
+    )
+      RUBY
+    end
+
     def add_check_constraint
+      return unless class_name.constantize.connection.supports_check_constraints?
       return if options[:skip_check_constraint]
-      <<-RUBY
+      <<-RUBY.chomp
     add_check_constraint(
       :#{table_name},
       "#{check_constraint}",
-      name: :#{arc}
+      name: "#{arc}"
     )
       RUBY
     end

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

@@ -1,6 +1,7 @@
 class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
 <%= add_references %>
+<%= remove_check_constraint %>
 <%= add_check_constraint %>
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-exclusive-arc
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
 platform: ruby
 authors:
 - justin talbott
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-10 00:00:00.000000000 Z
+date: 2024-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -89,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.4
 signing_key:
 specification_version: 4
 summary: An ActiveRecord extension for polymorphic exclusive arc relationships