Skip to content

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

14.4 KB
Raw Blame
# frozen_string_literal: true

module JsonApiKitSpec
  class ParametersAuthorResource < JsonApiKit::Resource
    type :users
  end

  class ParametersPostResource < JsonApiKit::Resource
    type :posts
    has_one :last_poster, resource: ParametersAuthorResource
  end

  class ParametersResource < JsonApiKit::Resource
    type :topics
    has_many :ordered_posts, resource: ParametersPostResource
  end

  class ParametersChange < JsonApiKit::VersionChange
    version "2026-09-15"
    description "Two resources rename a field."

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

    resource :users do
      renamed_attribute from: :handle, to: :username
    end
  end

  class ParametersMergeChange < JsonApiKit::VersionChange
    version "2026-09-15"
    description "The `posted_date` and `posted_time` attributes of the topics resource become `posted_at`."

    resource :topics 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 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
  subject(:declared_parameters) { request_parameters.to_h }

  let(:request_parameters) do
    described_class.new(parameters, glossary:, resource: JsonApiKitSpec::ParametersResource)
  end
  let(:glossary) { JsonApiKit::Glossary.kit }
  let(:parameters) { { "sort" => "-createdAt" } }
  let(:declared_filters) { declared_parameters.fetch("filter").transform_keys { it.filter.value } }

  it "converts the sort into declared names and directions" do
    expect(declared_parameters).to eq("sort" => { "created_at" => :desc })
  end

  context "when the sort holds several names" do
    let(:parameters) { { "sort" => "-createdAt,title" } }

    it "converts every one of them" do
      expect(declared_parameters).to eq("sort" => { "created_at" => :desc, "title" => :asc })
    end
  end

  context "when a sort name has a hyphen" do
    let(:parameters) { { "sort" => "last-posted-at" } }

    it "keeps the hyphen" do
      expect(declared_parameters).to eq("sort" => { "last-posted-at" => :asc })
    end
  end

  context "when the sort is an array" do
    let(:parameters) { { "sort" => %w[createdAt] } }

    it "leaves it to the contract" do
      expect(declared_parameters).to eq("sort" => %w[createdAt])
    end
  end

  context "when the sort is a hash" do
    let(:parameters) { { "sort" => { "createdAt" => :desc } } }

    it "converts the keys only" do
      expect(declared_parameters).to eq("sort" => { "created_at" => :desc })
    end
  end

  context "when the parameters have an include path" do
    let(:parameters) { { "include" => "orderedPosts.lastPoster" } }

    it "converts every segment of the path" do
      expect(declared_parameters).to eq("include" => "ordered_posts.last_poster")
    end

    context "when both relationships have historical names" do
      let(:parameters) { { "include" => "olderPosts.author,olderPosts" } }
      let(:glossary) { JsonApiKit::Edition.for(JsonApiKit::Timeline::FIRST_RELEASE).glossary }
      let(:version_change) do
        Class
          .new(JsonApiKit::VersionChange) do
            resource :topics do
              renamed_relationship from: :older_posts, to: :ordered_posts
            end
            resource :posts do
              renamed_relationship from: :author, to: :last_poster
            end
          end
          .new(__FILE__)
      end

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

      it "translates every path against the resource declarations" do
        expect(declared_parameters).to eq("include" => "ordered_posts.last_poster,ordered_posts")
      end

      context "when the paths are an array" do
        let(:parameters) { { "include" => ["olderPosts.author"] } }

        it "preserves the array while translating its paths" do
          expect(declared_parameters).to eq("include" => ["ordered_posts.last_poster"])
        end
      end
    end
  end

  context "when the parameters have a fieldset" do
    let(:parameters) { { "fields" => { "solved-statuses" => "answeredAt" } } }

    it "converts the fieldset into its declared names" do
      expect(declared_parameters).to eq("fields" => { "solved-statuses" => %w[answered_at] })
    end

    context "when the fieldset is empty" do
      let(:parameters) { { "fields" => { "solved-statuses" => "" } } }

      it "returns no name for it" do
        expect(declared_parameters).to eq("fields" => { "solved-statuses" => [] })
      end
    end

    context "when the fieldset is an array" do
      let(:parameters) { { "fields" => { "solved-statuses" => %w[answeredAt] } } }

      it "converts every name" do
        expect(declared_parameters).to eq("fields" => { "solved-statuses" => %w[answered_at] })
      end
    end

    context "when the fieldset is neither a list nor an array" do
      let(:parameters) { { "fields" => { "solved-statuses" => 42 } } }

      it "leaves it to the contract" do
        expect(declared_parameters).to eq("fields" => { "solved-statuses" => 42 })
      end
    end
  end

  context "when a filter is named like a parameter" do
    let(:parameters) { { "filter" => { "sort" => "created_at", "anchor" => "SomeValue" } } }

    it "keeps every filter value" do
      expect(declared_filters).to eq("sort" => "created_at", "anchor" => "SomeValue")
    end
  end

  context "when a name is not a member name" do
    let(:parameters) { { "sort" => "created_at" } }

    it "raises with the parameter that holds it" do
      expect { declared_parameters }.to raise_error(
        an_instance_of(JsonApiKit::Glossary::NotAMemberName).and(
          having_attributes(source: { parameter: "sort" }),
        ),
      )
    end

    context "when the name is a key" do
      let(:parameters) { { "page" => { "anchor" => { "created_at" => "2026-08-01" } } } }

      it "raises with the parameter that holds it" do
        expect { declared_parameters }.to raise_error(
          having_attributes(source: { parameter: "page[anchor][created_at]" }),
        )
      end
    end
  end

  context "with a version change" do
    let(:glossary) { JsonApiKit::Edition.for(version).glossary }
    let(:version) { JsonApiKit::Timeline::FIRST_RELEASE }
    let(:version_change) { JsonApiKitSpec::ParametersChange.new(__FILE__) }

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

    context "when a fieldset has a renamed field" do
      let(:parameters) { { "fields" => { "topics" => "postedAt" } } }

      it "converts the field to its current name" do
        expect(declared_parameters).to eq("fields" => { "topics" => %w[created_at] })
      end
    end

    context "when a fieldset of another type has a renamed field" do
      let(:parameters) { { "fields" => { "users" => "handle" } } }

      it "converts the field with the names of that type" do
        expect(declared_parameters).to eq("fields" => { "users" => %w[username] })
      end
    end

    context "when the sort has a renamed field" do
      let(:parameters) { { "sort" => "-postedAt" } }

      it "converts the field to its current name" do
        expect(declared_parameters).to eq("sort" => { "created_at" => :desc })
      end
    end

    context "when the sort has several fields" do
      let(:parameters) { { "sort" => "-postedAt,title" } }

      it "converts every field" do
        expect(declared_parameters).to eq("sort" => { "created_at" => :desc, "title" => :asc })
      end
    end

    context "when the sort has two fields that merge into one" do
      let(:version_change) { JsonApiKitSpec::ParametersMergeChange.new(__FILE__) }
      let(:parameters) { { "sort" => "postedDate,postedTime" } }

      it "converts both to the one field" do
        expect(declared_parameters).to eq("sort" => { "posted_at" => :asc })
      end

      context "when their directions differ" do
        let(:parameters) { { "sort" => "postedDate,-postedTime" } }

        it "raises with the parameter that holds them" do
          expect { declared_parameters }.to raise_error(
            having_attributes(source: { parameter: "sort" }),
          )
        end
      end

      context "when the sort is a hash and their directions differ" do
        let(:parameters) { { "sort" => { "postedDate" => "asc", "postedTime" => "desc" } } }

        it "raises with the parameter that holds them" do
          expect { declared_parameters }.to raise_error(
            having_attributes(source: { parameter: "sort" }),
          )
        end
      end
    end

    context "when a fieldset has several fields" do
      let(:parameters) { { "fields" => { "topics" => "title,postedAt" } } }

      it "converts every field" do
        expect(declared_parameters).to eq("fields" => { "topics" => %w[title created_at] })
      end
    end

    context "when the anchor has a renamed field" do
      let(:parameters) { { "page" => { "anchor" => { "postedAt" => "2026-08-01" } } } }

      it "converts the field to its current name" do
        expect(declared_parameters).to eq(
          "page" => {
            "anchor" => {
              "created_at" => "2026-08-01",
            },
          },
        )
      end
    end

    context "when the anchor has a reshaped field" do
      let(:version_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" } } }

      it "converts the case of the filter name only" do
        expect(declared_filters).to eq("posted_at" => "2026-08-01")
      end
    end
  end

  context "when a name has a newline" do
    let(:parameters) { { "sort" => "createdAt\n" } }

    it "converts the case and keeps the newline for the contract" do
      expect(declared_parameters).to eq("sort" => { "created_at\n" => :asc })
    end
  end

  context "when the parameters have a filter" do
    let(:parameters) { { "filter" => { "postCount" => "SomeTopic Title" } } }

    it "converts the filter name only" do
      expect(declared_filters).to eq("post_count" => "SomeTopic Title")
    end
  end

  context "when the parameters have page members" do
    let(:parameters) { { "page" => { "beforeSize" => "1", "after" => "WyJhQiJd" } } }

    it "converts the member names only" do
      expect(declared_parameters).to eq("page" => { "before_size" => "1", "after" => "WyJhQiJd" })
    end
  end

  context "when the parameters anchor on an attribute" do
    let(:parameters) { { "page" => { "anchor" => { "createdAt" => "2026-08-01" } } } }

    it "converts the anchor name only" do
      expect(declared_parameters).to eq("page" => { "anchor" => { "created_at" => "2026-08-01" } })
    end
  end

  context "when the parameters anchor on a computed position" do
    let(:parameters) { { "page" => { "anchor" => "withoutReplies" } } }

    it "converts the anchor name" do
      expect(declared_parameters).to eq("page" => { "anchor" => "without_replies" })
    end
  end

  context "when a type changes after a field name" do
    let(:glossary) { JsonApiKit::Edition.for(JsonApiKit::Timeline::FIRST_RELEASE).glossary }
    let(:field_change) do
      Class
        .new(JsonApiKit::VersionChange) do
          resource :discussion_threads do
            renamed_attribute from: :heading, to: :title
            renamed_filter from: :label, to: :title
          end
        end
        .new(__FILE__)
    end
    let(:type_change) do
      Class
        .new(JsonApiKit::VersionChange) { renamed_type from: :discussion_threads, to: :topics }
        .new(__FILE__)
    end

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

    context "when the request supplies a fieldset" do
      let(:parameters) { { "fields" => { "discussionThreads" => "heading" } } }

      it "translates the type and field together" do
        expect(declared_parameters).to eq("fields" => { "topics" => ["title"] })
      end
    end

    context "when the fieldset is empty" do
      let(:parameters) { { "fields" => { "discussionThreads" => "" } } }

      it "translates the type without a field name" do
        expect(declared_parameters).to eq("fields" => { "topics" => [] })
      end
    end

    context "when the fieldset value is invalid" do
      let(:parameters) { { "fields" => { "discussionThreads" => 42 } } }

      it "translates the type for the contract" do
        expect(declared_parameters).to eq("fields" => { "topics" => 42 })
      end
    end

    context "when the request supplies names without a type" do
      let(:parameters) do
        {
          "sort" => "heading",
          "filter" => {
            "label" => "A",
          },
          "page" => {
            "anchor" => {
              "heading" => "A",
            },
          },
        }
      end

      it "derives the historical type before translating names", :aggregate_failures do
        expect(declared_filters).to eq("title" => "A")
        expect(declared_parameters.except("filter")).to eq(
          "sort" => {
            "title" => :asc,
          },
          "page" => {
            "anchor" => {
              "title" => "A",
            },
          },
        )
      end
    end
  end

  describe "#fieldsets" do
    subject(:fieldsets) { request_parameters.fieldsets }

    let(:parameters) { { "fields" => { "topics" => "postedDate" } } }

    it "returns the fieldsets under the names the client sent" do
      expect(fieldsets.keep("topics", "postedDate" => "2026-08-01", "title" => "A")).to eq(
        "postedDate" => "2026-08-01",
      )
    end
  end
end