Skip to content

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

DEV: Allow to rename sorts and filters in JSON:API versions (#43524)

Loïc Guitaut488752f5d9e3
diff --git a/lib/json_api_kit/version_change/declaration.rb b/lib/json_api_kit/version_change/declaration.rb
index c7c5fc963df..8a3993b9a01 100644
--- a/lib/json_api_kit/version_change/declaration.rb
+++ b/lib/json_api_kit/version_change/declaration.rb
@@ -10,6 +10,7 @@ module JsonApiKit
end
DERIVED_FROM_AN_ATTRIBUTE = [Name::Field, Name::Sort, Name::Anchor].freeze
+ NO_CONVERSION = ->(value) { value }
def initialize(type, from:, to:, up:, down:)
@type = type.to_s
@@ -21,7 +22,7 @@ module JsonApiKit
def transformations
verify!
- DERIVED_FROM_AN_ATTRIBUTE.map { transformation(it) }
+ kinds.map { transformation(it) }
end
private
@@ -30,6 +31,8 @@ module JsonApiKit
def verify! = nil
+ def kinds = raise NotImplementedError, "#{self.class} must implement kinds"
+
def transformation(_kind)
raise NotImplementedError, "#{self.class} must implement transformation(kind)"
end
diff --git a/lib/json_api_kit/version_change/declaration/merged_attributes.rb b/lib/json_api_kit/version_change/declaration/merged_attributes.rb
index 2551d859b5a..6b48a403d81 100644
--- a/lib/json_api_kit/version_change/declaration/merged_attributes.rb
+++ b/lib/json_api_kit/version_change/declaration/merged_attributes.rb
@@ -10,6 +10,8 @@ module JsonApiKit
private
+ def kinds = DERIVED_FROM_AN_ATTRIBUTE
+
def verify!
raise fault("Declare at least two names") unless from.many?
end
diff --git a/lib/json_api_kit/version_change/declaration/renamed_attribute.rb b/lib/json_api_kit/version_change/declaration/renamed_attribute.rb
index fc9fb4294eb..9484fc7d772 100644
--- a/lib/json_api_kit/version_change/declaration/renamed_attribute.rb
+++ b/lib/json_api_kit/version_change/declaration/renamed_attribute.rb
@@ -3,11 +3,9 @@
module JsonApiKit
class VersionChange
class Declaration
- class RenamedAttribute < Declaration
- NO_CONVERSION = ->(value) { value }
-
+ class RenamedAttribute < RenamedName
def initialize(type, from:, to:, up: NO_CONVERSION, down: NO_CONVERSION)
- super
+ super(type, DERIVED_FROM_AN_ATTRIBUTE, from:, to:, up:, down:)
end
private
@@ -15,10 +13,6 @@ module JsonApiKit
def verify!
raise fault("Declare both up: and down:") if [up, down].count(NO_CONVERSION) == 1
end
-
- def transformation(kind)
- Rename.new(from: name(kind, from), to: name(kind, to), **converters)
- end
end
end
end
diff --git a/lib/json_api_kit/version_change/declaration/renamed_name.rb b/lib/json_api_kit/version_change/declaration/renamed_name.rb
new file mode 100644
index 00000000000..a777cd8f3cb
--- /dev/null
+++ b/lib/json_api_kit/version_change/declaration/renamed_name.rb
@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ class Declaration
+ class RenamedName < Declaration
+ def initialize(type, kinds, from:, to:, up: NO_CONVERSION, down: NO_CONVERSION)
+ super(type, from:, to:, up:, down:)
+ @kinds = kinds
+ end
+
+ private
+
+ attr_reader :kinds
+
+ def transformation(kind)
+ Rename.new(from: name(kind, from), to: name(kind, to), **converters)
+ end
+ end
+ end
+ end
+end
diff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rb
index 65da05cb252..397fb8aa33d 100644
--- a/lib/json_api_kit/version_change/declarations.rb
+++ b/lib/json_api_kit/version_change/declarations.rb
@@ -12,6 +12,14 @@ module JsonApiKit
def merged_attributes(**) = declare(Declaration::MergedAttributes.new(type, **))
+ def renamed_sort(from:, to:)
+ declare(Declaration::RenamedName.new(type, [Name::Sort], from:, to:))
+ end
+
+ def renamed_filter(from:, to:)
+ declare(Declaration::RenamedName.new(type, [Name::Filter], from:, to:))
+ end
+
def to_a = transformations
private
diff --git a/spec/integration/json_api_kit/version_changes_spec.rb b/spec/integration/json_api_kit/version_changes_spec.rb
index a4b20e61f28..0babe81b424 100644
--- a/spec/integration/json_api_kit/version_changes_spec.rb
+++ b/spec/integration/json_api_kit/version_changes_spec.rb
@@ -17,6 +17,8 @@ module JsonApiKitSpec
to: :title,
down: ->(title) { title.to_s.split(" ") },
up: ->(words) { words.to_a.join(" ") }
+ renamed_sort from: :bumped_at, to: :last_posted_at
+ renamed_filter from: :name, to: :title
end
end
end
@@ -34,6 +36,9 @@ RSpec.describe "JSON:API version changes", type: :request do
let(:ids) { parsed_body["data"].map { it["id"] } }
before do
+ oldest.update_columns(last_posted_at: Time.utc(2026, 8, 3))
+ middle.update_columns(last_posted_at: Time.utc(2026, 8, 1))
+ newest.update_columns(last_posted_at: Time.utc(2026, 8, 2))
freeze_time(change_version.date + 1.day)
allow(JsonApiKit::VersionChange).to receive(:all).and_return([change])
Rails.application.routes.disable_clear_and_finalize = true
@@ -152,6 +157,59 @@ RSpec.describe "JSON:API version changes", type: :request do
end
end
+ context "when the request sorts by the renamed sort" do
+ let(:query) { { "sort" => "bumpedAt" } }
+
+ it "orders the rows by the current sort" do
+ expect(ids).to eq([middle.id.to_s, newest.id.to_s, oldest.id.to_s])
+ end
+ end
+
+ context "when the request sorts by the current name of the renamed sort" do
+ let(:query) { { "sort" => "lastPostedAt" } }
+
+ it "sends the reason" do
+ expect(error).to eq(
+ refusal(
+ title: "Invalid member name",
+ detail: "Use bumpedAt, not lastPostedAt.",
+ parameter: "sort",
+ ).deep_stringify_keys,
+ )
+ end
+ end
+
+ context "when the request filters by the renamed filter" do
+ let(:query) { { "filter" => { "name" => newest.title } } }
+
+ it "sends the rows the current filter keeps" do
+ expect(ids).to eq([newest.id.to_s])
+ end
+ end
+
+ context "when a refusal includes the renamed sort" do
+ let(:query) do
+ {
+ "sort" => "bumpedAt",
+ "page" => {
+ "anchor" => {
+ "postedAt" => middle.created_at.iso8601(6),
+ },
+ },
+ }
+ end
+
+ it "sends the name of that version" do
+ expect(error).to eq(
+ refusal(
+ title: "Anchor does not match the sort",
+ detail: "The anchor is postedAt, but this request sorts by bumpedAt.",
+ parameter: "page[anchor][postedAt]",
+ ).deep_stringify_keys,
+ )
+ end
+ end
+
context "when the request uses the new name" do
let(:query) { { "fields" => { "topics" => "createdAt" } } }
@@ -199,5 +257,13 @@ RSpec.describe "JSON:API version changes", type: :request do
expect(attributes.keys).to contain_exactly("createdAt")
end
end
+
+ context "when the request sorts by the current sort" do
+ let(:query) { { "sort" => "lastPostedAt" } }
+
+ it "orders the rows by that sort" do
+ expect(ids).to eq([middle.id.to_s, newest.id.to_s, oldest.id.to_s])
+ end
+ end
end
end
diff --git a/spec/lib/json_api_kit/version_change/declaration/renamed_attribute_spec.rb b/spec/lib/json_api_kit/version_change/declaration/renamed_attribute_spec.rb
index c92b283498b..2296c280304 100644
--- a/spec/lib/json_api_kit/version_change/declaration/renamed_attribute_spec.rb
+++ b/spec/lib/json_api_kit/version_change/declaration/renamed_attribute_spec.rb
@@ -3,8 +3,8 @@
RSpec.describe JsonApiKit::VersionChange::Declaration::RenamedAttribute do
subject(:declaration) { described_class.new("things", from: :label, to: :name, up:, down:) }
- let(:up) { described_class::NO_CONVERSION }
- let(:down) { described_class::NO_CONVERSION }
+ let(:up) { JsonApiKit::VersionChange::Declaration::NO_CONVERSION }
+ let(:down) { JsonApiKit::VersionChange::Declaration::NO_CONVERSION }
describe "#transformations" do
subject(:transformations) { declaration.transformations }
diff --git a/spec/lib/json_api_kit/version_change/declaration/renamed_name_spec.rb b/spec/lib/json_api_kit/version_change/declaration/renamed_name_spec.rb
new file mode 100644
index 00000000000..4ee08478d74
--- /dev/null
+++ b/spec/lib/json_api_kit/version_change/declaration/renamed_name_spec.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::VersionChange::Declaration::RenamedName do
+ subject(:declaration) do
+ described_class.new("things", kinds, from: :bumped_at, to: :last_posted_at)
+ end
+
+ let(:kinds) { [JsonApiKit::Name::Sort] }
+
+ describe "#transformations" do
+ subject(:transformations) { declaration.transformations }
+
+ let(:rename) { transformations.sole }
+
+ it "returns one rename of that kind" do
+ expect(transformations).to contain_exactly(
+ an_object_having_attributes(
+ from: JsonApiKit::Name::Sort.new(value: "bumped_at", type: "things"),
+ to: JsonApiKit::Name::Sort.new(value: "last_posted_at", type: "things"),
+ ),
+ )
+ end
+
+ it "preserves the value through the up converter" do
+ expect(rename.up.call("a")).to eq("a")
+ end
+
+ it "preserves the value through the down converter" do
+ expect(rename.down.call("a")).to eq("a")
+ end
+
+ context "when the kind is a filter" do
+ let(:kinds) { [JsonApiKit::Name::Filter] }
+ let(:previous_names) { transformations.map(&:from) }
+
+ it "returns one rename of a filter" do
+ expect(previous_names).to contain_exactly(
+ JsonApiKit::Name::Filter.new(value: "bumped_at", type: "things"),
+ )
+ end
+ end
+ end
+end
diff --git a/spec/lib/json_api_kit/version_change/rename_spec.rb b/spec/lib/json_api_kit/version_change/rename_spec.rb
index c2c6bf06f31..f54f11e64f0 100644
--- a/spec/lib/json_api_kit/version_change/rename_spec.rb
+++ b/spec/lib/json_api_kit/version_change/rename_spec.rb
@@ -3,8 +3,8 @@
RSpec.describe JsonApiKit::VersionChange::Rename do
subject(:rename) { described_class.new(from: old_name, to: new_name, up:, down:) }
- let(:up) { JsonApiKit::VersionChange::Declaration::RenamedAttribute::NO_CONVERSION }
- let(:down) { JsonApiKit::VersionChange::Declaration::RenamedAttribute::NO_CONVERSION }
+ let(:up) { JsonApiKit::VersionChange::Declaration::NO_CONVERSION }
+ let(:down) { JsonApiKit::VersionChange::Declaration::NO_CONVERSION }
let(:old_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "topics") }
let(:new_name) { JsonApiKit::Name::Field.new(value: "created_at", type: "topics") }
diff --git a/spec/lib/json_api_kit/version_change_spec.rb b/spec/lib/json_api_kit/version_change_spec.rb
index ea6a3f0e153..23fd3ae54be 100644
--- a/spec/lib/json_api_kit/version_change_spec.rb
+++ b/spec/lib/json_api_kit/version_change_spec.rb
@@ -34,6 +34,16 @@ module JsonApiKitSpec
end
end
+ class RenameThingsSortAndFilter < JsonApiKit::VersionChange
+ version "2026-09-20"
+ description "The things resource renames its `bumped_at` sort and its `label` filter."
+
+ resource :things do
+ renamed_sort from: :bumped_at, to: :last_posted_at
+ renamed_filter from: :label, to: :name
+ end
+ end
+
class RenameThingsAndPeople < JsonApiKit::VersionChange
version "2026-10-01"
description "Two resources change their names."
@@ -162,6 +172,62 @@ RSpec.describe JsonApiKit::VersionChange do
expect(transformations).to all(be_a(JsonApiKit::VersionChange::Merge))
end
end
+
+ context "when the resource renames a sort and a filter" do
+ let(:change_class) { JsonApiKitSpec::RenameThingsSortAndFilter }
+ let(:previous_names) { transformations.map(&:from) }
+
+ it "collects one rename for the sort and one for the filter" do
+ expect(previous_names).to contain_exactly(
+ JsonApiKit::Name::Sort.new(value: "bumped_at", type: "things"),
+ JsonApiKit::Name::Filter.new(value: "label", type: "things"),
+ )
+ end
+ end
+
+ context "when a rename declares a converter" do
+ subject(:declare_resource) { Class.new(described_class).resource(:things, &declarations) }
+
+ context "when a sort rename declares an up converter" do
+ let(:declarations) do
+ proc { renamed_sort from: :label, to: :name, up: ->(value) { value } }
+ end
+
+ it "rejects the converter option" do
+ expect { declare_resource }.to raise_error(ArgumentError, "unknown keyword: :up")
+ end
+ end
+
+ context "when a sort rename declares a down converter" do
+ let(:declarations) do
+ proc { renamed_sort from: :label, to: :name, down: ->(value) { value } }
+ end
+
+ it "rejects the converter option" do
+ expect { declare_resource }.to raise_error(ArgumentError, "unknown keyword: :down")
+ end
+ end
+
+ context "when a filter rename declares an up converter" do
+ let(:declarations) do
+ proc { renamed_filter from: :label, to: :name, up: ->(value) { value } }
+ end
+
+ it "rejects the converter option" do
+ expect { declare_resource }.to raise_error(ArgumentError, "unknown keyword: :up")
+ end
+ end
+
+ context "when a filter rename declares a down converter" do
+ let(:declarations) do
+ proc { renamed_filter from: :label, to: :name, down: ->(value) { value } }
+ end
+
+ it "rejects the converter option" do
+ expect { declare_resource }.to raise_error(ArgumentError, "unknown keyword: :down")
+ end
+ end
+ end
end
describe "#version" do
@@ -207,6 +273,14 @@ RSpec.describe JsonApiKit::VersionChange do
it "returns the name" do
expect(current_name).to eq(name)
end
+
+ context "when the change renames the filter" do
+ let(:change_class) { JsonApiKitSpec::RenameThingsSortAndFilter }
+
+ it "returns the new name of the filter" do
+ expect(current_name).to eq(name.with(value: "name"))
+ end
+ end
end
context "when the change merges the name into another" do