graphql 2.6.12 → 2.6.13

data/lib/graphql/schema/build_from_definition.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
+# typed: false
 require "graphql/schema/build_from_definition/resolve_map"
 
 module GraphQL
   class Schema
     module BuildFromDefinition
       class << self
-        # @see {Schema.from_definition}
+        # See [Schema.from_definition](rdoc-ref:Schema.from_definition)
         def from_definition(schema_superclass, definition_string, parser: GraphQL.default_parser, **kwargs)
           if defined?(parser::SchemaParser)
             parser = parser::SchemaParser
@@ -25,8 +26,9 @@ module GraphQL
         end
       end
 
-      # @api private
-      module Builder
+      #--
+      # @requires_ancestor: Kernel
+      module Builder # :nodoc:
         include GraphQL::EmptyObjects
         extend self
 
@@ -53,12 +55,15 @@ module GraphQL
           schema_definition = schema_defns.first
           types = {}
           directives = schema_superclass.directives.dup
-          type_resolver = build_resolve_type(types, directives, ->(type_name) { types[type_name] ||= Schema::LateBoundType.new(type_name)})
-          # Make a different type resolver because we need to coerce directive arguments
-          # _while_ building the schema.
-          # It will dig for a type if it encounters a custom type. This could be a problem if there are cycles.
+          # Directive applications are queued while types are built, then applied once every type is complete,
+          # because applying a directive coerces its arguments, which requires fully-built input types.
+          queued_directives = []
+          type_resolver = TypeResolver.new(types, directives, queued_directives) { |type_name| types[type_name] ||= Schema::LateBoundType.new(type_name) }
+          # Make a different type resolver because directive argument types must be real classes (not late-bound)
+          # when queued directives are applied. It builds types eagerly. (Each type registers itself in `types`
+          # before building its members, so cycles between input objects terminate.)
           directive_type_resolver = nil
-          directive_type_resolver = build_resolve_type(types, directives, ->(type_name) {
+          directive_type_resolver = TypeResolver.new(types, directives, queued_directives) { |type_name|
             types[type_name] ||= begin
               defn = document.definitions.find { |d| d.respond_to?(:name) && d.name == type_name }
               if defn
@@ -69,7 +74,7 @@ module GraphQL
                 raise "No definition for #{type_name.inspect} found in schema document or built-in types. Add a definition for it or remove it."
               end
             end
-          })
+          }
 
           directives.merge!(GraphQL::Schema.default_directives)
           document.definitions.each do |definition|
@@ -117,7 +122,7 @@ module GraphQL
                   end
                 end
 
-                types[definition.name] = build_definition_from_node(definition, type_resolver, default_resolve, base_types)
+                build_definition_from_node(definition, type_resolver, default_resolve, base_types)
               end
             end
           end
@@ -185,11 +190,15 @@ module GraphQL
             end
           end
 
+          # All types are built now, so directive arguments can be coerced
+          apply_queued_directives(queued_directives)
+
           builder = self
 
           found_types = types.values
           object_types = found_types.select { |t| t.respond_to?(:kind) && t.kind.object? }
           schema_class = Class.new(schema_superclass) do
+            #: self as singleton(GraphQL::Schema)
             begin
               # Add these first so that there's some chance of resolving late-bound types
               add_type_and_traverse(found_types, root: false)
@@ -228,6 +237,7 @@ module GraphQL
             if schema_definition
               ast_node(schema_definition)
               builder.build_directives(self, schema_definition, type_resolver)
+              builder.apply_queued_directives(queued_directives)
             end
 
             using.each do |plugin, options|
@@ -262,6 +272,7 @@ module GraphQL
               build_directives(schema_class, ext, type_resolver)
             end
           end
+          apply_queued_directives(queued_directives)
 
           schema_class
         end
@@ -293,7 +304,13 @@ module GraphQL
         # with their actual definitions.
         #
         # (Schema definitions are allowed to reference those built-ins without redefining them.)
