active_shopify_graphql 0.4.0 → 0.5.0

data/lib/active_shopify_graphql/query/query_builder.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    # Builds complete GraphQL queries from a LoaderContext.
+    # Handles both fragment construction and query wrapping.
+    # Delegates rendering to polymorphic Node subclasses.
+    class QueryBuilder
+      attr_reader :context
+
+      def initialize(context)
+        @context = context
+      end
+
+      # === Class-level factory methods for building complete queries ===
+
+      def self.build_single_record_query(context)
+        builder = new(context)
+        fragment = builder.build_fragment
+
+        Node::SingleRecord.new(
+          model_type: context.graphql_type,
+          query_name: context.query_name,
+          fragment_name: context.fragment_name,
+          fragments: [fragment]
+        ).to_s
+      end
+
+      # Build a query that doesn't require an ID parameter (e.g., Customer Account API's current customer)
+      def self.build_current_customer_query(context, query_name: nil)
+        builder = new(context)
+        fragment = builder.build_fragment
+
+        Node::CurrentCustomer.new(
+          model_type: context.graphql_type,
+          query_name: query_name || context.query_name,
+          fragment_name: context.fragment_name,
+          fragments: [fragment]
+        ).to_s
+      end
+
+      def self.build_collection_query(context, query_name:, variables:, include_page_info: false)
+        builder = new(context)
+        fragment = builder.build_fragment
+
+        Node::Collection.new(
+          model_type: context.graphql_type,
+          query_name: query_name,
+          fragment_name: context.fragment_name,
+          variables: variables,
+          fragments: [fragment],
+          include_page_info: include_page_info
+        ).to_s
+      end
+
+      # Build a paginated collection query that includes pageInfo for cursor-based pagination
+      def self.build_paginated_collection_query(context, query_name:, variables:)
+        build_collection_query(context, query_name: query_name, variables: variables, include_page_info: true)
+      end
+
+      def self.build_connection_query(context, query_name:, variables:, parent_query: nil, singular: false)
+        builder = new(context)
+        fragment = builder.build_fragment
+
+        if parent_query
+          Node::NestedConnection.new(
+            query_name: query_name,
+            fragment_name: context.fragment_name,
+            variables: variables,
+            parent_query: parent_query,
+            fragments: [fragment],
+            singular: singular
+          ).to_s
+        else
+          Node::RootConnection.new(
+            query_name: query_name,
+            fragment_name: context.fragment_name,
+            variables: variables,
+            fragments: [fragment],
+            singular: singular
+          ).to_s
+        end
+      end
+
+      def self.normalize_includes(includes)
+        includes = Array(includes)
+        includes.each_with_object({}) do |inc, normalized|
+          case inc
+          when Hash
+            inc.each do |key, value|
+              key = key.to_sym
+              normalized[key] ||= []
+              case value
+              when Hash then normalized[key] << value
+              when Array then normalized[key].concat(value)
+              else normalized[key] << value
+              end
+            end
+          when Symbol, String
+            normalized[inc.to_sym] ||= []
+          end
+        end
+      end
+
+      def self.fragment_name(graphql_type)
+        "#{graphql_type}Fragment"
+      end
+
+      # === Instance methods for building fragments ===
+
+      # Build a complete fragment node with all fields and connections
+      def build_fragment
+        raise NotImplementedError, "#{@context.loader_class} must define attributes" if @context.defined_attributes.empty?
+
+        fragment_node = Node::Fragment.new(
+          name: @context.fragment_name,
+          arguments: { on: @context.graphql_type }
+        )
+
+        # Add field nodes from attributes
+        build_field_nodes.each { |node| fragment_node.add_child(node) }
+
+        # Add connection nodes
+        build_connection_nodes.each { |node| fragment_node.add_child(node) }
+
+        fragment_node
+      end
+
+      # Build field nodes from attribute definitions
+      def build_field_nodes
+        path_tree = {}
+        metafield_aliases = {}
+        raw_graphql_nodes = []
+        aliased_field_nodes = []
+
+        # Build a tree structure for nested paths
+        @context.defined_attributes.each do |attr_name, config|
+          if config[:raw_graphql]
+            raw_graphql_nodes << build_raw_graphql_node(attr_name, config[:raw_graphql])
+          elsif config[:is_metafield]
+            store_metafield_config(metafield_aliases, config)
+          else
+            path = config[:path]
+            if path.include?('.')
+              # Nested path - use tree structure (shared prefixes)
+              build_path_tree(path_tree, path)
+            else
+              # Simple path - add aliased field node
+              aliased_field_nodes << build_aliased_field_node(attr_name, path)
+            end
+          end
+        end
+
+        # Convert tree to Node objects
+        nodes_from_tree(path_tree) + aliased_field_nodes + metafield_nodes(metafield_aliases) + raw_graphql_nodes
+      end
+
+      # Build Node objects for all connections
+      def build_connection_nodes
+        return [] if @context.included_connections.empty?
+
+        connections = @context.connections
+        return [] if connections.empty?
+
+        normalized_includes = self.class.normalize_includes(@context.included_connections)
+
+        normalized_includes.filter_map do |connection_name, nested_includes|
+          connection_config = connections[connection_name]
+          next unless connection_config
+
+          build_connection_node(connection_config, nested_includes)
+        end
+      end
+
+      private
+
+      def store_metafield_config(metafield_aliases, config)
+        alias_name = config[:metafield_alias]
+        value_field = config[:type] == :json ? 'jsonValue' : 'value'
+
+        metafield_aliases[alias_name] = {
+          namespace: config[:metafield_namespace],
+          key: config[:metafield_key],
+          value_field: value_field
+        }
+      end
+
+      def build_raw_graphql_node(attr_name, raw_graphql)
+        # Prepend alias to raw GraphQL for predictable response mapping
+        aliased_raw_graphql = "#{attr_name}: #{raw_graphql}"
+        Node::Raw.new(
+          name: "raw",
+          arguments: { raw_graphql: aliased_raw_graphql }
+        )
+      end
+
+      def build_aliased_field_node(attr_name, path)
+        alias_name = attr_name.to_s
+        # Only add alias if the attr_name differs from the GraphQL field name
+        alias_name = nil if alias_name == path
+        Node::Field.new(name: path, alias_name: alias_name)
+      end
+
+      def build_path_tree(path_tree, path)
+        path_parts = path.split('.')
+        current_level = path_tree
+
+        path_parts.each_with_index do |part, index|
+          if index == path_parts.length - 1
+            current_level[part] = true
+          else
+            current_level[part] ||= {}
+            current_level = current_level[part]
+          end
+        end
+      end
+
+      def nodes_from_tree(tree)
+        tree.map do |key, value|
+          if value == true
+            Node::Field.new(name: key)
+          else
+            children = nodes_from_tree(value)
+            Node::Field.new(name: key, children: children)
+          end
+        end
+      end
+
+      def metafield_nodes(metafield_aliases)
+        metafield_aliases.map do |alias_name, config|
+          value_node = Node::Field.new(name: config[:value_field])
+          Node::Field.new(
+            name: "metafield",
+            alias_name: alias_name,
+            arguments: { namespace: config[:namespace], key: config[:key] },
+            children: [value_node]
+          )
+        end
+      end
+
+      def build_connection_node(connection_config, nested_includes)
+        target_class = connection_config[:class_name].constantize
+        target_context = @context.for_model(target_class, new_connections: nested_includes)
+
+        # Build child nodes for the target model
+        child_nodes = build_target_field_nodes(target_context, nested_includes)
+
+        query_name = connection_config[:query_name]
+        original_name = connection_config[:original_name]
+        connection_type = connection_config[:type] || :connection
+        formatted_args = (connection_config[:default_arguments] || {}).transform_keys(&:to_sym)
+
+        # Add alias if the connection name differs from the query name
+        alias_name = original_name.to_s == query_name ? nil : original_name.to_s
+
+        if connection_type == :singular
+          Node::Singular.new(
+            name: query_name,
+            alias_name: alias_name,
+            arguments: formatted_args,
+            children: child_nodes
+          )
+        else
+          Node::Connection.new(
+            name: query_name,
+            alias_name: alias_name,
+            arguments: formatted_args,
+            children: child_nodes
+          )
+        end
+      end
+
+      def build_target_field_nodes(target_context, nested_includes)
+        # Build attribute nodes
+        attribute_nodes = if target_context.defined_attributes.any?
+                            QueryBuilder.new(target_context.for_model(target_context.model_class, new_connections: [])).build_field_nodes
+                          else
+                            [Node::Field.new(name: "id")]
+                          end
+
+        # Build nested connection nodes
+        return attribute_nodes if nested_includes.empty?
+
+        nested_builder = QueryBuilder.new(target_context)
+        nested_connection_nodes = nested_builder.build_connection_nodes
+        attribute_nodes + nested_connection_nodes
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/query/relation.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Query
+    # A unified query builder that encapsulates all query configuration.
+    # This class provides a consistent interface for chaining operations like
+    # `where`, `find_by`, `includes`, `select`, `limit`, and pagination.
+    #
+    # Inspired by ActiveRecord::Relation, this class accumulates query state
+    # and executes the query when records are accessed.
+    #
+    # @example Basic usage
+    #   Customer.where(email: "john@example.com").first
+    #   Customer.includes(:orders).find_by(id: 123)
+    #   Customer.select(:id, :email).where(first_name: "John").limit(10).to_a
+    #
+    # @example Pagination
+    #   Customer.where(country: "Canada").in_pages(of: 50) do |page|
+    #     page.each { |customer| process(customer) }
+    #   end
+    class Relation
+      include Enumerable
+
+      DEFAULT_PER_PAGE = 250
+
+      attr_reader :model_class, :included_connections, :conditions, :total_limit, :per_page
+
+      def initialize(
+        model_class,
+        conditions: {},
+        included_connections: [],
+        selected_attributes: nil,
+        total_limit: nil,
+        per_page: DEFAULT_PER_PAGE,
+        loader_class: nil,
+        loader_extra_args: []
+      )
+        @model_class = model_class
+        @conditions = conditions
+        @included_connections = included_connections
+        @selected_attributes = selected_attributes
+        @total_limit = total_limit
+        @per_page = [per_page, ActiveShopifyGraphQL.configuration.max_objects_per_paginated_query].min
+        @loader_class = loader_class
+        @loader_extra_args = loader_extra_args
+        @loaded = false
+        @records = nil
+      end
+
+      # --------------------------------------------------------------------------
+      # Chainable Query Methods
+      # --------------------------------------------------------------------------
+
+      # Add conditions to the query
+      # @param conditions_or_first_condition [Hash, String] Conditions to filter by
+      # @return [Relation] A new relation with conditions applied
+      # @raise [ArgumentError] If where is called on a relation that already has conditions
+      def where(conditions_or_first_condition = {}, *args, **options)
+        new_conditions = build_conditions(conditions_or_first_condition, args, options)
+
+        if has_conditions? && !new_conditions.empty?
+          raise ArgumentError, "Chaining multiple where clauses is not supported. " \
+                               "Combine conditions in a single where call instead."
+        end
+
+        spawn(conditions: new_conditions)
+      end
+
+      # Find a single record by conditions
+      # @param conditions [Hash] The conditions to match
+      # @return [Object, nil] The first matching record or nil
+      def find_by(conditions = {}, **options)
+        merged = conditions.empty? ? options : conditions
+        where(merged).first
+      end
+
+      # Find a single record by ID
+      # @param id [String, Integer] The record ID
+      # @return [Object] The model instance
+      # @raise [ObjectNotFoundError] If the record is not found
+      def find(id)
+        gid = GidHelper.normalize_gid(id, @model_class.model_name.name.demodulize)
+        attributes = loader.load_attributes(gid)
+
+        raise ObjectNotFoundError, "Couldn't find #{@model_class.name} with id=#{id}" if attributes.nil?
+
+        ModelBuilder.build(@model_class, attributes)
+      end
+
+      # Include connections for eager loading
+      # @param connection_names [Array<Symbol>] Connection names to include
+      # @return [Relation] A new relation with connections included
+      def includes(*connection_names)
+        validate_includes_connections!(connection_names)
+
+        # Merge with existing and auto-eager-loaded connections
+        auto_included = @model_class.connections
+                                    .select { |_name, config| config[:eager_load] }
+                                    .keys
+
+        all_connections = (@included_connections + connection_names + auto_included).uniq
+
+        spawn(included_connections: all_connections)
+      end
+
+      # Select specific attributes to optimize the query
+      # @param attributes [Array<Symbol>] Attributes to select
+      # @return [Relation] A new relation with selected attributes
+      def select(*attributes)
+        attrs = Array(attributes).flatten.map(&:to_sym)
+        validate_select_attributes!(attrs)
+
+        spawn(selected_attributes: attrs)
+      end
+
+      # Limit the total number of records returned
+      # @param count [Integer] Maximum records to return
+      # @return [Relation] A new relation with limit applied
+      def limit(count)
+        spawn(total_limit: count)
+      end
+
+      # --------------------------------------------------------------------------
+      # Pagination Methods
+      # --------------------------------------------------------------------------
+
+      # Configure pagination and optionally iterate through pages
+      # @param of [Integer] Records per page (default: 250, max: configurable)
+      # @yield [PaginatedResult] Each page of results
+      # @return [PaginatedResult, self] 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 = spawn(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
+              trimmed_records = current_page.records.first(remaining)
+              current_page = PaginatedResult.new(
+                records: trimmed_records,
+                page_info: PageInfo.new,
+                query_scope: build_query_scope_for_pagination
+              )
+            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
+
+      # --------------------------------------------------------------------------
+      # Enumerable / Loading Methods
+      # --------------------------------------------------------------------------
+
+      # 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(s)
+      # @param count [Integer, nil] Number of records to return
+      # @return [Object, Array, nil] First record(s) or nil
+      def first(count = nil)
+        if count
+          spawn(total_limit: count, per_page: [count, ActiveShopifyGraphQL.configuration.max_objects_per_paginated_query].min).to_a
+        else
+          spawn(total_limit: 1, per_page: 1).to_a.first
+        end
+      end
+
+      # Check if any records exist
+      # @return [Boolean]
+      def exists?
+        first(1).any?
+      end
+
+      # Check if no records exist
+      # @return [Boolean]
+      def empty?
+        first(1).empty?
+      end
+
+      # Size/length of records (loads all pages)
+      # @return [Integer]
+      def size
+        to_a.size
+      end
+      alias length size
+
+      # Count records (loads all pages)
+      # @return [Integer]
+      def count
+        to_a.count
+      end
+
+      # Array-like access
+      def [](index)
+        to_a[index]
+      end
+
+      # Map over records
+      def map(&block)
+        to_a.map(&block)
+      end
+
+      # Select/filter records (Array compatibility - differs from query select)
+      def select_records(&block)
+        to_a.select(&block)
+      end
+
+      # --------------------------------------------------------------------------
+      # Inspection
+      # --------------------------------------------------------------------------
+
+      def inspect
+        parts = [@model_class.name]
+        parts << "includes(#{@included_connections.join(', ')})" if @included_connections.any?
+        parts << "select(#{@selected_attributes.join(', ')})" if @selected_attributes
+        parts << "where(#{@conditions.inspect})" unless @conditions.empty?
+        parts << "limit(#{@total_limit})" if @total_limit
+        "#<#{self.class.name} #{parts.join('.')}>"
+      end
+
+      # --------------------------------------------------------------------------
+      # Internal State Accessors (for compatibility)
+      # --------------------------------------------------------------------------
+
+      def has_included_connections?
+        @included_connections.any?
+      end
+
+      # --------------------------------------------------------------------------
+      # Pagination Support
+      # --------------------------------------------------------------------------
+
+      # 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: build_query_scope_for_pagination
+        )
+      end
+
+      # Fetch the first page of results
+      # @return [PaginatedResult]
+      def fetch_first_page
+        fetch_page
+      end
+
+      private
+
+      # Create a new Relation with modified options
+      def spawn(**changes)
+        Query::Relation.new(
+          @model_class,
+          conditions: changes.fetch(:conditions, @conditions),
+          included_connections: changes.fetch(:included_connections, @included_connections),
+          selected_attributes: changes.fetch(:selected_attributes, @selected_attributes),
+          total_limit: changes.fetch(:total_limit, @total_limit),
+          per_page: changes.fetch(:per_page, @per_page),
+          loader_class: changes.fetch(:loader_class, @loader_class),
+          loader_extra_args: changes.fetch(:loader_extra_args, @loader_extra_args)
+        )
+      end
+
+      def loader
+        @loader ||= build_loader
+      end
+
+      def has_conditions?
+        case @conditions
+        when Hash then @conditions.any?
+        when String then !@conditions.empty?
+        when Array then @conditions.any?
+        else false
+        end
+      end
+
+      def build_loader
+        klass = @loader_class || @model_class.send(:default_loader_class)
+
+        klass.new(
+          @model_class,
+          *@loader_extra_args,
+          selected_attributes: @selected_attributes,
+          included_connections: @included_connections
+        )
+      end
+
+      def effective_per_page
+        if @total_limit && @total_limit < @per_page
+          @total_limit
+        else
+          @per_page
+        end
+      end
+
+      # Build conditions from various input formats:
+      # - Hash: where(email: "test") => {email: "test"}
+      # - String with positional params: where("sku:?", "ABC") => ["sku:?", "ABC"]
+      # - String with named params: where("sku::sku", sku: "ABC") => ["sku::sku", {sku: "ABC"}]
+      def build_conditions(conditions_or_first_condition, args, options)
+        case conditions_or_first_condition
+        when String
+          if args.any?
+            [conditions_or_first_condition, *args]
+          elsif options.any?
+            [conditions_or_first_condition, options]
+          else
+            conditions_or_first_condition
+          end
+        when Hash
+          conditions_or_first_condition.empty? ? options : conditions_or_first_condition
+        else
+          options
+        end
+      end
+
+      # Build a Query::Scope for backward compatibility with PaginatedResult
+      def build_query_scope_for_pagination
+        Query::Scope.new(
+          @model_class,
+          conditions: @conditions,
+          loader: loader,
+          total_limit: @total_limit,
+          per_page: @per_page
+        )
+      end
+
+      def validate_includes_connections!(connection_names)
+        return unless @model_class.respond_to?(:connections)
+
+        available = @model_class.connections.keys
+        connection_names.each do |name|
+          if name.is_a?(Hash)
+            # Nested includes: { line_items: :variant }
+            name.each_key do |key|
+              next if available.include?(key.to_sym)
+
+              raise ArgumentError, "Invalid connection for #{@model_class.name}: #{key}. " \
+                                   "Available connections: #{available.join(', ')}"
+            end
+          else
+            next if available.include?(name.to_sym)
+
+            raise ArgumentError, "Invalid connection for #{@model_class.name}: #{name}. " \
+                                 "Available connections: #{available.join(', ')}"
+          end
+        end
+      end
+
+      def validate_select_attributes!(attributes)
+        return if attributes.empty?
+
+        available = available_select_attributes
+        invalid = attributes - available
+        return if invalid.empty?
+
+        raise ArgumentError, "Invalid attributes for #{@model_class.name}: #{invalid.join(', ')}. " \
+                             "Available attributes are: #{available.join(', ')}"
+      end
+
+      def available_select_attributes
+        loader_klass = @loader_class || @model_class.send(:default_loader_class)
+        model_attrs = @model_class.attributes_for_loader(loader_klass)
+        return [] unless model_attrs
+
+        model_attrs.keys.map(&:to_sym).uniq.sort
+      end
+    end
+  end
+end