graphql 2.6.9 → 2.6.14

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

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

data/lib/graphql/schema/member.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require 'graphql/schema/member/base_dsl_methods'
 require 'graphql/schema/member/graphql_type_names'
 require 'graphql/schema/member/has_ast_node'
@@ -20,8 +21,14 @@ module GraphQL
     # The base class for things that make up the schema,
     # eg objects, enums, scalars.
     #
-    # @api private
-    class Member
+    class Member # :nodoc:
+      # A module that defines a GraphQL interface type (it includes `GraphQL::Schema::Interface`).
+      #: type interface_definition = GraphQL::Schema::Interface::DefinitionMethods & Module
+
+      # A class or module that defines a GraphQL type:
+      # an object, union, enum, scalar or input object class, or an interface module.
+      #: type type_definition = singleton(GraphQL::Schema::Member) | interface_definition
+
       include GraphQLTypeNames
       extend BaseDSLMethods
       extend BaseDSLMethods::ConfigurationExtension

data/lib/graphql/schema/mutation.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
@@ -8,62 +9,65 @@ module GraphQL
     # If you want to customize how this class generates types, in your base class,
     # override the various `generate_*` methods.
     #
-    # @see {GraphQL::Schema::RelayClassicMutation} for an extension of this class with some conventions built-in.
+    # See [GraphQL::Schema::RelayClassicMutation](rdoc-ref:GraphQL::Schema::RelayClassicMutation) for an extension of this class with some conventions built-in.
     #
-    # @example Creating a comment
-    #  # Define the mutation:
-    #  class Mutations::CreateComment < GraphQL::Schema::Mutation
-    #    argument :body, String, required: true
-    #    argument :post_id, ID, required: true
+    # **Examples**
     #
-    #    field :comment, Types::Comment, null: true
-    #    field :errors, [String], null: false
+    # **Example: Creating a comment**
     #
-    #    def resolve(body:, post_id:)
-    #      post = Post.find(post_id)
-    #      comment = post.comments.build(body: body, author: context[:current_user])
-    #      if comment.save
-    #        # Successful creation, return the created object with no errors
-    #        {
-    #          comment: comment,
-    #          errors: [],
-    #        }
-    #      else
-    #        # Failed save, return the errors to the client
-    #        {
-    #          comment: nil,
-    #          errors: comment.errors.full_messages
-    #        }
-    #      end
-    #    end
-    #  end
+    # ```ruby
+    # # Define the mutation:
+    # class Mutations::CreateComment < GraphQL::Schema::Mutation
+    #   argument :body, String, required: true
+    #   argument :post_id, ID, required: true
     #
-    #  # Hook it up to your mutation:
-    #  class Types::Mutation < GraphQL::Schema::Object
-    #    field :create_comment, mutation: Mutations::CreateComment
-    #  end
+    #   field :comment, Types::Comment, null: true
+    #   field :errors, [String], null: false
     #
-    #  # Call it from GraphQL:
-    #  result = MySchema.execute <<-GRAPHQL
-    #  mutation {
-    #    createComment(postId: "1", body: "Nice Post!") {
-    #      errors
-    #      comment {
-    #        body
-    #        author {
-    #          login
-    #        }
-    #      }
-    #    }
-    #  }
-    #  GRAPHQL
+    #   def resolve(body:, post_id:)
+    #     post = Post.find(post_id)
+    #     comment = post.comments.build(body: body, author: context[:current_user])
+    #     if comment.save
+    #       # Successful creation, return the created object with no errors
+    #       {
+    #         comment: comment,
+    #         errors: [],
+    #       }
+    #     else
+    #       # Failed save, return the errors to the client
+    #       {
+    #         comment: nil,
+    #         errors: comment.errors.full_messages
+    #       }
+    #     end
+    #   end
+    # end
     #
