graphiti 1.12.2 → 2.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de4409a60f63682b5bb513238e1101ca1997943a18b136c3d9c507f1eeda9651
-  data.tar.gz: 62b1019afe5fbb095b1323f17c06f7c97f7c15aa0b9dfff3afded57b428ff326
+  metadata.gz: a741f7953d1f54e730d2e801715f3b1d718044a4e0bd59cfd8bb3b364373e715
+  data.tar.gz: 99391699d407dfb92178cf851cce313d691ea930eb0ada81abe764b7a8310087
 SHA512:
-  metadata.gz: b4da6af791178d1a3229dd0c9515792cecacd2bc60ee96274dfc8723af232531a6190e04697f5a1f6e2f9f2b6562a950cfe916657198969e33b0a5251b0854ab
-  data.tar.gz: 1f6561906d4b70bc148563be8c9d20b2dc028006a238993449d59a51fc125efd7c5110d9564a983ed09d749fcd53f46740667aab737e1e7e13d47977569b4246
+  metadata.gz: 77d02ef7c1a525c286d56677ef103f56c7ea80873f565c6db72d2208d887fac967c8f9cddc6a06f940c4a62c6d7faf58390f5331f18fd2a562aa855fff002afd
+  data.tar.gz: e4e83880da4609da20727c8e8bf7b21cddc6e7436d571218da2f874e682dfdbe03c6960799e12614716b936881a8af95ee0459d6458afcaf5f3818dae198543e

data/.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, beta]
   pull_request: {}
   workflow_dispatch: {}
 
@@ -29,7 +29,6 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - "2.7"
           - "3.0"
           - "3.1"
           - "3.2"
@@ -37,10 +36,8 @@ jobs:
           - "3.4"
         gemfile:
           - Gemfile
-          - gemfiles/rails_5_2.gemfile
           - gemfiles/rails_6.gemfile
           - gemfiles/rails_7.gemfile
-          - gemfiles/rails_5_2_graphiti_rails.gemfile
           - gemfiles/rails_6_graphiti_rails.gemfile
           - gemfiles/rails_7_graphiti_rails.gemfile
           - gemfiles/rails_7_1_graphiti_rails.gemfile
@@ -70,14 +67,10 @@ jobs:
           # Skip some extra variants
           - gemfile: Gemfile
             appraisal: true
-          - gemfile: gemfiles/rails_5_2.gemfile
-            appraisal: false
           - gemfile: gemfiles/rails_6.gemfile
             appraisal: false
           - gemfile: gemfiles/rails_7.gemfile
             appraisal: false
-          - gemfile: gemfiles/rails_5_2_graphiti_rails.gemfile
-            appraisal: false
           - gemfile: gemfiles/rails_6_graphiti_rails.gemfile
             appraisal: false
           - gemfile: gemfiles/rails_7_graphiti_rails.gemfile
@@ -92,30 +85,22 @@ jobs:
             appraisal: false
 
           # Rails 8.1 needs ruby 3.2 +
-          - gemfile: gemfiles/rails_8_1_graphiti_rails.gemfile
-            ruby: 2.7
           - gemfile: gemfiles/rails_8_1_graphiti_rails.gemfile
             ruby: 3.0
           - gemfile: gemfiles/rails_8_1_graphiti_rails.gemfile
             ruby: 3.1
 
           # Rails 8 needs ruby 3.2 +
-          - gemfile: gemfiles/rails_8_0_graphiti_rails.gemfile
-            ruby: 2.7
           - gemfile: gemfiles/rails_8_0_graphiti_rails.gemfile
             ruby: 3.0
           - gemfile: gemfiles/rails_8_0_graphiti_rails.gemfile
             ruby: 3.1
 
           # Rails 7.2 needs ruby 3.1 +
-          - gemfile: gemfiles/rails_7_2_graphiti_rails.gemfile
-            ruby: 2.7
           - gemfile: gemfiles/rails_7_2_graphiti_rails.gemfile
             ruby: 3.0
 
           # Rails 7.1 needs ruby 3.0 +
-          - gemfile: gemfiles/rails_7_1_graphiti_rails.gemfile
-            ruby: 2.7
           - gemfile: gemfiles/rails_7_1_graphiti_rails.gemfile
             ruby: 3.0
 
