union_of 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd3284d8704305e0614cd4baf7eef91b096cca37d2dbcc8759495782420b52db
-  data.tar.gz: 80f5a3386671e8825f71d89d2fd4033c48ed76c8fd1598f85f9a7716bb95d93f
+  metadata.gz: 6a4e286d4ad0ea71318a2995e3609209fb9c3829878c8638abda047602922525
+  data.tar.gz: c0b02d918a69fb395504b2036cf2da55903960229a8abe4ccf10d7f58fc0ac9b
 SHA512:
-  metadata.gz: 617a3ac3c4fe43f1ad8a54566ffb05b4849974851353fd8b473436bc5a6aa914d16b43f52e0449dcf9e6744c25f21ea0dcd3bb43f0c6ef972fe35715d9c514c2
-  data.tar.gz: 0efd99d12be0ab7d2ecb6ac35b96ee70afcd1282a6c540c80c363f6e067613d9ad70fde4adcec1777c3cf3490d2412aed094446a28ff2f45e107c0d83f4b7143
+  metadata.gz: 1ef814ee0cc9e2749801e1f16d186ccf65357e99912e50e9e7db7691c134a0e0616a29c9cdbc24c7409b0e8b86430b57ad18863ffc1f2c6bda16819211ed42df
+  data.tar.gz: 305fd61e60429096a23fa8d824f7822e4f5d023cbbcdedfdde9209a710646dd01835a33f233a804f6bdcdd5fed50b2e710b78433323d789ffb35cac822da8704

data/CHANGELOG.md

@@ -1,3 +1,7 @@
 # Changelog
 
 ## [Unreleased]
+
+## v1.0.0
+
+Initial release.

data/README.md

@@ -1,31 +1,185 @@
-# UnionOf
+# union_of
 
