active_shopify_graphql 0.1.0

data/lib/active_shopify_graphql/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Base
+    extend ActiveSupport::Concern
+
+    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
+
+    def initialize(attributes = {})
+      super()
+
+      # Extract connection cache if present
+      @_connection_cache = attributes.delete(:_connection_cache) if attributes.key?(:_connection_cache)
+
+      assign_attributes(attributes)
+    end
+  end
+end

data/lib/active_shopify_graphql/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Configuration class for setting up external dependencies
+  class Configuration
+    attr_accessor :admin_api_client, :customer_account_client_class, :logger, :log_queries, :compact_queries
+
+    def initialize
+      @admin_api_client = nil
+      @customer_account_client_class = nil
+      @logger = nil
+      @log_queries = false
+      @compact_queries = false
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  # Reset configuration (useful for testing)
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/active_shopify_graphql/connection_loader.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'global_id'
+
+module ActiveShopifyGraphQL
+  # Handles loading records for GraphQL connections.
+  # Refactored to use LoaderContext for cleaner parameter passing.
+  class ConnectionLoader
+    attr_reader :context
+
+    def initialize(context, loader_instance:)
+      @context = context
+      @loader_instance = loader_instance
+    end
+
+    # Load records for a connection query
+    # @param query_name [String] The connection field name (e.g., 'orders', 'addresses')
+    # @param variables [Hash] The GraphQL variables (first, sort_key, reverse, query)
+    # @param parent [Object] The parent object that owns this connection
+    # @param connection_config [Hash] The connection configuration
+    # @return [Array<Object>] Array of model instances
+    def load_records(query_name, variables, parent = nil, connection_config = nil)
+      is_nested = connection_config&.dig(:nested) || parent.respond_to?(:id)
+
+      if is_nested && parent
+        load_nested_connection(query_name, variables, parent, connection_config)
+      else
+        load_root_connection(query_name, variables, connection_config)
+      end
+    end
+
+    private
+
+    def load_nested_connection(query_name, variables, parent, connection_config)
+      parent_type = parent.class.graphql_type_for_loader(@context.loader_class)
+      parent_query_name = parent_type.downcase
+      connection_type = connection_config&.dig(:type) || :connection
+
+      query = QueryTree.build_connection_query(
+        @context,
+        query_name: query_name,
+        variables: variables,
+        parent_query: "#{parent_query_name}(id: $id)",
+        connection_type: connection_type
+      )
+
+      parent_id = extract_gid(parent)
+      response_data = @loader_instance.perform_graphql_query(query, id: parent_id)
+
+      return [] if response_data.nil?
+
+      mapper = ResponseMapper.new(@context)
+      mapper.map_nested_connection_response(response_data, query_name, parent, connection_config)
+    end
+
+    def load_root_connection(query_name, variables, connection_config)
+      connection_type = connection_config&.dig(:type) || :connection
+
+      query = QueryTree.build_connection_query(
+        @context,
+        query_name: query_name,
+        variables: variables,
+        parent_query: nil,
+        connection_type: connection_type
+      )
+
+      response_data = @loader_instance.perform_graphql_query(query)
+
+      return [] if response_data.nil?
+
+      mapper = ResponseMapper.new(@context)
+      mapper.map_connection_response(response_data, query_name, connection_config)
+    end
+
+    def extract_gid(parent)
+      return parent.gid if parent.respond_to?(:gid) && !parent.gid.nil?
+
+      id_value = parent.id
+      parent_type = resolve_parent_type(parent)
+
+      GidHelper.normalize_gid(id_value, parent_type)
+    end
+
+    def resolve_parent_type(parent)
+      klass = parent.class
+
+      if klass.respond_to?(:graphql_type_for_loader)
+        klass.graphql_type_for_loader(@context.loader_class)
+      elsif klass.respond_to?(:graphql_type)
+        klass.graphql_type
+      else
+        klass.name
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/connections/connection_proxy.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Connections
+    # Lazy-loading proxy for GraphQL connections.
+    # Implements Enumerable and delegates to the loaded records array.
+    class ConnectionProxy
+      include Enumerable
+
+      def initialize(parent:, connection_name:, connection_config:, options:)
+        @parent = parent
+        @connection_name = connection_name
+        @connection_config = connection_config
+        @options = options
+        @loaded = false
+        @records = nil
+      end
+
+      # Core Enumerable method - all others derive from this
+      def each(&block)
+        ensure_loaded
+        @records.each(&block)
+      end
+
+      # Array coercion (returns a copy to prevent mutation)
+      def to_a
+        ensure_loaded
+        @records.dup
+      end
+      alias to_ary to_a
+
+      def loaded?
+        @loaded
+      end
+
+      def load
+        ensure_loaded
+        self
+      end
+
+      # Override for efficiency - avoids full iteration
+      def size
+        ensure_loaded
+        @records.size
+      end
+      alias length size
+      alias count size
+
+      # Override for efficiency
+      def empty?
+        ensure_loaded
+        @records.empty?
+      end
+
+      # Override first/last for efficiency (avoid iterating entire collection)
+      def first(n = nil)
+        ensure_loaded
+        n ? @records.first(n) : @records.first
+      end
+
+      def last(n = nil)
+        ensure_loaded
+        n ? @records.last(n) : @records.last
+      end
+
+      def [](index)
+        ensure_loaded
+        @records[index]
+      end
+
+      def reload
+        @loaded = false
+        @records = nil
+        self
+      end
+
+      def inspect
+        ensure_loaded
+        @records.inspect
+      end
+
+      def pretty_print(q)
+        ensure_loaded
+        @records.pretty_print(q)
+      end
+
+      private
+
+      def ensure_loaded
+        return if @loaded
+
+        loader_class = @connection_config[:loader_class] || @parent.class.default_loader.class
+        target_class = @connection_config[:class_name].constantize
+        loader = loader_class.new(target_class)
+
+        @records = loader.load_connection_records(
+          @connection_config[:query_name],
+          build_variables,
+          @parent,
+          @connection_config
+        ) || []
+
+        @loaded = true
+      end
+
+      def build_variables
+        default_args = @connection_config[:default_arguments] || {}
+        default_args.merge(@options).compact
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/connections.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "connections/connection_proxy"
+
+module ActiveShopifyGraphQL
+  module Connections
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        attr_accessor :connections
+      end
+
+      self.connections = {}
+    end
+
+    class_methods do
+      # Define a singular connection (returns a single object)
+      # @see #connection
+      def has_one_connected(name, **options)
+        connection(name, type: :singular, **options)
+      end
+
+      # Define a plural connection (returns a collection via edges)
+      # @see #connection
+      def has_many_connected(name, **options)
+        connection(name, type: :connection, **options)
+      end
+
+      # Define a GraphQL connection to another ActiveShopifyGraphQL model
+      # @param name [Symbol] The connection name (e.g., :orders)
+      # @param class_name [String] The target model class name (defaults to name.to_s.classify)
+      # @param query_name [String] The GraphQL query field name (auto-determined based on nested/root-level)
+      # @param foreign_key [String] The field to filter by (auto-determined for root-level queries)
+      # @param loader_class [Class] Custom loader class to use (defaults to model's default loader)
+      # @param eager_load [Boolean] Whether to automatically eager load this connection (default: false)
+      # @param type [Symbol] The type of connection (:connection, :singular). Default is :connection.
+      # @param default_arguments [Hash] Default arguments to pass to the GraphQL query (e.g. first: 10)
+      def connection(name, class_name: nil, query_name: nil, foreign_key: nil, loader_class: nil, eager_load: false, type: :connection, default_arguments: {})
+        # Infer defaults
+        connection_class_name = class_name || name.to_s.classify
+
+        # Set query_name - default to camelCase for nested fields
+        connection_query_name = query_name || name.to_s.camelize(:lower)
+
+        connection_loader_class = loader_class
+
+        # Store connection metadata
+        connections[name] = {
+          class_name: connection_class_name,
+          query_name: connection_query_name,
+          foreign_key: foreign_key,
+          loader_class: connection_loader_class,
+          eager_load: eager_load,
+          type: type,
+          nested: true, # Always treated as nested (accessed via parent field)
+          target_class_name: connection_class_name,
+          original_name: name,
+          default_arguments: default_arguments
+        }
+
+        # Define the connection method that returns a proxy
+        define_method name do |**options|
+          # Check if this connection was eager loaded
+          return @_connection_cache[name] if @_connection_cache&.key?(name)
+
+          config = self.class.connections[name]
+          if config[:type] == :singular
+            # Lazy load singular association
+            loader_class = config[:loader_class] || self.class.default_loader.class
+            target_class = config[:class_name].constantize
+            loader = loader_class.new(target_class)
+
+            # Load the record
+            records = loader.load_connection_records(config[:query_name], options, self, config)
+
+            # Cache it
+            @_connection_cache ||= {}
+            @_connection_cache[name] = records
+            records
+          elsif options.empty?
+            # If no runtime options are provided, reuse existing proxy if it exists
+            @_connection_proxies ||= {}
+            @_connection_proxies[name] ||= ConnectionProxy.new(
+              parent: self,
+              connection_name: name,
+              connection_config: self.class.connections[name],
+              options: options
+            )
+          else
+            # Create a new proxy for custom options (don't cache these)
+            ConnectionProxy.new(
+              parent: self,
+              connection_name: name,
+              connection_config: self.class.connections[name],
+              options: options
+            )
+          end
+        end
+
+        # Define setter method for testing/caching
+        define_method "#{name}=" do |value|
+          @_connection_cache ||= {}
+          @_connection_cache[name] = value
+        end
+      end
+
+      # Load records with eager-loaded connections
+      # @param *connection_names [Symbol, Hash] The connection names to eager load
+      # @return [Class] A modified class for method chaining
+      #
+      # @example
+      #   Customer.includes(:orders).find(123)
+      #   Customer.includes(:orders, :addresses).where(email: "john@example.com")
+      #   Order.includes(line_items: :variant)
+      def includes(*connection_names)
+        # Validate connections exist
+        validate_includes_connections!(connection_names)
+
+        # Collect connections with eager_load: true
+        auto_included_connections = connections.select { |_name, config| config[:eager_load] }.keys
+
+        # Merge manual and automatic connections
+        all_included_connections = (connection_names + auto_included_connections).uniq
+
+        # Create a new class that inherits from self with eager loading enabled
+        included_class = Class.new(self)
+
+        # Store the connections to include
+        included_class.instance_variable_set(:@included_connections, all_included_connections)
+
+        # Override methods to use eager loading
+        included_class.define_singleton_method(:default_loader) do
+          @default_loader ||= superclass.default_loader.class.new(
+            superclass,
+            included_connections: @included_connections
+          )
+        end
+
+        # Preserve the original class name and model name for GraphQL operations
+        included_class.define_singleton_method(:name) { superclass.name }
+        included_class.define_singleton_method(:model_name) { superclass.model_name }
+        included_class.define_singleton_method(:connections) { superclass.connections }
+
+        included_class
+      end
+
+      private
+
+      def validate_includes_connections!(connection_names)
+        connection_names.each do |name|
+          if name.is_a?(Hash)
+            name.each do |key, value|
+              raise ArgumentError, "Invalid connection for #{self.name}: #{key}. Available connections: #{connections.keys.join(', ')}" unless connections.key?(key.to_sym)
+
+              # Recursively validate nested connections
+              target_class = connections[key.to_sym][:class_name].constantize
+              if target_class.respond_to?(:validate_includes_connections!, true)
+                nested_names = value.is_a?(Array) ? value : [value]
+                target_class.send(:validate_includes_connections!, nested_names)
+              end
+            end
+          else
+            raise ArgumentError, "Invalid connection for #{self.name}: #{name}. Available connections: #{connections.keys.join(', ')}" unless connections.key?(name.to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/finder_methods.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module FinderMethods
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Find a single record by ID using the provided loader
+      # @param id [String, Integer] The record ID (will be converted to GID automatically)
+      # @param loader [ActiveShopifyGraphQL::Loader] The loader to use for fetching data
+      # @return [Object, nil] The model instance or nil if not found
+      def find(id, loader: default_loader)
+        gid = GidHelper.normalize_gid(id, model_name.name.demodulize)
+        attributes = loader.load_attributes(gid)
+
+        return nil if attributes.nil?
+
+        new(attributes)
+      end
+
+      # Returns the default loader for this model's queries
+      # @return [ActiveGraphQL::Loader] The default loader instance
+      def default_loader
+        if respond_to?(:default_loader_instance)
+          default_loader_instance
+        else
+          @default_loader ||= begin
+            # Collect connections with eager_load: true
+            eagerly_loaded_connections = connections.select { |_name, config| config[:eager_load] }.keys
+
+            default_loader_class.new(
+              self,
+              included_connections: eagerly_loaded_connections
+            )
+          end
+        end
+      end
+
+      # Allows setting a custom default loader (useful for testing)
+      # @param loader [ActiveGraphQL::Loader] The loader to set as default
+      def default_loader=(loader)
+        @default_loader = loader
+      end
+
+      # Select specific attributes to optimize GraphQL queries
+      # @param *attributes [Symbol] The attributes to select
+      # @return [Class] A class with modified default loader for method chaining
+      #
+      # @example
+      #   Customer.select(:id, :email).find(123)
+      #   Customer.select(:id, :email).where(first_name: "John")
+      def select(*attributes)
+        # Validate attributes exist
+        attrs = Array(attributes).flatten.map(&:to_sym)
+        validate_select_attributes!(attrs)
+
+        # Create a new class that inherits from self with a modified default loader
+        selected_class = Class.new(self)
+
+        # Override the default_loader method to return a loader with selected attributes
+        selected_class.define_singleton_method(:default_loader) do
+          @default_loader ||= superclass.default_loader.class.new(
+            superclass,
+            selected_attributes: attrs
+          )
+        end
+
+        # Preserve the original class name and model name for GraphQL operations
+        selected_class.define_singleton_method(:name) { superclass.name }
+        selected_class.define_singleton_method(:model_name) { superclass.model_name }
+
+        selected_class
+      end
+
+      # Query for multiple records using attribute conditions
+      # @param conditions [Hash] The conditions to query (e.g., { email: "example@test.com", first_name: "John" })
+      # @param options [Hash] Options hash containing loader and limit (when first arg is a Hash)
+      # @option options [ActiveShopifyGraphQL::Loader] :loader The loader to use for fetching data
+      # @option options [Integer] :limit The maximum number of records to return (default: 250, max: 250)
+      # @return [Array<Object>] Array of model instances
+      # @raise [ArgumentError] If any attribute is not valid for querying
+      #
+      # @example
+      #   # Keyword argument style (recommended)
+      #   Customer.where(email: "john@example.com")
+      #   Customer.where(first_name: "John", country: "Canada")
+      #   Customer.where(orders_count: { gte: 5 })
+      #   Customer.where(created_at: { gte: "2024-01-01", lt: "2024-02-01" })
+      #
+      #   # Hash style with options
+      #   Customer.where({ email: "john@example.com" }, loader: custom_loader, limit: 100)
+      def where(conditions_or_first_condition = {}, *args, **options)
+        # Handle both syntaxes:
+        # where(email: "john@example.com") - keyword args become options
+        # where({ email: "john@example.com" }, loader: custom_loader) - explicit hash + options
+        if conditions_or_first_condition.is_a?(Hash) && !conditions_or_first_condition.empty?
+          # Explicit hash provided as first argument
+          conditions = conditions_or_first_condition
+          # Any additional options passed as keyword args or second hash argument
+          final_options = args.first.is_a?(Hash) ? options.merge(args.first) : options
+        else
+          # Keyword arguments style - conditions come from options, excluding known option keys
+          known_option_keys = %i[loader limit]
+          conditions = options.except(*known_option_keys)
+          final_options = options.slice(*known_option_keys)
+        end
+
+        loader = final_options[:loader] || default_loader
+        limit = final_options[:limit] || 250
+
+        # Ensure loader has model class set - needed for graphql_type inference
+        loader.instance_variable_set(:@model_class, self) if loader.instance_variable_get(:@model_class).nil?
+
+        attributes_array = loader.load_collection(conditions, limit: limit)
+
+        attributes_array.map { |attributes| new(attributes) }
+      end
+
+      private
+
+      # Validates that selected attributes exist in the model
+      # @param attributes [Array<Symbol>] The attributes to validate
+      # @raise [ArgumentError] If any attribute is invalid
+      def validate_select_attributes!(attributes)
+        return if attributes.empty?
+
+        available_attrs = available_select_attributes
+        invalid_attrs = attributes - available_attrs
+
+        return unless invalid_attrs.any?
+
+        raise ArgumentError, "Invalid attributes for #{name}: #{invalid_attrs.join(', ')}. " \
+                           "Available attributes are: #{available_attrs.join(', ')}"
+      end
+
+      # Gets all available attributes for selection
+      # @return [Array<Symbol>] Available attribute names
+      def available_select_attributes
+        attrs = []
+
+        # Get attributes from the model class
+        loader_class = default_loader.class
+        model_attrs = attributes_for_loader(loader_class)
+        attrs.concat(model_attrs.keys)
+
+        # Get attributes from the loader class
+        loader_attrs = default_loader.class.defined_attributes
+        attrs.concat(loader_attrs.keys)
+
+        attrs.map(&:to_sym).uniq.sort
+      end
+    end
+  end
+end