graphiti 2.0.0.beta.6 → 2.0.0.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e108e5f71103c3fb7f38f5328a890ff131b264201c583509081cfd3106a7b255
-  data.tar.gz: 18edd07b0ab429ec89309ec94164a2324a21bbbfbd6dd37f6e49bb6f9707f1c9
+  metadata.gz: acced292af02bc2826f89f6e1d9388bcc7fdedabada42e4cc65d1bfaf9f713f5
+  data.tar.gz: 79f966dc31ccb9b3aee687e7dc31a92e943e17845b6017258e366bebee066446
 SHA512:
-  metadata.gz: f2affdd800c2966ef15c5d1765b9d1acc48a032c3ee143b9283d69b9545290e227454d77559e25c94b4cd7b0131d0cdc2addbb031a4177155d8085086d818b3b
-  data.tar.gz: 79c294b775b8be269194cae7e61cf179a16ec8dd01e8b0b24e7a141d3333683bfbd54032e4c07623f6d2dc3fbe3ce6c721884658da89cbe24bfd9dac935f8e07
+  metadata.gz: 22584fd2a83e017219fb8202c965d3d295ac341fed01b2e543355c32722cae741866f3188970ee480018d6063c78b06281045f22934c42b9645de72c6cc9562f
+  data.tar.gz: 502371f38ad71f5e901b57ba187be70bb4d7c85c94544324e825207bc03f120fa652d0859fe56744efbdbcf826376dad84a4917444c62a7e30193482bca47700

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 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)
 
 

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

