active_shopify_graphql 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e4003c2f9180531bc4c3a08e9c921d16402642c60c45c777ac49726b5a6a3f2
-  data.tar.gz: df5619e4f4845d688cdd1beb5228047d52022eca04e3b1c3479265ed1b59d9c1
+  metadata.gz: 3044e5a4ac6255ea55f7d10e48b0fe9a65825f813712f0cdc14e5993437e24bf
+  data.tar.gz: f6b9e14fe814887bf0af4b90c174088f7c912ead322cb353fd84a95b2c4799e2
 SHA512:
-  metadata.gz: d95bac2e81df933e3f3bbfbef55c486e2ba719271a93283b7e8fca72684a43208f0479be44286bd6ee99e9de427cdbdf44378aa20feb2c5895e3908ad112ab8d
-  data.tar.gz: f87d6688ac0374fb4821da10928b13127f8c272d090978646026dbf84adfc210039e8690e348cd570b48c28608a43252e998e5dea7dc527a193bc67e97d96440
+  metadata.gz: d5b38dbe06885fc9783e0f0980f1c690ad0a3edc0355f379bff6c0277eb0d69c76c07824d31295a020272b648ee8cd90c812e7399c75dc629650a9681df04b2f
+  data.tar.gz: 6bdfb30c5888e3532cd19325769d460470c044d5db9c47ebf4b52bec368e8baaccfc65660d2696e04f978bf3d5d178e15a914718925a82b08f655fea8a3d25bf

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops:
   NewCops: enable
+  SuggestExtensions: false
 
 Style/StringLiterals:
   Enabled: false
@@ -63,3 +64,6 @@ Naming/BlockForwarding:
 
 Lint/DuplicateBranch:
   Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false

data/README.md

@@ -52,12 +52,10 @@ end
 
 ### Basic Model Setup
 
-Create a model that includes `ActiveShopifyGraphQL::Base` and define attributes directly:
+Create a model that inherits from `ActiveShopifyGraphQL::Model` and define attributes directly:
 
 ```ruby
-class Customer
-  include ActiveShopifyGraphQL::Base
-
+class Customer < ActiveShopifyGraphQL::Model
   # Define the GraphQL type
   graphql_type "Customer"
 
@@ -75,6 +73,37 @@ class Customer
 end
 ```
 
+### Application Base Class (Recommended)
+
+For consistency and to share common behavior across all your Shopify GraphQL models, we recommend creating an `ApplicationShopifyGqlRecord` base class, similar to Rails' `ApplicationRecord`:
+
+```ruby
+# app/models/application_shopify_gql_record.rb
+class ApplicationShopifyRecord < ActiveShopifyGraphQL::Model
+  # Extract numeric ID from Shopify GID
+  attribute :id, transform: ->(id) { id.split("/").last }
+  # Keep the original GID available
+  attribute :gid, path: "id"
+end
+```
+
+Then inherit from this base class in your models:
+
+```ruby
+class Customer < ApplicationShopifyRecord
+  graphql_type "Customer"
+
+  attribute :name, path: "displayName"
+  attribute :email, path: "defaultEmailAddress.emailAddress"
+  attribute :created_at, type: :datetime
+end
+```
+
+This pattern provides:
+- **Consistent ID handling**: All models automatically get a numeric `id` and full `gid`
+- **Shared behavior**: Add validations, methods, or transformations once for all models
+- **Clear inheritance**: The class definition line clearly shows the persistence layer
+
 ### Defining Attributes
 
 Attributes are now defined directly in the model class using the `attribute` method. The GraphQL fragments and response mapping are automatically generated!
@@ -82,9 +111,7 @@ Attributes are now defined directly in the model class using the `attribute` met
 #### Basic Attribute Definition
 
 ```ruby
-class Customer
-  include ActiveShopifyGraphQL::Base
-
+class Customer < ActiveShopifyGraphQL::Model
   graphql_type "Customer"
 
   # Define attributes with automatic GraphQL path inference and type coercion
@@ -124,9 +151,7 @@ attribute :name,
 Shopify metafields can be easily accessed using the `metafield_attribute` method:
 
 ```ruby
-class Product
-  include ActiveShopifyGraphQL::Base
-
+class Product < ActiveShopifyGraphQL::Model
   graphql_type "Product"
 
   # Regular attributes
@@ -148,9 +173,7 @@ The metafield attributes automatically generate the correct GraphQL syntax and h
 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
-
+class Product < ActiveShopifyGraphQL::Model
   graphql_type "Product"
 
   attribute :id, type: :string
@@ -166,7 +189,7 @@ class Product
   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 } } } } }'
+    raw_graphql: 'metafield(namespace: "bundles", key: "items") { references(first: 10) { nodes { ... on Product { id title } } } }'
 end
 ```
 
@@ -175,9 +198,7 @@ end
 For models that need different attributes depending on the API being used, you can define loader-specific overrides:
 
 ```ruby
-class Customer
-  include ActiveShopifyGraphQL::Base
-
+class Customer < ActiveShopifyGraphQL::Model
   graphql_type "Customer"
 
   # Default attributes (used by all loaders)
@@ -234,7 +255,7 @@ customer = Customer.with_loader(MyCustomLoader).find(id)
 Use the `where` method to query multiple records using Shopify's search syntax:
 
 ```ruby
-# Simple conditions
+# Hash-based queries (safe, with automatic escaping)
 customers = Customer.where(email: "john@example.com")
 
 # Range queries
@@ -248,8 +269,106 @@ customers = Customer.where(first_name: "John Doe")
 customers = Customer.where({ email: "john@example.com" }, limit: 100)
 ```
 
+#### String-based Queries for Advanced Syntax
+
+For advanced queries like wildcard matching, use string-based queries:
+
+```ruby
+# Raw string queries (user responsible for proper escaping)
+variants = ProductVariant.where("sku:*")  # Wildcard matching
+customers = Customer.where("email:*@example.com AND orders_count:>5")
+
+# String queries with parameter binding (safe, with automatic escaping)
+# Positional parameters
+variants = ProductVariant.where("sku:? AND product_id:?", "Test's Product", 123)
+
+# Named parameters (as hash)
+customers = Customer.where("email::email AND first_name::name",
+                          { email: "test@example.com", name: "John" })
+
+# Named parameters (as keyword arguments - more convenient!)
+variants = ProductVariant.where("sku::sku", sku: "Test's Product")
+```
+
+**Query safety levels:**
+- **Hash queries**: Fully safe, all values are automatically escaped (wildcards become literals)
+- **String with binding**: Safe, bound parameters are automatically escaped
+- **Raw strings**: User responsible for escaping; allows advanced syntax like wildcards
+
 The `where` method automatically converts Ruby conditions into Shopify's GraphQL query syntax and validates that the query fields are supported by Shopify.
 
