active_shopify_graphql 0.3.0 → 0.5.0

data/lib/active_shopify_graphql/response/paginated_result.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Response
+    # Represents a page of results from a paginated GraphQL query.
+    # Lazily builds model instances from attribute hashes on access.
+    # Provides methods to navigate between pages and access pagination metadata.
+    #
+    # @example Manual pagination
+    #   page = ProductVariant.where(sku: "*").in_pages(of: 10)
+    #   page.has_next_page? # => true
+    #   next_page = page.next_page
+    #
+    # @example Iteration with block
+    #   ProductVariant.where(sku: "*").in_pages(of: 10) do |page|
+    #     page.each { |variant| process(variant) }
+    #   end
+    class PaginatedResult
+      include Enumerable
+
+      attr_reader :page_info, :query_scope
+
+      def initialize(attributes:, model_class:, page_info:, query_scope:)
+        @attributes = attributes
+        @model_class = model_class
+        @page_info = page_info
+        @query_scope = query_scope
+        @records = nil # Lazily built
+      end
+
+      # Get the records for this page (builds instances on first access)
+      def records
+        @records ||= ModelBuilder.build_many(@model_class, @attributes)
+      end
+
+      # Iterate over records in this page
+      def each(&block)
+        records.each(&block)
+      end
+
+      # Access records by index
+      def [](index)
+        records[index]
+      end
+
+      # Number of records in this page
+      def size
+        @attributes.size
+      end
+      alias length size
+
+      # Check if this page has records
+      def empty?
+        @attributes.empty?
+      end
+
+      # Check if there is a next page
+      def has_next_page?
+        @page_info.has_next_page?
+      end
+
+      # Check if there is a previous page
+      def has_previous_page?
+        @page_info.has_previous_page?
+      end
+
+      # Cursor pointing to the start of this page
+      def start_cursor
+        @page_info.start_cursor
+      end
+
+      # Cursor pointing to the end of this page
+      def end_cursor
+        @page_info.end_cursor
+      end
+
+      # Fetch the next page of results
+      # @return [PaginatedResult, nil] The next page or nil if no more pages
+      def next_page
+        return nil unless has_next_page?
+
+        @query_scope.fetch_page(after: end_cursor)
+      end
+
+      # Fetch the previous page of results
+      # @return [PaginatedResult, nil] The previous page or nil if no previous pages
+      def previous_page
+        return nil unless has_previous_page?
+
+        @query_scope.fetch_page(before: start_cursor)
+      end
+
+      # Convert to array (useful for compatibility)
+      def to_a
+        records.dup
+      end
+
+      # Return all records across all pages
+      # Warning: This will make multiple API calls if there are many pages
+      # @return [Array] All records from all pages
+      def all_records
+        all = records.dup
+        current = self
+
+        while current.has_next_page?
+          current = current.next_page
+          all.concat(current.records)
+        end
+
+        all
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/response/response_mapper.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Response
+    # Handles mapping GraphQL responses to model attributes.
+    # Refactored to use LoaderContext and unified mapping methods.
+    class ResponseMapper
+      attr_reader :context
+
+      def initialize(context)
+        @context = context
+      end
+
+      # Map GraphQL response to attributes using declared attribute metadata
+      # @param response_data [Hash] The full GraphQL response
+      # @param root_path [Array<String>] Path to the data root (e.g., ["data", "customer"])
+      # @return [Hash] Mapped attributes
+      def map_response(response_data, root_path: nil)
+        root_path ||= ["data", @context.query_name]
+        root_data = response_data.dig(*root_path)
+        return {} unless root_data
+
+        map_node_to_attributes(root_data)
+      end
+
+      # Map a single node's data to attributes (used for both root and nested)
+      def map_node_to_attributes(node_data)
+        return {} unless node_data
+
+        result = {}
+        @context.defined_attributes.each do |attr_name, config|
+          value = extract_and_transform_value(node_data, config, attr_name)
+          result[attr_name] = value
+        end
+        result
+      end
+
+      # Extract connection data from GraphQL response for eager loading
+      def extract_connection_data(response_data, root_path: nil, parent_instance: nil)
+        return {} if @context.included_connections.empty?
+
+        root_path ||= ["data", @context.query_name]
+        root_data = response_data.dig(*root_path)
+        return {} unless root_data
+
+        extract_connections_from_node(root_data, parent_instance)
+      end
+
+      # Extract connections from a node (reusable for nested connections)
+      def extract_connections_from_node(node_data, parent_instance = nil)
+        return {} if @context.included_connections.empty?
+
+        connections = @context.connections
+        return {} if connections.empty?
+
+        normalized_includes = Query::QueryBuilder.normalize_includes(@context.included_connections)
+        connection_cache = {}
+
+        normalized_includes.each do |connection_name, nested_includes|
+          connection_config = connections[connection_name]
+          next unless connection_config
+
+          records = extract_connection_records(node_data, connection_config, nested_includes, parent_instance: parent_instance)
+          connection_cache[connection_name] = records if records
+        end
+
+        connection_cache
+      end
+
+      # Map nested connection response (when loading via parent query)
+      # Returns attributes instead of instances
+      def map_nested_connection_response(response_data, connection_field_name, parent, connection_config = nil)
+        parent_type = parent.class.graphql_type_for_loader(@context.loader_class)
+        parent_query_name = parent_type.camelize(:lower)
+        connection_type = connection_config&.dig(:type) || :connection
+
+        if connection_type == :singular
+          node_data = response_data.dig("data", parent_query_name, connection_field_name)
+          return nil unless node_data
+
+          map_node_to_attributes(node_data)
+        else
+          nodes = response_data.dig("data", parent_query_name, connection_field_name, "nodes")
+          return [] unless nodes
+
+          nodes.filter_map do |node_data|
+            map_node_to_attributes(node_data) if node_data
+          end
+        end
+      end
+
+      # Map root connection response
+      # Returns attributes instead of instances
+      def map_connection_response(response_data, query_name, connection_config = nil)
+        connection_type = connection_config&.dig(:type) || :connection
+
+        if connection_type == :singular
+          node_data = response_data.dig("data", query_name)
+          return nil unless node_data
+
+          map_node_to_attributes(node_data)
+        else
+          nodes = response_data.dig("data", query_name, "nodes")
+          return [] unless nodes
+
+          nodes.filter_map do |node_data|
+            map_node_to_attributes(node_data) if node_data
+          end
+        end
+      end
+
+      private
+
+      def extract_and_transform_value(node_data, config, attr_name)
+        path = config[:path]
+
+        value = if config[:raw_graphql]
+                  # For raw_graphql, the alias is the attr_name, then dig using path if nested
+                  raw_data = node_data[attr_name.to_s]
+                  if path.include?('.')
+                    # Path is relative to the aliased root
+                    path_parts = path.split('.')[1..] # Skip the first part (attr_name itself)
+                    path_parts.any? ? raw_data&.dig(*path_parts) : raw_data
+                  else
+                    raw_data
+                  end
+                elsif path.include?('.')
+                  # Nested path - dig using the full path
+                  path_parts = path.split('.')
+                  node_data.dig(*path_parts)
+                else
+                  # Simple path - use attr_name as key (matches the alias in the query)
+                  node_data[attr_name.to_s]
+                end
+
+        value = apply_defaults_and_transforms(value, config)
+        validate_null_constraint!(value, config, attr_name)
+        coerce_value(value, config[:type])
+      end
+
+      def apply_defaults_and_transforms(value, config)
+        if value.nil?
+          return config[:default] unless config[:default].nil?
+
+          return config[:transform]&.call(value)
+        end
+
+        config[:transform] ? config[:transform].call(value) : value
+      end
+
+      def validate_null_constraint!(value, config, attr_name)
+        return unless !config[:null] && value.nil?
+
+        raise ArgumentError, "Attribute '#{attr_name}' (GraphQL path: '#{config[:path]}') cannot be null but received nil"
+      end
+
+      def coerce_value(value, type)
+        return nil if value.nil?
+        return value if value.is_a?(Array) # Preserve arrays
+
+        type_caster(type).cast(value)
+      end
+
+      def type_caster(type)
+        case type
+        when :string   then ActiveModel::Type::String.new
+        when :integer  then ActiveModel::Type::Integer.new
+        when :float    then ActiveModel::Type::Float.new
+        when :boolean  then ActiveModel::Type::Boolean.new
+        when :datetime then ActiveModel::Type::DateTime.new
+        else ActiveModel::Type::Value.new
+        end
+      end
+
+      def extract_connection_records(node_data, connection_config, nested_includes, parent_instance: nil)
+        # Use original_name (Ruby attr name) as the response key since we alias connections
+        response_key = connection_config[:original_name].to_s
+        connection_type = connection_config[:type] || :connection
+        target_class = connection_config[:class_name].constantize
+
+        if connection_type == :singular
+          item_data = node_data[response_key]
+          return nil unless item_data
+
+          build_nested_model_instance(item_data, target_class, nested_includes,
+                                      parent_instance: parent_instance,
+                                      connection_config: connection_config)
+        else
+          nodes = node_data.dig(response_key, "nodes")
+          return nil unless nodes
+
+          nodes.filter_map do |item_data|
+            if item_data
+              build_nested_model_instance(item_data, target_class, nested_includes,
+                                          parent_instance: parent_instance,
+                                          connection_config: connection_config)
+            end
+          end
+        end
+      end
+
+      # Build a nested model instance with inverse_of wiring
+      # Used for eager-loaded connections that go into the connection cache
+      def build_nested_model_instance(node_data, target_class, nested_includes, parent_instance: nil, connection_config: nil)
+        nested_context = @context.for_model(target_class, new_connections: nested_includes)
+        nested_mapper = ResponseMapper.new(nested_context)
+
+        attributes = nested_mapper.map_node_to_attributes(node_data)
+        instance = target_class.new(attributes)
+
+        # Populate inverse cache if inverse_of is specified
+        if parent_instance && connection_config && connection_config[:inverse_of]
+          inverse_name = connection_config[:inverse_of]
+          instance.instance_variable_set(:@_connection_cache, {}) unless instance.instance_variable_get(:@_connection_cache)
+          cache = instance.instance_variable_get(:@_connection_cache)
+
+          # Check the type of the inverse connection to determine how to cache
+          if target_class.respond_to?(:connections) && target_class.connections[inverse_name]
+            inverse_type = target_class.connections[inverse_name][:type]
+            cache[inverse_name] =
+              if inverse_type == :singular
+                parent_instance
+              else
+                # For collection inverses, wrap parent in an array
+                [parent_instance]
+              end
+          end
+        end
+
+        # Handle nested connections recursively (instance becomes parent for its children)
+        if nested_includes.any?
+          nested_data = nested_mapper.extract_connections_from_node(node_data, instance)
+          nested_data.each do |nested_name, nested_records|
+            instance.send("#{nested_name}=", nested_records)
+          end
+        end
+
+        instance
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/search_query/hash_condition_formatter.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "value_sanitizer"
+
+module ActiveShopifyGraphQL
+  class SearchQuery
+    # Formats hash-based query conditions with proper sanitization
+    class HashConditionFormatter
+      # Formats hash conditions into a Shopify search query string
+      # @param conditions [Hash] The conditions to format
+      # @return [String] The formatted query string
+      def self.format(conditions)
+        return "" if conditions.empty?
+
+        query_parts = conditions.map do |key, value|
+          format_condition(key.to_s, value)
+        end
+
+        query_parts.join(" AND ")
+      end
+
+      # Formats a single query condition
+      # @param key [String] The attribute name
+      # @param value [Object] The attribute value
+      # @return [String] The formatted query condition
+      def self.format_condition(key, value)
+        case value
+        when Array
+          format_array_condition(key, value)
+        when String
+          format_string_condition(key, value)
+        when Numeric, true, false
+          "#{key}:#{value}"
+        when Hash
+          format_range_condition(key, value)
+        else
+          "#{key}:#{value}"
+        end
+      end
+
+      # Formats an array condition with OR clauses
+      # @param key [String] The attribute name
+      # @param values [Array] The array of values
+      # @return [String] The formatted query with OR clauses wrapped in parentheses
+      def self.format_array_condition(key, values)
+        return "" if values.empty?
+        return format_condition(key, values.first) if values.size == 1
+
+        or_parts = values.map do |value|
+          format_single_value(key, value)
+        end
+
+        "(#{or_parts.join(' OR ')})"
+      end
+
+      # Formats a single value for use in array OR clauses
+      # @param key [String] The attribute name
+      # @param value [Object] The attribute value
+      # @return [String] The formatted key:value pair
+      def self.format_single_value(key, value)
+        case value
+        when String
+          format_string_condition(key, value)
+        when Numeric, true, false
+          "#{key}:#{value}"
+        else
+          "#{key}:#{value}"
+        end
+      end
+
+      # Formats a string condition with proper quoting and sanitization
+      # @param key [String] The attribute name
+      # @param value [String] The string value
+      # @return [String] The formatted condition
+      def self.format_string_condition(key, value)
+        escaped_value = ValueSanitizer.sanitize(value)
+        "#{key}:'#{escaped_value}'"
+      end
+
+      # Formats a range condition (e.g., { created_at: { gte: '2024-01-01' } })
+      # @param key [String] The attribute name
+      # @param value [Hash] The range conditions
+      # @return [String] The formatted range condition
+      def self.format_range_condition(key, value)
+        range_parts = value.map do |operator, range_value|
+          case operator.to_sym
+          when :gt, :>
+            "#{key}:>#{range_value}"
+          when :gte, :>=
+            "#{key}:>=#{range_value}"
+          when :lt, :<
+            "#{key}:<#{range_value}"
+          when :lte, :<=
+            "#{key}:<=#{range_value}"
+          else
+            raise ArgumentError, "Unsupported range operator: #{operator}"
+          end
+        end
+        range_parts.join(" ")
+      end
+
+      private_class_method :format_condition, :format_array_condition,
+                           :format_single_value, :format_string_condition,
+                           :format_range_condition
+    end
+  end
+end

data/lib/active_shopify_graphql/search_query/parameter_binder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "value_sanitizer"
+
+module ActiveShopifyGraphQL
+  class SearchQuery
+    # Binds parameters to string queries with proper sanitization
+    # Supports both positional (?) and named (:param) placeholders
+    class ParameterBinder
+      # Binds parameters to a query string
+      # @param query_string [String] The query with placeholders
+      # @param args [Array] Positional arguments or a hash of named parameters
+      # @return [String] The query with bound and escaped parameters
+      def self.bind(query_string, *args)
+        return query_string if args.empty?
+
+        if args.first.is_a?(Hash)
+          bind_named_parameters(query_string, args.first)
+        else
+          bind_positional_parameters(query_string, args)
+        end
+      end
+
+      # Binds positional parameters (?)
+      # @param query_string [String] The query with ? placeholders
+      # @param values [Array] The values to bind
+      # @return [String] The query with bound parameters
+      def self.bind_positional_parameters(query_string, values)
+        result = query_string.dup
+        values.each do |value|
+          result = result.sub("?", format_value(value))
+        end
+        result
+      end
+
+      # Binds named parameters (:name)
+      # @param query_string [String] The query with :name placeholders
+      # @param params [Hash] The parameters hash
+      # @return [String] The query with bound parameters
+      def self.bind_named_parameters(query_string, params)
+        result = query_string.dup
+        params.each do |key, value|
+          placeholder = ":#{key}"
+          result = result.gsub(placeholder, format_value(value))
+        end
+        result
+      end
+
+      # Formats a value for safe insertion into query
+      # @param value [Object] The value to format
+      # @return [String] The formatted value
+      def self.format_value(value)
+        case value
+        when String
+          "'#{ValueSanitizer.sanitize(value)}'"
+        when Numeric, true, false
+          value.to_s
+        when nil
+          "null"
+        else
+          "'#{ValueSanitizer.sanitize(value.to_s)}'"
+        end
+      end
+
+      private_class_method :bind_positional_parameters, :bind_named_parameters, :format_value
+    end
+  end
+end

