Merge pull request #5575 from rmosolgo/dataloader-shorthands

exec-next: Add dataload: shorthands

Author: rmosolgo

guides/execution/next.md

@@ -111,32 +111,75 @@ This is a high-performance option for when you need to do I/O to generate result
 
 These fields use a _class method_ to map parent objects to field results, configured with `resolve_batch:`:
 
-  ```ruby
-  field :title, String, resolve_batch: :titles do
-    argument :language, Types::Language, required: false, default_value: "EN"
-  end
+```ruby
+field :title, String, resolve_batch: :titles do
+  argument :language, Types::Language, required: false, default_value: "EN"
+end
 
-  def self.titles(objects, context, language:)
-    # This is equivalent to plain `field :title, ...`, but for example:
-    objects.map { |obj| obj.title(language:) }
-  end
-  ```
+def self.titles(objects, context, language:)
+  # This is equivalent to plain `field :title, ...`, but for example:
+  objects.map { |obj| obj.title(language:) }
+end
+```
 
-  This is especially useful when batching Dataloader calls:
+This is especially useful when batching Dataloader calls:
 
-  ```ruby
-  class Types::Comment < BaseObject
-    field :post, Types::Post, resolve_batch: :posts
+```ruby
+class Types::Comment < BaseObject
+  field :author_rating, Integer, resolve_batch: true
 
-    # Use `.load_all(ids)` to fetch all in a single round-trip
-    def self.posts(objects, context)
-      # TODO: add a shorthand for this in GraphQL-Ruby
-      context.dataloader
-        .with(GraphQL::Dataloader::ActiveRecordSource)
-        .load_all(objects.map(&:post_id))
-    end
+  def self.author_rating(objects, context)
+    authors = context.dataload_all_records(objects, :author)
+    context.dataload_all(Sources::AuthorRating, authors)
   end
-  ```
+end
+```
+
+### Dataloader
+
+`Execution::Next` supports field configuration shorthands for common dataloader usage. Under the hood, these make sure data fetching is batched and cached.
+
+#### Sources
+
+Use a custom dataloader source from your application:
+
+```ruby
+class Types::CommentType
+  # Equivalent to `dataload(Sources::CommentRating, object)`
+  field :rating, Integer, dataload: Sources::CommentRating
+
+  # `using:`: A method to call to get a value to pass to dataloader
+  # `by: [...]`: An array of arguments to pass on to dataloader
+  #
+  # Equivalent to `dataload(Sources::ReadingDuration, :comment, object.body)
+  field :reading_duration, Integer, dataload: { with: Sources::ReadingDuration, using: :body, by: [:comment] }
+```
+
+#### Rails Associations
+
+Load ActiveRecord associations using {{ "GraphQL::Dataloader::ActiveRecordAssociationSource" | api_doc }}:
+
+```ruby
+class Types::CommentType < Types::BaseObject
+  # Equivalent to `dataload_association(:post)`
+  field :post, Types::Post, dataload: { association: true }
+  # Equivalent to `dataload_association(:user)
+  field :author, Types::Post, dataload: { association: :user }
+end
+```
+
+#### Rails Records
+
+Load ActiveRecord associations using {{ "GraphQL::Dataloader::ActiveRecordSource" | api_doc }}.
+
+```ruby
+class Types::SearchResult < Types::BaseObject
+  # Equivalent to `dataload_record(Post, object.post_id)`
+  field :post, Types::Post, dataload: { model: Post, using: :post_id }
+  # Equivalent to `dataload_record(User, object.created_by_handle, find_by: :handle)`
+  field :author, Types::User, dataload: { model: User, using: :created_by_handle, find_by: :handle }
+end
+```
 
 ### Legacy instance methods
 

lib/graphql/execution/next/field_resolve_step.rb

@@ -644,6 +644,27 @@ def resolve_batch(objects, context, args_hash)
             end
           when :dig
             objects.map { |o| o.dig(*@field_definition.execution_next_mode_key) }
+          when :dataload
+            if (k = @field_definition.execution_next_mode_key).is_a?(Class)
+              context.dataload_all(k, objects)
+            elsif (source_class = k[:with])
+              if (batch_args = k[:by])
+                context.dataload_all(source_class, *batch_args, objects)
+              else
+                context.dataload_all(source_class, objects)
+              end
+            elsif (model = k[:model])
+              value_method = k[:using]
+              values = objects.map(&value_method)
+              context.dataload_all_records(model, values, find_by: k[:find_by])
+            elsif (assoc = k[:association])
+              if assoc == true
+                assoc = @field_definition.original_name
+              end
+              context.dataload_all_associations(objects, assoc, scope: k[:scope])
+            else
+              raise ArgumentError, "Unexpected `dataload: ...` configuration: #{k.inspect}"
+            end
           when :resolver_class
             results = Array.new(objects.size, nil)
             ps = @pending_steps ||= []

lib/graphql/schema/field.rb

@@ -197,6 +197,7 @@ def method_conflict_warning?
       # @param resolve_batch [Symbol, true, nil] Used by {Schema.execute_next} map `objects` to a same-sized Array of results. Called on the owner type class with `objects, context, **arguments`.
       # @param resolve_each [Symbol, true, nil] Used by {Schema.execute_next} to get a value value for each item. Called on the owner type class with `object, context, **arguments`.
       # @param resolve_legacy_instance_method [Symbol, true, nil] Used by {Schema.execute_next} to get a value value for each item. Calls an instance method on the object type class.
+      # @param dataload [Class, Hash] Shorthand for making dataloader calls
       # @param max_page_size [Integer, nil] For connections, the maximum number of items to return from this field, or `nil` to allow unlimited results.
       # @param default_page_size [Integer, nil] For connections, the default number of items to return from this field, or `nil` to return unlimited results.
       # @param introspection [Boolean] If true, this field will be marked as `#introspection?` and the name may begin with `__`
