active_shopify_graphql 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fbed890ba698aa5134ff32bdd471ffa8944e56eaf5d6a8a6d28e8060983e519
-  data.tar.gz: 34d83bf513460e154f33369fe54e953c68a466e37d16effccb7cb92014f16824
+  metadata.gz: 2f853d9c152e7118a0916f0daf12f6b855779cf7006e15849738f4ddad75bbc3
+  data.tar.gz: '0195855f859d751a6ca53b2bbe08c804892a96dfb640ceb7a73267fb7e7c4748'
 SHA512:
-  metadata.gz: 4a1dad259585ae87c1afa68c18eb03f74b48b13068b452a41a7d42bfb576c244df4de5eab321559dc5c9a5f11e1f2964fb0cdef142058ae345a75cb29e9e5700
-  data.tar.gz: f847bdf0f63e10b67f866abd6fae9c0d24195977d078c6d7125e7eff083f2f6ba99e1b0c30ada1374f5ceb4f36f0e8a1d52506a2d7354c7e01020d7d1ab4bcf7
+  metadata.gz: 4f7871a5b0aee7d7b7cbe489d0ebec973b7f123adf5f28f821c781fc806e3daae2c5a6048554bdfc29756d4e2d5d97e394ad806c1cbd85c69b9f16aff6fff33f
+  data.tar.gz: 0e830f19306b3b0270f326514b775186ba769d76bc6a91a6f8a3e539552bd223a97c3071e42eb29a37e3f146fbe33bad8ee12c035dcf37c4eb45e75677719713

data/.github/workflows/lint.yml

@@ -17,12 +17,11 @@ permissions:
   contents: read
 
 jobs:
-  test:
-
+  lint:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.4']
+        ruby-version: ['4.0']
 
     steps:
     - uses: actions/checkout@v4

data/.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.2', '3.3', '3.4']
+        ruby-version: ['3.2', '3.3', '3.4', '4.0']
 
     steps:
     - uses: actions/checkout@v4

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/README.md

@@ -183,8 +183,8 @@ Attributes auto-generate GraphQL fragments and handle response mapping:
 class Customer < ActiveShopifyGraphQL::Model
   graphql_type "Customer"
 
-  # Auto-inferred path: displayName
-  attribute :name, type: :string
+  # Renaming an attribute
+  attribute :name, path: "displayName", type: :string
 
   # Custom path with dot notation
   attribute :email, path: "defaultEmailAddress.emailAddress", type: :string
@@ -201,7 +201,7 @@ Connections to related Shopify data with lazy/eager loading:
 ```ruby
 class Customer < ActiveShopifyGraphQL::Model
   # Lazy by default — loaded on first access
-  has_many_connected :orders
+  has_many_connected :orders, default_arguments: { first: 10 }
 
   # Always eager load — no N+1 queries
   has_many_connected :addresses, eager_load: true, default_arguments: { first: 5 }
@@ -472,6 +472,55 @@ reward.customer        # Loads Customer from shopify_customer_id
 reward.variants        # Queries ProductVariant.where({})
 ```
 
+### Logging
+
+Track GraphQL query performance and costs in your Rails logs:
+
+```ruby
+# config/initializers/active_shopify_graphql.rb
+require "benchmark"
+
+Rails.configuration.to_prepare do
+  ActiveShopifyGraphQL.configure do |config|
+    config.admin_api_executor = lambda do |query, **variables|
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session)
+      response = nil
+      duration_ms = Benchmark.realtime { response = client.query(query:, variables:) } * 1000
+      cost = response.body.dig("extensions", "cost")
+
+      # Log query with timing and cost
+      ActiveShopifyGraphQL::Logging::GraphqlLogger.log(
+        query: query,
+        duration_ms: duration_ms,
+        cost: cost,
+        variables: variables
+      )
+
+      errors = response.body["errors"]
+      raise errors.inspect if errors.present?
+      response.body if response
+    end
+  end
+end
+```
+
+#### Controller Runtime (Optional)
+
+Add GraphQL timing to your Rails request logs (`Completed 200 OK ... GraphQL: 45.2ms, 38 cost`):
+
+```ruby
+# config/initializers/graphql_controller_runtime.rb
+ActiveSupport.on_load(:action_controller) do
+  include ActiveShopifyGraphQL::Logging::GraphqlControllerRuntime
+end
+```
+
+This will append GraphQL timing and cost summaries to your controller logs:
+
+```
+Completed 200 OK in 250ms (Views: 12.3ms | ActiveRecord: 5.2ms | GraphQL: 45.2ms, 38 cost)
+```
+
 ---
 
 ## API Reference
@@ -558,15 +607,64 @@ Customer.with_loader(MyCustomLoader).find(123)
 
 ### Testing
 
-Mock data for tests:
+The gem ships with a built-in testing module that lets you register test data using Ruby-level attributes. `find`, `where`, `find_by`, `includes`, and connections all work transparently without real API calls.
+
+#### Setup
 
 ```ruby
-# Mock associations
-customer = Customer.new(id: 'gid://shopify/Customer/123')
-customer.orders = [Order.new(id: 'gid://shopify/Order/1')]
+# spec/spec_helper.rb (or test_helper.rb)
+require "active_shopify_graphql/testing"
 
-# Mock connections
-customer.orders = mock_orders
+RSpec.configure do |config|
+  config.before(:each) { ActiveShopifyGraphQL::Testing.enable! }
+  config.after(:each)  { ActiveShopifyGraphQL::Testing.reset! }
+end
+```
+
+#### Registering Test Data
+
+```ruby
+# Register records using Ruby attribute names — IDs are auto-normalized to GIDs
+ActiveShopifyGraphQL::Testing.register(Customer, [
+  { id: 1, email: "john@example.com", display_name: "John" },
+  { id: 2, email: "jane@example.com", display_name: "Jane" }
+])
+
+# With inline connections
+ActiveShopifyGraphQL::Testing.register(Customer, [
+  {
+    id: 1,
+    email: "john@example.com",
+    orders: [{ id: "gid://shopify/Order/100", name: "#1001" }]
+  }
+])
+
+# With extra search fields (not model attributes, used only for where matching)
+ActiveShopifyGraphQL::Testing.register(ProductVariant, [
+  { id: 1, sku: "ABC", product_id: 10 }
+])
+```
+
+#### Using in Tests
+
+All query patterns work the same as in production:
+
+```ruby
+Customer.find(1)                                    # => Customer instance
+Customer.where(email: "john@example.com").to_a      # => [Customer]
+Customer.find_by(email: "john@example.com")         # => Customer or nil
+Customer.includes(:orders).find(1)                  # => Customer with orders eager-loaded
+customer.orders                                     # => lazy-loads from store
+ProductVariant.where(product_id: 10).to_a           # => matches on search field
+```
+
+#### Manual Mocking
+
+For simpler cases, you can also mock data directly:
+
+```ruby
+customer = Customer.new(id: "gid://shopify/Customer/123")
+customer.orders = [Order.new(id: "gid://shopify/Order/1")]
 expect(customer.orders.size).to eq(1)
 ```
 
@@ -597,8 +695,8 @@ bundle exec rubocop
 - [x] Query optimization with `select`
 - [x] GraphQL connections with lazy/eager loading
 - [x] Cursor-based pagination
+- [x] Builtin instrumentation to track query costs
 - [ ] Metaobjects as models
-- [ ] Builtin instrumentation to track query costs
 - [ ] Advanced error handling and retry mechanisms
 - [ ] Caching layer
 - [ ] Chained `.where` with `.not` support

