graphql 2.6.11 → 2.6.13

data/lib/graphql/schema/loader.rb

@@ -1,23 +1,31 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
-    # You can use the result of {GraphQL::Introspection::INTROSPECTION_QUERY}
+    # You can use the result of [GraphQL::Introspection::INTROSPECTION_QUERY](rdoc-ref:GraphQL::Introspection::INTROSPECTION_QUERY)
     # to make a schema. This schema is missing some important details like
     # `resolve` functions, but it does include the full type system,
     # so you can use it to validate queries.
     #
-    # @see GraphQL::Schema.from_introspection for a public API
+    # See [GraphQL::Schema.from_introspection](rdoc-ref:GraphQL::Schema.from_introspection) for a public API
     module Loader
-      extend self
-
       # Create schema with the result of an introspection query.
-      # @param introspection_result [Hash] A response from {GraphQL::Introspection::INTROSPECTION_QUERY}
-      # @return [Class] the schema described by `input`
-      def load(introspection_result)
+      #
+      # **Parameters**
+      #
+      # - `introspection_result` (`Hash`) — A response from [GraphQL::Introspection::INTROSPECTION_QUERY](rdoc-ref:GraphQL::Introspection::INTROSPECTION_QUERY)
+      #
+      # **Returns**
+      #
+      # - `Class` — the schema described by `input`
+      #
+      # :call-seq:
+      #   load(Hash introspection_result) -> Class
+      def self.load(introspection_result)
         schema = introspection_result.fetch("data").fetch("__schema")
 
         types = {}
-        type_resolver = ->(type) { resolve_type(types, type) }
+        type_resolver = ->(type) { resolve_type_reference(types, type) }
 
         schema.fetch("types").each do |type|
           next if type.fetch("name").start_with?("__")
@@ -56,7 +64,7 @@ module GraphQL
       class << self
         private
 
-        def resolve_type(types, type)
+        def resolve_type_reference(types, type)
           case kind = type.fetch("kind")
           when "ENUM", "INTERFACE", "INPUT_OBJECT", "OBJECT", "SCALAR", "UNION"
             type_name = type.fetch("name")
@@ -67,9 +75,9 @@ module GraphQL
               type
             end
           when "LIST"
-            Schema::List.new(resolve_type(types, type.fetch("ofType")))
+            Schema::List.new(resolve_type_reference(types, type.fetch("ofType")))
           when "NON_NULL"
-            Schema::NonNull.new(resolve_type(types, type.fetch("ofType")))
+            Schema::NonNull.new(resolve_type_reference(types, type.fetch("ofType")))
           else
             fail GraphQL::RequiredImplementationMissingError, "#{kind} not implemented"
           end
@@ -113,6 +121,7 @@ module GraphQL
             end
           when "INTERFACE"
             Module.new do
+              #: self as GraphQL::Schema::Member::interface_definition
               include GraphQL::Schema::Interface
               graphql_name(type["name"])
               description(type["description"])
@@ -213,7 +222,9 @@ module GraphQL
               dummy_query_ast = GraphQL.parse(dummy_query_str)
 
               # Reach into the AST for the default value:
-              input_value_ast = dummy_query_ast.definitions.first.variables.first.default_value
+              operation = dummy_query_ast.definitions.first #: as GraphQL::Language::Nodes::OperationDefinition
+              variable = operation.variables.first #: as !nil
+              input_value_ast = variable.default_value
 
               kwargs[:default_value] = extract_default_value(default_value_str, input_value_ast)
             end

data/lib/graphql/schema/member/base_dsl_methods.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require "graphql/schema/find_inherited_value"
 
@@ -6,17 +7,28 @@ module GraphQL
   class Schema
     class Member
       # DSL methods shared by lots of things in the GraphQL Schema.
-      # @api private
-      # @see Classes that extend this, eg {GraphQL::Schema::Object}
-      module BaseDSLMethods
+      # See classes that extend this, eg [GraphQL::Schema::Object](rdoc-ref:GraphQL::Schema::Object)
+      #--
+      # @requires_ancestor: Kernel
+      # @requires_ancestor: Module
+      module BaseDSLMethods # :nodoc:
         include GraphQL::Schema::FindInheritedValue
 
         # Call this with a new name to override the default name for this schema member; OR
         # call it without an argument to get the name of this schema member
         #
         # The default name is implemented in default_graphql_name
-        # @param new_name [String]
-        # @return [String]
+        #
+        # **Parameters**
+        #
+        # - `new_name` (`String`)
+        #
+        # **Returns**
+        #
+        # - `String`
+        #
+        # :call-seq:
+        #   graphql_name(String new_name) -> String
         def graphql_name(new_name = nil)
           if new_name
             GraphQL::NameValidator.validate!(new_name)
@@ -28,8 +40,17 @@ module GraphQL
 
         # Call this method to provide a new description; OR
         # call it without an argument to get the description
-        # @param new_description [String]
-        # @return [String]
+        #
+        # **Parameters**
+        #
+        # - `new_description` (`String`)
+        #
+        # **Returns**
+        #
+        # - `String`
+        #
+        # :call-seq:
+        #   description(String new_description) -> String
         def description(new_description = nil)
           if new_description
             @description = new_description
@@ -42,8 +63,17 @@ module GraphQL
 
         # Call this method to provide a new comment; OR
         # call it without an argument to get the comment
-        # @param new_comment [String]
-        # @return [String, nil]
+        #
+        # **Parameters**
+        #
+        # - `new_comment` (`String`)
+        #
+        # **Returns**
+        #
+        # - `String, nil`
+        #
+        # :call-seq:
+        #   comment(String new_comment) -> String | nil
         def comment(new_comment = NOT_CONFIGURED)
           if !NOT_CONFIGURED.equal?(new_comment)
             @comment = new_comment
@@ -56,6 +86,9 @@ module GraphQL
 
         # This pushes some configurations _down_ the inheritance tree,
         # in order to prevent repetitive lookups at runtime.
+        #--
+        # @requires_ancestor: Module
+        # @requires_ancestor: GraphQL::Schema::Member::BaseDSLMethods
         module ConfigurationExtension
           def inherited(child_class)
             child_class.introspection(introspection)
@@ -72,7 +105,12 @@ module GraphQL
           end
         end
 
-        # @return [Boolean] If true, this object is part of the introspection system
+        # **Returns**
+        #
+        # - `Boolean` — If true, this object is part of the introspection system
+        #
+        # :call-seq:
+        #   introspection(new_introspection) -> bool
         def introspection(new_introspection = nil)
           if !new_introspection.nil?
             @introspection = new_introspection
@@ -88,7 +126,13 @@ module GraphQL
         end
 
         # The mutation this type was derived from, if it was derived from a mutation
-        # @return [Class]
+        #
+        # **Returns**
+        #
+        # - `Class`
+        #
+        # :call-seq:
+        #   mutation(mutation_class) -> Class
         def mutation(mutation_class = nil)
           if mutation_class
             @mutation = mutation_class
@@ -107,7 +151,9 @@ module GraphQL
         def default_graphql_name
           @default_graphql_name ||= begin
             raise GraphQL::RequiredImplementationMissingError, 'Anonymous class should declare a `graphql_name`' if name.nil?
-            g_name = -name.split("::").last
+            class_name = name #: as !nil
+            short_name = class_name.split("::").last #: as String
+            g_name = -short_name
             g_name.end_with?("Type") ? g_name.sub(/Type\Z/, "") : g_name
           end
         end

data/lib/graphql/schema/member/build_type.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Member
-      # @api private
-      module BuildType
+      #--
+      # @requires_ancestor: Kernel
+      module BuildType # :nodoc:
         LIST_TYPE_ERROR = "Use an array of [T] or [T, null: true] for list types; other arrays are not supported"
 
         module_function
-        # @param type_expr [String, Class, GraphQL::BaseType]
-        # @return [GraphQL::BaseType]
+        # **Parameters**
+        #
+        # - `type_expr` (`String, Class, GraphQL::BaseType`)
+        #
+        # **Returns**
+        #
+        # - `GraphQL::BaseType`
+        #
+        # :call-seq:
+        #   parse_type(String | Class | GraphQL::BaseType type_expr, null:) -> GraphQL::BaseType
         def parse_type(type_expr, null:)
           list_type = false
 
@@ -104,7 +114,8 @@ module GraphQL
             to_type_name(something.first)
           when Module
             if something.respond_to?(:graphql_name)
-              something.graphql_name
+              type_defn = something #: as GraphQL::Schema::Member::type_definition
+              type_defn.graphql_name
             else
               to_type_name(something.name)
             end

data/lib/graphql/schema/member/graphql_type_names.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
     class Member
       # These constants are interpreted as GraphQL types when defining fields or arguments
       #
-      # @example
-      #   field :is_draft, Boolean, null: false
-      #   field :id, ID, null: false
-      #   field :score, Int, null: false
       #
-      # @api private
-      module GraphQLTypeNames
+      # **Examples**
+      #
+      # **Example: field :is_draft, Boolean, null: false**
+      #
+      # ```ruby
+      # field :id, ID, null: false
+      # field :score, Int, null: false
+      # ```
+      module GraphQLTypeNames # :nodoc:
         Boolean = "Boolean"
         ID = "ID"
         Int = "Int"

data/lib/graphql/schema/member/has_arguments.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Member
+      #--
+      # @requires_ancestor: Kernel
       module HasArguments
         def self.included(cls)
           cls.extend(ArgumentClassAccessor)
@@ -14,28 +17,39 @@ module GraphQL
           cls.extend(ClassConfigured)
         end
 
-        # @param arg_name [Symbol] The underscore-cased name of this argument, `name:` keyword also accepted
-        # @param type_expr The GraphQL type of this argument; `type:` keyword also accepted
-        # @param desc [String] Argument description, `description:` keyword also accepted
-        # @option kwargs [Boolean, :nullable] :required if true, this argument is non-null; if false, this argument is nullable. If `:nullable`, then the argument must be provided, though it may be `null`.
-        # @option kwargs [String] :description Positional argument also accepted
-        # @option kwargs [Class, Array<Class>] :type Input type; positional argument also accepted
-        # @option kwargs [Symbol] :name positional argument also accepted
-        # @option kwargs [Object] :default_value
-        # @option kwargs [Class, Array<Class>] :loads A GraphQL type to load for the given ID when one is present
-        # @option kwargs [Symbol] :as Override the keyword name when passed to a method
-        # @option kwargs [Symbol] :prepare A method to call to transform this argument's valuebefore sending it to field resolution
-        # @option kwargs [Boolean] :camelize if true, the name will be camelized when building the schema
-        # @option kwargs [Boolean] :from_resolver if true, a Resolver class defined this argument
-        # @option kwargs [Hash{Class => Hash}] :directives
-        # @option kwargs [String] :deprecation_reason
-        # @option kwargs [String] :comment Private, used by GraphQL-Ruby when parsing GraphQL schema files
-        # @option kwargs [GraphQL::Language::Nodes::InputValueDefinition] :ast_node Private, used by GraphQL-Ruby when parsing schema files
-        # @option kwargs [Hash, nil] :validates Options for building validators, if any should be applied
-        # @option kwargs [Boolean] :replace_null_with_default if `true`, incoming values of `null` will be replaced with the configured `default_value`
-        # @param definition_block [Proc] Called with the newly-created {Argument}
-        # @param kwargs [Hash] Keywords for defining an argument. Any keywords not documented here must be handled by your base Argument class.
-        # @return [GraphQL::Schema::Argument] An instance of {argument_class} created from these arguments
+        # **Parameters**
+        #
+        # - `arg_name` (`Symbol`) — The underscore-cased name of this argument, `name:` keyword also accepted
+        # - `type_expr` — The GraphQL type of this argument; `type:` keyword also accepted
+        # - `desc` (`String`) — Argument description, `description:` keyword also accepted
+        # - `definition_block` (`Proc`) — Called with the newly-created [Argument](rdoc-ref:Argument)
+        # - `kwargs` (`Hash`) — Keywords for defining an argument. Any keywords not documented here must be handled by your base Argument class.
+        #
+        # **Options**
+        #
+        # - `kwargs.:required` (`Boolean, :nullable`) — if true, this argument is non-null; if false, this argument is nullable. If `:nullable`, then the argument must be provided, though it may be `null`.
+        # - `kwargs.:description` (`String`) — Positional argument also accepted
+        # - `kwargs.:type` (`Class, Array<Class>`) — Input type; positional argument also accepted
+        # - `kwargs.:name` (`Symbol`) — positional argument also accepted
+        # - `kwargs.:default_value` (`Object`)
+        # - `kwargs.:loads` (`Class, Array<Class>`) — A GraphQL type to load for the given ID when one is present
+        # - `kwargs.:as` (`Symbol`) — Override the keyword name when passed to a method
+        # - `kwargs.:prepare` (`Symbol`) — A method to call to transform this argument's valuebefore sending it to field resolution
+        # - `kwargs.:camelize` (`Boolean`) — if true, the name will be camelized when building the schema
+        # - `kwargs.:from_resolver` (`Boolean`) — if true, a Resolver class defined this argument
+        # - `kwargs.:directives` (`Hash{Class => Hash}`)
+        # - `kwargs.:deprecation_reason` (`String`)
+        # - `kwargs.:comment` (`String`) — Private, used by GraphQL-Ruby when parsing GraphQL schema files
+        # - `kwargs.:ast_node` (`GraphQL::Language::Nodes::InputValueDefinition`) — Private, used by GraphQL-Ruby when parsing schema files
+        # - `kwargs.:validates` (`Hash, nil`) — Options for building validators, if any should be applied
+        # - `kwargs.:replace_null_with_default` (`Boolean`) — if `true`, incoming values of `null` will be replaced with the configured `default_value`
+        #
+        # **Returns**
+        #
+        # - `GraphQL::Schema::Argument` — An instance of [argument_class](rdoc-ref:argument_class) created from these arguments
+        #
+        # :call-seq:
+        #   argument(Symbol arg_name, type_expr, String desc, Hash **kwargs, Proc &definition_block) -> GraphQL::Schema::Argument
         def argument(arg_name = nil, type_expr = nil, desc = nil, **kwargs, &definition_block)
           if kwargs[:loads]
             loads_name = arg_name || kwargs[:name]
@@ -65,8 +79,17 @@ module GraphQL
         end
 
         # Register this argument with the class.
-        # @param arg_defn [GraphQL::Schema::Argument]
-        # @return [GraphQL::Schema::Argument]
+        #
+        # **Parameters**
+        #
+        # - `arg_defn` (`GraphQL::Schema::Argument`)
+        #
+        # **Returns**
+        #
+        # - `GraphQL::Schema::Argument`
+        #
+        # :call-seq:
+        #   add_argument(GraphQL::Schema::Argument arg_defn) -> GraphQL::Schema::Argument
         def add_argument(arg_defn)
           @own_arguments ||= {}
           prev_defn = @own_arguments[arg_defn.name]
@@ -98,7 +121,12 @@ module GraphQL
           nil
         end
 
-        # @return [Hash<String => GraphQL::Schema::Argument] Arguments defined on this thing, keyed by name. Includes inherited definitions
+        # **Returns**
+        #
+        # - `Hash<String => GraphQL::Schema::Argument>` — Arguments defined on this thing, keyed by name. Includes inherited definitions
+        #
+        # :call-seq:
+        #   arguments(context:, _require_defined_arguments) -> Hash[String, GraphQL::Schema::Argument]
         def arguments(context = GraphQL::Query::NullContext.instance, _require_defined_arguments = nil)
           if !own_arguments.empty?
             own_arguments_that_apply = {}
@@ -122,6 +150,8 @@ module GraphQL
             child_class.extend(InheritedArguments)
           end
 
+          #--
+          # @requires_ancestor: singleton(Object)
           module InheritedArguments
             def arguments(context = GraphQL::Query::NullContext.instance, require_defined_arguments = true)
               own_arguments = super(context, require_defined_arguments)
@@ -145,7 +175,8 @@ module GraphQL
 
             def all_argument_definitions
               all_defns = {}
-              ancestors.reverse_each do |ancestor|
+              all_ancestors = ancestors #: Array[untyped]
+              all_ancestors.reverse_each do |ancestor|
                 if ancestor.respond_to?(:own_arguments)
                   all_defns.merge!(ancestor.own_arguments)
                 end
@@ -159,7 +190,8 @@ module GraphQL
             def get_argument(argument_name, context = GraphQL::Query::NullContext.instance)
               warden = Warden.from_context(context)
               skip_visible = context.respond_to?(:types) && context.types.is_a?(GraphQL::Schema::Visibility::Profile)
-              for ancestor in ancestors
+              all_ancestors = ancestors #: Array[untyped]
+              for ancestor in all_ancestors
                 if ancestor.respond_to?(:own_arguments) &&
                   (a = ancestor.own_arguments[argument_name]) &&
                   (skip_visible || (a = Warden.visible_entry?(:visible_argument?, a, context, warden)))
@@ -171,6 +203,9 @@ module GraphQL
           end
         end
 
+        #--
+        # @requires_ancestor: Kernel
+        # @requires_ancestor: GraphQL::Schema::Member::HasArguments
         module FieldConfigured
           def arguments(context = GraphQL::Query::NullContext.instance, _require_defined_arguments = nil)
             own_arguments = super
@@ -230,7 +265,12 @@ module GraphQL
           end
         end
 
-        # @return [GraphQL::Schema::Argument, nil] Argument defined on this thing, fetched by name.
+        # **Returns**
+        #
+        # - `GraphQL::Schema::Argument, nil` — Argument defined on this thing, fetched by name.
+        #
+        # :call-seq:
+        #   get_argument(argument_name, context:) -> GraphQL::Schema::Argument | nil
         def get_argument(argument_name, context = GraphQL::Query::NullContext.instance)
           warden = Warden.from_context(context)
           if (arg_config = own_arguments[argument_name]) && ((context.respond_to?(:types) && context.types.is_a?(GraphQL::Schema::Visibility::Profile)) || (visible_arg = Warden.visible_entry?(:visible_argument?, arg_config, context, warden)))
@@ -242,26 +282,32 @@ module GraphQL
           end
         end
 
-        # @param new_arg_class [Class] A class to use for building argument definitions
+        # **Parameters**
+        #
+        # - `new_arg_class` (`Class`) — A class to use for building argument definitions
+        #
+        # :call-seq:
+        #   argument_class(Class new_arg_class)
         def argument_class(new_arg_class = nil)
           self.class.argument_class(new_arg_class)
         end
 
-        # @api private
-        # If given a block, it will eventually yield the loaded args to the block.
+        # **Yields:** [Interpreter::Arguments, Execution::Lazy<Interpreter::Arguments>]
         #
-        # If no block is given, it will immediately dataload (but might return a Lazy).
+        # **Parameters**
         #
-        # @param values [Hash<String, Object>]
-        # @param context [GraphQL::Query::Context]
-        # @yield [Interpreter::Arguments, Execution::Lazy<Interpreter::Arguments>]
-        # @return [Interpreter::Arguments, Execution::Lazy<Interpreter::Arguments>]
-        def coerce_arguments(parent_object, values, context, &block)
+        # - `values` (`Hash<String, Object>`)
+        # - `context` (`GraphQL::Query::Context`)
+        #
+        # **Returns**
+        #
+        # - `Interpreter::Arguments, Execution::Lazy<Interpreter::Arguments>`
+        def coerce_arguments(parent_object, values, context, &block) # :nodoc:
           # Cache this hash to avoid re-merging it
           arg_defns = context.types.arguments(self)
           total_args_count = arg_defns.size
 