@@ -219,7 +220,7 @@ def method_conflict_warning?
       # @param relay_nodes_field [Boolean] (Private, used by GraphQL-Ruby)
       # @param extras [Array<:ast_node, :parent, :lookahead, :owner, :execution_errors, :graphql_name, :argument_details, Symbol>] Extra arguments to be injected into the resolver for this field
       # @param definition_block [Proc] an additional block for configuring the field. Receive the field as a block param, or, if no block params are defined, then the block is `instance_eval`'d on the new {Field}.
-      def initialize(type: nil, name: nil, owner: nil, null: nil, description: NOT_CONFIGURED, comment: NOT_CONFIGURED, deprecation_reason: nil, method: nil, resolve_legacy_instance_method: nil, resolve_static: nil, resolve_each: nil, resolve_batch: nil, hash_key: nil, dig: nil, resolver_method: nil, connection: nil, max_page_size: NOT_CONFIGURED, default_page_size: NOT_CONFIGURED, scope: nil, introspection: false, camelize: true, trace: nil, complexity: nil, ast_node: nil, extras: EMPTY_ARRAY, extensions: EMPTY_ARRAY, connection_extension: self.class.connection_extension, resolver_class: nil, subscription_scope: nil, relay_node_field: false, relay_nodes_field: false, method_conflict_warning: true, broadcastable: NOT_CONFIGURED, arguments: EMPTY_HASH, directives: EMPTY_HASH, validates: EMPTY_ARRAY, fallback_value: NOT_CONFIGURED, dynamic_introspection: false, &definition_block)
+      def initialize(type: nil, name: nil, owner: nil, null: nil, description: NOT_CONFIGURED, comment: NOT_CONFIGURED, deprecation_reason: nil, method: nil, resolve_legacy_instance_method: nil, resolve_static: nil, resolve_each: nil, resolve_batch: nil, hash_key: nil, dig: nil, resolver_method: nil, connection: nil, max_page_size: NOT_CONFIGURED, default_page_size: NOT_CONFIGURED, scope: nil, introspection: false, camelize: true, trace: nil, complexity: nil, dataload: nil, ast_node: nil, extras: EMPTY_ARRAY, extensions: EMPTY_ARRAY, connection_extension: self.class.connection_extension, resolver_class: nil, subscription_scope: nil, relay_node_field: false, relay_nodes_field: false, method_conflict_warning: true, broadcastable: NOT_CONFIGURED, arguments: EMPTY_HASH, directives: EMPTY_HASH, validates: EMPTY_ARRAY, fallback_value: NOT_CONFIGURED, dynamic_introspection: false, &definition_block)
         if name.nil?
           raise ArgumentError, "missing first `name` argument or keyword `name:`"
         end
