activerecord-sort 7.0.0 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec46a72d471b80abc582726404812b56fb9a89176349d5609b9734a6227c4c61
-  data.tar.gz: dd93e9fd01692c8113898c9c34aac125af3288a8b4d92d0be047660f396ace24
+  metadata.gz: 50d689663cb6717dab8e034f88d8645cf24a31489e322ca79d9cd52634281dc4
+  data.tar.gz: 544297bd2fc5b8322f8a719d3a4f52e235681a1c756dc191ac74fd69a4c556a7
 SHA512:
-  metadata.gz: 56688dd4bc023b5098de0792f27309452dd85d46bf56f905ae771b9ff3154d5c0ef5c9348a52e363b3a4ed20987805eb7f1e66384faf4eca40429ac126eb15ec
-  data.tar.gz: 8950bc656939f09fb886d5c917fb12a295a3da80d6d79a59ffde629a909c82a335aea17ce3cb5fbaceb4c1e5925261e11e536853321c89e58896dca9c66e2cff
+  metadata.gz: b0caa63a30b528ed30f2fa2ff5c29fe779fd633e9d30ec4404ede2c8b08f9a24a1832b3bd4bd10c39914bebe07cfd8fe23b10ce93496b254d6bb81d2450a3c9e
+  data.tar.gz: afc2f2911285ed3e681a39013013ad1b9ffbce9161a4ac5bb2da6fda40ddd03421942f3b42eaf0c0a3865878fe667759d4c77df0b8962b431937267be40a9d70

data/CHANGELOG.md

@@ -1,4 +1,74 @@
-## [7.0.0]
+# Changelog
+
+## [8.0.0] - 2026-08-27
+
+### Breaking changes
+
+- Relation sorts are unified across association types. Sorting by any
+  relation (`has_many`, `has_and_belongs_to_many`, `has_one`,
+  `belongs_to`) now `LEFT OUTER JOIN`s the association, groups by the
+  sorted table's primary key, and orders by an aggregate of the requested
+  column. For `has_many` sorts this changes behavior:
+  - each record is returned once, instead of once per associated row
+    (the join no longer fans out into duplicates)
+  - records with no associated rows are included (previously dropped by
+    the `INNER JOIN`)
+- Descending relation sorts key each record by its largest member
+  (`MAX`), ascending by its smallest (`MIN`) — the member you'd expect
+  to see first in that direction. For records with multiple associated
+  rows, descending is therefore not the reverse of ascending: a record
+  holding both extremes sorts first in both directions.
+- Sort columns are no longer added to the `SELECT`:
+  - loaded records keep their own attributes — a joined sort column can
+    no longer overwrite a same-named attribute on the base record
+    (previously even `id` could be clobbered)
+  - `pluck` and `ids` keep the sort (previously raised on
+    `has_and_belongs_to_many` sorts)
+  - a caller's `select` is left untouched
+  - chaining `.distinct` after a relation sort now raises: PostgreSQL
+    requires `ORDER BY` expressions to appear in the select list for
+    `SELECT DISTINCT`. It previously appeared to work while silently
+    deduplicating over the wrong tuple.
+- A bare `belongs_to`/`has_one` sort with no direction (e.g.
+  `Address.sort(property: :name)`) now defaults to ascending, matching
+  every other sort form (previously descending).
+- An unknown sort direction on a relation sort (e.g. `:dsc`) now raises
+  `ActiveRecord::Sort::InvalidSort` (previously sorted ascending
+  silently), matching column sorts.
+
+### Added
+
+- Sorting by `has_and_belongs_to_many` relations.
+- Unrecognized sort columns, associations, and directions raise
+  `ActiveRecord::Sort::InvalidSort`, a subclass of
+  `ActiveRecord::StatementInvalid` — so existing
+  `rescue ActiveRecord::StatementInvalid` handlers still catch bad sort
+  parameters, while callers can rescue the narrower class. Relation sort
+  columns are now validated up front (against the associated model's
+  columns) instead of only failing once the query reaches the database.
+- Sorts of different types compose: they can be combined in one call
+  (`Property.sort(:name, tags: :name, addresses: :id)`) or chained
+  (`.sort(...).sort(...)`), sharing a single `GROUP BY`.
+- Aggregates on a sorted relation (`count`, `sum`, `average`, `minimum`,
+  `maximum`) are computed over the records themselves rather than the
+  sort's grouped, joined rows — `count` returns the record count instead
+  of a per-group `Hash`, and multi-member records aren't weighted once
+  per member. A caller-supplied `group` still gets standard grouped
+  results.
+- A blank direction (`''`, as query parameters often produce) is
+  accepted as ascending on all sort forms.
+- `ActionController::Parameters` are accepted for relation sorts, and
+  their nulls option (`nulls_first`/`nulls_last`) is honored.
+
+### Fixed
+
+- `has_and_belongs_to_many` sorts crashed with `NoMethodError` on
+  ActiveRecord <= 8.0 (`Function#as` mutates and returns the receiver
+  there).
+- Combining a `has_and_belongs_to_many` sort with another relation sort
+  raised `PG::GroupingError`.
+
+## [7.0.0] - 2026-08-27
 
 The gem's version is now independent of the Rails version it targets.
 