+### Pagination
+
+ActiveShopifyGraphQL supports cursor-based pagination for efficiently working with large result sets. Queries return a chainable `Query::Scope` that provides both automatic and manual pagination.
+
+#### Basic Pagination with Limits
+
+Use the `limit` method to control the total number of records fetched:
+
+```ruby
+# Fetch up to 100 records (automatically handles pagination behind the scenes)
+variants = ProductVariant.where(sku: "*").limit(100).to_a
+
+# Chainable with other query methods
+customers = Customer.where(email: "*@example.com").limit(500).to_a
+```
+
+#### Manual Pagination
+
+Use `in_pages` without a block to manually navigate through pages:
+
+```ruby
+# Get first page (50 records per page)
+page = ProductVariant.where(sku: "FRZ*").in_pages(of: 50)
+
+page.size              # => 50
+page.has_next_page?    # => true
+page.end_cursor        # => "eyJsYXN0X2lk..."
+
+# Navigate to next page
+next_page = page.next_page
+next_page.size         # => 50
+
+# Navigate backwards
+prev_page = next_page.previous_page
+```
+
+#### Automatic Pagination with Blocks
+
+Process records in batches to control memory usage:
+
+```ruby
+# Process 10 records at a time
+ProductVariant.where(sku: "*").in_pages(of: 10) do |page|
+  page.each do |variant|
+    MemoryExpensiveThing.run(variant)
+  end
+end
+
+# Combine with limit to stop after a certain number of records
+ProductVariant.where(sku: "*").limit(500).in_pages(of: 50) do |page|
+  # Processes 10 pages of 50 records each, then stops
+  process_batch(page.to_a)
+end
+```
+
+#### Lazy Enumeration
+
+The `Query::Scope` returned by `where` is enumerable and lazy-loads records:
+
+```ruby
+# These don't execute queries immediately
+scope = Customer.where(email: "*@example.com")
+
+# Query executes when you iterate or convert to array
+scope.each { |customer| puts customer.email }
+scope.to_a    # Returns array of all records
+scope.first   # Fetches just the first record
+scope.empty?  # Checks if any records exist
+```
+
+**Note:** Shopify imposes a maximum of 250 records per page. The `in_pages(of: n)` method will cap `n` at 250.
+
 ### Optimizing Queries with Select
 
 Use the `select` method to only fetch specific attributes, reducing GraphQL query size and improving performance:
@@ -277,9 +396,7 @@ ActiveShopifyGraphQL provides ActiveRecord-like associations to define relations
 Use `has_many` to define one-to-many relationships:
 
 ```ruby
-class Customer
-  include ActiveShopifyGraphQL::Base
-
+class Customer < ActiveShopifyGraphQL::Model
   graphql_type "Customer"
 
   attribute :id, type: :string
@@ -314,15 +431,42 @@ customer.rewards
 Use `has_one` to define one-to-one relationships:
 
 ```ruby
-class Order
-  include ActiveShopifyGraphQL::Base
-
+class Order < ActiveShopifyGraphQL::Model
   has_one :billing_address, class_name: 'Address'
 end
 ```
 
 The associations automatically handle Shopify GID format conversion, extracting numeric IDs when needed for querying related records.
 
+## Bridging ActiveRecord with GraphQL
+
+The `GraphQLAssociations` module allows ActiveRecord models (or duck-typed objects) to define associations to Shopify GraphQL models:
+
+```ruby
+class Reward < ApplicationRecord
+  include ActiveShopifyGraphQL::GraphQLAssociations
+
+  belongs_to_graphql :customer                     # Expects shopify_customer_id column
+  has_one_graphql :primary_address,
+    class_name: "Address",
+    foreign_key: :customer_id
+  has_many_graphql :variants,
+    class_name: "ProductVariant"
+end
+
+reward = Reward.find(1)
+reward.customer        # Loads Customer from shopify_customer_id
+reward.primary_address # Queries Address.where(customer_id: reward.shopify_customer_id).first
+reward.variants        # Queries ProductVariant.where({})
+```
+
+**Available associations:**
+- `belongs_to_graphql` - Loads single GraphQL object via stored GID/ID
+- `has_one_graphql` - Queries first GraphQL object matching foreign key
+- `has_many_graphql` - Queries multiple GraphQL objects with optional filtering
+
+All associations support `class_name`, `foreign_key`, `primary_key`, and `loader_class` options. Results are automatically cached and setter methods are provided for testing.
+
 ## GraphQL Connections
 
 ActiveShopifyGraphQL supports GraphQL connections for loading related data from Shopify APIs. Connections provide both lazy and eager loading patterns.
@@ -332,9 +476,7 @@ ActiveShopifyGraphQL supports GraphQL connections for loading related data from
 Use the `connection` class method to define connections to other ActiveShopifyGraphQL models:
 
 ```ruby
-class Customer
-  include ActiveShopifyGraphQL::Base
-
+class Customer < ActiveShopifyGraphQL::Model
   graphql_type 'Customer'
 
   attribute :id
@@ -367,9 +509,7 @@ class Customer
     }
 end
 