data/lib/active_shopify_graphql/logging/graphql_controller_runtime.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Logging
+    # Adds GraphQL runtime and cost to the Rails request log
+    # Pattern borrowed from ActiveRecord::Railties::ControllerRuntime
+    #
+    # Include this module in your ApplicationController or via an initializer:
+    #
+    #   ActiveSupport.on_load(:action_controller) do
+    #     include ActiveShopifyGraphQL::Logging::GraphqlControllerRuntime
+    #   end
+    #
+    module GraphqlControllerRuntime
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def log_process_action(payload)
+          messages = super
+          runtime = payload[:graphql_runtime]
+          cost = payload[:graphql_cost]
+
+          if runtime&.positive?
+            cost_info = cost&.positive? ? ", #{cost.round} cost" : ""
+            messages << "GraphQL: #{runtime.round(1)}ms#{cost_info}"
+          end
+
+          messages
+        end
+      end
+
+      private
+
+      def append_info_to_payload(payload)
+        super
+        payload[:graphql_runtime] = GraphqlRuntime.reset_runtime
+        payload[:graphql_cost] = GraphqlRuntime.reset_cost
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/logging/graphql_logger.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Logging
+    # Logs GraphQL queries with timing and cost information
+    # Uses ActiveSupport::LogSubscriber for consistent Rails-style log formatting
+    class GraphqlLogger < ActiveSupport::LogSubscriber
+      YELLOW = 33
+      GREEN = 32
+      BLUE = 34
+      CYAN = 36
+      MAGENTA = 35
+
+      def self.log(query:, duration_ms:, cost:, variables:)
+        new.log(query:, duration_ms:, cost:, variables:)
+      end
+
+      def log(query:, duration_ms:, cost:, variables:)
+        GraphqlRuntime.add(duration_ms:, cost: cost&.dig("requestedQueryCost"))
+
+        name = color("  GraphQL (#{duration_ms.round(1)}ms)", YELLOW, bold: true)
+        colored_query = color(query.gsub(/\s+/, " ").strip, graphql_color(query), bold: true)
+        binds = variables.present? ? "  #{variables.inspect}" : ""
+
+        cost_info = "\n  ↳ cost: #{cost}" if cost
+        debug "#{name}  #{colored_query}#{binds}#{cost_info}"
+      end
+
+      private
+
+      def graphql_color(query)
+        case query
+        when /\A\s*mutation/i then GREEN
+        when /\A\s*query/i then BLUE
+        when /\A\s*subscription/i then CYAN
+        else MAGENTA
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/logging/graphql_runtime.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Logging
+    # Thread-safe runtime and cost tracking for request summaries
+    # Pattern borrowed from ActiveRecord's RuntimeRegistry
+    module GraphqlRuntime
+      module_function
+
+      def runtime=(value)
+        Thread.current[:active_shopify_graphql_runtime] = value
+      end
+
+      def runtime
+        Thread.current[:active_shopify_graphql_runtime] ||= 0
+      end
+
+      def reset_runtime
+        rt = runtime
+        self.runtime = 0
+        rt
+      end
+
+      def cost=(value)
+        Thread.current[:active_shopify_graphql_cost] = value
+      end
+
+      def cost
+        Thread.current[:active_shopify_graphql_cost] ||= 0
+      end
+
+      def reset_cost
+        c = cost
+        self.cost = 0
+        c
+      end
+
+      def add(duration_ms:, cost:)
+        self.runtime += duration_ms
+        self.cost += cost if cost
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/model/graphql_type_resolver.rb

@@ -8,8 +8,7 @@ module ActiveShopifyGraphQL::Model::GraphqlTypeResolver
     # 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
+    # @return [String] The GraphQL type name, inferred from the class name if not explicitly set
     def graphql_type(type = nil)
       if type
         if @current_loader_context
@@ -20,7 +19,7 @@ module ActiveShopifyGraphQL::Model::GraphqlTypeResolver
         end
       end
 
-      @base_graphql_type || raise(NotImplementedError, "#{self} must define graphql_type")
+      @base_graphql_type || name.demodulize
     end
 
     # Get the GraphQL type for a specific loader class.

data/lib/active_shopify_graphql/query/relation.rb

