active_shopify_graphql 0.4.0 → 0.5.0

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

data/lib/active_shopify_graphql/model/graphql_type_resolver.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::GraphqlTypeResolver
+  # Centralizes GraphQL type resolution logic.
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Set or get the base GraphQL type for this model.
+    #
+    # @param type [String, nil] The GraphQL type name to set, or nil to get
+    # @return [String] The GraphQL type name
+    # @raise [NotImplementedError] If no type is defined
+    def graphql_type(type = nil)
+      if type
+        if @current_loader_context
+          @loader_graphql_types ||= {}
+          @loader_graphql_types[@current_loader_context] = type
+        else
+          @base_graphql_type = type
+        end
+      end
+
+      @base_graphql_type || raise(NotImplementedError, "#{self} must define graphql_type")
+    end
+
+    # Get the GraphQL type for a specific loader class.
+    # Resolution order:
+    #   1. Loader-specific type defined via `for_loader`
+    #   2. Base graphql_type defined on the model
+    #   3. Type defined on the loader class itself
+    #   4. Inferred from model class name
+    #
+    # @param loader_class [Class] The loader class to resolve type for
+    # @return [String] The resolved GraphQL type
+    # @raise [NotImplementedError] If no type can be resolved
+    def graphql_type_for_loader(loader_class)
+      # 1. Check loader-specific override
+      return @loader_graphql_types[loader_class] if @loader_graphql_types&.key?(loader_class)
+
+      # 2. Check base graphql_type
+      return @base_graphql_type if @base_graphql_type
+
+      # 3. Check loader class itself
+      loader_type = loader_class.instance_variable_get(:@graphql_type)
+      return loader_type if loader_type
+
+      # 4. Infer from model name
+      return name.demodulize if respond_to?(:name) && name
+
+      raise NotImplementedError,
+            "#{self} must define graphql_type or #{loader_class} must define graphql_type"
+    end
+
+    # Resolve the GraphQL type from any source (model class, loader, or value).
+    # Useful for external callers that need to resolve type from various inputs.
+    #
+    # @param model_class [Class, nil] The model class
+    # @param loader_class [Class, nil] The loader class
+    # @return [String] The resolved GraphQL type
+    def resolve_graphql_type(model_class: nil, loader_class: nil)
+      if model_class.respond_to?(:graphql_type_for_loader) && loader_class
+        model_class.graphql_type_for_loader(loader_class)
+      elsif model_class.respond_to?(:graphql_type)
+        model_class.graphql_type
+      elsif loader_class.respond_to?(:graphql_type)
+        loader_class.graphql_type
+      elsif model_class.respond_to?(:name) && model_class.name
+        model_class.name.demodulize
+      else
+        raise ArgumentError, "Cannot resolve graphql_type from provided arguments"
+      end
+    end
+  end
+
+  # Module-level resolver for convenience
+  def self.resolve(model_class: nil, loader_class: nil)
+    if model_class.respond_to?(:graphql_type_for_loader) && loader_class
+      model_class.graphql_type_for_loader(loader_class)
+    elsif model_class.respond_to?(:graphql_type)
+      model_class.graphql_type
+    elsif loader_class.respond_to?(:graphql_type)
+      loader_class.graphql_type
+    elsif model_class.respond_to?(:name) && model_class.name
+      model_class.name.demodulize
+    else
+      raise ArgumentError, "Cannot resolve graphql_type"
+    end
+  end
+end

data/lib/active_shopify_graphql/model/loader_switchable.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::LoaderSwitchable
+  # Provides capability to switch between different loaders within the same model
+  extend ActiveSupport::Concern
+
+  # Generic method to execute with a specific loader
+  # @param loader_class [Class] The loader class to use
+  # @yield [Object] Block to execute with the loader
+  # @return [Object] Result of the block
+  def with_loader(loader_class, &_block)
+    old_loader = Thread.current[:active_shopify_graphql_loader]
+    Thread.current[:active_shopify_graphql_loader] = loader_class.new(self.class)
+
+    if block_given?
+      yield(self)
+    else
+      self
+    end
+  ensure
+    Thread.current[:active_shopify_graphql_loader] = old_loader
+  end
+
+  # Executes with the admin API loader
+  # @return [self]
+  def with_admin_api(&block)
+    with_loader(ActiveShopifyGraphQL::Loaders::AdminApiLoader, &block)
+  end
+
+  # Executes with the customer account API loader
+  # @return [self]
+  def with_customer_account_api(&block)
+    with_loader(ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader, &block)
+  end
+
+  class_methods do
+    # @!method use_loader(loader_class)
+    #   Sets the default loader class for this model.
+    #
+    #   @param loader_class [Class] The loader class to use as default
+    #   @example
+    #     class Customer < ActiveRecord::Base
+    #       use_loader ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader
+    #     end
+    def use_loader(loader_class)
+      @default_loader_class = loader_class
+    end
+
+    # Define loader-specific attribute and graphql_type overrides
+    # @param loader_class [Class] The loader class to override attributes for
+    def for_loader(loader_class, &block)
+      @current_loader_context = loader_class
+      @loader_contexts ||= {}
+      @loader_contexts[loader_class] ||= {}
+      instance_eval(&block) if block_given?
+      @current_loader_context = nil
+    end
+
+    # Class-level method to execute with admin API loader
+    # @return [LoaderProxy] Proxy object with find method
+    def with_admin_api
+      ActiveShopifyGraphQL::LoaderProxy.new(self, ActiveShopifyGraphQL::Loaders::AdminApiLoader.new(self))
+    end
+
+    # Class-level method to execute with customer account API loader
+    # @return [LoaderProxy] Proxy object with find method
+    def with_customer_account_api(token = nil)
+      ActiveShopifyGraphQL::LoaderProxy.new(self, ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader.new(self, token))
+    end
+
+    private
+
+    # Returns the default loader class (either set via DSL or inferred)
+    # @return [Class] The default loader class
+    def default_loader_class
+      @default_loader_class ||= ActiveShopifyGraphQL::Loaders::AdminApiLoader
+    end
+  end
+end

