active_shopify_graphql 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f8f9c57e3dd7f5371ace9fb8d3db79d796a0aa34890065d4727ae7a45a0723b
-  data.tar.gz: 16d8e5361a00e4aaa2b166ba8108496a8564e669fc16c76e68e4ed058df12a23
+  metadata.gz: 6e4003c2f9180531bc4c3a08e9c921d16402642c60c45c777ac49726b5a6a3f2
+  data.tar.gz: df5619e4f4845d688cdd1beb5228047d52022eca04e3b1c3479265ed1b59d9c1
 SHA512:
-  metadata.gz: c30453eafcf98bc563f309e2a5762373615ad9a23c0b8d0c6e3c0919e5e8490088974d0d187582e6a55b0d012d4cc2e9c3abcc77cb2c638bd4acd8098be1b032
-  data.tar.gz: 1b190403f8fcdee4d69d35b534c168b63200a87aca06a6cbf465ea09dc873b3d723597e3f99201acbd8e0d4ed9618897af028dbcf73653be891391cc6d383d23
+  metadata.gz: d95bac2e81df933e3f3bbfbef55c486e2ba719271a93283b7e8fca72684a43208f0479be44286bd6ee99e9de427cdbdf44378aa20feb2c5895e3908ad112ab8d
+  data.tar.gz: f87d6688ac0374fb4821da10928b13127f8c272d090978646026dbf84adfc210039e8690e348cd570b48c28608a43252e998e5dea7dc527a193bc67e97d96440

data/.rubocop.yml

@@ -1,3 +1,6 @@
+AllCops:
+  NewCops: enable
+
 Style/StringLiterals:
   Enabled: false
 
@@ -48,3 +51,15 @@ Naming/MethodParameterName:
 
 Naming/AccessorMethodName:
   Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/KeywordArgumentsMerging:
+  Enabled: false
+
+Naming/BlockForwarding:
+  Enabled: false
+
+Lint/DuplicateBranch:
+  Enabled: false

data/AGENTS.md

@@ -31,6 +31,7 @@
 
 ## Testing Guidelines
 - Framework: RSpec with documentation formatter (`.rspec`).
+- Before stubbing classes look in `model_factories.rb` for existing ones.
 - Place specs under `spec/` and name files `*_spec.rb` matching the class/module under test.
 - Do not use `let` or `before` blocks in specs; each test case should tell a complete story.
 - Use verifying doubles instead of normal doubles. Prefer `{instance|class}_{double|spy}` to `double` or `spy`

data/README.md

@@ -42,7 +42,7 @@ Rails.configuration.to_prepare do
     config.admin_api_client = ShopifyGraphQL::Client
 
     # Configure the Customer Account API client class (must have .from_config(token) class method)
-    # and reponsd to #execute(query, **variables)
+    # and respond to #execute(query, **variables)
     config.customer_account_client_class = Shopify::Account::Client
   end
 end
@@ -143,6 +143,33 @@ end
 
 The metafield attributes automatically generate the correct GraphQL syntax and handle value extraction from either `value` or `jsonValue` fields based on the type.
 
+#### Raw GraphQL Attributes
+
+For advanced GraphQL features not yet fully supported by the gem (like union types with `... on` syntax), you can inject raw GraphQL directly into the query using the `raw_graphql` option:
+
+```ruby
+class Product
+  include ActiveShopifyGraphQL::Base
+
+  graphql_type "Product"
+
+  attribute :id, type: :string
+  attribute :title, type: :string
+
+  # Raw GraphQL for accessing metaobject references with union types
+  attribute :provider_id,
+    path: "roaster.reference.id",  # Path to extract from the response
+    type: :string,
+    raw_graphql: 'metafield(namespace: "custom", key: "provider") { reference { ... on Metaobject { id } } }'
+
+  # Another example with complex nested queries not warranting full blown models
+  attribute :product_bundle,
+    path: "bundle",  # The alias will be used as the response key
+    type: :json,
+    raw_graphql: 'metafield(namespace: "bundles", key: "items") { references(first: 10) { edges { node { ... on Product { id title } } } } }'
+end
+```
+
 #### API-Specific Attributes
 
 For models that need different attributes depending on the API being used, you can define loader-specific overrides:
@@ -198,7 +225,7 @@ customer = Customer.with_customer_account_api(token).find
 # Use Admin API explicitly
 customer = Customer.with_admin_api.find(id)
 
-# Use you own custom Loader
+# Use your own custom Loader
 customer = Customer.with_loader(MyCustomLoader).find(id)
 ```
 
@@ -264,7 +291,7 @@ class Customer
   # Define an association to one of your own ActiveRecord models
   # foreign_key maps the id of the GraphQL powered model to the rewards.shopify_customer_id table
   has_many :rewards, foreign_key: :shopify_customer_id
-  # primary_key specifies which attribute use as the value for matching the ActiveRecord ID
+  # primary_key specifies which attribute to use as the value for matching the ActiveRecord ID
   has_many :referrals, primary_key: :plain_id, foreign_key: :shopify_id
 
   validates :id, presence: true
@@ -298,7 +325,7 @@ The associations automatically handle Shopify GID format conversion, extracting
 
 ## GraphQL Connections
 
-ActiveShopifyGraphQL supports GraphQL connections for loading related data from Shopify APIs. Connections provide both lazy and eager loading patterns with cursor-based pagination support.
+ActiveShopifyGraphQL supports GraphQL connections for loading related data from Shopify APIs. Connections provide both lazy and eager loading patterns.
 
 ### Defining Connections
 
@@ -329,12 +356,14 @@ class Customer
     }
 
   # Example of a "scoped" connection
+  # Multiple connections can use the same query_name with different arguments
   has_many_connected :recent_orders,
-    query_name: "orders",           # The query would be inferred to recentOrders() without this
-    class_name: "Shopify::Order",   # The class would be inferred to RecentOrder without this
-    default_arguments: {            # The arguments passed in the connection query
-      first: 2,
-      reverse: true
+    query_name: "orders",           # Uses the same GraphQL field as :orders
+    class_name: "Order",            # The class would be inferred to RecentOrder without this
+    default_arguments: {            # Different arguments for filtering
+      first: 5,
+      reverse: true,
+      sort_key: 'CREATED_AT'
     }
 end
 
@@ -349,6 +378,23 @@ class Order
 end
 ```
 
+**Connection Aliasing:** When multiple connections use the same `query_name` (like `orders` and `recent_orders` both using the "orders" field), the gem automatically generates GraphQL aliases to prevent conflicts:
+
+```graphql
+fragment CustomerFragment on Customer {
+  id
+  displayName
+  orders(first: 2) {
+    edges { node { id name } }
+  }
+  recent_orders: orders(first: 5, reverse: true, sortKey: CREATED_AT) {
+    edges { node { id name } }
+  }
+}
+```
+
+This allows you to have multiple "views" of the same connection with different filtering or sorting parameters, all in a single query.
+
 ### Lazy Loading (Default Behavior)
 
 Connections are loaded lazily when accessed. A separate GraphQL query is fired when the connection is first accessed:
@@ -505,6 +551,69 @@ expect(customer.orders.size).to eq(2)
 expect(customer.orders.first.name).to eq('#1001')
 ```
 
+### Inverse Relationships with `inverse_of`
+
+When you have bidirectional relationships between models, you can use the `inverse_of` parameter to avoid redundant GraphQL queries. This is similar to ActiveRecord's `inverse_of` option and automatically caches the parent object when loading children.
+
+#### Basic Usage
+
+```ruby
+class Product
+  include ActiveShopifyGraphQL::Base
+
+  graphql_type 'Product'
+
+  attribute :id
+  attribute :title
+
+  # Define inverse relationship to avoid redundant queries
+  has_many_connected :variants,
+    class_name: "ProductVariant",
+    inverse_of: :product,  # Points to the inverse connection name
+    default_arguments: { first: 10 }
+end
+
+class ProductVariant
+  include ActiveShopifyGraphQL::Base
+
+  graphql_type 'ProductVariant'
+
+  attribute :id
+  attribute :title
+
+  # Define inverse relationship back to Product
+  has_one_connected :product,
+    inverse_of: :variants  # Points back to the parent's connection
+end
+```
+
+#### With Eager Loading
+
+```ruby
+# Load product with variants in a single GraphQL query
+product = Product.includes(:variants).find(123)
+
+# Access variants - already loaded, no additional query
+product.variants.each do |variant|
+  # Access product from variant - uses cached parent, NO QUERY!
+  puts variant.product.title
+end
+```
+
+#### With Lazy Loading
+
+```ruby
+# Load product without preloading variants
+product = Product.find(123)
+
+# First access triggers a query to load variants
+variants = product.variants.to_a
+
+# Access product from variant - uses cached parent, NO QUERY!
+variant = variants.first
+puts variant.product.title  # Returns the same product instance
+```
+
 ### Connection Configuration
 
 Connections automatically infer sensible defaults but can be customized:
@@ -514,6 +623,7 @@ Connections automatically infer sensible defaults but can be customized:
 - **foreign_key**: Field used to filter connection records (defaults to `{model_name}_id`)
 - **loader_class**: Custom loader class (defaults to model's default loader)
 - **eager_load**: Whether to automatically eager load this connection on find/where queries (default: false)
+- **inverse_of**: The name of the inverse connection on the target model (optional, enables automatic inverse caching)
 - **default_arguments**: Hash of default arguments to pass to the GraphQL query (e.g., `{ first: 10, sort_key: 'CREATED_AT' }`)
 
 ### Error Handling
@@ -527,7 +637,7 @@ Connection queries use the same error handling as regular model queries. If a co
 - [x] Support `Model.where(param: value)` proxying params to the GraphQL query attribute
 - [x] Query optimization with `select` method
 - [x] GraphQL connections with lazy and eager loading via `Customer.includes(:orders).find(id)`
-- [ ] Support for paginating query results
+- [ ] Support for paginating query results with cursors
 - [ ] Better error handling and retry mechanisms for GraphQL API calls
 - [ ] Caching layer for frequently accessed data
 

data/lib/active_shopify_graphql/attributes.rb

@@ -13,9 +13,10 @@ module ActiveShopifyGraphQL
       # @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 attribute(name, path: nil, type: :string, null: true, default: nil, transform: nil)
+      # @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 }
+        config = { path: path, type: type, null: null, default: default, transform: transform, raw_graphql: raw_graphql }
 
         if @current_loader_context
           # Store in loader-specific context

data/lib/active_shopify_graphql/base.rb

@@ -20,10 +20,46 @@ module ActiveShopifyGraphQL
     def initialize(attributes = {})
       super()
 
-      # Extract connection cache if present
-      @_connection_cache = attributes.delete(:_connection_cache) if attributes.key?(:_connection_cache)
+      # Extract connection cache if present and populate inverse caches
+      if attributes.key?(:_connection_cache)
+        @_connection_cache = attributes.delete(:_connection_cache)
+        populate_inverse_caches_on_initialization
+      end
 
       assign_attributes(attributes)
     end
+
+    private
+
+    def populate_inverse_caches_on_initialization
+      return unless @_connection_cache
+
+      @_connection_cache.each do |connection_name, records|
+        connection_config = self.class.connections[connection_name]
+        next unless connection_config && connection_config[:inverse_of]
+
+        inverse_name = connection_config[:inverse_of]
+        records_array = Array(records).compact
+
+        records_array.each do |record|
+          next unless record.respond_to?(:instance_variable_set)
+
+          record.instance_variable_set(:@_connection_cache, {}) unless record.instance_variable_get(:@_connection_cache)
+          cache = record.instance_variable_get(:@_connection_cache)
+
+          # Determine the type of the inverse connection
+          next unless record.class.respond_to?(:connections) && record.class.connections[inverse_name]
+
+          inverse_type = record.class.connections[inverse_name][:type]
+          cache[inverse_name] =
+            if inverse_type == :singular
+              self
+            else
+              # For collection inverses, wrap parent in an array
+              [self]
+            end
+        end
+      end
+    end
   end
 end

data/lib/active_shopify_graphql/connection_loader.rb

@@ -33,7 +33,7 @@ module ActiveShopifyGraphQL
 
     def load_nested_connection(query_name, variables, parent, connection_config)
       parent_type = parent.class.graphql_type_for_loader(@context.loader_class)
-      parent_query_name = parent_type.downcase
+      parent_query_name = parent_type.camelize(:lower)
       connection_type = connection_config&.dig(:type) || :connection
 
       query = QueryTree.build_connection_query(

data/lib/active_shopify_graphql/connections/connection_proxy.rb

@@ -100,6 +100,9 @@ module ActiveShopifyGraphQL
           @connection_config
         ) || []
 
+        # Populate inverse cache if inverse_of is specified
+        populate_inverse_cache(@records, @connection_config, @parent)
+
         @loaded = true
       end
 
@@ -107,6 +110,35 @@ module ActiveShopifyGraphQL
         default_args = @connection_config[:default_arguments] || {}
         default_args.merge(@options).compact
       end
+
+      def populate_inverse_cache(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
   end
 end

data/lib/active_shopify_graphql/connections.rb

@@ -17,14 +17,14 @@ module ActiveShopifyGraphQL
     class_methods do
       # Define a singular connection (returns a single object)
       # @see #connection
-      def has_one_connected(name, **options)
-        connection(name, type: :singular, **options)
+      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 edges)
       # @see #connection
-      def has_many_connected(name, **options)
-        connection(name, type: :connection, **options)
+      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
@@ -36,7 +36,8 @@ module ActiveShopifyGraphQL
       # @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)
-      def connection(name, class_name: nil, query_name: nil, foreign_key: nil, loader_class: nil, eager_load: false, type: :connection, default_arguments: {})
+      # @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
 
@@ -56,9 +57,13 @@ module ActiveShopifyGraphQL
           nested: true, # Always treated as nested (accessed via parent field)
           target_class_name: connection_class_name,
           original_name: name,
-          default_arguments: default_arguments
+          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
@@ -74,6 +79,9 @@ module ActiveShopifyGraphQL
             # 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
@@ -123,30 +131,19 @@ module ActiveShopifyGraphQL
         # Merge manual and automatic connections
         all_included_connections = (connection_names + auto_included_connections).uniq
 
-        # Create a new class that inherits from self with eager loading enabled
-        included_class = Class.new(self)
-
-        # Store the connections to include
-        included_class.instance_variable_set(:@included_connections, all_included_connections)
-
-        # Override methods to use eager loading
-        included_class.define_singleton_method(:default_loader) do
-          @default_loader ||= superclass.default_loader.class.new(
-            superclass,
-            included_connections: @included_connections
-          )
-        end
-
-        # Preserve the original class name and model name for GraphQL operations
-        included_class.define_singleton_method(:name) { superclass.name }
-        included_class.define_singleton_method(:model_name) { superclass.model_name }
-        included_class.define_singleton_method(:connections) { superclass.connections }
-
-        included_class
+        # Create a scope object that holds the included connections
+        IncludesScope.new(self, all_included_connections)
       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)
@@ -166,5 +163,36 @@ module ActiveShopifyGraphQL
         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
 end

data/lib/active_shopify_graphql/finder_methods.rb

@@ -11,11 +11,16 @@ module ActiveShopifyGraphQL
       # @return [Object, nil] The model instance or nil if not found
       def find(id, loader: default_loader)
         gid = GidHelper.normalize_gid(id, model_name.name.demodulize)
-        attributes = loader.load_attributes(gid)
 
-        return nil if attributes.nil?
+        # If we have included connections, we need to handle inverse_of properly
+        if loader.respond_to?(:load_with_instance) && loader.has_included_connections?
+          loader.load_with_instance(gid, self)
+        else
+          attributes = loader.load_attributes(gid)
+          return nil if attributes.nil?
 
-        new(attributes)
+          new(attributes)
+        end
       end
 
       # Returns the default loader for this model's queries
@@ -130,7 +135,7 @@ module ActiveShopifyGraphQL
         return unless invalid_attrs.any?
 
         raise ArgumentError, "Invalid attributes for #{name}: #{invalid_attrs.join(', ')}. " \
-                           "Available attributes are: #{available_attrs.join(', ')}"
+                             "Available attributes are: #{available_attrs.join(', ')}"
       end
 
       # Gets all available attributes for selection

data/lib/active_shopify_graphql/fragment_builder.rb

@@ -30,18 +30,29 @@ module ActiveShopifyGraphQL
     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_value do |config|
-        if config[:is_metafield]
+      @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
-          build_path_tree(path_tree, config[:path])
+          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 QueryNode objects
-      nodes_from_tree(path_tree) + metafield_nodes(metafield_aliases)
+      nodes_from_tree(path_tree) + aliased_field_nodes + metafield_nodes(metafield_aliases) + raw_graphql_nodes
     end
 
     # Build QueryNode objects for all connections (protected for recursive calls)
@@ -74,6 +85,23 @@ module ActiveShopifyGraphQL
       }
     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}"
+      QueryNode.new(
+        name: "raw",
+        arguments: { raw_graphql: aliased_raw_graphql },
+        node_type: :raw
+      )
+    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
+      QueryNode.new(name: path, alias_name: alias_name, node_type: :field)
+    end
+
     def build_path_tree(path_tree, path)
       path_parts = path.split('.')
       current_level = path_tree
@@ -120,12 +148,17 @@ module ActiveShopifyGraphQL
       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
+
       node_type = connection_type == :singular ? :singular : :connection
       QueryNode.new(
         name: query_name,
+        alias_name: alias_name,
         arguments: formatted_args,
         node_type: node_type,
         children: child_nodes

data/lib/active_shopify_graphql/includes_scope.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # A scope object that holds included connections for eager loading.
+  # This allows chaining methods like find() and where() while maintaining
+  # the included connections configuration.
+  class IncludesScope
+    attr_reader :model_class, :included_connections
+
+    def initialize(model_class, included_connections)
+      @model_class = model_class
+      @included_connections = included_connections
+    end
+
+    # Delegate find to the model class with a custom loader
+    def find(id, loader: nil)
+      loader ||= default_loader
+      @model_class.find(id, loader: loader)
+    end
+
+    # Delegate where to the model class with a custom loader
+    def where(*args, **options)
+      loader = options.delete(:loader) || default_loader
+      @model_class.where(*args, **options.merge(loader: loader))
+    end
+
+    # Delegate select to create a new scope with select
+    def select(*attributes)
+      selected_scope = @model_class.select(*attributes)
+      # Chain the includes on top of select
+      IncludesScope.new(selected_scope, @included_connections)
+    end
+
+    # Allow chaining includes calls
+    def includes(*connection_names)
+      @model_class.includes(*(@included_connections + connection_names).uniq)
+    end
+
+    private
+
+    def default_loader
+      @default_loader ||= @model_class.default_loader.class.new(
+        @model_class,
+        included_connections: @included_connections
+      )
+    end
+  end
+end

data/lib/active_shopify_graphql/loader.rb

@@ -84,7 +84,7 @@ module ActiveShopifyGraphQL
 
     # Delegate query building methods
     def query_name(model_type = nil)
-      (model_type || graphql_type).downcase
+      (model_type || graphql_type).camelize(:lower)
     end
 
     def fragment_name(model_type = nil)
@@ -96,19 +96,50 @@ module ActiveShopifyGraphQL
     end
 
     # Map the GraphQL response to model attributes
-    def map_response_to_attributes(response_data)
+    def map_response_to_attributes(response_data, parent_instance: nil)
       mapper = ResponseMapper.new(context)
       attributes = mapper.map_response(response_data)
 
       # If we have included connections, extract and cache them
       if @included_connections.any?
-        connection_data = mapper.extract_connection_data(response_data)
+        connection_data = mapper.extract_connection_data(response_data, parent_instance: parent_instance)
         attributes[:_connection_cache] = connection_data unless connection_data.empty?
       end
 
       attributes
     end
 
+    # Check if this loader has included connections
+    def has_included_connections?
+      @included_connections&.any?
+    end
+
+    # Load and construct an instance with proper inverse_of support for included connections
+    def load_with_instance(id, model_class)
+      query = graphql_query
+      response_data = perform_graphql_query(query, id: id)
+
+      return nil if response_data.nil?
+
+      # First, extract just the attributes (without connections)
+      mapper = ResponseMapper.new(context)
+      attributes = mapper.map_response(response_data)
+
+      # Create the instance with basic attributes
+      instance = model_class.new(attributes)
+
+      # Now extract connection data with the instance as parent to support inverse_of
+      if @included_connections.any?
+        connection_data = mapper.extract_connection_data(response_data, parent_instance: instance)
+        unless connection_data.empty?
+          # Manually set the connection cache on the instance
+          instance.instance_variable_set(:@_connection_cache, connection_data)
+        end
+      end
+
+      instance
+    end
+
     # Executes the GraphQL query and returns the mapped attributes hash
     def load_attributes(id)
       query = graphql_query

data/lib/active_shopify_graphql/loader_context.rb

@@ -38,7 +38,7 @@ module ActiveShopifyGraphQL
 
     # Helper methods delegated from context
     def query_name
-      graphql_type.downcase
+      graphql_type.camelize(:lower)
     end
 
     def fragment_name

data/lib/active_shopify_graphql/loaders/admin_api_loader.rb

@@ -4,7 +4,7 @@ module ActiveShopifyGraphQL
   module Loaders
     class AdminApiLoader < Loader
       def initialize(model_class = nil, selected_attributes: nil, included_connections: nil)
-        super(model_class, selected_attributes: selected_attributes, included_connections: included_connections)
+        super
       end
 
       def perform_graphql_query(query, **variables)

data/lib/active_shopify_graphql/query_node.rb

@@ -40,6 +40,8 @@ class QueryNode
       render_singular(indent_level: indent_level)
     when :fragment
       render_fragment
+    when :raw
+      render_raw
     else
       raise ArgumentError, "Unknown node type: #{@node_type}"
     end
@@ -83,11 +85,14 @@ class QueryNode
     nested_fields = @children.map { |child| child.to_s(indent_level: indent_level + 2) }
     fields_string = nested_fields.join(compact? ? " " : "\n#{nested_indent}  ")
 
+    # Include alias if present
+    field_name = @alias_name ? "#{@alias_name}: #{@name}" : @name
+
     if compact?
-      "#{@name}#{args_string} { edges { node { #{fields_string} } } }"
+      "#{field_name}#{args_string} { edges { node { #{fields_string} } } }"
     else
       <<~GRAPHQL.strip
-        #{@name}#{args_string} {
+        #{field_name}#{args_string} {
         #{nested_indent}edges {
         #{nested_indent}  node {
         #{nested_indent}    #{fields_string}
@@ -108,10 +113,13 @@ class QueryNode
     nested_fields = @children.map { |child| child.to_s(indent_level: indent_level + 1) }
     fields_string = nested_fields.join(compact? ? " " : "\n#{nested_indent}")
 
+    # Include alias if present
+    field_name = @alias_name ? "#{@alias_name}: #{@name}" : @name
+
     if compact?
-      "#{@name}#{args_string} { #{fields_string} }"
+      "#{field_name}#{args_string} { #{fields_string} }"
     else
-      "#{@name}#{args_string} {\n#{nested_indent}#{fields_string}\n#{indent}}"
+      "#{field_name}#{args_string} {\n#{nested_indent}#{fields_string}\n#{indent}}"
     end
   end
 
@@ -127,6 +135,11 @@ class QueryNode
     end
   end
 
+  def render_raw
+    # Raw GraphQL string stored in arguments[:raw_graphql]
+    @arguments[:raw_graphql]
+  end
+
   def format_arguments
     return "" if @arguments.empty?
 

data/lib/active_shopify_graphql/query_tree.rb

@@ -73,11 +73,6 @@ module ActiveShopifyGraphQL
       FragmentBuilder.normalize_includes(includes)
     end
 
-    # Helper methods (kept for backward compatibility)
-    def self.query_name(graphql_type)
-      graphql_type.downcase
-    end
-
     def self.fragment_name(graphql_type)
       "#{graphql_type}Fragment"
     end

data/lib/active_shopify_graphql/response_mapper.rb

@@ -35,18 +35,18 @@ module ActiveShopifyGraphQL
     end
 
     # Extract connection data from GraphQL response for eager loading
-    def extract_connection_data(response_data, root_path: nil)
+    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)
+      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)
+    def extract_connections_from_node(node_data, parent_instance = nil)
       return {} if @context.included_connections.empty?
 
       connections = @context.connections
@@ -59,7 +59,7 @@ module ActiveShopifyGraphQL
         connection_config = connections[connection_name]
         next unless connection_config
 
-        records = extract_connection_records(node_data, connection_config, nested_includes)
+        records = extract_connection_records(node_data, connection_config, nested_includes, parent_instance: parent_instance)
         connection_cache[connection_name] = records if records
       end
 
@@ -69,7 +69,7 @@ module ActiveShopifyGraphQL
     # Map nested connection response (when loading via parent query)
     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.downcase
+      parent_query_name = parent_type.camelize(:lower)
       connection_type = connection_config&.dig(:type) || :connection
 
       if connection_type == :singular
@@ -111,8 +111,26 @@ module ActiveShopifyGraphQL
     private
 
     def extract_and_transform_value(node_data, config, attr_name)
-      path_parts = config[:path].split('.')
-      value = node_data.dig(*path_parts)
+      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)
@@ -153,23 +171,33 @@ module ActiveShopifyGraphQL
       end
     end
 
-    def extract_connection_records(node_data, connection_config, nested_includes)
-      query_name = connection_config[:query_name]
+    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
+      connection_name = connection_config[:original_name]
 
       if connection_type == :singular
-        item_data = node_data[query_name]
+        item_data = node_data[response_key]
         return nil unless item_data
 
-        build_nested_model_instance(item_data, target_class, nested_includes)
+        build_nested_model_instance(item_data, target_class, nested_includes,
+                                    parent_instance: parent_instance,
+                                    parent_connection_name: connection_name,
+                                    connection_config: connection_config)
       else
-        edges = node_data.dig(query_name, "edges")
+        edges = node_data.dig(response_key, "edges")
         return nil unless edges
 
         edges.filter_map do |edge|
           item_data = edge["node"]
-          build_nested_model_instance(item_data, target_class, nested_includes) if item_data
+          if item_data
+            build_nested_model_instance(item_data, target_class, nested_includes,
+                                        parent_instance: parent_instance,
+                                        parent_connection_name: connection_name,
+                                        connection_config: connection_config)
+          end
         end
       end
     end
@@ -181,16 +209,35 @@ module ActiveShopifyGraphQL
       @context.model_class.new(attributes)
     end
 
-    def build_nested_model_instance(node_data, target_class, nested_includes)
+    def build_nested_model_instance(node_data, target_class, nested_includes, parent_instance: nil, parent_connection_name: nil, connection_config: nil) # rubocop:disable Lint/UnusedMethodArgument
       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)
 
-      # Handle nested connections recursively
+      # 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)
+        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

data/lib/active_shopify_graphql/search_query.rb

@@ -27,6 +27,8 @@ module ActiveShopifyGraphQL
     # @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
@@ -38,6 +40,36 @@ module ActiveShopifyGraphQL
       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
+      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

data/lib/active_shopify_graphql/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveShopifyGraphQL
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/active_shopify_graphql.rb

@@ -23,6 +23,7 @@ require_relative "active_shopify_graphql/loaders/customer_account_api_loader"
 require_relative "active_shopify_graphql/loader_switchable"
 require_relative "active_shopify_graphql/finder_methods"
 require_relative "active_shopify_graphql/associations"
+require_relative "active_shopify_graphql/includes_scope"
 require_relative "active_shopify_graphql/connections"
 require_relative "active_shopify_graphql/attributes"
 require_relative "active_shopify_graphql/metafield_attributes"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_shopify_graphql
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nicolò Rebughini
@@ -52,34 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 description: ActiveShopifyGraphQL provides an ActiveRecord-like interface for interacting
   with Shopify's GraphQL APIs, supporting both Admin API and Customer Account API
   with automatic query building and response mapping.
@@ -108,6 +80,7 @@ files:
 - lib/active_shopify_graphql/fragment_builder.rb
 - lib/active_shopify_graphql/gid_helper.rb
 - lib/active_shopify_graphql/graphql_type_resolver.rb
+- lib/active_shopify_graphql/includes_scope.rb
 - lib/active_shopify_graphql/loader.rb
 - lib/active_shopify_graphql/loader_context.rb
 - lib/active_shopify_graphql/loader_switchable.rb
@@ -125,6 +98,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/nebulab/active_shopify_graphql
   source_code_uri: https://github.com/nebulab/active_shopify_graphql
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: