A platform for community discussion. Free, open, simple.
# frozen_string_literal: true
module JsonApiKitSpec
class RenameThingsLabelToName < JsonApiKit::VersionChange
version "2026-09-15"
description "The `label` attribute of the things resource is renamed to `name`."
resource :things do
renamed_attribute from: :label, to: :name
end
end
class ReshapeThingsWordsToTitle < JsonApiKit::VersionChange
version "2026-09-20"
description "The `words` attribute of the things resource becomes `title`, one string."
resource :things do
renamed_attribute from: :words,
to: :title,
down: ->(title) { title.to_s.split(" ") },
up: ->(words) { words.to_a.join(" ") }
end
end
class MergeThingsDateAndTimeIntoPostedAt < JsonApiKit::VersionChange
version "2026-09-20"
description "The `posted_date` and `posted_time` attributes of the things resource become `posted_at`."
resource :things do
merged_attributes from: %i[posted_date posted_time],
to: :posted_at,
up: ->(date, time) { "#{date} #{time}" },
down: ->(posted_at) { posted_at.to_s.split(" ") }
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."
resource :things do
renamed_attribute from: :label, to: :name
end
resource :people do
renamed_attribute from: :handle, to: :username
end
end
end
RSpec.describe JsonApiKit::VersionChange do
subject(:version_change) { change_class.new(__FILE__) }
let(:change_class) { JsonApiKitSpec::RenameThingsLabelToName }
let(:version) { JsonApiKit::ApiVersion.parse("2026-09-15") }
let(:name) { JsonApiKit::Name::Field.new(value: "label", type: "things") }
describe ".resource" do
subject(:transformations) { change_class.transformations }
it "collects a rename for each name the attribute derives" do
expect(transformations).to all(be_a(JsonApiKit::VersionChange::Rename))
end
context "when the resource merges attributes" do
let(:change_class) { JsonApiKitSpec::MergeThingsDateAndTimeIntoPostedAt }
it "collects a merge for each name the attribute derives" 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
it "returns the version of the change" do
expect(version_change.version).to eq(version)
end
end
describe "#description" do
it "returns the description of the change" do
expect(version_change.description).to eq(
"The `label` attribute of the things resource is renamed to `name`.",
)
end
end
describe "#current_names" do
subject(:current_names) { version_change.current_names(name) }
it "returns the name after the change" do
expect(current_names).to eq([name.with(value: "name")])
end
context "when the name is the sort derived from the attribute" do
let(:name) { JsonApiKit::Name::Sort.new(value: "label", type: "things") }
it "renames it" do
expect(current_names).to eq([name.with(value: "name")])
end
end
context "when the name is the anchor derived from the attribute" do
let(:name) { JsonApiKit::Name::Anchor.new(value: "label", type: "things") }
it "renames it" do
expect(current_names).to eq([name.with(value: "name")])
end
end
context "when the name is a filter with the same spelling" do
let(:name) { JsonApiKit::Name::Filter.new(value: "label", type: "things") }
it "returns the name" do
expect(current_names).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_names).to eq([name.with(value: "name")])
end
end
end
context "when the change merges the name into another" do
let(:change_class) { JsonApiKitSpec::MergeThingsDateAndTimeIntoPostedAt }
let(:name) { JsonApiKit::Name::Field.new(value: "posted_time", type: "things") }
it "returns the name it merges into" do
expect(current_names).to eq([name.with(value: "posted_at")])
end
end
context "with several resources" do
subject(:current_names) { [name, other_name].flat_map { version_change.current_names(it) } }
let(:change_class) { JsonApiKitSpec::RenameThingsAndPeople }
let(:other_name) { JsonApiKit::Name::Field.new(value: "handle", type: "people") }
it "renames the names of every resource" do
expect(current_names).to eq([name.with(value: "name"), other_name.with(value: "username")])
end
end
end
describe "#current_attributes" do
subject(:current_attributes) { version_change.current_attributes(attributes) }
let(:attributes) { { name => "A", other_name => "B" } }
let(:other_name) { JsonApiKit::Name::Field.new(value: "size", type: "things") }
it "returns a renamed attribute under its current name" do
expect(current_attributes).to include(name.with(value: "name") => "A")
end
it "keeps an attribute the change does not rename" do
expect(current_attributes).to include(other_name => "B")
end
context "when the change merges two attributes" do
let(:change_class) { JsonApiKitSpec::MergeThingsDateAndTimeIntoPostedAt }
let(:attributes) { { name => "2026-08-01", other_name => "00:00:00" } }
let(:name) { JsonApiKit::Name::Field.new(value: "posted_date", type: "things") }
let(:other_name) { JsonApiKit::Name::Field.new(value: "posted_time", type: "things") }
it "returns one attribute under the name they merge into" do
expect(current_attributes).to eq(name.with(value: "posted_at") => "2026-08-01 00:00:00")
end
end
context "when the change reshapes the value" do
let(:change_class) { JsonApiKitSpec::ReshapeThingsWordsToTitle }
let(:attributes) { { name => %w[Bands of a listing] } }
let(:name) { JsonApiKit::Name::Field.new(value: "words", type: "things") }
it "returns the value in its current shape" do
expect(current_attributes).to eq(name.with(value: "title") => "Bands of a listing")
end
context "when the value is null" do
let(:attributes) { { name => nil } }
it "returns the value the converter gives for null" do
expect(current_attributes).to eq(name.with(value: "title") => "")
end
end
end
end
describe "#previous_names" do
subject(:previous_names) { version_change.previous_names(name) }
let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
it "returns the name before the change" do
expect(previous_names).to eq([name.with(value: "label")])
end
context "when the change merges several names into the name" do
let(:change_class) { JsonApiKitSpec::MergeThingsDateAndTimeIntoPostedAt }
let(:name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "things") }
it "returns every one of them" do
expect(previous_names).to eq(
[name.with(value: "posted_date"), name.with(value: "posted_time")],
)
end
end
end
describe "#previous_attributes" do
subject(:previous_attributes) { version_change.previous_attributes(attributes) }
let(:attributes) { { name => "A", other_name => "B" } }
let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
let(:other_name) { JsonApiKit::Name::Field.new(value: "size", type: "things") }
it "returns a renamed attribute under its name before the change" do
expect(previous_attributes).to include(name.with(value: "label") => "A")
end
it "keeps an attribute the change does not rename" do
expect(previous_attributes).to include(other_name => "B")
end
context "when the change merges two attributes" do
let(:change_class) { JsonApiKitSpec::MergeThingsDateAndTimeIntoPostedAt }
let(:attributes) { { name => "2026-08-01 00:00:00" } }
let(:name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "things") }
it "returns the two attributes under their names before the change" do
expect(previous_attributes).to eq(
name.with(value: "posted_date") => "2026-08-01",
name.with(value: "posted_time") => "00:00:00",
)
end
end
context "when the change reshapes the value" do
let(:change_class) { JsonApiKitSpec::ReshapeThingsWordsToTitle }
let(:attributes) { { name => "Bands of a listing" } }
let(:name) { JsonApiKit::Name::Field.new(value: "title", type: "things") }
it "returns the value in its shape before the change" do
expect(previous_attributes).to eq(name.with(value: "words") => %w[Bands of a listing])
end
context "when the value is null" do
let(:attributes) { { name => nil } }
it "returns the value the converter gives for null" do
expect(previous_attributes).to eq(name.with(value: "words") => [])
end
end
end
end
end