@@ -112,7 +112,7 @@ module ActiveShopifyGraphQL
         end
 
         # Standard case: find by ID
-        gid = GidHelper.normalize_gid(id, @model_class.model_name.name.demodulize)
+        gid = GidHelper.normalize_gid(id, @model_class.graphql_type)
         attributes = loader.load_attributes(gid)
 
         raise ObjectNotFoundError, "Couldn't find #{@model_class.name} with id=#{id}" if attributes.nil?

data/lib/active_shopify_graphql/testing/hook.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Testing
+    # Prepended onto LoaderSwitchable::ClassMethods to redirect
+    # default_loader_class to TestLoader when testing is enabled.
+    module LoaderSwitchableHook
+      private
+
+      def default_loader_class
+        return super unless ActiveShopifyGraphQL::Testing.enabled?
+
+        ActiveShopifyGraphQL::Testing::TestLoader
+      end
+    end
+
+    # Prepended onto FinderMethods::ClassMethods to return fresh
+    # TestLoader instances (preventing memoization leaks between tests).
+    module FinderMethodsHook
+      def default_loader
+        return super unless ActiveShopifyGraphQL::Testing.enabled?
+
+        # Return a fresh instance each time to prevent state leakage between tests.
+        eagerly_loaded_connections = connections.select { |_name, config| config[:eager_load] }.keys
+        ActiveShopifyGraphQL::Testing::TestLoader.new(
+          self,
+          included_connections: eagerly_loaded_connections
+        )
+      end
+    end
+
+    # Prepended onto Attributes::ClassMethods so that attributes_for_loader
+    # returns attributes from ALL loader contexts when TestLoader is the
+    # requested loader. Without this, attributes defined only inside
+    # for_loader blocks (e.g. email on AdminApiLoader) would be invisible
+    # to the testing harness.
+    module AttributesHook
+      def attributes_for_loader(loader_class)
+        if ActiveShopifyGraphQL::Testing.enabled? && loader_class == ActiveShopifyGraphQL::Testing::TestLoader
+          base = instance_variable_get(:@base_attributes) || {}
+          loader_contexts = instance_variable_get(:@loader_contexts) || {}
+
+          merged = base.dup
+          loader_contexts.each_value { |ctx_attrs| merged.merge!(ctx_attrs) { |_key, base_val, _override_val| base_val } }
+          return merged
+        end
+
+        super
+      end
+    end
+
+    # Prepended onto GraphqlTypeResolver::ClassMethods so that graphql_type
+    # (with no argument) falls back to graphql_type_for_loader(TestLoader)
+    # when testing is enabled. Models that only define graphql_type inside
+    # for_loader blocks have no @base_graphql_type and would otherwise raise.
+    module GraphqlTypeResolverHook
+      def graphql_type(type = nil)
+        super
+      rescue NotImplementedError
+        raise unless ActiveShopifyGraphQL::Testing.enabled?
+
+        graphql_type_for_loader(ActiveShopifyGraphQL::Testing::TestLoader)
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/testing/store.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Testing
+    # In-memory data store for test records.
+    # Stores records keyed by model class, with IDs normalized to GID format.
+    # Supports lookup by ID, filtering by hash/string conditions, and
+    # extracting inline connection data from parent records.
+    class Store
+      def initialize
+        @data = {}
+      end
+
+      # Register test records for a model class.
+      # IDs are normalized to GID format using the model's graphql_type.
+      #
+      # @param model_class [Class] The model class (e.g., Customer)
+      # @param records [Array<Hash>] Array of attribute hashes
+      def register(model_class, records)
+        graphql_type = model_class.graphql_type_for_loader(model_class.send(:default_loader_class))
+
+        @data[model_class] = records.map do |record|
+          record = record.dup
+          record[:id] = GidHelper.normalize_gid(record[:id], graphql_type) if record.key?(:id)
+          record
+        end
+      end
+
+      # Find a single record by normalized GID.
+      #
+      # @param model_class [Class] The model class
+      # @param id [String] The GID to look up
+      # @return [Hash, nil] The matching record or nil
+      def find(model_class, id)
+        records = @data[model_class] || []
+        records.find { |r| r[:id] == id }
+      end
+
+      # Filter records by conditions.
+      # Hash conditions: match against ALL keys in stored hash (attributes + search fields).
+      # String conditions: parse simple key:value patterns, fallback to return all.
+      # Comparison uses .to_s on both sides so plain IDs match naturally.
+      #
+      # @param model_class [Class] The model class
+      # @param conditions [Hash, String] The filter conditions
+      # @return [Array<Hash>] Matching records
+      def where(model_class, conditions)
+        records = @data[model_class] || []
+
+        case conditions
+        when Hash
+          filter_by_hash(records, normalize_conditions(model_class, conditions))
+        when String
+          filter_by_string(records, conditions)
+        else
+          records
+        end
+      end
+
+      # Extract inline connection data from a parent's stored record.
+      #
+      # @param model_class [Class] The parent model class
+      # @param id [String] The parent's GID
+      # @param connection_name [Symbol] The connection key name
+      # @return [Array<Hash>, Hash, nil] The connection data
+      def connections_for(model_class, id, connection_name)
+        record = find(model_class, id)
+        return nil unless record
+
+        record[connection_name]
+      end
+
+      # Clear all stored data.
+      def clear
+        @data.clear
+      end
+
+      private
+
+      def filter_by_hash(records, conditions)
+        records.select do |record|
+          conditions.all? do |key, value|
+            next false unless record.key?(key)
+
+            case value
+            when Array
+              value.any? { |v| record[key].to_s == v.to_s }
+            else
+              record[key].to_s == value.to_s
+            end
+          end
+        end
+      end
+
+      # Normalize :id values in conditions to GIDs so they match stored records.
+      def normalize_conditions(model_class, conditions)
+        return conditions unless conditions.key?(:id)
+
+        graphql_type = model_class.graphql_type_for_loader(model_class.send(:default_loader_class))
+        normalized = conditions.dup
+
+        normalized[:id] =
+          case conditions[:id]
+          when Array
+            conditions[:id].map { |v| GidHelper.normalize_gid(v, graphql_type) }
+          else
+            GidHelper.normalize_gid(conditions[:id], graphql_type)
+          end
+
+        normalized
+      end
+
+      def filter_by_string(records, query)
+        return records if query.nil? || query.strip.empty?
+
+        # Parse simple key:'value' or key:value patterns
+        # Bail on wildcards or complex boolean queries
+        return records if query.include?("*") || query.include?(" AND ") || query.include?(" OR ")
+
+        pairs = parse_search_query(query)
+        return records if pairs.empty?
+
+        filter_by_hash(records, pairs)
+      end
+
+      # Parse a simple Shopify search query string into key-value pairs.
+      # Handles: key:'value', key:"value", key:value
+      def parse_search_query(query)
+        pairs = {}
+        # Match key:'value', key:"value", or key:unquoted_value
+        query.scan(/(\w+):(?:'([^']*)'|"([^"]*)"|(\S+))/) do |key, sq, dq, uq|
+          pairs[key.to_sym] = sq || dq || uq
+        end
+        pairs
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/testing/test_loader.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Testing
+    # Loader subclass that reads from the in-memory Store instead of
+    # executing GraphQL queries. Overrides the three main loading methods
+    # and raises on any attempt to perform a real GraphQL query.
+    class TestLoader < Loader
+      # Load attributes for a single record by ID.
+      #
+      # @param id [String] The GID of the record
+      # @return [Hash, nil] Filtered attribute hash with optional connection cache
+      def load_attributes(id)
+        record = Testing.store.find(@model_class, id)
+        return nil unless record
+
+        attrs = filter_to_model_attributes(record)
+
+        populate_connection_cache(record, attrs) if @included_connections.any?
+
+        attrs
+      end
+
+      # Load a paginated collection matching the given conditions.
+      #
+      # @return [Response::PaginatedResult]
+      def load_paginated_collection(conditions:, per_page:, query_scope:, after: nil, before: nil, sort_key: nil, reverse: nil) # rubocop:disable Lint/UnusedMethodArgument
+        all_records = Testing.store.where(@model_class, conditions)
+
+        # Simple cursor-based pagination using array indices
+        start_index = after ? after.to_i + 1 : 0
+        start_index = [all_records.size - per_page, 0].max if before
+
+        page_records = all_records[start_index, per_page] || []
+        end_index = start_index + page_records.size - 1
+
+        page_info = Response::PageInfo.new(
+          "hasNextPage" => end_index < all_records.size - 1,
+          "hasPreviousPage" => start_index.positive?,
+          "startCursor" => start_index.to_s,
+          "endCursor" => end_index.to_s
+        )
+
+        attributes_array = page_records.map do |record|
+          attrs = filter_to_model_attributes(record)
+          populate_connection_cache(record, attrs) if @included_connections.any?
+          attrs
+        end
+
+        Response::PaginatedResult.new(
+          attributes: attributes_array,
+          model_class: @model_class,
+          page_info: page_info,
+          query_scope: query_scope
+        )
+      end
+
+      # Load records for a connection (lazy-loaded or explicit).
+      #
+      # @return [Object, Array<Object>, nil] Built model instance(s)
+      def load_connection_records(_query_name, _variables, parent = nil, connection_config = nil)
+        return [] unless parent && connection_config
+
+        connection_name = connection_config[:original_name]
+        connection_data = Testing.store.connections_for(parent.class, parent.id, connection_name)
+
+        return (connection_config[:type] == :singular ? nil : []) unless connection_data
+
+        target_class = connection_config[:class_name].constantize
+        singular = connection_config[:type] == :singular
+
+        if singular
+          data = connection_data.is_a?(Array) ? connection_data.first : connection_data
+          return nil unless data
+
+          attrs = filter_to_model_attributes(data, target_class)
+          wire_inverse_of(parent, attrs, connection_config)
+          ModelBuilder.build(target_class, attrs)
+        else
+          items = connection_data.is_a?(Array) ? connection_data : [connection_data]
+          items.filter_map do |item|
+            attrs = filter_to_model_attributes(item, target_class)
+            wire_inverse_of(parent, attrs, connection_config)
+            ModelBuilder.build(target_class, attrs)
+          end
+        end
+      end
+
+      # Should never be called — all data comes from the Store.
+      def perform_graphql_query(_query, **_variables)
+        raise "TestLoader should not execute GraphQL queries. " \
+              "Ensure all test data is registered via ActiveShopifyGraphQL::Testing.register"
+      end
+
+      private
+
+      # Filter a stored record hash down to only the declared model attributes,
+      # then apply transforms and type coercion to match what the ResponseMapper
+      # would produce from a real GraphQL response.
+      def filter_to_model_attributes(record, model_class = @model_class)
+        defined_attributes = model_class.attributes_for_loader(self.class)
+        # Always include :id
+        allowed_keys = (defined_attributes.keys + [:id]).uniq
+
+        record.each_with_object({}) do |(key, value), attrs|
+          next unless allowed_keys.include?(key)
+
+          config = defined_attributes[key]
+          if config
+            value = apply_defaults_and_transforms(value, config)
+            value = coerce_value(value, config[:type])
+          end
+
+          attrs[key] = value
+        end
+      end
+
+      def apply_defaults_and_transforms(value, config)
+        if value.nil?
+          return config[:default] unless config[:default].nil?
+
+          return config[:transform]&.call(value)
+        end
+
+        config[:transform] ? config[:transform].call(value) : value
+      end
+
+      def coerce_value(value, type)
+        return nil if value.nil?
+        return value if value.is_a?(Array)
+
+        case type
+        when :string   then ActiveModel::Type::String.new
+        when :integer  then ActiveModel::Type::Integer.new
+        when :float    then ActiveModel::Type::Float.new
+        when :boolean  then ActiveModel::Type::Boolean.new
+        when :datetime then ActiveModel::Type::DateTime.new
+        else ActiveModel::Type::Value.new
+        end.cast(value)
+      end
+
+      # Build connection cache from inline connection data in the stored record.
+      def populate_connection_cache(record, attrs)
+        normalized = Query::QueryBuilder.normalize_includes(@included_connections)
+
+        cache = {}
+        normalized.each do |connection_name, nested_includes|
+          connection_config = @model_class.connections[connection_name]
+          next unless connection_config
+
+          connection_data = record[connection_name]
+          next unless connection_data
+
+          target_class = connection_config[:class_name].constantize
+          singular = connection_config[:type] == :singular
+
+          if singular
+            data = connection_data.is_a?(Array) ? connection_data.first : connection_data
+            if data
+              child_attrs = filter_to_model_attributes(data, target_class)
+              populate_nested_connections(data, child_attrs, target_class, nested_includes)
+              cache[connection_name] = ModelBuilder.build(target_class, child_attrs)
+            end
+          else
+            items = connection_data.is_a?(Array) ? connection_data : [connection_data]
+            cache[connection_name] = items.filter_map do |item|
+              child_attrs = filter_to_model_attributes(item, target_class)
+              populate_nested_connections(item, child_attrs, target_class, nested_includes)
+              ModelBuilder.build(target_class, child_attrs)
+            end
+          end
+        end
+
+        attrs[:_connection_cache] = cache unless cache.empty?
+      end
+
+      # Recursively populate nested connection caches for deeply included connections.
+      def populate_nested_connections(record, attrs, model_class, nested_includes)
+        return if nested_includes.nil? || nested_includes.empty?
+
+        normalized = Query::QueryBuilder.normalize_includes(nested_includes)
+        cache = {}
+
+        normalized.each do |connection_name, deeper_includes|
+          connection_config = model_class.connections[connection_name]
+          next unless connection_config
+
+          connection_data = record[connection_name]
+          next unless connection_data
+
+          target_class = connection_config[:class_name].constantize
+          singular = connection_config[:type] == :singular
+
+          if singular
+            data = connection_data.is_a?(Array) ? connection_data.first : connection_data
+            if data
+              child_attrs = filter_to_model_attributes(data, target_class)
+              populate_nested_connections(data, child_attrs, target_class, deeper_includes)
+              cache[connection_name] = ModelBuilder.build(target_class, child_attrs)
+            end
+          else
+            items = connection_data.is_a?(Array) ? connection_data : [connection_data]
+            cache[connection_name] = items.filter_map do |item|
+              child_attrs = filter_to_model_attributes(item, target_class)
+              populate_nested_connections(item, child_attrs, target_class, deeper_includes)
+              ModelBuilder.build(target_class, child_attrs)
+            end
+          end
+        end
+
+        attrs[:_connection_cache] = cache unless cache.empty?
+      end
+
+      # Wire inverse_of associations into the connection cache.
+      def wire_inverse_of(parent, attributes, connection_config)
+        return unless attributes.is_a?(Hash) && connection_config&.dig(:inverse_of)
+
+        inverse_name = connection_config[:inverse_of]
+        target_class = connection_config[:class_name].constantize
+        return unless target_class.respond_to?(:connections) && target_class.connections[inverse_name]
+
+        attributes[:_connection_cache] ||= {}
+        inverse_type = target_class.connections[inverse_name][:type]
+        attributes[:_connection_cache][inverse_name] =
+          if inverse_type == :singular
+            parent
+          else
+            [parent]
+          end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/testing.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "testing/store"
+require_relative "testing/test_loader"
+require_relative "testing/hook"
+
+module ActiveShopifyGraphQL
+  # Testing support module that provides an in-memory store for test data,
+  # allowing developers to register records using Ruby-level attributes and
+  # have find, where, includes, and connections work transparently without
+  # real API calls.
+  #
+  # @example In spec_helper.rb
+  #   require 'active_shopify_graphql/testing'
+  #
+  #   RSpec.configure do |config|
+  #     config.before(:each) { ActiveShopifyGraphQL::Testing.enable! }
+  #     config.after(:each)  { ActiveShopifyGraphQL::Testing.reset! }
+  #   end
+  #
+  # @example In tests
+  #   ActiveShopifyGraphQL::Testing.register(Customer, [
+  #     { id: 1, email: "john@example.com", display_name: "John" }
+  #   ])
+  #   Customer.find(1) # => Customer instance from the store
+  #
+  module Testing
+    class << self
+      def enable!
+        @enabled = true
+      end
+
+      def reset!
+        @enabled = false
+        store.clear
+      end
+
+      def enabled?
+        @enabled == true
+      end
+
+      def store
+        @store ||= Store.new
+      end
+
+      # Convenience delegate to store.register
+      def register(model_class, records)
+        store.register(model_class, records)
+      end
+    end
+  end
+end
+
+# Apply hooks once at load time
+ActiveShopifyGraphQL::Model::LoaderSwitchable::ClassMethods.prepend(
+  ActiveShopifyGraphQL::Testing::LoaderSwitchableHook
+)
+ActiveShopifyGraphQL::Model::FinderMethods::ClassMethods.prepend(
+  ActiveShopifyGraphQL::Testing::FinderMethodsHook
+)
+ActiveShopifyGraphQL::Model::Attributes::ClassMethods.prepend(
+  ActiveShopifyGraphQL::Testing::AttributesHook
+)
+ActiveShopifyGraphQL::Model::GraphqlTypeResolver::ClassMethods.prepend(
+  ActiveShopifyGraphQL::Testing::GraphqlTypeResolverHook
+)

