graphql 2.6.12 → 2.6.13

data/lib/graphql/schema/field_extension.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     # Extend this class to make field-level customizations to resolve behavior.
@@ -9,19 +10,31 @@ module GraphQL
     # The instance is frozen so that instance variables aren't modified during query execution,
     # which could cause all kinds of issues due to race conditions.
     class FieldExtension
-      # @return [GraphQL::Schema::Field]
+      # **Returns**
+      #
+      # - `GraphQL::Schema::Field`
       attr_reader :field
 
-      # @return [Object]
+      # **Returns**
+      #
+      # - `Object`
       attr_reader :options
 
-      # @return [Array<Symbol>, nil] `default_argument`s added, if any were added (otherwise, `nil`)
+      # **Returns**
+      #
+      # - `Array<Symbol>, nil` — `default_argument`s added, if any were added (otherwise, `nil`)
       attr_reader :added_default_arguments
 
       # Called when the extension is mounted with `extension(name, options)`.
       # The instance will be frozen to avoid improper use of state during execution.
-      # @param field [GraphQL::Schema::Field] The field where this extension was mounted
-      # @param options [Object] The second argument to `extension`, or `{}` if nothing was passed.
+      #
+      # **Parameters**
+      #
+      # - `field` (`GraphQL::Schema::Field`) — The field where this extension was mounted
+      # - `options` (`Object`) — The second argument to `extension`, or `{}` if nothing was passed.
+      #
+      # :call-seq:
+      #   initialize(GraphQL::Schema::Field field:, Object options:)
       def initialize(field:, options:)
         @field = field
         @options = options || {}
@@ -30,7 +43,12 @@ module GraphQL
       end
 
       class << self
-        # @return [Array(Array, Hash), nil] A list of default argument configs, or `nil` if there aren't any
+        # **Returns**
+        #
+        # - `Array(Array, Hash), nil` — A list of default argument configs, or `nil` if there aren't any
+        #
+        # :call-seq:
+        #   default_argument_configurations() -> Array(Array, Hash) | nil
         def default_argument_configurations
           args = superclass.respond_to?(:default_argument_configurations) ? superclass.default_argument_configurations : nil
           if @own_default_argument_configurations
@@ -43,8 +61,8 @@ module GraphQL
           args
         end
 
-        # @see Argument#initialize
-        # @see HasArguments#argument
+        # See the [GraphQL::Schema::Argument](rdoc-ref:GraphQL::Schema::Argument) API.
+        # See [HasArguments#argument](rdoc-ref:GraphQL::Schema::Member::HasArguments#argument) for argument configuration.
         def default_argument(*argument_args, **argument_kwargs)
           configs = @own_default_argument_configurations ||= []
           configs << [argument_args, argument_kwargs]
@@ -54,8 +72,16 @@ module GraphQL
         # but removed by from `arguments` before the field's `resolve` is called.
         # (The extras _will_ be present for other extensions, though.)
         #
-        # @param new_extras [Array<Symbol>] If provided, assign extras used by this extension
-        # @return [Array<Symbol>] any extras assigned to this extension
+        # **Parameters**
+        #
+        # - `new_extras` (`Array<Symbol>`) — If provided, assign extras used by this extension
+        #
+        # **Returns**
+        #
+        # - `Array<Symbol>` — any extras assigned to this extension
+        #
+        # :call-seq:
+        #   extras(Array[Symbol] new_extras) -> Array[Symbol]
         def extras(new_extras = nil)
           if new_extras
             @own_extras = new_extras
@@ -78,18 +104,29 @@ module GraphQL
 
       # Called when this extension is attached to a field.
       # The field definition may be extended during this method.
-      # @return [void]
+      #
+      # **Returns**
+      #
+      # - `void`
+      #
+      # :call-seq:
+      #   apply() -> void
       def apply
       end
 
       # Called after the field's definition block has been executed.
       # (Any arguments from the block are present on `field`)
-      # @return [void]
+      #
+      # **Returns**
+      #
+      # - `void`
+      #
+      # :call-seq:
+      #   after_define() -> void
       def after_define
       end
 
-      # @api private
-      def after_define_apply
+      def after_define_apply # :nodoc:
         after_define
         if (configs = self.class.default_argument_configurations)
           existing_keywords = field.all_argument_definitions.map(&:keyword)
@@ -113,41 +150,59 @@ module GraphQL
         freeze
       end
 
-      # @api private
-      attr_reader :added_extras
+      attr_reader :added_extras # :nodoc:
 
-      # Called before resolving {#field}. It should either:
+      # Called before resolving [field](rdoc-ref:#field). It should either:
       #
       # - `yield` values to continue execution; OR
       # - return something else to shortcut field execution.
       #
       # Whatever this method returns will be used for execution.
       #
-      # @param object [Object] The object the field is being resolved on (not passed by new execution)
-      # @param objects [Array<Object>] The objects the field is being resolved on (passed by new execution)
-      # @param arguments [Hash] Ruby keyword arguments for resolving this field
-      # @param context [Query::Context] the context for this query
-      # @yieldparam object_or_objects [Object, Array<Object>] The object or objects (new execution) to continue resolving the field on
-      # @yieldparam arguments [Hash] The keyword arguments to continue resolving with
-      # @yieldparam memo [Object] Any extension-specific value which will be passed to {#after_resolve} later
-      # @return [Object] The return value for this field.
+      # **Parameters**
+      #
+      # - `object` (`Object`) — The object the field is being resolved on (not passed by new execution)
+      # - `objects` (`Array<Object>`) — The objects the field is being resolved on (passed by new execution)
+      # - `arguments` (`Hash`) — Ruby keyword arguments for resolving this field
+      # - `context` (`Query::Context`) — the context for this query
+      #
+      # **Yields**
+      #
+      # - `object_or_objects` (`Object, Array<Object>`) — The object or objects (new execution) to continue resolving the field on
+      # - `arguments` (`Hash`) — The keyword arguments to continue resolving with
+      # - `memo` (`Object`) — Any extension-specific value which will be passed to [after resolve](rdoc-ref:#after_resolve) later
+      #
+      # **Returns**
+      #
+      # - `Object` — The return value for this field.
+      #
+      # :call-seq:
+      #   resolve(Object object:, Array[Object] objects:, Hash arguments:, Query::Context context:) -> Object
       def resolve(object: nil, objects: nil, arguments:, context:)
         yield(object.nil? ? objects : object, arguments, nil)
       end
 
-      # Called after {#field} was resolved, and after any lazy values (like `Promise`s) were synced,
+      # Called after [field](rdoc-ref:#field) was resolved, and after any lazy values (like `Promise`s) were synced,
       # but before the value was added to the GraphQL response.
       #
       # Whatever this hook returns will be used as the return value.
       #
-      # @param object [Object] The object the field is being resolved on (not passed by new execution)
-      # @param objects [Array<Object>] The object the field is being resolved on (passed by new execution)
-      # @param arguments [Hash] Ruby keyword arguments for resolving this field
-      # @param context [Query::Context] the context for this query
-      # @param value [Object] Whatever the field previously returned (not passed by new execution)
-      # @param values [Array<Object>] Whatever the field previously returned (passed by new execution)
-      # @param memo [Object] The third value yielded by {#resolve}, or `nil` if there wasn't one
-      # @return [Object] The return value for this field.
+      # **Parameters**
+      #
+      # - `object` (`Object`) — The object the field is being resolved on (not passed by new execution)
+      # - `objects` (`Array<Object>`) — The object the field is being resolved on (passed by new execution)
+      # - `arguments` (`Hash`) — Ruby keyword arguments for resolving this field
+      # - `context` (`Query::Context`) — the context for this query
+      # - `value` (`Object`) — Whatever the field previously returned (not passed by new execution)
+      # - `values` (`Array<Object>`) — Whatever the field previously returned (passed by new execution)
+      # - `memo` (`Object`) — The third value yielded by [resolve](rdoc-ref:#resolve), or `nil` if there wasn't one
+      #
+      # **Returns**
+      #
+      # - `Object` — The return value for this field.
+      #
+      # :call-seq:
+      #   after_resolve(Object object:, Array[Object] objects:, Hash arguments:, Query::Context context:, Array[Object] values:, Object value:, Object memo:) -> Object
       def after_resolve(object: nil, objects: nil, arguments:, context:, values: nil, value: nil, memo:)
         value.nil? ? values : value
       end

data/lib/graphql/schema/find_inherited_value.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
+    #--
+    # @requires_ancestor: Module
     module FindInheritedValue
       def self.extended(child_cls)
         child_cls.singleton_class.include(GraphQL::EmptyObjects)
@@ -16,9 +19,8 @@ module GraphQL
         if self.is_a?(Class)
           superclass.respond_to?(method_name, true) ? superclass.send(method_name) : default_value
         else
-          ancestors_except_self = ancestors
-          ancestors_except_self.delete(self)
-          ancestors_except_self.each do |ancestor|
+          ancestors.each do |ancestor|
+            next if ancestor.equal?(self)
             if ancestor.respond_to?(method_name, true)
               return ancestor.send(method_name)
             end

data/lib/graphql/schema/finder.rb

@@ -1,21 +1,35 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
     # Find schema members using string paths
     #
-    # @example Finding object types
-    #   MySchema.find("SomeObjectType")
+    # **Examples**
     #
-    # @example Finding fields
-    #   MySchema.find("SomeObjectType.myField")
+    # **Example: Finding object types**
     #
-    # @example Finding arguments
-    #   MySchema.find("SomeObjectType.myField.anArgument")
+    # ```ruby
+    # MySchema.find("SomeObjectType")
+    # ```
     #
-    # @example Finding directives
-    #   MySchema.find("@include")
+    # **Example: Finding fields**
     #
+    # ```ruby
+    # MySchema.find("SomeObjectType.myField")
+    # ```
+    #
+    # **Example: Finding arguments**
+    #
+    # ```ruby
+    # MySchema.find("SomeObjectType.myField.anArgument")
+    # ```
+    #
+    # **Example: Finding directives**
+    #
+    # ```ruby
+    # MySchema.find("@include")
+    # ```
     class Finder
       class MemberNotFoundError < ArgumentError; end
 

data/lib/graphql/schema/has_single_input_argument.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
+    #--
+    # @requires_ancestor: GraphQL::Schema::Resolver
     module HasSingleInputArgument
       def resolve_with_support(**inputs)
         input_kwargs = flatten_arguments(inputs)
@@ -31,7 +34,8 @@ module GraphQL
         end
 
         new_extras = field ? field.extras : []
-        all_extras = self.class.extras + new_extras
+        resolver_class = self.class #: as singleton(GraphQL::Schema::Resolver)
+        all_extras = resolver_class.extras + new_extras
 
         # Transfer these from the top-level hash to the
         # shortcutted `input:` object
@@ -54,6 +58,8 @@ module GraphQL
         input_kwargs
       end
 
+      #--
+      # @requires_ancestor: singleton(GraphQL::Schema::Resolver)
       module ClassMethods
         def dummy
           @dummy ||= begin
@@ -89,6 +95,7 @@ module GraphQL
         # Also apply this argument to the input type:
         def argument(*args, own_argument: false, **kwargs, &block)
           it = input_type # make sure any inherited arguments are already added to it
+          args = args #: untyped
           arg = super(*args, **kwargs, &block)
 
           # This definition might be overriding something inherited;
@@ -111,8 +118,17 @@ module GraphQL
         end
 
         # The base class for generated input object types
-        # @param new_class [Class] The base class to use for generating input object definitions
-        # @return [Class] The base class for this mutation's generated input object (default is {GraphQL::Schema::InputObject})
+        #
+        # **Parameters**
+        #
+        # - `new_class` (`Class`) — The base class to use for generating input object definitions
+        #
+        # **Returns**
+        #
+        # - `Class` — The base class for this mutation's generated input object (default is [GraphQL::Schema::InputObject](rdoc-ref:GraphQL::Schema::InputObject))
+        #
+        # :call-seq:
+        #   input_object_class(Class new_class) -> Class
         def input_object_class(new_class = nil)
           if new_class
             @input_object_class = new_class
@@ -120,8 +136,16 @@ module GraphQL
           @input_object_class || (superclass.respond_to?(:input_object_class) ? superclass.input_object_class : GraphQL::Schema::InputObject)
         end
 
-        # @param new_input_type [Class, nil] If provided, it configures this mutation to accept `new_input_type` instead of generating an input type
-        # @return [Class] The generated {Schema::InputObject} class for this mutation's `input`
+        # **Parameters**
+        #
+        # - `new_input_type` (`Class, nil`) — If provided, it configures this mutation to accept `new_input_type` instead of generating an input type
+        #
+        # **Returns**
+        #
+        # - `Class` — The generated [Schema::InputObject](rdoc-ref:Schema::InputObject) class for this mutation's `input`
+        #
+        # :call-seq:
+        #   input_type(Class | nil new_input_type) -> Class
         def input_type(new_input_type = nil)
           if new_input_type
             @input_type = new_input_type
@@ -133,17 +157,26 @@ module GraphQL
 
         # Generate the input type for the `input:` argument
         # To customize how input objects are generated, override this method
-        # @return [Class] a subclass of {.input_object_class}
+        #
+        # **Returns**
+        #
+        # - `Class` — a subclass of [.input_object_class](rdoc-ref:.input_object_class)
+        #
+        # :call-seq:
+        #   generate_input_type() -> Class
         def generate_input_type
           mutation_args = all_argument_definitions
           mutation_class = self
           Class.new(input_object_class) do
+            #: self as singleton(GraphQL::Schema::InputObject)
             class << self
               def default_graphql_name
+                #: self as singleton(GraphQL::Schema::InputObject)
                 "#{self.mutation.graphql_name}Input"
               end
 
               def description(new_desc = nil)
+                #: self as singleton(GraphQL::Schema::InputObject)
                 super || "Autogenerated input type of #{self.mutation.graphql_name}"
               end
             end

data/lib/graphql/schema/input_object.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class InputObject < GraphQL::Schema::Member
@@ -18,9 +19,13 @@ module GraphQL
         end
       end
 
-      # @return [GraphQL::Query::Context] The context for this query
+      # **Returns**
+      #
+      # - `GraphQL::Query::Context` — The context for this query
       attr_reader :context
-      # @return [GraphQL::Execution::Interpereter::Arguments] The underlying arguments instance
+      # **Returns**
+      #
+      # - `GraphQL::Execution::Interpereter::Arguments` — The underlying arguments instance
       attr_reader :arguments
 
       # Ruby-like hash behaviors, read-only
@@ -72,8 +77,8 @@ module GraphQL
         when Array
           value.map { |item| unwrap_value(item) }
         when Hash
-          value.reduce({}) do |h, (key, value)|
-            h.merge!(key => unwrap_value(value))
+          value.reduce({}) do |h, (key, nested_value)|
+            h.merge!(key => unwrap_value(nested_value))
           end
         when InputObject
           value.to_h
@@ -84,7 +89,13 @@ module GraphQL
 
       # Lookup a key on this object, it accepts new-style underscored symbols
       # Or old-style camelized identifiers.
-      # @param key [Symbol, String]
+      #
+      # **Parameters**
+      #
+      # - `key` (`Symbol, String`)
+      #
+      # :call-seq:
+      #   [](Symbol | String key)
       def [](key)
         if @ruby_style_hash.key?(key)
           @ruby_style_hash[key]
@@ -104,8 +115,7 @@ module GraphQL
         @ruby_style_hash.dup
       end
 
-      # @api private
-      def validate_for(context)
+      def validate_for(context) # :nodoc:
         object = context[:current_object]
         # Pass this object's class with `as` so that messages are rendered correctly from inherited validators
         Schema::Validator.validate!(self.class.validators, object, context, @ruby_style_hash, as: self.class)
@@ -145,6 +155,7 @@ module GraphQL
         end
 
         def argument(*args, **kwargs, &block)
+          args = args #: untyped
           argument_defn = super(*args, **kwargs, &block)
           if one_of?
             if argument_defn.type.non_null?
@@ -165,7 +176,7 @@ module GraphQL
           GraphQL::TypeKinds::INPUT_OBJECT
         end
 
-        # @api private
+        # :nodoc:
         INVALID_OBJECT_MESSAGE = "Expected %{object} to be a key-value object."
 
         def validate_non_null_input(input, ctx, max_errors: nil)
@@ -181,7 +192,7 @@ module GraphQL
           end
 
 
-          result = nil
+          result = nil #: GraphQL::Query::InputValidationResult?
 
 
           input.each do |argument_name, value|
@@ -270,14 +281,27 @@ module GraphQL
           result
         end
 
-        # @param new_has_no_arguments [Boolean] Call with `true` to make this InputObject type ignore the requirement to have any defined arguments.
-        # @return [void]
+        # **Parameters**
+        #
+        # - `new_has_no_arguments` (`Boolean`) — Call with `true` to make this InputObject type ignore the requirement to have any defined arguments.
+        #
+        # **Returns**
+        #
+        # - `void`
+        #
+        # :call-seq:
+        #   has_no_arguments(bool new_has_no_arguments) -> void
         def has_no_arguments(new_has_no_arguments)
           @has_no_arguments = new_has_no_arguments
           nil
         end
 
-        # @return [Boolean] `true` if `has_no_arguments(true)` was configued
+        # **Returns**
+        #
+        # - `Boolean` — `true` if `has_no_arguments(true)` was configued
+        #
+        # :call-seq:
+        #   has_no_arguments?() -> bool
         def has_no_arguments?
           @has_no_arguments
         end
@@ -301,7 +325,10 @@ module GraphQL
         end
 
         def define_accessor_method(method_name)
-          define_method(method_name) { self[method_name] }
+          define_method(method_name) {
+            #: self as GraphQL::Schema::InputObject
+            self[method_name]
+          }
           alias_method(method_name, method_name)
         end
       end

data/lib/graphql/schema/interface.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     module Interface
@@ -28,32 +29,36 @@ module GraphQL
             defn_methods_module = Module.new
             @_definition_methods = defn_methods_module
             const_set(:DefinitionMethods, defn_methods_module)
-            extend(self::DefinitionMethods)
+            extend(defn_methods_module)
           end
-          self::DefinitionMethods.module_exec(&block)
+          const_get(:DefinitionMethods).module_exec(&block)
         end
 
         # Instance methods defined in this block will become class methods on objects that implement this interface.
         # Use it to implement `resolve_each:`, `resolve_batch:`, and `resolve_static:` fields.
-        # @example
-        #   field :thing, String, resolve_static: true
         #
-        #   resolver_methods do
-        #     def thing
-        #       Somehow.get.thing
-        #     end
+        # **Examples**
+        #
+        # **Example: field :thing, String, resolve_static: true**
+        #
+        # ```ruby
+        # resolver_methods do
+        #   def thing
+        #     Somehow.get.thing
         #   end
+        # end
+        # ```
         def resolver_methods(&block)
           if !defined?(@_resolver_methods)
             resolver_methods_module = Module.new
             @_resolver_methods = resolver_methods_module
             const_set(:ResolverMethods, resolver_methods_module)
-            extend(self::ResolverMethods)
+            extend(resolver_methods_module)
           end
-          self::ResolverMethods.module_exec(&block)
+          const_get(:ResolverMethods).module_exec(&block)
         end
 
-        # @see {Schema::Warden} hides interfaces without visible implementations
+        # See [Schema::Warden](rdoc-ref:Schema::Warden) hides interfaces without visible implementations
         def visible?(context)
           true
         end
@@ -78,7 +83,7 @@ module GraphQL
             child_class.type_membership_class(self.type_membership_class)
             child_class.ancestors.reverse_each do |ancestor|
               if ancestor.const_defined?(:DefinitionMethods) && ancestor != child_class
-                child_class.extend(ancestor::DefinitionMethods)
+                child_class.extend(ancestor.const_get(:DefinitionMethods))
               end
             end
 