@@ -133,27 +118,6 @@ jobs:
           - gemfile: gemfiles/rails_6_graphiti_rails.gemfile
             ruby: 3.4
 
-          # Rails 5 can't run on Ruby 3
-          - gemfile: gemfiles/rails_5_2.gemfile
-            ruby: 3.0
-          - gemfile: gemfiles/rails_5_2_graphiti_rails.gemfile
-            ruby: 3.0
-          - gemfile: gemfiles/rails_5_2.gemfile
-            ruby: 3.1
-          - gemfile: gemfiles/rails_5_2_graphiti_rails.gemfile
-            ruby: 3.1
-          - gemfile: gemfiles/rails_5_2.gemfile
-            ruby: 3.2
-          - gemfile: gemfiles/rails_5_2_graphiti_rails.gemfile
-            ruby: 3.2
-          - gemfile: gemfiles/rails_5_2.gemfile
-            ruby: 3.3
-          - gemfile: gemfiles/rails_5_2_graphiti_rails.gemfile
-            ruby: 3.3
-          - gemfile: gemfiles/rails_5_2.gemfile
-            ruby: 3.4
-          - gemfile: gemfiles/rails_5_2_graphiti_rails.gemfile
-            ruby: 3.4
     continue-on-error: ${{ matrix.ruby == 'ruby-head' }}
     env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
       BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}
@@ -171,6 +135,8 @@ jobs:
   publish:
     name: Release
     runs-on: ubuntu-latest
+    # Only main auto-releases. Beta releases are cut by manually running
+    # "Generate New Release" with the beta branch selected.
     if: github.ref == 'refs/heads/main'
     needs: [test]
     steps:
@@ -178,4 +144,7 @@ jobs:
         uses: benc-uk/workflow-dispatch@v1
         with:
           workflow: Generate New Release
+          # Without an explicit ref the dispatch runs against the default
+          # branch rather than the branch that triggered it.
+          ref: ${{ github.ref }}
           token: ${{ secrets.GITHUB_TOKEN }}

data/.standard.yml

@@ -1,6 +1,6 @@
 fix: true
 parallel: true
-ruby_version: 2.7
+ruby_version: 3.0
 
 ignore:
   - 'vendor/**/*'

data/Appraisals

@@ -1,18 +1,3 @@
-appraise "rails-5_2" do
-  gem "rails", "~> 5.2.0"
-  gem "rspec-rails"
-  gem "sqlite3", "~> 1.4.0"
-  gem "database_cleaner"
-end
-
-appraise "rails-5_2-graphiti-rails" do
-  gem "rails", "~> 5.2.0"
-  gem "rspec-rails"
-  gem "sqlite3", "~> 1.4.0"
-  gem "database_cleaner"
-  gem "graphiti-rails", "~> 0.4.0"
-end
-
 appraise "rails-6" do
   gem "rails", "~> 6.0"
   gem "rspec-rails"

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 graphiti changelog
 
