active_shopify_graphql 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e4003c2f9180531bc4c3a08e9c921d16402642c60c45c777ac49726b5a6a3f2
-  data.tar.gz: df5619e4f4845d688cdd1beb5228047d52022eca04e3b1c3479265ed1b59d9c1
+  metadata.gz: f0b5f3a4ce7ed92feb8483e2c064379788138d7a7336daa849a81715fd0dd3f2
+  data.tar.gz: b48985b14a5e07a5e5273431d82c06756dfc7feab40ddd27f65fa313c080d261
 SHA512:
-  metadata.gz: d95bac2e81df933e3f3bbfbef55c486e2ba719271a93283b7e8fca72684a43208f0479be44286bd6ee99e9de427cdbdf44378aa20feb2c5895e3908ad112ab8d
-  data.tar.gz: f87d6688ac0374fb4821da10928b13127f8c272d090978646026dbf84adfc210039e8690e348cd570b48c28608a43252e998e5dea7dc527a193bc67e97d96440
+  metadata.gz: 5f7cd6debcc40234ea46da5b8e88332a6c715db5d78ef82040ec1827a963557b60589f70df2261d09f6b08e699233b2aad7eaf00eb20eb6a2f80eb35608d6258
+  data.tar.gz: e3d0c95ba71e3be17f0a57ba26cd6f25d7c6ea783dc4b0608609f6344bf783ef2aec0e5b532b83d1a90084c3e3389bc8018396911a02c2da06d9f2c523b33c66

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops:
   NewCops: enable
+  SuggestExtensions: false
 
 Style/StringLiterals:
   Enabled: false

data/README.md

@@ -323,6 +323,35 @@ 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.

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

@@ -8,19 +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)
 
         # If we have included connections, we need to handle inverse_of properly
-        if loader.respond_to?(:load_with_instance) && loader.has_included_connections?
-          loader.load_with_instance(gid, self)
-        else
-          attributes = loader.load_attributes(gid)
-          return nil if attributes.nil?
+        result =
+          if loader.has_included_connections?
+            loader.load_with_instance(gid, self)
+          else
+            attributes = loader.load_attributes(gid)
+            attributes.nil? ? nil : new(attributes)
+          end
 
-          new(attributes)
-        end
+        raise ObjectNotFoundError, "Couldn't find #{name} with id=#{id}" if result.nil?
+
+        result
       end
 
       # Returns the default loader for this model's queries
@@ -77,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)

