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/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

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)