Skip to content

A platform for community discussion. Free, open, simple.

DEV: Preserve removed sorts for older API versions (#43829)

Loïc Guitautc665ba85342d
diff --git a/lib/json_api_kit/declarations/sorts.rb b/lib/json_api_kit/declarations/sorts.rb
index 31e979c6d0b..75f96f311bc 100644
--- a/lib/json_api_kit/declarations/sorts.rb
+++ b/lib/json_api_kit/declarations/sorts.rb
@@ -5,17 +5,25 @@ module JsonApiKit
class Sorts
delegate :fetch, to: :sorts
- def initialize(sorts, schema:, unique_by: nil)
- @sorts = sorts.index_by(&:name)
+ def initialize(declarations, schema:, unique_by: nil)
+ @declarations = declarations
@schema = schema
@unique_by = Array(unique_by.presence || schema.primary_key)
end
+ def names = sorts.keys
+
+ def with(additional_sorts)
+ self.class.new(declarations.chain(additional_sorts), schema:, unique_by:)
+ end
+
def keyset(ordering) = Pagination::Keyset.new(keys(ordering))
private
- attr_reader :sorts, :schema, :unique_by
+ attr_reader :declarations, :schema, :unique_by
+
+ def sorts = @sorts ||= declarations.index_by(&:name)
def keys(ordering)
[
diff --git a/lib/json_api_kit/edition.rb b/lib/json_api_kit/edition.rb
index 6b38abe84d9..1b0c942abb1 100644
--- a/lib/json_api_kit/edition.rb
+++ b/lib/json_api_kit/edition.rb
@@ -20,6 +20,8 @@ module JsonApiKit
def removed_filters = @removed_filters ||= RemovedFilters.new(changes)
+ def removed_sorts = @removed_sorts ||= RemovedSorts.new(changes)
+
private
attr_reader :changes
diff --git a/lib/json_api_kit/removed_declarations.rb b/lib/json_api_kit/removed_declarations.rb
new file mode 100644
index 00000000000..0eb25f23c70
--- /dev/null
+++ b/lib/json_api_kit/removed_declarations.rb
@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class RemovedDeclarations
+ def initialize(changes)
+ @changes = changes
+ end
+
+ def for(type) = enum_for(:each_for, type)
+
+ private
+
+ attr_reader :changes
+
+ def each_for(type)
+ return if changes.empty?
+
+ changes
+ .reverse_each
+ .zip(types_at_changes(type, changes.reverse_each)) do |change, historical_type|
+ each_from(change, historical_type) { yield(it) }
+ end
+ end
+
+ def each_from(_change, _type)
+ raise NotImplementedError, "#{self.class} must implement each_from"
+ end
+
+ def types_at_changes(type, changes)
+ Enumerator.produce(type) { changes.next.previous_resource_type(it) }
+ end
+ end
+end
diff --git a/lib/json_api_kit/removed_filters.rb b/lib/json_api_kit/removed_filters.rb
index d5d5a9e87e6..45052443a36 100644
--- a/lib/json_api_kit/removed_filters.rb
+++ b/lib/json_api_kit/removed_filters.rb
@@ -1,29 +1,11 @@
# frozen_string_literal: true
module JsonApiKit
- class RemovedFilters
- def initialize(changes)
- @changes = changes
- end
-
- def for(type) = enum_for(:each_removed_filter, type)
-
+ class RemovedFilters < RemovedDeclarations
private
- attr_reader :changes
-
- def each_removed_filter(type)
- return if changes.empty?
-
- changes
- .reverse_each
- .zip(types_at_changes(type, changes.reverse_each)) do |change, historical_type|
- change.each_removed_filter(historical_type) { yield(it) }
- end
- end
-
- def types_at_changes(type, changes)
- Enumerator.produce(type) { changes.next.previous_resource_type(it) }
+ def each_from(change, type, &)
+ change.each_removed_filter(type, &)
end
end
end
diff --git a/lib/json_api_kit/removed_sorts.rb b/lib/json_api_kit/removed_sorts.rb
new file mode 100644
index 00000000000..a55657034b9
--- /dev/null
+++ b/lib/json_api_kit/removed_sorts.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class RemovedSorts < RemovedDeclarations
+ private
+
+ def each_from(change, type, &)
+ change.each_removed_sort(type, &)
+ end
+ end
+end
diff --git a/lib/json_api_kit/resource/anchoring.rb b/lib/json_api_kit/resource/anchoring.rb
index e9f703cc9f8..83a31da244d 100644
--- a/lib/json_api_kit/resource/anchoring.rb
+++ b/lib/json_api_kit/resource/anchoring.rb
@@ -35,7 +35,11 @@ module JsonApiKit
def declared_anchor(name) = declared_anchors.detect { it.name == name.to_s }
end
- delegate :anchor_names, :anchor_accepts?, :anchored_by?, :anchors, to: :class
+ delegate :anchor_names, :anchor_accepts?, :anchors, to: :class
+
+ def anchored_by?(anchor_name:, ordering:)
+ anchors(guardian).fetch(anchor_name.to_s) { return true }.locatable_in?(order(ordering))
+ end
end
end
end
diff --git a/lib/json_api_kit/resource/paging.rb b/lib/json_api_kit/resource/paging.rb
index a65b21a297e..21d092bc746 100644
--- a/lib/json_api_kit/resource/paging.rb
+++ b/lib/json_api_kit/resource/paging.rb
@@ -28,7 +28,9 @@ module JsonApiKit
def paged_from?(cursor, ordering:) = order(ordering).compatible_with?(cursor:)
end
- delegate :page_limits, :page_size, :max_page_size, :paged_from?, to: :class
+ delegate :page_limits, :page_size, :max_page_size, to: :class
+
+ def paged_from?(cursor, ordering:) = order(ordering).compatible_with?(cursor:)
end
end
end
diff --git a/lib/json_api_kit/resource/sorting.rb b/lib/json_api_kit/resource/sorting.rb
index 920277bf915..5a3c28cfbf2 100644
--- a/lib/json_api_kit/resource/sorting.rb
+++ b/lib/json_api_kit/resource/sorting.rb
@@ -26,6 +26,8 @@ module JsonApiKit
end
class_methods do
+ include Ordering
+
def sort(name, **options)
self.declared_sorts = declared_sorts + [Declarations::Sort.for(name, **options)]
end
@@ -34,40 +36,30 @@ module JsonApiKit
self.declared_default_sort = default_ordering(ordering)
end
- def default_ordering(ordering = declared_default_sort)
- verify_sorts(ordering.keys)
- ordering.each_value { Pagination::Direction.for(it) }
- ordering.transform_keys(&:to_s).freeze
- end
-
def unique_by(*columns)
self.declared_unique_by = columns
end
def sort_names = declared_sorts.map(&:name)
- def order(ordering) = Pagination::Order.new(sorts.keyset(ordering), type:)
-
- def sortable_by?(ordering:) = (ordering.keys - sort_names).empty?
-
- private
-
def sorts
Declarations::Sorts.new(declared_sorts, schema:, unique_by: declared_unique_by)
end
- def verify_sorts(names)
- missing = names.map(&:to_s) - declared_sorts.map(&:name)
- raise UndeclaredDefault, no_such_sort(missing) unless missing.empty?
- end
+ private
- def no_such_sort(names)
- "#{self}: there is no sort named #{names.join(", ")}, " \
- "declare it with `sort` before naming it as the default"
- end
+ def current_default_ordering = declared_default_sort
end
- delegate :sort_names, :order, :sortable_by?, :default_ordering, to: :class
+ include Ordering
+
+ delegate :names, to: :sorts, prefix: :sort
+
+ def sorts = @sorts ||= self.class.sorts.with(edition.removed_sorts.for(type))
+
+ private
+
+ def current_default_ordering = self.class.default_ordering
end
end
end
diff --git a/lib/json_api_kit/resource/sorting/ordering.rb b/lib/json_api_kit/resource/sorting/ordering.rb
new file mode 100644
index 00000000000..e2507208e1f
--- /dev/null
+++ b/lib/json_api_kit/resource/sorting/ordering.rb
@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class Resource
+ module Sorting
+ module Ordering
+ def default_ordering(ordering = current_default_ordering)
+ verify_sorts(ordering.keys)
+ ordering.each_value { Pagination::Direction.for(it) }
+ ordering.transform_keys(&:to_s).freeze
+ end
+
+ def order(ordering) = Pagination::Order.new(sorts.keyset(ordering), type:)
+
+ def sortable_by?(ordering:) = (ordering.keys - sort_names).empty?
+
+ private
+
+ def verify_sorts(names)
+ missing = names.map(&:to_s) - sort_names
+ raise UndeclaredDefault, no_such_sort(missing) unless missing.empty?
+ end
+
+ def no_such_sort(names)
+ "#{self}: there is no sort named #{names.join(", ")}, " \
+ "declare it with `sort` before naming it as the default"
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rb
index 607113adcec..504b4faabaa 100644
--- a/lib/json_api_kit/version_change.rb
+++ b/lib/json_api_kit/version_change.rb
@@ -23,6 +23,7 @@ module JsonApiKit
transformations.concat(it.transformations)
default_sorts.concat(it.default_sorts)
removed_filters.concat(it.removed_filters)
+ removed_sorts.concat(it.removed_sorts)
end
end
@@ -40,6 +41,8 @@ module JsonApiKit
def default_sorts = @default_sorts ||= []
def removed_filters = @removed_filters ||= []
+
+ def removed_sorts = @removed_sorts ||= []
end
delegate :version, :description, to: :class
@@ -52,6 +55,7 @@ module JsonApiKit
@type_renames = TypeRenames.new(self.class.type_renames)
@default_sorts = DefaultSorts.new(self.class.default_sorts)
@removed_filters = RemovedFilters.new(self.class.removed_filters)
+ @removed_sorts = RemovedSorts.new(self.class.removed_sorts)
end
def verify!
@@ -90,6 +94,8 @@ module JsonApiKit
def each_removed_filter(type, &) = removed_filters.each_for(type, &)
+ def each_removed_sort(type, &) = removed_sorts.each_for(type, &)
+
def each_current_default_sort(type)
default_sorts.each_for(type) do |default|
yield default.convert_names { transformations.current_names(it).sole }
@@ -98,7 +104,7 @@ module JsonApiKit
private
- attr_reader :transformations, :type_renames, :default_sorts, :removed_filters
+ attr_reader :transformations, :type_renames, :default_sorts, :removed_filters, :removed_sorts
def current_type(name) = name.convert_type { current_resource_type(it) }
diff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rb
index ebb873bc47a..ca223b9d8ae 100644
--- a/lib/json_api_kit/version_change/declarations.rb
+++ b/lib/json_api_kit/version_change/declarations.rb
@@ -8,11 +8,15 @@ module JsonApiKit
@transformations = []
@default_sorts = []
@removed_filters = []
+ @removed_sorts = []
end
- attr_reader :default_sorts, :removed_filters
+ attr_reader :default_sorts, :removed_filters, :removed_sorts
- def transformations = @transformations + removed_filters.flat_map(&:transformations)
+ def transformations
+ @transformations + removed_filters.flat_map(&:transformations) +
+ removed_sorts.flat_map(&:transformations)
+ end
def changed_default_sort(from:) = default_sorts << DefaultSort.new(type, from)
@@ -20,6 +24,10 @@ module JsonApiKit
removed_filters << RemovedFilter.new(type, name, &condition)
end
+ def removed_sort(name, **options)
+ removed_sorts << RemovedSort.new(type, name, **options)
+ end
+
def renamed_attribute(**) = declare(Declaration::RenamedAttribute.new(type, **))
def merged_attributes(**) = declare(Declaration::MergedAttributes.new(type, **))
diff --git a/lib/json_api_kit/version_change/removed_sort.rb b/lib/json_api_kit/version_change/removed_sort.rb
new file mode 100644
index 00000000000..a00961f7e6f
--- /dev/null
+++ b/lib/json_api_kit/version_change/removed_sort.rb
@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ class RemovedSort
+ attr_reader :type, :name
+
+ delegate :key, to: :sort
+
+ def initialize(type, name, **options)
+ @type = type.to_s
+ @name = "__removed_sort_#{object_id}"
+ @sort = JsonApiKit::Declarations::Sort.for(name, **options)
+ end
+
+ def transformations
+ Declaration::RenamedName.new(type, [Name::Sort], from: sort.name, to: name).transformations
+ end
+
+ private
+
+ attr_reader :sort
+ end
+ end
+end
diff --git a/lib/json_api_kit/version_change/removed_sorts.rb b/lib/json_api_kit/version_change/removed_sorts.rb
new file mode 100644
index 00000000000..8b5c3f9c5ee
--- /dev/null
+++ b/lib/json_api_kit/version_change/removed_sorts.rb
@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ class RemovedSorts
+ def initialize(sorts)
+ @sorts = sorts.group_by(&:type)
+ @sorts.default = [].freeze
+ end
+
+ def each_for(type, &) = sorts[type].each(&)
+
+ private
+
+ attr_reader :sorts
+ end
+ end
+end
diff --git a/spec/integration/json_api_kit/removed_sorts_spec.rb b/spec/integration/json_api_kit/removed_sorts_spec.rb
new file mode 100644
index 00000000000..6642f5ed578
--- /dev/null
+++ b/spec/integration/json_api_kit/removed_sorts_spec.rb
@@ -0,0 +1,439 @@
+# frozen_string_literal: true
+
+module JsonApiKitSpec
+ class RemovedSortPostResource < JsonApiKit::Resource
+ model Post
+ type :posts
+ attribute :post_number
+ end
+
+ class RemovedSortTopicResource < JsonApiKit::Resource
+ model Topic
+ type :topics
+
+ scope { |guardian| Topic.where(user_id: guardian.user&.id) }
+ attribute :title
+ attribute :created_at
+ sort :title
+ default_sort title: :asc
+ anchor :created_at
+ anchor :title
+ anchor :id
+ page default: 10, max: 20
+ has_many :posts, resource: RemovedSortPostResource
+ end
+
+ class RemovedSortTopicsController < JsonApiKit::BaseController
+ resource RemovedSortTopicResource
+ end
+end
+
+RSpec.describe JsonApiKitSpec::RemovedSortTopicsController, type: :request do
+ fab!(:author, :user)
+ fab!(:oldest_category) { Fabricate(:category, name: "M category") }
+ fab!(:middle_category) { Fabricate(:category, name: "A category") }
+ fab!(:newest_category) { Fabricate(:category, name: "Z category") }
+ fab!(:oldest) do
+ Fabricate(
+ :topic,
+ user: author,
+ category: oldest_category,
+ title: "A first topic to sort",
+ created_at: Time.utc(2026, 8, 1),
+ last_posted_at: Time.utc(2026, 8, 1),
+ )
+ end
+ fab!(:middle) do
+ Fabricate(
+ :topic,
+ user: author,
+ category: middle_category,
+ title: "Z middle topic to sort",
+ created_at: Time.utc(2026, 8, 2),
+ last_posted_at: nil,
+ )
+ end
+ fab!(:newest) do
+ Fabricate(
+ :topic,
+ user: author,
+ category: newest_category,
+ title: "M last topic to sort",
+ created_at: Time.utc(2026, 8, 3),
+ last_posted_at: Time.utc(2026, 8, 3),
+ )
+ end
+ fab!(:other_topic) { Fabricate(:topic, created_at: Time.utc(2026, 8, 4)) }
+
+ let(:resource) { JsonApiKitSpec::RemovedSortTopicResource }
+ let(:version) { JsonApiKit::Timeline::FIRST_RELEASE.to_s }
+ let(:parameters) { { sort: "-createdAt" } }
+ let(:body) { JSON.parse(response.body) }
+ let(:ids) { body.fetch("data").map { it.fetch("id") } }
+ let(:error) { body.fetch("errors").sole }
+ let(:removal_class) do
+ Class.new(JsonApiKit::VersionChange) do
+ version "2026-09-10"
+ description "Topics remove their creation sort."
+
+ resource :topics do
+ removed_sort :created_at
+ changed_default_sort from: { created_at: :desc }
+ end
+ end
+ end
+ let(:removal) { removal_class.new(__FILE__) }
+ let(:changes) { [removal] }
+ let(:version_changes) { JsonApiKit::VersionChanges.new(changes) }
+ let(:original_resource) { Class.new(resource) { sort :created_at } }
+ let(:original_cursor) do
+ original_resource.order("created_at" => :desc).locate(Topic.where(id: newest.id)).cursor.to_s
+ end
+
+ before do
+ freeze_time(Date.new(2026, 9, 18))
+ sign_in(author)
+ allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)
+ allow(described_class).to receive(:declared_resource).and_return(resource)
+ Rails.application.routes.disable_clear_and_finalize = true
+ Rails.application.routes.draw do
+ get "/api/removed-sort-topics" => "json_api_kit_spec/removed_sort_topics#index"
+ get "/api/removed-sort-topics/:id" => "json_api_kit_spec/removed_sort_topics#show"
+ end
+ Rails.application.routes.disable_clear_and_finalize = false
+ end
+
+ after { Rails.application.reload_routes! }
+
+ describe "#index" do
+ before do
+ get "/api/removed-sort-topics", headers: { "HTTP_API_VERSION" => version }, params: parameters
+ end
+
+ it "uses the retained sort within the authorized scope" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+
+ it "preserves the current declarations" do
+ expect(resource.sort_names).to eq(["title"])
+ end
+
+ context "when the client requests ascending order" do
+ let(:parameters) { { sort: "createdAt" } }
+
+ it "uses the requested direction" do
+ expect(ids).to eq([oldest.id, middle.id, newest.id].map(&:to_s))
+ end
+ end
+
+ context "when the client omits the sort" do
+ let(:parameters) { {} }
+
+ it "uses the removed sort as the historical default" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+
+ context "when the pin includes the removal" do
+ let(:version) { "2026-09-10" }
+
+ it "uses the current default" do
+ expect(ids).to eq([oldest.id, newest.id, middle.id].map(&:to_s))
+ end
+ end
+ end
+
+ context "when the pin includes the removal" do
+ let(:version) { "2026-09-10" }
+
+ it "rejects the removed sort in the client's vocabulary" do
+ expect(error).to include(
+ "status" => "400",
+ "title" => "No such sort",
+ "detail" => "There is no sort named createdAt.",
+ )
+ end
+ end
+
+ context "when the client follows a page link" do
+ let(:parameters) { super().merge(page: { size: 1 }) }
+ let(:next_page) { URI.parse(body.fetch("links").fetch("next")).request_uri }
+
+ before { get next_page, headers: { "HTTP_API_VERSION" => version } }
+
+ it "continues the retained ordering" do
+ expect(JSON.parse(response.body).fetch("data").map { it.fetch("id") }).to eq(
+ [middle.id.to_s],
+ )
+ end
+ end
+
+ context "when the cursor predates the removal" do
+ let(:parameters) { super().merge(page: { after: original_cursor }) }
+
+ it "accepts the original sort's cursor" do
+ expect(ids).to eq([middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the anchor matches the removed sort" do
+ let(:parameters) do
+ super().merge(page: { anchor: { createdAt: middle.created_at.iso8601 }, size: 2 })
+ end
+
+ it "enters the retained ordering at the anchor" do
+ expect(ids).to eq([middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the anchor matches only the current sort" do
+ let(:parameters) { super().merge(page: { anchor: { title: middle.title }, size: 2 }) }
+
+ it "rejects the incompatible anchor" do
+ expect(error).to include("status" => "400", "title" => "Anchor does not match the sort")
+ end
+ end
+
+ context "when the client uses the identity anchor" do
+ let(:parameters) { super().merge(page: { anchor: { id: middle.id }, size: 2 }) }
+
+ it "locates the row within the retained ordering" do
+ expect(ids).to eq([middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the removed sort has an aliased column" do
+ let(:parameters) { { sort: "-postedAt" } }
+ let(:removal_class) do
+ Class.new(JsonApiKit::VersionChange) do
+ version "2026-09-10"
+ resource(:topics) { removed_sort :posted_at, column: :created_at }
+ end
+ end
+
+ it "orders by the retained column" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the removed sort uses a SQL expression" do
+ let(:parameters) { { sort: "titleLength", fields: { topics: "title" } } }
+ let(:removal_class) do
+ Class.new(JsonApiKit::VersionChange) do
+ version "2026-09-10"
+ resource(:topics) { removed_sort :title_length, sql: "LENGTH(topics.title)" }
+ end
+ end
+
+ it "orders by the retained expression with a sparse fieldset" do
+ expect(ids).to eq([newest.id, oldest.id, middle.id].map(&:to_s))
+ end
+ end
+
+ context "when the removed sort has explicit joins" do
+ let(:parameters) { { sort: "categoryName" } }
+ let(:removal_class) do
+ Class.new(JsonApiKit::VersionChange) do
+ version "2026-09-10"
+ resource(:topics) do
+ removed_sort :category_name, sql: "categories.name", joins: :category
+ end
+ end
+ end
+
+ it "applies the retained joins" do
+ expect(ids).to eq([middle.id, oldest.id, newest.id].map(&:to_s))
+ end
+ end
+
+ context "when the removed sort names a related column" do
+ let(:parameters) { { sort: "category.name" } }
+ let(:removal_class) do
+ Class.new(JsonApiKit::VersionChange) do
+ version "2026-09-10"
+ resource(:topics) { removed_sort "category.name" }
+ end
+ end
+
+ it "preserves the related sort's lookup and projection" do
+ expect(ids).to eq([middle.id, oldest.id, newest.id].map(&:to_s))
+ end
+ end
+
+ context "when the removed sort has explicit null placement" do
+ let(:parameters) { { sort: "lastPostedAt" } }
+ let(:removal_class) do
+ Class.new(JsonApiKit::VersionChange) do
+ version "2026-09-10"
+ resource(:topics) { removed_sort :last_posted_at, nulls: :first }
+ end
+ end
+
+ it "places null values at the declared end" do
+ expect(ids).to eq([middle.id, oldest.id, newest.id].map(&:to_s))
+ end
+
+ context "when the client follows a page link across the null segment" do
+ let(:parameters) { super().merge(page: { size: 1 }) }
+ let(:next_page) { URI.parse(body.fetch("links").fetch("next")).request_uri }
+
+ before { get next_page, headers: { "HTTP_API_VERSION" => version } }
+
+ it "continues into the segment with values" do
+ expect(JSON.parse(response.body).fetch("data").map { it.fetch("id") }).to eq(
+ [oldest.id.to_s],
+ )
+ end
+ end
+ end
+
+ context "when the client follows a page link with a historical default" do
+ let(:parameters) { { page: { size: 1 } } }
+ let(:next_page) { URI.parse(body.fetch("links").fetch("next")).request_uri }
+
+ before { get next_page, headers: { "HTTP_API_VERSION" => version } }
+
+ it "continues the default ordering without an explicit sort" do
+ expect(JSON.parse(response.body).fetch("data").map { it.fetch("id") }).to eq(
+ [middle.id.to_s],
+ )
+ end
+ end
+
+ context "when a later rename reuses the removed spelling" do
+ let(:resource) { Class.new(super()) { sort :recency, column: :title } }
+ let(:changes) do
+ [
+ removal,
+ Class
+ .new(JsonApiKit::VersionChange) do
+ version "2026-09-15"
+ resource(:topics) { renamed_sort from: :created_at, to: :recency }
+ end
+ .new(__FILE__),
+ ]
+ end
+
+ it "keeps the old request bound to its retained implementation" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the resource type changes in the removal's own change" do
+ let(:removal_class) { super().tap { it.renamed_type from: :discussions, to: :topics } }
+
+ it "uses the declaration's type after the rename" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the same sort name is removed more than once" do
+ let(:changes) do
+ [
+ removal,
+ Class
+ .new(JsonApiKit::VersionChange) do
+ version "2026-09-15"
+ resource(:topics) { removed_sort :created_at, column: :title }
+ end
+ .new(__FILE__),
+ ]
+ end
+
+ it "uses the first implementation for the oldest pin" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+
+ context "when the pin is between removals" do
+ let(:version) { "2026-09-10" }
+
+ it "uses the second implementation" do
+ expect(ids).to eq([middle.id, newest.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the pin includes both removals" do
+ let(:version) { "2026-09-15" }
+
+ it "rejects the removed sort" do
+ expect(error).to include("status" => "400", "title" => "No such sort")
+ end
+ end
+ end
+
+ context "when the current resource reuses the removed name" do
+ let(:resource) { Class.new(super()) { sort :created_at, column: :title } }
+
+ it "keeps the old implementation for the older pin" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+
+ context "when the pin includes the removal" do
+ let(:version) { "2026-09-10" }
+
+ it "uses the current implementation" do
+ expect(ids).to eq([middle.id, newest.id, oldest.id].map(&:to_s))
+ end
+ end
+ end
+
+ context "when the sort was renamed before removal" do
+ let(:parameters) { { sort: "-postedAt" } }
+ let(:changes) do
+ [
+ Class
+ .new(JsonApiKit::VersionChange) do
+ version "2026-09-05"
+ resource(:topics) { renamed_sort from: :posted_at, to: :created_at }
+ end
+ .new(__FILE__),
+ removal,
+ ]
+ end
+
+ it "resolves the earlier name to the retained implementation" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when the resource type changes after removal" do
+ let(:resource) { Class.new(super()) { type :threads } }
+ let(:changes) do
+ [
+ removal,
+ Class
+ .new(JsonApiKit::VersionChange) do
+ version "2026-09-15"
+ renamed_type from: :topics, to: :threads
+ end
+ .new(__FILE__),
+ ]
+ end
+
+ it "restores the sort for the renamed resource" do
+ expect(ids).to eq([newest.id, middle.id, oldest.id].map(&:to_s))
+ end
+ end
+
+ context "when related resources have removed default sorts" do
+ fab!(:first_post) { Fabricate(:post, topic: newest, post_number: 1) }
+ fab!(:second_post) { Fabricate(:post, topic: newest, post_number: 2) }
+
+ let(:parameters) { super().merge(include: "posts") }
+ let(:removal_class) do
+ super().tap do |change|
+ change.resource :posts do
+ removed_sort :post_number
+ changed_default_sort from: { post_number: :desc }
+ end
+ end
+ end
+ let(:post_ids) do
+ body.fetch("data").first.dig("relationships", "posts", "data").map { it.fetch("id") }
+ end
+
+ it "uses the related resource's retained ordering" do
+ expect(post_ids).to eq([second_post.id, first_post.id].map(&:to_s))
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/declarations/sorts_spec.rb b/spec/lib/json_api_kit/declarations/sorts_spec.rb
index 77dd0017c56..e3752a997c5 100644
--- a/spec/lib/json_api_kit/declarations/sorts_spec.rb
+++ b/spec/lib/json_api_kit/declarations/sorts_spec.rb
@@ -26,6 +26,24 @@ RSpec.describe JsonApiKit::Declarations::Sorts do
end
end
+ describe "#with" do
+ subject(:combined) { sorts.with([sort_class.new(:title)]) }
+
+ let(:unique_by) { %i[created_at id] }
+
+ it "combines current and additional declarations" do
+ expect(combined.names).to contain_exactly("created_at", "ran_at", "title")
+ end
+
+ it "preserves the unique keys" do
+ expect(combined.keyset("title" => :desc).keys.map(&:name)).to eq(%i[title created_at id])
+ end
+
+ it "preserves the original collection" do
+ expect { combined.names }.not_to change(sorts, :names)
+ end
+ end
+
describe "#keyset" do
subject(:keyset) { sorts.keyset(ordering) }
diff --git a/spec/lib/json_api_kit/edition_spec.rb b/spec/lib/json_api_kit/edition_spec.rb
index bf491ce6e1e..109ef0e807f 100644
--- a/spec/lib/json_api_kit/edition_spec.rb
+++ b/spec/lib/json_api_kit/edition_spec.rb
@@ -91,4 +91,10 @@ RSpec.describe JsonApiKit::Edition do
expect(edition.removed_filters).to equal(edition.removed_filters)
end
end
+
+ describe "#removed_sorts" do
+ it "retains the resolver for the edition" do
+ expect(edition.removed_sorts).to equal(edition.removed_sorts)
+ end
+ end
end
diff --git a/spec/lib/json_api_kit/removed_sorts_spec.rb b/spec/lib/json_api_kit/removed_sorts_spec.rb
new file mode 100644
index 00000000000..28b9a9b173c
--- /dev/null
+++ b/spec/lib/json_api_kit/removed_sorts_spec.rb
@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::RemovedSorts do
+ subject(:removed_sorts) { described_class.new(changes) }
+
+ let(:changes) { [removal] }
+ let(:removal) { removal_class.new(__FILE__) }
+ let(:removal_class) do
+ Class.new(JsonApiKit::VersionChange) do
+ resource(:topics) { removed_sort :created_at }
+ resource(:groups) { removed_sort :name }
+ end
+ end
+ let(:topic_sort) { removal_class.removed_sorts.first }
+
+ describe "#for" do
+ subject(:sorts) { removed_sorts.for(type).to_a }
+
+ let(:type) { "topics" }
+
+ it "returns the resource's retained sorts" do
+ expect(sorts).to contain_exactly(topic_sort)
+ end
+
+ context "when the edition has no changes" do
+ let(:changes) { [] }
+
+ it "returns no retained sorts" do
+ expect(sorts).to be_empty
+ end
+ end
+
+ context "when the resource has no removed sorts" do
+ let(:type) { "users" }
+
+ it "returns no retained sorts" do
+ expect(sorts).to be_empty
+ end
+ end
+
+ context "when the resource type changes after removal" do
+ let(:type) { "threads" }
+ let(:changes) do
+ [
+ removal,
+ Class
+ .new(JsonApiKit::VersionChange) { renamed_type from: :topics, to: :threads }
+ .new(__FILE__),
+ ]
+ end
+
+ it "finds the sorts under the resource's earlier type" do
+ expect(sorts).to contain_exactly(topic_sort)
+ end
+
+ context "when another resource acquires the earlier type" do
+ let(:type) { "topics" }
+ let(:changes) do
+ super() +
+ [
+ Class
+ .new(JsonApiKit::VersionChange) { renamed_type from: :groups, to: :topics }
+ .new(__FILE__),
+ ]
+ end
+
+ it "returns only that resource's retained sorts" do
+ expect(sorts).to contain_exactly(removal_class.removed_sorts.last)
+ end
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/version_change/removed_sorts_spec.rb b/spec/lib/json_api_kit/version_change/removed_sorts_spec.rb
new file mode 100644
index 00000000000..8946e418725
--- /dev/null
+++ b/spec/lib/json_api_kit/version_change/removed_sorts_spec.rb
@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::VersionChange do
+ subject(:version_change) { change_class.new("2026-09-10_remove_sorts.rb") }
+
+ let(:change_class) do
+ Class.new(described_class) do
+ version "2026-09-10"
+ description "Topics remove their created_at sort."
+ resource(:topics) { removed_sort :created_at }
+ end
+ end
+
+ describe "#verify!" do
+ subject(:verify) { version_change.verify! }
+
+ before { freeze_time(Date.new(2026, 9, 18)) }
+
+ it "accepts a removed sort" do
+ expect { verify }.not_to raise_error
+ end
+
+ context "when the same sort is removed twice" do
+ before { change_class.resource(:topics) { removed_sort :created_at } }
+
+ it "reports the conflicting name and source" do
+ expect { verify }.to raise_error(
+ ArgumentError,
+ "2026-09-10_remove_sorts.rb changes created_at twice.",
+ )
+ end
+ end
+
+ context "when the same sort is both renamed and removed" do
+ before { change_class.resource(:topics) { renamed_sort from: :created_at, to: :title } }
+
+ it "rejects the conflicting declarations" do
+ expect { verify }.to raise_error(ArgumentError, /changes created_at twice/)
+ end
+ end
+
+ context "when an attribute rename also renames the removed sort" do
+ before do
+ change_class.resource(:topics) { renamed_attribute from: :created_at, to: :posted_at }
+ end
+
+ it "rejects the conflicting declarations" do
+ expect { verify }.to raise_error(ArgumentError, /changes created_at twice/)
+ end
+ end
+
+ context "when two resources remove the same sort name" do
+ before { change_class.resource(:other_topics) { removed_sort :created_at } }
+
+ it "accepts the independent declarations" do
+ expect { verify }.not_to raise_error
+ end
+ end
+ end
+
+ describe "#each_removed_sort" do
+ subject(:sorts) { version_change.enum_for(:each_removed_sort, type).to_a }
+
+ let(:type) { "topics" }
+
+ it "yields the retained declaration" do
+ expect(sorts).to contain_exactly(change_class.removed_sorts.sole)
+ end
+
+ context "when the resource has no removed sorts" do
+ let(:type) { "users" }
+
+ it "yields no sorts" do
+ expect(sorts).to be_empty
+ end
+ end
+ end
+end