data/lib/active_shopify_graphql/graphql_associations.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module ActiveShopifyGraphQL
+  # Allows ActiveRecord (or duck-typed) objects to define associations to GraphQL objects
+  # This module bridges the gap between local database records and remote Shopify GraphQL data
+  #
+  # @example
+  #   class Reward < ApplicationRecord
+  #     include ActiveShopifyGraphQL::GraphQLAssociations
+  #
+  #     belongs_to_graphql :customer
+  #     has_many_graphql :variants, class: "ProductVariant", query_name: "productVariants"
+  #   end
+  #
+  #   reward = Reward.first
+  #   customer = reward.customer # => ActiveShopifyGraphQL::Customer instance
+  #   variants = reward.variants(first: 10) # => Array of ProductVariant instances
+  module GraphQLAssociations
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        attr_accessor :graphql_associations
+      end
+
+      self.graphql_associations = {}
+    end
+
+    class_methods do
+      # Define a belongs_to relationship with a GraphQL object
+      # Fetches a single GraphQL object using a stored GID or foreign key
+      #
+      # @param name [Symbol] The association name (e.g., :customer)
+      # @param class_name [String] The target GraphQL model class name (defaults to name.to_s.classify)
+      # @param foreign_key [Symbol, String] The attribute/column storing the GID or ID (defaults to "shopify_#{name}_id")
+      # @param loader_class [Class] Custom loader class (defaults to target class's default_loader)
+      #
+      # @example Basic usage
+      #   belongs_to_graphql :customer
+      #   # Expects: shopify_customer_id column with GID like "gid://shopify/Customer/123"
+      #
+      # @example With custom foreign key
+      #   belongs_to_graphql :customer, foreign_key: :customer_gid
+      #
+      # @example With custom class
+      #   belongs_to_graphql :owner, class_name: "Customer"
+      def belongs_to_graphql(name, class_name: nil, foreign_key: nil, loader_class: nil)
+        association_class_name = class_name || name.to_s.classify
+        association_foreign_key = foreign_key || "shopify_#{name}_id"
+
+        # Store association metadata
+        graphql_associations[name] = {
+          type: :belongs_to,
+          class_name: association_class_name,
+          foreign_key: association_foreign_key,
+          loader_class: loader_class
+        }
+
+        # Define the association method
+        define_method name do
+          return @_graphql_association_cache[name] if @_graphql_association_cache&.key?(name)
+
+          @_graphql_association_cache ||= {}
+
+          # Get the GID or ID value from the foreign key
+          gid_or_id = send(association_foreign_key)
+          return @_graphql_association_cache[name] = nil if gid_or_id.blank?
+
+          # Resolve the target class
+          target_class = association_class_name.constantize
+
+          # Determine which loader to use
+          loader = if self.class.graphql_associations[name][:loader_class]
+                     self.class.graphql_associations[name][:loader_class].new(target_class)
+                   else
+                     target_class.default_loader
+                   end
+
+          # Load and cache the GraphQL object
+          @_graphql_association_cache[name] = target_class.find(gid_or_id, loader: loader)
+        end
+
+        # Define setter method for testing/mocking
+        define_method "#{name}=" do |value|
+          @_graphql_association_cache ||= {}
+          @_graphql_association_cache[name] = value
+        end
+      end
+
+      # Define a has_one relationship with a GraphQL object
+      # Fetches a single GraphQL object using a where clause
+      #
+      # @param name [Symbol] The association name (e.g., :primary_address)
+      # @param class_name [String] The target GraphQL model class name (defaults to name.to_s.classify)
+      # @param foreign_key [Symbol, String] The attribute on GraphQL objects to filter by (e.g., :customer_id)
+      # @param primary_key [Symbol, String] The local attribute to use as filter value (defaults to :id)
+      # @param loader_class [Class] Custom loader class (defaults to target class's default_loader)
+      #
+      # @example Basic usage
+      #   has_one_graphql :primary_address, class_name: "Address", foreign_key: :customer_id
+      #   customer.primary_address # Returns first Address where customer_id matches
+      def has_one_graphql(name, class_name: nil, foreign_key: nil, primary_key: nil, loader_class: nil)
+        association_class_name = class_name || name.to_s.classify
+        association_primary_key = primary_key || :id
+        association_loader_class = loader_class
+
+        # Store association metadata
+        graphql_associations[name] = {
+          type: :has_one,
+          class_name: association_class_name,
+          foreign_key: foreign_key,
+          primary_key: association_primary_key,
+          loader_class: association_loader_class
+        }
+
+        # Define the association method
+        define_method name do
+          return @_graphql_association_cache[name] if @_graphql_association_cache&.key?(name)
+
+          @_graphql_association_cache ||= {}
+
+          # Get primary key value
+          primary_key_value = send(association_primary_key)
+          return @_graphql_association_cache[name] = nil if primary_key_value.blank?
+
+          # Resolve the target class
+          target_class = association_class_name.constantize
+
+          # Determine which loader to use
+          loader = if self.class.graphql_associations[name][:loader_class]
+                     self.class.graphql_associations[name][:loader_class].new(target_class)
+                   else
+                     target_class.default_loader
+                   end
+
+          # Query with foreign key filter if provided
+          result = if self.class.graphql_associations[name][:foreign_key]
+                     foreign_key_sym = self.class.graphql_associations[name][:foreign_key]
+                     query_conditions = { foreign_key_sym => primary_key_value }
+                     target_class.where(query_conditions, loader: loader).first
+                   end
+
+          # Cache the result
+          @_graphql_association_cache[name] = result
+        end
+
+        # Define setter method for testing/mocking
+        define_method "#{name}=" do |value|
+          @_graphql_association_cache ||= {}
+          @_graphql_association_cache[name] = value
+        end
+      end
+
+      # Define a has_many relationship with GraphQL objects
+      # Queries multiple GraphQL objects using a where clause or connection
+      #
+      # @param name [Symbol] The association name (e.g., :variants)
+      # @param class_name [String] The target GraphQL model class name (defaults to name.to_s.classify.singularize)
+      # @param query_name [String] The GraphQL query field name (defaults to class_name.pluralize.camelize(:lower))
+      # @param foreign_key [Symbol, String] The attribute on GraphQL objects to filter by (e.g., :customer_id)
+      # @param primary_key [Symbol, String] The local attribute to use as filter value (defaults to :id)
+      # @param loader_class [Class] Custom loader class (defaults to target class's default_loader)
+      # @param query_method [Symbol] Method to use for querying (:where or :connection, defaults to :where)
+      #
+      # @example Basic usage with where query
+      #   has_many_graphql :variants, class: "ProductVariant"
+      #   reward.variants # Uses where to query
+      #
+      # @example With custom query_name for a connection
+      #   has_many_graphql :line_items, query_name: "lineItems", query_method: :connection
+      #   order.line_items(first: 10)
+      #
+      # @example With filtering by foreign key
+      #   has_many_graphql :orders, foreign_key: :customer_id
+      #   # Queries orders where customer_id matches the local record's id
+      def has_many_graphql(name, class_name: nil, query_name: nil, foreign_key: nil, primary_key: nil, loader_class: nil, query_method: :where)
+        association_class_name = class_name || name.to_s.singularize.classify
+        association_primary_key = primary_key || :id
+        association_loader_class = loader_class
+        association_query_method = query_method
+
+        # Auto-determine query_name if not provided
+        association_query_name = query_name || name.to_s.camelize(:lower)
+
+        # Store association metadata
+        graphql_associations[name] = {
+          type: :has_many,
+          class_name: association_class_name,
+          query_name: association_query_name,
+          foreign_key: foreign_key,
+          primary_key: association_primary_key,
+          loader_class: association_loader_class,
+          query_method: association_query_method
+        }
+
+        # Define the association method
+        define_method name do |**options|
+          return @_graphql_association_cache[name] if @_graphql_association_cache&.key?(name) && options.empty?
+
+          @_graphql_association_cache ||= {}
+
+          # Get primary key value
+          primary_key_value = send(association_primary_key)
+          return @_graphql_association_cache[name] = [] if primary_key_value.blank?
+
+          # Resolve the target class
+          target_class = association_class_name.constantize
+
+          # Determine which loader to use
+          loader = if self.class.graphql_associations[name][:loader_class]
+                     self.class.graphql_associations[name][:loader_class].new(target_class)
+                   else
+                     target_class.default_loader
+                   end
+
+          # Build query based on query_method
+          result = if association_query_method == :connection
+                     # For connections, we need to handle this differently
+                     # This would typically be a nested connection on a parent object
+                     # For now, return empty array - real implementation would need parent context
+                     []
+                   elsif self.class.graphql_associations[name][:foreign_key]
+                     # Query with foreign key filter
+                     foreign_key_sym = self.class.graphql_associations[name][:foreign_key]
+                     query_conditions = { foreign_key_sym => primary_key_value }.merge(options)
+                     target_class.where(query_conditions, loader: loader)
+                   else
+                     # No foreign key specified, just query with provided options
+                     target_class.where(options, loader: loader)
+                   end
+
+          # Cache if no runtime options provided
+          @_graphql_association_cache[name] = result if options.empty?
+          result
+        end
+
+        # Define setter method for testing/mocking
+        define_method "#{name}=" do |value|
+          @_graphql_association_cache ||= {}
+          @_graphql_association_cache[name] = value
+        end
+      end
+    end
+  end
+end

