active_shopify_graphql 0.4.0 → 0.5.0

data/lib/active_shopify_graphql/loader.rb

@@ -4,48 +4,31 @@ 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.
+  # The Loader acts as a stateless orchestrator that:
+  # - Receives a model class and delegates to it for GraphQL type and attribute definitions
+  # - Builds a LoaderContext that encapsulates all query-building parameters
+  # - Delegates query construction to Query::QueryBuilder
+  # - Delegates response mapping to Response::ResponseMapper
+  # - Executes GraphQL queries via subclass-specific implementations (perform_graphql_query)
+  #
+  # == Subclass Requirements
+  #
+  # Subclasses must implement:
+  # - +perform_graphql_query(query, **variables)+ - Execute the query against the appropriate API
+  #
+  # == Usage
+  #
+  #   loader = AdminApiLoader.new(Customer, selected_attributes: [:id, :email])
+  #   attributes = loader.load_attributes("gid://shopify/Customer/123")
+  #   customer = Customer.new(attributes)
+  #
+  # @see LoaderContext For query-building context management
+  # @see Query::QueryBuilder For GraphQL query construction
+  # @see Response::ResponseMapper For response-to-attribute mapping
   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
+    # Initialize loader with model class and configuration
+    def initialize(model_class, selected_attributes: nil, included_connections: nil, **)
+      @model_class = model_class
       @selected_attributes = selected_attributes&.map(&:to_sym)
       @included_connections = included_connections || []
     end
@@ -53,7 +36,7 @@ module ActiveShopifyGraphQL
     # Build the LoaderContext for this loader instance
     def context
       @context ||= LoaderContext.new(
-        graphql_type: graphql_type,
+        graphql_type: resolve_graphql_type,
         loader_class: self.class,
         defined_attributes: defined_attributes,
         model_class: @model_class,
@@ -61,51 +44,23 @@ module ActiveShopifyGraphQL
       )
     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)
+      filter_selected_attributes(@model_class.attributes_for_loader(self.class))
     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).camelize(:lower)
-    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)
+    # Returns the arguments needed to initialize a new loader of the same type
+    # Subclasses should override this if they require additional initialization arguments
+    # @return [Array] Array of arguments to pass to the loader initializer
+    def initialization_args
+      []
     end
 
     # Map the GraphQL response to model attributes
     def map_response_to_attributes(response_data, parent_instance: nil)
-      mapper = ResponseMapper.new(context)
+      mapper = create_response_mapper
       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, parent_instance: parent_instance)
-        attributes[:_connection_cache] = connection_data unless connection_data.empty?
-      end
-
+      cache_connections(mapper, response_data, target: attributes, parent_instance: parent_instance)
       attributes
     end
 
@@ -114,63 +69,47 @@ module ActiveShopifyGraphQL
       @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
+    # @param id [String] The GID of the record to load
+    # @return [Hash, nil] Attribute hash with connection cache, or nil if not found
     def load_attributes(id)
-      query = graphql_query
-      response_data = perform_graphql_query(query, id: id)
-
+      query = Query::QueryBuilder.build_single_record_query(context)
+      response_data = execute_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 }
+    # Executes a paginated collection query that returns attributes and page info
+    # Executes a paginated collection query that returns attributes and page info
+    # @param conditions [Hash] Search conditions
+    # @param per_page [Integer] Number of records per page
+    # @param after [String, nil] Cursor to fetch records after
+    # @param before [String, nil] Cursor to fetch records before
+    # @param query_scope [Query::Scope] The query scope for navigation
+    # @return [PaginatedResult] A paginated result with attribute hashes and page info
+    def load_paginated_collection(conditions:, per_page:, query_scope:, after: nil, before: nil)
+      collection_query_name = context.query_name.pluralize
+      variables = build_collection_variables(
+        conditions,
+        per_page: per_page,
+        after: after,
+        before: before
+      )
 
