graphiti-activegraph 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96124388fd7da0f681746c33d199a96431291363f8ec3acd1a1ef2533fba7e3b
-  data.tar.gz: ba13ae0e3229a1e31a3e575d8d7b1e8c502a58d6d774ab3326b1936138e09d5c
+  metadata.gz: 99c8c00fe58ed3146c7feae681bac89ec82989b09f88dfa97aa6a54ef7e9930b
+  data.tar.gz: c21e632e4fa1a4f6b24315c01c76d89f91158ae9996a73cdf6da83e97805e2ce
 SHA512:
-  metadata.gz: 9985ef640559045360fc73f8dc41daf8ce09b43d92010cddff64bec9967e031cea3d806683865793c0dcca9f3e3092539cee81501b9bcc06e0a6f1bf4b0f1104
-  data.tar.gz: 711c568f287e85dc68d39fcf09b87425c7e8f1c61e20ce656578d1eee12bee57a2c62258a30f9df4e20380d9cebebb020c1951e557ff61d1eb82944dd0eeae64
+  metadata.gz: 8942c7a92552d7554cdc78e5183b970bab9c6d9cee23e5d21e23244c84c45491bbd5a3085671cde7919ca3f7e531cd2e7c6388f0ad367cecc430b77597c0db9c
+  data.tar.gz: e31a9631f62d743899851ea815c2158c801f550a5d7ec86eafab260045441fbbd84813f0c5511f9cadc3ad2a7fe8b750d315effc65cbc46866235d31f136731a

data/.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

data/CHANGELOG.md