+    # # Hook it up to your mutation:
+    # class Types::Mutation < GraphQL::Schema::Object
+    #   field :create_comment, mutation: Mutations::CreateComment
+    # end
+    #
+    # # Call it from GraphQL:
+    # result = MySchema.execute <<-GRAPHQL
+    # mutation {
+    #   createComment(postId: "1", body: "Nice Post!") {
+    #     errors
+    #     comment {
+    #       body
+    #       author {
+    #         login
+    #       }
+    #     }
+    #   }
+    # }
+    # GRAPHQL
+    # ```
     class Mutation < GraphQL::Schema::Resolver
       extend GraphQL::Schema::Member::HasFields
       extend GraphQL::Schema::Resolver::HasPayloadType
 
-      # @api private
-      def call_resolve(_args_hash)
+      def call_resolve(_args_hash) # :nodoc:
         # Clear any cached values from `loads` or authorization:
         dataloader.clear_cache
         super

data/lib/graphql/schema/non_null.rb

@@ -1,24 +1,40 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
     # Represents a non null type in the schema.
-    # Wraps a {Schema::Member} when it is required.
-    # @see {Schema::Member::TypeSystemHelpers#to_non_null_type}
+    # Wraps a [Schema::Member](rdoc-ref:Schema::Member) when it is required.
+    # See [Schema::Member::TypeSystemHelpers#to_non_null_type](rdoc-ref:Schema::Member::TypeSystemHelpers#to_non_null_type)
     class NonNull < GraphQL::Schema::Wrapper
       include Schema::Member::ValidatesInput
 
-      # @return [GraphQL::TypeKinds::NON_NULL]
+      # **Returns**
+      #
+      # - `GraphQL::TypeKinds::NON_NULL`
+      #
+      # :call-seq:
+      #   kind() -> GraphQL::TypeKinds::NON_NULL
       def kind
         GraphQL::TypeKinds::NON_NULL
       end
 
-      # @return [true]
+      # **Returns**
+      #
+      # - `true`
+      #
+      # :call-seq:
+      #   non_null?() -> true
       def non_null?
         true
       end
 
-      # @return [Boolean] True if this type wraps a list type
+      # **Returns**
+      #
+      # - `Boolean` — True if this type wraps a list type
+      #
+      # :call-seq:
+      #   list?() -> bool
       def list?
         @of_type.list?
       end

data/lib/graphql/schema/object.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require "graphql/query/null_context"
 
@@ -18,13 +19,22 @@ module GraphQL
         end
       end
 
-      # @return [Object] the application object this type is wrapping
+      # **Returns**
+      #
+      # - `Object` — the application object this type is wrapping
       attr_reader :object
 
-      # @return [GraphQL::Query::Context] the context instance for this query
+      # **Returns**
+      #
+      # - `GraphQL::Query::Context` — the context instance for this query
       attr_reader :context
 
-      # @return [GraphQL::Dataloader]
+      # **Returns**
+      #
+      # - `GraphQL::Dataloader`
+      #
+      # :call-seq:
+      #   dataloader() -> GraphQL::Dataloader
       def dataloader
         context.dataloader
       end
@@ -36,8 +46,8 @@ module GraphQL
       end
 
       class << self
-        # This is protected so that we can be sure callers use the public method, {.authorized_new}
-        # @see authorized_new to make instances
+        # This is protected so that we can be sure callers use the public method, [.authorized_new](rdoc-ref:.authorized_new)
+        # See [authorized_new](rdoc-ref:authorized_new) to make instances
         protected :new
 
         def wrap_scoped(object, context)
@@ -54,26 +64,40 @@ module GraphQL
         #
         # Probably only the framework should call this method.
         #
-        # This might return a {GraphQL::Execution::Lazy} if the user-provided `.authorized?`
+        # This might return a [GraphQL::Execution::Lazy](rdoc-ref:GraphQL::Execution::Lazy) if the user-provided `.authorized?`
         # hook returns some lazy value (like a Promise).
         #
-        # The reason that the auth check is in this wrapper method instead of {.new} is because
+        # The reason that the auth check is in this wrapper method instead of [.new](rdoc-ref:.new) is because
         # of how it might return a Promise. It would be weird if `.new` returned a promise;
