active_shopify_graphql 0.5.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6fe91cae8b27f0c6154d8d43a42477e900dba59925b27421f5ea43278c8a786
-  data.tar.gz: 6480859442d7a8ff30dc17fa3c0a96c5ae383f0ce0465fbbb8a67ff26c46f6da
+  metadata.gz: 2f853d9c152e7118a0916f0daf12f6b855779cf7006e15849738f4ddad75bbc3
+  data.tar.gz: '0195855f859d751a6ca53b2bbe08c804892a96dfb640ceb7a73267fb7e7c4748'
 SHA512:
-  metadata.gz: e8572b7217ec7bb43172611d1d4059114b70de34342bb7c702265a90f3295004fd7de85b5449077054633ea199dd3f6606638f042cff3798dfc76d76dde24f4e
-  data.tar.gz: 975eca8ec8d7ab7e3f166884baa6e885d76596d130f4525281b85075b3acef960f5562a45ed8a7ae73ac14e1a2e179cc129dbcff6a5b0d5588ba21ccb6838893
+  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

@@ -25,15 +25,21 @@ gem install active_shopify_graphql
 ```ruby
 # Configure in pure Ruby
 ActiveShopifyGraphQL.configure do |config|
-  config.admin_api_client = ShopifyGraphQL::Client
-  config.customer_account_client_class = Shopify::Account::Client
+  config.admin_api_executor = lambda do |query, **variables|
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session)
+    response = client.query(query:, variables:)
+    response.body if response
+  end
 end
 
 # Or define a Rails initializer
 Rails.configuration.to_prepare do
   ActiveShopifyGraphQL.configure do |config|
-    config.admin_api_client = ShopifyGraphQL::Client
-    config.customer_account_client_class = Shopify::Account::Client
+    config.admin_api_executor = lambda do |query, **variables|
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session)
+      response = client.query(query:, variables:)
+      response.body if response
+    end
   end
 end
 
@@ -90,7 +96,7 @@ orders = customer["orders"]["nodes"].map { |o| parse_order(o) }
 customer = Customer.includes(:orders).find(123456789)
 customer.email                # => "john@example.com"
 customer.created_at           # => #<DateTime>
-customer.orders.to_a          # Lazily loaded as a single query
+customer.orders               # Eagerly loaded as a single query
 ```
 
 **Benefits:**
@@ -138,11 +144,19 @@ Configure your Shopify GraphQL clients:
 # config/initializers/active_shopify_graphql.rb
 Rails.configuration.to_prepare do
   ActiveShopifyGraphQL.configure do |config|
-    # Admin API (must respond to #execute(query, **variables))
-    config.admin_api_client = ShopifyGraphQL::Client
-
-    # Customer Account API (must have .from_config(token) and #execute)
-    config.customer_account_client_class = Shopify::Account::Client
+    # Admin API (receives query, **variables as arguments)
+    config.admin_api_executor = lambda do |query, **variables|
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session)
+      response = client.query(query:, variables:)
+      response.body if response
+    end
+
+    # Optional Customer Account API (receives query, customer_token, **variables as arguments)
+    config.customer_account_api_executor = lambda do |query, customer_token, **variables|
+      # This is a custom client example
+      client = Shopify::Account::Client.from_config(customer_token)
+      response = client.query(query, **variables)
+    end
   end
 end
 ```
@@ -169,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
@@ -187,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 }
@@ -309,7 +323,8 @@ Customer.where(email: "john@example.com")
 Customer.where(created_at: { gte: "2024-01-01", lt: "2024-02-01" })
 Customer.where(orders_count: { gte: 5 })
 
-# Wildcards (string query)
+# Wildcards are supported in string queries only
+# Use with caution as interpolation can lead to security issues
 Customer.where("email:*@example.com")
 
 # Parameter binding (safe)
@@ -319,6 +334,21 @@ Customer.where("email::email", email: "john@example.com")
 Customer.where(email: "@gmail.com").limit(100)
 ```
 
