made relationship_id(s) extractable (#49)

* made relationship_id(s) extractable
* Qltysh in github actions (rubocop and code coverage)
* bumped version and updated documentation

Author: mrhardikjoshi

.github/workflows/specs.yml

@@ -10,11 +10,14 @@ on:
   workflow_dispatch:
 
 permissions:
+  actions: write
   contents: read
 
 jobs:
   test:
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
     strategy:
       fail-fast: false
       matrix:
@@ -49,3 +52,8 @@ jobs:
 
       - name: Run tests
         run: bundle exec rspec
+
+      - uses: qltysh/qlty-action/coverage@v1
+        with:
+          oidc: true
+          files: coverage/coverage.json

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.1] - 2025-11-5
+### Added
+- **Deserializer: relationship id(s) helpers**: introduced `relationship_id` and `relationship_ids` methods in `Deserializer` to fetch relationship id(s) by association name from request payload. (PR #49)
+
 ## [1.3.0] - 2025-10-13
 ### Added
 - **Extra fields preloading in main query**: Support preloading associations for `extra_fields` for main and sideloaded records. Adds `preload` option to `extra_attribute` in resource classes. Example: `extra_attribute :full_post_title, :string, preload: :author`. (PR #45)

README.md

@@ -45,6 +45,11 @@ graphiti-activegraph allows assigning and unassigning relationships via sidepost
 Graphiti stores context using `Thread.current[]`, which does not persist across different fibers within the same thread. In graphiti-activegraph, when running on MRI (non-JRuby environments), the gem uses `thread_variable_get` and `thread_variable_set`. Ensuring the context remains consistent across different fibers in the same thread.
 
 ### New Features in graphiti-activegraph
+For detailed API documentation and helper method behavior, see the [docs](./docs) directory.
+- [Deserializer](./docs/deserializer.md)
+- [Adapter](./docs/adapter.md) *(planned)*
+- [Resource](./docs/resource.md) *(planned)*
+
 #### Rendering Preloaded Objects Without Extra Queries
 graphiti-activegraph introduces two new methods on the Graphiti resource class:
 `with_preloaded_obj(record, params)` – Renders a single preloaded ActiveGraph object without querying the database.
@@ -107,6 +112,8 @@ Currently, this feature does not support preloading for deep sideloads such as `
 
 Check [spec/support/factory_bot_setup.rb](https://github.com/mrhardikjoshi/graphiti-activegraph/blob/master/spec/support/factory_bot_setup.rb) and [spec/active_graph/sideload_resolve_spec.rb](https://github.com/mrhardikjoshi/graphiti-activegraph/blob/master/spec/active_graph/sideload_resolve_spec.rb) for examples of usage.
 
+## [CHANGELOG](CHANGELOG.md)
+
 ## Contributing
 Bug reports and pull requests are welcome on GitHub at https://github.com/mrhardikjoshi/graphiti-activegraph. This project is intended to be a safe, welcoming space for collaboration.
 

docs/deserializer.md

@@ -0,0 +1,40 @@
+# Deserializer
+
+### Overview
+Handles incoming JSON:API payloads for Graphiti. Deserializes the request body and provides helper methods to extract and reconcile data, relationships and meta.
+
+### Methods
+
+#### `relationship_id(name)`
+Returns the single related id for the given association name.  
+Used when the relationship is `has_one`.
+
+#### `relationship_ids(name)`
+Returns an array of related ids for the given association name.  
+Used when the relationship is `has_many`.
+
+#### `add_path_id_to_relationships!(params)`
+Ensures that relationship ids passed in the request path are reflected in `params[:data][:relationships]` when missing in the request body.
+If the request body already contains an id for the same relationship, it compares the path and body ids using `detect_conflict` to prevent mismatched identifiers.  
+The method is idempotent per request—subsequent calls are ignored once processed.
+
+**Behavior summary:**
+- Adds missing relationship ids to the request body.
+- Detects and surfaces id mismatches between path and body.
+- Updates the internal `relationships` hash for consistency.
+- Marks the deserializer as updated to avoid repeated execution.
+
+**Parameters:**
+- `params` — Hash (usually the request parameters).
+
+**Returns:**
+- Modified `params` Hash with relationship ids added where necessary.
+
+**Example:**
+```ruby
+# Given a path like /authors/42/books
+path_map = { author: "42" }
+params = { data: { type: "books", attributes: { title: "Graph Databases" } } }
+
+deserializer.add_path_id_to_relationships!(params)
+# => params[:data][:relationships][:author][:data][:id] == "42"

graphiti-activegraph.gemspec

@@ -26,6 +26,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'standard'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'ffaker'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'simplecov_json_formatter'
   spec.add_development_dependency 'factory_bot_rails'
   spec.add_development_dependency 'rake', '>= 10.0'
   spec.add_development_dependency 'rspec', '>= 3.9.0'

lib/graphiti/active_graph/concerns/relationships.rb

@@ -0,0 +1,15 @@
+module Graphiti::ActiveGraph::Concerns
+  module Relationships
+    def relationship?(name)
+      relationships[name.to_sym].present?
+    end
+
+    def relationship_id(name)
+      relationships[name]&.dig(:attributes, :id)
+    end
+
+    def relationship_ids(name)
+      Array.wrap(relationships[name]).pluck(:attributes).pluck(:id)
+    end
+  end
+end

lib/graphiti/active_graph/deserializer.rb

@@ -1,6 +1,7 @@
 module Graphiti::ActiveGraph
   class Deserializer < Graphiti::Deserializer
     include Concerns::PathRelationships
+    include Concerns::Relationships
 
     class Conflict < StandardError
       attr_reader :key, :path_value, :body_value
@@ -55,10 +56,6 @@ def process_relationships(relationship_hash)
       end
     end
 
-    def relationship?(name)
-      relationships[name.to_sym].present?
-    end
-
     # change empty relationship as `disassociate` hash so they will be removed
     def process_nil_relationship(name)
       attributes = {}

lib/graphiti/active_graph/extensions/query_dsl/performer.rb

@@ -23,8 +23,6 @@ def query_generator
     end
 
     def query_generator_config
-      require 'pry'
-      binding.pry
       {
         query: scope,
         with_vars_to_carry:,

lib/graphiti/active_graph/version.rb

@@ -1,5 +1,5 @@
 module Graphiti
   module ActiveGraph
-    VERSION = '1.3.0'
+    VERSION = '1.3.1'
   end
 end

spec/active_graph/deserializer_spec.rb

@@ -39,6 +39,37 @@
     end
   end
 
+  describe '#relationship_id' do
+    let(:rel_data) { { data: { id: 1, type: 'satellites' } } }
+    let(:params) { { data: { relationships: { satellites: rel_data } } }.with_indifferent_access }
+    subject { deserializer.relationship_id(:satellites) }
+
+    it { is_expected.to be 1 }
+
+    context 'with no relationship in payload' do
+      let(:params) { { data: {'type': 'planet'} } }
+      it { is_expected.to be nil }
+    end
+  end
+
+  describe '#relationship_ids' do
+    let(:rel_data) { { data: [{ id: 1, type: 'satellites' }] } }
+    let(:params) { { data: { relationships:  { satellites: rel_data } } }.with_indifferent_access }
+    subject { deserializer.relationship_ids(:satellites) }
+
+    it { is_expected.to contain_exactly(1) }
+
+    context 'with multiple relationships in payload' do
+      let(:rel_data) { { data: [{ id: 1, type: 'satellites' }, { id: 29, type: 'satellites' }] } }
+      it { is_expected.to contain_exactly(1, 29) }
+    end
+
+    context 'with no relationship in payload' do
+      let(:params) { { data: {'type': 'planet'} } }
+      it { is_expected.to be_empty }
+    end
+  end
+
   describe '#relationship?' do
     subject { deserializer.relationship?(rel_name) }