data/lib/active_shopify_graphql/search_query/value_sanitizer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  class SearchQuery
+    # Sanitizes values by escaping special characters for Shopify search syntax
+    class ValueSanitizer
+      # Sanitizes a value by escaping special characters
+      # @param value [String] The value to sanitize
+      # @return [String] The sanitized value
+      def self.sanitize(value)
+        value
+          .gsub('\\', '\\\\\\\\') # Escape backslashes first: \ becomes \\
+          .gsub('"', '\\"') # Escape double quotes with a single backslash
+          # Escape single quotes: O'Reilly becomes O\\'Reilly
+          # Why 4 backslashes? The escaping happens in layers:
+          # 1. Ruby string literal: "\\\\\\\\''" = literal string "\\\\''"
+          # 2. String interpolation in "#{key}:'#{escaped_value}'": the \\\' becomes \\'
+          # 3. Final GraphQL query: customers(query: "title:'O\\'Reilly'")
+          # The double backslash is required by Shopify's search syntax to properly escape the single quote
+          .gsub("'", "\\\\\\\\'")
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/search_query.rb

@@ -1,103 +1,53 @@
 # frozen_string_literal: true
 
+require_relative "search_query/hash_condition_formatter"
+require_relative "search_query/parameter_binder"
+
 module ActiveShopifyGraphQL
   # Represents a Shopify search query, converting Ruby conditions into Shopify's search syntax
