active_shopify_graphql 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f8f9c57e3dd7f5371ace9fb8d3db79d796a0aa34890065d4727ae7a45a0723b
-  data.tar.gz: 16d8e5361a00e4aaa2b166ba8108496a8564e669fc16c76e68e4ed058df12a23
+  metadata.gz: f0b5f3a4ce7ed92feb8483e2c064379788138d7a7336daa849a81715fd0dd3f2
+  data.tar.gz: b48985b14a5e07a5e5273431d82c06756dfc7feab40ddd27f65fa313c080d261
 SHA512:
-  metadata.gz: c30453eafcf98bc563f309e2a5762373615ad9a23c0b8d0c6e3c0919e5e8490088974d0d187582e6a55b0d012d4cc2e9c3abcc77cb2c638bd4acd8098be1b032
-  data.tar.gz: 1b190403f8fcdee4d69d35b534c168b63200a87aca06a6cbf465ea09dc873b3d723597e3f99201acbd8e0d4ed9618897af028dbcf73653be891391cc6d383d23
+  metadata.gz: 5f7cd6debcc40234ea46da5b8e88332a6c715db5d78ef82040ec1827a963557b60589f70df2261d09f6b08e699233b2aad7eaf00eb20eb6a2f80eb35608d6258
+  data.tar.gz: e3d0c95ba71e3be17f0a57ba26cd6f25d7c6ea783dc4b0608609f6344bf783ef2aec0e5b532b83d1a90084c3e3389bc8018396911a02c2da06d9f2c523b33c66

data/.rubocop.yml

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

data/AGENTS.md

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

data/README.md

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

data/lib/active_shopify_graphql/associations.rb

@@ -36,9 +36,6 @@ module ActiveShopifyGraphQL
           primary_key_value = send(association_primary_key)
           return @_association_cache[name] = [] if primary_key_value.blank?
 
-          # Extract numeric ID from Shopify GID if needed
-          primary_key_value = primary_key_value.to_plain_id if primary_key_value.gid?
-
           association_class = association_class_name.constantize
           @_association_cache[name] = association_class.where(association_foreign_key => primary_key_value)
         end
@@ -73,7 +70,14 @@ module ActiveShopifyGraphQL
           return @_association_cache[name] = nil if primary_key_value.blank?
 
           # Extract numeric ID from Shopify GID if needed
-          primary_key_value = primary_key_value.to_plain_id if primary_key_value.gid?
+          if primary_key_value.is_a?(String)
+            begin
+              parsed_gid = URI::GID.parse(primary_key_value)
+              primary_key_value = parsed_gid.model_id
+            rescue URI::InvalidURIError, URI::BadURIError, ArgumentError
+              # Not a GID, use value as-is
+            end
+          end
 
           association_class = association_class_name.constantize
           @_association_cache[name] = association_class.find_by(association_foreign_key => primary_key_value)

data/lib/active_shopify_graphql/attributes.rb

@@ -13,9 +13,10 @@ module ActiveShopifyGraphQL
       # @param null [Boolean] Whether the attribute can be null (default: true)
       # @param default [Object] Default value when GraphQL response is nil
       # @param transform [Proc] Custom transform block for the value
-      def attribute(name, path: nil, type: :string, null: true, default: nil, transform: nil)
+      # @param raw_graphql [String] Raw GraphQL string to inject directly (escape hatch for unsupported features)
+      def attribute(name, path: nil, type: :string, null: true, default: nil, transform: nil, raw_graphql: nil)
         path ||= infer_path(name)
-        config = { path: path, type: type, null: null, default: default, transform: transform }
+        config = { path: path, type: type, null: null, default: default, transform: transform, raw_graphql: raw_graphql }
 
         if @current_loader_context
           # Store in loader-specific context

data/lib/active_shopify_graphql/base.rb

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

data/lib/active_shopify_graphql/connection_loader.rb

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

data/lib/active_shopify_graphql/connections/connection_proxy.rb

@@ -100,6 +100,9 @@ module ActiveShopifyGraphQL
           @connection_config
         ) || []
 
+        # Populate inverse cache if inverse_of is specified
+        populate_inverse_cache(@records, @connection_config, @parent)
+
         @loaded = true
       end
 
@@ -107,6 +110,35 @@ module ActiveShopifyGraphQL
         default_args = @connection_config[:default_arguments] || {}
         default_args.merge(@options).compact
       end
