jpie 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd3d3cf0f731b0a5d47d2e0ae3b4fc405d7b49ae775da39baf04a3f862b06d3b
-  data.tar.gz: 2d305cd5e41bb20cc5ef36fdf0321407425e503fee2a7424f40035cb9fda0059
+  metadata.gz: 5c04100490b218fa6dbef0035d581acd97ec7ebae03d045d0966a633bdcfb567
+  data.tar.gz: 116d6e4ae7f51f03a47f8222771f2fb508435fce759014eadd3a02642a4f7b85
 SHA512:
-  metadata.gz: beeb386f1743ca01b78a5532925d16115b66ca94ae00f31b1b94118c7b0bdf63367e00242593b78e62cd891c7e497cc00b722ee17d6fa37b724f2de5aa40d178
-  data.tar.gz: e6362ed9996bec7dedabf0891e9a50a4ff80f240829cf6f7e08decf4b4ddf5d29c139f6e71eb88de1a53648449c416907a81c7f73dee1134e49a4b8704ca5063
+  metadata.gz: e86bd604abba1b02e6148d857a2967a05b90a35c796503f2517d25368cbb95a8c102afddc2208a8f77961085bc041a55e27e6b6d0f304b37ed9404362fbf64eb
+  data.tar.gz: 3ec3bda5b8ce2e07fb494f790cbc20391b37fd12a9f57c6a352b3129a9037246116d68440f70cb86b17e3ca424ad6bd4efdbba174b3af8825cb1149bfc59fbb5

data/CHANGELOG.md

@@ -7,6 +7,36 @@ at release time.
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-09-15
+
+### Fixed
+
+- **Preload the include tree, never join it.** `scope_with_includes` handed the
+  tree to `includes`, and Rails answers `includes` with one LEFT OUTER JOIN
+  across every path as soon as the scope answers `eager_loading?` with true. A
+  single condition on a table that no `joins` names is enough to cause that: a
+  resource default such as
+  `super.includes(:archival).where(archivals: { archived_at: nil })` does it.
+  Every collection path in the tree then multiplied row for row. A reported
+  page of 25 records joined 75,712 rows and allocated 796.1MB to return an
+  822kB document, and 98% of those bytes were the rows, not the serializer. The
+  tree now preloads in every case: the same document costs 18.1MB in 12
+  queries. Serialization filters on none of the included tables, so the tree
+  never needed the join, and a scope's own `includes` is untouched — it still
+  supplies whatever join its own conditions need. Regression spec:
+  `include_preload_never_joins_spec.rb`.
+
+  **One behaviour change comes with it.** A query that puts a condition or an
+  order on an included table, and does not join that table itself, now raises.
+  Before, it worked only when the client's `?include=` named that table. Look
+  for such a query in three places:
+
+  - the `records` scope of a resource;
+  - a model scope that `sort` calls, such as `order(authors: { name: dir })`;
+  - a model scope that `filter` calls, such as `where(authors: { name: v })`.
+
+  Add `joins` or `left_joins` for the table to fix it.
+
 ## [4.0.0] - 2026-09-09
 
 ### Changed

data/lib/json_api/controllers/concerns/resource_actions/include_preloading.rb

@@ -25,12 +25,16 @@ module JSONAPI
         return scope unless includes.any?
         return scope if scope.is_a?(Array)
 
-        inc_hash = includes_to_hash(includes)
-        # `includes` may resolve to a JOIN when the base scope already references an
-        # associated table (e.g. a `records` override that sorts by one). Rails cannot
-        # eager-load polymorphic or instance-dependent associations in a JOIN, so those
-        # must go through `preload` (a separate query), which loads them without raising.
-        preload_required?(inc_hash, model_class) ? scope.preload(inc_hash) : scope.includes(inc_hash)
+        # `preload`, never `includes`. `includes` resolves to one LEFT OUTER JOIN
+        # across the whole tree whenever the scope already answers
+        # `eager_loading?` with true, which one condition on an unjoined table is
+        # enough to cause. Every collection path in the tree then multiplies row
+        # for row: a measured page of 25 records loaded 75,712 rows and allocated
+        # 800MB, against 18MB for the same document through `preload`.
+        # Serialization filters on none of the included tables, so the tree never
+        # needs the join. A scope's own `includes` is untouched and still supplies
+        # whatever join its own conditions need.
+        scope.preload(includes_to_hash(includes))
       end
 
       def filter_includable(hash, klass)
@@ -57,35 +61,6 @@ module JSONAPI
         reflection.macro == :has_one_attached ? :"#{key}_attachment" : :"#{key}_attachments"
       end
 
-      def preload_required?(hash, klass)
-        hash.any? do |key, value|
-          assoc = klass.reflect_on_association(key)
-          next false unless assoc
-
-          assoc.polymorphic? || instance_dependent_scope?(assoc) ||
-            (value.present? && preload_required?(value, assoc.klass))
-        end
-      end
-
-      # Rails refuses to eager-load (JOIN) an association whose scope takes the owner
-      # instance (`->(owner) { ... }`), raising "instance dependent scopes are not
-      # supported". Its arity is non-zero; such associations must be preloaded instead.
-      def instance_dependent_scope?(assoc)
-        scope = assoc.scope
-        !scope.nil? && scope.arity != 0
-      end
-
-      def hash_contains_polymorphic?(hash, klass)
-        hash.any? { |key, value| polymorphic_in_hash_entry?(key, value, klass) }
-      end
-
-      def polymorphic_in_hash_entry?(key, value, klass)
-        assoc = klass.reflect_on_association(key)
-        return false unless assoc
-
-        assoc.polymorphic? || (value.present? && hash_contains_polymorphic?(value, assoc.klass))
-      end
-
       # Applies each included resource's own `records` preloads to the records
       # of that resource's class. Walks the whole include tree: a resource
       # reached at depth 3 gets its preloads just as one reached at depth 1.

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "4.0.0"
+  VERSION = "4.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Emil Kampp