-TODO: Delete this and the text below, and describe your gem
+[![CI](https://github.com/keygen-sh/union_of/actions/workflows/test.yml/badge.svg)](https://github.com/keygen-sh/union_of/actions)
+[![Gem Version](https://badge.fury.io/rb/union_of.svg)](https://badge.fury.io/rb/union_of)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/union_of`. To experiment with that code, run `bin/console` for an interactive prompt.
+Use `union_of` to create associations that combine multiple Active Record
+associations using a SQL `UNION` under the hood. `union_of` fully supports
+joins, preloading, and eager loading, as well as through-union associations.
+
+This gem was extracted from [Keygen](https://keygen.sh) and is being used in
+production to serve millions of API requests per day, performantly querying
+tables with millions and millions of rows.
+
+Sponsored by:
+
+<a href="https://keygen.sh?ref=union_of">
+  <div>
+    <img src="https://keygen.sh/images/logo-pill.png" width="200" alt="Keygen">
+  </div>
+</a>
+
+_A fair source software licensing and distribution API._
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'union_of'
+```
 
-Install the gem and add to the application's Gemfile by executing:
+And then execute:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```bash
+$ bundle
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```bash
+$ gem install union_of
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+To use `union_of`, define a `has_many` association as you would normally, and
+provide the associations you'd like to union together via the `union_of:`
+keyword:
+
+```ruby
+class Book < ActiveRecord::Base
+  # the primary author of the book
+  belongs_to :author, class_name: 'User', foreign_key: 'author_id', optional: true
+
+  # coauthors of the book via a join table
+  has_many :coauthorships
+  has_many :coauthors, through: :coauthorships, source: :user
+
+  # prefacers for the book via a join table
+  has_many :prefaces
+  has_many :prefacers, through: :prefaces, source: :user
+
+  # prefacers for the book via a join table
+  has_many :forewords
+  has_many :foreworders, through: :forewords, source: :user
+
+  # illustrators for the book via a join table
+  has_many :illustrations
+  has_many :illustrators, -> { distinct }, through: :illustrations, source: :user
+
+  # editors for the book via a join table
+  has_many :edits
+  has_many :editors, -> { distinct }, through: :edits, source: :user
+
+  # union association for all contributors to the book
+  has_many :contributors, class_name: 'User', union_of: %i[
+    author
+    coauthors
+    foreworders
+    prefacers
+    illustrators
+    editors
+  ]
+end
+```
+
+Here's a quick example of what's possible:
+
+```ruby
+# contributors to the book
+author = User.create(name: 'Isaac Asimov')
+editor = User.create(name: 'John W. Campbell')
+illustrator = User.create(name: 'Frank Kelly Freas')
+writer = User.create(name: 'Ray Bradbury')
+
+# create book by the author
+book = Book.create(title: 'I, Robot', author:)
+
+# assign a preface by the author
+Preface.create(user: author, book:)
+
+# assign foreword writers
+Foreword.create(user: writer, book:)
+Foreword.create(user: editor, book:)
 
-## Development
+# assign an illustrator
+Illustration.create(user: illustrator, book:)
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+# assign an editor
+Edit.create(user: editor, book:)
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# access all contributors (author, editors, illustrator, etc.)
+book.contributors.to_a
+# => [#<User id=1, name="Isaac Asimov">, #<User id=2, name="John W. Campbell">, #<User id=3, name="Frank Kelly Freas">, #<User id=4, name="Ray Bradbury">]
+
+# example of querying the union of contributors
+book.contributors.order(:name).limit(3)
+# => [#<User id=4, name="Frank Kelly Freas">, #<User id=3, name="Isaac Asimov">, #<User id=2, name="John W. Campbell">]
+
+book.contributors.where(id: editor.id)
+# => [#<User id=2, name="John W. Campbell">]
+
+book.contributors.to_sql
+# => SELECT * FROM users WHERE id IN (
+#      SELECT id FROM users WHERE id = 1
+#      UNION
+#      SELECT users.id FROM users INNER JOIN prefaces ON users.id = prefaces.user_id WHERE prefaces.book_id = 1
+#      UNION
+#      SELECT users.id FROM users INNER JOIN forewords ON users.id = forewords.user_id WHERE forewords.book_id = 1
+#      UNION
+#      SELECT DISTINCT users.id FROM users INNER JOIN illustrations ON users.id = illustrations.user_id WHERE illustrations.book_id = 1
+#      UNION
+#      SELECT DISTINCT users.id FROM users INNER JOIN edits ON users.id = edits.user_id WHERE edits.book_id = 1
+#   )
+
+# example of more advanced querying e.g. preloading the union
+Book.joins(:contributors).where(contributors: { ... })
+Book.preload(:contributors)
+Book.eager_load(:contributors)
+Book.includes(:contributors)
+```
+
+Right now, the underlying table and model for each unioned association must
+match. We'd like to change that in the future. Originally, `union_of` was
+created to make migrating from a one-to-many relationship to a many-to-many
+relationship easier and safer, while retaining backwards compatibility.
+
+There is support for complex unions as well, e.g. a union made up of direct and
+through associations, even when those associations utilize union associations.
+
+## Supported databases
+
+We currently support PostgreSQL, MySQL, and MariaDB. We'd love contributions
+that add SQLite support, but we probably won't add it ourselves.
+
+## Supported Rubies
+
+**`union_of` supports Ruby 3.1 and above.** We encourage you to upgrade if
+you're on an older version. Ruby 3 provides a lot of great features, like better
+pattern matching and a new shorthand hash syntax.
+
+## Performance notes
+
+As is expected, you will need to pay close attention to performance and ensure
+your tables are indexed well. We have tried to make the underlying `UNION`
+queries as efficient as possible, but please open an issue or PR if you are
+encountering a performance issue that is caused by this gem. But good indexing
+will go a long way.
+
+We use Postgres in production, but we do not actively use MySQL or MariaDB, so
+there may be performance issues we are unaware of. If you stumble upon issues,
+please open an issue or a PR.
+
+## Is it any good?
+
+Yes.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/union_of.
+If you have an idea, or have discovered a bug, please open an issue or create a
+pull request.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/union_of/association.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'readonly_association'
+require_relative 'scope'
+
+module UnionOf
+  class Association < UnionOf::ReadonlyAssociation
+    def skip_statement_cache?(...) = true # doesn't work with cache
+    def association_scope
+      return if
+        klass.nil?
+
+      @association_scope ||= UnionOf::Scope.create.scope(self)
+    end
+  end
+end

data/lib/union_of/builder.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module UnionOf
+  class Builder < ActiveRecord::Associations::Builder::CollectionAssociation
+    private_class_method def self.valid_options(...) = %i[sources class_name inverse_of extend]
+    private_class_method def self.macro              = :union_of
+  end
+end

data/lib/union_of/macro.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'builder'
+
+module UnionOf
+  module Macro
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def union_of(name, scope = nil, **options, &extension)
+        reflection = UnionOf::Builder.build(self, name, scope, options, &extension)
+
+        ActiveRecord::Reflection.add_union_reflection(self, name, reflection)
+        ActiveRecord::Reflection.add_reflection(self, name, reflection)
+      end
+
+      def has_many(name, scope = nil, **options, &extension)
+        if sources = options.delete(:union_of)
+          union_of(name, scope, **options.merge(sources:), &extension)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/union_of/preloader/association.rb

@@ -0,0 +1,88 @@
+
+# frozen_string_literal: true
+
+module UnionOf
+  module Preloader
+    class Association < ActiveRecord::Associations::Preloader::ThroughAssociation
+      def load_records(*)
+        preloaded_records # we don't need to load anything except the union associations
+      end
+
+      def preloaded_records
+        @preloaded_records ||= union_preloaders.flat_map(&:preloaded_records)
+      end
+
+      def records_by_owner
+        @records_by_owner ||= owners.each_with_object({}) do |owner, result|
+          if loaded?(owner)
+            result[owner] = target_for(owner)
+
+            next
+          end
+
+          records = union_records_by_owner[owner] || []
+          records.compact!
+          records.sort_by! { preload_index[_1] } unless scope.order_values.empty?
+          records.uniq! if scope.distinct_value
+
+          result[owner] = records
+        end
+      end
+
+      def runnable_loaders
+        return [self] if
+          data_available?
+
+        union_preloaders.flat_map(&:runnable_loaders)
+      end
+
+      def future_classes
+        return [] if
+          run?
+
+        union_classes  = union_preloaders.flat_map(&:future_classes).uniq
+        source_classes = source_reflection.chain.map(&:klass)
+
+        (union_classes + source_classes).uniq
+      end
+
+      private
+
+      def data_available?
+        owners.all? { loaded?(_1) } || union_preloaders.all?(&:run?)
+      end
+
+      def source_reflection = reflection
+      def union_reflections = reflection.union_reflections
+
+      def union_preloaders
+        @union_preloaders ||= ActiveRecord::Associations::Preloader.new(scope:, records: owners, associations: union_reflections.collect(&:name))
+                                                                   .loaders
+      end
+
+      def union_records_by_owner
+        @union_records_by_owner ||= union_preloaders.map(&:records_by_owner).reduce do |left, right|
+          left.merge(right) do |owner, left_records, right_records|
+            left_records | right_records # merge record sets
+          end
+        end
+      end
+
+      def build_scope
+        scope = source_reflection.klass.unscoped
+
+        if reflection.type && !reflection.through_reflection?
+          scope.where!(reflection.type => model.polymorphic_name)
+        end
+
+        scope.merge!(reflection_scope) unless reflection_scope.empty_scope?
+
+        if preload_scope && !preload_scope.empty_scope?
+          scope.merge!(preload_scope)
+        end
+
+        cascade_strict_loading(scope)
+      end
+    end
+  end
+end

data/lib/union_of/preloader.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'preloader/association'
+
+module UnionOf
+  module Preloader; end
+end

data/lib/union_of/railtie.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal
+
+require_relative 'macro'
+require_relative 'preloader'
+require_relative 'readonly_association_proxy'
+
+module UnionOf
+  module ReflectionExtension
+    def add_union_reflection(model, name, reflection)
+      model.union_reflections = model.union_reflections.merge(name.to_s => reflection)
+    end
+
+    private
+
+    def reflection_class_for(macro)
+      case macro
+      when :union_of
+        UnionOf::Reflection
+      else
+        super
+      end
+    end
+  end
+
+  module MacroReflectionExtension
+    def through_union_of? = false
+    def union_of?         = false
+  end
+
+  module RuntimeReflectionExtension
+    delegate :union_of?, :union_sources, to: :@reflection
+    delegate :name, :active_record_primary_key, to: :@reflection # FIXME(ezekg)
+  end
+
+  module ActiveRecordExtensions
+    extend ActiveSupport::Concern
+
+    included do
+      include UnionOf::Macro
+
+      class_attribute :union_reflections, instance_writer: false, default: {}
+    end
+
+    class_methods do
+      def reflect_on_all_unions = union_reflections.values
+      def reflect_on_union(union)
+        union_reflections[union.to_s]
+      end
+    end
+  end
+
+  module ThroughReflectionExtension
+    delegate :union_of?, :union_sources, to: :source_reflection
+    delegate :join_scope, to: :source_reflection
+
+    def through_union_of? = through_reflection.union_of? || through_reflection.through_union_of?
+  end
+
+  module AssociationExtension
+    def scope
+      if reflection.union_of? || reflection.through_union_of?
+        UnionOf::Scope.create.scope(self)
+      else
+        super
+      end
+    end
+  end
+
+  module PreloaderExtension
+    def preloader_for(reflection)
+      if reflection.union_of?
+        UnionOf::Preloader::Association
+      else
+        super
+      end
+    end
+  end
+
+  module DelegationExtension
+    def delegated_classes
+      super << UnionOf::ReadonlyAssociationProxy
+    end
+  end
+
+  module JoinAssociationExtension
+    # Overloads Rails internals to prepend our left outer joins onto the join chain since Rails
+    # unfortunately does not do this for us (it can do inner joins via the LeadingJoin arel
+    # node, but it can't do outer joins because there is no LeadingOuterJoin node).
+    def join_constraints(foreign_table, foreign_klass, join_type, alias_tracker)
+      chain = reflection.chain.reverse
+      joins = super
+
+      # FIXME(ezekg) This is inefficient (we're recreating reflection scopes).
+      chain.zip(joins).each do |reflection, join|
+        klass = reflection.klass
+        table = join.left
+
+        if reflection.union_of?
+          scope = reflection.join_scope(table, foreign_table, foreign_klass, alias_tracker)
+          arel  = scope.arel(alias_tracker.aliases)
+
+          # Splice union dependencies, i.e. left joins, into the join chain. This is the least
+          # intrusive way of doing this, since we don't want to overload AR internals.
+          unless arel.join_sources.empty?
+            index = joins.index(join)
+
+            unless (constraints = arel.constraints).empty?
+              right = join.right
+
+              right.expr = constraints # updated aliases
+            end
+
+            joins.insert(index, *arel.join_sources)
+          end
+        end
+
+        # The current table in this iteration becomes the foreign table in the next
+        foreign_table, foreign_klass = table, klass
+      end
+
+      joins
+    end
+  end
+
+  ActiveSupport.on_load :active_record do
+    include ActiveRecordExtensions
+
+    ActiveRecord::Reflection.singleton_class.prepend(ReflectionExtension)
+    ActiveRecord::Reflection::MacroReflection.prepend(MacroReflectionExtension)
+    ActiveRecord::Reflection::RuntimeReflection.prepend(RuntimeReflectionExtension)
+    ActiveRecord::Reflection::ThroughReflection.prepend(ThroughReflectionExtension)
+    ActiveRecord::Associations::Association.prepend(AssociationExtension)
+    ActiveRecord::Associations::JoinDependency::JoinAssociation.prepend(JoinAssociationExtension)
+    ActiveRecord::Associations::Preloader::Branch.prepend(PreloaderExtension)
+    ActiveRecord::Delegation.singleton_class.prepend(DelegationExtension)
+  end
+end

data/lib/union_of/readonly_association.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module UnionOf
+  class ReadonlyAssociation < ActiveRecord::Associations::CollectionAssociation
+    MUTATION_METHODS = %i[
+      writer ids_writer
+      insert_record build_record
+      destroy_all delete_all delete_records
+      update_all concat_records
+    ]
+
+    MUTATION_METHODS.each do |method_name|
+      define_method method_name do |*, **|
+        raise UnionOf::ReadonlyAssociationError.new(owner, reflection)
+      end
+    end
+
+    def reader
+      ensure_klass_exists!
+
+      if stale_target?
+        reload
+      end
+
+      @proxy ||= UnionOf::ReadonlyAssociationProxy.create(klass, self)
+      @proxy.reset_scope
+    end
+
+    def count_records
+      count = scope.count(:all)
+
+      if count.zero?
+        target.select!(&:new_record?)
+        loaded!
+      end
+
+      [association_scope.limit_value, count].compact.min
+    end
+  end
+end

data/lib/union_of/readonly_association_proxy.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module UnionOf
+  class ReadonlyAssociationProxy < ActiveRecord::Associations::CollectionProxy
+    MUTATION_METHODS = %i[
+      insert insert! insert_all insert_all!
+      build new create create!
+      upsert upsert_all update_all update! update
+      delete destroy destroy_all delete_all
+    ]
+
+    MUTATION_METHODS.each do |method_name|
+      define_method method_name do |*, **|
+        raise UnionOf::ReadonlyAssociationError.new(@association.owner, @association.reflection)
+      end
+    end
+  end
+end

data/lib/union_of/reflection.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module UnionOf
+  class Reflection < ActiveRecord::Reflection::AssociationReflection
+    attr_reader :union_sources
+
+    def initialize(...)
+      super
+
+      @union_sources = @options[:sources]
+    end
+
+    def macro             = :union_of
+    def union_of?         = true
+    def collection?       = true
+    def association_class = UnionOf::Association
+    def union_reflections = union_sources.collect { active_record.reflect_on_association(_1) }
+
+    def join_scope(table, foreign_table, foreign_klass, alias_tracker = nil)
+      predicate_builder = predicate_builder(table)
+      scope_chain_items = join_scopes(table, predicate_builder)
+      klass_scope       = klass_join_scope(table, predicate_builder)
+
+      # This holds our union's constraints. For example, if we're unioning across 3
+      # tables, then this will hold constraints for all 3 of those tables, so that
+      # the join on our target table mirrors the union of all 3 associations.
+      foreign_constraints = []
+
+      union_sources.each do |union_source|
+        union_reflection = foreign_klass.reflect_on_association(union_source)
+
+        if union_reflection.through_reflection?
+          source_reflection  = union_reflection.source_reflection
+          through_reflection = union_reflection.through_reflection
+          through_klass      = through_reflection.klass
+          through_table      = through_klass.arel_table
+
+          # Alias table if we're provided with an alias tracker (i.e. via our #join_constraints overload)
+          unless alias_tracker.nil?
+            through_table = alias_tracker.aliased_table_for(through_table) do
+              through_reflection.alias_candidate(union_source)
+            end
+          end
+
+          # Create base join constraints and add default constraints if available
+          through_constraint = through_table[through_reflection.join_primary_key].eq(
+            foreign_table[through_reflection.join_foreign_key],
+          )
+
+          unless (where_clause = through_klass.default_scoped.where_clause).empty?
+            through_constraint = where_clause.ast.and(through_constraint)
+          end
+
+          klass_scope.joins!(
+            Arel::Nodes::OuterJoin.new(
+              through_table,
+              Arel::Nodes::On.new(through_constraint),
+            ),
+          )
+
+          foreign_constraints << table[source_reflection.join_primary_key].eq(through_table[source_reflection.join_foreign_key])
+        else
+          foreign_constraints << table[union_reflection.join_primary_key].eq(foreign_table[union_reflection.join_foreign_key])
+        end
+      end
+
+      unless foreign_constraints.empty?
+        foreign_constraint = foreign_constraints.reduce(&:or)
+
+        klass_scope.where!(foreign_constraint)
+      end
+
+      unless scope_chain_items.empty?
+        scope_chain_items.reduce(klass_scope) do |scope, item|
+          scope.merge!(item) # e.g. default scope constraints
+        end
+
+        # FIXME(ezekg) Wrapping the where clause in a grouping node so that Rails
+        #              doesn't append our left outer joins a second time. This is
+        #              because internally, during joining in #join_constraints,
+        #              if Rails sees an Arel::Nodes::And node with predicates that
+        #              don't match the current table, it'll concat all join
+        #              sources. We don't want that, thus the hack.
+        klass_scope.where_clause = ActiveRecord::Relation::WhereClause.new(
+          [Arel::Nodes::Grouping.new(klass_scope.where_clause.ast)],
+        )
+      end
+
+      klass_scope
+    end
+
+    # FIXME(ezekg) scope cache is borked
+    def association_scope_cache(...) = raise NotImplementedError
+
+    def deconstruct_keys(keys) = { name:, options: }
+  end
+end

data/lib/union_of/scope.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module UnionOf
+  class Scope < ActiveRecord::Associations::AssociationScope
+    private
+
+    def last_chain_scope(scope, reflection, owner)
+      return super unless reflection.union_of?
+
+      foreign_klass = reflection.klass
+      foreign_table = reflection.aliased_table
+      primary_key   = reflection.active_record_primary_key
+
+      sources = reflection.union_sources.map do |source|
+        association = owner.association(source)
+
+        association.scope.select(association.reflection.active_record_primary_key)
+                         .unscope(:order)
+                         .arel
+      end
+
+      unions = sources.compact.reduce(nil) do |left, right|
+        if left
+          Arel::Nodes::Union.new(left, right)
+        else
+          right
+        end
+      end
+
+      # We can simplify the query if the scope class is the same as our foreign class
+      if scope.klass == foreign_klass
+        scope.where!(
+          foreign_table[primary_key].in(
+            foreign_table.project(foreign_table[primary_key])
+                         .from(
+                           Arel::Nodes::TableAlias.new(unions, foreign_table.name),
+                         ),
+          ),
+        )
+      else
+        # FIXME(ezekg) Selecting IDs in a separate query is faster than a subquery
+        #              selecting IDs, or an EXISTS subquery, or even a
+        #              materialized CTE. Not sure why...
+        ids = foreign_klass.find_by_sql(
+                             foreign_table.project(foreign_table[primary_key])
+                                          .from(
+                                            Arel::Nodes::TableAlias.new(unions, foreign_table.name),
+                                          ),
+                           )
+                           .pluck(
+                             primary_key,
+                           )
+
+        scope.where!(
+          foreign_table[primary_key].in(ids),
+        )
+      end
+
+      scope.merge!(
+        scope.default_scoped,
+      )
+
+      scope
+    end
+
+    def next_chain_scope(scope, reflection, next_reflection)
+      return super unless reflection.union_of?
+
+      klass         = reflection.klass
+      table         = klass.arel_table
+      foreign_klass = next_reflection.klass
+      foreign_table = foreign_klass.arel_table
+
+      # This holds our union's constraints. For example, if we're unioning across 3
+      # tables, then this will hold constraints for all 3 of those tables, so that
+      # the join on our target table mirrors the union of all 3 associations.
+      foreign_constraints = []
+
+      reflection.union_sources.each do |union_source|
+        union_reflection = foreign_klass.reflect_on_association(union_source)
+
+        if union_reflection.through_reflection?
+          through_reflection = union_reflection.through_reflection
+          through_table      = through_reflection.klass.arel_table
+
+          scope.left_outer_joins!(
+            through_reflection.name,
+          )
+
+          foreign_constraints << foreign_table[through_reflection.join_foreign_key].eq(through_table[through_reflection.join_primary_key])
+        else
+          foreign_constraints << foreign_table[union_reflection.join_foreign_key].eq(table[union_reflection.join_primary_key])
+        end
+      end
+
+      # Flatten union constraints and add any default constraints
+      foreign_constraint = unless (where_clause = foreign_klass.default_scoped.where_clause).empty?
+                             where_clause.ast.and(foreign_constraints.reduce(&:or))
+                           else
+                             foreign_constraints.reduce(&:or)
+                           end
+
+      scope.joins!(
+        Arel::Nodes::InnerJoin.new(
+          foreign_table,
+          Arel::Nodes::On.new(
+            foreign_constraint,
+          ),
+        ),
+      )
+
+      # FIXME(ezekg) Why is this needed? Should be handled automatically...
+      scope.merge!(
+        scope.default_scoped,
+      )
+
+      scope
+    end
+
+    # NOTE(ezekg) This overloads our scope's joins to not use an Arel::Nodes::LeadingJoin node.
+    def join(table, constraint)
+      Arel::Nodes::InnerJoin.new(table, Arel::Nodes::On.new(constraint))
+    end
+  end
+end

data/lib/union_of/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UnionOf
-  VERSION = '0.0.2'
+  VERSION = '1.0.0'
 end

data/lib/union_of.rb

@@ -1,6 +1,25 @@
 # frozen_string_literal: true
 
+require 'active_support'
+require 'active_record'
+
+require_relative 'union_of/association'
+require_relative 'union_of/builder'
+require_relative 'union_of/macro'
+require_relative 'union_of/preloader'
+require_relative 'union_of/readonly_association_proxy'
+require_relative 'union_of/readonly_association'
+require_relative 'union_of/reflection'
+require_relative 'union_of/scope'
 require_relative 'union_of/version'
+require_relative 'union_of/railtie'
 
 module UnionOf
+  class Error < ActiveRecord::ActiveRecordError; end
+
+  class ReadonlyAssociationError < Error
+    def initialize(owner, reflection)
+      super("Cannot modify association '#{owner.class.name}##{reflection.name}' because it is read-only")
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: union_of
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-04-11 00:00:00.000000000 Z
+date: 2024-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -38,9 +38,79 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 'Define associations that are a union of other associations on an Active
-  Record model, using a SQL UNION, with full support for joins, preloading and eager
-  loading on the union association. '
+- !ruby/object:Gem::Dependency
+  name: temporary_tables
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sql_matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Create associations that combine multiple Active Record associations
+  using a SQL UNION under the hood, with full support for joins, preloading and eager
+  loading on the union association, as well as through-union associations.
 email:
 - oss@keygen.sh
 executables: []
@@ -53,6 +123,16 @@ files:
 - README.md
 - SECURITY.md
 - lib/union_of.rb
+- lib/union_of/association.rb
+- lib/union_of/builder.rb
+- lib/union_of/macro.rb
+- lib/union_of/preloader.rb
+- lib/union_of/preloader/association.rb
+- lib/union_of/railtie.rb
+- lib/union_of/readonly_association.rb
+- lib/union_of/readonly_association_proxy.rb
+- lib/union_of/reflection.rb
+- lib/union_of/scope.rb
 - lib/union_of/version.rb
 homepage: https://github.com/keygen-sh/union_of
 licenses:
@@ -76,6 +156,6 @@ requirements: []
 rubygems_version: 3.4.13
 signing_key: 
 specification_version: 4
-summary: Define associations that are a union of other associations on an Active Record
-  model, using a SQL UNION.
+summary: Create associations that combine multiple Active Record associations using
+  a SQL UNION under the hood.
 test_files: []