+
+      def populate_inverse_cache(records, connection_config, parent)
+        return unless connection_config[:inverse_of]
+        return if records.nil? || (records.is_a?(Array) && records.empty?)
+
+        inverse_name = connection_config[:inverse_of]
+        target_class = connection_config[:class_name].constantize
+
+        # Ensure target class has the inverse connection defined
+        return unless target_class.respond_to?(:connections) && target_class.connections[inverse_name]
+
+        inverse_type = target_class.connections[inverse_name][:type]
+        records_array = records.is_a?(Array) ? records : [records]
+
+        records_array.each do |record|
+          next unless record
+
+          record.instance_variable_set(:@_connection_cache, {}) unless record.instance_variable_get(:@_connection_cache)
+          cache = record.instance_variable_get(:@_connection_cache)
+
+          cache[inverse_name] =
+            if inverse_type == :singular
+              parent
+            else
+              # For collection inverses, wrap parent in an array
+              [parent]
+            end
+        end
+      end
     end
   end
 end

data/lib/active_shopify_graphql/connections.rb

@@ -17,14 +17,14 @@ module ActiveShopifyGraphQL
     class_methods do
       # Define a singular connection (returns a single object)
       # @see #connection
-      def has_one_connected(name, **options)
-        connection(name, type: :singular, **options)
+      def has_one_connected(name, inverse_of: nil, **options)
+        connection(name, type: :singular, inverse_of: inverse_of, **options)
       end
 
       # Define a plural connection (returns a collection via edges)
       # @see #connection
-      def has_many_connected(name, **options)
-        connection(name, type: :connection, **options)
+      def has_many_connected(name, inverse_of: nil, **options)
+        connection(name, type: :connection, inverse_of: inverse_of, **options)
       end
 
       # Define a GraphQL connection to another ActiveShopifyGraphQL model
@@ -36,7 +36,8 @@ module ActiveShopifyGraphQL
       # @param eager_load [Boolean] Whether to automatically eager load this connection (default: false)
       # @param type [Symbol] The type of connection (:connection, :singular). Default is :connection.
       # @param default_arguments [Hash] Default arguments to pass to the GraphQL query (e.g. first: 10)
-      def connection(name, class_name: nil, query_name: nil, foreign_key: nil, loader_class: nil, eager_load: false, type: :connection, default_arguments: {})
+      # @param inverse_of [Symbol] The name of the inverse connection on the target model (optional)
+      def connection(name, class_name: nil, query_name: nil, foreign_key: nil, loader_class: nil, eager_load: false, type: :connection, default_arguments: {}, inverse_of: nil)
         # Infer defaults
         connection_class_name = class_name || name.to_s.classify
 
@@ -56,9 +57,13 @@ module ActiveShopifyGraphQL
           nested: true, # Always treated as nested (accessed via parent field)
           target_class_name: connection_class_name,
           original_name: name,
-          default_arguments: default_arguments
+          default_arguments: default_arguments,
+          inverse_of: inverse_of
         }
 
+        # Validate inverse relationship if specified (validation is deferred to runtime)
+        validate_inverse_of!(name, connection_class_name, inverse_of) if inverse_of
+
         # Define the connection method that returns a proxy
         define_method name do |**options|
           # Check if this connection was eager loaded
@@ -74,6 +79,9 @@ module ActiveShopifyGraphQL
             # Load the record
             records = loader.load_connection_records(config[:query_name], options, self, config)
 
+            # Populate inverse cache if inverse_of is specified
+            populate_inverse_cache_for_connection(records, config, self)
+
             # Cache it
             @_connection_cache ||= {}
             @_connection_cache[name] = records
@@ -123,30 +131,19 @@ module ActiveShopifyGraphQL
         # Merge manual and automatic connections
         all_included_connections = (connection_names + auto_included_connections).uniq
 
-        # Create a new class that inherits from self with eager loading enabled
-        included_class = Class.new(self)
-
-        # Store the connections to include
-        included_class.instance_variable_set(:@included_connections, all_included_connections)
-
-        # Override methods to use eager loading
-        included_class.define_singleton_method(:default_loader) do
-          @default_loader ||= superclass.default_loader.class.new(
-            superclass,
-            included_connections: @included_connections
-          )
-        end
-
-        # Preserve the original class name and model name for GraphQL operations
-        included_class.define_singleton_method(:name) { superclass.name }
-        included_class.define_singleton_method(:model_name) { superclass.model_name }
-        included_class.define_singleton_method(:connections) { superclass.connections }
-
-        included_class
+        # Create a scope object that holds the included connections
+        IncludesScope.new(self, all_included_connections)
       end
 
       private
 