data/lib/active_shopify_graphql/version.rb

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

data/lib/active_shopify_graphql.rb

@@ -14,6 +14,8 @@ loader.inflector.inflect(
   "active_shopify_graphql" => "ActiveShopifyGraphQL",
   "graphql_associations" => "GraphQLAssociations"
 )
+loader.ignore("#{__dir__}/active_shopify_graphql/testing")
+loader.ignore("#{__dir__}/active_shopify_graphql/testing.rb")
 loader.setup
 
 module ActiveShopifyGraphQL

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_shopify_graphql
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Nicolò Rebughini
 autorequire:
 bindir: exe
 cert_chain: []
-date:
+date: 2026-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -79,6 +79,7 @@ files:
 - ".github/workflows/test.yml"
 - ".rubocop.yml"
 - AGENTS.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -93,6 +94,9 @@ files:
 - lib/active_shopify_graphql/loader_proxy.rb
 - lib/active_shopify_graphql/loaders/admin_api_loader.rb
 - lib/active_shopify_graphql/loaders/customer_account_api_loader.rb
+- lib/active_shopify_graphql/logging/graphql_controller_runtime.rb
+- lib/active_shopify_graphql/logging/graphql_logger.rb
+- lib/active_shopify_graphql/logging/graphql_runtime.rb
 - lib/active_shopify_graphql/model.rb
 - lib/active_shopify_graphql/model/associations.rb
 - lib/active_shopify_graphql/model/attributes.rb
@@ -123,6 +127,10 @@ files:
 - lib/active_shopify_graphql/search_query/hash_condition_formatter.rb
 - lib/active_shopify_graphql/search_query/parameter_binder.rb
 - lib/active_shopify_graphql/search_query/value_sanitizer.rb
+- lib/active_shopify_graphql/testing.rb
+- lib/active_shopify_graphql/testing/hook.rb
+- lib/active_shopify_graphql/testing/store.rb
+- lib/active_shopify_graphql/testing/test_loader.rb
 - lib/active_shopify_graphql/version.rb
 homepage: https://github.com/nebulab/active_shopify_graphql
 licenses:
@@ -146,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: An ActiveRecord-like interface for Shopify GraphQL APIs