-          finished_args = nil
+          finished_args = nil #: untyped
           prepare_finished_args = -> {
             if total_args_count == 0
               finished_args = GraphQL::Execution::Interpreter::Arguments::EMPTY
@@ -271,7 +317,7 @@ module GraphQL
             else
               argument_values = {}
               resolved_args_count = 0
-              raised_error = false
+              raised_error = false #: bool
               arg_defns.each do |arg_defn|
                 context.dataloader.append_job do
                   begin
@@ -318,6 +364,8 @@ module GraphQL
           nil
         end
 
+        #--
+        # @requires_ancestor: Kernel
         module HasDirectiveArguments
           def validate_directive_argument(arg_defn, value)
             if value.nil? && arg_defn.type.non_null?
@@ -334,6 +382,8 @@ module GraphQL
           end
         end
 
+        #--
+        # @requires_ancestor: singleton(Object)
         module ArgumentClassAccessor
           def argument_class(new_arg_class = nil)
             if new_arg_class
@@ -346,14 +396,21 @@ module GraphQL
           end
         end
 
+        #--
+        # @requires_ancestor: Kernel
         module ArgumentObjectLoader
           # Look up the corresponding object for a provided ID.
-          # By default, it uses Relay-style {Schema.object_from_id},
+          # By default, it uses Relay-style [Schema.object_from_id](rdoc-ref:Schema.object_from_id),
           # override this to find objects another way.
           #
-          # @param type [Class, Module] A GraphQL type definition
-          # @param id [String] A client-provided to look up
-          # @param context [GraphQL::Query::Context] the current context
+          # **Parameters**
+          #
+          # - `type` (`Class, Module`) — A GraphQL type definition
+          # - `id` (`String`) — A client-provided to look up
+          # - `context` (`GraphQL::Query::Context`) — the current context
+          #
+          # :call-seq:
+          #   object_from_id(Class | Module type, String id, GraphQL::Query::Context context)
           def object_from_id(type, id, context)
             context.schema.object_from_id(id, context)
           end
@@ -374,7 +431,7 @@ module GraphQL
           def authorize_application_object(argument, id, context, loaded_application_object)
             context.query.after_lazy(loaded_application_object) do |application_object|
               if application_object.nil?
-                err = GraphQL::LoadApplicationObjectFailedError.new(context: context, argument: argument, id: id, object: application_object)
+                err = GraphQL::LoadApplicationObjectFailedError.new(context: context, argument: argument, id: id, object: application_object) #: GraphQL::RuntimeError
                 application_object = load_application_object_failed(err)
               end
               # Double-check that the located object is actually of this type
@@ -424,7 +481,8 @@ module GraphQL
                         )
                         if self.respond_to?(:unauthorized_object)
                           err.set_backtrace(caller)
-                          unauthorized_object(err)
+                          loader = self #: untyped
+                          loader.unauthorized_object(err)
                         else
                           raise err
                         end
@@ -439,9 +497,18 @@ module GraphQL
           # Called when an argument's `loads:` configuration fails to fetch an application object.
           # By default, this method raises the given error, but you can override it to handle failures differently.
           #
-          # @param err [GraphQL::LoadApplicationObjectFailedError] The error that occurred
-          # @return [Object, nil] If a value is returned, it will be used instead of the failed load
-          # @api public
+          # **API:** public
+          #
+          # **Parameters**
+          #
+          # - `err` (`GraphQL::LoadApplicationObjectFailedError`) — The error that occurred
+          #
+          # **Returns**
+          #
+          # - `Object, nil` — If a value is returned, it will be used instead of the failed load
+          #
+          # :call-seq:
+          #   load_application_object_failed(GraphQL::LoadApplicationObjectFailedError err) -> Object | nil
           def load_application_object_failed(err)
             raise err
           end

data/lib/graphql/schema/member/has_ast_node.rb

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

data/lib/graphql/schema/member/has_authorization.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class Member
@@ -18,12 +19,16 @@ module GraphQL
           true
         end
 
+        #--
+        # @requires_ancestor: Kernel
         module InstanceConfigured
           def authorizes?(context)
             raise RequiredImplementationMissingError, "#{self.class} must implement #authorizes?(context)"
           end
         end
 
+        #--
+        # @requires_ancestor: Kernel
         module ClassConfigured
           def authorizes?(context)
             method(:authorized?).owner != GraphQL::Schema::Member::HasAuthorization