+      def validate_inverse_of!(_name, _target_class_name, _inverse_name)
+        # Validation is deferred until runtime when connections are actually used
+        # This allows class definitions to be in any order
+        # The validation logic will be checked when inverse cache is populated
+        nil
+      end
+
       def validate_includes_connections!(connection_names)
         connection_names.each do |name|
           if name.is_a?(Hash)
@@ -166,5 +163,36 @@ module ActiveShopifyGraphQL
         end
       end
     end
+
+    # Instance method to populate inverse cache for lazy-loaded connections
+
+    def populate_inverse_cache_for_connection(records, connection_config, parent)
+      return unless connection_config[:inverse_of]
+      return if records.nil? || (records.is_a?(Array) && records.empty?)
+
+      inverse_name = connection_config[:inverse_of]
+      target_class = connection_config[:class_name].constantize
+
+      # Ensure target class has the inverse connection defined
+      return unless target_class.respond_to?(:connections) && target_class.connections[inverse_name]
+
+      inverse_type = target_class.connections[inverse_name][:type]
+      records_array = records.is_a?(Array) ? records : [records]
+
+      records_array.each do |record|
+        next unless record
+
+        record.instance_variable_set(:@_connection_cache, {}) unless record.instance_variable_get(:@_connection_cache)
+        cache = record.instance_variable_get(:@_connection_cache)
+
+        cache[inverse_name] =
+          if inverse_type == :singular
+            parent
+          else
+            # For collection inverses, wrap parent in an array
+            [parent]
+          end
+      end
+    end
   end
 end

data/lib/active_shopify_graphql/finder_methods.rb

@@ -8,14 +8,23 @@ module ActiveShopifyGraphQL
       # Find a single record by ID using the provided loader
       # @param id [String, Integer] The record ID (will be converted to GID automatically)
       # @param loader [ActiveShopifyGraphQL::Loader] The loader to use for fetching data
-      # @return [Object, nil] The model instance or nil if not found
+      # @return [Object] The model instance
+      # @raise [ActiveShopifyGraphQL::ObjectNotFoundError] If the record is not found
       def find(id, loader: default_loader)
         gid = GidHelper.normalize_gid(id, model_name.name.demodulize)
-        attributes = loader.load_attributes(gid)
 
-        return nil if attributes.nil?
+        # If we have included connections, we need to handle inverse_of properly
+        result =
+          if loader.has_included_connections?
+            loader.load_with_instance(gid, self)
+          else
+            attributes = loader.load_attributes(gid)
+            attributes.nil? ? nil : new(attributes)
+          end
+
+        raise ObjectNotFoundError, "Couldn't find #{name} with id=#{id}" if result.nil?
 
-        new(attributes)
+        result
       end
 
       # Returns the default loader for this model's queries
@@ -72,6 +81,25 @@ module ActiveShopifyGraphQL
         selected_class
       end
 
+      # Find a single record by attribute conditions
+      # @param conditions [Hash] The conditions to query (e.g., { email: "example@test.com", first_name: "John" })
+      # @param options [Hash] Options hash containing loader
+      # @option options [ActiveShopifyGraphQL::Loader] :loader The loader to use for fetching data
+      # @return [Object, nil] The first matching model instance or nil if not found
+      # @raise [ArgumentError] If any attribute is not valid for querying
+      #
+      # @example
+      #   # Keyword argument style (recommended)
+      #   Customer.find_by(email: "john@example.com")
+      #   Customer.find_by(first_name: "John", country: "Canada")
+      #   Customer.find_by(orders_count: { gte: 5 })
+      #
+      #   # Hash style with options
+      #   Customer.find_by({ email: "john@example.com" }, loader: custom_loader)
+      def find_by(conditions_or_first_condition = {}, *args, **options)
+        where(conditions_or_first_condition, *args, **options.merge(limit: 1)).first
+      end
+
       # Query for multiple records using attribute conditions
       # @param conditions [Hash] The conditions to query (e.g., { email: "example@test.com", first_name: "John" })
       # @param options [Hash] Options hash containing loader and limit (when first arg is a Hash)
@@ -130,7 +158,7 @@ module ActiveShopifyGraphQL
         return unless invalid_attrs.any?
 
         raise ArgumentError, "Invalid attributes for #{name}: #{invalid_attrs.join(', ')}. " \
-                           "Available attributes are: #{available_attrs.join(', ')}"
+                             "Available attributes are: #{available_attrs.join(', ')}"
       end
 
       # Gets all available attributes for selection