activerecord-sort 6.1.0.1 → 10.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24b933e7b9456dfe06da3a8da7a20ad8bf7b03043c81667021dbdafc8f6b9cf4
-  data.tar.gz: 77347b9a5f294de607d485598b2c41305e66b2932debec47da84ded5cca9772d
+  metadata.gz: 55d032ac200c1f9c9bc9a06f988d54744427dcb2afbb2d0f82e89b7f7e6f32de
+  data.tar.gz: 5e10e73498fb36d17d579f9610a79d54ff254b3e36eb5940f9971e5538f15300
 SHA512:
-  metadata.gz: 41524ce760cfbf7f8bdb93bd5688c149e553a277b615d45c240939d8c51541c6d34660ccf8ad681ce78aeececcf86995b62ab20fd10797f5440115b88767acd6
-  data.tar.gz: f2098644c9201456b82899f1b621f8348a140bee47d6db7e4780ca4273b2ee47061771c535905d727a70195d4b20fc3da2c02181396bfcf84c1e645a739ef73c
+  metadata.gz: 91149455ebd6e9bf3f44b78a4e249c11335ca900923898dc4b90a10113b00276ab44dbe6412f58829f41aa40a04b3d664238e261633c8d3efcfee9087480d78f
+  data.tar.gz: 6e8028be2e9a156bd5a36ff0fc566121b2313aaa4aa48a51b48e41d344f7f59f10837f7c4cdee2fc8a98c763e8962b6fe9a406d560c77f482b26dc4c03651248

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## 10.0.0.rc1 (July 15, 2026)
+
+Starting with this release the gem is versioned independently of Rails,
+following [semantic versioning](https://semver.org). Earlier releases
+(6.x) tracked the minimum supported Rails version; the jump to 10 makes
+the break explicit so the version can't be misread as a Rails version.
+
+### 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::StatementInvalid` (previously sorted ascending
+  silently), matching column sorts.
+- ActiveRecord 7.1 or newer is required (previously 6.1).
+
+### Added
+
+- Sorting by `has_and_belongs_to_many` relations.
+- 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`.

data/README.md

@@ -40,18 +40,34 @@ Property.sort(id: {asc: :nulls_last})
 # => "...ORDER BY properties.id ASC NULLS LAST"
 ```
 
-It can also sort on relations:
+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:
 
 ```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_frist}}).to_sql
-# => "...INNER JOIN addresses ON addresses.property_id = properties.id
-# => "   ORDER BY addresses.id ASC NULLS FIRST"
+Property.sort(addresses: {id: {asc: :nulls_first}}).to_sql
+# => "...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.

data/ext/active_record/base.rb

@@ -0,0 +1,173 @@
+require 'active_record'
+require 'active_record/relation'
+
+module ActiveRecord
+  module QueryMethods
+  # class << self
+
+    # ordering:
+    # :id
+    # :name, :id
+    # :id => :desc
+    # :id => {:desc => :nulls_last}
+    # :listings => :id
+    # :listings => {:id => {:asc => :nulls_first}}
+    # :random
+    def sort(*ordering)
+      resource = all
+      ordering.compact!
+      ordering.flatten!
+      return resource if ordering.size == 0
+
+      ordering.each do |order|
+        order = Array(order)
+        order.each do |column_or_relation, options|
+          if column_or_relation.to_sym == :random
+            resource = resource.random_sort
+          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)
+          else
+            raise ActiveRecord::StatementInvalid.new("Unkown column #{column_or_relation}")
+          end
+        end
+      end
+
+      resource
+    end
+    
+    def random_sort
+      self.order(Arel::Nodes::RandomOrdering.new)
+    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, nulls = sort_direction_and_nulls(options)
+
+      if direction == :desc
+        self.order(Arel::Nodes::Descending.new(column, nulls))
+      elsif direction == :asc
+        self.order(Arel::Nodes::Ascending.new(column, nulls))
+      else
+        raise ActiveRecord::StatementInvalid.new("Unkown ordering #{direction}")
+      end
+    end
+
+    # 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)
+
+      if relation.macro == :has_many || relation.macro == :has_and_belongs_to_many
+        options = [options] if !options.is_a?(Array)
+
+        options.each do |order|
+          Array(order).each do |column_name, options|
+            # LEFT JOIN the collection, 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.
+            column = Arel::Attributes::Relation.new(relation.klass.arel_table[column_name], relation.name)
+            direction, nulls = sort_direction_and_nulls(options)
+
+            order = if direction == :desc
+              Arel::Nodes::Descending.new(column.maximum, nulls)
+            elsif direction == :asc
+              Arel::Nodes::Ascending.new(column.minimum, nulls)
+            else
+              raise ActiveRecord::StatementInvalid.new("Unkown ordering #{direction}")
+            end
+
+            resource = resource.left_outer_joins(relation.name)
+            resource = resource.order(order)
+          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]
+            direction, nulls = sort_direction_and_nulls(options)
+
+            if direction == :desc
+              order = Arel::Nodes::Descending.new(column.maximum, nulls)
+            elsif direction == :asc
+              order = Arel::Nodes::Ascending.new(column.minimum, nulls)
+            else
+              raise ActiveRecord::StatementInvalid.new("Unkown ordering #{direction}")
+            end
+
+            resource = resource.left_outer_joins(relation.name)
+            resource = resource.order(order)
+          end
+        end
+      end
+
+      resource = resource.group(klass.arel_table[klass.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 = '6.1.0.1'
+    VERSION = '10.0.0.rc1'
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-sort
 version: !ruby/object:Gem::Version
-  version: 6.1.0.1
+  version: 10.0.0.rc1
 platform: ruby
 authors:
 - Jon Bracy
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: arel-extensions
   requirement: !ruby/object:Gem::Requirement
@@ -112,18 +111,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:
     - - ">="
@@ -137,35 +136,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: 6.1.0.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 6.1.0.2
 - !ruby/object:Gem::Dependency
-  name: sunstone
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0.2
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0.2
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: webmock
+  name: debug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -187,15 +186,16 @@ extensions: []
 extra_rdoc_files:
 - README.md
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
+- ext/active_record/base.rb
 - lib/active_record/sort.rb
 - lib/active_record/sort/version.rb
 homepage: https://github.com/malomalo/activerecord-sort
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options:
 - "--main"
 - README.md
@@ -205,15 +205,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key:
+rubygems_version: 4.0.2
 specification_version: 4
 summary: A safe way to accept user parameters and order against your ActiveRecord
   Models