-        # It would be a headache to try to maintain Promise-y state inside a {Schema::Object}
+        # It would be a headache to try to maintain Promise-y state inside a [Schema::Object](rdoc-ref:Schema::Object)
         # instance. So, hopefully this wrapper method will do the job.
         #
-        # @param object [Object] The thing wrapped by this object
-        # @param context [GraphQL::Query::Context]
-        # @return [GraphQL::Schema::Object, GraphQL::Execution::Lazy]
-        # @raise [GraphQL::UnauthorizedError] if the user-provided hook returns `false`
+        # **Parameters**
+        #
+        # - `object` (`Object`) — The thing wrapped by this object
+        # - `context` (`GraphQL::Query::Context`)
+        #
+        # **Returns**
+        #
+        # - `GraphQL::Schema::Object, GraphQL::Execution::Lazy`
+        #
+        # **Raises**
+        #
+        # - `GraphQL::UnauthorizedError` — if the user-provided hook returns `false`
+        #
+        # :call-seq:
+        #   authorized_new(Object object, GraphQL::Query::Context context) -> GraphQL::Schema::Object | GraphQL::Execution::Lazy | GraphQL::UnauthorizedError
         def authorized_new(object, context)
           context.query.current_trace.begin_authorized(self, object, context)
+          raised_auth_err = nil
           begin
             maybe_lazy_auth_val = context.query.current_trace.authorized(query: context.query, type: self, object: object) do
               begin
                 authorized?(object, context)
               rescue GraphQL::UnauthorizedError => err
-                context.schema.unauthorized_object(err)
+                # Raising is equivalent to returning `false`; `unauthorized_object` is called below
+                raised_auth_err = err
+                false
               rescue StandardError => err
                 context.query.handle_or_reraise(err)
               end
@@ -86,7 +110,12 @@ module GraphQL
             GraphQL::Execution::Lazy.new do
               context.query.current_trace.begin_authorized(self, object, context)
               context.query.current_trace.authorized_lazy(query: context.query, type: self, object: object) do
-                res = context.schema.sync_lazy(maybe_lazy_auth_val)
+                res = begin
+                  context.schema.sync_lazy(maybe_lazy_auth_val)
+                rescue GraphQL::UnauthorizedError => err
+                  raised_auth_err = err
+                  false
+                end
                 context.query.current_trace.end_authorized(self, object, context, res)
                 res
               end
@@ -100,7 +129,7 @@ module GraphQL
               self.new(object, context)
             else
               # It failed the authorization check, so go to the schema's authorized object hook
-              err = GraphQL::UnauthorizedError.new(object: object, type: self, context: context)
+              err = raised_auth_err || GraphQL::UnauthorizedError.new(object: object, type: self, context: context)
               # If a new value was returned, wrap that instead of the original value
               begin
                 new_obj = context.schema.unauthorized_object(err)

data/lib/graphql/schema/printer.rb

@@ -1,42 +1,58 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
-    # Used to convert your {GraphQL::Schema} to a GraphQL schema string
+    # Used to convert your [GraphQL::Schema](rdoc-ref:GraphQL::Schema) to a GraphQL schema string
     #
-    # @example print your schema to standard output (via helper)
-    #   puts GraphQL::Schema::Printer.print_schema(MySchema)
+    # **Examples**
     #
-    # @example print your schema to standard output
-    #   puts GraphQL::Schema::Printer.new(MySchema).print_schema
+    # **Example: print your schema to standard output (via helper)**
     #
-    # @example print a single type to standard output
-    #   class Types::Query < GraphQL::Schema::Object
-    #     description "The query root of this schema"
+    # ```ruby
+    # puts GraphQL::Schema::Printer.print_schema(MySchema)
+    # ```
     #
-    #     field :post, Types::Post, null: true
-    #   end
+    # **Example: print your schema to standard output**
     #