-      query = QueryTree.build_collection_query(
+      query = Query::QueryBuilder.build_paginated_collection_query(
         context,
         query_name: collection_query_name,
-        variables: variables,
-        connection_type: :nodes_only
+        variables: variables
       )
 
-      response = perform_graphql_query(query, **variables)
-      validate_search_response(response)
-      map_collection_response(response, collection_query_name)
+      response = execute_query_and_validate_search_response(query, **variables)
+      map_paginated_response(response, collection_query_name, query_scope)
     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 = Connections::ConnectionLoader.new(context, loader_instance: self)
       connection_loader.load_records(query_name, variables, parent, connection_config)
     end
 
@@ -181,6 +120,41 @@ module ActiveShopifyGraphQL
 
     private
 
+    def create_response_mapper
+      Response::ResponseMapper.new(context)
+    end
+
+    def should_log?
+      ActiveShopifyGraphQL.configuration.log_queries && ActiveShopifyGraphQL.configuration.logger
+    end
+
+    def log_query(api_name, query, variables)
+      return unless should_log?
+
+      ActiveShopifyGraphQL.configuration.logger.info("ActiveShopifyGraphQL Query (#{api_name}):\n#{query}")
+      ActiveShopifyGraphQL.configuration.logger.info("ActiveShopifyGraphQL Variables:\n#{variables}")
+    end
+
+    def cache_connections(mapper, response_data, target:, parent_instance: nil)
+      return unless @included_connections.any?
+
+      connection_data = mapper.extract_connection_data(response_data, parent_instance: parent_instance)
+      return if connection_data.empty?
+
+      case target
+      when Hash
+        target[:_connection_cache] = connection_data
+      else
+        target.instance_variable_set(:@_connection_cache, connection_data)
+      end
+    end
+
+    def resolve_graphql_type
+      raise ArgumentError, "#{self.class} requires a model_class" unless @model_class
+
+      @model_class.graphql_type_for_loader(self.class)
+    end
+
     def filter_selected_attributes(attrs)
       return attrs unless @selected_attributes
 
@@ -191,7 +165,7 @@ module ActiveShopifyGraphQL
       selected
     end
 
-    def validate_search_response(response)
+    def validate_search_query_response(response)
       return unless response.dig("extensions", "search")
 
       warnings = response["extensions"]["search"].flat_map { |s| s["warnings"] || [] }
@@ -201,14 +175,61 @@ module ActiveShopifyGraphQL
       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?
+    def execute_query(query, **variables)
+      perform_graphql_query(query, **variables)
+    end
+
+    def execute_query_and_validate_search_response(query, **variables)
+      response = execute_query(query, **variables)
+      validate_search_query_response(response)
+      response
+    end
 
-      nodes.filter_map do |node_data|
-        single_response = { "data" => { query_name => node_data } }
-        map_response_to_attributes(single_response)
+    def build_collection_variables(conditions, per_page:, after: nil, before: nil)
+      search_query = SearchQuery.new(conditions)
+      variables = { query: search_query.to_s }
+
+      if before
+        variables[:last] = per_page
+        variables[:before] = before
+      else
+        variables[:first] = per_page
+        variables[:after] = after if after
       end
+
+      variables.compact
+    end
+
+    def map_node_to_attributes(node_data)
+      single_response = { "data" => { context.query_name => node_data } }
+      map_response_to_attributes(single_response)
+    end
+
+    def map_paginated_response(response_data, collection_query_name, query_scope)
+      connection_data = response_data.dig("data", collection_query_name)
+      return empty_paginated_result(query_scope) unless connection_data
+
+      page_info_data = connection_data["pageInfo"] || {}
+      page_info = Response::PageInfo.new(page_info_data)
+
+      nodes = connection_data["nodes"] || []
+      attributes_array = nodes.filter_map { |node_data| map_node_to_attributes(node_data) }
+
+      Response::PaginatedResult.new(
+        attributes: attributes_array,
+        model_class: @model_class,
+        page_info: page_info,
+        query_scope: query_scope
+      )
+    end
+
+    def empty_paginated_result(query_scope)
+      Response::PaginatedResult.new(
+        attributes: [],
+        model_class: @model_class,
+        page_info: Response::PageInfo.new,
+        query_scope: query_scope
+      )
     end
   end
 end

data/lib/active_shopify_graphql/loader_context.rb

@@ -14,23 +14,12 @@ module ActiveShopifyGraphQL
       @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),