data/lib/active_shopify_graphql/model/metafield_attributes.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL::Model::MetafieldAttributes
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Define a metafield attribute for this model.
+    #
+    # @param name [Symbol] The Ruby attribute name
+    # @param namespace [String] The metafield namespace
+    # @param key [String] The metafield key
+    # @param type [Symbol] The type for coercion (:string, :integer, :float, :boolean, :datetime, :json)
+    # @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
+    def metafield_attribute(name, namespace:, key:, type: :string, null: true, default: nil, transform: nil)
+      @metafields ||= {}
+      @metafields[name] = { namespace: namespace, key: key, type: type }
+
+      # Build metafield config
+      alias_name = "#{infer_path(name)}Metafield"
+      value_field = type == :json ? 'jsonValue' : 'value'
+      path = "#{alias_name}.#{value_field}"
+
+      config = {
+        path: path,
+        type: type,
+        null: null,
+        default: default,
+        transform: transform,
+        is_metafield: true,
+        metafield_alias: alias_name,
+        metafield_namespace: namespace,
+        metafield_key: key
+      }
+
+      if @current_loader_context
+        @loader_contexts[@current_loader_context][name] = config
+      else
+        @base_attributes ||= {}
+        @base_attributes[name] = config
+      end
+
+      attr_accessor name unless method_defined?(name) || method_defined?("#{name}=")
+    end
+
+    # Get metafields defined for this model
+    def metafields
+      @metafields || {}
+    end
+
+    private
+
+    # Infer GraphQL path from Ruby attribute name (delegates to Attributes if available)
+    def infer_path(name)
+      name.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+    end
+  end
+end

data/lib/active_shopify_graphql/{base.rb → model.rb}

@@ -1,25 +1,39 @@
 # frozen_string_literal: true
 
 module ActiveShopifyGraphQL
-  module Base
-    extend ActiveSupport::Concern
+  # Base class for all GraphQL-backed models.
+  #
+  # Models should inherit from this class (typically via an ApplicationShopifyGqlRecord
+  # intermediate class) to gain ActiveRecord-like functionality for Shopify GraphQL APIs.
+  #
+  # @example Creating an ApplicationShopifyGqlRecord base class
+  #   class ApplicationShopifyGqlRecord < ActiveShopifyGraphQL::Model
+  #     attribute :id, transform: ->(id) { id.split("/").last }
+  #     attribute :gid, path: "id"
+  #   end
+  #
+  # @example Defining a model
+  #   class Customer < ApplicationShopifyGqlRecord
+  #     graphql_type "Customer"
+  #
+  #     attribute :first_name
+  #     attribute :email, path: "defaultEmailAddress.emailAddress"
+  #   end
+  #
+  class Model
+    include ActiveModel::AttributeAssignment
+    include ActiveModel::Validations
+    extend ActiveModel::Naming
 
-    included do
-      include ActiveModel::AttributeAssignment
-      include ActiveModel::Validations
-      extend ActiveModel::Naming
-      include ActiveShopifyGraphQL::GraphqlTypeResolver
-      include ActiveShopifyGraphQL::FinderMethods
-      include ActiveShopifyGraphQL::Associations
-      include ActiveShopifyGraphQL::Connections
-      include ActiveShopifyGraphQL::Attributes
-      include ActiveShopifyGraphQL::MetafieldAttributes
-      include ActiveShopifyGraphQL::LoaderSwitchable
-    end
+    include GraphqlTypeResolver
+    include FinderMethods
+    include Associations
+    include Connections
+    include Attributes
+    include MetafieldAttributes
+    include LoaderSwitchable
 
     def initialize(attributes = {})
-      super()
-
       # Extract connection cache if present and populate inverse caches
       if attributes.key?(:_connection_cache)
         @_connection_cache = attributes.delete(:_connection_cache)