@@ -289,6 +290,9 @@ def initialize(type: nil, name: nil, owner: nil, null: nil, description: NOT_CON
         elsif resolve_legacy_instance_method
           @execution_next_mode = :resolve_legacy_instance_method
           @execution_next_mode_key = resolve_legacy_instance_method == true ? @method_sym : resolve_legacy_instance_method
+        elsif dataload
+          @execution_next_mode = :dataload
+          @execution_next_mode_key = dataload
         else
           @execution_next_mode = :direct_send
           @execution_next_mode_key = @method_sym

lib/graphql/schema/member/has_dataloader.rb

@@ -56,6 +56,16 @@ def dataload_record(model, find_by_value, find_by: nil)
           source.load(find_by_value)
         end
 
+        # @see dataload_record Like `dataload_record`, but accepts an Array of `find_by_values`
+        def dataload_all_records(model, find_by_values, find_by: nil)
+          source = if find_by
+            dataloader.with(Dataloader::ActiveRecordSource, model, find_by: find_by)
+          else
+            dataloader.with(Dataloader::ActiveRecordSource, model)
+          end
+          source.load_all(find_by_values)
+        end
+
         # Look up an associated record using a Rails association (via {Dataloader::ActiveRecordAssociationSource})
         # @param association_name [Symbol] A `belongs_to` or `has_one` association. (If a `has_many` association is named here, it will be selected without pagination.)
         # @param record [ActiveRecord::Base] The object that the association belongs to.
@@ -73,6 +83,16 @@ def dataload_association(record = object, association_name, scope: nil)
           end
           source.load(record)
         end
+
+        # @see dataload_association Like `dataload_assocation` but accepts an Array of records (required param)
+        def dataload_all_associations(records, association_name, scope: nil)
+          source = if scope
+            dataloader.with(Dataloader::ActiveRecordAssociationSource, association_name, scope)
+          else
+            dataloader.with(Dataloader::ActiveRecordAssociationSource, association_name)
+          end
+          source.load_all(records)
+        end
       end
     end
   end

lib/graphql/schema/member/has_fields.rb

@@ -48,6 +48,7 @@ module HasFields
         # @option kwargs [Boolean] :dynamic_introspection (Private, used by GraphQL-Ruby)
         # @option kwargs [Boolean] :relay_node_field (Private, used by GraphQL-Ruby)
         # @option kwargs [Boolean] :relay_nodes_field (Private, used by GraphQL-Ruby)
+        # @option kwargs [Class, Hash] :dataload Shorthand for dataloader lookups
         # @option kwargs [Array<:ast_node, :parent, :lookahead, :owner, :execution_errors, :graphql_name, :argument_details, Symbol>] :extras Extra arguments to be injected into the resolver for this field
         # @param kwargs [Hash] Keywords for defining the field. Any not documented here will be passed to your base field class where they must be handled.
         # @param definition_block [Proc] an additional block for configuring the field. Receive the field as a block param, or, if no block params are defined, then the block is `instance_eval`'d on the new {Field}.

spec/graphql/dataloader/active_record_association_source_spec.rb

@@ -3,50 +3,7 @@
 
 describe GraphQL::Dataloader::ActiveRecordAssociationSource do
   if testing_rails?
-    class VulfpeckSchema < GraphQL::Schema
-      class Album < GraphQL::Schema::Object
-        field :name, String
-      end
-      class Band < GraphQL::Schema::Object
-        field :albums, [Album] do
-          argument :genre, String, required: false
-          argument :reverse, Boolean, required: false, default_value: false
-          argument :unscoped, Boolean, required: false, default_value: false
-        end
-
-        def albums(genre: nil, reverse:, unscoped:)
-          if unscoped
-            scope = nil
-          else
-            scope = ::Album
-            if genre
-              scope = scope.where(band_genre: genre)
-            end
-
-            scope = if reverse
-              scope.order(name: :desc)
-            else
-              scope.order(:name)
-            end
-          end
-          dataload_association(:albums, scope: scope)
-        end
-      end
-
-      class Query < GraphQL::Schema::Object
-        field :band, Band do
-          argument :name, String
-        end
-
-        def band(name:)
-          ::Band.find_by(name: name)
-        end
-      end
-
-      query(Query)
-      use GraphQL::Dataloader
-    end
-
+    include VulfpeckSchemaHelpers
     it "works with different scopes on the same object at runtime" do
       query_str = <<~GRAPHQL
         {
@@ -67,13 +24,30 @@ def band(name:)
         }
       GRAPHQL
 
-      result = VulfpeckSchema.execute(query_str)
+      result = exec_query(query_str)
       assert_equal ["Mit Peck", "My First Car"], result["data"]["band"]["allAlbums"].map { |a| a["name"] }
       assert_equal ["Mit Peck", "My First Car"], result["data"]["band"]["unscopedAlbums"].map { |a| a["name"] }
       assert_equal ["My First Car", "Mit Peck"], result["data"]["band"]["reverseAlbums"].map { |a| a["name"] }
       assert_equal [], result["data"]["band"]["countryAlbums"]
     end
 
+    it "works with field shorthands" do
+      skip("NOT IMPLEMENTED") unless TESTING_EXEC_NEXT
+      result = exec_query <<-GRAPHQL
+        {
+          band(name: "Vulfpeck") {
+            allAlbums {
+              name
+              band { name }
+            }
+          }
+        }
+      GRAPHQL
+
+      assert_equal ["Mit Peck", "My First Car"], result["data"]["band"]["allAlbums"].map { |a| a["name"] }
+      assert_equal ["Vulfpeck", "Vulfpeck"], result["data"]["band"]["allAlbums"].map { |a| a["band"]["name"] }
+    end
+
     it_dataloads "queries for associated records when the association isn't already loaded" do |d|
       my_first_car = ::Album.find(2)
       homey = ::Album.find(4)

spec/graphql/dataloader/active_record_source_spec.rb

@@ -3,6 +3,14 @@
 
 describe GraphQL::Dataloader::ActiveRecordSource do
   if testing_rails?
+    include VulfpeckSchemaHelpers
+    it "works with field config shorthands" do
+      skip("Not implemented") unless TESTING_EXEC_NEXT
+      query_str = "{ rootBand { name } }"
+      assert_equal "Wilco", exec_query(query_str, root_value: OpenStruct.new(band_name: "Wilco"))["data"]["rootBand"]["name"]
+      assert_equal "Chon", exec_query(query_str, root_value: OpenStruct.new(band_name: "Chon"))["data"]["rootBand"]["name"]
+    end
+
     describe "finding by ID" do
       it_dataloads "loads once, then returns from a cache when available" do |d|
         log = with_active_record_log(colorize: false) do

spec/graphql/dataloader/source_spec.rb

@@ -8,6 +8,18 @@ def fetch(keys)
     end
   end
 
+  if testing_rails?
+    describe "with field configuration shorthands" do
+      include VulfpeckSchemaHelpers
+      it "calls the configured source" do
+        skip("Not implemented") unless TESTING_EXEC_NEXT
+        result = exec_query("{ bandsCount albumsCount }")
+        assert_equal 4, result["data"]["bandsCount"]
+        assert_equal 6, result["data"]["albumsCount"]
+      end
+    end
+  end
+
   it "raises an error when it tries too many times to sync" do
     dl = GraphQL::Dataloader.new
     dl.append_job { dl.with(FailsToLoadSource).load(1) }

spec/graphql/execution/batching_spec.rb spec/graphql/execution/next_spec.rbspec/graphql/execution/batching_spec.rb renamed to spec/graphql/execution/next_spec.rb

@@ -26,6 +26,12 @@ def fetch(keys)
       assert_equal 4, example.dataload_record(Album, "Homey", find_by: :name).id
     end
 
+    it_dataloads "loads many records with dataload_all_records" do |d|
+      example = DataloaderExample.new(d)
+      assert_equal ["Homey", "Mit Peck"], example.dataload_all_records(Album, [4, 1]).map(&:name)
+      assert_equal [4, 1], example.dataload_all_records(Album, ["Homey", "Mit Peck"], find_by: :name).map(&:id)
+    end
+
     it_dataloads "loads association with dataload_association" do |d|
       album1 = Album.find(1)
       example = DataloaderExample.new(d, album1)
@@ -37,6 +43,17 @@ def fetch(keys)
       assert_nil example.dataload_association(album, :band, scope: Band.country)
     end
 
+    it_dataloads "loads association on many objects with dataload_all_associations" do |d|
+      album1 = Album.find(1)
+      album4 = Album.find(4)
+      example = DataloaderExample.new(d, album1)
+
+      assert_equal ["Vulfpeck", "Chon"], example.dataload_all_associations([album1, album4], :band).map(&:name)
+      album1.reload
+      album4.reload
+      assert_equal [nil, nil], example.dataload_all_associations([album1, album4], :band, scope: Band.country)
+    end
+
     it_dataloads "calls any source with dataload..." do |d|
       example = DataloaderExample.new(d)
       d.with(PlusSource).request(2)