active_shopify_graphql 0.1.0

data/lib/active_shopify_graphql/fragment_builder.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Builds GraphQL fragments from model attributes and connections.
+  class FragmentBuilder
+    def initialize(context)
+      @context = context
+    end
+
+    # Build a complete fragment node with all fields and connections
+    def build
+      raise NotImplementedError, "#{@context.loader_class} must define attributes" if @context.defined_attributes.empty?
+
+      fragment_node = QueryNode.new(
+        name: @context.fragment_name,
+        arguments: { on: @context.graphql_type },
+        node_type: :fragment
+      )
+
+      # Add field nodes from attributes
+      build_field_nodes.each { |node| fragment_node.add_child(node) }
+
+      # Add connection nodes
+      build_connection_nodes.each { |node| fragment_node.add_child(node) }
+
+      fragment_node
+    end
+
+    # Build field nodes from attribute definitions (protected for recursive calls)
+    def build_field_nodes
+      path_tree = {}
+      metafield_aliases = {}
+
+      # Build a tree structure for nested paths
+      @context.defined_attributes.each_value do |config|
+        if config[:is_metafield]
+          store_metafield_config(metafield_aliases, config)
+        else
+          build_path_tree(path_tree, config[:path])
+        end
+      end
+
+      # Convert tree to QueryNode objects
+      nodes_from_tree(path_tree) + metafield_nodes(metafield_aliases)
+    end
+
+    # Build QueryNode objects for all connections (protected for recursive calls)
+    def build_connection_nodes
+      return [] if @context.included_connections.empty?
+
+      connections = @context.connections
+      return [] if connections.empty?
+
+      normalized_includes = normalize_includes(@context.included_connections)
+
+      normalized_includes.filter_map do |connection_name, nested_includes|
+        connection_config = connections[connection_name]
+        next unless connection_config
+
+        build_connection_node(connection_config, nested_includes)
+      end
+    end
+
+    private
+
+    def store_metafield_config(metafield_aliases, config)
+      alias_name = config[:metafield_alias]
+      value_field = config[:type] == :json ? 'jsonValue' : 'value'
+
+      metafield_aliases[alias_name] = {
+        namespace: config[:metafield_namespace],
+        key: config[:metafield_key],
+        value_field: value_field
+      }
+    end
+
+    def build_path_tree(path_tree, path)
+      path_parts = path.split('.')
+      current_level = path_tree
+
+      path_parts.each_with_index do |part, index|
+        if index == path_parts.length - 1
+          current_level[part] = true
+        else
+          current_level[part] ||= {}
+          current_level = current_level[part]
+        end
+      end
+    end
+
+    def nodes_from_tree(tree)
+      tree.map do |key, value|
+        if value == true
+          QueryNode.new(name: key, node_type: :field)
+        else
+          children = nodes_from_tree(value)
+          QueryNode.new(name: key, node_type: :field, children: children)
+        end
+      end
+    end
+
+    def metafield_nodes(metafield_aliases)
+      metafield_aliases.map do |alias_name, config|
+        value_node = QueryNode.new(name: config[:value_field], node_type: :field)
+        QueryNode.new(
+          name: "metafield",
+          alias_name: alias_name,
+          arguments: { namespace: config[:namespace], key: config[:key] },
+          node_type: :field,
+          children: [value_node]
+        )
+      end
+    end
+
+    def build_connection_node(connection_config, nested_includes)
+      target_class = connection_config[:class_name].constantize
+      target_context = @context.for_model(target_class, new_connections: nested_includes)
+
+      # Build child nodes for the target model
+      child_nodes = build_target_field_nodes(target_context, nested_includes)
+
+      query_name = connection_config[:query_name]
+      connection_type = connection_config[:type] || :connection
+      formatted_args = (connection_config[:default_arguments] || {}).transform_keys(&:to_sym)
+
+      node_type = connection_type == :singular ? :singular : :connection
+      QueryNode.new(
+        name: query_name,
+        arguments: formatted_args,
+        node_type: node_type,
+        children: child_nodes
+      )
+    end
+
+    def build_target_field_nodes(target_context, nested_includes)
+      # Build attribute nodes
+      attribute_nodes = if target_context.defined_attributes.any?
+                          FragmentBuilder.new(target_context.with_connections([])).build_field_nodes
+                        else
+                          [QueryNode.new(name: "id", node_type: :field)]
+                        end
+
+      # Build nested connection nodes
+      return attribute_nodes if nested_includes.empty?
+
+      nested_builder = FragmentBuilder.new(target_context)
+      nested_connection_nodes = nested_builder.build_connection_nodes
+      attribute_nodes + nested_connection_nodes
+    end
+
+    # Normalize includes from various formats to a consistent hash structure
+    def normalize_includes(includes)
+      includes = Array(includes)
+      includes.each_with_object({}) do |inc, normalized|
+        case inc
+        when Hash
+          inc.each do |key, value|
+            key = key.to_sym
+            normalized[key] ||= []
+            case value
+            when Hash then normalized[key] << value
+            when Array then normalized[key].concat(value)
+            else normalized[key] << value
+            end
+          end
+        when Symbol, String
+          normalized[inc.to_sym] ||= []
+        end
+      end
+    end
+
+    class << self
+      # Expose for external use (QueryTree needs this)
+      def normalize_includes(includes)
+        includes = Array(includes)
+        includes.each_with_object({}) do |inc, normalized|
+          case inc
+          when Hash
+            inc.each do |key, value|
+              key = key.to_sym
+              normalized[key] ||= []
+              case value
+              when Hash then normalized[key] << value
+              when Array then normalized[key].concat(value)
+              else normalized[key] << value
+              end
+            end
+          when Symbol, String
+            normalized[inc.to_sym] ||= []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/gid_helper.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Helper module for handling Shopify Global IDs (GIDs)
+  # Provides utilities for parsing and building GIDs according to the URI::GID standard
+  module GidHelper
+    # Normalize an ID value to a proper Shopify GID format
+    # If the ID is already a valid GID, returns it as-is
+    # Otherwise, builds a new GID using the provided model name
+    #
+    # @param id [String, Integer] The ID value (can be numeric or existing GID)
+    # @param model_name [String] The GraphQL type name (e.g., "Customer", "Order")
+    # @return [String] The normalized GID in format "gid://shopify/ModelName/id"
+    #
+    # @example
+    #   normalize_gid(123, "Customer")
+    #   # => "gid://shopify/Customer/123"
+    #
+    #   normalize_gid("gid://shopify/Customer/123", "Customer")
+    #   # => "gid://shopify/Customer/123"
+    #
+    def self.normalize_gid(id, model_name)
+      # Check if id is already a valid GID
+      begin
+        parsed_gid = URI::GID.parse(id)
+        return id if parsed_gid
+      rescue URI::InvalidURIError, URI::BadURIError, ArgumentError
+        # Not a valid GID, proceed to build one
+      end
+
+      # Build GID from the provided ID and model name
+      URI::GID.build(app: "shopify", model_name: model_name, model_id: id).to_s
+    end
+
+    # Check if a value is a valid Shopify GID
+    #
+    # @param value [String] The value to check
+    # @return [Boolean] true if the value is a valid GID, false otherwise
+    #
+    # @example
+    #   valid_gid?("gid://shopify/Customer/123")
+    #   # => true
+    #
+    #   valid_gid?("123")
+    #   # => false
+    #
+    def self.valid_gid?(value)
+      URI::GID.parse(value)
+      true
+    rescue URI::InvalidURIError, URI::BadURIError, ArgumentError
+      false
+    end
+  end
+end