@@ -7,6 +7,15 @@ 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)
+- **Extra fields preloading in separate query**: Collect IDs from the main query result and run a single separate query to load and calculate `extra_fields` values for all records. does not support preloading for deep sideloads. (PR #47)
+
 ## [1.2.0] - 2025-05-20
 
 ### Added

data/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.
@@ -65,6 +70,50 @@ Control the links in response payload via request query params:
 - `pagination_links=true|false` — toggle top-level pagination links
 - `links=true|false` — toggle links inside each resource object
 
+#### Preload Extra Attribute Associations via `preload:` option
+You can declare an extra attribute on your resource and specify an association to preload using the `preload:` option.
+  Example:
+  ```ruby
+    extra_attribute :full_post_title, :string, preload: :author
+  ```
+Check [spec/active_graph/scoping/internal/extra_field_normalizer_spec.rb](https://github.com/mrhardikjoshi/graphiti-activegraph/blob/master/spec/active_graph/scoping/internal/extra_field_normalizer_spec.rb) for examples of usage `preload:` option.
+
+#### Preload Extra Fields via Model Preload Method
+You can define a custom preload method with prefix `preload_` in your model (e.g., `preload_posts_number` for the posts_number extra field) that fetches values for the extra attribute.
+When you request an extra field (e.g., `posts_number`) in your query, graphiti-activegraph will call this method, passing all relevant record IDs, and assign the returned values to each record’s extra attribute.
+This works for both top-level results and sideloaded records of the matching resource type.
+
+##### Usage example
+```ruby
+  class Comment
+    # Allows assignment of the extra field value by the preloader
+    attr_writer :author_activity
+
+    def author_activity
+      @author_activity ||= author.comments.count + author.posts.count
+    end
+
+    # Preload method which fetches values for the extra_attribute
+    def self.preload_author_activity(comment_ids)
+      where(id: comment_ids).with_associations(author: [:posts, :comments]).to_h do |comment|
+        author = comment.author
+        [comment.id, author.posts.count + author.comments.count]
+      end
+    end
+  end
+
+  class CommentResource < Graphiti::ActiveGraph::Resource
+    extra_attribute :author_activity, :integer
+  end
+```
+
+**Note:**
+Currently, this feature does not support preloading for deep sideloads such as `posts.comment.author*`. Deeply sideloaded records will not appear in the array of relevant records for preload, and thus will not have extra fields assigned.
+
+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.
 

data/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"

data/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'

data/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

data/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 @@ module Graphiti::ActiveGraph
       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 = {}

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

@@ -0,0 +1,38 @@
+module Graphiti::ActiveGraph::Extensions::QueryDsl
+  module Performer
+    attr_accessor :with_vars, :skip_arrow_cypher_rels
+
+    def apply_query_dsl
+      query_param = resource.context&.params&.[](:query)
+      query_param.present? ? apply_query_param(query_param) : scope
+    end
+
+    def apply_query_param(query_param)
+      @scope = query_generator.new(query_param, **query_generator_config).tap do |qg|
+        qg.generate_functions_optional_match
+        qg.generate_with_clause_partition_query
+        qg.generate_match_query
+        qg.generate_with_clause_query
+      end.query
+    end
+
+    private
+
+    def query_generator
+      Graphiti::ActiveGraph::Extensions::QueryDsl::QueryGenerator
+    end
+
+    def query_generator_config
+      {
+        query: scope,
+        with_vars_to_carry:,
+        skip_arrow_cypher_rels: skip_arrow_cypher_rels || [],
+        resource: resource.class
+      }
+    end
+
+    def with_vars_to_carry
+      (query ? with_vars_for_sort : []).push(*with_vars).push(*Graphiti.context[:with_vars]).compact
+    end
+  end
+end

data/lib/graphiti/active_graph/extensions/query_dsl/query_generator.rb

@@ -0,0 +1,20 @@
+module Graphiti::ActiveGraph::Extensions::QueryDsl
+  class QueryGenerator
+    def initialize(query_param, query:, **config)
+      @query_param = query_param
+      @query = query
+    end
+
+    def generate_functions_optional_match
+    end
+
+    def generate_with_clause_partition_query
+    end
+
+    def generate_match_query
+    end
+
+    def generate_with_clause_query
+    end
+  end
+end

data/lib/graphiti/active_graph/resource.rb

@@ -45,8 +45,9 @@ module Graphiti
 
       def handle_includes(scope, includes, sorts, **opts)
         includes_str = JSONAPI::IncludeDirective.new(includes, retain_rel_limit: true).to_string.split(',')
+        extra_includes_str = opts.delete(:extra_fields_includes) || []
         options = opts.merge(max_page_size:).merge!(authorize_scope_params)
-        scope.with_ordered_associations(includes_str, sorts, options)
+        scope.with_ordered_associations(includes_str.union(extra_includes_str), sorts, options)
       end
 
       def sideload_name_arr(query)

data/lib/graphiti/active_graph/scoping/filter.rb

@@ -2,6 +2,15 @@ module Graphiti::ActiveGraph
   module Scoping
     module Filter
       include Filterable
+      include Internal::SortingAliases
+      include Extensions::QueryDsl::Performer
+
+      attr_reader :scope
+
+      def apply
+        super
+        apply_query_dsl
+      end
 
       def each_filter
         filter_param.each_pair do |param_name, param_value|

data/lib/graphiti/active_graph/scoping/include.rb

@@ -10,9 +10,10 @@ module Graphiti::ActiveGraph
       end
 
       def apply_standard_scope
-        return scope if normalized_includes.empty?
+        return scope if normalized_includes.empty? && extra_fields_includes.empty?
+
         self.scope = resource.handle_includes(scope, normalized_includes, normalized_sorts,
-                                              with_vars: with_vars_for_sort, paginate: paginate?)
+                                              extra_fields_includes:, with_vars: with_vars_for_sort, paginate: paginate?)
       end
 
       private
@@ -23,6 +24,10 @@ module Graphiti::ActiveGraph
         @opts[:query_obj]
       end
 
+      def extra_fields_includes
+        @extra_fields_includes ||= Internal::ExtraFieldNormalizer.new(@query_hash[:extra_fields]).normalize(resource, normalized_includes)
+      end
+
       def paginate?
         Graphiti::Scoping::Paginate.new(@resource, @query_hash, scope, @opts).apply?
       end

data/lib/graphiti/active_graph/scoping/internal/extra_field_normalizer.rb

@@ -0,0 +1,76 @@
+module Graphiti::ActiveGraph
+  module Scoping
+    module Internal
+      class ExtraFieldNormalizer
+
+        def initialize(extra_fields)
+          @extra_fields = extra_fields
+          @extra_includes = []
+        end
+
+        def normalize(resource, normalized_includes)
+          return [] if @extra_fields.blank?
+
+          process_extra_fields_for_assoc(resource, [], '')
+          collect_extra_field_paths(resource, normalized_includes) unless normalized_includes.blank?
+          @extra_includes.uniq
+        end
+
+        private
+
+        def collect_extra_field_paths(resource, normalized_includes, parent_path = [])
+          normalized_includes.each do |assoc, nested_assoc|
+            assoc_resource = fetch_assoc_resource(resource, assoc)
+            next unless assoc_resource
+
+            process_extra_fields_for_assoc(assoc_resource, parent_path, assoc)
+            collect_extra_field_paths(assoc_resource, nested_assoc, parent_path + [assoc.to_s]) unless nested_assoc.empty?
+          end
+        end
+
+        def fetch_assoc_resource(resource, assoc)
+          rel_name = Util::Transformers::RelationParam.new(assoc).rel_name_sym
+          resource.class&.sideload_resource_class(rel_name)&.new
+        end
+
+        def process_extra_fields_for_assoc(assoc_resource, parent_path, assoc)
+          return unless @extra_fields.key?(assoc_resource.type)
+
+          Array(@extra_fields[assoc_resource.type]).each do |extra_field|   
+            add_preload_paths_for_extra_field(extra_field_config(assoc_resource, extra_field), parent_path, assoc)
+          end
+        end
+
+        def extra_field_config(assoc_resource, extra_field)
+          assoc_resource.class&.config&.dig(:extra_attributes, extra_field)
+        end
+
+        def add_preload_paths_for_extra_field(config, parent_path, assoc)
+          return unless config && config[:preload].present?
+            
+          flatten_preload_hash(config[:preload]).each do |preload|
+            @extra_includes << construct_preload_path(parent_path, assoc, preload)
+          end
+        end
+
+        def flatten_preload_hash(preload, prefix = [])
+          case preload
+          when Hash
+            preload.flat_map { |k, v| flatten_preload_hash(v, prefix + [k.to_s]) }
+          when Array
+            preload.flat_map { |v| flatten_preload_hash(v, prefix) }
+          else
+            value = preload.to_s
+            return [] if value.empty?
+
+            [(prefix + [value]).join('.')]
+          end
+        end
+
+        def construct_preload_path(parent_path, assoc, preload)
+          (parent_path + [assoc.to_s, preload.to_s]).compact_blank.join('.')
+        end
+      end
+    end
+  end
+end

data/lib/graphiti/active_graph/sideload_resolve.rb

@@ -43,32 +43,77 @@ module Graphiti::ActiveGraph
     end
 
     def preload_extra_fields(results)
-      requested_extra_fields.each do |extra_field_name|
-        next unless preload_extra_field?(extra_field_name)
+      @query.extra_fields.each do |type, extra_field_names|
+        extra_field_names.each do |name|
+          next unless preload_extra_field?(type, name)
 
-        result_map = fetch_preloaded_data(extra_field_name, results)
-        assign_preloaded_data(results, extra_field_name, result_map)
+          records_for_preload = collect_records_for_preload(type, results)
+          result_map = fetch_preloaded_data(type, name, records_for_preload)
+          assign_preloaded_data(records_for_preload, name, result_map)
+        end
       end
     end
 
-    def requested_extra_fields
-      @query.extra_fields[@resource.type] || []
-    end
-
-    def fetch_preloaded_data(extra_field_name, results)
-      @resource.model.public_send(default_preload_method(extra_field_name), results.pluck(:id))
+    def fetch_preloaded_data(type, extra_field_name, results)
+      resource_for_preload(type).model.public_send(default_preload_method(extra_field_name), results.pluck(:id).uniq)
     end
 
     def assign_preloaded_data(results, extra_field_name, result_map)
       results.each { |r| r.public_send("#{extra_field_name}=", result_map[r.id]) }
     end
 
-    def preload_extra_field?(extra_field_name)
-      @resource.extra_attribute?(extra_field_name) && @resource.model.respond_to?(default_preload_method(extra_field_name))
+    def preload_extra_field?(type, extra_field_name)
+      resource = resource_for_preload(type)
+      resource && resource.extra_attribute?(extra_field_name) && resource.model.respond_to?(default_preload_method(extra_field_name))
+    end
+
+    def resource_for_preload(type)
+      return @resource if type == @resource.type
+
+      find_resource_in_included_associations(type) unless @query.sideloads.empty?
+    end
+
+    def find_resource_in_included_associations(type, sideload_query = @query)
+      sideload_query.sideloads.values.each do |sideload|
+        return sideload.resource if sideload.resource.type == type
+
+        resource = find_resource_in_included_associations(type, sideload)
+        return resource if resource
+      end
+
+      nil
     end
 
     def default_preload_method(extra_field_name)
       "#{PRELOAD_METHOD_PREFIX}#{extra_field_name}"
     end
+
+    def collect_records_for_preload(type, results)
+      base_records = resource_matches_type?(@resource, type) ? Array(results) : []
+      sideloaded_records = collect_sideloaded_records(Array(results), @query, type)
+      (base_records + sideloaded_records).flatten.compact.uniq
+    end
+
+    def collect_sideloaded_records(source_records, sideload_query, type)
+      return [] if source_records.empty? || sideload_query.sideloads.empty?
+
+      sideload_query.sideloads.flat_map do |sideload_name, nested_query|
+        associated_records = collect_associated_records(source_records, sideload_name)
+        matched_records = resource_matches_type?(nested_query.resource, type) ? associated_records : []
+        matched_records + collect_sideloaded_records(associated_records, nested_query, type)
+      end
+    end
+
+    def resource_matches_type?(resource, type)
+      resource&.type == type
+    end
+
+    def collect_associated_records(source_records, sideload_name)
+      source_records.flat_map do |parent|
+        next [] unless parent.respond_to?(sideload_name)
+
+        Array(parent.public_send(sideload_name)).compact
+      end
+    end
   end
 end

data/lib/graphiti/active_graph/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: graphiti-activegraph
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Hardik Joshi
 bindir: exe
 cert_chain: []
-date: 2025-05-20 00:00:00.000000000 Z
+date: 2025-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphiti
@@ -127,6 +127,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov_json_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: factory_bot_rails
   requirement: !ruby/object:Gem::Requirement
@@ -183,6 +211,7 @@ files:
 - Gemfile
 - LICENSE.txt
 - README.md
+- docs/deserializer.md
 - graphiti-activegraph.gemspec
 - lib/graphiti-activegraph.rb
 - lib/graphiti/active_graph/adapters/active_graph.rb
@@ -192,9 +221,12 @@ files:
 - lib/graphiti/active_graph/adapters/active_graph/polymorphic_belongs_to.rb
 - lib/graphiti/active_graph/adapters/active_graph/sideload.rb
 - lib/graphiti/active_graph/concerns/path_relationships.rb
+- lib/graphiti/active_graph/concerns/relationships.rb
 - lib/graphiti/active_graph/deserializer.rb
 - lib/graphiti/active_graph/extensions/context.rb
 - lib/graphiti/active_graph/extensions/grouping/params.rb
+- lib/graphiti/active_graph/extensions/query_dsl/performer.rb
+- lib/graphiti/active_graph/extensions/query_dsl/query_generator.rb
 - lib/graphiti/active_graph/extensions/query_params.rb
 - lib/graphiti/active_graph/extensions/resources/authorizationable.rb
 - lib/graphiti/active_graph/extensions/resources/payload_combinable.rb
@@ -214,6 +246,7 @@ files:
 - lib/graphiti/active_graph/scoping/filter.rb
 - lib/graphiti/active_graph/scoping/filterable.rb
 - lib/graphiti/active_graph/scoping/include.rb
+- lib/graphiti/active_graph/scoping/internal/extra_field_normalizer.rb
 - lib/graphiti/active_graph/scoping/internal/include_normalizer.rb
 - lib/graphiti/active_graph/scoping/internal/path_descriptor.rb
 - lib/graphiti/active_graph/scoping/internal/sort_normalizer.rb