active_shopify_graphql 0.3.0 → 0.5.0

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

data/lib/active_shopify_graphql/model/attributes.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::Attributes
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Define an attribute with automatic GraphQL path inference and type coercion.
+    #
+    # @param name [Symbol] The Ruby attribute name
+    # @param path [String] The GraphQL field path (auto-inferred if not provided)
+    # @param type [Symbol] The type for coercion (:string, :integer, :float, :boolean, :datetime)
+    # @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
+    # @param raw_graphql [String] Raw GraphQL string to inject directly (escape hatch for unsupported features)
+    def attribute(name, path: nil, type: :string, null: true, default: nil, transform: nil, raw_graphql: nil)
+      path ||= infer_path(name)
+      config = { path: path, type: type, null: null, default: default, transform: transform, raw_graphql: raw_graphql }
+
+      if @current_loader_context
+        # Store in loader-specific context
+        @loader_contexts[@current_loader_context][name] = config
+      else
+        # Store in base attributes
+        @base_attributes ||= {}
+        @base_attributes[name] = config
+      end
+
+      # Always create attr_accessor
+      attr_accessor name unless method_defined?(name) || method_defined?("#{name}=")
+    end
+
+    # Get attributes for a specific loader class, merging base with loader-specific overrides.
+    def attributes_for_loader(loader_class)
+      base = @base_attributes || {}
+      overrides = @loader_contexts&.dig(loader_class) || {}
+
+      base.merge(overrides) { |_key, base_val, override_val| base_val.merge(override_val) }
+    end
+
+    private
+
+    # Infer GraphQL path from Ruby attribute name (snake_case -> camelCase)
+    def infer_path(name)
+      name.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+    end
+  end
+end

data/lib/active_shopify_graphql/model/connections.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::Connections
+  extend ActiveSupport::Concern
+
+  included do
+    class << self
+      def connections
+        @connections ||= {}
+      end
+
+      attr_writer :connections
+    end
+  end
+
+  class_methods do
+    # Define a singular connection (returns a single object)
+    # @see #connection
+    def has_one_connected(name, inverse_of: nil, **options)
+      connection(name, type: :singular, inverse_of: inverse_of, **options)
+    end
+
+    # Define a plural connection (returns a collection via nodes)
+    # @see #connection
+    def has_many_connected(name, inverse_of: nil, **options)
+      connection(name, type: :connection, inverse_of: inverse_of, **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)
+    # @param inverse_of [Symbol] The name of the inverse connection on the target model (optional)
+    def connection(name, class_name: nil, query_name: nil, foreign_key: nil, loader_class: nil, eager_load: false, type: :connection, default_arguments: {}, inverse_of: nil)
+      # 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,
+        inverse_of: inverse_of
+      }
+
+      # Validate inverse relationship if specified (validation is deferred to runtime)
+      validate_inverse_of!(name, connection_class_name, inverse_of) if inverse_of
+
+      # 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)
+
+          # Populate inverse cache if inverse_of is specified
+          populate_inverse_cache_for_connection(records, config, self)
+
+          # 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] ||= ActiveShopifyGraphQL::Connections::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)
+          Connections::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
+
+    private
+
+    def validate_inverse_of!(_name, _target_class_name, _inverse_name)
+      # Validation is deferred until runtime when connections are actually used
+      # This allows class definitions to be in any order
+      # The validation logic will be checked when inverse cache is populated
+      nil
+    end
+
+    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
+
+  # Instance method to populate inverse cache for lazy-loaded connections
+
+  def populate_inverse_cache_for_connection(records, connection_config, parent)
+    return unless connection_config[:inverse_of]
+    return if records.nil? || (records.is_a?(Array) && records.empty?)
+
+    inverse_name = connection_config[:inverse_of]
+    target_class = connection_config[:class_name].constantize
+
+    # Ensure target class has the inverse connection defined
+    return unless target_class.respond_to?(:connections) && target_class.connections[inverse_name]
+
+    inverse_type = target_class.connections[inverse_name][:type]
+    records_array = records.is_a?(Array) ? records : [records]
+
+    records_array.each do |record|
+      next unless record
+
+      record.instance_variable_set(:@_connection_cache, {}) unless record.instance_variable_get(:@_connection_cache)
+      cache = record.instance_variable_get(:@_connection_cache)
+
+      cache[inverse_name] =
+        if inverse_type == :singular
+          parent
+        else
+          # For collection inverses, wrap parent in an array
+          [parent]
+        end
+    end
+  end
+end