@@ -25,4 +95,5 @@ The gem's version is now independent of the Rails version it targets.
   `ActiveRecord::QueryMethods.public_instance_methods(false)` — which keeps
   Rails' internal delegation invariants intact.
 
+[8.0.0]: https://github.com/malomalo/activerecord-sort/releases/tag/v8.0.0
 [7.0.0]: https://github.com/malomalo/activerecord-sort/releases/tag/v7.0.0

data/README.md

@@ -50,22 +50,41 @@ Property.sort(id: {asc: :nulls_last}).to_sql
 # => "...ORDER BY properties.id ASC NULLS LAST"
 ```
 
-It can also sort on associations:
+It can also sort on relations. A relation sort groups by the sorted table's
+primary key — so each record appears once and records with no associated
+rows are still included — and orders by an aggregate of the requested
+column: `MIN` ascending or `MAX` descending, keying each record by the
+member you'd expect to see first in that direction. A record with no
+associated rows has a `NULL` sort key; where `NULL`s land is
+database-dependent, so pass `nulls_first`/`nulls_last` to place those
+records explicitly:
 
 ```ruby
 Property.sort(addresses: :id).to_sql
-# => "...INNER JOIN addresses ON addresses.property_id = properties.id
-# => "   ORDER BY addresses.id ASC"
+# => "SELECT properties.* FROM properties
+# => "   LEFT OUTER JOIN addresses ON addresses.property_id = properties.id
+# => "   GROUP BY properties.id
+# => "   ORDER BY MIN(addresses.id) ASC"
 
 Property.sort(addresses: {id: :desc}).to_sql
-# => "...INNER JOIN addresses ON addresses.property_id = properties.id
-# => "   ORDER BY addresses.id DESC"
+# => "...ORDER BY MAX(addresses.id) DESC"
 
 Property.sort(addresses: {id: {asc: :nulls_first}}).to_sql
-# => "...INNER JOIN addresses ON addresses.property_id = properties.id
-# => "   ORDER BY addresses.id ASC NULLS FIRST"
+# => "...ORDER BY MIN(addresses.id) ASC NULLS FIRST"
+
+Property.sort(tags: :name).to_sql # has_and_belongs_to_many
+# => "SELECT properties.* FROM properties
+# => "   LEFT OUTER JOIN properties_tags ON properties_tags.property_id = properties.id
+# => "   LEFT OUTER JOIN tags ON tags.id = properties_tags.tag_id
+# => "   GROUP BY properties.id
+# => "   ORDER BY MIN(tags.name) ASC"
 ```
 
+A relation sort is order-only — it never adds or removes records — so
+aggregates on a sorted relation (`count`, `sum`, `average`, `minimum`,
+`maximum`) are computed over the records themselves, not the sort's
+grouped and joined rows.
+
 Order randomly:
 
 ```ruby
@@ -77,9 +96,13 @@ Unrecognized columns raise, so unfiltered params can't inject SQL:
 
 ```ruby
 Property.sort(:name_or_something_unexpected)
-# => raises ActiveRecord::StatementInvalid
+# => raises ActiveRecord::Sort::InvalidSort
 ```
 
+`ActiveRecord::Sort::InvalidSort` subclasses `ActiveRecord::StatementInvalid`,
+so existing `rescue ActiveRecord::StatementInvalid` handlers keep catching bad
+sort parameters, while callers that want to can rescue the narrower class.
+
 Called with no arguments, `#sort` behaves like Ruby's `Enumerable#sort` —
 it loads the records and sorts them by `<=>` — rather than building a query:
 

data/ext/active_record/base.rb

@@ -8,6 +8,15 @@ module ActiveRecord
   # delegation tests assert against — while relations still respond to them.
   module Sort
 
+    # Raised when a sort references an unrecognized column or association,
+    # or an unknown direction. Subclasses StatementInvalid so existing
+    # `rescue ActiveRecord::StatementInvalid` handlers — the safety
+    # contract that makes it OK to pass request params straight through —
+    # keep working, while callers can rescue this narrower class to tell a
+    # bad sort parameter apart from a genuine database error.
+    class InvalidSort < ActiveRecord::StatementInvalid
+    end
+
     # ordering:
     # :id
     # :name, :id
@@ -29,7 +38,6 @@ module ActiveRecord
       ordering.flatten!
       return resource if ordering.size == 0
 