+  # Supports hash-based conditions (with sanitization), string-based conditions (raw), and parameter binding
+  #
+  # @example Hash-based query (safe, with sanitization)
+  #   SearchQuery.new(sku: "ABC-123").to_s
+  #   # => "sku:'ABC-123'"
+  #
+  # @example String-based query (raw, user responsibility for safety)
+  #   SearchQuery.new("sku:* AND product_id:123").to_s
+  #   # => "sku:* AND product_id:123"
+  #
+  # @example String with positional parameter binding
+  #   SearchQuery.new("sku:? product_id:?", "Good ol' value", 123).to_s
+  #   # => "sku:'Good ol\\' value' product_id:123"
+  #
+  # @example String with named parameter binding
+  #   SearchQuery.new("sku::sku product_id::product_id", { sku: "A-SKU", product_id: 123 }).to_s
+  #   # => "sku:'A-SKU' product_id:123"
   class SearchQuery
-    def initialize(conditions = {})
+    def initialize(conditions = {}, *args)
       @conditions = conditions
+      @args = args
     end
 
     # Converts conditions to Shopify search query string
     # @return [String] The Shopify query string
     def to_s
-      return "" if @conditions.empty?
-
-      query_parts = @conditions.map do |key, value|
-        format_condition(key.to_s, value)
-      end
-
-      query_parts.join(" AND ")
-    end
-
-    private
-
-    # Formats a single query condition into Shopify's query syntax
-    # @param key [String] The attribute name
-    # @param value [Object] The attribute value
-    # @return [String] The formatted query condition
-    def format_condition(key, value)
-      case value
-      when Array
-        format_array_condition(key, value)
-      when String
-        format_string_condition(key, value)
-      when Numeric, true, false
-        "#{key}:#{value}"
+      case @conditions
       when Hash
