graphiti 2.0.0.beta.5 → 2.0.0.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdd882c646fa88d0ac6522b7725ad6132b7ad890043822f5e2a2ce8af3f0fc4c
-  data.tar.gz: 687c64e9c5e6d2931a09bde9f5595b965e36f1a090d863fa17b9edf11559533f
+  metadata.gz: acced292af02bc2826f89f6e1d9388bcc7fdedabada42e4cc65d1bfaf9f713f5
+  data.tar.gz: 79f966dc31ccb9b3aee687e7dc31a92e943e17845b6017258e366bebee066446
 SHA512:
-  metadata.gz: 1907226aa19ad065b0affe66f5ea22bb7149fd11aef92d225d7b433a5c67111bde2d7ef5911e633c5ea9059559ff903654c21f835099b5e15e72fdf7ab59cc9b
-  data.tar.gz: 91fd8e83a1452d29ffb45076b94a9eeb316c4e508a2f6565c5e079e6c54a184eede79da45ecb9d25f340f395551d907e10eb152e05666387792c434ed5fb4361
+  metadata.gz: 22584fd2a83e017219fb8202c965d3d295ac341fed01b2e543355c32722cae741866f3188970ee480018d6063c78b06281045f22934c42b9645de72c6cc9562f
+  data.tar.gz: 502371f38ad71f5e901b57ba187be70bb4d7c85c94544324e825207bc03f120fa652d0859fe56744efbdbcf826376dad84a4917444c62a7e30193482bca47700

data/.github/workflows/ci.yml

@@ -41,25 +41,30 @@ jobs:
           - { ruby: "3.2", gemfile: Gemfile, appraisal: false }
           - { ruby: "3.3", gemfile: Gemfile, appraisal: false }
           - { ruby: "3.4", gemfile: Gemfile, appraisal: false }
