Merge pull request #386 from rmosolgo/boxed_values

Lazy resolution API

Author: rmosolgo

guides/_layouts/default.html

@@ -44,6 +44,7 @@ <h3>Guides</h3>
                 <li><a href="{{ site.baseurl }}/schema/configuration_options">Configuration Options</a></li>
                 <li><a href="{{ site.baseurl }}/schema/code_reuse">Code Reuse</a></li>
                 <li><a href="{{ site.baseurl }}/schema/instrumentation">Instrumentation</a></li>
+                <li><a href="{{ site.baseurl }}/schema/lazy_execution">Lazy Execution</a></li>
                 <li><a href="{{ site.baseurl }}/schema/limiting_visibility">Limiting Visibility</a></li>
                 <li><a href="{{ site.baseurl }}/schema/testing">Testing</a></li>
               </ul>

guides/schema/lazy_execution.md

@@ -0,0 +1,84 @@
+---
+title: Schema — Lazy Execution
+---
+
+With lazy execution, you can optimize access to external services (such as databases) by making batched calls. Building a lazy loader has three steps:
+
+- Define a lazy-loading class with _one_ method for loading & returning a value
+- Connect it to your schema with {{ "GraphQL::Schema#lazy_resolve" | api_doc }}
+- In `resolve` functions, return instances of the lazy-loading class
+
+[`graphql-batch`](https://github.com/shopify/graphql-batch) provides a powerful, flexible toolkit for lazy resolution with GraphQL.
+
+## Example: Batched Find
+
+Here's a way to find many objects by ID using one database call, preventing N+1 queries.
+
+1. Lazy-loading class which finds models by ID.
+
+  ```ruby
+  class LazyFindPerson
+    def initialize(query_ctx, person_id)
+      @person_id = person_id
+      # Initialize the loading state for this query,
+      # or get the previously-initiated state
+      @lazy_state = query_ctx[:lazy_find_person] ||= {
+        pending_ids: [],
+        loaded_ids: {},
+      }
+      # Register this ID to be loaded later:
+      @lazy_state[:pending_ids] << person_id
+    end
+
+    # Return the loaded record, hitting the database if needed
+    def person
+      # Check if the record was already loaded:
+      loaded_record = @lazy_state[:loaded_ids][@person_id]
+      if loaded_record
+        # The pending IDs were already loaded,
+        # so return the result of that previous load
+        loaded_record
+      else
+        # The record hasn't been loaded yet, so
+        # hit the database with all pending IDs
+        pending_ids = @lazy_state[:pending_ids]
+        people = Person.where(id: pending_ids)
+        people.each { |person| @lazy_state[:loaded_ids][person.id] = person }
+        # Now, get the matching person from the loaded result:
+        @lazy_state[:loaded_ids][@person_id]
+      end
+    end
+  ```
+
+2. Connect the lazy resolve method
+
+  ```ruby
+  MySchema = GraphQL::Schema.define do
+    # ...
+    lazy_resolve(LazyFindPerson, :person)
+  end
+  ```
+
+3. Return lazy objects from `resolve`
+
+  ```ruby
+  field :author, PersonType do
+    resolve ->(obj, args, ctx) {
+      LazyFindPerson(ctx, obj.author_id)
+    }
+  end
+  ```
+
+Now, calls to `author` will use batched database access. For example, this query:
+
+```graphql
+{
+  p1: post(id: 1) { author { name } }
+  p2: post(id: 2) { author { name } }
+  p3: post(id: 3) { author { name } }
+}
+```
+
+Will only make one query to load the `author` values.
+
+The example above is simple and has some shortcomings. Consider the `graphql-batch` gem for a robust solution to batched resolution.

lib/graphql.rb

@@ -67,6 +67,7 @@ def self.scan_with_ragel(query_string)
 require "graphql/introspection"
 require "graphql/language"
 require "graphql/analysis"
+require "graphql/execution"
 require "graphql/schema"
 require "graphql/schema/loader"
 require "graphql/schema/printer"
@@ -81,5 +82,4 @@ def self.scan_with_ragel(query_string)
 require "graphql/static_validation"
 require "graphql/version"
 require "graphql/relay"
-require "graphql/execution"
 require "graphql/compatibility"

lib/graphql/compatibility.rb

@@ -1,3 +1,4 @@
 require "graphql/compatibility/execution_specification"
+require "graphql/compatibility/lazy_execution_specification"
 require "graphql/compatibility/query_parser_specification"
 require "graphql/compatibility/schema_parser_specification"

lib/graphql/compatibility/execution_specification.rb

@@ -1,3 +1,6 @@
+require "graphql/compatibility/execution_specification/counter_schema"
+require "graphql/compatibility/execution_specification/specification_schema"
+
 module GraphQL
   module Compatibility
     # Test an execution strategy. This spec is not meant as a development aid.
@@ -22,164 +25,22 @@ module Compatibility
     # - Relay features
     #
     module ExecutionSpecification
-      DATA = {
-        "1001" => OpenStruct.new({
-          name: "Fannie Lou Hamer",
-          birthdate: Time.new(1917, 10, 6),
-          organization_ids: [],
-        }),
-        "1002" => OpenStruct.new({
-          name: "John Lewis",
-          birthdate: Time.new(1940, 2, 21),
-          organization_ids: ["2001"],
-        }),
-        "1003" => OpenStruct.new({
-          name: "Diane Nash",
-          birthdate: Time.new(1938, 5, 15),
-          organization_ids: ["2001", "2002"],
-        }),
-        "1004" => OpenStruct.new({
-          name: "Ralph Abernathy",
-          birthdate: Time.new(1926, 3, 11),
-          organization_ids: ["2002"],
-        }),
-        "2001" => OpenStruct.new({
-          name: "SNCC",
-          leader_id: nil, # fail on purpose
-        }),
-        "2002" => OpenStruct.new({
-          name: "SCLC",
-          leader_id: "1004",
-        }),
-      }
-
       # Make a minitest suite for this execution strategy, making sure it
       # fulfills all the requirements of this library.
       # @param execution_strategy [<#new, #execute>] An execution strategy class
       # @return [Class<Minitest::Test>] A test suite for this execution strategy
       def self.build_suite(execution_strategy)
         Class.new(Minitest::Test) do
-          def self.build_schema(execution_strategy)
-            organization_type = nil
-
-            timestamp_type = GraphQL::ScalarType.define do
-              name "Timestamp"
-              coerce_input ->(value) { Time.at(value.to_i) }
-              coerce_result ->(value) { value.to_i }
-            end
-
-            named_entity_interface_type = GraphQL::InterfaceType.define do
-              name "NamedEntity"
-              field :name, !types.String
-            end
-
-            person_type = GraphQL::ObjectType.define do
-              name "Person"
-              interfaces [named_entity_interface_type]
-              field :name, !types.String
-              field :birthdate, timestamp_type
-              field :age, types.Int do
-                argument :on, !timestamp_type
-                resolve ->(obj, args, ctx) {
-                  if obj.birthdate.nil?
-                    nil
-                  else
-                    age_on = args[:on]
-                    age_years = age_on.year - obj.birthdate.year
-                    this_year_birthday = Time.new(age_on.year, obj.birthdate.month, obj.birthdate.day)
-                    if this_year_birthday > age_on
-                      age_years -= 1
-                    end
-                  end
-                  age_years
-                }
-              end
-              field :organizations, types[organization_type] do
-                resolve ->(obj, args, ctx) {
-                  obj.organization_ids.map { |id| DATA[id] }
-                }
-              end
-              field :first_organization, !organization_type do
-                resolve ->(obj, args, ctx) {
-                  DATA[obj.organization_ids.first]
-                }
-              end
-            end
-
-            organization_type = GraphQL::ObjectType.define do
-              name "Organization"
-              interfaces [named_entity_interface_type]
-              field :name, !types.String
-              field :leader, !person_type do
-                resolve ->(obj, args, ctx) {
-                  DATA[obj.leader_id] || (ctx[:return_error] ? ExecutionError.new("Error on Nullable") : nil)
-                }
-              end
-              field :returnedError, types.String do
-                resolve ->(o, a, c) {
-                  GraphQL::ExecutionError.new("This error was returned")
-                }
-              end
-              field :raisedError, types.String do
-                resolve ->(o, a, c) {
-                  raise GraphQL::ExecutionError.new("This error was raised")
-                }
-              end
-
-              field :nodePresence, !types[!types.Boolean] do
-                resolve ->(o, a, ctx) {
-                  [
-                    ctx.irep_node.is_a?(GraphQL::InternalRepresentation::Node),
-                    ctx.ast_node.is_a?(GraphQL::Language::Nodes::AbstractNode),
-                    false, # just testing
-                  ]
-                }
-              end
-            end
-
-            node_union_type = GraphQL::UnionType.define do
-              name "Node"
-              possible_types [person_type, organization_type]
-            end
-
-            query_type = GraphQL::ObjectType.define do
-              name "Query"
-              field :node, node_union_type do
-                argument :id, !types.ID
-                resolve ->(obj, args, ctx) {
-                  obj[args[:id]]
-                }
-              end
-
-              field :organization, !organization_type do
-                argument :id, !types.ID
-                resolve ->(obj, args, ctx) {
-                  args[:id].start_with?("2") && obj[args[:id]]
-                }
-              end
-
-              field :organizations, types[organization_type] do
-                resolve ->(obj, args, ctx) {
-                  [obj["2001"], obj["2002"]]
-                }
-              end
-            end
-
-            GraphQL::Schema.define do
-              query_execution_strategy execution_strategy
-              query query_type
-
-              resolve_type ->(obj, ctx) {
-                obj.respond_to?(:birthdate) ? person_type : organization_type
-              }
-            end
+          class << self
+            attr_accessor :counter_schema, :specification_schema
           end
 
-          @@schema = build_schema(execution_strategy)
+          self.specification_schema = SpecificationSchema.build(execution_strategy)
+          self.counter_schema = CounterSchema.build(execution_strategy)
 
           def execute_query(query_string, **kwargs)
-            kwargs[:root_value] = DATA
-            @@schema.execute(query_string, **kwargs)
+            kwargs[:root_value] = SpecificationSchema::DATA
+            self.class.specification_schema.execute(query_string, **kwargs)
           end
 
           def test_it_fetches_data
@@ -409,47 +270,7 @@ def test_it_doesnt_add_errors_for_invalid_nulls_from_execution_errors
           end
 
           def test_it_only_resolves_fields_once_on_typed_fragments
-            count = 0
-            counter_type = nil
-
-            has_count_interface = GraphQL::InterfaceType.define do
-              name "HasCount"
-              field :count, types.Int
-              field :counter, ->{ counter_type }
-            end
-
-            counter_type = GraphQL::ObjectType.define do
-              name "Counter"
-              interfaces [has_count_interface]
-              field :count, types.Int, resolve: ->(o,a,c) { count += 1 }
-              field :counter, has_count_interface, resolve: ->(o,a,c) { :counter }
-            end
-
-            alt_counter_type = GraphQL::ObjectType.define do
-              name "AltCounter"
-              interfaces [has_count_interface]
-              field :count, types.Int, resolve: ->(o,a,c) { count += 1 }
-              field :counter, has_count_interface, resolve: ->(o,a,c) { :counter }
-            end
-
-            has_counter_interface = GraphQL::InterfaceType.define do
-              name "HasCounter"
-              field :counter, counter_type
-            end
-
-            query_type = GraphQL::ObjectType.define do
-              name "Query"
-              interfaces [has_counter_interface]
-              field :counter, has_count_interface, resolve: ->(o,a,c) { :counter }
-            end
-
-            schema = GraphQL::Schema.define(
-              query: query_type,
-              resolve_type: ->(o, c) { o == :counter ? counter_type : nil },
-              orphan_types: [alt_counter_type],
-            )
-
-            res = schema.execute("
+            res = self.class.counter_schema.execute("
             {
               counter { count }
               ... on HasCounter {
@@ -462,10 +283,10 @@ def test_it_only_resolves_fields_once_on_typed_fragments
               "counter" => { "count" => 1 }
             }
             assert_equal expected_data, res["data"]
-            assert_equal 1, count
+            assert_equal 1, self.class.counter_schema.metadata[:count]
 
             # Deep typed children are correctly distinguished:
-            res = schema.execute("
+            res = self.class.counter_schema.execute("
             {
               counter {
                 ... on Counter {