active_shopify_graphql 0.3.0 → 0.5.0

data/lib/active_shopify_graphql/model/graphql_type_resolver.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::GraphqlTypeResolver
+  # Centralizes GraphQL type resolution logic.
+  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

data/lib/active_shopify_graphql/model/loader_switchable.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::LoaderSwitchable
+  # Provides capability to switch between different loaders within the same model
+  extend ActiveSupport::Concern
+
+  # Generic method to execute with a specific loader
+  # @param loader_class [Class] The loader class to use
+  # @yield [Object] Block to execute with the loader
+  # @return [Object] Result of the block
+  def with_loader(loader_class, &_block)
+    old_loader = Thread.current[:active_shopify_graphql_loader]
+    Thread.current[:active_shopify_graphql_loader] = loader_class.new(self.class)
+
+    if block_given?
+      yield(self)
+    else
+      self
+    end
+  ensure
+    Thread.current[:active_shopify_graphql_loader] = old_loader
+  end
+
+  # Executes with the admin API loader
+  # @return [self]
+  def with_admin_api(&block)
+    with_loader(ActiveShopifyGraphQL::Loaders::AdminApiLoader, &block)
+  end
+
+  # Executes with the customer account API loader
+  # @return [self]
+  def with_customer_account_api(&block)
+    with_loader(ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader, &block)
+  end
+
+  class_methods do
+    # @!method use_loader(loader_class)
+    #   Sets the default loader class for this model.
+    #
+    #   @param loader_class [Class] The loader class to use as default
+    #   @example
+    #     class Customer < ActiveRecord::Base
+    #       use_loader ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader
+    #     end
+    def use_loader(loader_class)
+      @default_loader_class = loader_class
+    end
+
+    # Define loader-specific attribute and graphql_type overrides
+    # @param loader_class [Class] The loader class to override attributes for
+    def for_loader(loader_class, &block)
+      @current_loader_context = loader_class
+      @loader_contexts ||= {}
+      @loader_contexts[loader_class] ||= {}
+      instance_eval(&block) if block_given?
+      @current_loader_context = nil
+    end
+
+    # Class-level method to execute with admin API loader
+    # @return [LoaderProxy] Proxy object with find method
+    def with_admin_api
+      ActiveShopifyGraphQL::LoaderProxy.new(self, ActiveShopifyGraphQL::Loaders::AdminApiLoader.new(self))
+    end
+
+    # Class-level method to execute with customer account API loader
+    # @return [LoaderProxy] Proxy object with find method
+    def with_customer_account_api(token = nil)
+      ActiveShopifyGraphQL::LoaderProxy.new(self, ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader.new(self, token))
+    end
+
+    private
+
+    # Returns the default loader class (either set via DSL or inferred)
+    # @return [Class] The default loader class
+    def default_loader_class
+      @default_loader_class ||= ActiveShopifyGraphQL::Loaders::AdminApiLoader
+    end
+  end
+end

data/lib/active_shopify_graphql/model/metafield_attributes.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::MetafieldAttributes
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Define a metafield attribute for this model.
+    #
+    # @param name [Symbol] The Ruby attribute name
+    # @param namespace [String] The metafield namespace
+    # @param key [String] The metafield key
+    # @param type [Symbol] The type for coercion (:string, :integer, :float, :boolean, :datetime, :json)
+    # @param null [Boolean] Whether the attribute can be null (default: true)
+    # @param default [Object] Default value when GraphQL response is nil
+    # @param transform [Proc] Custom transform block for the value
+    def metafield_attribute(name, namespace:, key:, type: :string, null: true, default: nil, transform: nil)
+      @metafields ||= {}
+      @metafields[name] = { namespace: namespace, key: key, type: type }
+
+      # Build metafield config
+      alias_name = "#{infer_path(name)}Metafield"
+      value_field = type == :json ? 'jsonValue' : 'value'
+      path = "#{alias_name}.#{value_field}"
+
+      config = {
+        path: path,
+        type: type,
+        null: null,
+        default: default,
+        transform: transform,
+        is_metafield: true,
+        metafield_alias: alias_name,
+        metafield_namespace: namespace,
+        metafield_key: key
+      }
+
+      if @current_loader_context
+        @loader_contexts[@current_loader_context][name] = config
+      else
+        @base_attributes ||= {}
+        @base_attributes[name] = config
+      end
+
+      attr_accessor name unless method_defined?(name) || method_defined?("#{name}=")
+    end
+
+    # Get metafields defined for this model
+    def metafields
+      @metafields || {}
+    end
+
+    private
+
+    # Infer GraphQL path from Ruby attribute name (delegates to Attributes if available)
+    def infer_path(name)
+      name.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+    end
+  end
+end

data/lib/active_shopify_graphql/{base.rb → model.rb}

@@ -1,25 +1,39 @@
 # frozen_string_literal: true
 
 module ActiveShopifyGraphQL
-  module Base
-    extend ActiveSupport::Concern
+  # Base class for all GraphQL-backed models.
+  #
+  # Models should inherit from this class (typically via an ApplicationShopifyGqlRecord
+  # intermediate class) to gain ActiveRecord-like functionality for Shopify GraphQL APIs.
+  #
+  # @example Creating an ApplicationShopifyGqlRecord base class
+  #   class ApplicationShopifyGqlRecord < ActiveShopifyGraphQL::Model
+  #     attribute :id, transform: ->(id) { id.split("/").last }
+  #     attribute :gid, path: "id"
+  #   end
+  #
+  # @example Defining a model
+  #   class Customer < ApplicationShopifyGqlRecord
+  #     graphql_type "Customer"
+  #
+  #     attribute :first_name
+  #     attribute :email, path: "defaultEmailAddress.emailAddress"
+  #   end
+  #
+  class Model
+    include ActiveModel::AttributeAssignment
+    include ActiveModel::Validations
+    extend ActiveModel::Naming
 
-    included do
-      include ActiveModel::AttributeAssignment
-      include ActiveModel::Validations
-      extend ActiveModel::Naming
-      include ActiveShopifyGraphQL::GraphqlTypeResolver
-      include ActiveShopifyGraphQL::FinderMethods
-      include ActiveShopifyGraphQL::Associations
-      include ActiveShopifyGraphQL::Connections
-      include ActiveShopifyGraphQL::Attributes
-      include ActiveShopifyGraphQL::MetafieldAttributes
-      include ActiveShopifyGraphQL::LoaderSwitchable
-    end
+    include GraphqlTypeResolver
+    include FinderMethods
+    include Associations
+    include Connections
+    include Attributes
+    include MetafieldAttributes
+    include LoaderSwitchable
 
     def initialize(attributes = {})
-      super()
-
       # Extract connection cache if present and populate inverse caches
       if attributes.key?(:_connection_cache)
         @_connection_cache = attributes.delete(:_connection_cache)

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