data/lib/active_shopify_graphql/version.rb

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

data/lib/active_shopify_graphql.rb

@@ -23,6 +23,7 @@ require_relative "active_shopify_graphql/loaders/customer_account_api_loader"
 require_relative "active_shopify_graphql/loader_switchable"
 require_relative "active_shopify_graphql/finder_methods"
 require_relative "active_shopify_graphql/associations"
+require_relative "active_shopify_graphql/graphql_associations"
 require_relative "active_shopify_graphql/includes_scope"
 require_relative "active_shopify_graphql/connections"
 require_relative "active_shopify_graphql/attributes"
@@ -32,4 +33,5 @@ require_relative "active_shopify_graphql/base"
 
 module ActiveShopifyGraphQL
   class Error < StandardError; end
+  class ObjectNotFoundError < Error; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_shopify_graphql
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Nicolò Rebughini
@@ -79,6 +79,7 @@ files:
 - lib/active_shopify_graphql/finder_methods.rb
 - lib/active_shopify_graphql/fragment_builder.rb
 - lib/active_shopify_graphql/gid_helper.rb
+- lib/active_shopify_graphql/graphql_associations.rb
 - lib/active_shopify_graphql/graphql_type_resolver.rb
 - lib/active_shopify_graphql/includes_scope.rb
 - lib/active_shopify_graphql/loader.rb