active_shopify_graphql 0.4.0 → 0.5.0

data/lib/active_shopify_graphql/model_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Pure factory for building model instances from attribute hashes.
+  # Separates data mapping (Loader/ResponseMapper) from object construction.
+  #
+  # Responsibilities:
+  # - Build single model instances from attributes
+  # - Apply connection caches to instances
+  # - Handle batch building with connection caching
+  #
+  # @example Single instance
+  #   attributes = loader.load_attributes(gid)
+  #   customer = ModelBuilder.build(Customer, attributes)
+  #
+  # @example Batch building
+  #   attributes_list = loader.load_paginated_attributes(...)
+  #   customers = ModelBuilder.build_many(Customer, attributes_list)
+  class ModelBuilder
+    class << self
+      # Build a single model instance from attributes
+      # @param model_class [Class] The model class to instantiate
+      # @param attributes [Hash] Attribute hash (may contain :_connection_cache)
+      # @return [Object] The instantiated model with cached connections
+      def build(model_class, attributes)
+        return nil if attributes.nil?
+
+        instance = model_class.new(attributes)
+        apply_connection_cache(instance, attributes)
+        instance
+      end
+
+      # Build multiple model instances from an array of attribute hashes
+      # @param model_class [Class] The model class to instantiate
+      # @param attributes_array [Array<Hash>] Array of attribute hashes
+      # @return [Array<Object>] Array of instantiated models
+      def build_many(model_class, attributes_array)
+        return [] if attributes_array.nil? || attributes_array.empty?
+
+        attributes_array.filter_map { |attrs| build(model_class, attrs) }
+      end
+
+      # Apply connection cache from attributes to an already-instantiated model
+      # @param instance [Object] The model instance
+      # @param attributes [Hash] Attribute hash that may contain :_connection_cache
+      def apply_connection_cache(instance, attributes)
+        return unless attributes.is_a?(Hash) && attributes.key?(:_connection_cache)
+
+        instance.instance_variable_set(:@_connection_cache, attributes[:_connection_cache])
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/collection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders a collection query with optional pagination.
+      # Example without pagination:
+      #   query getCustomers {
+      #     customers(first: 10) {
+      #       nodes {
+      #         ...CustomerFragment
+      #       }
+      #     }
+      #   }
+      #
+      # Example with pagination:
+      #   query getCustomers {
+      #     customers(first: 10, after: "cursor") {
+      #       pageInfo {
+      #         hasNextPage
+      #         hasPreviousPage
+      #         startCursor
+      #         endCursor
+      #       }
+      #       nodes {
+      #         ...CustomerFragment
+      #       }
+      #     }
+      #   }
+      class Collection < Node
+        attr_reader :model_type, :query_name, :fragment_name, :variables, :fragments, :include_page_info
+
+        def initialize(model_type:, query_name:, fragment_name:, variables: {}, fragments: [], include_page_info: false)
+          @model_type = model_type
+          @query_name = query_name
+          @fragment_name = fragment_name
+          @variables = variables
+          @fragments = fragments
+          @include_page_info = include_page_info
+          super(name: query_name)
+        end
+
+        def to_s
+          parts = [fragments_string, "query get#{model_type.pluralize} { #{query_name}#{field_signature} {"]
+          parts << PAGE_INFO_FIELDS if @include_page_info
+          parts << "nodes { ...#{fragment_name} }"
+          parts << "} }"
+          parts.join(' ')
+        end
+
+        private
+
+        def fragments_string
+          @fragments.map(&:to_s).join(' ')
+        end
+
+        def field_signature
+          params = build_field_parameters(@variables.compact)
+          params.empty? ? "" : "(#{params.join(', ')})"
+        end
+
+        def build_field_parameters(variables)
+          variables.map do |key, value|
+            "#{key.to_s.camelize(:lower)}: #{format_inline_value(key, value)}"
+          end
+        end
+
+        def format_inline_value(key, value)
+          case value
+          when Integer, TrueClass, FalseClass then value.to_s
+          when String then STRING_KEYS_NEEDING_QUOTES.include?(key.to_sym) ? "\"#{value}\"" : value
+          else value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/connection.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders connection fields using the nodes pattern.
+      # Example: `orders(first: 10) { nodes { id createdAt } }`
+      class Connection < Node
+        def to_s
+          nested_fields = render_children
+          "#{field_name_with_alias}#{format_arguments} { nodes { #{nested_fields.join(' ')} } }"
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/current_customer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders a query that doesn't require an ID parameter.
+      # Used for Customer Account API's current customer query.
+      # Example:
+      #   query getCurrentCustomer {
+      #     customer {
+      #       ...CustomerFragment
+      #     }
+      #   }
+      class CurrentCustomer < Node
+        attr_reader :model_type, :query_name, :fragment_name, :fragments
+
+        def initialize(model_type:, query_name:, fragment_name:, fragments: [])
+          @model_type = model_type
+          @query_name = query_name
+          @fragment_name = fragment_name
+          @fragments = fragments
+          super(name: query_name)
+        end
+
+        def to_s
+          "#{fragments_string} query getCurrent#{model_type} { #{query_name} { ...#{fragment_name} } }"
+        end
+
+        private
+
+        def fragments_string
+          @fragments.map(&:to_s).join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/field.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders simple fields and nested fields with children.
+      # Examples:
+      #   - Simple: `id`
+      #   - With alias: `customerId: id`
+      #   - Nested: `defaultAddress { city country }`
+      class Field < Node
+        def to_s
+          full_name = "#{field_name_with_alias}#{format_arguments}"
+
+          return full_name unless has_children?
+
+          nested_fields = render_children
+          "#{full_name} { #{nested_fields.join(' ')} }"
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/fragment.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders GraphQL fragment definitions.
+      # Example: `fragment CustomerFragment on Customer { id displayName email }`
+      class Fragment < Node
+        def to_s
+          type_name = @arguments[:on]
+          fields = render_children
+          "fragment #{@name} on #{type_name} { #{fields.join(' ')} }"
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/nested_connection.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders a nested connection query (loaded from a parent record).
+      # Example:
+      #   query($id: ID!) {
+      #     customer(id: $id) {
+      #       orders(first: 10) {
+      #         pageInfo {
+      #           hasNextPage
+      #           hasPreviousPage
+      #           startCursor
+      #           endCursor
+      #         }
+      #         nodes {
+      #           ...OrderFragment
+      #         }
+      #       }
+      #     }
+      #   }
+      class NestedConnection < Node
+        attr_reader :query_name, :fragment_name, :variables, :parent_query, :fragments, :singular
+
+        def initialize(query_name:, fragment_name:, parent_query:, variables: {}, fragments: [], singular: false)
+          @query_name = query_name
+          @fragment_name = fragment_name
+          @variables = variables
+          @parent_query = parent_query
+          @fragments = fragments
+          @singular = singular
+          super(name: query_name)
+        end
+
+        def to_s(*)
+          if @singular
+            render_singular_connection
+          else
+            render_nodes_connection
+          end
+        end
+
+        private
+
+        def render_singular_connection
+          "#{fragments_string} query($id: ID!) { #{parent_query} { #{query_name}#{field_signature} { ...#{fragment_name} } } }"
+        end
+
+        def render_nodes_connection
+          "#{fragments_string} query($id: ID!) { #{parent_query} { #{query_name}#{field_signature} { #{PAGE_INFO_FIELDS} nodes { ...#{fragment_name} } } } }"
+        end
+
+        def fragments_string
+          @fragments.map(&:to_s).join(' ')
+        end
+
+        def field_signature
+          params = build_field_parameters(@variables.compact)
+          params.empty? ? "" : "(#{params.join(', ')})"
+        end
+
+        def build_field_parameters(variables)
+          variables.map do |key, value|
+            "#{key.to_s.camelize(:lower)}: #{format_inline_value(key, value)}"
+          end
+        end
+
+        def format_inline_value(key, value)
+          case value
+          when Integer, TrueClass, FalseClass then value.to_s
+          when String then STRING_KEYS_NEEDING_QUOTES.include?(key.to_sym) ? "\"#{value}\"" : value
+          else value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/raw.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders raw GraphQL strings verbatim.
+      # Used for custom GraphQL snippets that don't fit other node types.
+      class Raw < Node
+        def to_s(*)
+          @arguments[:raw_graphql]
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/root_connection.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders a root-level connection query (no parent record).
+      # Example:
+      #   query {
+      #     customers(first: 10) {
+      #       pageInfo {
+      #         hasNextPage
+      #         hasPreviousPage
+      #         startCursor
+      #         endCursor
+      #       }
+      #       nodes {
+      #         ...CustomerFragment
+      #       }
+      #     }
+      #   }
+      class RootConnection < Node
+        attr_reader :query_name, :fragment_name, :variables, :fragments, :singular
+
+        def initialize(query_name:, fragment_name:, variables: {}, fragments: [], singular: false)
+          @query_name = query_name
+          @fragment_name = fragment_name
+          @variables = variables
+          @fragments = fragments
+          @singular = singular
+          super(name: query_name)
+        end
+
+        def to_s(*)
+          if @singular
+            render_singular_connection
+          else
+            render_nodes_connection
+          end
+        end
+
+        private
+
+        def render_singular_connection
+          "#{fragments_string} query { #{query_name}#{field_signature} { ...#{fragment_name} } }"
+        end
+
+        def render_nodes_connection
+          "#{fragments_string} query { #{query_name}#{field_signature} { #{PAGE_INFO_FIELDS} nodes { ...#{fragment_name} } } }"
+        end
+
+        def fragments_string
+          @fragments.map(&:to_s).join(' ')
+        end
+
+        def field_signature
+          params = build_field_parameters(@variables.compact)
+          params.empty? ? "" : "(#{params.join(', ')})"
+        end
+
+        def build_field_parameters(variables)
+          variables.map do |key, value|
+            "#{key.to_s.camelize(:lower)}: #{format_inline_value(key, value)}"
+          end
+        end
+
+        def format_inline_value(key, value)
+          case value
+          when Integer, TrueClass, FalseClass then value.to_s
+          when String then STRING_KEYS_NEEDING_QUOTES.include?(key.to_sym) ? "\"#{value}\"" : value
+          else value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/single_record.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders a single record query by ID.
+      # Example:
+      #   query getCustomer($id: ID!) {
+      #     customer(id: $id) {
+      #       ...CustomerFragment
+      #     }
+      #   }
+      class SingleRecord < Node
+        attr_reader :model_type, :query_name, :fragment_name, :fragments
+
+        def initialize(model_type:, query_name:, fragment_name:, fragments: [])
+          @model_type = model_type
+          @query_name = query_name
+          @fragment_name = fragment_name
+          @fragments = fragments
+          super(name: query_name)
+        end
+
+        def to_s
+          "#{fragments_string} query get#{model_type}($id: ID!) { #{query_name}(id: $id) { ...#{fragment_name} } }"
+        end
+
+        private
+
+        def fragments_string
+          @fragments.map(&:to_s).join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node/singular.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    class Node
+      # Renders singular association fields (has_one relationships).
+      # Example: `defaultAddress { city country zip }`
+      class Singular < Node
+        def to_s
+          nested_fields = render_children
+          "#{field_name_with_alias}#{format_arguments} { #{nested_fields.join(' ')} }"
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/node.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    # Abstract base class for all GraphQL query nodes.
+    # Provides shared attributes and helper methods for node rendering.
+    #
+    # Subclasses:
+    #   - Node::Field - Simple and nested fields
+    #   - Node::Singular - Singular associations (has_one)
+    #   - Node::Connection - Collection associations using nodes pattern
+    #   - Node::Fragment - Fragment definitions
+    #   - Node::Raw - Raw GraphQL strings
+    #   - Node::SingleRecord - Single record queries by ID
+    #   - Node::CurrentCustomer - ID-less queries (Customer Account API)
+    #   - Node::Collection - Collection queries with optional pagination
+    #   - Node::NestedConnection - Nested connection queries
+    #   - Node::RootConnection - Root-level connection queries
+    class Node
+      # Shared constants for query formatting
+      PAGE_INFO_FIELDS = "pageInfo { hasNextPage hasPreviousPage startCursor endCursor }"
+      STRING_KEYS_NEEDING_QUOTES = %i[query after before].freeze
+      attr_reader :name, :alias_name, :arguments, :children
+
+      # @param name [String] The field name (e.g., 'id', 'displayName', 'orders')
+      # @param alias_name [String] Optional field alias (e.g., 'myAlias' for 'myAlias: fieldName')
+      # @param arguments [Hash] Field arguments (e.g., { first: 10, sortKey: 'CREATED_AT' })
+      # @param children [Array<Query::Node>] Child nodes for nested structures
+      def initialize(name:, alias_name: nil, arguments: {}, children: [])
+        @name = name
+        @alias_name = alias_name
+        @arguments = arguments
+        @children = children
+      end
+
+      # Add a child node
+      def add_child(node)
+        @children << node
+        node
+      end
+
+      # Check if node has children
+      def has_children?
+        @children.any?
+      end
+
+      # Convert node to GraphQL string - must be implemented by subclasses
+      def to_s
+        raise NotImplementedError, "#{self.class} must implement #to_s"
+      end
+
+      private
+
+      def field_name_with_alias
+        @alias_name ? "#{@alias_name}: #{@name}" : @name
+      end
+
+      def format_arguments
+        return "" if @arguments.empty?
+
+        # Filter out internal arguments (like :on for fragments)
+        graphql_args = @arguments.except(:on)
+        return "" if graphql_args.empty?
+
+        args = graphql_args.map do |key, value|
+          graphql_key = key.to_s.camelize(:lower)
+          formatted_value = format_argument_value(key, value)
+          "#{graphql_key}: #{formatted_value}"
+        end
+
+        "(#{args.join(', ')})"
+      end
+
+      def format_argument_value(key, value)
+        case value
+        when String
+          # Keys that need quoted string values
+          if %i[namespace key query].include?(key.to_sym)
+            "\"#{value}\""
+          else
+            value
+          end
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+
+      def render_children
+        @children.map(&:to_s)
+      end
+    end
+  end
+end