-        format_range_condition(key, value)
-      else
-        "#{key}:#{value}"
-      end
-    end
-
-    # Formats an array condition with OR clauses
-    # @param key [String] The attribute name
-    # @param values [Array] The array of values
-    # @return [String] The formatted query with OR clauses wrapped in parentheses
-    def format_array_condition(key, values)
-      return "" if values.empty?
-      return format_condition(key, values.first) if values.size == 1
-
-      or_parts = values.map do |value|
-        format_single_value(key, value)
-      end
-
-      "(#{or_parts.join(' OR ')})"
-    end
-
-    # Formats a single value for use in array OR clauses
-    # @param key [String] The attribute name
-    # @param value [Object] The attribute value
-    # @return [String] The formatted key:value pair
-    def format_single_value(key, value)
-      case value
+        HashConditionFormatter.format(@conditions)
       when String
-        format_string_condition(key, value)
-      when Numeric, true, false
-        "#{key}:#{value}"
-      else
-        "#{key}:#{value}"
-      end
-    end
-
-    # Formats a string condition with proper quoting
-    def format_string_condition(key, value)
-      # Handle special string values and escape quotes
-      if value.include?(" ") && !value.start_with?('"')
-        # Multi-word values should be quoted
-        "#{key}:\"#{value.gsub('"', '\\"')}\""
-      else
-        "#{key}:#{value}"
-      end
-    end
-
-    # Formats a range condition (e.g., { created_at: { gte: '2024-01-01' } })
-    def format_range_condition(key, value)
-      range_parts = value.map do |operator, range_value|
-        case operator.to_sym
-        when :gt, :>
-          "#{key}:>#{range_value}"
-        when :gte, :>=
-          "#{key}:>=#{range_value}"
-        when :lt, :<
-          "#{key}:<#{range_value}"
-        when :lte, :<=
-          "#{key}:<=#{range_value}"
+        if @args.empty?
+          @conditions
         else
-          raise ArgumentError, "Unsupported range operator: #{operator}"
+          ParameterBinder.bind(@conditions, *@args)
         end
+      when Array
+        # Handle [query_string, *binding_args] format from FinderMethods#where
+        query_string = @conditions.first
+        binding_args = @conditions[1..]
+        ParameterBinder.bind(query_string, *binding_args)
+      else
+        ""
       end
-      range_parts.join(" ")
     end
   end
 end