activerecord-sort 8.0.0 → 8.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50d689663cb6717dab8e034f88d8645cf24a31489e322ca79d9cd52634281dc4
-  data.tar.gz: 544297bd2fc5b8322f8a719d3a4f52e235681a1c756dc191ac74fd69a4c556a7
+  metadata.gz: ac06d1612ad8c40162ba17e9773ff79b9d3be2808a9357cb99baa213d49366dc
+  data.tar.gz: fbe32a2fbd355362ddafe5961170dcfda5ceb45bca56753fe9e909a636d0fca8
 SHA512:
-  metadata.gz: b0caa63a30b528ed30f2fa2ff5c29fe779fd633e9d30ec4404ede2c8b08f9a24a1832b3bd4bd10c39914bebe07cfd8fe23b10ce93496b254d6bb81d2450a3c9e
-  data.tar.gz: afc2f2911285ed3e681a39013013ad1b9ffbce9161a4ac5bb2da6fda40ddd03421942f3b42eaf0c0a3865878fe667759d4c77df0b8962b431937267be40a9d70
+  metadata.gz: 9dee845ccc33507878d09c6c1b3adb31f0e01fa94b70630086fc83fff7a472aa05fec70949d747a18da0c1c97ad54cd11963d4734cc25ea04194075f9470432f
+  data.tar.gz: 8d0d7b0feb26f2ba93a20ada61308b5b363328c3d3f31466c75143c6b239cc2ea25b5c25e4eb6d67e51bd5cd03f1964ed4771f2d4e6099dd2a419f0e52c71cae

data/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## [8.1.0] - 2026-10-21
+
+### Added
+
+- `#resort`, which sorts like `#sort` but replaces any order the relation
+  already has, as `reorder` does for `order`, including the order of an
+  association's or default scope. `Property.order(:name).resort(:id)` orders
+  by `id` alone, and `resort(nil)` removes the order as `reorder(nil)` does
+  (a Rails 8.2 `default_order` still applies, as it does after
+  `reorder(nil)`).
+
+### Fixed
+
+- Aggregates on a relation sort now honor `limit` and `offset`. The
+  subquery that restricts them to the sorted records dropped the sort's
+  `GROUP BY` and `ORDER BY` but kept the `LIMIT`, so the limit applied to
+  the join's fanned-out, unordered rows: `Property.sort(addresses:
+  :id).limit(2).count` returned 1 where two records load, and `sum` added
+  up whichever records those rows happened to belong to. The subquery now
+  keeps the group and order, so it selects the same records loading would.
+- Aggregates on a relation sort no longer put back a default scope the
+  relation removed. The outer query restricting them to the sorted records
+  started from the model, re-applying its `default_scope`, so with
+  `default_scope { where(active: true) }`,
+  `Property.unscoped.sort(addresses: :id).count` counted only the active
+  records while loading returned them all. A relation that keeps its
+  default scope still counts within it.
+- Relation sorts now order by the association's own join when its table is
+  joined more than once. Rails aliases the later joins of a table — a
+  second `belongs_to` to the same model, a scoped `has_many`, a
+  self-referential association, or a table the caller already joined —
+  but the sort always named the plain table, so it silently ordered by
+  another join: `Property.joins(:landlord).sort(manager: :name)` ordered
+  by the landlord, `Property.sort(children: :name)` by each record's own
+  name, and `Property.sort(manager: :name).sort(landlord: :name)` dropped
+  the second sort as a duplicate of the first. The sort now finds the
+  alias Rails gave its join when the query is built, so it follows joins
+  added after it too. If that join has been removed (e.g.
+  `unscope(:left_outer_joins)`), building the query raises
+  `ActiveRecord::Sort::InvalidSort` instead of ordering by whichever join
+  has the table's name.
+
+## [8.0.1] - 2026-09-04
+
+### Changed
+
+- Enabled `# frozen_string_literal: true`, so the gem no longer allocates a
+  new String for each literal it evaluates.
+- An unrecognized value in the nulls position now raises
+  `ActiveRecord::Sort::InvalidSort` instead of being silently dropped.
+  `sort(:name => {:asc => :nulls_frist})` previously ordered by a plain
+  `ASC`, quietly returning results in the wrong null order; it now raises,
+  like any other unknown sort value. A blank nulls value still means "no
+  `NULLS` clause" rather than an invalid one — `""` (what query params
+  send) and `nil` (what JSON sends) are both absent, not wrong.
+
+### Fixed
+
+- Directions and nulls values are now matched case-insensitively wherever
+  they appear. `sort(:name => 'DESC')` already downcased, but the hash forms
+  did not, so `sort(:name => {'DESC' => 'NULLS_LAST'})` raised on the same
+  input the bare form accepted.
+- `sort(:name => {})` now sorts ascending instead of raising. An empty hash
+  states no direction, which is what `""` (from a query string) and `nil`
+  (from JSON) already meant; the blank check simply sat after the hash
+  check and so never saw it.
+- Sort parameters holding `nil` or a non-string key no longer raise
+  `NoMethodError`. `{"name" => {"asc" => nil}}`, `{"name" => {nil =>
+  "asc"}}` and a non-string column such as `{123 =>
+  "asc"}` — all reachable from a JSON request body, where a query string
+  would send `""` — now raise `ActiveRecord::Sort::InvalidSort`, or sort
+  normally where the value is merely absent, honoring the documented
+  contract that unfiltered params are rescuable as
+  `ActiveRecord::StatementInvalid`.
+
 ## [8.0.0] - 2026-08-27
 
 ### Breaking changes
@@ -95,5 +170,7 @@ 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.1.0]: https://github.com/malomalo/activerecord-sort/releases/tag/v8.1.0
+[8.0.1]: https://github.com/malomalo/activerecord-sort/releases/tag/v8.0.1
 [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

@@ -2,8 +2,12 @@
 
 `ActiveRecord::Sort` provides an easy, safe way to accept user input and order a
 query by it. Only recognized columns and associations produce SQL — anything
-else raises `ActiveRecord::StatementInvalid`, so it's safe to pass request
-parameters straight through.
+else raises `ActiveRecord::StatementInvalid`, so unfiltered request parameters
+can't inject SQL.
+
+Recognized is not the same as permitted, though. Every column on the model and
+on its associations is sortable, including ones you never expose — see
+[Restricting what can be sorted](#restricting-what-can-be-sorted).
 
 Requirements
 ------------
@@ -110,3 +114,66 @@ it loads the records and sorts them by `<=>` — rather than building a query:
 Property.all.sort            # => Array of Property, sorted by <=>
 Property.sort(nil)           # => relation (unchanged), for chaining
 ```
+
+Replacing an existing order
+---------------------------
+
+`#sort` adds to any order the relation already has, as `order` does.
+`#resort` replaces it, as `reorder` does, including the order of an
+association's or default scope:
+
+```ruby
+Property.order(:name).sort(:id).to_sql
+# => "...ORDER BY properties.name ASC, properties.id ASC"
+
+Property.order(:name).resort(:id).to_sql
+# => "...ORDER BY properties.id ASC"
+
+property.addresses.resort(:id)   # has_many :addresses, -> { order(:name) }
+# => "...ORDER BY addresses.id ASC"
+
+Property.order(:name).resort(nil) # => relation, with no ORDER BY
+```
+
+With no ordering, `#resort` removes the order the way `reorder(nil)` does, so a
+`default_order` (Rails 8.2+), which applies when a relation has no other order,
+still applies:
+
+```ruby
+has_many :addresses, default_order: :likes
+
+property.addresses.resort(nil)    # ORDER BY likes, as with reorder(nil)
+property.addresses.resort(:name)  # ORDER BY name
+```
+
+Restricting what can be sorted
+------------------------------
+
+`#sort` checks that a name is a real column or association — not that the
+requester is allowed to know about it. Every column is sortable, including the
+ones you don't select:
+
+```ruby
+User.sort(:password_digest)               # valid, and it sorts
+Post.sort(author: :reset_password_token)  # so is this
+```
+
+A sort reveals something about a column even though its values are never
+returned, because the resulting order is a comparison. Someone with a row they
+control can set their own value, see which side of it a target row lands on,
+and narrow the value down over a series of ordinary-looking requests. Equal
+values also sort together, which is enough to tell that two accounts share a
+password hash.
+
+So passing parameters straight through is safe as far as SQL injection goes,
+but *which* columns may be sorted is an authorization question, and only your
+application can answer it. Filter the parameters before they reach `#sort`:
+
+```ruby
+SORTABLE = %w[name created_at].freeze
+
+Property.sort(sort_params.slice(*SORTABLE))
+```
+
+[StandardAPI](https://github.com/malomalo/standardapi) does this with an ACL,
+resolving per request which attributes a user may read and sort by.

data/ext/active_record/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_record'
 require 'active_record/relation'
 
@@ -41,14 +43,16 @@ module ActiveRecord
       ordering.each do |order|
         order = Array(order)
         order.each do |column_or_relation, options|
-          if column_or_relation.to_sym == :random
+          key = column_or_relation.to_s
+
+          if key == 'random'
             resource = resource.order(Arel::Nodes::RandomOrdering.new)
-          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)
+          elsif self.column_names.include?(key)
+            resource = resource.sort_for_column(self.arel_table[key], options)
+          elsif reflect_on_association(key)
+            resource = resource.sort_for_relation(key, options)
           else
-            raise InvalidSort.new("Unknown column #{column_or_relation}")
+            raise InvalidSort.new("Unknown column #{key}")
           end
         end
       end
@@ -56,26 +60,60 @@ module ActiveRecord
       resource
     end
 
+    # Like #sort, but replaces any order the relation already has, as
+    # +reorder+ does for +order+, including the order of an association's or
+    # default scope:
+    #
+    #   Property.order(:name).resort(:id)
+    #   # => "...ORDER BY properties.id ASC"
+    #
+    # With no ordering, or a blank one, its order is removed, as
+    # +reorder(nil)+ does. A +default_order+ (Rails 8.2+) still applies when
+    # the relation has no other order, as it does after +reorder(nil)+.
+    def resort(*ordering)
+      resource = reorder(nil)
+      ordering.empty? ? resource : resource.sort(*ordering)
+    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
+    # means 'asc'; a blank or nil value means no NULLS clause.
     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]
+      if options.blank?
+        ['asc', nil]
+      elsif options.is_a?(Hash) || options.class.name == "ActionController::Parameters"
+        direction = options.keys.first.to_s.downcase
+
+        if direction == 'asc' || direction == 'desc'
+          [direction, sort_nulls(options.values.first)]
+        else
+          [direction, nil]
+        end
       else
-        [options.to_s.downcase.to_sym, nil]
+        [options.to_s.downcase, nil]
+      end
+    end
+
+    # Cast on the way out: Arel's visitor matches the nulls value with
+    # `case o.nulls when :nulls_first`, so this is the one value that has
+    # to reach the node as a symbol.
+    def sort_nulls(value)
+      return nil if value.blank?
+
+      nulls = value.to_s.downcase
+      if nulls != 'nulls_first' && nulls != 'nulls_last'
+        raise InvalidSort.new("Unknown nulls ordering #{value}")
       end
+
+      nulls.to_sym
     end
 
     def sort_for_column(column, options)
       direction, nulls = sort_direction_and_nulls(options)
 
-      if direction == :desc
+      if direction == 'desc'
         self.order(Arel::Nodes::Descending.new(column, nulls))
-      elsif direction == :asc
+      elsif direction == 'asc'
         self.order(Arel::Nodes::Ascending.new(column, nulls))
       else
         raise InvalidSort.new("Unknown ordering #{direction}")
@@ -117,18 +155,17 @@ module ActiveRecord
           # 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
+          # (belongs_to / has_one) uses the plain attribute. Either way the
+          # attribute is a JoinedAttribute, pointed at the table (or alias)
+          # the association's join actually uses once the query is built.
+          column = JoinedAttribute.new(relation, column_name)
+          column = Arel::Attributes::Relation.new(column, relation.name) if relation.collection?
 
           direction, nulls = sort_direction_and_nulls(column_options)
 
-          order = if direction == :desc
+          order = if direction == 'desc'
             Arel::Nodes::Descending.new(column.maximum, nulls)
-          elsif direction == :asc
+          elsif direction == 'asc'
             Arel::Nodes::Ascending.new(column.minimum, nulls)
           else
             raise InvalidSort.new("Unknown ordering #{direction}")
@@ -158,6 +195,100 @@ module ActiveRecord
   end
 
   module Sort
+    # A column of a sorted association. Rails aliases a table it joins more
+    # than once — a second belongs_to to the same model, a scoped has_many,
+    # a self-join, or a table the caller already joined — and which join
+    # gets the alias depends on every join in the final query, so the sort
+    # can't name the table up front. This stands in for the column until
+    # the query is built, when JoinAliases swaps in the association's
+    # actual table. The reflection is part of its identity, so sorts on two
+    # associations to the same table aren't deduplicated as one.
+    class JoinedAttribute < Arel::Attributes::Attribute
+      attr_reader :reflection
+
+      def initialize(reflection, name)
+        super(reflection.klass.arel_table, name)
+        @reflection = reflection
+      end
+
+      def eql?(other)
+        super && reflection == other.reflection
+      end
+      alias == eql?
+
+      def hash
+        [super, reflection].hash
+      end
+    end
+
+    module JoinAliases
+      def construct_join_dependency(associations, join_type) # :nodoc:
+        join_dependency = super
+        @sort_join_dependencies << join_dependency if @sort_join_dependencies
+        join_dependency
+      end
+
+      private
+
+      # Builds the query, recording the join dependencies Rails constructs
+      # for it, then points each JoinedAttribute in the ORDER BY at the
+      # table its association was joined as. The orders are rebuilt rather
+      # than modified: order nodes are shared with every relation chained
+      # from this one, and those can join differently.
+      def build_arel(...)
+        return super if order_values.empty?
+
+        @sort_join_dependencies = []
+        arel = super
+        # Plus those built beforehand, as eager loading and merge do.
+        join_dependencies = @sort_join_dependencies +
+          (joins_values + left_outer_joins_values).grep(ActiveRecord::Associations::JoinDependency)
+        arel.ast.orders.map! { |order| resolve_sort_joins(order, join_dependencies) }
+        arel
+      ensure
+        @sort_join_dependencies = nil
+      end
+
+      def resolve_sort_joins(node, join_dependencies)
+        case node
+        when JoinedAttribute
+          table = sort_join_table(node.reflection, join_dependencies)
+          raise InvalidSort.new("Can't find the join for #{node.reflection.name} to sort by") unless table
+          table[node.name]
+        when Arel::Attributes::Relation
+          rebuild_sort_node(node, :relation, resolve_sort_joins(node.relation, join_dependencies))
+        when Arel::Nodes::Unary
+          rebuild_sort_node(node, :expr, resolve_sort_joins(node.expr, join_dependencies))
+        when Arel::Nodes::Function
+          rebuild_sort_node(node, :expressions, node.expressions.map { |e| resolve_sort_joins(e, join_dependencies) })
+        else
+          node
+        end
+      end
+
+      def rebuild_sort_node(node, attribute, value)
+        return node if node.public_send(attribute) == value
+
+        node = node.dup
+        node.public_send(:"#{attribute}=", value)
+        node
+      end
+
+      # The table of a top-level join of the association. Every join of it
+      # (the sort's own LEFT JOIN, the caller's, an eager load's) has the
+      # same conditions, so the first found will do.
+      def sort_join_table(reflection, join_dependencies)
+        join_dependencies.each do |join_dependency|
+          join_dependency.send(:join_root).children.each do |join|
+            if join.table && join.reflection.name == reflection.name && join.reflection.active_record == reflection.active_record
+              return join.table
+            end
+          end
+        end
+        nil
+      end
+    end
+
     module Calculations
       # sort_for_relation groups by the primary key and LEFT JOINs the
       # relation, so aggregates would see grouped, fanned-out rows: count
@@ -167,10 +298,14 @@ module ActiveRecord
       # 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.
+      # the standard grouped behavior. The subquery keeps the group and
+      # order so a limit or offset picks the same records loading would,
+      # rather than counting off fanned-out, unordered rows. The outer query
+      # is unscoped: the subquery already carries whatever default scope the
+      # relation kept, and must not have one it removed put back.
       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))
+          klass.unscoped.where(klass.primary_key => except(:select).select(klass.primary_key))
                .calculate(operation, column_name)
         else
           super
@@ -181,3 +316,4 @@ module ActiveRecord
 end
 
 ActiveRecord::Relation.prepend(ActiveRecord::Sort::Calculations)
+ActiveRecord::Relation.prepend(ActiveRecord::Sort::JoinAliases)

data/lib/active_record/sort/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module ActiveRecord
   module Sort
-    VERSION = '8.0.0'
+    VERSION = '8.1.0'
   end
 end

data/lib/active_record/sort.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require 'active_record'
 require 'arel/extensions'
 
 require File.expand_path(File.join(__FILE__, '../../../ext/active_record/base'))
 
 ActiveRecord::QueryMethods.prepend(ActiveRecord::Sort)
-ActiveRecord::Querying.delegate :sort, to: :all
+ActiveRecord::Querying.delegate :sort, :resort, to: :all

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-sort
 version: !ruby/object:Gem::Version
-  version: 8.0.0
+  version: 8.1.0
 platform: ruby
 authors:
 - Jon Bracy