+        graphql_type: new_graphql_type || new_model_class.graphql_type_for_loader(loader_class),
         loader_class: loader_class,
-        defined_attributes: new_attributes || infer_attributes(new_model_class),
+        defined_attributes: new_attributes || new_model_class.attributes_for_loader(loader_class),
         model_class: new_model_class,
         included_connections: new_connections
       )
@@ -50,39 +39,5 @@ module ActiveShopifyGraphQL
 
       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

data/lib/active_shopify_graphql/loader_proxy.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Simple proxy class to handle loader delegation when using a specific API
+  # This provides a consistent interface with Relation while using a custom loader
+  class LoaderProxy
+    def initialize(model_class, loader)
+      @model_class = model_class
+      @loader = loader
+    end
+
+    # Create a Relation with this loader's configuration
+    # @return [Relation] A relation configured with this loader
+    def all
+      build_relation
+    end
+
+    # Delegate chainable methods to Relation
+    def includes(*connection_names)
+      build_relation.includes(*connection_names)
+    end
+
+    def select(*attribute_names)
+      build_relation.select(*attribute_names)
+    end
+
+    def where(*args, **options)
+      build_relation.where(*args, **options)
+    end
+
+    def find_by(conditions = {}, **options)
+      build_relation.find_by(conditions, **options)
+    end
+
+    def find(id = nil)
+      # For Customer Account API, if no ID is provided, load the current customer
+      if id.nil? && @loader.is_a?(ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader)
+        attributes = @loader.load_attributes
+        return nil if attributes.nil?
+
+        return @model_class.new(attributes)
+      end
+
+      # For other cases, require ID and use standard flow
+      return nil if id.nil?
+
+      build_relation.find(id)
+    end
+
+    attr_reader :loader
+
+    def inspect
+      "#{@model_class.name}(with_#{@loader.class.name.demodulize})"
+    end
+    alias to_s inspect
+
+    private
+
+    def build_relation
+      Query::Relation.new(
+        @model_class,
+        loader_class: @loader.class,
+        loader_extra_args: @loader.initialization_args
+      )
+    end
+  end
+end

data/lib/active_shopify_graphql/loaders/admin_api_loader.rb

@@ -3,30 +3,14 @@
 module ActiveShopifyGraphQL
   module Loaders
     class AdminApiLoader < Loader
-      def initialize(model_class = nil, selected_attributes: nil, included_connections: nil)
-        super
-      end
-
       def perform_graphql_query(query, **variables)
-        log_query(query, variables) if should_log?
+        log_query("Admin API", query, variables)
 
         client = ActiveShopifyGraphQL.configuration.admin_api_client
         raise Error, "Admin API client not configured. Please configure it using ActiveShopifyGraphQL.configure" unless client
 
         client.execute(query, **variables)
       end
-
-      private
-
-      def should_log?
-        ActiveShopifyGraphQL.configuration.log_queries && ActiveShopifyGraphQL.configuration.logger
-      end
-
-      def log_query(query, variables)
-        logger = ActiveShopifyGraphQL.configuration.logger
-        logger.info("ActiveShopifyGraphQL Query (Admin API):\n#{query}")
-        logger.info("ActiveShopifyGraphQL Variables:\n#{variables}")
-      end
     end
   end
 end

data/lib/active_shopify_graphql/loaders/customer_account_api_loader.rb

@@ -8,23 +8,15 @@ module ActiveShopifyGraphQL
         @token = token
       end
 
-      # Override to handle Customer queries that don't need an ID
-      def graphql_query(model_type = nil)
-        type = model_type || graphql_type
-        if type == 'Customer'
-          QueryTree.build_current_customer_query(context)
-        else
-          super(type)
-        end
-      end
-
       # Override load_attributes to handle the Customer case
       def load_attributes(id = nil)