data/lib/active_shopify_graphql/model/finder_methods.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::FinderMethods
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Returns a Relation for the model that can be chained
+    # @return [Relation] A new relation for this model
+    def all
+      ActiveShopifyGraphQL::Query::Relation.new(self)
+    end
+
+    # Find a single record by ID
+    # @param id [String, Integer] The record ID (will be converted to GID automatically)
+    # @param loader [ActiveShopifyGraphQL::Loader] The loader to use for fetching data (deprecated, use Relation chain)
+    # @return [Object] The model instance
+    # @raise [ActiveShopifyGraphQL::ObjectNotFoundError] If the record is not found
+    def find(id)
+      all.find(id)
+    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
+
+    # Find a single record by attribute conditions
+    # @param conditions [Hash] The conditions to query
+    # @return [Object, nil] The first matching model instance or nil if not found
+    #
+    # @example
+    #   Customer.find_by(email: "john@example.com")
+    #   Customer.find_by(first_name: "John", country: "Canada")
+    #   Customer.find_by(orders_count: { gte: 5 })
+    def find_by(conditions = {}, **options)
+      all.find_by(conditions.empty? ? options : conditions)
+    end
+
+    # Query for multiple records using attribute conditions
+    # Returns a Relation that supports chaining .limit(), .includes(), .find_by() and .in_pages()
+    #
+    # Supports three query styles:
+    # 1. Hash-based (safe, with automatic sanitization) - burden on library
+    # 2. String-based (raw query, no sanitization) - burden on developer
+    # 3. String with parameter binding (safe, with sanitization) - burden on library
+    #
+    # @param conditions_or_first_condition [Hash, String] The conditions to query
+    # @param args [Array] Additional positional arguments for parameter binding
+    # @param options [Hash] Named parameters for parameter binding
+    # @return [Relation] A chainable relation
+    #
+    # @example Hash-based query (safe, escaped)
+    #   Customer.where(email: "john@example.com").to_a
+    #   # => produces: query:"email:'john@example.com'"
+    #
+    # @example String-based query (raw, allows wildcards)
+    #   ProductVariant.where("sku:*").to_a
+    #   # => produces: query:"sku:*" (wildcard matching enabled)
+    #
+    # @example String with positional parameter binding (safe)
+    #   ProductVariant.where("sku:? product_id:?", "Good ol' value", 123).to_a
+    #   # => produces: query:"sku:'Good ol\\' value' product_id:123"
+    #
+    # @example String with named parameter binding (safe)
+    #   ProductVariant.where("sku::sku product_id::id", { sku: "A-SKU", id: 123 }).to_a
+    #   ProductVariant.where("sku::sku", sku: "A-SKU").to_a
+    #   # => produces: query:"sku:'A-SKU' product_id:123"
+    #
+    # @example With limit
+    #   Customer.where(first_name: "John").limit(100).to_a
+    #
+    # @example With pagination block
+    #   Customer.where(orders_count: { gte: 5 }).in_pages(of: 50) do |page|
+    #     page.each { |customer| process(customer) }
+    #   end
+    def where(conditions_or_first_condition = {}, *args, **options)
+      all.where(conditions_or_first_condition, *args, **options)
+    end
+
+    # Select specific attributes to optimize GraphQL queries
+    # @param attributes [Symbol] The attributes to select
+    # @return [Relation] A relation with selected attributes
+    #
+    # @example
+    #   Customer.select(:id, :email).find(123)
+    #   Customer.select(:id, :email).where(first_name: "John")
+    def select(*attributes)
+      all.select(*attributes)
+    end
+
+    # Include connections for eager loading
+    # @param connection_names [Array<Symbol>] Connection names to include
+    # @return [Relation] A relation with connections included
+    #
+    # @example
+    #   Customer.includes(:orders).find(123)
+    #   Customer.includes(:orders, :addresses).where(country: "Canada")
+    def includes(*connection_names)
+      all.includes(*connection_names)
+    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