-        # @return void
+        #
+        # **Returns**
+        #
+        # - `Object` — void
+        #
+        # :call-seq:
+        #   replace_late_bound_types_with_built_in(types) -> Object
         def replace_late_bound_types_with_built_in(types)
           GraphQL::Schema::BUILT_IN_TYPES.each do |scalar_name, built_in_scalar|
             existing_type = types[scalar_name]
@@ -303,7 +320,26 @@ module GraphQL
           end
         end
 
+        # Apply `ast_node`'s directives to `definition`. If any of those directives has arguments,
+        # they're queued for {apply_queued_directives} because coercing arguments requires fully-built types.
+        # Directives without arguments are applied right away, since some (like `@oneOf`) affect how the rest of the type is built.
         def build_directives(definition, ast_node, type_resolver)
+          return if ast_node.directives.empty?
+
+          if ast_node.directives.all? { |dir_node| dir_node.name == "deprecated" || type_resolver.directive_class(dir_node.name)&.all_argument_definitions&.empty? }
+            apply_directives(definition, ast_node, type_resolver)
+          else
+            type_resolver.queued_directives << [definition, ast_node, type_resolver]
+          end
+        end
+
+        def apply_queued_directives(queued_directives)
+          until queued_directives.empty?
+            apply_directives(*queued_directives.shift)
+          end
+        end
+
+        def apply_directives(definition, ast_node, type_resolver)
           dirs = prepare_directives(ast_node, type_resolver)
           dirs.each do |(dir_class, options)|
             if definition.respond_to?(:schema_directive)
@@ -354,7 +390,9 @@ module GraphQL
         def build_enum_type(enum_type_definition, type_resolver, base_type)
           builder = self
           Class.new(base_type) do
+            #: self as singleton(GraphQL::Schema::Enum)
             graphql_name(enum_type_definition.name)
+            type_resolver.register(self)
             builder.build_directives(self, enum_type_definition, type_resolver)
             description(enum_type_definition.description)
             ast_node(enum_type_definition)
@@ -364,13 +402,13 @@ module GraphQL
 
         def build_values(type_class, enum_value_definitions, type_resolver)
           enum_value_definitions.each do |enum_value_definition|