-class Order
-  include ActiveShopifyGraphQL::Base
-
+class Order < ActiveShopifyGraphQL::Model
   graphql_type 'Order'
 
   attribute :id
@@ -385,10 +525,10 @@ fragment CustomerFragment on Customer {
   id
   displayName
   orders(first: 2) {
-    edges { node { id name } }
+    nodes { id name }
   }
   recent_orders: orders(first: 5, reverse: true, sortKey: CREATED_AT) {
-    edges { node { id name } }
+    nodes { id name }
   }
 }
 ```
@@ -458,9 +598,7 @@ puts customer.orders.loaded?    # => This won't be a proxy since data was eager
 For connections that should always be loaded, you can use the `eager_load: true` parameter when defining the connection. This will automatically include the connection in all find and where queries without needing to explicitly use `includes`:
 
 ```ruby
-class Customer
-  include ActiveShopifyGraphQL::Base
-
+class Customer < ActiveShopifyGraphQL::Model
   graphql_type 'Customer'
 
   attribute :id
@@ -494,25 +632,21 @@ query customer($id: ID!) {
 
     # Eager-loaded connections
     orders(first: 10, sortKey: CREATED_AT, reverse: false) {
-      edges {
-        node {
-          id
-          name
-          totalPriceSet {
-            shopMoney {
-              amount
-            }
+      nodes {
+        id
+        name
+        totalPriceSet {
+          shopMoney {
+            amount
           }
         }
       }
     }
     addresses(first: 5, sortKey: CREATED_AT, reverse: false) {
-      edges {
-        node {
-          id
-          address1
-          city
-        }
+      nodes {
+        id
+        address1
+        city
       }
     }
   }
@@ -558,9 +692,7 @@ When you have bidirectional relationships between models, you can use the `inver
 #### Basic Usage
 
 ```ruby
-class Product
-  include ActiveShopifyGraphQL::Base
-
+class Product < ActiveShopifyGraphQL::Model
   graphql_type 'Product'
 
   attribute :id
@@ -573,9 +705,7 @@ class Product
     default_arguments: { first: 10 }
 end
 
-class ProductVariant
-  include ActiveShopifyGraphQL::Base
-
+class ProductVariant < ActiveShopifyGraphQL::Model
   graphql_type 'ProductVariant'
 
   attribute :id
@@ -637,9 +767,10 @@ 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 with cursors
+- [x] Support for paginating query results with cursors
 - [ ] Better error handling and retry mechanisms for GraphQL API calls
 - [ ] Caching layer for frequently accessed data
+- [ ] Multiple `.where` chaining with possibility of using `.not`
 
 ## Development
 

data/lib/active_shopify_graphql/configuration.rb

@@ -3,27 +3,14 @@
 module ActiveShopifyGraphQL
   # Configuration class for setting up external dependencies
   class Configuration
-    attr_accessor :admin_api_client, :customer_account_client_class, :logger, :log_queries, :compact_queries
+    attr_accessor :admin_api_client, :customer_account_client_class, :logger, :log_queries, :max_objects_per_paginated_query
 
     def initialize
       @admin_api_client = nil
       @customer_account_client_class = nil
       @logger = nil
       @log_queries = false
-      @compact_queries = false
+      @max_objects_per_paginated_query = 250
     end
   end
-
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
-
-  def self.configure
-    yield(configuration)
-  end
-
-  # Reset configuration (useful for testing)
-  def self.reset_configuration!
-    @configuration = Configuration.new
-  end
 end

data/lib/active_shopify_graphql/connections/connection_loader.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  module Connections
+    # Handles loading records for GraphQL connections.
+    # Refactored to use LoaderContext for cleaner parameter passing.
+    class ConnectionLoader
+      attr_reader :context
+
+      def initialize(context, loader_instance:)
+        @context = context
+        @loader_instance = loader_instance
+      end
+
+      # Load records for a connection query
+      # @param query_name [String] The connection field name (e.g., 'orders', 'addresses')
+      # @param variables [Hash] The GraphQL variables (first, sort_key, reverse, query)
+      # @param parent [Object] The parent object that owns this connection
+      # @param connection_config [Hash] The connection configuration
+      # @return [Array<Object>] Array of model instances
+      def load_records(query_name, variables, parent = nil, connection_config = nil)
+        is_nested = connection_config&.dig(:nested) || parent.respond_to?(:id)
+
+        if is_nested && parent
+          load_nested_connection(query_name, variables, parent, connection_config)
+        else
+          load_root_connection(query_name, variables, connection_config)
+        end
+      end
+
+      private
+
+      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.camelize(:lower)
+        singular = connection_config&.dig(:type) == :singular
+
+        query = Query::QueryBuilder.build_connection_query(
+          @context,
+          query_name: query_name,
+          variables: variables,
+          parent_query: "#{parent_query_name}(id: $id)",
+          singular: singular
+        )
+
+        parent_id = extract_gid(parent)
+        response_data = @loader_instance.perform_graphql_query(query, id: parent_id)
+
+        return [] if response_data.nil?
+
+        mapper = Response::ResponseMapper.new(@context)
+        attributes = mapper.map_nested_connection_response(response_data, query_name, parent, connection_config)
+
+        # ResponseMapper now returns attributes, need to build instances
+        if singular
+          return nil if attributes.nil?
+
+          wire_inverse_of(parent, attributes, connection_config)
+          ModelBuilder.build(@context.model_class, attributes)
+        else
+          return [] if attributes.nil? || attributes.empty?
+
+          attributes.each { |attrs| wire_inverse_of(parent, attrs, connection_config) }
+          ModelBuilder.build_many(@context.model_class, attributes)
+        end
+      end
+
+      def load_root_connection(query_name, variables, connection_config)
+        singular = connection_config&.dig(:type) == :singular
+
+        query = Query::QueryBuilder.build_connection_query(
+          @context,
+          query_name: query_name,
+          variables: variables,
+          parent_query: nil,
+          singular: singular
+        )
+
+        response_data = @loader_instance.perform_graphql_query(query)
+
+        return [] if response_data.nil?
+
+        mapper = Response::ResponseMapper.new(@context)
+        attributes = mapper.map_connection_response(response_data, query_name, connection_config)
+
+        # ResponseMapper now returns attributes, need to build instances
+        if singular
+          return nil if attributes.nil?
+
+          ModelBuilder.build(@context.model_class, attributes)
+        else
+          return [] if attributes.nil? || attributes.empty?
+
+          ModelBuilder.build_many(@context.model_class, attributes)
+        end
+      end
+
+      # Wire up inverse_of associations by adding parent to attributes 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]
+        attributes[:_connection_cache] ||= {}
+
+        # Check the type of the inverse connection
+        target_class = @context.model_class
+        return unless target_class.respond_to?(:connections) && target_class.connections[inverse_name]
+
+        inverse_type = target_class.connections[inverse_name][:type]
+        attributes[:_connection_cache][inverse_name] =
+          if inverse_type == :singular
+            parent
+          else
+            # For collection inverses, wrap parent in an array
+            [parent]
+          end
+      end
+
+      def extract_gid(parent)
+        return parent.gid if parent.respond_to?(:gid) && !parent.gid.nil?
+
+        id_value = parent.id
+        parent_type = resolve_parent_type(parent)
+
+        GidHelper.normalize_gid(id_value, parent_type)
+      end
+
+      def resolve_parent_type(parent)
+        klass = parent.class
+
+        if klass.respond_to?(:graphql_type_for_loader)
+          klass.graphql_type_for_loader(@context.loader_class)
+        elsif klass.respond_to?(:graphql_type)
+          klass.graphql_type
+        else
+          klass.name
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/gid_helper.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'global_id'
+
 module ActiveShopifyGraphQL
   # Helper module for handling Shopify Global IDs (GIDs)
   # Provides utilities for parsing and building GIDs according to the URI::GID standard