-    #   class Types::Post < GraphQL::Schema::Object
-    #     description "A blog post"
+    # ```ruby
+    # puts GraphQL::Schema::Printer.new(MySchema).print_schema
+    # ```
     #
-    #     field :id, ID, null: false
-    #     field :title, String, null: false
-    #     field :body, String, null: false
-    #   end
+    # **Example: print a single type to standard output**
     #
-    #   class MySchema < GraphQL::Schema
-    #     query(Types::Query)
-    #   end
+    # ```ruby
+    # class Types::Query < GraphQL::Schema::Object
+    #   description "The query root of this schema"
     #
-    #   printer = GraphQL::Schema::Printer.new(MySchema)
-    #   puts printer.print_type(Types::Post)
+    #   field :post, Types::Post, null: true
+    # end
     #
+    # class Types::Post < GraphQL::Schema::Object
+    #   description "A blog post"
+    #
+    #   field :id, ID, null: false
+    #   field :title, String, null: false
+    #   field :body, String, null: false
+    # end
+    #
+    # class MySchema < GraphQL::Schema
+    #   query(Types::Query)
+    # end
+    #
+    # printer = GraphQL::Schema::Printer.new(MySchema)
+    # puts printer.print_type(Types::Post)
+    # ```
     class Printer < GraphQL::Language::Printer
       attr_reader :schema, :warden
 