-            type_class.value(enum_value_definition.name,
+            enum_value = type_class.value(enum_value_definition.name,
               value: enum_value_definition.name,
               deprecation_reason: build_deprecation_reason(enum_value_definition.directives),
               description: enum_value_definition.description,
-              directives: prepare_directives(enum_value_definition, type_resolver),
               ast_node: enum_value_definition,
             )
+            build_directives(enum_value, enum_value_definition, type_resolver)
           end
         end
 
@@ -387,7 +425,9 @@ module GraphQL
         def build_scalar_type(scalar_type_definition, type_resolver, base_type, default_resolve:)
           builder = self
           Class.new(base_type) do
+            #: self as singleton(GraphQL::Schema::Scalar)
             graphql_name(scalar_type_definition.name)
+            type_resolver.register(self)
             description(scalar_type_definition.description)
             ast_node(scalar_type_definition)
             builder.build_directives(self, scalar_type_definition, type_resolver)
@@ -410,7 +450,9 @@ module GraphQL
         def build_union_type(union_type_definition, type_resolver, base_type)
           builder = self
           Class.new(base_type) do
+            #: self as singleton(GraphQL::Schema::Union)
             graphql_name(union_type_definition.name)
+            type_resolver.register(self)
             description(union_type_definition.description)
             possible_types(*union_type_definition.types.map { |type_name| type_resolver.call(type_name) })
             ast_node(union_type_definition)
@@ -422,7 +464,9 @@ module GraphQL
           builder = self
 
           Class.new(base_type) do
+            #: self as singleton(GraphQL::Schema::Object)
             graphql_name(object_type_definition.name)
+            type_resolver.register(self)
             description(object_type_definition.description)
             ast_node(object_type_definition)
             builder.build_directives(self, object_type_definition, type_resolver)
@@ -440,7 +484,9 @@ module GraphQL
         def build_input_object_type(input_object_type_definition, type_resolver, base_type)
           builder = self
           Class.new(base_type) do
+            #: self as singleton(GraphQL::Schema::InputObject)
             graphql_name(input_object_type_definition.name)
+            type_resolver.register(self)
             description(input_object_type_definition.description)
             ast_node(input_object_type_definition)
             builder.build_directives(self, input_object_type_definition, type_resolver)
@@ -473,7 +519,7 @@ module GraphQL
               EMPTY_HASH
             end
 
-            type_class.argument(
+            argument = type_class.argument(
               argument_defn.name,
               type: type_resolver.call(argument_defn.type),
               required: false,
@@ -481,9 +527,9 @@ module GraphQL
               deprecation_reason: builder.build_deprecation_reason(argument_defn.directives),
               ast_node: argument_defn,
               camelize: false,
-              directives: prepare_directives(argument_defn, type_resolver),
               **default_value_kwargs
             )
+            builder.build_directives(argument, argument_defn, type_resolver)
           end
         end
 
@@ -502,8 +548,10 @@ module GraphQL
         def build_interface_type(interface_type_definition, type_resolver, base_type)
           builder = self
           Module.new do
+            #: self as GraphQL::Schema::Member::interface_definition
             include base_type
             graphql_name(interface_type_definition.name)
+            type_resolver.register(self)
             description(interface_type_definition.description)
             builder.build_interfaces(self, interface_type_definition.interfaces, type_resolver)
             ast_node(interface_type_definition)
@@ -528,11 +576,11 @@ module GraphQL
               ast_node: field_definition,
               method_conflict_warning: false,
               camelize: false,
-              directives: prepare_directives(field_definition, type_resolver),
               resolver_method: resolve_method_name,
               resolve_batch: resolve_method_name,
             )
 
+            builder.build_directives(schema_field_defn, field_definition, type_resolver)
             builder.build_arguments(schema_field_defn, field_definition.arguments, type_resolver)
 
             # Don't do this for interfaces
@@ -544,6 +592,7 @@ module GraphQL
 
         def define_field_resolve_method(owner, method_name, field_name)
           owner.define_method(method_name) { |**args|
+            #: self as GraphQL::Schema::Object
             field_instance = context.types.field(owner, field_name)
             context.schema.definition_default_resolve.call(self.class, field_instance, object, args, context)
           }
@@ -555,28 +604,46 @@ module GraphQL
           }
         end
 
-        def build_resolve_type(lookup_hash, directives, missing_type_handler)
-          resolve_type_proc = nil
-          resolve_type_proc = ->(ast_node) {
+        class TypeResolver
+          def initialize(lookup_hash, directives, queued_directives, &missing_type_handler)
+            @lookup_hash = lookup_hash
+            @directives = directives
+            @queued_directives = queued_directives
+            @missing_type_handler = missing_type_handler
+          end
+
+          # Directive applications waiting for {Builder#apply_queued_directives}
+          attr_reader :queued_directives
+
+          # Add `type` to the lookup hash. Types call this before building their members, so that references back to them (including cycles) find this type.
+          def register(type)
+            @lookup_hash[type.graphql_name] = type
+          end
+
+          # The already-defined directive class named `name`, or `nil` if there isn't one yet
+          def directive_class(name)
+            @directives[name]
+          end
+
+          def call(ast_node)
             case ast_node
             when GraphQL::Language::Nodes::TypeName
               type_name = ast_node.name
-              if lookup_hash.key?(type_name)
-                lookup_hash[type_name]
+              if @lookup_hash.key?(type_name)
+                @lookup_hash[type_name]
               else
-                missing_type_handler.call(type_name)
+                @missing_type_handler.call(type_name)
               end
             when GraphQL::Language::Nodes::NonNullType
-              resolve_type_proc.call(ast_node.of_type).to_non_null_type
+              call(ast_node.of_type).to_non_null_type
             when GraphQL::Language::Nodes::ListType
-              resolve_type_proc.call(ast_node.of_type).to_list_type
+              call(ast_node.of_type).to_list_type
             when String
-              directives[ast_node] ||= missing_type_handler.call(ast_node)
+              @directives[ast_node] ||= @missing_type_handler.call(ast_node)
             else
               raise "Unexpected ast_node: #{ast_node.inspect}"
             end
-          }
-          resolve_type_proc
+          end
         end
       end
 

