active_shopify_graphql 0.2.0 → 0.4.0

data/lib/active_shopify_graphql/fragment_builder.rb

@@ -30,18 +30,29 @@ module ActiveShopifyGraphQL
     def build_field_nodes
       path_tree = {}
       metafield_aliases = {}
+      raw_graphql_nodes = []
+      aliased_field_nodes = []
 
       # Build a tree structure for nested paths
-      @context.defined_attributes.each_value do |config|
-        if config[:is_metafield]
+      @context.defined_attributes.each do |attr_name, config|
+        if config[:raw_graphql]
+          raw_graphql_nodes << build_raw_graphql_node(attr_name, config[:raw_graphql])
+        elsif config[:is_metafield]
           store_metafield_config(metafield_aliases, config)
         else
-          build_path_tree(path_tree, config[:path])
+          path = config[:path]
+          if path.include?('.')
+            # Nested path - use tree structure (shared prefixes)
+            build_path_tree(path_tree, path)
+          else
+            # Simple path - add aliased field node
+            aliased_field_nodes << build_aliased_field_node(attr_name, path)
+          end
         end
       end
 
       # Convert tree to QueryNode objects
-      nodes_from_tree(path_tree) + metafield_nodes(metafield_aliases)
+      nodes_from_tree(path_tree) + aliased_field_nodes + metafield_nodes(metafield_aliases) + raw_graphql_nodes
     end
 
     # Build QueryNode objects for all connections (protected for recursive calls)
@@ -74,6 +85,23 @@ module ActiveShopifyGraphQL
       }
     end
 
+    def build_raw_graphql_node(attr_name, raw_graphql)
+      # Prepend alias to raw GraphQL for predictable response mapping
+      aliased_raw_graphql = "#{attr_name}: #{raw_graphql}"
+      QueryNode.new(
+        name: "raw",
+        arguments: { raw_graphql: aliased_raw_graphql },
+        node_type: :raw
+      )
+    end
+
+    def build_aliased_field_node(attr_name, path)
+      alias_name = attr_name.to_s
+      # Only add alias if the attr_name differs from the GraphQL field name
+      alias_name = nil if alias_name == path
+      QueryNode.new(name: path, alias_name: alias_name, node_type: :field)
+    end
+
     def build_path_tree(path_tree, path)
       path_parts = path.split('.')
       current_level = path_tree
@@ -120,12 +148,17 @@ module ActiveShopifyGraphQL
       child_nodes = build_target_field_nodes(target_context, nested_includes)
 
       query_name = connection_config[:query_name]
+      original_name = connection_config[:original_name]
       connection_type = connection_config[:type] || :connection
       formatted_args = (connection_config[:default_arguments] || {}).transform_keys(&:to_sym)
 
