Document, add tests for child field and grandchild field

Author: rmosolgo

guides/queries/executing_queries.md

@@ -123,6 +123,53 @@ end
 
 Note that `context` is _not_ the hash that you passed it. It's an instance of {{ "GraphQL::Query::Context" | api_doc }}, but it delegates `#[]`, `#[]=`, and a few other methods to the hash you provide.
 
+### Scoped Context
+
+`context` is shared by the whole query. Anything you add to `context` will be accessible by any other field in the query (although GraphQL-Ruby's order of execution can vary).
+
+However, "scoped context" is can be used to assign values into `context` that are only available in the current field and the _children_ of the current field. For example, in this query:
+
+```graphql
+{
+  posts {
+    comments {
+      author
+      isOriginalPoster
+    }
+  }
+}
+```
+
+You could use "scoped context" to implement `isOriginalPoster`, based on the parent `comments` field.
+
+In `def comments`, add `:current_post` to scoped context using `context.scoped_set!`:
+
+```ruby
+class Types::Post < Types::BaseObject
+  # ...
+  def comments
+    context.scoped_set!(:current_post, object)
+    object.comments
+  end
+end
+```
+
+Then, inside `User`, you can check `context[:current_post]`:
+
+```ruby
+class Types::User < Types::BaseObject
+  # ...
+  def is_original_poster
+    current_post = context[:current_post]
+    current_post && current_post.author == object
+  end
+end
+```
+
+`context[:current_post]` will be present if an "upstream" field assigned it with `scoped_set!`.
+
+`context.scoped_merge!({ ... })` is also available for setting multiple keys at once.
+
 ## Root Value
 
 You can provide a root `object` value with `root_value:`. For example, to base the query off of the current organization:

lib/graphql/query/context.rb

@@ -97,8 +97,12 @@ def initialize(query_context)
           @no_path = [].freeze
         end
 
-        def current_context
-          @path_contexts[current_path]
+        def merged_context
+          merged_ctx = {}
+          each_present_path_ctx do |path_ctx|
+            merged_ctx = path_ctx.merge(merged_ctx)
+          end
+          merged_ctx
         end
 
         def merge!(hash)
@@ -111,26 +115,26 @@ def current_path
         end
 
         def key?(key)
-          each_path_ctx do |path_ctx|
-            if path_ctx && path_ctx.key?(key)
+          each_present_path_ctx do |path_ctx|
+            if path_ctx.key?(key)
               return true
             end
           end
           false
         end
 
         def [](key)
-          each_path_ctx do |path_ctx|
-            if path_ctx && path_ctx.key?(key)
+          each_present_path_ctx do |path_ctx|
+            if path_ctx.key?(key)
               return path_ctx[key]
             end
           end
           nil
         end
 
         def dig(key, *other_keys)
-          each_path_ctx do |path_ctx|
-            if path_ctx && path_ctx.key?(key)
+          each_present_path_ctx do |path_ctx|
+            if path_ctx.key?(key)
               found_value = path_ctx[key]
               if other_keys.any?
                 return found_value.dig(*other_keys)
@@ -146,12 +150,17 @@ def dig(key, *other_keys)
 
         # Start at the current location,
         # but look up the tree for previously-assigned scoped values
-        def each_path_ctx
+        def each_present_path_ctx
           search_path = current_path.dup
-          yield(@path_contexts[search_path])
+          if (current_path_ctx = @path_contexts[search_path])
+            yield(current_path_ctx)
+          end
+
           while search_path.size > 0
             search_path.pop # look one level higher
-            yield(@path_contexts[search_path])
+            if (search_path_ctx = @path_contexts[search_path])
+              yield(search_path_ctx)
+            end
           end
         end
       end
@@ -225,7 +234,7 @@ def dig(key, *other_keys)
       end
 
       def to_h
-        if (current_scoped_context = @scoped_context.current_context)
+        if (current_scoped_context = @scoped_context.merged_context)
           @provided_values.merge(current_scoped_context)
         else
           @provided_values

spec/graphql/query/context_spec.rb

@@ -407,6 +407,24 @@ class ContextSchema < GraphQL::Schema
       assert(context.key?(expected_key))
       assert_equal(expected_value, context.fetch(expected_key))
       assert_equal(expected_value, context.dig(expected_key)) if RUBY_VERSION >= '2.3.0'
+
+      # Enter a child field:
+      context.namespace(:interpreter)[:current_path] = ["somewhere", "child"]
+      assert_nil(context[expected_key])
+      assert_equal({ expected_key => nil }, context.to_h)
+      assert(context.key?(expected_key))
+      assert_nil(context.fetch(expected_key))
+      assert_nil(context.dig(expected_key)) if RUBY_VERSION >= '2.3.0'
+
+      # And a grandchild field
+      context.namespace(:interpreter)[:current_path] = ["somewhere", "child", "grandchild"]
+      context.scoped_set!(expected_key, :something_else)
+      context.scoped_set!(:another_key, :another_value)
+      assert_equal(:something_else, context[expected_key])
+      assert_equal({ expected_key => :something_else, another_key: :another_value }, context.to_h)
+      assert(context.key?(expected_key))
+      assert_equal(:something_else, context.fetch(expected_key))
+      assert_equal(:something_else, context.dig(expected_key)) if RUBY_VERSION >= '2.3.0'
     end
 
     it "sets a value using #scoped_set!" do