Skip to content

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

13.2 KB
Raw Blame
# frozen_string_literal: true

module JsonApiKitSpec
  MarkingRule =
    Struct.new(:mark) do
      def declared_name(name) = name.convert { "#{it}<#{mark}" }

      def declared_names(name) = [declared_name(name)]

      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

  module BrokenRule
    def self.declared_name(name) = name

    def self.declared_names(name) = [name]

    def self.declared_attributes(_attributes) = raise NoMethodError, "a fault in the kit"
  end

  class GlossaryChange < JsonApiKit::VersionChange
    version "2026-09-15"
    description "The `posted_at` attribute of the topics resource is renamed to `created_at`."

    resource :topics do
      renamed_attribute from: :posted_at, to: :created_at
    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`."

    resource :topics do
      renamed_attribute from: :label, to: :posted_at
    end
  end
end

RSpec.describe JsonApiKit::Glossary do
  subject(:glossary) { described_class.new([described_class::CasingRule]) }

  let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }
  let(:version_change) { JsonApiKitSpec::GlossaryChange.new(__FILE__) }
  let(:name) { JsonApiKit::Name::Field.new(value:, type: "topics") }
  let(:value) { "createdAt" }

  describe ".kit" do
    subject(:kit) { described_class.kit }

    before { allow(described_class).to receive(:new).and_call_original }

    it "builds a glossary with the wire format rules" do
      kit
      expect(described_class).to have_received(:new).with([described_class::CasingRule])
    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) { JsonApiKit::Edition.for(version).glossary }

      let(:attributes) { { name => %w[Anchors and pages] } }
      let(:value) { "words" }

      before do
        allow(JsonApiKit::VersionChanges.core).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

      context "when a converter cannot convert a value" do
        let(:attributes) { { name => 5, name.with(value: "size") => "L" } }

        it "raises a bad value with the names of that attribute only" do
          expect { declared_attributes }.to raise_error(
            described_class::BadValue,
            /cannot convert the value of words\./,
          )
        end
      end
    end

    context "when a rule raises" do
      subject(:glossary) { described_class.new([JsonApiKitSpec::BrokenRule]) }

      it "raises the error of the rule" do
        expect { declared_attributes }.to raise_error(NoMethodError, /a fault in the kit/)
      end
    end

    context "when conversion fails between two rules" do
      let(:glossary) { described_class.new([first_rule, failing_rule, last_rule]) }
      let(:first_rule) { JsonApiKitSpec::MarkingRule.new("first") }
      let(:last_rule) { JsonApiKitSpec::MarkingRule.new("last") }
      let(:failing_rule) do
        Class
          .new do
            def declared_name(name) = name

            def declared_names(name) = [name]

            def declared_attributes(attributes)
              raise JsonApiKit::VersionChange::Converter::Failure.new(attributes.keys)
            end

            def member_name(name) = name.convert { "#{it}>failure" }
          end
          .new
      end

      it "translates failure names through the preceding rules only" do
        expect { declared_attributes }.to raise_error(
          described_class::BadValue,
          "This version cannot convert the value of createdAt<first>first.",
        )
      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", type: "topics<a<b") => "Anchors and pages",
        )
      end
    end
  end

  describe "#declared_name" do
    subject(:declared_name) { glossary.declared_name(name) }

    context "when a casing correction precedes a type change" do
      let(:glossary) { JsonApiKit::Edition.for(version).glossary }
      let(:name) { JsonApiKit::Name::Field.new(value:, type: "discussions") }
      let(:value) { "created_at" }
      let(:version_change) do
        Class
          .new(JsonApiKit::VersionChange) do
            renamed_type from: :discussions, to: :topics
            resource :topics do
              renamed_attribute from: :posted_at, to: :created_at
            end
          end
          .new(__FILE__)
      end

      before do
        allow(JsonApiKit::VersionChanges.core).to receive(:after).and_return([version_change])
      end

      it "translates the correction through the remaining rules" do
        expect { declared_name }.to raise_error(
          having_attributes(member: name.with(value: "postedAt")),
        )
      end

      context "when only the casing is incorrect" do
        let(:value) { "posted_at" }

        it "still rejects the original name" do
          expect { declared_name }.to raise_error(
            having_attributes(member: name.with(value: "postedAt")),
          )
        end
      end
    end

    it "returns the declared name" do
      expect(declared_name).to eq(name.with(value: "created_at"))
    end

    context "when the name was converted before" do
      before do
        allow(described_class::CasingRule).to receive(:declared_name).and_call_original
        glossary.declared_name(name)
      end

      it "does not ask the rules again" do
        declared_name
        expect(described_class::CasingRule).to have_received(:declared_name).once
      end
    end

    context "when the name was refused before" do
      let(:value) { "created_at" }

      before do
        allow(described_class::CasingRule).to receive(:declared_name).and_call_original
        suppress(described_class::NotAMemberName) { glossary.declared_name(name) }
      end

      it "asks the rules again" do
        suppress(described_class::NotAMemberName) { declared_name }
        expect(described_class::CasingRule).to have_received(:declared_name).twice
      end
    end

    context "when the name is not a member name" do
      let(:value) { "created_at" }

      it "raises a refusal" do
        expect { declared_name }.to raise_error(described_class::NotAMemberName)
      end

      it "suggests the name to use instead" do
        expect { declared_name }.to raise_error(/Use createdAt, not created_at\./)
      end
    end

    context "with a version rule" do
      subject(:glossary) { JsonApiKit::Edition.for(version).glossary }

      let(:value) { "postedAt" }

      before do
        allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
          [version_change],
        )
      end

      it "returns the current name" do
        expect(declared_name).to eq(name.with(value: "created_at"))
      end

      context "when the name belongs to a later version" do
        let(:value) { "createdAt" }

        it "suggests the name of this version, on the wire" do
          expect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)
        end
      end

      context "when the name is in snake case" do
        let(:value) { "created_at" }

        it "suggests the name of this version, on the wire" do
          expect { declared_name }.to raise_error(/Use postedAt, not created_at\./)
        end
      end

      context "when a later change reuses a spelling of this version" do
        let(:value) { "createdAt" }

        before do
          allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
            [version_change, JsonApiKitSpec::GlossaryReuseChange.new(__FILE__)],
          )
        end

        it "suggests the name of this version, on the wire" do
          expect { declared_name }.to raise_error(/Use postedAt, not createdAt\./)
        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_name).to eq(name.with(value: "createdAt<a<b", type: "topics<a<b"))
      end
    end
  end

  describe "#member_type" do
    subject(:member_type) { glossary.member_type("discussion_threads") }

    it "returns the type in camel case" do
      expect(member_type).to eq("discussionThreads")
    end

    context "when the type has a historical name" do
      let(:glossary) { JsonApiKit::Edition.for(version).glossary }
      let(:version_change) do
        Class
          .new(JsonApiKit::VersionChange) do
            renamed_type from: :forum_topics, to: :discussion_threads
          end
          .new(__FILE__)
      end

      before do
        allow(JsonApiKit::VersionChanges.core).to receive(:after).and_return([version_change])
      end

      it "returns the historical type in camel case" do
        expect(member_type).to eq("forumTopics")
      end
    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) { JsonApiKit::Edition.for(version).glossary }

      before do
        allow(JsonApiKit::VersionChanges.core).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", type: "topics>b>a") => "Anchors and pages",
        )
      end
    end
  end

  describe "#member_name" do
    subject(:member_name) { glossary.member_name(name) }

    let(:value) { "created_at" }

    it "returns the member name" do
      expect(member_name).to eq(name.with(value: "createdAt"))
    end

    context "when the name was converted before" do
      before do
        allow(described_class::CasingRule).to receive(:member_name).and_call_original
        glossary.member_name(name)
      end

      it "does not ask the rules again" do
        member_name
        expect(described_class::CasingRule).to have_received(:member_name).once
      end
    end

    context "with a version rule" do
      subject(:glossary) { JsonApiKit::Edition.for(version).glossary }

      before do
        allow(JsonApiKit::VersionChanges.core).to receive(:after).with(version).and_return(
          [version_change],
        )
      end

      it "returns the name of this version, on the wire" do
        expect(member_name).to eq(name.with(value: "postedAt"))
      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_name).to eq(name.with(value: "created_at>b>a", type: "topics>b>a"))
      end
    end
  end
end