+#### Sorting
+
+```ruby
+# Sort by created_at ascending (default)
+Customer.where(email: "@example.com").order(sort_key: "CREATED_AT")
+
+# Sort by updated_at descending
+Customer.order(sort_key: "UPDATED_AT", reverse: true)
+
+# Combine with other chainable methods
+Customer.where(country: "Canada").order(sort_key: "CREATED_AT").limit(25)
+```
+
+**Note:** Sort keys are Shopify GraphQL enum values (e.g., `"CREATED_AT"`, `"UPDATED_AT"`, `"RELEVANCE"`). Available values depend on the specific Shopify API endpoint.
+
 #### Query Optimization
 
 ```ruby
@@ -349,7 +379,7 @@ ProductVariant.where("sku:FRZ*").in_pages(of: 10) do |page|
 end
 
 # Lazy enumeration
-scope = Customer.where(email: "*@example.com")
+scope = Customer.where(email: "@example.com")
 scope.each { |c| puts c.name }  # Executes query
 scope.first                      # Fetches just first
 ```
@@ -442,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
@@ -528,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
+# spec/spec_helper.rb (or test_helper.rb)
+require "active_shopify_graphql/testing"
+
+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
-# Mock associations
-customer = Customer.new(id: 'gid://shopify/Customer/123')
-customer.orders = [Order.new(id: 'gid://shopify/Order/1')]
+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
+```
 
-# Mock connections
-customer.orders = mock_orders
+#### 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)
 ```
 
@@ -567,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/configuration.rb

@@ -3,11 +3,11 @@
 module ActiveShopifyGraphQL
   # Configuration class for setting up external dependencies
   class Configuration
-    attr_accessor :admin_api_client, :customer_account_client_class, :logger, :log_queries, :max_objects_per_paginated_query
+    attr_accessor :admin_api_executor, :customer_account_api_executor, :logger, :log_queries, :max_objects_per_paginated_query
 
     def initialize
-      @admin_api_client = nil
-      @customer_account_client_class = nil
+      @admin_api_executor = nil
+      @customer_account_api_executor = nil
       @logger = nil
       @log_queries = false
       @max_objects_per_paginated_query = 250

data/lib/active_shopify_graphql/connections/connection_loader.rb

@@ -44,7 +44,7 @@ module ActiveShopifyGraphQL
         )
 
         parent_id = extract_gid(parent)
-        response_data = @loader_instance.perform_graphql_query(query, id: parent_id)
+        response_data = @loader_instance.execute_query(query, id: parent_id)
 
         return [] if response_data.nil?
 
@@ -76,7 +76,7 @@ module ActiveShopifyGraphQL
           singular: singular
         )
 
-        response_data = @loader_instance.perform_graphql_query(query)
+        response_data = @loader_instance.execute_query(query)
 
         return [] if response_data.nil?
 

data/lib/active_shopify_graphql/loader.rb

@@ -58,7 +58,7 @@ module ActiveShopifyGraphQL
 
     # Map the GraphQL response to model attributes
     def map_response_to_attributes(response_data, parent_instance: nil)
-      mapper = create_response_mapper
+      mapper = Response::ResponseMapper.new(context)
       attributes = mapper.map_response(response_data)
       cache_connections(mapper, response_data, target: attributes, parent_instance: parent_instance)
       attributes
@@ -74,7 +74,7 @@ module ActiveShopifyGraphQL
     # @return [Hash, nil] Attribute hash with connection cache, or nil if not found
     def load_attributes(id)
       query = Query::QueryBuilder.build_single_record_query(context)
-      response_data = execute_query(query, id: id)
+      response_data = perform_graphql_query(query, id: id)
       return nil if response_data.nil?
 
       map_response_to_attributes(response_data)
@@ -86,15 +86,19 @@ module ActiveShopifyGraphQL
     # @param per_page [Integer] Number of records per page
     # @param after [String, nil] Cursor to fetch records after
     # @param before [String, nil] Cursor to fetch records before
+    # @param sort_key [String, nil] The Shopify sort key (e.g., "CREATED_AT")
+    # @param reverse [Boolean, nil] Whether to reverse the sort order
     # @param query_scope [Query::Scope] The query scope for navigation
     # @return [PaginatedResult] A paginated result with attribute hashes and page info
