association_scope 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67d2f037f4c3007105757fe5b90f5307eb56614979e7cd4fa83d9036b5584321
-  data.tar.gz: d775072058420799584cf18dc27d80c246070dfd2ae1246e084f0a25acf3aa44
+  metadata.gz: '0059e9dbe18df446d6d2e2052bfac18e55a2a63bc80cc3fdb8b1b7c1857de712'
+  data.tar.gz: 1cb46137b1e72f91cf131aa03961566deee85425e231cf68c9d8b47db4acdcdb
 SHA512:
-  metadata.gz: 5aa81882d47e6207b82deb659f43f3010e83d985fe1bed9a411e29c5796082509c4d19f4435bfdbb9d8a636878c06ac3dde49e7543bf5f7b7db38ec4583d0504
-  data.tar.gz: 22d3f940c21d6e1722eef994d0294a80d6e3f80a87a3bbadba1f457f1eeb6ef54fecc6ef3c9d761100213dcdc669f04c5f242cc8e95f4546151639f15727eb25
+  metadata.gz: ad2173c80fc92258f0c559c5a4fd6314ed3c7fafe8ea1f9c50824df7434d8c130a828e3d2575786d31558d6d6f11b0b2583506f463d5283807e1d1f12ff13f81
+  data.tar.gz: 8ade7d8c45150524d87740fe69759199f0263054cc6184e1a93a5fba14acd5654df02d9967d1761b864b540d09be93aabd90b910a4c39b86b9664cbb16c3ed8e

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 1.0.0 - 2026-09-10
+
+### Changed
+
+- Support is now limited to Ruby 3.2 through 4.0 and Rails 7.1 or newer.
+- The development and test dependencies are pinned and the CI suite explicitly
+  tests the supported Ruby, Rails, and database adapter versions (SQLite and
+  PostgreSQL).
+
+### Fixed
+
+- Preserve scoped `belongs_to`, through, and HABTM association predicates.
+- Support explicit source selections and self-referential `belongs_to` scopes.
+- Honor custom association primary keys for direct associations.
+- Return one record per owner for `has_one :through`, preserving source order
+  and applying offsets per owner for both direct and through `has_one` scopes.
+- Exercise real queries and chaining in the installed-gem smoke test.
+
+### Documentation
+
+- Documented inverse-association requirements, generated scope naming,
+  unsupported options, upgrade notes, and verification commands.
+
+### Upgrade notes
+
+- Upgrade to Ruby 3.2 or newer and Rails 7.1 or newer before updating the gem.
+- Replace polymorphic `belongs_to` association scopes with explicit application
+  scopes; they are not supported.
+- Association scopes now require the corresponding inverse association on the
+  target model. Add `inverse_of` when Rails cannot infer that association.
+- `has_association_scope_on` accepts only an association name or an array of
+  association names. It does not accept `only:` or `except:` options.
+
+## 0.4.0 - 2021-11-12
+
+### Added
+
+- Polymorphic association behavior and test coverage.
+
+## 0.3.3 - 2021-11-12
+
+### Changed
+
+- Updated development dependencies and CI configuration.
+
+## 0.3.0
+
+See the [v0.3.0 release](https://github.com/datae95/association_scope/tree/v0.3.0)
+for the changes in this release.

data/README.md

@@ -57,6 +57,40 @@ Topic.all.users
 ```
 to retrieve the users of all of the topics of your application.
 
+The argument must be an array of association names.
+Each generated relation scope uses the pluralized association name: `:user`
+creates `.users`, and `:profile` creates `.profiles`. Names must be unique
+after pluralization and must not already be defined as class methods/scopes.
+There is no `only:` or `except:` option; list exactly the associations to
+expose.
+
+### Inverse associations
+
+The association must have a matching inverse association on its target model.
+AssociationScope uses that inverse to construct the join. Define both sides
+before calling `has_association_scope_on`, and use `inverse_of` when the inverse
+cannot be inferred (for example, with a custom `class_name` or `source`):
+
+```ruby
+class Topic < ApplicationRecord
+  belongs_to :user, inverse_of: :topics
+  has_association_scope_on [:user]
+end
+
+class User < ApplicationRecord
+  has_many :topics, inverse_of: :user
+end
+```
+
+### Supported association types
+
+`has_association_scope_on` supports `belongs_to`, `has_one`, `has_many`,
+`has_many :through`, `has_one :through`, and `has_and_belongs_to_many`
+associations. Polymorphic `has_many` associations (for example,
+`has_many :pictures, as: :imageable`) are supported. A polymorphic
+`belongs_to` association is not supported because its target model cannot be
+determined when the scope is defined.
+
 ### Migration from `.of_model`
 When you already use any form of `.of_model` scope, you can replace it with association scopes:
 
@@ -74,8 +108,8 @@ scope.of_users(users)
 users.topics.merge(scope)
 ```
 
-## Known Issues
-* This gem works with `reflections`.
+## Limitations
+* This gem works with Active Record `reflections`.
 To make this work, the `has_association_scope_on` call has to be below your association definitions.
 ```ruby
 # won't work
@@ -95,9 +129,40 @@ end
 Workaround: Migrate JSON columns to JSONB.
 * Error messages are not raised during application start, but on first instantiation, because of the order in which classes are loaded.
 
+## Compatibility
+
+The gem supports Ruby 3.2 through 4.0 and Rails 7.1 or newer. The CI matrix
+tests Rails 7.1, 7.2, 8.0, and 8.1 on each supported Ruby version, using both
+SQLite and PostgreSQL.
+
+The test suite supports SQLite and PostgreSQL. PostgreSQL is recommended when
+using `distinct` with JSON-valued columns; SQLite does not provide the same
+JSON type behavior.
+
+### Upgrade notes
+
+Version 1.0 drops support for Ruby versions before 3.2 and Rails versions
+before 7.1. Upgrade Ruby and Rails first, then run `bundle update
+association_scope`. If you previously relied on a polymorphic `belongs_to`
+association scope, replace it with an explicit application scope; that
+association type is intentionally rejected. Also ensure every exposed
+association has an inverse on its target model and remove unsupported
+`only:`/`except:` arguments.
+
 ## Development
 Clone this repository and run `bundle`.
+
+The development Ruby version is 3.4.7. See [Compatibility](#compatibility) for
+the supported runtime versions.
+
 To use `rails console` you have to navigate to the dummy application 
 ```bash
 $ cd spec/dummy
 ```
+
+### Verification
+
+Run the test suite with `bundle exec rake` (or `bundle exec rspec`). Check
+formatting with `bundle exec standardrb` and dependencies with
+`bundle exec bundler-audit check --update`. The CI matrix additionally runs
+the suite on the supported Ruby/Rails combinations with SQLite and PostgreSQL.

data/Rakefile

@@ -4,12 +4,11 @@ require "bundler/setup"
 
 require "bundler/gem_tasks"
 
-require "rake/testtask"
+require "rspec/core/rake_task"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.pattern = "test/**/*_test.rb"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = "spec/**/*_spec.rb"
   t.verbose = false
 end
 
-task default: :test
+task default: :spec

data/lib/association_scope/scope/belongs_to_reflection.rb

@@ -9,43 +9,34 @@ module AssociationScope
         end
 
         association = @association
-        class_name = reflection_details.options[:class_name]&.constantize || association.camelize.constantize
-        foreign_key = reflection_details.options[:foreign_key]
-        association_name = association.to_s.underscore.to_sym
-        own_table_name = class_name.to_s.pluralize.underscore
-        table_name = table_name class_name
-
-        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          scope association.pluralize, -> do
-            if foreign_key.present?
-              class_name
-                .joins("JOIN #{table_name} ON #{table_name}.#{foreign_key} = #{own_table_name}.id")
-            else
-              class_name
-                .joins(table_name)
-            end
-              .where(table_name => { association_name =>
-                select("#{association_name}_id".to_sym) })
-              .distinct
-          end
-        RUBY
-      end
-
-      private
+        class_name = reflection_details.klass
+        inverse_association = inverse_reflection(class_name)
 
-      def table_name(class_name)
-        case inverse_reflection(class_name)&.source_reflection&.class&.to_s&.split("::")&.last
-        when "HasOneReflection"
-          model.to_s.underscore.to_sym
-        when "HasManyReflection"
-          model.to_s.underscore.pluralize.to_sym
-        else
+        unless inverse_association
           raise AssociationMissingError.new missing_in: class_name, association: model.to_s.underscore.pluralize
         end
+
+        foreign_key = reflection_details.foreign_key
+        validate_scope!(reflection_details)
+        association_scope = reflection_details.scope
+        owner_key = model.arel_table[foreign_key]
+        target_key = class_name.arel_table[reflection_details.association_primary_key]
+
+        model.scope association.pluralize, -> do
+          Scope.target_relation(class_name, association_scope)
+            .where(target_key.in(reselect(owner_key).arel))
+            .distinct
+        end
       end
 
+      private
+
       def inverse_reflection(class_name)
-        class_name.reflections[model.to_s.underscore.singularize] || class_name.reflections[model.to_s.underscore.pluralize]
+        inverse_name = reflection_details.options[:inverse_of]
+
+        class_name.reflections[inverse_name.to_s] ||
+          class_name.reflections[model.to_s.underscore.singularize] ||
+          class_name.reflections[model.to_s.underscore.pluralize]
       end
 
       def reflection_details

data/lib/association_scope/scope/has_and_belongs_to_many_reflection.rb

@@ -5,19 +5,20 @@ module AssociationScope
     class HasAndBelongsToManyReflection < Scope
       def apply
         association = @association.pluralize
-        class_name = reflection_details.options[:class_name]&.constantize || association.singularize.camelize.constantize
-        table_name = model.to_s.underscore.pluralize.to_sym
+        class_name = reflection_details.klass
+        inverse_association = inverse_association(class_name)
+        validate_scope!(reflection_details)
+        association_scope = reflection_details.scope
+        owner_table = model.table_name
 
-        raise AssociationMissingError.new(missing_in: class_name, association: table_name) unless class_name.reflections.has_key?(table_name.to_s)
+        raise AssociationMissingError.new(missing_in: class_name, association: model.table_name) unless inverse_association
 
-        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          scope association, -> do
-            class_name
-              .joins(table_name)
-              .where(table_name => self)
-              .distinct
-          end
-        RUBY
+        model.scope association, -> do
+          Scope.target_relation(class_name, association_scope)
+            .joins(inverse_association)
+            .where(owner_table => self)
+            .distinct
+        end
       end
 
       private
@@ -25,6 +26,14 @@ module AssociationScope
       def reflection_details
         model.reflections[association]
       end
+
+      def inverse_association(class_name)
+        class_name.reflections.values.find do |reflection|
+          reflection.macro == :has_and_belongs_to_many &&
+            reflection.klass == model &&
+            reflection.join_table == reflection_details.join_table
+        end&.name
+      end
     end
   end
 end

data/lib/association_scope/scope/has_many_reflection.rb

@@ -4,20 +4,30 @@ module AssociationScope
   class Scope
     class HasManyReflection < Scope
       def apply
-        class_name = reflection_details.options[:class_name]&.constantize || association.singularize.camelize.constantize
+        class_name = reflection_details.klass
 
         association = @association.pluralize
         column_name = reflection_details.options[:as] || model.to_s.underscore
+        inverse_association = inverse_reflection(class_name, column_name)
 
-        raise AssociationMissingError.new(missing_in: class_name, association: column_name) unless class_name.reflections.has_key?(column_name.to_s)
+        raise AssociationMissingError.new(missing_in: class_name, association: column_name) unless inverse_association
 
-        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          scope association, -> do
-            class_name
-              .where(column_name => self)
-              .distinct
-          end
-        RUBY
+        association_scope = reflection_details.scope
+        validate_scope!(reflection_details)
+        polymorphic = reflection_details.options[:as]
+        foreign_key = reflection_details.foreign_key
+        owner_key = model.arel_table[reflection_details.active_record_primary_key]
+        target_key = class_name.arel_table[foreign_key]
+        foreign_type = reflection_details.type if polymorphic
+        owner_type = model.polymorphic_name if polymorphic
+        singular = reflection_details.macro == :has_one
+
+        model.scope association, -> do
+          relation = Scope.target_relation(class_name, association_scope)
+            .where(target_key.in(reselect(owner_key).arel))
+          relation = relation.where(foreign_type => owner_type) if polymorphic
+          singular ? Scope.one_per_owner(relation, target_key) : relation.distinct
+        end
       end
 
       private
@@ -25,6 +35,12 @@ module AssociationScope
       def reflection_details
         model.reflections[@association]
       end
+
+      def inverse_reflection(class_name, column_name)
+        inverse_name = reflection_details.options[:inverse_of]
+
+        class_name.reflections[inverse_name.to_s] || class_name.reflections[column_name.to_s]
+      end
     end
   end
 end

data/lib/association_scope/scope/through_reflection.rb

@@ -5,19 +5,49 @@ module AssociationScope
     class ThroughReflection < Scope
       def apply
         association = @association
-        class_name = reflection_details.options[:class_name]&.constantize || association.singularize.camelize.constantize
-        first_join = inverse_reflection(class_name)&.options&.fetch(:through, nil) || inverse_reflection(class_name)&.options&.fetch(:source, nil)
-        second_join = compute_second_join class_name
+        class_name = begin
+          reflection_details.klass
+        rescue ActiveRecord::AmbiguousSourceReflectionForThroughAssociation
+          # Rails cannot resolve an omitted source when multiple source
+          # reflections exist; retain the historical association-name
+          # fallback for this inherently ambiguous case.
+          association.singularize.camelize.constantize
+        end
+        source = begin
+          reflection_details.source_reflection
+        rescue ActiveRecord::AmbiguousSourceReflectionForThroughAssociation
+          nil
+        end
+        validate_scope!(reflection_details)
+        source ||= reflection_details.through_reflection.klass.reflections.values.find do |candidate|
+          candidate.name.to_s == association.to_s && candidate.klass == class_name && candidate.through_reflection?
+        end
+        if source&.through_reflection?
+          first_join = source.options[:through]
+          second_join = reflection_details.options[:through].to_sym
+        else
+          first_join = inverse_reflection(class_name)&.options&.fetch(:through, nil) || inverse_reflection(class_name)&.options&.fetch(:source, nil)
+          second_join = compute_second_join class_name
+        end
 
         raise AssociationMissingError.new missing_in: class_name, association: inverse unless inverse_reflection(class_name)
+        through_reflection = reflection_details.through_reflection
+        through_table = through_reflection.klass.table_name
+        through_key = through_reflection.belongs_to? ? through_reflection.association_primary_key : through_reflection.foreign_key
+        source_key = through_reflection.belongs_to? ? through_reflection.foreign_key : through_reflection.active_record_primary_key
+        owner_key = model.arel_table[source_key]
+        partition_key = through_reflection.klass.arel_table[through_key]
+        association_scope = reflection_details.scope
+        source_scope = source&.scope
+        validate_scope!(source) if source
+        singular = reflection_details.macro == :has_one
 
-        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          scope association.pluralize, -> do
-            class_name
-              .joins(first_join => second_join)
-              .distinct
-          end
-        RUBY
+        model.scope association.pluralize, -> do
+          relation = Scope.target_relation(class_name, source_scope, association_scope)
+            .joins(first_join => second_join)
+            .where(through_table => {through_key => reselect(owner_key)})
+          singular ? Scope.one_per_owner(relation, partition_key) : relation.distinct
+        end
       end
 
       private

data/lib/association_scope/scope.rb

@@ -10,11 +10,58 @@ module AssociationScope
     end
 
     def self.inject_scopes(model, reflections)
+      unknown_association = reflections.find { |association| !model.reflections.key?(association) }
+      if unknown_association
+        raise AssociationMissingError.new(missing_in: model, association: unknown_association)
+      end
+
+      generated_scopes = reflections.map(&:pluralize)
+      if generated_scopes.uniq.length != generated_scopes.length
+        raise ArgumentError, "association scope names must be unique after pluralization"
+      end
+
+      generated_scopes.each do |scope_name|
+        if model.respond_to?(scope_name)
+          raise ArgumentError, "association scope :#{scope_name} is already defined on #{model}"
+        end
+      end
+
       model.reflections.slice(*reflections).each do |association, details|
         scope_type = details.class.to_s.split("::").last
+        scope_type = "HasManyReflection" if scope_type == "HasOneReflection"
 
         "AssociationScope::Scope::#{scope_type}".constantize.new(model, association).apply
       end
     end
+
+    def self.target_relation(klass, *scopes)
+      # Start independently of the owners' current scope, including for self joins.
+      scopes.compact.reduce(klass.default_scoped) do |relation, scope|
+        relation.instance_exec(&scope) || relation
+      end
+    end
+
+    def self.one_per_owner(relation, owner_key)
+      klass = relation.klass
+      table = klass.arel_table
+      orders = relation.arel.orders.presence || [table[klass.primary_key].asc]
+      window = Arel::Nodes::Window.new.partition(owner_key).order(*orders)
+      row_number = Arel::Nodes::NamedFunction.new("ROW_NUMBER", []).over(window)
+      ranked = relation.except(:select, :order, :limit, :offset, :distinct)
+        .select(table[Arel.star], row_number.as("association_scope_row_number"))
+
+      # Keep ordering inside the window so offsets select a record for each owner.
+      result = klass.unscoped.from(ranked, klass.table_name)
+        .where(table[:association_scope_row_number].eq(relation.offset_value.to_i + 1))
+        .distinct
+      relation.select_values.any? ? result.select(*relation.select_values) : result
+    end
+
+    private
+
+    def validate_scope!(reflection)
+      scope = reflection.scope
+      raise ArgumentError, "owner-dependent association scopes are not supported" if scope && scope.arity != 0
+    end
   end
 end

data/lib/association_scope/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AssociationScope
-  VERSION = "0.4.0"
+  VERSION = "1.0.0"
 end

data/lib/association_scope.rb

@@ -3,7 +3,6 @@
 require "association_scope/version"
 require "association_scope/scope"
 require "association_scope/scope/has_many_reflection"
-require "association_scope/scope/has_one_reflection"
 require "association_scope/scope/belongs_to_reflection"
 require "association_scope/scope/has_and_belongs_to_many_reflection"
 require "association_scope/scope/through_reflection"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: association_scope
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - datae
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,56 +15,56 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.6
+        version: '1.56'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.6
+        version: '1.56'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.26
+        version: 0.9.37
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.26
+        version: 0.9.37
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: awesome_print
   requirement: !ruby/object:Gem::Requirement
@@ -80,13 +79,29 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.9.2
-description: AssociationScope adds useful scopes targeting Associations in ActiveRecord.
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: AssociationScope lets Active Record relations expose associations as
+  chainable scopes.
 email:
 - accounts@datae.de
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -97,17 +112,15 @@ files:
 - lib/association_scope/scope/belongs_to_reflection.rb
 - lib/association_scope/scope/has_and_belongs_to_many_reflection.rb
 - lib/association_scope/scope/has_many_reflection.rb
-- lib/association_scope/scope/has_one_reflection.rb
 - lib/association_scope/scope/through_reflection.rb
 - lib/association_scope/version.rb
 homepage: https://github.com/datae95/association_scope
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/datae95/association_scope
+  homepage_uri: https://github.com/datae95/association_scope#readme
   source_code_uri: https://github.com/datae95/association_scope
-  changelog_uri: https://github.com/datae95/association_scope/changelog
-post_install_message: 
+  changelog_uri: https://github.com/datae95/association_scope/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -115,15 +128,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.8
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.25
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
-summary: AssociationScope adds useful scopes targeting Associations in ActiveRecord.
+summary: Chain Active Record associations from relation scopes.
 test_files: []

data/lib/association_scope/scope/has_one_reflection.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module AssociationScope
-  class Scope
-    class HasOneReflection < HasManyReflection
-      # works the same way like has_many reflections
-    end
-  end
-end