data/lib/graphql/schema/built_in_types.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     BUILT_IN_TYPES = {

data/lib/graphql/schema/directive/deprecated.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/feature.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member
@@ -12,27 +13,35 @@ module GraphQL
       #
       # To use it, you have to implement `.enabled?`, for example:
       #
-      # @example Implementing the Feature directive
-      #   # app/graphql/directives/feature.rb
-      #   class Directives::Feature < GraphQL::Schema::Directive::Feature
-      #     def self.enabled?(flag_name, _obj, context)
-      #       # Translate some GraphQL data for Ruby:
-      #       flag_key = flag_name.underscore
-      #       current_user = context[:viewer]
-      #       # Check the feature flag however your app does it:
-      #       MyFeatureFlags.enabled?(current_user, flag_key)
-      #     end
+      # **Examples**
+      #
+      # **Example: Implementing the Feature directive**
+      #
+      # ```ruby
+      # # app/graphql/directives/feature.rb
+      # class Directives::Feature < GraphQL::Schema::Directive::Feature
+      #   def self.enabled?(flag_name, _obj, context)
+      #     # Translate some GraphQL data for Ruby:
+      #     flag_key = flag_name.underscore
+      #     current_user = context[:viewer]
+      #     # Check the feature flag however your app does it:
+      #     MyFeatureFlags.enabled?(current_user, flag_key)
       #   end
+      # end
+      # ```
       #
-      # @example Flagging a part of the query
-      #   viewer {
-      #     # This field only runs if `.enabled?("recommendationEngine", obj, context)`
-      #     # returns true. Otherwise, it's treated as if it didn't exist.
-      #     recommendations @feature(flag: "recommendationEngine") {
-      #       name
-      #       rating
-      #     }
+      # **Example: Flagging a part of the query**
+      #
+      # ```ruby
+      # viewer {
+      #   # This field only runs if `.enabled?("recommendationEngine", obj, context)`
+      #   # returns true. Otherwise, it's treated as if it didn't exist.
+      #   recommendations @feature(flag: "recommendationEngine") {
+      #     name
+      #     rating
       #   }
+      # }
+      # ```
       class Feature < Schema::Directive
         description "Directs the executor to run this only if a certain server-side feature is enabled."
 
@@ -53,10 +62,18 @@ module GraphQL
 
         # Override this method in your app's subclass of this directive.
         #
-        # @param flag_name [String] The client-provided string of a feature to check
-        # @param object [GraphQL::Schema::Objct] The currently-evaluated GraphQL object instance
-        # @param context [GraphQL::Query::Context]
-        # @return [Boolean] If truthy, execution will continue
+        # **Parameters**
+        #
+        # - `flag_name` (`String`) — The client-provided string of a feature to check
+        # - `object` (`GraphQL::Schema::Objct`) — The currently-evaluated GraphQL object instance
+        # - `context` (`GraphQL::Query::Context`)
+        #
+        # **Returns**
+        #
+        # - `Boolean` — If truthy, execution will continue
+        #
+        # :call-seq:
+        #   enabled?(String flag_name, GraphQL::Schema::Objct object, GraphQL::Query::Context context) -> bool
         def self.enabled?(flag_name, object, context)
           raise GraphQL::RequiredImplementationMissingError, "Implement `.enabled?(flag_name, object, context)` to return true or false for the feature flag (#{flag_name.inspect})"
         end

data/lib/graphql/schema/directive/flagged.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member
-      # This is _similar_ to {Directive::Feature}, except it's prescribed by the server, not the client.
+      # This is _similar_ to [Directive::Feature](rdoc-ref:Directive::Feature), except it's prescribed by the server, not the client.
       #
       # In this case, the server hides types and fields _entirely_, unless the current context has certain `:flags` present.
       class Flagged < GraphQL::Schema::Directive
@@ -39,6 +40,10 @@ module GraphQL
 
         repeatable(true)
 
+        #--
+
+        # @requires_ancestor: GraphQL::Schema::Member::HasDirectives
+
         module VisibleByFlag
           def self.included(schema_class)
             schema_class.extend(self)

data/lib/graphql/schema/directive/include.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/one_of.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/skip.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/specified_by.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member

data/lib/graphql/schema/directive/transform.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Directive < GraphQL::Schema::Member
@@ -8,15 +9,23 @@ module GraphQL
       # and if the named transform is whitelisted and applies to the return value,
       # it's applied by calling a method with that name.
       #
-      # @example Installing the directive
-      #   class MySchema < GraphQL::Schema
-      #     directive(GraphQL::Schema::Directive::Transform)
-      #   end
+      # **Examples**
       #
-      # @example Transforming strings
-      #   viewer {
-      #     username @transform(by: "upcase")
-      #   }
+      # **Example: Installing the directive**
+      #
+      # ```ruby
+      # class MySchema < GraphQL::Schema
+      #   directive(GraphQL::Schema::Directive::Transform)
+      # end
+      # ```
+      #
+      # **Example: Transforming strings**
+      #
+      # ```ruby
+      # viewer {
+      #   username @transform(by: "upcase")
+      # }
+      # ```
       class Transform < Schema::Directive
         description "Directs the executor to run named transform on the return value."
 

data/lib/graphql/schema/directive.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
-    # Subclasses of this can influence how {GraphQL::Execution::Interpreter} runs queries.
+    # Subclasses of this can influence how [GraphQL::Execution::Interpreter](rdoc-ref:GraphQL::Execution::Interpreter) runs queries.
     #
-    # - {.include?}: if it returns `false`, the field or fragment will be skipped altogether, as if it were absent
-    # - {.resolve}: Wraps field resolution (so it should call `yield` to continue)
+    # - [.include?](rdoc-ref:.include?): if it returns `false`, the field or fragment will be skipped altogether, as if it were absent
+    # - [.resolve](rdoc-ref:.resolve): Wraps field resolution (so it should call `yield` to continue)
     class Directive < GraphQL::Schema::Member
       extend GraphQL::Schema::Member::HasArguments
       extend GraphQL::Schema::Member::HasArguments::HasDirectiveArguments
@@ -31,7 +32,7 @@ module GraphQL
 
         def locations(*new_locations)
           if !new_locations.empty?
-            is_runtime = false
+            is_runtime = false #: bool
             new_locations.each do |new_loc|
               loc_sym = new_loc.to_sym
               if !LOCATIONS.include?(loc_sym)
@@ -69,7 +70,7 @@ module GraphQL
           static_include?(arguments, context)
         end
 
-        # Determines whether {Execution::Lookahead} considers the field to be selected
+        # Determines whether [Execution::Lookahead](rdoc-ref:Execution::Lookahead) considers the field to be selected
         def static_include?(_arguments, _context)
           true
         end
@@ -127,10 +128,14 @@ module GraphQL
         end
       end
 
-      # @return [GraphQL::Schema::Field, GraphQL::Schema::Argument, Class, Module]
+      # **Returns**
+      #
+      # - `GraphQL::Schema::Field, GraphQL::Schema::Argument, Class, Module`
       attr_reader :owner
 
-      # @return [GraphQL::Interpreter::Arguments]
+      # **Returns**
+      #
+      # - `GraphQL::Interpreter::Arguments`
       attr_reader :arguments
 
       class InvalidArgumentError < GraphQL::Error