+# [2.0.0-beta.1](https://github.com/graphiti-api/graphiti/compare/v1.12.2...v2.0.0-beta.1) (2026-07-30)
+
+
+### Features
+
+* drop Ruby 2.7 and Rails 5.2 support ([e905ddb](https://github.com/graphiti-api/graphiti/commit/e905ddb5c842299ffbfe5ec3c4ff98ec9b603a51))
+* the model you inspect is the model that saves ([#465](https://github.com/graphiti-api/graphiti/issues/465)) ([a905fff](https://github.com/graphiti-api/graphiti/commit/a905fffc3a2aa5e663ff4cadcd632e68f053c81a))
+
+
+### BREAKING CHANGES
+
+* around_persistence hooks receive the assigned model instead of the attributes hash. Move attribute-hash modifications to before_attributes, or set values on the model. Custom create/update overrides that should receive a pre-assigned model must accept an assigned_model: keyword. See UPGRADING.md
+* Ruby >= 3.0 / Rails >= 6 are now required.
+
 ## [1.12.2](https://github.com/graphiti-api/graphiti/compare/v1.12.1...v1.12.2) (2026-07-29)
 
 

data/UPGRADING.md

@@ -0,0 +1,71 @@
+# Upgrading Graphiti
+
+## 1.x to 2.0
+
+### Requirements
+
+Graphiti 2.0 requires Ruby 3.0+ and Rails 6.0+ (when using Rails).
+
+### The model you inspect is the model that saves
+
+Proxies returned by `build` and `find` now apply the request payload lazily, and expose the resulting model before anything is written:
+
+```ruby
+# Creates
+resource = MyResource.build(params)
+resource.data          # unsaved model, attributes applied
+resource.data.valid?   # inspect before committing to anything
+resource.save          # persists that same instance
+
+# Updates
+resource = MyResource.find(params)
+resource.assign_attributes(params)
+resource.data.changed  # dirty tracking works
+resource.update
+
+# or assign and save in one call, Rails-style
+resource = MyResource.find(params)
+resource.update(params)
+```
+
+`assign_attributes` is idempotent per payload, validation still runs before assignment, and the instance you inspect is the instance that saves.
+
+### Breaking: around_persistence receives the model, not the attributes hash
+
+To make the above hold, attributes are assigned to the model once, before the persistence hooks fire. `around_persistence` now wraps the save of an already-assigned model and receives that model:
+
+```ruby
+# 1.x
+def do_around_persistence(attributes)
+  attributes[:tenant_id] = current_tenant.id
+  model = yield
+  model.log_saved!
+end
+
+# 2.0
+def do_around_persistence(model)
+  model.tenant_id = current_tenant.id # last chance to touch the model before save, inside the transaction
+  saved = yield
+  saved.log_saved!
+end
+```
+
+To migrate, move attribute-hash modifications to `before_attributes` (which still receives the mutable hash, before assignment), or set the value on the model as above. Hooks that only wrap their yield - transactions, timing, post-save side effects - need no changes. Graphiti 1.x releases warn at runtime when a hook would be affected.
+
+`before/around/after_attributes` and `before/around/after_save` are unchanged.
+
+### Breaking: custom create/update overrides and pre-assigned models
+
+If a resource overrides `create` or `update` and callers inspect the model before saving, the override must accept the already-assigned model:
+
+```ruby
+def create(attributes, meta = nil, assigned_model: nil)
+```
+
+Without the keyword, saving a proxy whose model was inspected raises `Graphiti::Errors::AssignedModelNotSupported` rather than silently discarding changes made to the inspected instance. Overridden resources used only via plain `save` are unaffected.
+
+### Fine print
+
+- If you inspect the model before saving, the attributes callbacks run at inspection time (in your controller, outside the save transaction). On the plain `save` path they run inside the transaction, at the same point as 1.x.
+- Writable guards judge persisted state: a guard asking for the model gets a fresh build/find, never the current request's unsaved changes. A payload cannot influence its own authorization.
+- Sideposted child models are still built and assigned during save; `data` exposes the pre-assigned root model only.

data/graphiti.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-  spec.required_ruby_version = ">= 2.7"
+  spec.required_ruby_version = ">= 3.0"
 
   # TODO: remove once the 1.12 upgrade window has passed
   spec.post_install_message = <<~MSG

data/lib/graphiti/errors.rb

@@ -84,6 +84,25 @@ module Graphiti
       end
     end
 
+    class AssignedModelNotSupported < Base
+      def initialize(resource_class, method_name)
+        @resource_class = resource_class
+        @method_name = method_name
+      end
+
+      def message
+        <<~MSG
+          #{@resource_class}: the model was already assigned via #assign_attributes (or #data before save), but ##{@method_name} is overridden without a parameter to receive it, so changes made to the unsaved model would be silently lost.
+
+          Accept and use the assigned model in your override:
+
+            def #{@method_name}(attributes, meta = nil, assigned_model: nil)
+
+          or persist with #save alone, without inspecting the model first. See UPGRADING.md.
+        MSG
+      end
+    end
+
     class RemoteWrite < Base
       def initialize(resource_class)
         @resource_class = resource_class

data/lib/graphiti/query.rb

@@ -4,6 +4,7 @@ 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)
       @resource = resource
       @association_name = association_name

data/lib/graphiti/request_validators/validator.rb

@@ -17,7 +17,6 @@ module Graphiti
         return true unless @params.has_key?(:data)
 
         resource = @root_resource
-
         if @params[:data].has_key?(:type)
           if (meta_type = deserialized_payload.meta[:type].try(:to_sym))
             if @root_resource.type != meta_type && @root_resource.polymorphic?

data/lib/graphiti/resource/interface.rb

@@ -50,7 +50,7 @@ module Graphiti
         def build(params, base_scope = nil)
           validate_request!(params)
           runner = Runner.new(self, params)
-          runner.proxy(base_scope, single: true, raise_on_missing: true)
+          runner.proxy(base_scope, single: true, raise_on_missing: true, assign_action: :create)
         end
 
         private

data/lib/graphiti/resource/persistence.rb

@@ -69,39 +69,57 @@ module Graphiti
         end
       end
 
-      def create(create_params, meta = nil)
-        model_instance = nil
-
-        run_callbacks :persistence, :create, create_params, meta do
-          run_callbacks :attributes, :create, create_params, meta do |params|
-            model_instance = call_with_meta(:build, model, meta)
-            call_with_meta(:assign_attributes, model_instance, params, meta)
-            model_instance
+      # +model_instance+ is the already-built model from a previous #assign
+      # (see ResourceProxy#assign_attributes). When given, attributes are
+      # applied to it rather than to a freshly built/found model.
+      def assign(assign_params, meta = nil, action_name = nil, model_instance: nil)
+        # Only update strips :id (it identifies the record to find) - a create
+        # payload may legitimately carry a client-supplied id to assign.
+        if action_name == :update
+          id = assign_params[:id]
+          assign_params = assign_params.except(:id)
+        end
+
+        run_callbacks :attributes, action_name, assign_params, meta do |params|
+          model_instance ||= if action_name == :update
+            self.class._find(id: id).data
+          else
+            call_with_meta(:build, model, meta)
           end
+          call_with_meta(:assign_attributes, model_instance, params, meta)
+          model_instance
+        end
+
+        model_instance
+      end
+
+      # Attributes are assigned before the persistence callbacks fire, so
+      # around_persistence receives the assigned model - its pre-yield
+      # position is the last chance to touch the model before save, inside
+      # the transaction. Modify attributes in before_attributes instead.
+      def create(create_params, meta = nil, assigned_model: nil)
+        model_instance = assigned_model || assign(create_params, meta, :create)
 
+        run_callbacks :persistence, :create, model_instance, meta do
           run_callbacks :save, :create, model_instance, meta do
             model_instance = call_with_meta(:save, model_instance, meta)
           end
 
           model_instance
         end
-      end
 
-      def update(update_params, meta = nil)
-        model_instance = nil
-        id = update_params[:id]
-        update_params = update_params.except(:id)
+        model_instance
+      end
 
-        run_callbacks :persistence, :update, update_params, meta do
-          run_callbacks :attributes, :update, update_params, meta do |params|
-            model_instance = self.class._find(id: id).data
-            call_with_meta(:assign_attributes, model_instance, params, meta)
-            model_instance
-          end
+      def update(update_params, meta = nil, assigned_model: nil)
+        model_instance = assigned_model || assign(update_params, meta, :update)
 
+        run_callbacks :persistence, :update, model_instance, meta do
           run_callbacks :save, :update, model_instance, meta do
             model_instance = call_with_meta(:save, model_instance, meta)
           end
+
+          model_instance
         end
 
         model_instance

data/lib/graphiti/resource.rb

@@ -123,9 +123,18 @@ module Graphiti
       adapter.disassociate(parent, child, association_name, type)
     end
 
-    def persist_with_relationships(meta, attributes, relationships, caller_model = nil, foreign_key = nil)
+    # TODO: make foreign_key a keyword once the satellite gems are rolled in - they call these positionally
+    def assign_with_relationships(meta, attributes, relationships, caller_model = nil, foreign_key = nil, model_instance: nil)
       persistence = Graphiti::Util::Persistence \
-        .new(self, meta, attributes, relationships, caller_model, foreign_key)
+        .new(self, meta, attributes, relationships, caller_model, foreign_key,
+          assigned_model: model_instance)
+      persistence.assign
+    end
+
+    def persist_with_relationships(meta, attributes, relationships, caller_model = nil, foreign_key = nil, assigned_model: nil)
+      persistence = Graphiti::Util::Persistence \
+        .new(self, meta, attributes, relationships, caller_model, foreign_key,
+          assigned_model: assigned_model)
       persistence.run
     end
 

data/lib/graphiti/resource_proxy.rb

@@ -11,6 +11,7 @@ module Graphiti
       payload: nil,
       single: false,
       raise_on_missing: false,
+      assign_action: nil,
       cache: nil,
       cache_expires_in: nil,
       cache_tag: nil
@@ -22,6 +23,7 @@ module Graphiti
       @payload = payload
       @single = single
       @raise_on_missing = raise_on_missing
+      @assign_action = assign_action
       @cache = cache
       @cache_expires_in = cache_expires_in
       @cache_tag = cache_tag
@@ -81,7 +83,10 @@ module Graphiti
     end
 
     def data
-      @data ||= begin
+      return @data unless @data.nil?
+      return assign_attributes(@payload.params) if @assign_action
+
+      @data = begin
         records = @scope.resolve
         raise Graphiti::Errors::RecordNotFound if records.empty? && raise_on_missing?
 
@@ -89,6 +94,7 @@ module Graphiti
         records
       end
     end
+
     alias_method :to_a, :data
     alias_method :resolve_data, :data
 
@@ -131,18 +137,56 @@ module Graphiti
       @pagination ||= Delegates::Pagination.new(self)
     end
 
+    # Apply request params to the underlying model without saving it,
+    # Rails-style: the params are always passed explicitly, in the same
+    # request-params shape find/build accept. They are validated,
+    # deserialized, and become the payload #save will persist.
+    #
+    # Idempotent per params - calling again with params that normalize to
+    # the same payload is a no-op, so the attributes callbacks fire once.
+    # Different params re-assign onto the same model instance.
+    #
+    # Note the attributes callbacks fire here, outside any transaction
+    # opened during #save - the persistence hooks wrap only the save phase,
+    # receiving this assigned model.
+    def assign_attributes(params)
+      action = @assign_action || :update
+      params = normalized_params_copy(params)
+      add_endpoint_filter(params, action)
+      validator = ::Graphiti::RequestValidator.new(@resource, params, action)
+      validator.validate!
+
+      if @assigned_model && same_write_payload?(validator.deserialized_payload)
+        return @assigned_model
+      end
+
+      @payload = validator.deserialized_payload
+      @assigned_model = @data = @resource.assign_with_relationships(
+        @payload.meta(action: action),
+        @payload.attributes,
+        @payload.relationships,
+        model_instance: @assigned_model || (data if action == :update)
+      )
+    end
+
     def save(action: :create)
       # TODO: remove this. Only used for persisting many-to-many with AR
       # (see activerecord adapter)
       original = Graphiti.context[:namespace]
       begin
         Graphiti.context[:namespace] = action
-        ::Graphiti::RequestValidator.new(@resource, @payload.params, action).validate!
+        # An assigned model can only come from #assign_attributes, which
+        # validated the payload it stored - re-validating here would run the
+        # writable guards (and their guard_model lookups) a redundant time.
+        unless @assigned_model
+          ::Graphiti::RequestValidator.new(@resource, @payload.params, action).validate!
+        end
         validator = persist {
           @resource.persist_with_relationships \
             @payload.meta(action: action),
             @payload.attributes,
-            @payload.relationships
+            @payload.relationships,
+            assigned_model: @assigned_model
         }
       ensure
         Graphiti.context[:namespace] = original
@@ -179,12 +223,16 @@ module Graphiti
       success
     end
 
-    def update
+    # Rails-style: pass params to assign and save in one call, or call with
+    # no arguments to save a payload assigned earlier (via find or
+    # #assign_attributes).
+    def update(params = nil)
+      assign_attributes(params) if params
       resolve_data
       save(action: :update)
     end
 
-    alias update_attributes update # standard:disable Style/Alias
+    alias_method :update_attributes, :update
 
     def include_hash
       @include_hash ||= begin
@@ -241,6 +289,39 @@ module Graphiti
 
     private
 
+    # Validation typecasts values and injects ids into the params it is
+    # given - work on a deep copy so the caller's hash stays untouched.
+    def normalized_params_copy(params)
+      if params.respond_to?(:to_unsafe_h)
+        params.to_unsafe_h.deep_symbolize_keys
+      else
+        ::Graphiti::Util::Hash.deep_dup(params)
+      end
+    end
+
+    # UpdateValidator enforces that data.id matches the endpoint's filter id.
+    # Params that came through find already carry that filter; params passed
+    # directly to #assign_attributes usually don't, so merge in the id this
+    # proxy was found with. A payload whose data.id names a different record
+    # still fails validation with ConflictRequest. Mutates the copy made by
+    # #normalized_params_copy, never caller state.
+    def add_endpoint_filter(params, action)
+      return unless action == :update
+
+      endpoint_id = @query.filters[:id]
+      return if endpoint_id.nil? || params[:filter].try(:[], :id)
+
+      params[:filter] ||= {}
+      params[:filter][:id] = endpoint_id
+    end
+
+    # Compare only the write payload (data + included) - a repeat call whose
+    # params differ in read-side keys like sort or page is still a no-op.
+    def same_write_payload?(deserialized_payload)
+      deserialized_payload.params.values_at(:data, :included) ==
+        @payload.params.values_at(:data, :included)
+    end
+
     def persist
       transaction_response = @resource.transaction do
         ::Graphiti::Util::TransactionHooksRecorder.record do

data/lib/graphiti/runner.rb

@@ -3,12 +3,12 @@ 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)
       @resource_class = resource_class
       @params = params
       @query = query
       @action = action
-
       validator = RequestValidator.new(jsonapi_resource, params, action)
       validator.validate!
 
@@ -77,6 +77,7 @@ module Graphiti
         payload: deserialized_payload,
         single: opts[:single],
         raise_on_missing: opts[:raise_on_missing],
+        assign_action: opts[:assign_action],
         cache: opts[:cache],
         cache_expires_in: opts[:cache_expires_in],
         cache_tag: opts[:cache_tag]

data/lib/graphiti/serializer.rb

@@ -103,6 +103,7 @@ module Graphiti
     def strip_relationships?
       return false unless Graphiti.config.links_on_demand
       params = Graphiti.context[:object]&.params || {}
+
       [false, nil, "false"].include?(params[:links])
     end
   end

data/lib/graphiti/util/hash.rb

@@ -55,8 +55,15 @@ module Graphiti
         else
           {}.tap do |duped|
             hash.each_pair do |key, value|
-              value = deep_dup(value) if value.is_a?(Hash)
-              value = value.dup if value&.respond_to?(:dup) && ![Symbol, Integer].include?(value.class)
+              value = if value.is_a?(Hash)
+                deep_dup(value)
+              elsif value.is_a?(Array)
+                value.map { |element| element.is_a?(Hash) ? deep_dup(element) : element }
+              elsif value&.respond_to?(:dup) && ![Symbol, Integer].include?(value.class)
+                value.dup
+              else
+                value
+              end
               duped[key] = value
             end
           end

data/lib/graphiti/util/persistence.rb

@@ -7,8 +7,12 @@ class Graphiti::Util::Persistence
   # @param [Hash] relationships see (Deserializer#relationships)
   # @param [Model] caller_model The persisted parent object in the request graph
   # @param [Symbol] foreign_key Attribute assigned by parent object in graph
-  def initialize(resource, meta, attributes, relationships, caller_model, foreign_key = nil)
+  # @param [Model] assigned_model a model already built by #assign, to be
+  #   assigned onto rather than rebuilt
+  # TODO: make foreign_key a keyword once the satellite gems are rolled in
+  def initialize(resource, meta, attributes, relationships, caller_model, foreign_key = nil, assigned_model: nil)
     @resource = resource
+    @assigned_model = assigned_model
     @meta = meta
     @attributes = attributes
     @relationships = relationships
@@ -24,6 +28,14 @@ class Graphiti::Util::Persistence
     end
   end
 
+  def assign
+    attributes = @adapter.persistence_attributes(self, @attributes)
+    assigned = @resource.assign(attributes, metadata, @meta[:method], model_instance: @assigned_model)
+    @resource.decorate_record(assigned)
+
+    assigned
+  end
+
   # Perform the actual save logic.
   #
   # belongs_to must be processed before/separately from has_many -
@@ -46,11 +58,13 @@ class Graphiti::Util::Persistence
   def run
     attributes = @adapter.persistence_attributes(self, @attributes)
 
+    payload_attributes = attributes.dup
     parents = @adapter.process_belongs_to(self, attributes)
+    apply_derived_attributes(attributes, payload_attributes)
     persisted = persist_object(@meta[:method], attributes)
     @resource.decorate_record(persisted)
-    assign_temp_id(persisted, @meta[:temp_id])
 
+    assign_temp_id(persisted, @meta[:temp_id])
     associate_parents(persisted, parents)
 
     children = @adapter.process_has_many(self, persisted)
@@ -81,6 +95,19 @@ class Graphiti::Util::Persistence
 
   private
 
+  # process_belongs_to persists the parents and writes their primary keys into
+  # +attributes+. A model that was already assigned (see ResourceProxy#assign_attributes)
+  # predates those keys, so apply just them - the payload attributes are already on it,
+  # and re-applying them would clobber any changes made since.
+  def apply_derived_attributes(attributes, payload_attributes)
+    return unless @assigned_model
+
+    derived = attributes.reject { |key, value| payload_attributes[key] == value }
+    return if derived.empty?
+
+    @resource.assign_attributes(@assigned_model, derived, metadata)
+  end
+
   def add_hook(prc, lifecycle_event)
     ::Graphiti::Util::TransactionHooksRecorder.add(prc, lifecycle_event)
   end
@@ -163,10 +190,19 @@ class Graphiti::Util::Persistence
     }
   end
 
+  def accepts_assigned_model?(method)
+    method.parameters.any? { |type, name| name == :assigned_model && [:key, :keyreq].include?(type) }
+  end
+
   def call_resource_method(method_name, attributes, caller_model)
     method = @resource.method(method_name)
 
-    if method.arity == 1
+    if @assigned_model && [:create, :update].include?(method_name)
+      unless accepts_assigned_model?(method)
+        raise Graphiti::Errors::AssignedModelNotSupported.new(@resource.class, method_name)
+      end
+      method.call(attributes, metadata, assigned_model: @assigned_model)
+    elsif method.arity == 1
       method.call(attributes)
     else
       method.call(attributes, metadata)

data/lib/graphiti/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphiti
 version: !ruby/object:Gem::Version
-  version: 1.12.2
+  version: 2.0.0.beta.1
 platform: ruby
 authors:
 - Lee Richmond
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-29 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jsonapi-serializable
@@ -248,6 +248,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- UPGRADING.md
 - bin/appraisal
 - bin/console
 - bin/rspec
@@ -269,8 +270,6 @@ files:
 - deprecated_generators/graphiti/templates/update_request_spec.rb.erb
 - exe/graphiti
 - gemfiles/.bundle/config
-- gemfiles/rails_5_2.gemfile
-- gemfiles/rails_5_2_graphiti_rails.gemfile
 - gemfiles/rails_6.gemfile
 - gemfiles/rails_6_graphiti_rails.gemfile
 - gemfiles/rails_7.gemfile
@@ -386,12 +385,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.27
 signing_key:

data/gemfiles/rails_5_2.gemfile

@@ -1,18 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rails", "~> 5.2.0"
-gem "rspec-rails"
-gem "sqlite3", "~> 1.4.0"
-gem "database_cleaner"
-
-group :test do
-  gem "pry"
-  gem "pry-byebug", platform: [:mri]
-  gem "appraisal"
-  gem "guard"
-  gem "guard-rspec"
-end
-
-gemspec path: "../"

data/gemfiles/rails_5_2_graphiti_rails.gemfile

@@ -1,19 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "rails", "~> 5.2.0"
-gem "rspec-rails"
-gem "sqlite3", "~> 1.4.0"
-gem "database_cleaner"
-gem "graphiti-rails", "~> 0.4.0"
-
-group :test do
-  gem "pry"
-  gem "pry-byebug", platform: [:mri]
-  gem "appraisal"
-  gem "guard"
-  gem "guard-rspec"
-end
-
-gemspec path: "../"