-      order_columns = []
       ordering.each do |order|
         order = Array(order)
         order.each do |column_or_relation, options|
@@ -38,97 +46,138 @@ module ActiveRecord
           elsif self.column_names.include?(column_or_relation.to_s)
             resource = resource.sort_for_column(self.arel_table[column_or_relation.to_s], options)
           elsif reflect_on_association(column_or_relation.to_sym)
-            resource = resource.sort_for_relation(column_or_relation.to_sym, options, order_columns)
+            resource = resource.sort_for_relation(column_or_relation.to_sym, options)
           else
-            raise ActiveRecord::StatementInvalid.new("Unkown column #{column_or_relation}")
+            raise InvalidSort.new("Unknown column #{column_or_relation}")
           end
         end
       end
-      
-      if order_columns.present?
-        resource = resource.select(resource.klass.arel_table[Arel::Nodes::SqlLiteral.new('*')], *order_columns)
-      end
 
       resource
     end
 
+    # Normalizes per-column sort options into [direction, nulls]. A blank
+    # direction — a bare column, or "" as query params often produce —
+    # means :asc.
     # TODO: probably don't need to cast to sym
+    def sort_direction_and_nulls(options)
+      if options.is_a?(Hash) || options.class.name == "ActionController::Parameters"
+        [options.keys.first.to_sym, options.values.first.to_sym]
+      elsif options.blank?
+        [:asc, nil]
+      else
+        [options.to_s.downcase.to_sym, nil]
+      end
+    end
+
     def sort_for_column(column, options)
-      direction = (options.is_a?(Hash) || options.class.name == "ActionController::Parameters" ? options.keys.first.to_sym : options.to_s.downcase.to_sym)
+      direction, nulls = sort_direction_and_nulls(options)
 
-      nulls = (options.is_a?(Hash) ? options.values.first.to_sym : nil)
       if direction == :desc
         self.order(Arel::Nodes::Descending.new(column, nulls))
-      elsif direction == :asc || direction == :''
+      elsif direction == :asc
         self.order(Arel::Nodes::Ascending.new(column, nulls))
       else
-        raise ActiveRecord::StatementInvalid.new("Unkown ordering #{direction}")
+        raise InvalidSort.new("Unknown ordering #{direction}")
       end
     end
 
-    def sort_for_relation(relation, options, order_columns)
+    # The sort key lives only in the ORDER BY — nothing is added to the
+    # select list. That keeps the ORDER BY self-contained (so pluck/ids,
+    # which replace the select list, keep the sort), leaves the caller's
+    # select untouched, and means loaded records carry exactly their own
+    # attributes (a selected join column would overwrite a same-named
+    # attribute on the base table).
+    def sort_for_relation(relation, options)
       resource = self
       relation = reflect_on_association(relation)
+      options = [options] if !options.is_a?(Array)
+
+      # LEFT JOIN the association, group by this table's primary key — so
+      # rows don't fan / duplicate and records with an empty collection
+      # still appear — and order by an aggregate of the requested column:
+      #
+      #   SELECT properties.*
+      #   FROM properties
+      #   LEFT JOIN properties_tags ON properties_tags.property_id = properties.id
+      #   LEFT JOIN tags ON tags.id = properties_tags.tag_id
+      #   GROUP BY properties.id
+      #   ORDER BY MIN(tags.name) ASC
+      #
+      # Ascending keys each record by its smallest member (MIN), descending
+      # by its largest (MAX) — the member you'd expect to see first in that
+      # direction. Toggling asc/desc therefore re-keys multi-value records
+      # rather than strictly reversing the list.
+      options.each do |order|
+        Array(order).each do |column_name, column_options|
+          if !relation.klass.column_names.include?(column_name.to_s)
+            raise InvalidSort.new("Unknown column #{column_name}")
+          end
 