+      # Add alias if the connection name differs from the query name
+      alias_name = original_name.to_s == query_name ? nil : original_name.to_s
+
       node_type = connection_type == :singular ? :singular : :connection
       QueryNode.new(
         name: query_name,
+        alias_name: alias_name,
         arguments: formatted_args,
         node_type: node_type,
         children: child_nodes

data/lib/active_shopify_graphql/graphql_associations.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Allows ActiveRecord (or duck-typed) objects to define associations to GraphQL objects
+  # This module bridges the gap between local database records and remote Shopify GraphQL data
+  #
+  # @example
+  #   class Reward < ApplicationRecord
+  #     include ActiveShopifyGraphQL::GraphQLAssociations
+  #
+  #     belongs_to_graphql :customer
+  #     has_many_graphql :variants, class: "ProductVariant", query_name: "productVariants"
+  #   end
+  #
+  #   reward = Reward.first
+  #   customer = reward.customer # => ActiveShopifyGraphQL::Customer instance
+  #   variants = reward.variants(first: 10) # => Array of ProductVariant instances
+  module GraphQLAssociations
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        attr_accessor :graphql_associations
+      end
+
+      self.graphql_associations = {}
+    end
+
+    class_methods do
+      # Define a belongs_to relationship with a GraphQL object
+      # Fetches a single GraphQL object using a stored GID or foreign key
+      #
+      # @param name [Symbol] The association name (e.g., :customer)
+      # @param class_name [String] The target GraphQL model class name (defaults to name.to_s.classify)
+      # @param foreign_key [Symbol, String] The attribute/column storing the GID or ID (defaults to "shopify_#{name}_id")
+      # @param loader_class [Class] Custom loader class (defaults to target class's default_loader)
+      #
+      # @example Basic usage
+      #   belongs_to_graphql :customer
+      #   # Expects: shopify_customer_id column with GID like "gid://shopify/Customer/123"
+      #
+      # @example With custom foreign key
+      #   belongs_to_graphql :customer, foreign_key: :customer_gid
+      #
+      # @example With custom class
+      #   belongs_to_graphql :owner, class_name: "Customer"
+      def belongs_to_graphql(name, class_name: nil, foreign_key: nil, loader_class: nil)
+        association_class_name = class_name || name.to_s.classify
+        association_foreign_key = foreign_key || "shopify_#{name}_id"
+
+        # Store association metadata
+        graphql_associations[name] = {
+          type: :belongs_to,
+          class_name: association_class_name,
+          foreign_key: association_foreign_key,
+          loader_class: loader_class
+        }
+
+        # Define the association method
+        define_method name do
+          return @_graphql_association_cache[name] if @_graphql_association_cache&.key?(name)
+
+          @_graphql_association_cache ||= {}
+
+          # Get the GID or ID value from the foreign key
+          gid_or_id = send(association_foreign_key)
+          return @_graphql_association_cache[name] = nil if gid_or_id.blank?
+
+          # Resolve the target class
+          target_class = association_class_name.constantize
+
+          # Determine which loader to use
+          loader = if self.class.graphql_associations[name][:loader_class]
+                     self.class.graphql_associations[name][:loader_class].new(target_class)
+                   else
+                     target_class.default_loader
+                   end
+
+          # Load and cache the GraphQL object
+          @_graphql_association_cache[name] = target_class.find(gid_or_id, loader: loader)
+        end
+
+        # Define setter method for testing/mocking
+        define_method "#{name}=" do |value|
+          @_graphql_association_cache ||= {}
+          @_graphql_association_cache[name] = value
+        end
+      end
+
+      # Define a has_one relationship with a GraphQL object
+      # Fetches a single GraphQL object using a where clause
+      #
+      # @param name [Symbol] The association name (e.g., :primary_address)
+      # @param class_name [String] The target GraphQL model class name (defaults to name.to_s.classify)
+      # @param foreign_key [Symbol, String] The attribute on GraphQL objects to filter by (e.g., :customer_id)
+      # @param primary_key [Symbol, String] The local attribute to use as filter value (defaults to :id)
+      # @param loader_class [Class] Custom loader class (defaults to target class's default_loader)
+      #
+      # @example Basic usage
+      #   has_one_graphql :primary_address, class_name: "Address", foreign_key: :customer_id
+      #   customer.primary_address # Returns first Address where customer_id matches
+      def has_one_graphql(name, class_name: nil, foreign_key: nil, primary_key: nil, loader_class: nil)
+        association_class_name = class_name || name.to_s.classify
+        association_primary_key = primary_key || :id
+        association_loader_class = loader_class
+
+        # Store association metadata
+        graphql_associations[name] = {
+          type: :has_one,
+          class_name: association_class_name,
+          foreign_key: foreign_key,
+          primary_key: association_primary_key,
+          loader_class: association_loader_class
+        }
+
+        # Define the association method
+        define_method name do
+          return @_graphql_association_cache[name] if @_graphql_association_cache&.key?(name)
+
+          @_graphql_association_cache ||= {}
+
+          # Get primary key value
+          primary_key_value = send(association_primary_key)
+          return @_graphql_association_cache[name] = nil if primary_key_value.blank?
+
+          # Resolve the target class
+          target_class = association_class_name.constantize
+
+          # Determine which loader to use
+          loader = if self.class.graphql_associations[name][:loader_class]
+                     self.class.graphql_associations[name][:loader_class].new(target_class)
+                   else
+                     target_class.default_loader
+                   end
+
+          # Query with foreign key filter if provided
+          result = if self.class.graphql_associations[name][:foreign_key]
+                     foreign_key_sym = self.class.graphql_associations[name][:foreign_key]
+                     query_conditions = { foreign_key_sym => primary_key_value }
+                     target_class.where(query_conditions, loader: loader).first
+                   end
+
+          # Cache the result
+          @_graphql_association_cache[name] = result
+        end
+
+        # Define setter method for testing/mocking
+        define_method "#{name}=" do |value|
+          @_graphql_association_cache ||= {}
+          @_graphql_association_cache[name] = value
+        end
+      end
+
+      # Define a has_many relationship with GraphQL objects
+      # Queries multiple GraphQL objects using a where clause or connection
+      #
+      # @param name [Symbol] The association name (e.g., :variants)
+      # @param class_name [String] The target GraphQL model class name (defaults to name.to_s.classify.singularize)
+      # @param query_name [String] The GraphQL query field name (defaults to class_name.pluralize.camelize(:lower))
+      # @param foreign_key [Symbol, String] The attribute on GraphQL objects to filter by (e.g., :customer_id)
+      # @param primary_key [Symbol, String] The local attribute to use as filter value (defaults to :id)
+      # @param loader_class [Class] Custom loader class (defaults to target class's default_loader)
+      # @param query_method [Symbol] Method to use for querying (:where or :connection, defaults to :where)
+      #
+      # @example Basic usage with where query
+      #   has_many_graphql :variants, class: "ProductVariant"
+      #   reward.variants # Uses where to query
+      #
+      # @example With custom query_name for a connection
+      #   has_many_graphql :line_items, query_name: "lineItems", query_method: :connection
+      #   order.line_items(first: 10)
+      #
+      # @example With filtering by foreign key
+      #   has_many_graphql :orders, foreign_key: :customer_id
+      #   # Queries orders where customer_id matches the local record's id
+      def has_many_graphql(name, class_name: nil, query_name: nil, foreign_key: nil, primary_key: nil, loader_class: nil, query_method: :where)
+        association_class_name = class_name || name.to_s.singularize.classify
+        association_primary_key = primary_key || :id
+        association_loader_class = loader_class
+        association_query_method = query_method
+
+        # Auto-determine query_name if not provided
+        association_query_name = query_name || name.to_s.camelize(:lower)
+
+        # Store association metadata
+        graphql_associations[name] = {
+          type: :has_many,
+          class_name: association_class_name,
+          query_name: association_query_name,
+          foreign_key: foreign_key,
+          primary_key: association_primary_key,
+          loader_class: association_loader_class,
+          query_method: association_query_method
+        }
+
+        # Define the association method
+        define_method name do |**options|
+          return @_graphql_association_cache[name] if @_graphql_association_cache&.key?(name) && options.empty?
+
+          @_graphql_association_cache ||= {}
+
+          # Get primary key value
+          primary_key_value = send(association_primary_key)
+          return @_graphql_association_cache[name] = [] if primary_key_value.blank?
+
+          # Resolve the target class
+          target_class = association_class_name.constantize
+
+          # Determine which loader to use
+          loader = if self.class.graphql_associations[name][:loader_class]
+                     self.class.graphql_associations[name][:loader_class].new(target_class)
+                   else
+                     target_class.default_loader
+                   end
+
+          # Build query based on query_method
+          result = if association_query_method == :connection
+                     # For connections, we need to handle this differently
+                     # This would typically be a nested connection on a parent object
+                     # For now, return empty array - real implementation would need parent context
+                     []
+                   elsif self.class.graphql_associations[name][:foreign_key]
+                     # Query with foreign key filter
+                     foreign_key_sym = self.class.graphql_associations[name][:foreign_key]
+                     query_conditions = { foreign_key_sym => primary_key_value }.merge(options)
+                     target_class.where(query_conditions, loader: loader)
+                   else
+                     # No foreign key specified, just query with provided options
+                     target_class.where(options, loader: loader)
+                   end
+
+          # Cache if no runtime options provided
+          @_graphql_association_cache[name] = result if options.empty?
+          result
+        end
+
+        # Define setter method for testing/mocking
+        define_method "#{name}=" do |value|
+          @_graphql_association_cache ||= {}
+          @_graphql_association_cache[name] = value
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/includes_scope.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # A scope object that holds included connections for eager loading.
+  # This allows chaining methods like find() and where() while maintaining
+  # the included connections configuration.
+  class IncludesScope
+    attr_reader :model_class, :included_connections
+
+    def initialize(model_class, included_connections)
+      @model_class = model_class
+      @included_connections = included_connections
+    end
+
+    # Delegate find to the model class with a custom loader
+    def find(id, loader: nil)
+      loader ||= default_loader
+      @model_class.find(id, loader: loader)
+    end
+
+    # Delegate where to the model class with a custom loader
+    def where(*args, **options)
+      loader = options.delete(:loader) || default_loader
+      @model_class.where(*args, **options.merge(loader: loader))
+    end
+
+    # Delegate select to create a new scope with select
+    def select(*attributes)
+      selected_scope = @model_class.select(*attributes)
+      # Chain the includes on top of select
+      IncludesScope.new(selected_scope, @included_connections)
+    end
+
+    # Allow chaining includes calls
+    def includes(*connection_names)
+      @model_class.includes(*(@included_connections + connection_names).uniq)
+    end
+
+    private
+
+    def default_loader
+      @default_loader ||= @model_class.default_loader.class.new(
+        @model_class,
+        included_connections: @included_connections
+      )
+    end
+  end
+end

data/lib/active_shopify_graphql/loader.rb

@@ -84,7 +84,7 @@ module ActiveShopifyGraphQL
 
     # Delegate query building methods
     def query_name(model_type = nil)
-      (model_type || graphql_type).downcase
+      (model_type || graphql_type).camelize(:lower)
     end
 
     def fragment_name(model_type = nil)
@@ -96,19 +96,50 @@ module ActiveShopifyGraphQL
     end
 
     # Map the GraphQL response to model attributes
-    def map_response_to_attributes(response_data)
+    def map_response_to_attributes(response_data, parent_instance: nil)
       mapper = ResponseMapper.new(context)
       attributes = mapper.map_response(response_data)
 
       # If we have included connections, extract and cache them
       if @included_connections.any?
-        connection_data = mapper.extract_connection_data(response_data)
+        connection_data = mapper.extract_connection_data(response_data, parent_instance: parent_instance)
         attributes[:_connection_cache] = connection_data unless connection_data.empty?
       end
 
       attributes
     end
 
+    # Check if this loader has included connections
+    def has_included_connections?
+      @included_connections&.any?
+    end
+
+    # Load and construct an instance with proper inverse_of support for included connections
+    def load_with_instance(id, model_class)
+      query = graphql_query
+      response_data = perform_graphql_query(query, id: id)
+
+      return nil if response_data.nil?
+
+      # First, extract just the attributes (without connections)
+      mapper = ResponseMapper.new(context)
+      attributes = mapper.map_response(response_data)
+
+      # Create the instance with basic attributes
+      instance = model_class.new(attributes)
+
+      # Now extract connection data with the instance as parent to support inverse_of
+      if @included_connections.any?
+        connection_data = mapper.extract_connection_data(response_data, parent_instance: instance)
+        unless connection_data.empty?
+          # Manually set the connection cache on the instance
+          instance.instance_variable_set(:@_connection_cache, connection_data)
+        end
+      end
+
+      instance
+    end
+
     # Executes the GraphQL query and returns the mapped attributes hash
     def load_attributes(id)
       query = graphql_query

data/lib/active_shopify_graphql/loader_context.rb

@@ -38,7 +38,7 @@ module ActiveShopifyGraphQL
 
     # Helper methods delegated from context
     def query_name
-      graphql_type.downcase
+      graphql_type.camelize(:lower)
     end
 
     def fragment_name

data/lib/active_shopify_graphql/loaders/admin_api_loader.rb

@@ -4,7 +4,7 @@ module ActiveShopifyGraphQL
   module Loaders
     class AdminApiLoader < Loader
       def initialize(model_class = nil, selected_attributes: nil, included_connections: nil)
-        super(model_class, selected_attributes: selected_attributes, included_connections: included_connections)
+        super
       end
 
       def perform_graphql_query(query, **variables)

data/lib/active_shopify_graphql/query_node.rb

@@ -40,6 +40,8 @@ class QueryNode
       render_singular(indent_level: indent_level)
     when :fragment
       render_fragment
+    when :raw
+      render_raw
     else
       raise ArgumentError, "Unknown node type: #{@node_type}"
     end
@@ -83,11 +85,14 @@ class QueryNode
     nested_fields = @children.map { |child| child.to_s(indent_level: indent_level + 2) }
     fields_string = nested_fields.join(compact? ? " " : "\n#{nested_indent}  ")
 
+    # Include alias if present
+    field_name = @alias_name ? "#{@alias_name}: #{@name}" : @name
+
     if compact?
-      "#{@name}#{args_string} { edges { node { #{fields_string} } } }"
+      "#{field_name}#{args_string} { edges { node { #{fields_string} } } }"
     else
       <<~GRAPHQL.strip
-        #{@name}#{args_string} {
+        #{field_name}#{args_string} {
         #{nested_indent}edges {
         #{nested_indent}  node {
         #{nested_indent}    #{fields_string}
@@ -108,10 +113,13 @@ class QueryNode
     nested_fields = @children.map { |child| child.to_s(indent_level: indent_level + 1) }
     fields_string = nested_fields.join(compact? ? " " : "\n#{nested_indent}")
 
+    # Include alias if present
+    field_name = @alias_name ? "#{@alias_name}: #{@name}" : @name
+
     if compact?
-      "#{@name}#{args_string} { #{fields_string} }"
+      "#{field_name}#{args_string} { #{fields_string} }"
     else
-      "#{@name}#{args_string} {\n#{nested_indent}#{fields_string}\n#{indent}}"
+      "#{field_name}#{args_string} {\n#{nested_indent}#{fields_string}\n#{indent}}"
     end
   end
 
@@ -127,6 +135,11 @@ class QueryNode
     end
   end
 
+  def render_raw
+    # Raw GraphQL string stored in arguments[:raw_graphql]
+    @arguments[:raw_graphql]
+  end
+
   def format_arguments
     return "" if @arguments.empty?
 

data/lib/active_shopify_graphql/query_tree.rb

@@ -73,11 +73,6 @@ module ActiveShopifyGraphQL
       FragmentBuilder.normalize_includes(includes)
     end
 
-    # Helper methods (kept for backward compatibility)
-    def self.query_name(graphql_type)
-      graphql_type.downcase
-    end
-
     def self.fragment_name(graphql_type)
       "#{graphql_type}Fragment"
     end

data/lib/active_shopify_graphql/response_mapper.rb

@@ -35,18 +35,18 @@ module ActiveShopifyGraphQL
     end
 
     # Extract connection data from GraphQL response for eager loading
-    def extract_connection_data(response_data, root_path: nil)
+    def extract_connection_data(response_data, root_path: nil, parent_instance: nil)
       return {} if @context.included_connections.empty?
 
       root_path ||= ["data", @context.query_name]
       root_data = response_data.dig(*root_path)
       return {} unless root_data
 
-      extract_connections_from_node(root_data)
+      extract_connections_from_node(root_data, parent_instance)
     end
 
     # Extract connections from a node (reusable for nested connections)
-    def extract_connections_from_node(node_data)
+    def extract_connections_from_node(node_data, parent_instance = nil)
       return {} if @context.included_connections.empty?
 
       connections = @context.connections
@@ -59,7 +59,7 @@ module ActiveShopifyGraphQL
         connection_config = connections[connection_name]
         next unless connection_config
 
-        records = extract_connection_records(node_data, connection_config, nested_includes)
+        records = extract_connection_records(node_data, connection_config, nested_includes, parent_instance: parent_instance)
         connection_cache[connection_name] = records if records
       end
 
@@ -69,7 +69,7 @@ module ActiveShopifyGraphQL
     # Map nested connection response (when loading via parent query)
     def map_nested_connection_response(response_data, connection_field_name, parent, connection_config = nil)
       parent_type = parent.class.graphql_type_for_loader(@context.loader_class)
-      parent_query_name = parent_type.downcase
+      parent_query_name = parent_type.camelize(:lower)
       connection_type = connection_config&.dig(:type) || :connection
 
       if connection_type == :singular
@@ -111,8 +111,26 @@ module ActiveShopifyGraphQL
     private
 
     def extract_and_transform_value(node_data, config, attr_name)
-      path_parts = config[:path].split('.')
-      value = node_data.dig(*path_parts)
+      path = config[:path]
+
+      value = if config[:raw_graphql]
+                # For raw_graphql, the alias is the attr_name, then dig using path if nested
+                raw_data = node_data[attr_name.to_s]
+                if path.include?('.')
+                  # Path is relative to the aliased root
+                  path_parts = path.split('.')[1..] # Skip the first part (attr_name itself)
+                  path_parts.any? ? raw_data&.dig(*path_parts) : raw_data
+                else
+                  raw_data
+                end
+              elsif path.include?('.')
+                # Nested path - dig using the full path
+                path_parts = path.split('.')
+                node_data.dig(*path_parts)
+              else
+                # Simple path - use attr_name as key (matches the alias in the query)
+                node_data[attr_name.to_s]
+              end
 
       value = apply_defaults_and_transforms(value, config)
       validate_null_constraint!(value, config, attr_name)
@@ -153,23 +171,33 @@ module ActiveShopifyGraphQL
       end
     end
 
-    def extract_connection_records(node_data, connection_config, nested_includes)
-      query_name = connection_config[:query_name]
+    def extract_connection_records(node_data, connection_config, nested_includes, parent_instance: nil)
+      # Use original_name (Ruby attr name) as the response key since we alias connections
+      response_key = connection_config[:original_name].to_s
       connection_type = connection_config[:type] || :connection
       target_class = connection_config[:class_name].constantize
+      connection_name = connection_config[:original_name]
 
       if connection_type == :singular
-        item_data = node_data[query_name]
+        item_data = node_data[response_key]
         return nil unless item_data
 
-        build_nested_model_instance(item_data, target_class, nested_includes)
+        build_nested_model_instance(item_data, target_class, nested_includes,
+                                    parent_instance: parent_instance,
+                                    parent_connection_name: connection_name,
+                                    connection_config: connection_config)
       else
-        edges = node_data.dig(query_name, "edges")
+        edges = node_data.dig(response_key, "edges")
         return nil unless edges
 
         edges.filter_map do |edge|
           item_data = edge["node"]
-          build_nested_model_instance(item_data, target_class, nested_includes) if item_data
+          if item_data
+            build_nested_model_instance(item_data, target_class, nested_includes,
+                                        parent_instance: parent_instance,
+                                        parent_connection_name: connection_name,
+                                        connection_config: connection_config)
+          end
         end
       end
     end
@@ -181,16 +209,35 @@ module ActiveShopifyGraphQL
       @context.model_class.new(attributes)
     end
 
-    def build_nested_model_instance(node_data, target_class, nested_includes)
+    def build_nested_model_instance(node_data, target_class, nested_includes, parent_instance: nil, parent_connection_name: nil, connection_config: nil) # rubocop:disable Lint/UnusedMethodArgument
       nested_context = @context.for_model(target_class, new_connections: nested_includes)
       nested_mapper = ResponseMapper.new(nested_context)
 
       attributes = nested_mapper.map_node_to_attributes(node_data)
       instance = target_class.new(attributes)
 
-      # Handle nested connections recursively
+      # Populate inverse cache if inverse_of is specified
+      if parent_instance && connection_config && connection_config[:inverse_of]
+        inverse_name = connection_config[:inverse_of]
+        instance.instance_variable_set(:@_connection_cache, {}) unless instance.instance_variable_get(:@_connection_cache)
+        cache = instance.instance_variable_get(:@_connection_cache)
+
+        # Check the type of the inverse connection to determine how to cache
+        if target_class.respond_to?(:connections) && target_class.connections[inverse_name]
+          inverse_type = target_class.connections[inverse_name][:type]
+          cache[inverse_name] =
+            if inverse_type == :singular
+              parent_instance
+            else
+              # For collection inverses, wrap parent in an array
+              [parent_instance]
+            end
+        end
+      end
+
+      # Handle nested connections recursively (instance becomes parent for its children)
       if nested_includes.any?
-        nested_data = nested_mapper.extract_connections_from_node(node_data)
+        nested_data = nested_mapper.extract_connections_from_node(node_data, instance)
         nested_data.each do |nested_name, nested_records|
           instance.send("#{nested_name}=", nested_records)
         end