-        type = graphql_type
-        query = graphql_query(type)
-
-        variables = type == 'Customer' ? {} : { id: id }
-        response_data = perform_graphql_query(query, **variables)
+        query = if context.graphql_type == 'Customer'
+                  Query::QueryBuilder.build_current_customer_query(context)
+                else
+                  Query::QueryBuilder.build_single_record_query(context)
+                end
+        variables = context.graphql_type == 'Customer' ? {} : { id: id }
+        response_data = execute_query(query, **variables)
 
         return nil if response_data.nil?
 
@@ -39,20 +31,12 @@ module ActiveShopifyGraphQL
       end
 
       def perform_graphql_query(query, **variables)
-        log_query(query, variables) if should_log?
+        log_query("Customer Account API", query, variables)
         client.query(query, variables)
       end
 
-      private
-
-      def should_log?
-        ActiveShopifyGraphQL.configuration.log_queries && ActiveShopifyGraphQL.configuration.logger
-      end
-
-      def log_query(query, variables)
-        logger = ActiveShopifyGraphQL.configuration.logger
-        logger.info("ActiveShopifyGraphQL Query (Customer Account API):\n#{query}")
-        logger.info("ActiveShopifyGraphQL Variables:\n#{variables}")
+      def initialization_args
+        [@token]
       end
     end
   end

data/lib/active_shopify_graphql/model/associations.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::Associations
+  # Handles associations between ActiveShopifyGraphQL objects and ActiveRecord objects
+  extend ActiveSupport::Concern
+
+  included do
+    class << self
+      def associations
+        @associations ||= {}
+      end
+
+      attr_writer :associations
+    end
+  end
+
+  class_methods do
+    def has_many(name, class_name: nil, foreign_key: nil, primary_key: nil)
+      association_class_name = class_name || name.to_s.classify
+      association_foreign_key = foreign_key || "shopify_#{model_name.element.downcase}_id"
+      association_primary_key = primary_key || :id
+
+      # Store association metadata
+      associations[name] = {
+        type: :has_many,
+        class_name: association_class_name,
+        foreign_key: association_foreign_key,
+        primary_key: association_primary_key
+      }
+
+      # Define the association method
+      define_method name do
+        return @_association_cache[name] if @_association_cache&.key?(name)
+
+        @_association_cache ||= {}
+
+        primary_key_value = send(association_primary_key)
+        return @_association_cache[name] = [] if primary_key_value.blank?
+
+        association_class = association_class_name.constantize
+        @_association_cache[name] = association_class.where(association_foreign_key => primary_key_value)
+      end
+
+      # Define the association setter method for testing/mocking
+      define_method "#{name}=" do |value|
+        @_association_cache ||= {}
+        @_association_cache[name] = value
+      end
+    end
+
+    def has_one(name, class_name: nil, foreign_key: nil, primary_key: nil)
+      association_class_name = class_name || name.to_s.classify
+      association_foreign_key = foreign_key || "shopify_#{model_name.element.downcase}_id"
+      association_primary_key = primary_key || :id
+
+      # Store association metadata
+      associations[name] = {
+        type: :has_one,
+        class_name: association_class_name,
+        foreign_key: association_foreign_key,
+        primary_key: association_primary_key
+      }
+
+      # Define the association method
+      define_method name do
+        return @_association_cache[name] if @_association_cache&.key?(name)
+
+        @_association_cache ||= {}
+
+        primary_key_value = send(association_primary_key)
+        return @_association_cache[name] = nil if primary_key_value.blank?
+
+        # Extract numeric ID from Shopify GID if needed
+        if primary_key_value.is_a?(String)
+          begin
+            parsed_gid = URI::GID.parse(primary_key_value)
+            primary_key_value = parsed_gid.model_id
+          rescue URI::InvalidURIError, URI::BadURIError, ArgumentError
+            # Not a GID, use value as-is
+          end
+        end
+
+        association_class = association_class_name.constantize
+        @_association_cache[name] = association_class.find_by(association_foreign_key => primary_key_value)
+      end
+
+      # Define the association setter method for testing/mocking
+      define_method "#{name}=" do |value|
+        @_association_cache ||= {}
+        @_association_cache[name] = value
+      end
+    end
+  end
+end