-      if relation.macro == :has_many
-        options = [options] if !options.is_a?(Array)
-
-        options.each do |order|
-          order = Array(order)
-          order.each do |column, options|
-            column = Arel::Attributes::Relation.new(relation.klass.arel_table[column], relation.name)
-            order_columns.push(column)
-            direction = (options.is_a?(Hash) ? options.keys.first.to_sym : options.to_s.downcase.to_sym)
-
-            nulls = (options.is_a?(Hash) ? options.values.first.to_sym : nil)
-            if direction == :desc
-              # aggregation = Arel::Nodes::Max.new([column], "max_#{relation.name}_#{column.name}")
-              # order = Arel::Nodes::Descending.new(Arel::Nodes::SqlLiteral.new("max_#{relation.name}_#{column.name}"), nulls)
-
-              if relation.options[:through]
-                resource = resource.joins(relation.options[:through] => relation.source_reflection_name)
-              else
-                resource = resource.joins(relation.name)
-              end
-              # resource = resource.select(aggregation)
-              # resource = resource.order(order)
-              resource = resource.order(Arel::Nodes::Descending.new(column, nulls))
-            else
-              # aggregation = Arel::Nodes::Min.new([column], "min_#{relation.name}_#{column.name}")
-              order = Arel::Nodes::Ascending.new(Arel::Nodes::SqlLiteral.new("min_#{relation.name}_#{column.name}"), nulls)
-
-              resource = resource.joins(relation.name)
-              # resource = resource.select(aggregation)
-              # resource = resource.order(order)
-              resource = resource.order(Arel::Nodes::Ascending.new(column, nulls))
-            end
+          # A collection (has_many / has_and_belongs_to_many) wraps the
+          # attribute in an Arel::Attributes::Relation so the aggregate
+          # references the joined table correctly; a singular association
+          # (belongs_to / has_one) uses the plain attribute.
+          column = if relation.collection?
+            Arel::Attributes::Relation.new(relation.klass.arel_table[column_name], relation.name)
+          else
+            relation.klass.arel_table[column_name]
           end
-        end
-      elsif relation.macro == :belongs_to || relation.macro == :has_one
-        options = [options] if !options.is_a?(Array)
-
-        options.each do |order|
-          order = Array(order)
-          order.each do |column, options|
-            column = relation.klass.arel_table[column]
-            order_columns.push(column)
-            direction = (options.is_a?(Hash) ? options.keys.first.to_sym : options.to_s.downcase.to_sym)
-
-            nulls = (options.is_a?(Hash) ? options.values.first.to_sym : nil)
-            if direction == :asc
-              order = Arel::Nodes::Ascending.new(column, nulls)
-            else
-              order = Arel::Nodes::Descending.new(column, nulls)
-            end
-
-            resource = resource.left_outer_joins(relation.name)
-            resource = resource.order(order)
+
+          direction, nulls = sort_direction_and_nulls(column_options)
+
+          order = if direction == :desc
+            Arel::Nodes::Descending.new(column.maximum, nulls)
+          elsif direction == :asc
+            Arel::Nodes::Ascending.new(column.minimum, nulls)
+          else
+            raise InvalidSort.new("Unknown ordering #{direction}")
           end
+
+          resource = resource.left_outer_joins(relation.name)
+          resource = resource.order(order)
         end
       end
 
+      # Group by the primary key so the aggregate collapses the joined,
+      # fanned-out rows to one per record. Every relation sort adds this,
+      # so only add it once: ActiveRecord < 8.1's group! appends rather
+      # than unioning, which would leave a duplicate [pk, pk] that trips
+      # the count override's group_values check below.
+      # TODO: once Rails <= 8.0 is no longer supported, group! unions on
+      # its own — drop the include? guard and just group(primary_key).
+      primary_key = klass.arel_table[klass.primary_key]
+      resource = resource.group(primary_key) unless resource.group_values.include?(primary_key)
+      # Tag the relation for the count override below. Chained relations
+      # are built with clone, which copies instance variables, so the tag
+      # survives further chaining.
+      resource.instance_variable_set(:@sorted_by_relation, true)
       resource
     end
 
   end
+
+  module Sort
+    module Calculations
+      # sort_for_relation groups by the primary key and LEFT JOINs the
+      # relation, so aggregates would see grouped, fanned-out rows: count
+      # returns a per-group Hash, and sum/average weigh a record once per
+      # collection member. But a relation sort is order-only — records are
+      # never added or removed — so every aggregate has a well-defined
+      # answer: compute it over the base table restricted to the sorted
+      # relation's (distinct) primary keys. User joins and conditions still
+      # apply inside the subquery, and a user-added group falls through to
+      # the standard grouped behavior.
+      def calculate(operation, column_name)
+        if @sorted_by_relation && group_values == [klass.arel_table[klass.primary_key]]
+          klass.where(klass.primary_key => unscope(:group, :order, :select).select(klass.primary_key))
+               .calculate(operation, column_name)
+        else
+          super
+        end
+      end
+    end
+  end
 end
+
+ActiveRecord::Relation.prepend(ActiveRecord::Sort::Calculations)

data/lib/active_record/sort/version.rb

@@ -1,5 +1,5 @@
 module ActiveRecord
   module Sort
-    VERSION = '7.0.0'
+    VERSION = '8.0.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-sort
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 8.0.0
 platform: ruby
 authors:
 - Jon Bracy
@@ -103,18 +103,18 @@ dependencies:
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0.rc5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0.rc5
 - !ruby/object:Gem::Dependency
-  name: factory_bot
+  name: faker
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -128,35 +128,35 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: faker
+  name: sunstone
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 7.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 7.0.0
 - !ruby/object:Gem::Dependency
-  name: sunstone
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: webmock
+  name: debug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="