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.rbindex 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 JsonApiKitendDERIVED_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 JsonApiKitdef transformationsverify!- DERIVED_FROM_AN_ATTRIBUTE.map { transformation(it) }+ kinds.map { transformation(it) }endprivate@@ -30,6 +31,8 @@ module JsonApiKitdef verify! = nil+ def kinds = raise NotImplementedError, "#{self.class} must implement kinds"+def transformation(_kind)raise NotImplementedError, "#{self.class} must implement transformation(kind)"enddiff --git a/lib/json_api_kit/version_change/declaration/merged_attributes.rb b/lib/json_api_kit/version_change/declaration/merged_attributes.rbindex 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 JsonApiKitprivate+ def kinds = DERIVED_FROM_AN_ATTRIBUTE+def verify!raise fault("Declare at least two names") unless from.many?enddiff --git a/lib/json_api_kit/version_change/declaration/renamed_attribute.rb b/lib/json_api_kit/version_change/declaration/renamed_attribute.rbindex 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 JsonApiKitclass VersionChangeclass Declaration- class RenamedAttribute < Declaration- NO_CONVERSION = ->(value) { value }-+ class RenamedAttribute < RenamedNamedef initialize(type, from:, to:, up: NO_CONVERSION, down: NO_CONVERSION)- super+ super(type, DERIVED_FROM_AN_ATTRIBUTE, from:, to:, up:, down:)endprivate@@ -15,10 +13,6 @@ module JsonApiKitdef verify!raise fault("Declare both up: and down:") if [up, down].count(NO_CONVERSION) == 1end-- def transformation(kind)- Rename.new(from: name(kind, from), to: name(kind, to), **converters)- endendendenddiff --git a/lib/json_api_kit/version_change/declaration/renamed_name.rb b/lib/json_api_kit/version_change/declaration/renamed_name.rbnew file mode 100644index 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+enddiff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rbindex 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 JsonApiKitdef 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 = transformationsprivatediff --git a/spec/integration/json_api_kit/version_changes_spec.rb b/spec/integration/json_api_kit/version_changes_spec.rbindex 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 JsonApiKitSpecto: :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: :titleendendend@@ -34,6 +36,9 @@ RSpec.describe "JSON:API version changes", type: :request dolet(: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 doendend+ 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" dolet(:query) { { "fields" => { "topics" => "createdAt" } } }@@ -199,5 +257,13 @@ RSpec.describe "JSON:API version changes", type: :request doexpect(attributes.keys).to contain_exactly("createdAt")endend++ 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+ endendenddiff --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.rbindex 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 dosubject(: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" dosubject(: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.rbnew file mode 100644index 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+enddiff --git a/spec/lib/json_api_kit/version_change/rename_spec.rb b/spec/lib/json_api_kit/version_change/rename_spec.rbindex 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 dosubject(: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.rbindex 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 JsonApiKitSpecendend+ 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::VersionChangeversion "2026-10-01"description "Two resources change their names."@@ -162,6 +172,62 @@ RSpec.describe JsonApiKit::VersionChange doexpect(transformations).to all(be_a(JsonApiKit::VersionChange::Merge))endend++ 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+ endenddescribe "#version" do@@ -207,6 +273,14 @@ RSpec.describe JsonApiKit::VersionChange doit "returns the name" doexpect(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+ endendcontext "when the change merges the name into another" do