@@ -214,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` |

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

data/lib/graphiti/query.rb

@@ -4,8 +4,15 @@ module Graphiti
   class Query
     attr_reader :resource, :association_name, :params, :action
 
-    # TODO: make the trailing optionals keywords once the satellite gems are rolled in - see Runner#query for the nil-padding this forces
-    def initialize(resource, params, association_name = nil, nested_include = nil, parents = [], action = nil)
+    def initialize(resource, params, *positional, association_name: nil, nested_include: nil, parents: [], action: nil)
+      if positional.any?
+        Graphiti::DEPRECATOR.warn("Passing Query.new trailing arguments positionally is deprecated. Use association_name:/nested_include:/parents:/action: keywords.")
+        association_name ||= positional[0]
+        nested_include ||= positional[1]
+        parents = positional[2] if positional.length > 2
+        action ||= positional[3]
+      end
+
       @resource = resource
       @association_name = association_name
       @params = params
@@ -21,6 +28,13 @@ module Graphiti
       !!@association_name
     end
 
+    # Concurrent::Map because sideload scopes resolve on pool threads
+    def entity_map
+      return root.entity_map unless root == self
+
+      @entity_map ||= Concurrent::Map.new
+    end
+
     def top_level?
       !association?
     end
@@ -110,9 +124,10 @@ module Graphiti
             relationship_name = sideload ? sideload.name : key
             hash[relationship_name] = Query.new sl_resource,
               @params,
-              key,
-              sub_hash,
-              query_parents, :all
+              association_name: key,
+              nested_include: sub_hash,
+              parents: query_parents,
+              action: :all
           else
             handle_missing_sideload(key)
           end
@@ -124,6 +139,10 @@ module Graphiti
       @parents ||= []
     end
 
+    def root
+      parents.first || self
+    end
+
     def fields
       @fields ||= begin
         hash = parse_fieldset(@params[:fields] || {})

data/lib/graphiti/resource/interface.rb

@@ -17,7 +17,7 @@ module Graphiti
 
         # @api private
         def _all(params, opts, base_scope)
-          runner = Runner.new(self, params, opts.delete(:query), :all)
+          runner = Runner.new(self, params, query: opts.delete(:query), action: :all)
           opts[:params] = params
           runner.proxy(base_scope, opts.merge(caching_options))
         end
@@ -36,7 +36,7 @@ module Graphiti
           params[:filter] ||= {}
           params[:filter][:id] = id if id
 
-          runner = Runner.new(self, params, nil, :find)
+          runner = Runner.new(self, params, action: :find)
 
           find_options = {
             single: true,
@@ -56,7 +56,7 @@ module Graphiti
         # Wrap models fetched outside graphiti so they render like any other proxy
         def wrap(models, base_scope = nil)
           validate_wrap_models!(models)
-          runner = Runner.new(self, {}, nil, :find)
+          runner = Runner.new(self, {}, action: :find)
           runner.proxy(base_scope, bypass_required_filters: true).tap do |proxy|
             proxy.data = models
           end

data/lib/graphiti/runner.rb

@@ -3,8 +3,13 @@ module Graphiti
     attr_reader :params
     attr_reader :deserialized_payload
 
-    # TODO: make query and action keywords once the satellite gems are rolled in - they instantiate Runner positionally
-    def initialize(resource_class, params, query = nil, action = nil)
+    def initialize(resource_class, params, *positional, query: nil, action: nil)
+      if positional.any?
+        Graphiti::DEPRECATOR.warn("Passing query/action to Runner.new positionally is deprecated. Use query:/action: keywords.")
+        query ||= positional[0]
+        action ||= positional[1]
+      end
+
       @resource_class = resource_class
       @params = params
       @query = query
@@ -30,7 +35,7 @@ module Graphiti
     end
 
     def query
-      @query ||= Query.new(jsonapi_resource, params, nil, nil, [], @action)
+      @query ||= Query.new(jsonapi_resource, params, action: @action)
     end
 
     def query_hash

data/lib/graphiti/scope.rb

@@ -154,12 +154,25 @@ module Graphiti
         payload[:results]
       }
       resolved.compact!
+      deduplicate_entities!(resolved)
       assign_serializer(resolved)
       yield resolved if block_given?
       @opts[:after_resolve]&.call(resolved)
       resolved
     end
 
+    # Must run before sideloads assign, so every include path populates the
+    # canonical instance. The resource class in the key keeps two resources
+    # serving the same model from sharing an instance and a serializer.
+    def deduplicate_entities!(resolved)
+      resolved.map! do |record|
+        next record unless record.respond_to?(:id) && !record.id.nil?
+
+        key = [@resource.class, record.class, record.id]
+        @query.entity_map.compute_if_absent(key) { record }
+      end
+    end
+
     def each_applicable_sideload
       @query.sideloads.each_pair do |name, sideload_query|
         sideload = @resource.class.sideload(name)

data/lib/graphiti/spec_helpers.rb

@@ -26,6 +26,11 @@ module Graphiti
     end
 
     module Sugar
+      def self.included(base)
+        Graphiti::DEPRECATOR.warn("Graphiti::SpecHelpers::Sugar is deprecated. Call jsonapi_data, jsonapi_included, jsonapi_errors, json_date and json_datetime directly.")
+        super
+      end
+
       def d
         jsonapi_data
       end

data/lib/graphiti/version.rb

@@ -1,3 +1,3 @@
 module Graphiti
-  VERSION = "2.0.0.beta.6"
+  VERSION = "2.0.0.beta.7"
 end

data/package.json

@@ -22,6 +22,7 @@
   },
   "release": {
     "branches": [
+      "1.x",
       "main",
       {
         "name": "beta",

data/website/sidebars.js

@@ -21,18 +21,18 @@ module.exports = {
       type: 'category',
       label: 'Topics',
       items: [
-        'topics/authorization',
-        'topics/error-handling',
         'topics/testing',
+        'topics/error-handling',
+        'topics/authorization',
         'topics/debugging',
         'topics/caching',
         'topics/etags',
         'topics/json-attributes',
-        'topics/remote-resources',
+        'topics/customizing-sideloads',
         'concepts/backends-and-models',
         'topics/without-activerecord',
         'topics/openstruct-models',
-        'topics/customizing-sideloads',
+        'topics/remote-resources',
         'topics/hopping-relationships',
       ],
     },

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphiti
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta.6
+  version: 2.0.0.beta.7
 platform: ruby
 authors:
 - Lee Richmond