graphiti-activegraph 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96124388fd7da0f681746c33d199a96431291363f8ec3acd1a1ef2533fba7e3b
-  data.tar.gz: ba13ae0e3229a1e31a3e575d8d7b1e8c502a58d6d774ab3326b1936138e09d5c
+  metadata.gz: 64aa5789f68595122f2d8113a497fa4f822f262bed07cac85da0474cb1ed7d51
+  data.tar.gz: f95a5b41c60d54f43e245c0b0279577b69325fb777e41c526f376e7fed40f1a3
 SHA512:
-  metadata.gz: 9985ef640559045360fc73f8dc41daf8ce09b43d92010cddff64bec9967e031cea3d806683865793c0dcca9f3e3092539cee81501b9bcc06e0a6f1bf4b0f1104
-  data.tar.gz: 711c568f287e85dc68d39fcf09b87425c7e8f1c61e20ce656578d1eee12bee57a2c62258a30f9df4e20380d9cebebb020c1951e557ff61d1eb82944dd0eeae64
+  metadata.gz: c2d65e132c567d4fcb814389e199a3b4c4c13d53f83f9604d57ddc98b7dd05573b8527eecc67e78294de9cc9e178ef7ab287ad571626f5854efcc8db30de32a2
+  data.tar.gz: 6fdd6b5a5ec1be222a0905bf1877761c1b81342e0d48f19d662e5ae014c3819938e5a72aaf159e65c86b7a58d173fd2e3d65f66071734e7cc90d9e4d83ea08ed

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -65,6 +65,48 @@ 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.
+
 ## 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/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/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.0'
   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.0
 platform: ruby
 authors:
 - Hardik Joshi
 bindir: exe
 cert_chain: []
-date: 2025-05-20 00:00:00.000000000 Z
+date: 2025-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphiti
@@ -214,6 +214,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