-    def load_paginated_collection(conditions:, per_page:, query_scope:, after: nil, before: nil)
+    def load_paginated_collection(conditions:, per_page:, query_scope:, after: nil, before: nil, sort_key: nil, reverse: nil)
       collection_query_name = context.query_name.pluralize
       variables = build_collection_variables(
         conditions,
         per_page: per_page,
         after: after,
-        before: before
+        before: before,
+        sort_key: sort_key,
+        reverse: reverse
       )
 
       query = Query::QueryBuilder.build_paginated_collection_query(
@@ -113,6 +117,11 @@ module ActiveShopifyGraphQL
       connection_loader.load_records(query_name, variables, parent, connection_config)
     end
 
+    def execute_query(query, **variables)
+      log_query(self.class.name, query, variables)
+      perform_graphql_query(query, **variables)
+    end
+
     # Abstract method for executing GraphQL queries
     def perform_graphql_query(query, **variables)
       raise NotImplementedError, "#{self.class} must implement perform_graphql_query"
@@ -120,10 +129,6 @@ module ActiveShopifyGraphQL
 
     private
 
-    def create_response_mapper
-      Response::ResponseMapper.new(context)
-    end
-
     def should_log?
       ActiveShopifyGraphQL.configuration.log_queries && ActiveShopifyGraphQL.configuration.logger
     end
@@ -175,17 +180,13 @@ module ActiveShopifyGraphQL
       raise ArgumentError, "Shopify query validation failed: #{messages.join(', ')}"
     end
 
-    def execute_query(query, **variables)
-      perform_graphql_query(query, **variables)
-    end
-
     def execute_query_and_validate_search_response(query, **variables)
       response = execute_query(query, **variables)
       validate_search_query_response(response)
       response
     end
 
-    def build_collection_variables(conditions, per_page:, after: nil, before: nil)
+    def build_collection_variables(conditions, per_page:, after: nil, before: nil, sort_key: nil, reverse: nil)
       search_query = SearchQuery.new(conditions)
       variables = { query: search_query.to_s }
 
@@ -197,6 +198,9 @@ module ActiveShopifyGraphQL
         variables[:after] = after if after
       end
 
+      variables[:sort_key] = sort_key if sort_key
+      variables[:reverse] = reverse unless reverse.nil?
+
       variables.compact
     end
 

data/lib/active_shopify_graphql/loaders/admin_api_loader.rb

@@ -4,12 +4,10 @@ module ActiveShopifyGraphQL
   module Loaders
     class AdminApiLoader < Loader
       def perform_graphql_query(query, **variables)
-        log_query("Admin API", query, variables)
+        executor = ActiveShopifyGraphQL.configuration.admin_api_executor
+        raise Error, "Admin API executor not configured. Please configure it using ActiveShopifyGraphQL.configure" unless executor
 
-        client = ActiveShopifyGraphQL.configuration.admin_api_client
-        raise Error, "Admin API client not configured. Please configure it using ActiveShopifyGraphQL.configure" unless client
-
-        client.execute(query, **variables)
+        executor.call(query, **variables)
       end
     end
   end

data/lib/active_shopify_graphql/loaders/customer_account_api_loader.rb

@@ -23,16 +23,11 @@ module ActiveShopifyGraphQL
         map_response_to_attributes(response_data)
       end
 
-      def client
-        client_class = ActiveShopifyGraphQL.configuration.customer_account_client_class
-        raise Error, "Customer Account API client class not configured" unless client_class
-
-        @client ||= client_class.from_config(@token)
-      end
-
       def perform_graphql_query(query, **variables)
-        log_query("Customer Account API", query, variables)
-        client.query(query, variables)
+        executor = ActiveShopifyGraphQL.configuration.customer_account_api_executor
+        raise Error, "Customer Account API executor not configured. Please configure it using ActiveShopifyGraphQL.configure" unless executor
+
+        executor.call(query, @token, **variables)
       end
 
       def initialization_args

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/connections.rb

@@ -102,7 +102,7 @@ module ActiveShopifyGraphQL::Model::Connections
           )
         else
           # Create a new proxy for custom options (don't cache these)