@@ -91,9 +96,11 @@ module GraphQL
             end
           elsif child_class < GraphQL::Schema::Object
             # This is being included into an object type, make sure it's using `implements(...)`
-            backtrace_line = caller_locations(0, 10).find do |location|
+            locations = caller_locations(0, 10) #: as !nil
+            backtrace_line = locations.find do |location|
+              location_path = location.path #: as !nil
               location.base_label == "implements" &&
-                location.path.end_with?("schema/member/has_interfaces.rb")
+                location_path.end_with?("schema/member/has_interfaces.rb")
             end
 
             if !backtrace_line
@@ -102,7 +109,7 @@ module GraphQL
 
             child_class.ancestors.reverse_each do |ancestor|
               if ancestor != child_class && ancestor <= GraphQL::Schema::Interface && ancestor.const_defined?(:ResolverMethods, false)
-                child_class.extend(ancestor::ResolverMethods)
+                child_class.extend(ancestor.const_get(:ResolverMethods))
               end
             end
           end
@@ -114,8 +121,17 @@ module GraphQL
         #
         # When those Interfaces or Objects aren't used as the return values of fields,
         # they may have to be registered using this method so that GraphQL-Ruby can find them.
-        # @param types [Class, Module]
-        # @return [Array<Module, Class>] Implementers of this interface, if they're registered
+        #
+        # **Parameters**
+        #
+        # - `types` (`Class, Module`)
+        #
+        # **Returns**
+        #
+        # - `Array<Module, Class>` — Implementers of this interface, if they're registered
+        #
+        # :call-seq:
+        #   orphan_types(Class | Module *types) -> Array[Module | Class]
         def orphan_types(*types)
           if !types.empty?
             @orphan_types ||= []

data/lib/graphql/schema/introspection_system.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     class IntrospectionSystem
@@ -64,9 +65,11 @@ module GraphQL
       # Replace those with the objects that they refer to, since LateBoundTypes
       # aren't handled at runtime.
       #
-      # @api private
-      # @return void
-      def resolve_late_bindings
+      #
+      # **Returns**
+      #
+      # - `Object` — void
+      def resolve_late_bindings # :nodoc:
         @types.each do |name, t|
           if t.kind.fields?
             t.all_field_definitions.each do |field_defn|
@@ -123,6 +126,7 @@ module GraphQL
       def dup_type_class(type_class)
         type_name = type_class.graphql_name
         Class.new(type_class) do
+          #: self as untyped
           # This won't be inherited like other things will
           graphql_name(type_name)
 

data/lib/graphql/schema/late_bound_type.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     # A stand-in for a type which will be resolved in a given schema, by name.
     # TODO: support argument types too, make this a public API somehow
-    # @api Private
-    class LateBoundType
+    class LateBoundType # :nodoc:
       attr_reader :name
       alias :graphql_name :name
       def initialize(local_name)

data/lib/graphql/schema/list.rb

@@ -1,19 +1,30 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
     # Represents a list type in the schema.
-    # Wraps a {Schema::Member} as a list type.
-    # @see Schema::Member::TypeSystemHelpers#to_list_type Create a list type from another GraphQL type
+    # Wraps a [Schema::Member](rdoc-ref:Schema::Member) as a list type.
+    # See [Schema::Member::TypeSystemHelpers#to_list_type](rdoc-ref:Schema::Member::TypeSystemHelpers#to_list_type) Create a list type from another GraphQL type
     class List < GraphQL::Schema::Wrapper
       include Schema::Member::ValidatesInput
 
-      # @return [GraphQL::TypeKinds::LIST]
+      # **Returns**
+      #
+      # - `GraphQL::TypeKinds::LIST`
+      #
+      # :call-seq:
+      #   kind() -> GraphQL::TypeKinds::LIST
       def kind
         GraphQL::TypeKinds::LIST
       end
 
-      # @return [true]
+      # **Returns**
+      #
+      # - `true`
+      #
+      # :call-seq:
+      #   list?() -> true
       def list?
         true
       end