+          - { ruby: "4.0", gemfile: Gemfile, appraisal: false }
           - { ruby: ruby-head, gemfile: Gemfile, appraisal: false }
 
           # Rails 7.1 - the floor
           - { ruby: "3.2", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_7_1.gemfile, appraisal: true }
 
           # Rails 7.2
           - { ruby: "3.2", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_7_2.gemfile, appraisal: true }
 
           # Rails 8.0
           - { ruby: "3.2", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_8_0.gemfile, appraisal: true }
 
           # Rails 8.1
           - { ruby: "3.2", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
           - { ruby: "3.4", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
+          - { ruby: "4.0", gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
           - { ruby: ruby-head, gemfile: gemfiles/rails_8_1.gemfile, appraisal: true }
 
     continue-on-error: ${{ matrix.ruby == 'ruby-head' }}

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 graphiti changelog
 
+# [2.0.0-beta.7](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.6...v2.0.0-beta.7) (2026-08-10)
+
+
+### Features
+
+* dedupe under concurrency and across distinct resources ([800b1a2](https://github.com/graphiti-api/graphiti/commit/800b1a2bf9bb59702efd00afe8e4f54ae06b500e))
+* deduplicate sideloaded entities across include paths ([0c2829a](https://github.com/graphiti-api/graphiti/commit/0c2829a634e9b96e2403ff168be9a48c6a663c78))
+* deprecate SpecHelpers::Sugar in favor of the full helper names ([b155849](https://github.com/graphiti-api/graphiti/commit/b155849f55fe84b2d0911fa4681d82682dfa39ae))
+
+# [2.0.0-beta.6](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.5...v2.0.0-beta.6) (2026-08-09)
+
+
+### Bug Fixes
+
+* reject invalid page parameters ([#537](https://github.com/graphiti-api/graphiti/issues/537)) ([bb3698b](https://github.com/graphiti-api/graphiti/commit/bb3698b52911c658c5d023ad8fd55b5106195001)), closes [#347](https://github.com/graphiti-api/graphiti/issues/347)
+* treat empty polymorphic configuration as unset ([#538](https://github.com/graphiti-api/graphiti/issues/538)) ([5c17899](https://github.com/graphiti-api/graphiti/commit/5c1789993fbb4638d4443cf014b8bef358addb80)), closes [#199](https://github.com/graphiti-api/graphiti/issues/199)
+
+
+### Features
+
+* Add graphiti:audit task to audit resources for issues ([84436ea](https://github.com/graphiti-api/graphiti/commit/84436eab7c7d0713ec6f355b62ba8b06913ee31a))
+* raise MissingRelationshipMethod when rendering reads an association the model does not define ([1c41cee](https://github.com/graphiti-api/graphiti/commit/1c41cee787b4f747d2906b2230f8fb926e3d887d))
+* rename always_include_resource_ids to resource_ids, with a belongs_to_resource_ids_by_default setting ([8b11151](https://github.com/graphiti-api/graphiti/commit/8b111516822f6fc6e3675b59941688791cb34e74))
+
 # [2.0.0-beta.5](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.4...v2.0.0-beta.5) (2026-08-07)
 
 

data/docs/concepts/relationships.md

@@ -70,10 +70,20 @@ has_many :positions,
   writable: true,
   link: self.autolink, # default true
   single: false, # only allow this sideload when one employee
-  always_include_resource_ids: true # default: true for belongs_to, false otherwise
+  resource_ids: false
 ```
 
-`belongs_to` renders resource linkage by default, so a client can see which record a relationship points at without following the link:
+`resource_ids` is the one whose default depends on the relationship type:
+
+| type | renders resource ids by default |
+|---|---|
+| `belongs_to` | yes, when its foreign key already holds the related id |
+| `has_one` | no |
+| `has_many` | no |
+| `many_to_many` | no |
+| `polymorphic_belongs_to` | no |
+
+`belongs_to` renders them so a client can see which record a relationship points at without following the link:
 
 ```json
 "employee": {
@@ -82,19 +92,109 @@ has_many :positions,
 }
 ```
 
-That costs nothing, because the id is already on the parent as its foreign key. A `has_many` would have to run a query per record to answer the same question, so it stays off unless you ask for it.
+That costs nothing, because the id is already on the parent as its foreign key.
+
+No other relationship type has a free source for its ids. A collection accepts `resource_ids: true`, but that reads the association on every render of every parent record, whether or not the request wants the relationship. That is the N+1 from [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646) on every response. Leave collections off and let clients `?include=` them.
 
-A `belongs_to` falls back to loading the association when the foreign key cannot answer for it: a `params` block or `base_scope` can filter out the record the key points at, a polymorphic target takes its type from the record rather than the relationship, and a remote resource has no local key to read. Turning linkage on for those, or for a `has_many`, brings back the 1+N described in [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646).
+Not every `belongs_to` can use its foreign key. A `scope` or `params` block or a `base_scope` can filter out the record the key points at, a polymorphic target's type varies per record while rendered ids carry one type for the whole relationship, a remote resource has no local key to read, and a custom `primary_key` points the relationship at some other column. Those load the association instead, so they stay off by default too.
 
-Set the default for every relationship on a resource, whatever its type:
+<details>
+<summary>Which `belongs_to` declarations render resource ids, and which do not</summary>
+
+```ruby
+# yes. employee_id is the employee's id, so the payload already has it
+belongs_to :employee
+
+# no. nothing renders at all, ids included
+belongs_to :employee, readable: false
+
+# no. employee_id holds a name, not the related id
+belongs_to :employee, primary_key: :first_name
+
+# no. the base scope can exclude the employee the key points at, and
+# graphiti cannot know whether it does without running it
+belongs_to :employee, base_scope: -> { Employee.all }
+
+# no. a remote resource has no local foreign key to read
+belongs_to :employee, remote: "http://foo.com/employees"
+
+# no. the record's own class decides its type, so the key gives an id
+# with no type to pair it with
+belongs_to :employee, resource: CreditCardResource
+
+# no. the scope can exclude the employee the key points at, and graphiti
+# cannot know whether it does without running it
+belongs_to :employee do
+  scope { |ids| {type: :employees, conditions: {id: ids}} }
+end
+
+# no. same, a params filter can exclude the employee the key points at
+belongs_to :employee do
+  params { |hash, positions| hash[:filter][:active] = true }
+end
+
+# no. credit_card_type is local, but rendered ids carry one type for the
+# whole relationship and this one's varies per record
+polymorphic_belongs_to :credit_card do
+  group_by(:credit_card_type) do
+    on(:Visa).belongs_to :visa, resource: VisaResource
+  end
+end
+```
+
+Watch for the `scope`, `params` and `base_scope` cases. Nothing about those declarations looks like it concerns resource ids, so adding a scope block to filter a relationship also stops its ids from rendering.
+
+If you keep a `schema.json`, the schema check catches that. A relationship that renders resource ids is marked `linkage: true`, and one that stops rendering them is reported as a breaking change. Gaining them is additive and passes.
+
+To render ids anyway, opt in on the relationship and accept the query:
+
+```ruby
+belongs_to :employee, resource_ids: true do
+  scope { |ids| {type: :employees, conditions: {id: ids}} }
+end
+```
+
+Know what that buys for the `scope`, `params` and `base_scope` cases. Rendering reads the association off the model, which does not apply the block, so if the block narrows what sideloading returns, the ids will disagree with it. Opting in there says you know the two agree. A `primary_key`, polymorphic or remote relationship does resolve to the right id this way.
+
+</details>
+
+### belongs_to_resource_ids_by_default {#belongs-to-resource-ids}
+
+To change how far a `belongs_to` goes, across a whole API, set it on the resource everything inherits from:
 
 ```ruby
 class ApplicationResource < Graphiti::Resource
-  self.always_include_resource_ids_by_default = false
+  self.belongs_to_resource_ids_by_default = :foreign_key
 end
 ```
 
-Subclasses inherit it, and a relationship passing `always_include_resource_ids` explicitly still wins.
+| | |
+|---|---|
+| `:foreign_key` | Default. Render resource ids wherever the foreign key already holds the related id, and never run an extra query. |
+| `:always` | Render them for every `belongs_to`, loading the association when the foreign key cannot answer. A query per record, per relationship, on every render. |
+| `:never` | Render none. This is the 1.x payload. |
+
+Subclasses inherit it, and a relationship passing `resource_ids` explicitly still wins.
+
+All three describe requests that do not include the relationship. A relationship the request does include renders its ids whatever this is set to, `:never` included, because the records are already loaded and sitting in `included`.
+
+Before flipping the setting, [`bin/rake graphiti:audit`](/topics/debugging#graphiti-audit) reports how every relationship renders resource ids today and which would start loading the association.
+
+#### What a client sees {#relationship-payload-shapes}
+
+A client never has to work out which rule applied. The relationship object says what it knows:
+
+```json
+"employee": { "data": { "type": "employees", "id": "1" } }   // here is the id
+"employee": { "links": { "related": "..." } }                 // fetch it yourself
+"employee": { "meta": { "included": false } }                 // neither
+```
+
+The last shape appears only when a relationship has no ids **and** no link, which usually means `link: false`. It is not a general "was this sideloaded" flag. Relationships are autolinked by default, so the link shape is the one you normally see.
+
+The setting covers `belongs_to` and `polymorphic_belongs_to`, and no collection, deliberately. An API-wide `:always` on collections would be the N+1 from [#167](https://github.com/graphiti-api/graphiti/issues/167#issuecomment-686866646) applied everywhere at once.
+
+`:always` renders ids by loading the association, so a relationship naming a method the model does not have raises on every render once you set it.
 
 ### Conditional Relationships {#conditional-relationships}
 
@@ -221,7 +321,7 @@ Defaults to these common options:
 has_many :positions,
   foreign_key: :employee_id,
   primary_key: :id,
-  always_include_resource_ids: false,
+  resource_ids: false,
   resource: PositionResource
 ```
 
@@ -265,7 +365,7 @@ Defaults to these common options:
 belongs_to :employee,
   foreign_key: :employee_id,
   primary_key: :id,
-  always_include_resource_ids: false,
+  resource_ids: true,
   resource: EmployeeResource
 ```
 

data/docs/topics/debugging.md

@@ -172,6 +172,32 @@ Which add Debugger output as well.
 The `PATH` should not contain the domain unless you want to hit a live
 API instead of a test server.
 
+#### graphiti:audit {#graphiti-audit}
+
+> `bin/rake graphiti:audit`
+
+Audits every relationship declared across your resources. It reports anything that will raise at request time, relationships that load an association just to render resource ids, and `belongs_to` relationships that render no ids unless included. A checklist at the end shows what was checked:
+
+```
+ERROR will raise when the relationship is included: the model has no association method
+
+  EmployeeResource
+    has_many :positions  Employee has no #positions method
+
+  fix: define it, point the relationship at the real association with `as:`, or remove the relationship
+
+checks
+
+  ✓ all relationships inspectable
+  ✗ 1 association method missing
+  ✓ all readable guards defined
+  ✓ all sideload filters declared
+
+graphiti: 12 resources, 40 relationships, 1 error.
+```
+
+The task exits nonzero when there are errors, so it can hold the line in CI. Run it before and after flipping [belongs_to_resource_ids_by_default](/concepts/relationships#belongs-to-resource-ids) to see exactly what the setting changes.
+
 #### graphiti:benchmark {#graphiti-benchmark}
 
 > `bin/rake graphiti:benchmark[PATH,NUM_REQUESTS]`

data/docs/topics/testing.md

@@ -134,7 +134,6 @@ require 'graphiti/spec_helpers/rspec'
 RSpec.configure do |config|
   config.include FactoryBot::Syntax::Methods
   config.include Graphiti::SpecHelpers::RSpec
-  config.include Graphiti::SpecHelpers::Sugar
   config.include Graphiti::Rails::TestHelpers, type: :request
 
   # Clean your DB between test runs
@@ -163,8 +162,6 @@ These helpers ship with Graphiti, under `Graphiti::SpecHelpers`.
 
 ### #jsonapi_data {#jsonapi-data}
 
-> Note: for brevity, this method is aliased to `d`
-
 The `jsonapi_data` method will parse response data and return a normalized object (`Graphiti::SpecHelpers::Node`). Assert against this the same way you assert against JSON:
 
 ```ruby
@@ -183,7 +180,7 @@ expect(data.first_name).to eq('Jane')
 To grab a relationship:
 
 ```ruby
-sideload = d[0].sideload(:comments)
+sideload = jsonapi_data[0].sideload(:comments)
 expect(sideload.id).to eq(123)
 expect(sideload.jsonapi_type).to eq('comments')
 expect(sideload.body).to eq('body')
@@ -196,7 +193,7 @@ The `sideload` method accepts the *name of the relationship*. It returns a norma
 To grab a Link:
 
 ```ruby
-d[0].link(:comments, :related)
+jsonapi_data[0].link(:comments, :related)
 ```
 
 This accepts the relationship name and the link type. It will return the link URL.
@@ -205,28 +202,26 @@ This accepts the relationship name and the link type. It will return the link UR
 
 To see the raw JSON response, use `json`.
 
-### #date and #datetime {#date-and-datetime}
+### #json_date and #json_datetime {#date-and-datetime}
 
 In Graphiti, datetimes are rendered in [ISO 8601 format](https://www.iso.org/iso-8601-date-and-time-format.html). This means that straight date comparisons will fail:
 
 ```ruby
 # WRONG
-expect(d[0].created_at).to eq(post.created_at)
+expect(jsonapi_data[0].created_at).to eq(post.created_at)
 ```
 
-Instead, use the `datetime` helper to convert to ISO 8601 and compare apples to apples:
+Instead, use the `json_datetime` helper to convert to ISO 8601 and compare apples to apples:
 
 ```ruby
 # RIGHT
-expect(d[0].created_at).to eq(datetime(post.created_at))
+expect(jsonapi_data[0].created_at).to eq(json_datetime(post.created_at))
 ```
 
-Similarly, there's a `date` helper as well.
+Similarly, there's a `json_date` helper as well.
 
 ### #jsonapi_errors {#jsonapi-errors}
 
-> This method is aliased to `errors` for brevity
-
 To parse an [Errors Payload](http://jsonapi.org/format/#errors):
 
 ```ruby
@@ -261,7 +256,7 @@ Resource tests have two helpers, both different ways to execute a query.
 ```ruby
 it 'works' do
   render
-  expect(d[0].first_name).to eq('Jane')
+  expect(jsonapi_data[0].first_name).to eq('Jane')
   json # => { data: { type: 'employees', ... } }
 end
 ```
@@ -275,6 +270,33 @@ it 'works' do
 end
 ```
 
+### Resource Matchers {#resource-matchers}
+
+For one-line assertions about a Resource's shape, use the built-in matchers. They're included automatically in `type: :resource` specs and expect a Resource instance as the subject:
+
+```ruby
+RSpec.describe PostResource, type: :resource do
+  subject { described_class.new }
+
+  it { is_expected.to belong_to_resource(:author) }
+  it { is_expected.to have_many_resources(:comments) }
+  it { is_expected.to have_one_resource(:detail) }
+  it { is_expected.to expose_attribute(:title, :string) }
+  it { is_expected.to filter_attribute(:title, :string) }
+end
+```
+
+Each matcher accepts `with_options` to assert configuration:
+
+```ruby
+it do
+  is_expected.to belong_to_resource(:author)
+    .with_options(foreign_key: :author_id, resource: AuthorResource)
+end
+
+it { is_expected.to expose_attribute(:title, :string).with_options(writable: false) }
+```
+
 ### API Test Helpers {#api-test-helpers}
 
 When executing an API test request, always use the `jsonapi_` doppelgänger:
@@ -378,7 +400,7 @@ describe 'filtering' do
 
     it 'works' do
       render
-      expect(d.map(&:id)).to eq([employee2.id])
+      expect(jsonapi_data.map(&:id)).to eq([employee2.id])
     end
   end
 end
@@ -401,7 +423,7 @@ describe 'sorting' do
 
       it 'works' do
         render
-        expect(d.map(&:id)).to eq([
+        expect(jsonapi_data.map(&:id)).to eq([
           employee1.id,
           employee2.id
         ])
@@ -415,7 +437,7 @@ describe 'sorting' do
 
       it 'works' do
         render
-        expect(d.map(&:id)).to eq([
+        expect(jsonapi_data.map(&:id)).to eq([
           employee2.id,
           employee1.id
         ])
@@ -447,7 +469,7 @@ describe 'sideloading' do
 
     it 'returns position with historical index == 1' do
       render
-      sl = d[0].sideload(:current_position)
+      sl = jsonapi_data[0].sideload(:current_position)
       expect(sl.jsonapi_type).to eq('positions')
       expect(sl.id).to eq(pos2.id)
     end
@@ -669,9 +691,9 @@ RSpec.describe "employees#index", type: :request do
       expect(EmployeeResource).to receive(:all).and_call_original
       make_request
       expect(response.status).to eq(200)
-      expect(d.map(&:jsonapi_type).uniq)
+      expect(jsonapi_data.map(&:jsonapi_type).uniq)
         .to match_array(['employees'])
-      expect(d.map(&:id))
+      expect(jsonapi_data.map(&:id))
         .to match_array([employee1.id, employee2.id])
     end
   end
@@ -694,8 +716,8 @@ describe 'basic fetch' do
     expect(EmployeeResource).to receive(:find).and_call_original
     make_request
     expect(response.status).to eq(200)
-    expect(d.jsonapi_type).to eq('employees')
-    expect(d.id).to eq(employee.id)
+    expect(jsonapi_data.jsonapi_type).to eq('employees')
+    expect(jsonapi_data.id).to eq(employee.id)
   end
 end
 ```
@@ -843,7 +865,7 @@ it 'works' do
   Graphiti.with_context ctx do
     render
   end
-  expect(d[0].salary).to eq(100_000)
+  expect(jsonapi_data[0].salary).to eq(100_000)
 end
 ```
 

data/docs/upgrading.md

@@ -128,9 +128,9 @@ It has to be a request spec. Exceptions are rendered in Rack middleware, which c
 Nothing to do here. These change what a client receives or when a callback runs, and none of them warns you, because none of them is a rename.
 
 <details>
-<summary>A `belongs_to` renders resource linkage in every payload, where 1.x sent only a link</summary>
+<summary>A `belongs_to` renders resource ids when its foreign key already holds them, where 1.x sent only a link</summary>
 
-A `belongs_to` now includes resource linkage in the payload by default, where 1.x sent only a link:
+A `belongs_to` now renders resource ids in the payload by default, where 1.x sent only a link:
 
 ```json
 "employee": { "data": { "type": "employees", "id": "1" }, "links": { "related": "..." } }
@@ -138,27 +138,29 @@ A `belongs_to` now includes resource linkage in the payload by default, where 1.
 
 The id comes from the foreign key already on the parent, so this costs no extra queries, and clients can resolve the relationship against data they already hold instead of following the link. `has_many` is unchanged, since answering there means a query per record.
 
-Not every `belongs_to` qualifies. A `scope` or `params` block, a `base_scope`, a polymorphic or remote target or a custom `primary_key` all mean the foreign key is not the related id, and those keep loading the association, so they stay opt-in as in 1.x.
+Not every `belongs_to` qualifies. A remote target or a custom `primary_key` mean the foreign key is not the related id, a polymorphic target means one rendered type cannot cover every record, and a `scope` or `params` block or a `base_scope` mean the key might not survive the filter. Rendering ids for those means loading the association, so they stay opt-in as in 1.x and render nothing until you ask.
 
-Relationships are marked `linkage: true` in `schema.json`, and the schema check reports a relationship that stops including it.
+Run [`bin/rake graphiti:audit`](/topics/debugging#graphiti-audit) to see where your API stands: it lists every relationship that renders no ids, and why.
 
 To go back to the old payload for one relationship:
 
 ```ruby
-belongs_to :employee, always_include_resource_ids: false
+belongs_to :employee, resource_ids: false
 ```
 
-Or for the whole API, on the resource everything inherits from. The same setting with `true` is the 2.0 replacement for the `Sideload::BelongsTo` monkey patch that [#167](https://github.com/graphiti-api/graphiti/issues/167) has been recommending, and it now covers every relationship type rather than only `belongs_to`:
+Or for the whole API, on the resource everything inherits from:
 
 ```ruby
 class ApplicationResource < Graphiti::Resource
   self.abstract_class = true
 
-  self.always_include_resource_ids_by_default = false
+  self.belongs_to_resource_ids_by_default = :never
 end
 ```
 
-How linkage is configured, and when a `belongs_to` cannot use its foreign key, is covered in [Customizing Relationships](/concepts/relationships#customizing-relationships).
+If you carry the `Sideload::BelongsTo` monkey patch from [#167](https://github.com/graphiti-api/graphiti/issues/167), delete it and set nothing. The default now covers the safe cases on its own. To force ids onto the rest the way the patch did, set `self.belongs_to_resource_ids_by_default = :always`, at a query per record for each one.
+
+The three settings, and when a `belongs_to` cannot use its foreign key, are covered in [Customizing Relationships](/concepts/relationships#belongs-to-resource-ids).
 
 </details>
 
@@ -212,6 +214,7 @@ Every name below still works, warns, and will be removed in the next major. They
 | --- | --- |
 | `require "graphiti_spec_helpers/rspec"` | `require "graphiti/spec_helpers/rspec"` |
 | `GraphitiSpecHelpers::RSpec` / `::Sugar` / `::Errors::*` | `Graphiti::SpecHelpers::*` |
+| `include Graphiti::SpecHelpers::Sugar` (`d`, `included`, `errors`, `dt`) | call `jsonapi_data`, `jsonapi_included`, `jsonapi_errors`, `json_datetime` directly |
 | `require "graphiti-rails"` | remove / no longer needed |
 | `include Graphiti::Rails` | `include Graphiti::Rails::Controller`|
 | `include Graphiti::Responders` | `include Graphiti::Rails::Responders` |
@@ -224,6 +227,7 @@ Every name below still works, warns, and will be removed in the next major. They
 | `context_namespace` | `current_action` |
 | `Graphiti::Rails::DEPRECATOR` | `Graphiti::DEPRECATOR` (the old name still resolves) |
 | `require "graphiti_errors"`, `require "graphiti/responders"` | remove / no longer needed |
+| `always_include_resource_ids: true` on a relationship | `resource_ids: true` |
 
 `RSpec.describe PostResource, type: :resource` still picks up the resource-testing context automatically. That has not changed.
 
@@ -234,6 +238,9 @@ Every name below still works, warns, and will be removed in the next major. They
 | `include GraphitiErrors` | `register_exception` is available on every controller |
 | `GraphitiErrors::ExceptionHandler` | subclass `Graphiti::Rails::ExceptionHandler` |
 | `GraphitiErrors.enable!` / `.disable!` | `handle_request_exceptions` |
+| `self.always_include_resource_ids_by_default` | `self.belongs_to_resource_ids_by_default`, which takes `:foreign_key`, `:always` or `:never` |
+
+`always_include_resource_ids_by_default` only ever shipped in `2.0.0.beta.4`, so it is gone rather than deprecated and raises `NoMethodError` at class-definition time. It applied to every relationship type, and only a `belongs_to` can render resource ids without loading an association, so the replacement covers `belongs_to` alone. `= false` becomes `:never`. There is no equivalent of `= true`, because arming every collection API-wide is the behavior it was removed for. Use `:always` for `belongs_to`.
 
 ## Without Rails {#without-rails}
 

data/graphiti.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rescue_registry", "~> 1.0"
   spec.add_dependency "concurrent-ruby", ">= 1.2", "< 2.0"
   spec.add_dependency "activesupport", ">= 7.1"
-  # Bundled (no longer default) as of Ruby 3.5; graphiti uses OpenStruct in lib/
+  # Bundled (no longer default) as of Ruby 4.0; graphiti uses OpenStruct in lib/
   spec.add_dependency "ostruct", ">= 0.5"
 
   spec.add_development_dependency "faraday", "~> 0.15"

data/lib/generators/graphiti/install_generator.rb

@@ -49,7 +49,6 @@ module Graphiti
 
             RSpec.configure do |config|
               config.include Graphiti::SpecHelpers::RSpec
-              config.include Graphiti::SpecHelpers::Sugar
             end
 
             Graphiti::SpecHelpers::RSpec.schema!

data/lib/generators/graphiti/templates/index_request_spec.rb.erb

@@ -15,8 +15,8 @@ RSpec.describe "<%= type %>#index", type: :request do
       expect(<%= resource_class %>).to receive(:all).and_call_original
       make_request
       expect(response.status).to eq(200), response.body
-      expect(d.map(&:jsonapi_type).uniq).to match_array(['<%= type %>'])
-      expect(d.map(&:<%= id_or_rawid %>)).to match_array([<%= var %>1.id, <%= var %>2.id])
+      expect(jsonapi_data.map(&:jsonapi_type).uniq).to match_array(['<%= type %>'])
+      expect(jsonapi_data.map(&:<%= id_or_rawid %>)).to match_array([<%= var %>1.id, <%= var %>2.id])
     end
   end
 end

data/lib/generators/graphiti/templates/resource_reads_spec.rb.erb

@@ -11,7 +11,7 @@ RSpec.describe <%= resource_class %>, type: :resource do
       expect(data.jsonapi_type).to eq('<%= type %>')
       <%- attributes.each do |a| -%>
       <%- if [:created_at, :updated_at].include?(a.name.to_sym) -%>
-      expect(data.<%= a.name %>).to eq(datetime(<%= file_name %>.<%= a.name %>))
+      expect(data.<%= a.name %>).to eq(json_datetime(<%= file_name %>.<%= a.name %>))
       <%- else -%>
       expect(data.<%= a.name %>).to eq(<%= file_name %>.<%= a.name %>)
       <%- end -%>
@@ -31,7 +31,7 @@ RSpec.describe <%= resource_class %>, type: :resource do
 
       it 'works' do
         render
-        expect(d.map(&:<%= id_or_rawid %>)).to eq([<%= var %>2.id])
+        expect(jsonapi_data.map(&:<%= id_or_rawid %>)).to eq([<%= var %>2.id])
       end
     end
   end
@@ -48,7 +48,7 @@ RSpec.describe <%= resource_class %>, type: :resource do
 
         it 'works' do
           render
-          expect(d.map(&:<%= id_or_rawid %>)).to eq([
+          expect(jsonapi_data.map(&:<%= id_or_rawid %>)).to eq([
             <%= var %>1.id,
             <%= var %>2.id
           ]<%= sort_raw_ids %>)
@@ -62,7 +62,7 @@ RSpec.describe <%= resource_class %>, type: :resource do
 
         it 'works' do
           render
-          expect(d.map(&:<%= id_or_rawid %>)).to eq([
+          expect(jsonapi_data.map(&:<%= id_or_rawid %>)).to eq([
             <%= var %>2.id,
             <%= var %>1.id
           ]<%= sort_raw_ids_descending %>)

data/lib/generators/graphiti/templates/show_request_spec.rb.erb

@@ -14,8 +14,8 @@ RSpec.describe "<%= type %>#show", type: :request do
       expect(<%= resource_class %>).to receive(:find).and_call_original
       make_request
       expect(response.status).to eq(200)
-      expect(d.jsonapi_type).to eq('<%= type %>')
-      expect(d.<%= id_or_rawid %>).to eq(<%= var %>.id)
+      expect(jsonapi_data.jsonapi_type).to eq('<%= type %>')
+      expect(jsonapi_data.<%= id_or_rawid %>).to eq(<%= var %>.id)
     end
   end
 end