active_shopify_graphql 0.4.0 → 0.5.0

data/lib/active_shopify_graphql/query/scope.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    # A chainable query builder that accumulates query configuration
+    # and executes the query when records are accessed.
+    #
+    # @example Basic usage
+    #   ProductVariant.where(sku: "*").limit(100).to_a
+    #
+    # @example Pagination with block
+    #   ProductVariant.where(sku: "*").in_pages(of: 50) do |page|
+    #     process_batch(page)
+    #   end
+    #
+    # @example Manual pagination
+    #   page = ProductVariant.where(sku: "*").in_pages(of: 50)
+    #   page.each { |record| process(record) }
+    #   page = page.next_page while page.has_next_page?
+    class Scope
+      include Enumerable
+
+      DEFAULT_PER_PAGE = 250
+
+      attr_reader :model_class, :conditions, :total_limit, :per_page
+
+      def initialize(model_class, conditions: {}, loader: nil, total_limit: nil, per_page: DEFAULT_PER_PAGE)
+        @model_class = model_class
+        @conditions = conditions
+        @loader = loader
+        @total_limit = total_limit
+        @per_page = [per_page, ActiveShopifyGraphQL.configuration.max_objects_per_paginated_query].min
+        @loaded = false
+        @records = nil
+      end
+
+      # Set a limit on total records to return
+      # @param count [Integer] Maximum number of records to fetch across all pages
+      # @return [Scope] A new scope with the limit applied
+      def limit(count)
+        dup_with(total_limit: count)
+      end
+
+      # Configure pagination and optionally iterate through pages
+      # @param of [Integer] Number of records per page (default: 250, max: 250)
+      # @yield [PaginatedResult] Each page of results
+      # @return [PaginatedResult, self] Returns PaginatedResult if no block given
+      def in_pages(of: DEFAULT_PER_PAGE, &block)
+        page_size = [of, ActiveShopifyGraphQL.configuration.max_objects_per_paginated_query].min
+        scoped = dup_with(per_page: page_size)
+
+        if block_given?
+          scoped.each_page(&block)
+          self
+        else
+          scoped.fetch_first_page
+        end
+      end
+
+      # Iterate through all pages, yielding each page
+      # @yield [PaginatedResult] Each page of results
+      def each_page
+        current_page = fetch_first_page
+        records_yielded = 0
+
+        loop do
+          break if current_page.empty?
+
+          # Apply total limit if set
+          if @total_limit
+            remaining = @total_limit - records_yielded
+            break if remaining <= 0
+
+            if current_page.size > remaining
+              # Trim the page to fit the limit
+              trimmed_records = current_page.records.first(remaining)
+              current_page = Response::PaginatedResult.new(
+                records: trimmed_records,
+                page_info: Response::PageInfo.new, # Empty page info to stop pagination
+                query_scope: self
+              )
+            end
+          end
+
+          yield current_page
+          records_yielded += current_page.size
+
+          break unless current_page.has_next_page?
+          break if @total_limit && records_yielded >= @total_limit
+
+          current_page = current_page.next_page
+        end
+      end
+
+      # Iterate through all records across all pages
+      # @yield [Object] Each record
+      def each(&block)
+        return to_enum(:each) unless block_given?
+
+        each_page do |page|
+          page.each(&block)
+        end
+      end
+
+      # Load all records respecting total_limit
+      # @return [Array] All records
+      def to_a
+        return @records if @loaded
+
+        all_records = []
+        each_page do |page|
+          all_records.concat(page.to_a)
+        end
+        @records = all_records
+        @loaded = true
+        @records
+      end
+      alias load to_a
+
+      # Get first record
+      # @param count [Integer, nil] Number of records to return
+      # @return [Object, Array, nil] First record(s) or nil
+      def first(count = nil)
+        if count
+          scoped = dup_with(total_limit: count, per_page: [count, max_objects_per_paginated_query].min)
+          scoped.to_a
+        else
+          scoped = dup_with(total_limit: 1, per_page: 1)
+          scoped.to_a.first
+        end
+      end
+
+      # Check if any records exist
+      # @return [Boolean]
+      def exists?
+        first(1).any?
+      end
+
+      # Check if no records exist (Array compatibility)
+      # @return [Boolean]
+      def empty?
+        first(1).empty?
+      end
+
+      # Size/length of records (loads all pages, use with caution)
+      # @return [Integer]
+      def size
+        to_a.size
+      end
+      alias length size
+
+      # Count records (loads all pages, use with caution)
+      # @return [Integer]
+      def count
+        to_a.count
+      end
+
+      # Array-like access
+      def [](index)
+        to_a[index]
+      end
+
+      # Map over records (Array compatibility)
+      def map(&block)
+        to_a.map(&block)
+      end
+
+      # Select/filter records (Array compatibility)
+      def select_records(&block)
+        to_a.select(&block)
+      end
+
+      # Fetch a specific page by cursor
+      # @param after [String, nil] Cursor to fetch records after
+      # @param before [String, nil] Cursor to fetch records before
+      # @return [PaginatedResult]
+      def fetch_page(after: nil, before: nil)
+        loader.load_paginated_collection(
+          conditions: @conditions,
+          per_page: effective_per_page,
+          after: after,
+          before: before,
+          query_scope: self
+        )
+      end
+
+      # Fetch the first page of results
+      # @return [PaginatedResult]
+      def fetch_first_page
+        fetch_page
+      end
+
+      private
+
+      # Calculate effective per_page considering total_limit
+      def effective_per_page
+        if @total_limit && @total_limit < @per_page
+          @total_limit
+        else
+          @per_page
+        end
+      end
+
+      def loader
+        @loader ||= @model_class.default_loader
+      end
+
+      def dup_with(**changes)
+        Scope.new(
+          @model_class,
+          conditions: changes.fetch(:conditions, @conditions),
+          loader: changes.fetch(:loader, @loader),
+          total_limit: changes.fetch(:total_limit, @total_limit),
+          per_page: changes.fetch(:per_page, @per_page)
+        )
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/response/page_info.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Response
+    # Holds pagination metadata returned from a Shopify GraphQL connection query.
+    # Provides methods for navigating between pages.
+    class PageInfo
+      attr_reader :start_cursor, :end_cursor
+
+      def initialize(data = {})
+        @has_next_page = data["hasNextPage"] || false
+        @has_previous_page = data["hasPreviousPage"] || false
+        @start_cursor = data["startCursor"]
+        @end_cursor = data["endCursor"]
+      end
+
+      def has_next_page?
+        @has_next_page
+      end
+
+      def has_previous_page?
+        @has_previous_page
+      end
+
+      # Check if this is an empty/null page info
+      def empty?
+        @start_cursor.nil? && @end_cursor.nil?
+      end
+
+      def to_h
+        {
+          has_next_page: @has_next_page,
+          has_previous_page: @has_previous_page,
+          start_cursor: @start_cursor,
+          end_cursor: @end_cursor
+        }
+      end
+    end
+  end
+end

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