-          Connections::ConnectionProxy.new(
+          ActiveShopifyGraphQL::Connections::ConnectionProxy.new(
             parent: self,
             connection_name: name,
             connection_config: self.class.connections[name],

data/lib/active_shopify_graphql/model/finder_methods.rb

@@ -120,6 +120,18 @@ module ActiveShopifyGraphQL::Model::FinderMethods
       all.includes(*connection_names)
     end
 
+    # Set the sort order for the query
+    # @param sort_key [String] The Shopify sort key (e.g., "CREATED_AT", "UPDATED_AT")
+    # @param reverse [Boolean] Whether to reverse the sort order (optional)
+    # @return [Relation] A relation with order applied
+    #
+    # @example
+    #   Customer.order(sort_key: "CREATED_AT").where(country: "Canada")
+    #   Customer.where(status: "active").order(sort_key: "UPDATED_AT", reverse: true)
+    def order(sort_key:, reverse: nil)
+      all.order(sort_key: sort_key, reverse: reverse)
+    end
+
     private
 
     # Validates that selected attributes exist in the model

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

@@ -23,7 +23,7 @@ module ActiveShopifyGraphQL
 
       DEFAULT_PER_PAGE = 250
 
-      attr_reader :model_class, :included_connections, :conditions, :total_limit, :per_page
+      attr_reader :model_class, :included_connections, :conditions, :total_limit, :per_page, :sort_key, :reverse
 
       def initialize(
         model_class,
@@ -33,7 +33,9 @@ module ActiveShopifyGraphQL
         total_limit: nil,
         per_page: DEFAULT_PER_PAGE,
         loader_class: nil,
-        loader_extra_args: []
+        loader_extra_args: [],
+        sort_key: nil,
+        reverse: nil
       )
         @model_class = model_class
         @conditions = conditions
@@ -43,6 +45,8 @@ module ActiveShopifyGraphQL
         @per_page = [per_page, ActiveShopifyGraphQL.configuration.max_objects_per_paginated_query].min
         @loader_class = loader_class
         @loader_extra_args = loader_extra_args
+        @sort_key = sort_key
+        @reverse = reverse
         @loaded = false
         @records = nil
       end
@@ -66,6 +70,22 @@ module ActiveShopifyGraphQL
         spawn(conditions: new_conditions)
       end
 
+      # Set the sort order for the query
+      # @param sort_key [String] The Shopify sort key (e.g., "CREATED_AT", "UPDATED_AT")
+      # @param reverse [Boolean] Whether to reverse the sort order (optional)
+      # @return [Relation] A new relation with order applied
+      # @raise [ArgumentError] If order is called on a relation that already has ordering
+      # @example
+      #   Customer.where(email: "*@example.com").order(sort_key: "CREATED_AT", reverse: true)
+      def order(sort_key:, reverse: nil)
+        if has_ordering?
+          raise ArgumentError, "Chaining multiple order clauses is not supported. " \
+                               "Combine ordering in a single order call instead."
+        end
+
+        spawn(sort_key: sort_key, reverse: reverse)
+      end
+
       # Find a single record by conditions
       # @param conditions [Hash] The conditions to match
       # @return [Object, nil] The first matching record or nil
@@ -92,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?
@@ -302,6 +322,8 @@ module ActiveShopifyGraphQL
           per_page: effective_per_page,
           after: after,
           before: before,
+          sort_key: @sort_key,
+          reverse: @reverse,
           query_scope: build_query_scope_for_pagination
         )
       end
@@ -324,7 +346,9 @@ module ActiveShopifyGraphQL
           total_limit: changes.fetch(:total_limit, @total_limit),
           per_page: changes.fetch(:per_page, @per_page),
           loader_class: changes.fetch(:loader_class, @loader_class),
-          loader_extra_args: changes.fetch(:loader_extra_args, @loader_extra_args)
+          loader_extra_args: changes.fetch(:loader_extra_args, @loader_extra_args),
+          sort_key: changes.fetch(:sort_key, @sort_key),
+          reverse: changes.fetch(:reverse, @reverse)
         )
       end
 
@@ -341,6 +365,10 @@ module ActiveShopifyGraphQL
         end
       end
 
+      def has_ordering?
+        !@sort_key.nil?
+      end
+
       def build_loader
         klass = @loader_class || @model_class.send(:default_loader_class)
 

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 = "0.5.3"
+  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: 0.5.3
+  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