-      # @param schema [GraphQL::Schema]
-      # @param context [Hash]
-      # @param introspection [Boolean] Should include the introspection types in the string?
+      # **Parameters**
+      #
+      # - `schema` (`GraphQL::Schema`)
+      # - `context` (`Hash`)
+      # - `introspection` (`Boolean`) — Should include the introspection types in the string?
+      #
+      # :call-seq:
+      #   initialize(GraphQL::Schema schema, Hash context:, bool introspection:)
       def initialize(schema, context: nil, introspection: false)
         @document_from_schema = GraphQL::Language::DocumentFromSchemaDefinition.new(
           schema,
@@ -53,9 +69,8 @@ module GraphQL
         query_root = Class.new(GraphQL::Schema::Object) do
           graphql_name "Root"
           field :throwaway_field, String
-          def self.visible?(ctx)
-            false
-          end
+          # Not `def self.visible?`: Sorbet would treat it as a definition of `Printer.visible?`
+          define_singleton_method(:visible?) { |ctx| false }
         end
         schema = Class.new(GraphQL::Schema) {
           query(query_root)
@@ -75,10 +90,16 @@ module GraphQL
       end
 
       # Return a GraphQL schema string for the defined types in the schema
-      # @param schema [GraphQL::Schema]
-      # @param context [Hash]
-      # @param only [<#call(member, ctx)>]
-      # @param except [<#call(member, ctx)>]
+      #
+      # **Parameters**
+      #
+      # - `schema` (`GraphQL::Schema`)
+      # - `context` (`Hash`)
+      # - `only` (`<#call(member, ctx)>`)
+      # - `except` (`<#call(member, ctx)>`)
+      #
+      # :call-seq:
+      #   print_schema(GraphQL::Schema schema, **args)
       def self.print_schema(schema, **args)
         printer = new(schema, **args)
         printer.print_schema

data/lib/graphql/schema/ractor_shareable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Schema
     module RactorShareable
@@ -7,6 +8,8 @@ module GraphQL
         schema_class.freeze_schema
       end
 
+      #--
+      # @requires_ancestor: singleton(GraphQL::Schema)
       module SchemaExtension
 
         def freeze_error_handlers(handlers)
@@ -25,7 +28,7 @@ module GraphQL
           default_logger
           freeze_error_handlers(error_handlers)
           # TODO: this freezes errors of parent classes which could cause trouble
-          parent_class = superclass
+          parent_class = superclass #: untyped
           while parent_class.respond_to?(:error_handlers)
             freeze_error_handlers(parent_class.error_handlers)
             parent_class = parent_class.superclass
@@ -58,7 +61,8 @@ module GraphQL
           extend(FrozenMethods)
 
           Ractor.make_shareable(self)
-          superclass.respond_to?(:freeze_schema) && superclass.freeze_schema
+          parent_class = superclass #: untyped
+          parent_class.respond_to?(:freeze_schema) && parent_class.freeze_schema
         end
 
         module FrozenMethods

data/lib/graphql/schema/relay_classic_mutation.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
@@ -17,8 +18,7 @@ module GraphQL
     # - using a single `input:` argument makes it easy to post whole JSON objects to the mutation
     #   using one GraphQL variable (`$input`) instead of making a separate variable for each argument.
     #
-    # @see {GraphQL::Schema::Mutation} for an example, it's basically the same.
-    #
+    # See [GraphQL::Schema::Mutation](rdoc-ref:GraphQL::Schema::Mutation) for an example, it's basically the same.
     class RelayClassicMutation < GraphQL::Schema::Mutation
       include GraphQL::Schema::HasSingleInputArgument
 
@@ -29,7 +29,7 @@ module GraphQL
       # Relay classic default:
       null(true)
 
-      # Override {GraphQL::Schema::Resolver#resolve_with_support} to
+    # Override [resolve_with_support](rdoc-ref:#resolve_with_support) to
       # delete `client_mutation_id` from the kwargs.
       def resolve_with_support(**inputs)
         input = inputs[:input].to_kwargs

data/lib/graphql/schema/resolver/has_payload_type.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
@@ -7,12 +8,24 @@ module GraphQL
       # generate payload types.
       #
       # Or, an already-defined one can be attached with `payload_type(...)`.
+      #--
+      # @requires_ancestor: singleton(GraphQL::Schema::Resolver)
+      # @requires_ancestor: GraphQL::Schema::Member::HasFields
       module HasPayloadType
         # Call this method to get the derived return type of the mutation,
         # or use it as a configuration method to assign a return type
         # instead of generating one.
-        # @param new_payload_type [Class, nil] If a type definition class is provided, it will be used as the return type of the mutation field
-        # @return [Class] The object type which this mutation returns.
+        #
+        # **Parameters**
+        #
+        # - `new_payload_type` (`Class, nil`) — If a type definition class is provided, it will be used as the return type of the mutation field
+        #
+        # **Returns**
+        #
+        # - `Class` — The object type which this mutation returns.
+        #
+        # :call-seq:
+        #   payload_type(Class | nil new_payload_type) -> Class
         def payload_type(new_payload_type = nil)
           if new_payload_type
             @payload_type = new_payload_type
@@ -44,8 +57,17 @@ module GraphQL
         end
 
         # An object class to use for deriving return types
-        # @param new_class [Class, nil] Defaults to {GraphQL::Schema::Object}
-        # @return [Class]
+        #
+        # **Parameters**
+        #
+        # - `new_class` (`Class, nil`) — Defaults to [GraphQL::Schema::Object](rdoc-ref:GraphQL::Schema::Object)
+        #
+        # **Returns**
+        #
+        # - `Class`
+        #
+        # :call-seq:
+        #   object_class(Class | nil new_class) -> Class
         def object_class(new_class = nil)
           if new_class
             if defined?(@payload_type)
@@ -83,13 +105,13 @@ module GraphQL
 
         private
 
-        # Build a subclass of {.object_class} based on `self`.
-        # This value will be cached as `{.payload_type}`.
+        # Build a subclass of [.object_class](rdoc-ref:.object_class) based on `self`.
+        # This value will be cached as [.payload_type](rdoc-ref:.payload_type).
         # Override this hook to customize return type generation.
         def generate_payload_type
           resolver_name = graphql_name
           resolver_fields = all_field_definitions
-          pt = Class.new(object_class)
+          pt = Class.new(object_class) #: as singleton(GraphQL::Schema::Object)
           pt.graphql_name("#{resolver_name}Payload")
           pt.description("Autogenerated return type of #{resolver_name}.")
           resolver_fields.each do |f|