Skip to content

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

DEV: Convert a renamed attribute's value across JSON:API versions (#43349)

Loïc Guitautde00917e8d51
diff --git a/lib/json_api_kit/declarations/attributes.rb b/lib/json_api_kit/declarations/attributes.rb
index 79b9158acfd..1159dcc7416 100644
--- a/lib/json_api_kit/declarations/attributes.rb
+++ b/lib/json_api_kit/declarations/attributes.rb
@@ -3,23 +3,29 @@
module JsonApiKit
module Declarations
class Attributes
- def initialize(attributes, guardian:, schema:)
+ def initialize(attributes, guardian:, schema:, type:)
@attributes = attributes
@guardian = guardian
@schema = schema
+ @type = type
+ @field_names = {}
end
def names = attributes.map(&:name)
- def values_for(record) = readable(record).to_h { [it.name, it.value_for(record)] }
+ def values_for(record) = readable(record).to_h { [field_name(it), it.value_for(record)] }
def columns = Columns.for(attributes.map { it.column_for(schema) })
private
- attr_reader :attributes, :guardian, :schema
+ attr_reader :attributes, :guardian, :schema, :type, :field_names
def readable(record) = attributes.select { it.readable_for?(guardian, record) }
+
+ def field_name(attribute)
+ field_names[attribute] ||= Name::Field.new(value: attribute.name, type:)
+ end
end
end
end
diff --git a/lib/json_api_kit/declarations/fields.rb b/lib/json_api_kit/declarations/fields.rb
index f030934de70..047d31dab38 100644
--- a/lib/json_api_kit/declarations/fields.rb
+++ b/lib/json_api_kit/declarations/fields.rb
@@ -12,16 +12,19 @@ module JsonApiKit
new(names, **declarations)
end
- def initialize(names, guardian:, attributes:, relationships:, schema:)
+ def initialize(names, guardian:, attributes:, relationships:, schema:, type:)
@names = names
@guardian = guardian
@declared_attributes = attributes
@declared_relationships = relationships
@schema = schema
+ @type = type
verify_field_names
end
- def attributes = @attributes ||= Attributes.new(pick(declared_attributes), guardian:, schema:)
+ def attributes
+ @attributes ||= Attributes.new(pick(declared_attributes), guardian:, schema:, type:)
+ end
def relationships = Relationships.new(pick(declared_relationships))
@@ -29,7 +32,7 @@ module JsonApiKit
private
- attr_reader :names, :guardian, :declared_attributes, :declared_relationships, :schema
+ attr_reader :names, :guardian, :declared_attributes, :declared_relationships, :schema, :type
def pick(fields) = readable(fields).select { names.include?(it.name) }
diff --git a/lib/json_api_kit/document/resource_object.rb b/lib/json_api_kit/document/resource_object.rb
index 3456fa8dbf9..bab7bd87602 100644
--- a/lib/json_api_kit/document/resource_object.rb
+++ b/lib/json_api_kit/document/resource_object.rb
@@ -18,13 +18,11 @@ module JsonApiKit
attr_reader :record, :urls, :glossary, :meta
- def field(value) = Name::Field.new(value:, type:)
-
def relationship(value) = Name::Relationship.new(value:, type:)
def member_value(name) = glossary.member_name(name).value
- def attributes = record.attributes.transform_keys { member_value(field(it)) }
+ def attributes = glossary.member_attributes(record.attributes).transform_keys(&:value)
def relationships
record.relationships.to_h do |name, linkage|
diff --git a/lib/json_api_kit/glossary.rb b/lib/json_api_kit/glossary.rb
index 985baf4f4c5..8549970d2f0 100644
--- a/lib/json_api_kit/glossary.rb
+++ b/lib/json_api_kit/glossary.rb
@@ -40,6 +40,11 @@ module JsonApiKit
@member_names = {}
end
+ def declared_attributes(attributes)
+ attributes.each_key { declared_name(it) }
+ rules.reduce(attributes) { |result, rule| rule.declared_attributes(result) }
+ end
+
def declared_name(name)
declared_names[name] ||= rules.reduce(name) { |result, rule| rule.declared_name(result) }
rescue Correction => correction
@@ -52,6 +57,10 @@ module JsonApiKit
.reduce(name) { |result, rule| rule.member_name(result) }
end
+ def member_attributes(attributes)
+ rules.reverse_each.reduce(attributes) { |result, rule| rule.member_attributes(result) }
+ end
+
private
attr_reader :rules, :declared_names, :member_names
diff --git a/lib/json_api_kit/glossary/casing_rule.rb b/lib/json_api_kit/glossary/casing_rule.rb
index 6c4d6a0870f..39fad511454 100644
--- a/lib/json_api_kit/glossary/casing_rule.rb
+++ b/lib/json_api_kit/glossary/casing_rule.rb
@@ -5,21 +5,28 @@ module JsonApiKit
module CasingRule
CAMEL_BOUNDARY = /(?<before>[a-z\d])(?<capital>[A-Z])/
SNAKE_BOUNDARY = /_(?<letter>[a-z\d])/
+ MEMBER_NAMES = Hash.new { |cache, name| cache[name] = camel_case(name) }
class << self
+ def declared_attributes(attributes) = attributes.transform_keys { declared_name(it) }
+
def declared_name(name)
- snake_case(name).tap { raise Correction.new(it) unless member_name(it) == name }
+ snake_case(name).tap { raise Correction.new(it) unless camel_case(it) == name }
end
- def member_name(name)
- name.convert { it.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase } }
- end
+ def member_name(name) = camel_case(name)
+
+ def member_attributes(attributes) = attributes.transform_keys { MEMBER_NAMES[it] }
private
def snake_case(name)
name.convert { it.gsub(CAMEL_BOUNDARY, '\k<before>_\k<capital>').downcase }
end
+
+ def camel_case(name)
+ name.convert { it.gsub(SNAKE_BOUNDARY) { Regexp.last_match[:letter].upcase } }
+ end
end
end
end
diff --git a/lib/json_api_kit/glossary/version_rule.rb b/lib/json_api_kit/glossary/version_rule.rb
index b11a4dcc8da..483301b3390 100644
--- a/lib/json_api_kit/glossary/version_rule.rb
+++ b/lib/json_api_kit/glossary/version_rule.rb
@@ -7,6 +7,10 @@ module JsonApiKit
@changes = VersionChange.after(version)
end
+ def declared_attributes(attributes)
+ changes.reduce(attributes) { |result, change| change.current_attributes(result) }
+ end
+
def declared_name(name)
current_name(name).tap { raise Correction.new(it) unless member_name(it) == name }
end
@@ -15,6 +19,12 @@ module JsonApiKit
changes.reverse_each.reduce(name) { |result, change| change.previous(result) }
end
+ def member_attributes(attributes)
+ changes
+ .reverse_each
+ .reduce(attributes) { |result, change| change.previous_attributes(result) }
+ end
+
private
attr_reader :changes
diff --git a/lib/json_api_kit/name/anchor.rb b/lib/json_api_kit/name/anchor.rb
index 7ce5bbea41b..dd04223ccdb 100644
--- a/lib/json_api_kit/name/anchor.rb
+++ b/lib/json_api_kit/name/anchor.rb
@@ -2,11 +2,6 @@
module JsonApiKit
module Name
- Anchor =
- Data.define(:value, :type) do
- include Name
-
- def kind = :anchor
- end
+ Anchor = Data.define(:value, :type) { include Name }
end
end
diff --git a/lib/json_api_kit/name/field.rb b/lib/json_api_kit/name/field.rb
index b44a3e0bd62..f94eff145ad 100644
--- a/lib/json_api_kit/name/field.rb
+++ b/lib/json_api_kit/name/field.rb
@@ -2,11 +2,6 @@
module JsonApiKit
module Name
- Field =
- Data.define(:value, :type) do
- include Name
-
- def kind = :field
- end
+ Field = Data.define(:value, :type) { include Name }
end
end
diff --git a/lib/json_api_kit/name/filter.rb b/lib/json_api_kit/name/filter.rb
index 7af6576c613..95f29c8a40c 100644
--- a/lib/json_api_kit/name/filter.rb
+++ b/lib/json_api_kit/name/filter.rb
@@ -2,11 +2,6 @@
module JsonApiKit
module Name
- Filter =
- Data.define(:value, :type) do
- include Name
-
- def kind = :filter
- end
+ Filter = Data.define(:value, :type) { include Name }
end
end
diff --git a/lib/json_api_kit/name/member.rb b/lib/json_api_kit/name/member.rb
index 50b399d49ba..9ec2f33ee3e 100644
--- a/lib/json_api_kit/name/member.rb
+++ b/lib/json_api_kit/name/member.rb
@@ -2,11 +2,6 @@
module JsonApiKit
module Name
- Member =
- Data.define(:value) do
- include Name
-
- def kind = :member
- end
+ Member = Data.define(:value) { include Name }
end
end
diff --git a/lib/json_api_kit/name/relationship.rb b/lib/json_api_kit/name/relationship.rb
index 9703d8b9269..4c5c75f9c71 100644
--- a/lib/json_api_kit/name/relationship.rb
+++ b/lib/json_api_kit/name/relationship.rb
@@ -2,11 +2,6 @@
module JsonApiKit
module Name
- Relationship =
- Data.define(:value, :type) do
- include Name
-
- def kind = :relationship
- end
+ Relationship = Data.define(:value, :type) { include Name }
end
end
diff --git a/lib/json_api_kit/name/sort.rb b/lib/json_api_kit/name/sort.rb
index 9a6ea28f791..4525461b3e8 100644
--- a/lib/json_api_kit/name/sort.rb
+++ b/lib/json_api_kit/name/sort.rb
@@ -2,11 +2,6 @@
module JsonApiKit
module Name
- Sort =
- Data.define(:value, :type) do
- include Name
-
- def kind = :sort
- end
+ Sort = Data.define(:value, :type) { include Name }
end
end
diff --git a/lib/json_api_kit/query.rb b/lib/json_api_kit/query.rb
index bcc5858ecfa..1e5177512bf 100644
--- a/lib/json_api_kit/query.rb
+++ b/lib/json_api_kit/query.rb
@@ -13,8 +13,8 @@ module JsonApiKit
def records
@records ||=
Records.new(
- rows.map do
- Record.new(it, fields, type:, namespace:, relationships: sideloads.linkage_for(it))
+ rows.map do |row|
+ Record.new(row, fields, type:, namespace:, relationships: sideloads.linkage_for(row))
end,
)
end
diff --git a/lib/json_api_kit/request/contract/filtering.rb b/lib/json_api_kit/request/contract/filtering.rb
index 4c61916fcf2..5107166c9f4 100644
--- a/lib/json_api_kit/request/contract/filtering.rb
+++ b/lib/json_api_kit/request/contract/filtering.rb
@@ -18,8 +18,8 @@ module JsonApiKit
def check_filter_names
refuse_unknown(
:filter,
- (filter.keys - resource.filter_names).map do
- Name::Filter.new(value: it.to_s, type: resource.type)
+ (filter.keys - resource.filter_names).map do |name|
+ Name::Filter.new(value: name.to_s, type: resource.type)
end,
)
end
diff --git a/lib/json_api_kit/request/contract/paging.rb b/lib/json_api_kit/request/contract/paging.rb
index edebe2cc9bf..c000f826f30 100644
--- a/lib/json_api_kit/request/contract/paging.rb
+++ b/lib/json_api_kit/request/contract/paging.rb
@@ -102,8 +102,8 @@ module JsonApiKit
def raw_cursors = { after:, before: }.compact
def check_cursors
- (raw_cursors.keys - cursors.keys).each do
- errors.add(it, :unreadable_cursor, message: "unreadable cursor")
+ (raw_cursors.keys - cursors.keys).each do |name|
+ errors.add(name, :unreadable_cursor, message: "unreadable cursor")
end
end
diff --git a/lib/json_api_kit/request/contract/sorting.rb b/lib/json_api_kit/request/contract/sorting.rb
index 24c98de4b65..37bac101a2d 100644
--- a/lib/json_api_kit/request/contract/sorting.rb
+++ b/lib/json_api_kit/request/contract/sorting.rb
@@ -40,8 +40,8 @@ module JsonApiKit
def check_sort_names
refuse_unknown(
:sort,
- (sort.keys - resource.sort_names).map do
- Name::Sort.new(value: it.to_s, type: resource.type)
+ (sort.keys - resource.sort_names).map do |name|
+ Name::Sort.new(value: name.to_s, type: resource.type)
end,
)
end
diff --git a/lib/json_api_kit/request/family/fields.rb b/lib/json_api_kit/request/family/fields.rb
index 8d893094eaf..519f372a8d2 100644
--- a/lib/json_api_kit/request/family/fields.rb
+++ b/lib/json_api_kit/request/family/fields.rb
@@ -9,8 +9,8 @@ module JsonApiKit
value.to_h do |fieldset_type, fields|
[
fieldset_type,
- names(fields, path + [fieldset_type]) do
- Name::Field.new(value: it, type: fieldset_type)
+ names(fields, path + [fieldset_type]) do |field|
+ Name::Field.new(value: field, type: fieldset_type)
end,
]
end
diff --git a/lib/json_api_kit/request/family/page.rb b/lib/json_api_kit/request/family/page.rb
index 530b2da38f1..055d294455b 100644
--- a/lib/json_api_kit/request/family/page.rb
+++ b/lib/json_api_kit/request/family/page.rb
@@ -16,7 +16,20 @@ module JsonApiKit
private
- def anchor(value, path) = names(value, path) { Name::Anchor.new(value: it, type:) }
+ def anchor(value, path)
+ return names(value, path) { anchor_name(it) } unless value.is_a?(Hash)
+ declared_anchor(value, path)
+ end
+
+ def declared_anchor(value, path)
+ glossary.declared_attributes(value.transform_keys { anchor_name(it) }).transform_keys(
+ &:value
+ )
+ rescue Glossary::NotAMemberName => error
+ raise error.at(ParameterName.new(*path, error.raw.value).to_s)
+ end
+
+ def anchor_name(value) = Name::Anchor.new(value:, type:)
end
end
end
diff --git a/lib/json_api_kit/resource/fields.rb b/lib/json_api_kit/resource/fields.rb
index 1ce2ff8d5dd..529d2d3893b 100644
--- a/lib/json_api_kit/resource/fields.rb
+++ b/lib/json_api_kit/resource/fields.rb
@@ -42,6 +42,7 @@ module JsonApiKit
attributes: declared_attributes,
relationships: declared_relationships,
schema:,
+ type:,
)
end
diff --git a/lib/json_api_kit/sideloads.rb b/lib/json_api_kit/sideloads.rb
index 31fb2765665..112fbdeece6 100644
--- a/lib/json_api_kit/sideloads.rb
+++ b/lib/json_api_kit/sideloads.rb
@@ -4,8 +4,14 @@ module JsonApiKit
class Sideloads
def self.for(relationships, paths:, rows:, request:, schema:)
new(
- relationships.map do
- Sideload.new(it, paths: paths.next_for(it.name), rows:, request:, schema:)
+ relationships.map do |relationship|
+ Sideload.new(
+ relationship,
+ paths: paths.next_for(relationship.name),
+ rows:,
+ request:,
+ schema:,
+ )
end,
)
end
diff --git a/lib/json_api_kit/version_change.rb b/lib/json_api_kit/version_change.rb
index 06db6587afd..7e641bf2f41 100644
--- a/lib/json_api_kit/version_change.rb
+++ b/lib/json_api_kit/version_change.rb
@@ -4,6 +4,7 @@ module JsonApiKit
class VersionChange
CHANGES_DIRECTORY = Rails.root.join("config/api_changes")
DATE_PREFIX = /\A\d{4}-\d{2}-\d{2}_/
+ PASS_THROUGH = ->(_index, name) { PassThrough.new(name) }
class << self
def all = @all ||= read(CHANGES_DIRECTORY)
@@ -52,6 +53,8 @@ module JsonApiKit
def initialize(source)
@source = source
+ @upward = index_by(&:from)
+ @downward = index_by(&:to)
end
def verify!
@@ -61,20 +64,32 @@ module JsonApiKit
raise ArgumentError, "#{source} is dated on or before the first release."
end
raise ArgumentError, "#{source} has no description." if description.blank?
+ duplicate_name(:from).try { raise ArgumentError, "#{source} renames #{it} twice." }
+ duplicate_name(:to).try { raise ArgumentError, "#{source} renames two names to #{it}." }
return if File.basename(source).start_with?(version.to_s)
raise ArgumentError, "The file name must start with the version #{version}: #{source}."
end
- def current(name)
- transformations.reduce(name) { |result, transformation| transformation.current(result) }
+ def current(name) = upward[name].current
+
+ def current_attributes(attributes)
+ attributes.flat_map { |name, value| upward[name].current_pairs(value) }.to_h
end
- def previous(name)
- transformations
- .reverse_each
- .reduce(name) { |result, transformation| transformation.previous(result) }
+ def previous(name) = downward[name].previous
+
+ def previous_attributes(attributes)
+ attributes.flat_map { |name, value| downward[name].previous_pairs(value) }.to_h
end
- def introduces?(name) = transformations.any? { it.introduces?(name) }
+ private
+
+ attr_reader :upward, :downward
+
+ def index_by(&) = transformations.index_by(&).tap { it.default_proc = PASS_THROUGH }
+
+ def duplicate_name(field)
+ transformations.map(&field).tally.detect { |_name, count| count > 1 }&.first
+ end
end
end
diff --git a/lib/json_api_kit/version_change/declarations.rb b/lib/json_api_kit/version_change/declarations.rb
index 50aa15ea8bc..7890225a357 100644
--- a/lib/json_api_kit/version_change/declarations.rb
+++ b/lib/json_api_kit/version_change/declarations.rb
@@ -3,16 +3,28 @@
module JsonApiKit
class VersionChange
class Declarations
- DERIVED_FROM_AN_ATTRIBUTE = %i[field sort anchor].freeze
+ DERIVED_FROM_AN_ATTRIBUTE = [Name::Field, Name::Sort, Name::Anchor].freeze
+ NO_CONVERSION = ->(value) { value }
def initialize(type)
@type = type.to_s
@transformations = []
end
- def renamed_attribute(from:, to:)
- DERIVED_FROM_AN_ATTRIBUTE.each do
- transformations << Rename.new(kind: it, type:, from: from.to_s, to: to.to_s)
+ def renamed_attribute(from:, to:, up: NO_CONVERSION, down: NO_CONVERSION)
+ if [up, down].count(NO_CONVERSION) == 1
+ raise ArgumentError, "Declare both up: and down: to rename #{from} to #{to}."
+ end
+ unless [up, down].all? { it.respond_to?(:call) }
+ raise ArgumentError, "up: and down: must respond to call, to rename #{from} to #{to}."
+ end
+ DERIVED_FROM_AN_ATTRIBUTE.each do |kind|
+ transformations << Rename.new(
+ from: kind.new(value: from.to_s, type:),
+ to: kind.new(value: to.to_s, type:),
+ up:,
+ down:,
+ )
end
end
diff --git a/lib/json_api_kit/version_change/pass_through.rb b/lib/json_api_kit/version_change/pass_through.rb
new file mode 100644
index 00000000000..369ca575edd
--- /dev/null
+++ b/lib/json_api_kit/version_change/pass_through.rb
@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module JsonApiKit
+ class VersionChange
+ PassThrough =
+ Data.define(:name) do
+ def current = name
+
+ def current_pairs(value) = [[name, value]]
+
+ def previous = name
+
+ def previous_pairs(value) = [[name, value]]
+ end
+ end
+end
diff --git a/lib/json_api_kit/version_change/rename.rb b/lib/json_api_kit/version_change/rename.rb
index bb0749e2cf8..804f998de73 100644
--- a/lib/json_api_kit/version_change/rename.rb
+++ b/lib/json_api_kit/version_change/rename.rb
@@ -3,22 +3,14 @@
module JsonApiKit
class VersionChange
Rename =
- Data.define(:kind, :type, :from, :to) do
- def current(name)
- return name unless applies_to?(name) && name.value == from
- name.with(value: to)
- end
+ Data.define(:from, :to, :up, :down) do
+ def current = to
- def previous(name)
- return name unless introduces?(name)
- name.with(value: from)
- end
+ def current_pairs(value) = [[to, up.call(value)]]
- def introduces?(name) = applies_to?(name) && name.value == to
+ def previous = from
- private
-
- def applies_to?(name) = name.kind == kind && name.type == type
+ def previous_pairs(value) = [[from, down.call(value)]]
end
end
end
diff --git a/spec/fixtures/json_api_kit/api_changes_with_two_renames_from_one_name/2026-09-02_two_renames_from_one_name.rb b/spec/fixtures/json_api_kit/api_changes_with_two_renames_from_one_name/2026-09-02_two_renames_from_one_name.rb
new file mode 100644
index 00000000000..16fe00746c1
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_with_two_renames_from_one_name/2026-09-02_two_renames_from_one_name.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class TwoRenamesFromOneName < JsonApiKit::VersionChange
+ version "2026-09-02"
+ description "A change that renames one attribute twice."
+
+ resource :widgets do
+ renamed_attribute from: :label, to: :name
+ renamed_attribute from: :label, to: :title
+ end
+end
diff --git a/spec/fixtures/json_api_kit/api_changes_with_two_renames_to_one_name/2026-09-02_two_renames_to_one_name.rb b/spec/fixtures/json_api_kit/api_changes_with_two_renames_to_one_name/2026-09-02_two_renames_to_one_name.rb
new file mode 100644
index 00000000000..348d37e7fc0
--- /dev/null
+++ b/spec/fixtures/json_api_kit/api_changes_with_two_renames_to_one_name/2026-09-02_two_renames_to_one_name.rb
@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class TwoRenamesToOneName < JsonApiKit::VersionChange
+ version "2026-09-02"
+ description "A change that renames two attributes to one name."
+
+ resource :widgets do
+ renamed_attribute from: :label, to: :title
+ renamed_attribute from: :caption, to: :title
+ end
+end
diff --git a/spec/integration/json_api_kit/version_changes_spec.rb b/spec/integration/json_api_kit/version_changes_spec.rb
index 5c00ea5f1ee..a4b20e61f28 100644
--- a/spec/integration/json_api_kit/version_changes_spec.rb
+++ b/spec/integration/json_api_kit/version_changes_spec.rb
@@ -13,6 +13,10 @@ module JsonApiKitSpec
resource :topics do
renamed_attribute from: :posted_at, to: :created_at
+ renamed_attribute from: :words,
+ to: :title,
+ down: ->(title) { title.to_s.split(" ") },
+ up: ->(words) { words.to_a.join(" ") }
end
end
end
@@ -48,7 +52,27 @@ RSpec.describe "JSON:API version changes", type: :request do
end
it "sends the attributes under the names of that version" do
- expect(attributes.keys).to contain_exactly("title", "postedAt")
+ expect(attributes.keys).to contain_exactly("words", "postedAt")
+ end
+
+ it "sends a reshaped attribute in the shape of that version" do
+ expect(attributes["words"]).to eq(%w[Bands of a segmented listing])
+ end
+
+ context "when the request selects the reshaped field" do
+ let(:query) { { "fields" => { "topics" => "words" } } }
+
+ it "sends that field only" do
+ expect(attributes.keys).to contain_exactly("words")
+ end
+ end
+
+ context "when the request sorts by the reshaped field" do
+ let(:query) { { "sort" => "words" } }
+
+ it "orders the rows by that attribute" do
+ expect(ids).to eq([oldest.id.to_s, newest.id.to_s, middle.id.to_s])
+ end
end
context "when the request selects the renamed field" do
@@ -86,10 +110,29 @@ RSpec.describe "JSON:API version changes", type: :request do
end
end
+ context "when the request anchors a window on the reshaped field" do
+ let(:query) do
+ {
+ "sort" => "words",
+ "page" => {
+ "anchor" => {
+ "words" => %w[Bands of a segmented listing],
+ },
+ "beforeSize" => "1",
+ "afterSize" => "0",
+ },
+ }
+ end
+
+ it "sends the rows of the window" do
+ expect(ids).to eq([oldest.id.to_s, newest.id.to_s])
+ end
+ end
+
context "when a refusal includes the renamed field" do
let(:query) do
{
- "sort" => "title",
+ "sort" => "words",
"page" => {
"anchor" => {
"postedAt" => middle.created_at.iso8601(6),
@@ -102,7 +145,7 @@ RSpec.describe "JSON:API version changes", type: :request do
expect(error).to eq(
refusal(
title: "Anchor does not match the sort",
- detail: "The anchor is postedAt, but this request sorts by title.",
+ detail: "The anchor is postedAt, but this request sorts by words.",
parameter: "page[anchor][postedAt]",
).deep_stringify_keys,
)
@@ -134,7 +177,7 @@ RSpec.describe "JSON:API version changes", type: :request do
end
it "sends the attributes under the names of the first version" do
- expect(attributes.keys).to contain_exactly("title", "postedAt")
+ expect(attributes.keys).to contain_exactly("words", "postedAt")
end
end
diff --git a/spec/lib/json_api_kit/declarations/attributes_spec.rb b/spec/lib/json_api_kit/declarations/attributes_spec.rb
index 82da7b9ee7f..f03472b196b 100644
--- a/spec/lib/json_api_kit/declarations/attributes_spec.rb
+++ b/spec/lib/json_api_kit/declarations/attributes_spec.rb
@@ -1,7 +1,7 @@
# frozen_string_literal: true
RSpec.describe JsonApiKit::Declarations::Attributes do
- subject(:attributes) { described_class.new(declarations, guardian:, schema:) }
+ subject(:attributes) { described_class.new(declarations, guardian:, schema:, type: "topics") }
fab!(:topic) { Fabricate(:topic, title: "A field rendered from a record", closed: false) }
@@ -9,6 +9,8 @@ RSpec.describe JsonApiKit::Declarations::Attributes do
let(:schema) { JsonApiKit::Schema.new(Topic) }
let(:attribute) { JsonApiKit::Declarations::Attribute }
let(:declarations) { [attribute.new(:title), attribute.new(:closed)] }
+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }
+ let(:closed) { JsonApiKit::Name::Field.new(value: "closed", type: "topics") }
describe "#columns" do
subject(:columns) { attributes.columns }
@@ -29,8 +31,16 @@ RSpec.describe JsonApiKit::Declarations::Attributes do
describe "#values_for" do
subject(:attribute_values) { attributes.values_for(topic) }
- it "returns the value of every field it holds" do
- expect(attribute_values).to eq("title" => topic.title, "closed" => false)
+ it "returns the value of every field it holds, under its name" do
+ expect(attribute_values).to eq(title => topic.title, closed => false)
+ end
+
+ context "with a second record" do
+ fab!(:other_topic) { Fabricate(:topic, title: "Another field rendered from a record") }
+
+ it "builds the name of a field once" do
+ expect(attribute_values.keys.first).to equal(attributes.values_for(other_topic).keys.first)
+ end
end
context "when it holds no field" do
diff --git a/spec/lib/json_api_kit/declarations/fields_spec.rb b/spec/lib/json_api_kit/declarations/fields_spec.rb
index 2ce5a70d8b1..217250e36e4 100644
--- a/spec/lib/json_api_kit/declarations/fields_spec.rb
+++ b/spec/lib/json_api_kit/declarations/fields_spec.rb
@@ -1,7 +1,9 @@
# frozen_string_literal: true
RSpec.describe JsonApiKit::Declarations::Fields do
- subject(:fields) { described_class.for(names, guardian:, attributes:, relationships:, schema:) }
+ subject(:fields) do
+ described_class.for(names, guardian:, attributes:, relationships:, schema:, type: "topics")
+ end
let(:guardian) { Guardian.new }
@@ -26,7 +28,7 @@ RSpec.describe JsonApiKit::Declarations::Fields do
[JsonApiKit::Declarations::Relationship::ToOne.new(:title, resource: users_resource)]
end
- it "refuses the declaration" do
+ it "raises a collision" do
expect { fields }.to raise_error(described_class::Collision, /title/)
end
end
@@ -39,7 +41,7 @@ RSpec.describe JsonApiKit::Declarations::Fields do
]
end
- it "refuses the declaration" do
+ it "raises a collision" do
expect { fields }.to raise_error(described_class::Collision, /title/)
end
end
@@ -52,24 +54,24 @@ RSpec.describe JsonApiKit::Declarations::Fields do
]
end
- it "refuses the declaration" do
+ it "raises a collision" do
expect { fields }.to raise_error(described_class::Collision, /id, type/)
end
end
end
describe "#attributes" do
- subject(:attribute_values) { fields.attributes.values_for(topic) }
+ subject(:attribute_names) { fields.attributes.values_for(topic).keys.map(&:value) }
it "holds every field the resource declares" do
- expect(attribute_values.keys).to eq(%w[title closed])
+ expect(attribute_names).to eq(%w[title closed])
end
context "when the fieldset holds one field" do
let(:names) { %w[title] }
it "holds only those" do
- expect(attribute_values.keys).to eq(%w[title])
+ expect(attribute_names).to eq(%w[title])
end
end
@@ -77,7 +79,7 @@ RSpec.describe JsonApiKit::Declarations::Fields do
let(:names) { %w[closed title] }
it "holds them in the order the resource declares" do
- expect(attribute_values.keys).to eq(%w[title closed])
+ expect(attribute_names).to eq(%w[title closed])
end
end
@@ -85,7 +87,7 @@ RSpec.describe JsonApiKit::Declarations::Fields do
let(:names) { %w[title secrets] }
it "leaves that name out" do
- expect(attribute_values.keys).to eq(%w[title])
+ expect(attribute_names).to eq(%w[title])
end
end
@@ -93,7 +95,7 @@ RSpec.describe JsonApiKit::Declarations::Fields do
let(:names) { [] }
it "holds no field" do
- expect(attribute_values).to be_empty
+ expect(attribute_names).to be_empty
end
end
end
diff --git a/spec/lib/json_api_kit/document/contents_spec.rb b/spec/lib/json_api_kit/document/contents_spec.rb
index 7ff1ab81d0e..b3455e6efb0 100644
--- a/spec/lib/json_api_kit/document/contents_spec.rb
+++ b/spec/lib/json_api_kit/document/contents_spec.rb
@@ -12,7 +12,6 @@ RSpec.describe JsonApiKit::Document::Contents do
let(:other_topic_record) { record_of(other_topic, "topics") }
let(:records) { [record_of(topic, "topics", "user" => linkage(author_record))] }
let(:related_records) { [author_record] }
-
let(:guardian) { Guardian.new }
def record_of(model, type, relationships = {})
@@ -24,6 +23,7 @@ RSpec.describe JsonApiKit::Document::Contents do
attributes: [],
relationships: [],
schema: JsonApiKit::Schema.new(model.class),
+ type:,
),
type:,
relationships:,
@@ -37,7 +37,7 @@ RSpec.describe JsonApiKit::Document::Contents do
expect(contents.primary.map(&:record)).to eq([topic])
end
- context "when a path reads a primary record a second time" do
+ context "when a path holds a primary record a second time" do
let(:related_records) { [author_record, record_of(topic, "topics", "tags" => linkage)] }
it "holds the relationships of both readings" do
@@ -59,7 +59,7 @@ RSpec.describe JsonApiKit::Document::Contents do
expect(contents.related.map(&:record)).to eq([author])
end
- context "when a path reads a primary record a second time" do
+ context "when a path holds a primary record a second time" do
let(:related_records) { [author_record, record_of(topic, "topics")] }
it "drops that record" do
@@ -84,7 +84,7 @@ RSpec.describe JsonApiKit::Document::Contents do
end
end
- context "when two paths read one record" do
+ context "when two paths hold one record" do
let(:related_records) do
[author_record, record_of(author, "users", "groups" => linkage(record_of(group, "groups")))]
end
diff --git a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb b/spec/lib/json_api_kit/glossary/casing_rule_spec.rb
index 9e858cc031a..a2de4fd0020 100644
--- a/spec/lib/json_api_kit/glossary/casing_rule_spec.rb
+++ b/spec/lib/json_api_kit/glossary/casing_rule_spec.rb
@@ -5,6 +5,20 @@ RSpec.describe JsonApiKit::Glossary::CasingRule do
let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }
let(:value) { "createdAt" }
+ describe "#declared_attributes" do
+ subject(:declared_attributes) { rule.declared_attributes(name => "2026-08-01") }
+
+ it "returns the attributes with their names in snake case" do
+ expect(declared_attributes).to eq(name.with(value: "created_at") => "2026-08-01")
+ end
+
+ context "when a name has an underscore" do
+ let(:value) { "created_at" }
+
+ it { expect { declared_attributes }.to raise_error(JsonApiKit::Glossary::Correction) }
+ end
+ end
+
describe "#declared_name" do
subject(:declared_name) { rule.declared_name(name) }
@@ -57,6 +71,29 @@ RSpec.describe JsonApiKit::Glossary::CasingRule do
expect { declared_name }.to raise_error(having_attributes(name:))
end
end
+
+ context "when the name comes from a client" do
+ let(:value) { "sentByClient" }
+
+ it "adds nothing to the memo" do
+ expect { declared_name }.not_to change(described_class::MEMBER_NAMES, :size)
+ end
+ end
+ end
+
+ describe "#member_attributes" do
+ subject(:member_attributes) { rule.member_attributes(attributes) }
+
+ let(:attributes) { { name => "2026-08-01" } }
+ let(:value) { "created_at" }
+
+ it "returns the attributes with their names in camel case" do
+ expect(member_attributes).to eq(name.with(value: "createdAt") => "2026-08-01")
+ end
+
+ it "returns the same object for a name it converted before" do
+ expect(member_attributes.keys.first).to equal(rule.member_attributes(attributes).keys.first)
+ end
end
describe "#member_name" do
@@ -83,5 +120,13 @@ RSpec.describe JsonApiKit::Glossary::CasingRule do
expect(member_name).to eq(name)
end
end
+
+ context "when the name comes from a client" do
+ let(:value) { "named_by_client" }
+
+ it "adds nothing to the memo" do
+ expect { member_name }.not_to change(described_class::MEMBER_NAMES, :size)
+ end
+ end
end
end
diff --git a/spec/lib/json_api_kit/glossary/version_rule_spec.rb b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
index b3e9a53b532..60c6431fb57 100644
--- a/spec/lib/json_api_kit/glossary/version_rule_spec.rb
+++ b/spec/lib/json_api_kit/glossary/version_rule_spec.rb
@@ -53,6 +53,14 @@ RSpec.describe JsonApiKit::Glossary::VersionRule do
)
end
+ describe "#declared_attributes" do
+ subject(:declared_attributes) { rule.declared_attributes(name => "2026-08-01") }
+
+ it "returns the attributes with their current names" do
+ expect(declared_attributes).to eq(name.with(value: "published_at") => "2026-08-01")
+ end
+ end
+
describe "#declared_name" do
subject(:declared_name) { rule.declared_name(name) }
@@ -65,7 +73,7 @@ RSpec.describe JsonApiKit::Glossary::VersionRule do
let(:second_change) { JsonApiKitSpec::LabelToNameChange.new(__FILE__) }
let(:value) { "name" }
- it "returns the current name of the old name" do
+ it "returns the current name" do
expect(declared_name).to eq(name.with(value: "title"))
end
@@ -97,6 +105,16 @@ RSpec.describe JsonApiKit::Glossary::VersionRule do
end
end
+ describe "#member_attributes" do
+ subject(:member_attributes) { rule.member_attributes(name => "2026-08-01") }
+
+ let(:value) { "published_at" }
+
+ it "returns the attributes with the names of this version" do
+ expect(member_attributes).to eq(name.with(value: "posted_at") => "2026-08-01")
+ end
+ end
+
describe "#member_name" do
subject(:member_name) { rule.member_name(name) }
diff --git a/spec/lib/json_api_kit/glossary_spec.rb b/spec/lib/json_api_kit/glossary_spec.rb
index 52610724c62..4407d61444c 100644
--- a/spec/lib/json_api_kit/glossary_spec.rb
+++ b/spec/lib/json_api_kit/glossary_spec.rb
@@ -6,6 +6,10 @@ module JsonApiKitSpec
def declared_name(name) = name.convert { "#{it}<#{mark}" }
def member_name(name) = name.convert { "#{it}>#{mark}" }
+
+ def declared_attributes(attributes) = attributes.transform_keys { declared_name(it) }
+
+ def member_attributes(attributes) = attributes.transform_keys { member_name(it) }
end
class GlossaryChange < JsonApiKit::VersionChange
@@ -17,6 +21,18 @@ module JsonApiKitSpec
end
end
+ class GlossaryShapeChange < JsonApiKit::VersionChange
+ version "2026-09-15"
+ description "The `words` attribute of the topics resource becomes `title`, a string."
+
+ resource :topics do
+ renamed_attribute from: :words,
+ to: :title,
+ down: ->(title) { title.to_s.split(" ") },
+ up: ->(words) { words.to_a.join(" ") }
+ end
+ end
+
class GlossaryReuseChange < JsonApiKit::VersionChange
version "2026-10-01"
description "The `label` attribute of the topics resource is renamed to `posted_at`."
@@ -67,6 +83,60 @@ RSpec.describe JsonApiKit::Glossary do
end
end
+ describe "#declared_attributes" do
+ subject(:declared_attributes) { glossary.declared_attributes(attributes) }
+
+ let(:attributes) { { name => "Anchors and pages" } }
+
+ it "returns the attributes with their declared names" do
+ expect(declared_attributes).to eq(name.with(value: "created_at") => "Anchors and pages")
+ end
+
+ context "when a name is not a member name" do
+ let(:value) { "created_at" }
+
+ it "raises with the member name to use" do
+ expect { declared_attributes }.to raise_error(/Use createdAt, not created_at\./)
+ end
+ end
+
+ context "with a version rule" do
+ subject(:glossary) { described_class.resource(version) }
+
+ let(:attributes) { { name => %w[Anchors and pages] } }
+ let(:value) { "words" }
+
+ before do
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ [JsonApiKitSpec::GlossaryShapeChange.new(__FILE__)],
+ )
+ end
+
+ it "returns the attributes with the current names and shapes" do
+ expect(declared_attributes).to eq(name.with(value: "title") => "Anchors and pages")
+ end
+
+ context "when a name belongs to a later version" do
+ let(:value) { "title" }
+
+ it "raises with the name of this version" do
+ expect { declared_attributes }.to raise_error(/Use words, not title\./)
+ end
+ end
+ end
+
+ context "with several rules" do
+ subject(:glossary) { described_class.new([mark_a, mark_b]) }
+
+ let(:mark_a) { JsonApiKitSpec::MarkingRule.new("a") }
+ let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
+
+ it "applies them in order" do
+ expect(declared_attributes).to eq(name.with(value: "createdAt<a<b") => "Anchors and pages")
+ end
+ end
+ end
+
describe "#declared_name" do
subject(:declared_name) { glossary.declared_name(name) }
@@ -150,7 +220,7 @@ RSpec.describe JsonApiKit::Glossary do
)
end
- it "suggests the name of this version, converted once" do
+ it "suggests the name of this version, on the wire" do
expect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)
end
end
@@ -168,6 +238,41 @@ RSpec.describe JsonApiKit::Glossary do
end
end
+ describe "#member_attributes" do
+ subject(:member_attributes) { glossary.member_attributes(name => "Anchors and pages") }
+
+ let(:value) { "title" }
+
+ it "returns the attributes with their member names" do
+ expect(member_attributes).to eq(name => "Anchors and pages")
+ end
+
+ context "with a version rule" do
+ subject(:glossary) { described_class.resource(version) }
+
+ before do
+ allow(JsonApiKit::VersionChange).to receive(:after).with(version).and_return(
+ [JsonApiKitSpec::GlossaryShapeChange.new(__FILE__)],
+ )
+ end
+
+ it "returns the attributes with the names and the values of this version, on the wire" do
+ expect(member_attributes).to eq(name.with(value: "words") => %w[Anchors and pages])
+ end
+ end
+
+ context "with several rules" do
+ subject(:glossary) { described_class.new([mark_a, mark_b]) }
+
+ let(:mark_a) { JsonApiKitSpec::MarkingRule.new("a") }
+ let(:mark_b) { JsonApiKitSpec::MarkingRule.new("b") }
+
+ it "applies them in reverse order" do
+ expect(member_attributes).to eq(name.with(value: "title>b>a") => "Anchors and pages")
+ end
+ end
+ end
+
describe "#member_name" do
subject(:member_name) { glossary.member_name(name) }
diff --git a/spec/lib/json_api_kit/included_spec.rb b/spec/lib/json_api_kit/included_spec.rb
index 54005af4bea..03953e468d8 100644
--- a/spec/lib/json_api_kit/included_spec.rb
+++ b/spec/lib/json_api_kit/included_spec.rb
@@ -10,7 +10,6 @@ RSpec.describe JsonApiKit::Included do
let(:author_record) { record_of(author, "users") }
let(:records) { [record_of(topic, "topics", "user" => linkage(author_record))] }
-
let(:guardian) { Guardian.new }
def record_of(model, type, relationships = {})
@@ -22,6 +21,7 @@ RSpec.describe JsonApiKit::Included do
attributes: [],
relationships: [],
schema: JsonApiKit::Schema.new(model.class),
+ type:,
),
type:,
relationships:,
diff --git a/spec/lib/json_api_kit/name/anchor_spec.rb b/spec/lib/json_api_kit/name/anchor_spec.rb
index c39281f6399..e53299e1125 100644
--- a/spec/lib/json_api_kit/name/anchor_spec.rb
+++ b/spec/lib/json_api_kit/name/anchor_spec.rb
@@ -5,5 +5,5 @@ require_relative "support"
RSpec.describe JsonApiKit::Name::Anchor do
subject(:name) { described_class.new(value: "posted_at", type: "topics") }
- it_behaves_like "a name", :anchor
+ it_behaves_like "a name"
end
diff --git a/spec/lib/json_api_kit/name/field_spec.rb b/spec/lib/json_api_kit/name/field_spec.rb
index e3b30d135a7..0d6527499c1 100644
--- a/spec/lib/json_api_kit/name/field_spec.rb
+++ b/spec/lib/json_api_kit/name/field_spec.rb
@@ -5,5 +5,5 @@ require_relative "support"
RSpec.describe JsonApiKit::Name::Field do
subject(:name) { described_class.new(value: "posted_at", type: "topics") }
- it_behaves_like "a name", :field
+ it_behaves_like "a name"
end
diff --git a/spec/lib/json_api_kit/name/filter_spec.rb b/spec/lib/json_api_kit/name/filter_spec.rb
index ac22a60d0f5..e65a75fb3c3 100644
--- a/spec/lib/json_api_kit/name/filter_spec.rb
+++ b/spec/lib/json_api_kit/name/filter_spec.rb
@@ -5,5 +5,5 @@ require_relative "support"
RSpec.describe JsonApiKit::Name::Filter do
subject(:name) { described_class.new(value: "posted_at", type: "topics") }
- it_behaves_like "a name", :filter
+ it_behaves_like "a name"
end
diff --git a/spec/lib/json_api_kit/name/member_spec.rb b/spec/lib/json_api_kit/name/member_spec.rb
index 1ca32cff057..930d8eb0989 100644
--- a/spec/lib/json_api_kit/name/member_spec.rb
+++ b/spec/lib/json_api_kit/name/member_spec.rb
@@ -5,5 +5,5 @@ require_relative "support"
RSpec.describe JsonApiKit::Name::Member do
subject(:name) { described_class.new(value: "after_size") }
- it_behaves_like "a name", :member
+ it_behaves_like "a name"
end
diff --git a/spec/lib/json_api_kit/name/relationship_spec.rb b/spec/lib/json_api_kit/name/relationship_spec.rb
index 8d41e7517ed..bddee583ce3 100644
--- a/spec/lib/json_api_kit/name/relationship_spec.rb
+++ b/spec/lib/json_api_kit/name/relationship_spec.rb
@@ -5,5 +5,5 @@ require_relative "support"
RSpec.describe JsonApiKit::Name::Relationship do
subject(:name) { described_class.new(value: "posted_at", type: "topics") }
- it_behaves_like "a name", :relationship
+ it_behaves_like "a name"
end
diff --git a/spec/lib/json_api_kit/name/sort_spec.rb b/spec/lib/json_api_kit/name/sort_spec.rb
index 79ec71ca4cc..a8f4b6091b2 100644
--- a/spec/lib/json_api_kit/name/sort_spec.rb
+++ b/spec/lib/json_api_kit/name/sort_spec.rb
@@ -5,5 +5,5 @@ require_relative "support"
RSpec.describe JsonApiKit::Name::Sort do
subject(:name) { described_class.new(value: "posted_at", type: "topics") }
- it_behaves_like "a name", :sort
+ it_behaves_like "a name"
end
diff --git a/spec/lib/json_api_kit/name/support.rb b/spec/lib/json_api_kit/name/support.rb
index 5148140a637..f5bd207dd19 100644
--- a/spec/lib/json_api_kit/name/support.rb
+++ b/spec/lib/json_api_kit/name/support.rb
@@ -1,12 +1,6 @@
# frozen_string_literal: true
-RSpec.shared_examples "a name" do |kind|
- describe "#kind" do
- it "returns #{kind.inspect}" do
- expect(name.kind).to eq(kind)
- end
- end
-
+RSpec.shared_examples "a name" do
describe "#convert" do
it "returns the name with the converted value" do
expect(name.convert(&:upcase)).to eq(name.with(value: name.value.upcase))
diff --git a/spec/lib/json_api_kit/query/collection_spec.rb b/spec/lib/json_api_kit/query/collection_spec.rb
index e702ceefcce..cbb290ee306 100644
--- a/spec/lib/json_api_kit/query/collection_spec.rb
+++ b/spec/lib/json_api_kit/query/collection_spec.rb
@@ -31,7 +31,7 @@ RSpec.describe JsonApiKit::Query::Collection do
describe ".new" do
let(:params) { { sort: { secrets: :asc } } }
- it "reads nothing before a caller asks for records" do
+ it "queries nothing before a caller asks for records" do
expect { query }.not_to raise_error
end
end
@@ -86,11 +86,11 @@ RSpec.describe JsonApiKit::Query::Collection do
expect(previous_cursor).to be_nil
end
- context "when a caller reads from further into the listing" do
+ context "when a caller starts further into the listing" do
let(:first_cursor) { described_class.new(resource, request_for({})).rows.first.cursor.to_s }
let(:params) { { page: { size: 2, after: first_cursor } } }
- it "returns the cursor that reads the page before it" do
+ it "returns the cursor of the page before it" do
expect(previous_cursor).to be_present
end
end
@@ -109,9 +109,10 @@ RSpec.describe JsonApiKit::Query::Collection do
attribute :closed
end
end
+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }
- it "renders every row in the order the listing reads them" do
- expect(fields.map { it["title"] }).to eq(
+ it "renders every row in the order of the listing" do
+ expect(fields.map { it[title] }).to eq(
[first_topic.title, second_topic.title, third_topic.title],
)
end
@@ -120,10 +121,10 @@ RSpec.describe JsonApiKit::Query::Collection do
let(:params) { { fields: { topics: %w[title] } } }
it "renders only those fields" do
- expect(fields.first.keys).to contain_exactly("title")
+ expect(fields.first.keys).to contain_exactly(title)
end
- it "reads only the columns those fields and the order need" do
+ it "selects only the columns those fields and the order need" do
expect(query.records.first.record.attributes.keys).to contain_exactly(
"id",
"title",
@@ -145,7 +146,7 @@ RSpec.describe JsonApiKit::Query::Collection do
end
let(:params) { { fields: { topics: %w[title slug] } } }
- it "reads the whole row" do
+ it "selects every column" do
expect(query.records.first.record.attributes.keys).to include("closed", "views")
end
end
@@ -154,22 +155,22 @@ RSpec.describe JsonApiKit::Query::Collection do
describe "#records" do
subject(:records) { query.records.map(&:record) }
- it "reads the rows the resource exposes in the order it declares" do
+ it "returns the rows the resource exposes in the order it declares" do
expect(records).to eq([first_topic, second_topic, third_topic])
end
context "when the sort holds a key" do
let(:params) { { sort: { created_at: :desc } } }
- it "reads the rows that way" do
+ it "returns the rows in that order" do
expect(records).to eq([third_topic, second_topic, first_topic])
end
end
- context "when the resource is read as part of another listing" do
+ context "when another listing scopes the resource" do
let(:scoped_to) { Topic.where(id: [first_topic.id, third_topic.id]) }
- it "reads only the rows both allow" do
+ it "returns only the rows both allow" do
expect(records).to eq([first_topic, third_topic])
end
end
@@ -177,7 +178,7 @@ RSpec.describe JsonApiKit::Query::Collection do
context "when the page holds a size" do
let(:params) { { page: { size: 2 } } }
- it "reads only that many rows" do
+ it "returns only that many rows" do
expect(records).to eq([first_topic, second_topic])
end
end
@@ -186,7 +187,7 @@ RSpec.describe JsonApiKit::Query::Collection do
let(:resource) { Class.new(super()) { filter :title } }
let(:params) { { filter: { title: second_topic.title } } }
- it "reads only the rows that filter keeps" do
+ it "returns only the rows that filter keeps" do
expect(records).to eq([second_topic])
end
end
@@ -197,7 +198,7 @@ RSpec.describe JsonApiKit::Query::Collection do
end
let(:guardian) { Guardian.new(second_topic.user) }
- it "reads only the rows that scope exposes" do
+ it "returns only the rows that scope exposes" do
expect(records).to eq([second_topic])
end
end
diff --git a/spec/lib/json_api_kit/query/individual_spec.rb b/spec/lib/json_api_kit/query/individual_spec.rb
index 79d16d3235f..5ffd9540faf 100644
--- a/spec/lib/json_api_kit/query/individual_spec.rb
+++ b/spec/lib/json_api_kit/query/individual_spec.rb
@@ -16,6 +16,7 @@ RSpec.describe JsonApiKit::Query::Individual do
let(:request) { JsonApiKit::Request::Individual.new(params, guardian:) }
let(:params) { { id: topic.id } }
let(:guardian) { Guardian.new }
+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }
describe "#record" do
it "returns the record with that id" do
@@ -23,13 +24,13 @@ RSpec.describe JsonApiKit::Query::Individual do
end
it "renders it with the fields the resource declares" do
- expect(reading.record.attributes).to eq("title" => topic.title)
+ expect(reading.record.attributes).to eq(title => topic.title)
end
context "when nothing is there under that id" do
let(:params) { { id: -1 } }
- it "refuses the request instead of answering with nothing" do
+ it "raises not found instead of answering with nothing" do
expect { reading.record }.to raise_error(JsonApiKit::NotFound)
end
end
@@ -37,7 +38,7 @@ RSpec.describe JsonApiKit::Query::Individual do
context "when the scope withholds the row" do
let(:resource) { Class.new(super()) { scope { Topic.where(closed: true) } } }
- it "refuses the request instead of answering with nothing" do
+ it "raises not found instead of answering with nothing" do
expect { reading.record }.to raise_error(JsonApiKit::NotFound)
end
end
diff --git a/spec/lib/json_api_kit/record_spec.rb b/spec/lib/json_api_kit/record_spec.rb
index 552b53c8fdc..5684370a3cf 100644
--- a/spec/lib/json_api_kit/record_spec.rb
+++ b/spec/lib/json_api_kit/record_spec.rb
@@ -33,10 +33,11 @@ RSpec.describe JsonApiKit::Record do
end
let(:relationships) { {} }
let(:namespace) { nil }
+ let(:title) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }
describe "#attributes" do
it "renders the fields that the resource declares" do
- expect(record.attributes).to eq("title" => topic.title)
+ expect(record.attributes).to eq(title => topic.title)
end
end
@@ -98,7 +99,7 @@ RSpec.describe JsonApiKit::Record do
end
it "renders its own fields" do
- expect(merged.attributes).to eq("title" => topic.title)
+ expect(merged.attributes).to eq(title => topic.title)
end
it "leaves this record unchanged" do
diff --git a/spec/lib/json_api_kit/request/contract/collection_spec.rb b/spec/lib/json_api_kit/request/contract/collection_spec.rb
index 697dead9842..4a6a33595c6 100644
--- a/spec/lib/json_api_kit/request/contract/collection_spec.rb
+++ b/spec/lib/json_api_kit/request/contract/collection_spec.rb
@@ -39,7 +39,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
context "when a parameter is unknown" do
let(:params) { { sorts: { created_at: :asc } } }
- it "refuses the parameter" do
+ it "adds an error on the parameter" do
expect(contract).to be_invalid
expect(contract.errors).to include(:sorts)
end
@@ -48,7 +48,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
context "when a page parameter is unknown" do
let(:params) { { page: { sise: 2 } } }
- it "refuses it under the parameter it came in" do
+ it "adds an error under the parameter it came in" do
expect(contract).to be_invalid
expect(contract.errors).to include(:"page.sise")
end
@@ -88,7 +88,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
expect(contract.sort).to eq("created_at" => :desc, "title" => :asc)
end
- context "when there’s a hyphen in the sort name" do
+ context "when the sort name has a hyphen" do
let(:params) { { sort: "last-posted-at" } }
it "converts it as a hash" do
@@ -96,7 +96,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
end
end
- context "when there’s also a cursor" do
+ context "when a cursor comes with the sort" do
let(:params) { { sort: "title", page: { after: cursor } } }
it "checks the cursor against that sort" do
@@ -158,7 +158,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
end
end
- context "when fieldset is a list of symbols" do
+ context "when fieldset is a list of symbols" do
let(:params) { { fields: { topics: %i[title] } } }
it "converts it as a list of fields" do
@@ -174,6 +174,12 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
before { contract.valid? }
+ it { is_expected.to validate_length_of(:anchor).as_array.is_equal_to(1).allow_nil }
+ it { is_expected.to allow_value({ id: 12 }, :first_unread).for(:anchor) }
+ it { is_expected.not_to allow_value({}, { id: 12, title: "a topic" }).for(:anchor) }
+ it { is_expected.not_to allow_value({ id: { a: 1 } }, { id: %w[a b] }).for(:anchor) }
+ it { is_expected.not_to allow_value({ secrets: 12 }, :guesswork).for(:anchor) }
+
context "when the anchor is not the sort" do
let(:params) { { sort: { created_at: :asc }, page: { anchor: { title: "A" } } } }
@@ -185,12 +191,6 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
end
end
- it { is_expected.to validate_length_of(:anchor).as_array.is_equal_to(1).allow_nil }
- it { is_expected.to allow_value({ id: 12 }, :first_unread).for(:anchor) }
- it { is_expected.not_to allow_value({}, { id: 12, title: "a topic" }).for(:anchor) }
- it { is_expected.not_to allow_value({ id: { a: 1 } }, { id: %w[a b] }).for(:anchor) }
- it { is_expected.not_to allow_value({ secrets: 12 }, :guesswork).for(:anchor) }
-
context "when the anchor name matches the sort" do
let(:params) { { sort: { title: :asc }, page: {} } }
@@ -315,7 +315,7 @@ RSpec.describe JsonApiKit::Request::Contract::Collection, type: :model do
it { is_expected.not_to allow_value("").for(:before_size) }
it { is_expected.not_to allow_value("").for(:after_size) }
- context "when both `page[before_size]` and `page[after_size]` are provided" do
+ context "when the page holds both sizes" do
let(:params) { { page: { anchor: { id: 12 }, before_size: 25 } } }
it { is_expected.to allow_value(20).for(:after_size).against(:window_size) }
diff --git a/spec/lib/json_api_kit/request/parameters_spec.rb b/spec/lib/json_api_kit/request/parameters_spec.rb
index 8c24a2bee96..4e60e3225d0 100644
--- a/spec/lib/json_api_kit/request/parameters_spec.rb
+++ b/spec/lib/json_api_kit/request/parameters_spec.rb
@@ -17,6 +17,18 @@ module JsonApiKitSpec
renamed_attribute from: :handle, to: :username
end
end
+
+ class ParametersShapeChange < JsonApiKit::VersionChange
+ version "2026-09-15"
+ description "The `words` attribute of the topics resource becomes `title`, one string."
+
+ resource :topics do
+ renamed_attribute from: :words,
+ to: :title,
+ down: ->(title) { title.to_s.split(" ") },
+ up: ->(words) { words.to_a.join(" ") }
+ end
+ end
end
RSpec.describe JsonApiKit::Request::Parameters do
@@ -153,6 +165,21 @@ RSpec.describe JsonApiKit::Request::Parameters do
end
end
+ context "when the anchor has a reshaped field" do
+ let(:change) { JsonApiKitSpec::ParametersShapeChange.new(__FILE__) }
+ let(:parameters) { { "page" => { "anchor" => { "words" => %w[Anchors and pages] } } } }
+
+ it "converts the field to its current name and shape" do
+ expect(declared_parameters).to eq(
+ "page" => {
+ "anchor" => {
+ "title" => "Anchors and pages",
+ },
+ },
+ )
+ end
+ end
+
context "when a filter has the name of a renamed field" do
let(:parameters) { { "filter" => { "postedAt" => "2026-08-01" } } }
diff --git a/spec/lib/json_api_kit/resource_spec.rb b/spec/lib/json_api_kit/resource_spec.rb
index 4f775e790a9..d87a8868879 100644
--- a/spec/lib/json_api_kit/resource_spec.rb
+++ b/spec/lib/json_api_kit/resource_spec.rb
@@ -126,7 +126,7 @@ RSpec.describe JsonApiKit::Resource do
context "when that name matches no model" do
subject(:resource) { Class.new(described_class) { model :nowhere_to_be_found } }
- it "refuses the model name" do
+ it "raises a missing declaration with that name" do
expect { model }.to raise_error(described_class::MissingDeclaration, /NowhereToBeFound/)
end
end
@@ -280,12 +280,12 @@ RSpec.describe JsonApiKit::Resource do
end
describe ".default_sort" do
- it "reads a listing in the order the resource declares" do
+ it "orders a listing as the resource declares" do
expect(topic_resource.order.leading.name).to eq(:last_posted_at)
end
context "when the resource declares no such sort" do
- it "refuses the declaration" do
+ it "raises an undeclared default" do
expect {
Class.new(described_class) do
model Topic
@@ -334,7 +334,9 @@ RSpec.describe JsonApiKit::Resource do
fab!(:topic) { Fabricate(:topic, title: "A field a resource renders") }
it "renders the field the resource declares" do
- expect(attribute_values).to eq("title" => topic.title)
+ expect(attribute_values).to eq(
+ JsonApiKit::Name::Field.new(value: "title", type: topic_resource.type) => topic.title,
+ )
end
context "when the resource declares one more after a reading" do
@@ -344,7 +346,9 @@ RSpec.describe JsonApiKit::Resource do
end
it "renders the new field too" do
- expect(attribute_values).to include("closed")
+ expect(attribute_values).to include(
+ JsonApiKit::Name::Field.new(value: "closed", type: topic_resource.type),
+ )
end
end
end
@@ -430,14 +434,14 @@ RSpec.describe JsonApiKit::Resource do
describe ".includes" do
subject(:allowed_paths) { topic_resource.allow(JsonApiKit::Paths.new(%w[user.groups])) }
- it "lets a request read a path through a relationship" do
+ it "allows a path through a relationship" do
expect(allowed_paths.map(&:to_s)).to eq(%w[user.groups])
end
- context "when the path reads a relationship no resource declares" do
+ context "when the path holds a relationship no resource declares" do
before { topic_resource.includes("user.badges") }
- it "refuses to read the resource" do
+ it "raises an unresolved path" do
expect { allowed_paths }.to raise_error(
JsonApiKit::Declarations::IncludePaths::Unresolved,
/user\.badges/,
@@ -450,7 +454,7 @@ RSpec.describe JsonApiKit::Resource do
before { child.includes("posts.groups") }
- it "reads the paths declared above it" do
+ it "allows the paths declared above it" do
expect(child.allow(JsonApiKit::Paths.new(%w[user.groups])).map(&:to_s)).to eq(
%w[user.groups],
)
@@ -490,7 +494,7 @@ RSpec.describe JsonApiKit::Resource do
end
context "when the default is larger than the maximum" do
- it "refuses the declaration" do
+ it "raises an out-of-range limit" do
expect {
Class.new(described_class) do
model Topic
@@ -503,7 +507,7 @@ RSpec.describe JsonApiKit::Resource do
end
describe ".page_size" do
- it "returns the size a page reads at" do
+ it "returns the size of a page" do
expect(topic_resource.page_size).to eq(2)
end
end
@@ -515,7 +519,7 @@ RSpec.describe JsonApiKit::Resource do
it { is_expected.to be_anchored_by(anchor_name: :created_at, ordering:) }
- context "when the order does not read by that anchor" do
+ context "when the order does not hold that anchor" do
let(:ordering) { { "ran_at" => :desc } }
it { is_expected.not_to be_anchored_by(anchor_name: :created_at, ordering:) }
@@ -552,7 +556,7 @@ RSpec.describe JsonApiKit::Resource do
describe ".all" do
before { allow(JsonApiKit::Query::Collection).to receive(:new) }
- it "reads a listing for the request a caller sends" do
+ it "builds a listing for the request a caller sends" do
topic_resource.all({ sort: { created_at: :asc } }, guardian:)
expect(JsonApiKit::Query::Collection).to have_received(:new).with(
@@ -580,7 +584,7 @@ RSpec.describe JsonApiKit::Resource do
end
context "when no column of the order allows null" do
- it "reads the listing in one segment" do
+ it "orders the listing in one segment" do
expect(topic_resource.order("created_at" => :desc).segments.size).to eq(1)
end
end
diff --git a/spec/lib/json_api_kit/sideload_spec.rb b/spec/lib/json_api_kit/sideload_spec.rb
index 03854be90c2..0084eec6d6c 100644
--- a/spec/lib/json_api_kit/sideload_spec.rb
+++ b/spec/lib/json_api_kit/sideload_spec.rb
@@ -53,7 +53,7 @@ RSpec.describe JsonApiKit::Sideload do
end
end
- context "when a path reads past the relationship" do
+ context "when a path goes past the relationship" do
let(:paths) { JsonApiKit::Paths.new(%w[user.groups]).next_for("user") }
before { allow(relationship).to receive(:listing).and_call_original }
@@ -71,7 +71,9 @@ RSpec.describe JsonApiKit::Sideload do
let(:params) { { fields: { users: %w[username] } } }
it "renders the related record as those fields" do
- expect(linkage.records.map(&:attributes)).to eq([{ "username" => author.username }])
+ expect(linkage.records.map(&:attributes)).to eq(
+ [{ JsonApiKit::Name::Field.new(value: "username", type: "users") => author.username }],
+ )
end
end
@@ -79,14 +81,14 @@ RSpec.describe JsonApiKit::Sideload do
fab!(:another) { Fabricate(:topic, user: author, title: "Another topic by that author") }
let(:records) { [topic, another] }
- let(:reads_of_users) do
+ let(:user_queries) do
track_sql_queries { rows.each { sideload.linkage_for(it) } }.grep(/FROM "users"/).size
end
def related_record(row) = sideload.linkage_for(row).records.first
- it "reads the related rows of them all in one query" do
- expect(reads_of_users).to eq(1)
+ it "loads the related rows of them all in one query" do
+ expect(user_queries).to eq(1)
end
it "gives two rows that relate to one row the same record" do
diff --git a/spec/lib/json_api_kit/version_change/pass_through_spec.rb b/spec/lib/json_api_kit/version_change/pass_through_spec.rb
new file mode 100644
index 00000000000..3514e5d31a9
--- /dev/null
+++ b/spec/lib/json_api_kit/version_change/pass_through_spec.rb
@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+RSpec.describe JsonApiKit::VersionChange::PassThrough do
+ subject(:pass_through) { described_class.new(name) }
+
+ let(:name) { JsonApiKit::Name::Field.new(value: "title", type: "topics") }
+
+ describe "#current" do
+ it "returns the name" do
+ expect(pass_through.current).to eq(name)
+ end
+ end
+
+ describe "#current_pairs" do
+ it "returns the name with the value" do
+ expect(pass_through.current_pairs("A")).to eq([[name, "A"]])
+ end
+ end
+
+ describe "#previous" do
+ it "returns the name" do
+ expect(pass_through.previous).to eq(name)
+ end
+ end
+
+ describe "#previous_pairs" do
+ it "returns the name with the value" do
+ expect(pass_through.previous_pairs("A")).to eq([[name, "A"]])
+ 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 101d03dce6b..4cb9aff6289 100644
--- a/spec/lib/json_api_kit/version_change/rename_spec.rb
+++ b/spec/lib/json_api_kit/version_change/rename_spec.rb
@@ -1,59 +1,76 @@
# frozen_string_literal: true
RSpec.describe JsonApiKit::VersionChange::Rename do
- subject(:rename) do
- described_class.new(kind: :field, type: "topics", from: "posted_at", to: "created_at")
- end
+ subject(:rename) { described_class.new(from: old_name, to: new_name, up:, down:) }
+ let(:up) { JsonApiKit::VersionChange::Declarations::NO_CONVERSION }
+ let(:down) { JsonApiKit::VersionChange::Declarations::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") }
describe "#current" do
- it "returns the new name for the old one" do
- expect(rename.current(old_name)).to eq(new_name)
+ it "returns the new name" do
+ expect(rename.current).to eq(new_name)
end
+ end
- context "when the name is of another kind" do
- let(:old_name) { JsonApiKit::Name::Sort.new(value: "posted_at", type: "topics") }
+ describe "#current_pairs" do
+ subject(:current_pairs) { rename.current_pairs(value) }
- it "returns the name" do
- expect(rename.current(old_name)).to eq(old_name)
- end
+ let(:value) { "2026/08/01" }
+
+ it "returns one pair, the new name with the value" do
+ expect(current_pairs).to eq([[new_name, "2026/08/01"]])
end
- context "when the name is of another type" do
- let(:old_name) { JsonApiKit::Name::Field.new(value: "posted_at", type: "users") }
+ context "when the rename converts the value" do
+ let(:down) { ->(date) { date.to_s.tr("-", "/") } }
+ let(:up) { ->(date) { date.to_s.tr("/", "-") } }
- it "returns the name" do
- expect(rename.current(old_name)).to eq(old_name)
+ it "returns the new name with the converted value" do
+ expect(current_pairs).to eq([[new_name, "2026-08-01"]])
+ end
+
+ context "when the value is null" do
+ let(:value) { nil }
+
+ it "gives the converter the null value" do
+ expect(current_pairs).to eq([[new_name, ""]])
+ end
end
end
end
describe "#previous" do
- it "returns the old name for the new one" do
- expect(rename.previous(new_name)).to eq(old_name)
+ it "returns the old name" do
+ expect(rename.previous).to eq(old_name)
end
+ end
- context "when the name is of another kind" do
- let(:new_name) { JsonApiKit::Name::Sort.new(value: "created_at", type: "topics") }
+ describe "#previous_pairs" do
+ subject(:previous_pairs) { rename.previous_pairs(value) }
- it "returns the name" do
- expect(rename.previous(new_name)).to eq(new_name)
- end
+ let(:value) { "2026-08-01" }
+
+ it "returns one pair, the old name with the value" do
+ expect(previous_pairs).to eq([[old_name, "2026-08-01"]])
end
- context "when the name is of another type" do
- let(:new_name) { JsonApiKit::Name::Field.new(value: "created_at", type: "users") }
+ context "when the rename converts the value" do
+ let(:down) { ->(date) { date.to_s.tr("-", "/") } }
+ let(:up) { ->(date) { date.tr("/", "-") } }
- it "returns the name" do
- expect(rename.previous(new_name)).to eq(new_name)
+ it "returns the old name with the converted value" do
+ expect(previous_pairs).to eq([[old_name, "2026/08/01"]])
end
- end
- end
- describe "#introduces?" do
- it { expect(rename).to be_introduces(new_name) }
- it { expect(rename).not_to be_introduces(old_name) }
+ context "when the value is null" do
+ let(:value) { nil }
+
+ it "gives the converter the null value" do
+ expect(previous_pairs).to eq([[old_name, ""]])
+ end
+ end
+ end
end
end
diff --git a/spec/lib/json_api_kit/version_change_spec.rb b/spec/lib/json_api_kit/version_change_spec.rb
index efbd87b2661..2b2fe40d968 100644
--- a/spec/lib/json_api_kit/version_change_spec.rb
+++ b/spec/lib/json_api_kit/version_change_spec.rb
@@ -10,6 +10,18 @@ module JsonApiKitSpec
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 RenameThingsAndPeople < JsonApiKit::VersionChange
version "2026-10-01"
description "Two resources change their names."
@@ -25,8 +37,9 @@ module JsonApiKitSpec
end
RSpec.describe JsonApiKit::VersionChange do
- subject(:change) { JsonApiKitSpec::RenameThingsLabelToName.new(__FILE__) }
+ subject(:change) { change_class.new(__FILE__) }
+ let(:change_class) { JsonApiKitSpec::RenameThingsLabelToName }
let(:version) { JsonApiKit::ApiVersion.parse("2026-09-15") }
let(:later_version) { JsonApiKit::ApiVersion.parse("2026-10-01") }
let(:fixtures) { Rails.root.join("spec/fixtures/json_api_kit") }
@@ -88,6 +101,18 @@ RSpec.describe JsonApiKit::VersionChange do
it { expect { changes }.to raise_error(ArgumentError, /has no description/) }
end
+
+ context "when a change renames one name twice" do
+ let(:directory) { "api_changes_with_two_renames_from_one_name" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /renames label twice/) }
+ end
+
+ context "when a change renames two names to one name" do
+ let(:directory) { "api_changes_with_two_renames_to_one_name" }
+
+ it { expect { changes }.to raise_error(ArgumentError, /renames two names to title/) }
+ end
end
describe ".after" do
@@ -111,6 +136,32 @@ RSpec.describe JsonApiKit::VersionChange do
end
end
+ describe ".resource" do
+ context "when a rename declares one converter only" do
+ subject(:declaration) do
+ Class.new(described_class) do
+ version "2026-09-15"
+ description "Half a shape change."
+ resource(:things) { renamed_attribute from: :a, to: :b, down: ->(value) { value } }
+ end
+ end
+
+ it { expect { declaration }.to raise_error(ArgumentError, /both up: and down:/) }
+ end
+
+ context "when a converter is not callable" do
+ subject(:declaration) do
+ Class.new(described_class) do
+ version "2026-09-15"
+ description "A converter that is not one."
+ resource(:things) { renamed_attribute from: :a, to: :b, up: nil, down: nil }
+ end
+ end
+
+ it { expect { declaration }.to raise_error(ArgumentError, /must respond to call/) }
+ end
+ end
+
describe "#version" do
it "returns the version of the change" do
expect(change.version).to eq(version)
@@ -148,7 +199,7 @@ RSpec.describe JsonApiKit::VersionChange do
end
end
- context "when the name is a filter with that name" do
+ 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
@@ -169,6 +220,39 @@ RSpec.describe JsonApiKit::VersionChange do
end
end
+ describe "#current_attributes" do
+ subject(:current_attributes) { 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 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" do
subject(:previous_name) { change.previous(name) }
@@ -179,15 +263,37 @@ RSpec.describe JsonApiKit::VersionChange do
end
end
- describe "#introduces?" do
- context "when the change renames another name to this one" do
- let(:name) { JsonApiKit::Name::Field.new(value: "name", type: "things") }
+ describe "#previous_attributes" do
+ subject(:previous_attributes) { 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 { expect(change).to be_introduces(name) }
+ it "keeps an attribute the change does not rename" do
+ expect(previous_attributes).to include(other_name => "B")
end
- context "when the change renames this name away" do
- it { expect(change).not_to be_introduces(name) }
+ 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