data/lib/active_shopify_graphql/graphql_type_resolver.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Centralizes GraphQL type resolution logic.
+  module GraphqlTypeResolver
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Set or get the base GraphQL type for this model.
+      #
+      # @param type [String, nil] The GraphQL type name to set, or nil to get
+      # @return [String] The GraphQL type name
+      # @raise [NotImplementedError] If no type is defined
+      def graphql_type(type = nil)
+        if type
+          if @current_loader_context
+            @loader_graphql_types ||= {}
+            @loader_graphql_types[@current_loader_context] = type
+          else
+            @base_graphql_type = type
+          end
+        end
+
+        @base_graphql_type || raise(NotImplementedError, "#{self} must define graphql_type")
+      end
+
+      # Get the GraphQL type for a specific loader class.
+      # Resolution order:
+      #   1. Loader-specific type defined via `for_loader`
+      #   2. Base graphql_type defined on the model
+      #   3. Type defined on the loader class itself
+      #   4. Inferred from model class name
+      #
+      # @param loader_class [Class] The loader class to resolve type for
+      # @return [String] The resolved GraphQL type
+      # @raise [NotImplementedError] If no type can be resolved
+      def graphql_type_for_loader(loader_class)
+        # 1. Check loader-specific override
+        return @loader_graphql_types[loader_class] if @loader_graphql_types&.key?(loader_class)
+
+        # 2. Check base graphql_type
+        return @base_graphql_type if @base_graphql_type
+
+        # 3. Check loader class itself
+        loader_type = loader_class.instance_variable_get(:@graphql_type)
+        return loader_type if loader_type
+
+        # 4. Infer from model name
+        return name.demodulize if respond_to?(:name) && name
+
+        raise NotImplementedError,
+              "#{self} must define graphql_type or #{loader_class} must define graphql_type"
+      end
+
+      # Resolve the GraphQL type from any source (model class, loader, or value).
+      # Useful for external callers that need to resolve type from various inputs.
+      #
+      # @param model_class [Class, nil] The model class
+      # @param loader_class [Class, nil] The loader class
+      # @return [String] The resolved GraphQL type
+      def resolve_graphql_type(model_class: nil, loader_class: nil)
+        if model_class.respond_to?(:graphql_type_for_loader) && loader_class
+          model_class.graphql_type_for_loader(loader_class)
+        elsif model_class.respond_to?(:graphql_type)
+          model_class.graphql_type
+        elsif loader_class.respond_to?(:graphql_type)
+          loader_class.graphql_type
+        elsif model_class.respond_to?(:name) && model_class.name
+          model_class.name.demodulize
+        else
+          raise ArgumentError, "Cannot resolve graphql_type from provided arguments"
+        end
+      end
+    end
+
+    # Module-level resolver for convenience
+    def self.resolve(model_class: nil, loader_class: nil)
+      if model_class.respond_to?(:graphql_type_for_loader) && loader_class
+        model_class.graphql_type_for_loader(loader_class)
+      elsif model_class.respond_to?(:graphql_type)
+        model_class.graphql_type
+      elsif loader_class.respond_to?(:graphql_type)
+        loader_class.graphql_type
+      elsif model_class.respond_to?(:name) && model_class.name
+        model_class.name.demodulize
+      else
+        raise ArgumentError, "Cannot resolve graphql_type"
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/loader.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'active_model/type'
+require 'global_id'
+
+module ActiveShopifyGraphQL
+  # Base loader class that orchestrates GraphQL query execution and response mapping.
+  # Refactored to use LoaderContext for cleaner parameter management.
+  class Loader
+    class << self
+      # Set or get the GraphQL type for this loader
+      def graphql_type(type = nil)
+        return @graphql_type = type if type
+
+        # Try to get GraphQL type from associated model class first
+        return model_class.graphql_type_for_loader(self) if model_class
+
+        @graphql_type || raise(NotImplementedError, "#{self} must define graphql_type")
+      end
+
+      # Get the model class associated with this loader
+      def model_class
+        @model_class ||= infer_model_class
+      end
+
+      attr_writer :model_class
+
+      # Get attributes from the model class for this loader
+      def defined_attributes
+        return {} unless model_class
+
+        model_class.attributes_for_loader(self)
+      end
+
+      private
+
+      def infer_model_class
+        return nil unless @graphql_type
+
+        Object.const_get(@graphql_type)
+      rescue NameError
+        nil
+      end
+    end
+
+    # Initialize loader with optional model class and configuration
+    def initialize(model_class = nil, selected_attributes: nil, included_connections: nil, **)
+      @model_class = model_class || self.class.model_class
+      @selected_attributes = selected_attributes&.map(&:to_sym)
+      @included_connections = included_connections || []
+    end
+
+    # Build the LoaderContext for this loader instance
+    def context
+      @context ||= LoaderContext.new(
+        graphql_type: graphql_type,
+        loader_class: self.class,
+        defined_attributes: defined_attributes,
+        model_class: @model_class,
+        included_connections: @included_connections
+      )
+    end
+
+    # Get GraphQL type for this loader instance
+    def graphql_type
+      GraphqlTypeResolver.resolve(model_class: @model_class, loader_class: self.class)
+    end
+
+    # Get defined attributes for this loader instance
+    def defined_attributes
+      attrs = if @model_class
+                @model_class.attributes_for_loader(self.class)
+              else
+                self.class.defined_attributes
+              end
+
+      filter_selected_attributes(attrs)
+    end
+
+    # Returns the complete GraphQL fragment
+    def fragment
+      FragmentBuilder.new(context).build
+    end
+
+    # Delegate query building methods
+    def query_name(model_type = nil)
+      (model_type || graphql_type).downcase
+    end
+
+    def fragment_name(model_type = nil)
+      "#{model_type || graphql_type}Fragment"
+    end
+
+    def graphql_query(_model_type = nil)
+      QueryTree.build_single_record_query(context)
+    end
+
+    # Map the GraphQL response to model attributes
+    def map_response_to_attributes(response_data)
+      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)
+        attributes[:_connection_cache] = connection_data unless connection_data.empty?
+      end
+
+      attributes
+    end
+
+    # Executes the GraphQL query and returns the mapped attributes hash
+    def load_attributes(id)
+      query = graphql_query
+      response_data = perform_graphql_query(query, id: id)
+
+      return nil if response_data.nil?
+
+      map_response_to_attributes(response_data)
+    end
+
+    # Executes a collection query using Shopify's search syntax
+    def load_collection(conditions = {}, limit: 250)
+      search_query = SearchQuery.new(conditions)
+      collection_query_name = query_name.pluralize
+      variables = { query: search_query.to_s, first: limit }
+
+      query = QueryTree.build_collection_query(
+        context,
+        query_name: collection_query_name,
+        variables: variables,
+        connection_type: :nodes_only
+      )
+
+      response = perform_graphql_query(query, **variables)
+      validate_search_response(response)
+      map_collection_response(response, collection_query_name)
+    end
+
+    # Load records for a connection query
+    def load_connection_records(query_name, variables, parent = nil, connection_config = nil)
+      connection_loader = ConnectionLoader.new(context, loader_instance: self)
+      connection_loader.load_records(query_name, variables, parent, connection_config)
+    end
+
+    # Abstract method for executing GraphQL queries
+    def perform_graphql_query(query, **variables)
+      raise NotImplementedError, "#{self.class} must implement perform_graphql_query"
+    end
+
+    private
+
+    def filter_selected_attributes(attrs)
+      return attrs unless @selected_attributes
+
+      selected = {}
+      (@selected_attributes + [:id]).uniq.each do |attr|
+        selected[attr] = attrs[attr] if attrs.key?(attr)
+      end
+      selected
+    end
+
+    def validate_search_response(response)
+      return unless response.dig("extensions", "search")
+
+      warnings = response["extensions"]["search"].flat_map { |s| s["warnings"] || [] }
+      return if warnings.empty?
+
+      messages = warnings.map { |w| "#{w['field']}: #{w['message']}" }
+      raise ArgumentError, "Shopify query validation failed: #{messages.join(', ')}"
+    end
+
+    def map_collection_response(response_data, collection_query_name)
+      nodes = response_data.dig("data", collection_query_name, "nodes")
+      return [] unless nodes&.any?
+
+      nodes.filter_map do |node_data|
+        single_response = { "data" => { query_name => node_data } }
+        map_response_to_attributes(single_response)
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/loader_context.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Value object that encapsulates the shared context needed across query building,
+  # response mapping, and connection loading operations.
+  class LoaderContext
+    attr_reader :graphql_type, :loader_class, :defined_attributes, :model_class, :included_connections
+
+    def initialize(graphql_type:, loader_class:, defined_attributes:, model_class:, included_connections: [])
+      @graphql_type = graphql_type
+      @loader_class = loader_class
+      @defined_attributes = defined_attributes
+      @model_class = model_class
+      @included_connections = Array(included_connections)
+    end
+
+    # Create a new context with different included connections (for nested loading)
+    def with_connections(new_connections)
+      self.class.new(
+        graphql_type: graphql_type,
+        loader_class: loader_class,
+        defined_attributes: defined_attributes,
+        model_class: model_class,
+        included_connections: new_connections
+      )
+    end
+
+    # Create a new context for a different model (for connection targets)
+    def for_model(new_model_class, new_graphql_type: nil, new_attributes: nil, new_connections: [])
+      self.class.new(
+        graphql_type: new_graphql_type || infer_graphql_type(new_model_class),
+        loader_class: loader_class,
+        defined_attributes: new_attributes || infer_attributes(new_model_class),
+        model_class: new_model_class,
+        included_connections: new_connections
+      )
+    end
+
+    # Helper methods delegated from context
+    def query_name
+      graphql_type.downcase
+    end
+
+    def fragment_name
+      "#{graphql_type}Fragment"
+    end
+
+    def connections
+      return {} unless model_class
+
+      model_class.connections
+    end
+
+    def ==(other)
+      other.is_a?(LoaderContext) &&
+        graphql_type == other.graphql_type &&
+        loader_class == other.loader_class &&
+        defined_attributes == other.defined_attributes &&
+        model_class == other.model_class &&
+        included_connections == other.included_connections
+    end
+    alias eql? ==
+
+    def hash
+      [graphql_type, loader_class, defined_attributes, model_class, included_connections].hash
+    end
+
+    private
+
+    def infer_graphql_type(klass)
+      if klass.respond_to?(:graphql_type_for_loader)
+        klass.graphql_type_for_loader(loader_class)
+      elsif klass.respond_to?(:graphql_type)
+        klass.graphql_type
+      elsif klass.respond_to?(:name) && klass.name
+        klass.name.demodulize
+      else
+        raise ArgumentError, "Cannot infer graphql_type for #{klass}"
+      end
+    end
+
+    def infer_attributes(klass)
+      return klass.attributes_for_loader(loader_class) if klass.respond_to?(:attributes_for_loader)
+
+      {}
+    end
+  end
+end